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

2. Configure environment (IMPORTANT!)

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 endpoint
POST /chat - Chat completion with MCP tool calling
POST /ingest_github - Ingest GitHub repository documents
POST /search - Search documents in knowledge base
GET /documents/count - Get total document count
GET /mcp/info - Get MCP server information
GET /docs - Swagger UI documentation
GET /redoc - ReDoc documentation

MCP Tools

search_documents - Search documents by text query
get_all_documents - Get all documents with limit
get_document_count - Get total document count
search_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

2. MCP Server Information

# 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`

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

AI assistant application that integrates FastMCP server with MongoDB Atlas knowledge base, enabling direct MCP tool calling for document search and retrieval through a complete REST API.

Related MCP Servers

mcp-ragdocs
hannesrudolph
A
security
A
license
A
quality
An MCP server implementation that provides tools for retrieving and processing documentation through vector search, enabling AI assistants to augment their responses with relevant documentation context
Last updated -
22
229
MIT License
MongoDB Atlas MCP Serverofficial
mongodb-developer
A
security
A
license
A
quality
An MCP server that enables users to create and manage MongoDB Atlas clusters, users, and network access through natural language commands.
Last updated -
6
20
11
MIT License
Apifox MCP
sujianqingfeng
A
security
F
license
A
quality
An MCP server that integrates Apifox API documentation with AI assistants, allowing AI to extract and understand API information from Apifox projects.
Last updated -
2
23
Astro Docs MCP Server
dreyfus92
A
security
F
license
A
quality
An MCP server that provides AI assistants with access to Astro documentation, enabling them to search and reference Astro docs when helping users with Astro-related tasks.
Last updated -
1
3

View all related MCP servers

Sample MCP Server