python-mcp-handson

Overview

python-mcp-handson is a hands-on project demonstrating the Model Context Protocol (MCP) server using Python. It provides practical tools for AI agents, including a Retrieval-Augmented Generation (RAG) system that combines Weaviate vector database with OpenAI API.

Provided Tools

1. greet - A simple greeting tool

   • Returns a personalized greeting message

2. search_docs - Semantic search over indexed documents

   • Searches the docs/ directory using natural language queries
   • Returns relevant document chunks with similarity scores

3. list_indexed_sources - List all indexed documents

   • Returns file information for indexed documents

Usage

Dependencies

• Docker and Docker Compose
• OpenAI API key (for embeddings)

Setup & Run

1. Set up environment variables:

   export OPENAI_API_KEY="your-api-key"

2. Index documents (first time):

   docker compose --profile index run --rm indexer

   Place your documents in the docs/ directory before running this.

3. Start the MCP server:

   docker compose up

4. Use the tools:

   • Call the search_docs tool with a natural language query to find relevant documents
   • Use greet to test basic functionality
   • Query list_indexed_sources to see which documents are indexed

License

MIT