sample-mcp-server
MCP Server Example
AI assistant application that integrates FastMCP server, MongoDB Atlas knowledge base, and LLM endpoint with direct MCP tool calling capabilities.
🎯 Key Update: Direct MCP Integration Implemented
This version implements the exact requested flow:
User Query → LLM Service → MCP Tools → MongoDB Atlas → LLM Service → User Response
Flow Implementation
- User sends chat message → FastAPI
/chat endpoint - LLM generates JSON function call → Compatible with Llama3-8B-Instruct
- LLM service calls MCP tools directly →
await mcp._mcp_call_tool(function_name, parameters) - MCP tools query MongoDB Atlas → Native FastMCP integration
- Documents returned through MCP → Proper MCP protocol response
- LLM processes results → Generates final response with context
- User receives response → Complete chat completion with document context
🚀 Quick Start
1. Setup project
task setup
Edit .env file with your actual credentials
nano .env # or your preferred editor
3. Start the server
task dev
Features
- FastMCP Server: Provides MCP tools for document search and retrieval
- REST API: Complete API with /chat and /ingest_github endpoints
- MongoDB Atlas Integration: Document storage and search capabilities
- LLM Integration: LLM endpoint
- GitHub Integration: Repository document ingestion
- Swagger/ReDoc Documentation: Auto-generated API documentation
- Production-Grade: Comprehensive error handling, logging, and async architecture
API Endpoints
GET /healthz - Health check endpointPOST /chat - Chat completion with MCP tool callingPOST /ingest_github - Ingest GitHub repository documentsPOST /search - Search documents in knowledge baseGET /documents/count - Get total document countGET /mcp/info - Get MCP server informationGET /docs - Swagger UI documentationGET /redoc - ReDoc documentation
search_documents - Search documents by text queryget_all_documents - Get all documents with limitget_document_count - Get total document countsearch_documents_by_metadata - Search by metadata filters
Prerequisites
- Python 3.12+
- Poetry (for dependency management)
- MongoDB Atlas account and cluster
- GitHub token (for repository ingestion)
- Access to LLM endpoint
📋 Prerequisites
- Python 3.12+ (recommended to use pyenv)
- Poetry for dependency management
- Task (optional but recommended) for task automation
- MongoDB Atlas account and cluster
- GitHub token for repository ingestion
- Access to LLM endpoint
Access the Application
Once running, you can access:
- API Server: http://localhost:8000
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- Health Check: http://localhost:8000/healthz
Manual API Testing
1. Health Check
# Using Task
task test-health
# Manual curl
curl -X GET "http://localhost:8000/healthz" -H "accept: application/json" | jq
# Using Task
task test-mcp-info
# Manual curl
curl -X GET "http://localhost:8000/mcp/info" -H "accept: application/json" | jq
3. Document Count
# Using Task
task test-document-count
# Manual curl
curl -X GET "http://localhost:8000/documents/count" -H "accept: application/json" | jq
4. Document Search
# Using Task
task test-search
# Manual curl
curl -X POST "http://localhost:8000/search" \
-H "Content-Type: application/json" \
-H "accept: application/json" \
-d '{
"query": "Python programming",
"limit": 5
}' | jq
5. Chat Completion (requires valid LLM credentials)
# Using Task
task test-chat
# Manual curl
curl -X POST "http://localhost:8000/chat" \
-H "Content-Type: application/json" \
-H "accept: application/json" \
-d '{
"messages": [
{"role": "user", "content": "Hello, can you search for documents about Python programming?"}
]
}' | jq
6. GitHub Repository Ingestion (requires valid GitHub token)
# Using Task
task test-github-ingest
# Manual curl
curl -X POST "http://localhost:8000/ingest_github" \
-H "Content-Type: application/json" \
-H "accept: application/json" \
-d '{
"repository_url": "https://github.com/python/cpython",
"branch": "main",
"file_patterns": ["*.py", "*.md"],
"max_file_size": 1048576
}' | jq
Testing with Swagger UI
- Start the server:
task dev - Open http://localhost:8000/docs in your browser
- Use the interactive API documentation to test endpoints
- Click "Try it out" on any endpoint to test with custom parameters
Architecture
Services
- MongoDBService: Async MongoDB Atlas operations
- GitHubService: Repository cloning and document ingestion
- LLMService: LLM integration with tool calling
- MCP Server: FastMCP server with document tools
Models
- Document: Core document model with metadata
- ChatRequest/Response: Chat API models
- GitHubIngestRequest/Response: GitHub ingestion models
- DocumentSearchRequest/Response: Search API models
Configuration
- Pydantic Settings: Environment-based configuration
- Async Architecture: Full async/await support
- Error Handling: Comprehensive error management
- Logging: Structured logging throughout
📁 Project Structure
chatgtg-backend/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI application & endpoints
│ ├── config.py # Configuration management
│ ├── models.py # Pydantic models
│ ├── mcp_server.py # FastMCP server & tools
│ └── services/
│ ├── __init__.py
│ ├── mongodb_service.py # MongoDB Atlas operations
│ ├── github_service.py # GitHub integration
│ └── llm_service.py # LLM integration
├── pyproject.toml # Poetry dependencies
├── Taskfile.yml # Task automation
├── .env.template # Environment template
├── .env # Your actual environment (create from template)
└── README.md # This documentation
🛠️ Development
Available Tasks
# View all available tasks
task --list
# Development tasks
task setup # Setup project (install deps, create .env)
task dev # Start development server
task run # Start production server
### Adding New Features
1. **New API Endpoints**: Add to `app/main.py`
2. **New Services**: Create in `app/services/`
3. **New Models**: Add to `app/models.py`
4. **New MCP Tools**: Add to `app/mcp_server.py`
5. **New Tasks**: Add to `Taskfile.yml`