# 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
1. **User sends chat message** → FastAPI `/chat` endpoint
2. **LLM generates JSON function call** → Compatible with Llama3-8B-Instruct
3. **LLM service calls MCP tools directly** → `await mcp._mcp_call_tool(function_name, parameters)`
4. **MCP tools query MongoDB Atlas** → Native FastMCP integration
5. **Documents returned through MCP** → Proper MCP protocol response
6. **LLM processes results** → Generates final response with context
7. **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
```bash
# Using Task
task test-health

# Manual curl
curl -X GET "http://localhost:8000/healthz" -H "accept: application/json" | jq
```

#### 2. MCP Server Information
```bash
# Using Task
task test-mcp-info

# Manual curl
curl -X GET "http://localhost:8000/mcp/info" -H "accept: application/json" | jq
```

#### 3. Document Count
```bash
# Using Task
task test-document-count

# Manual curl
curl -X GET "http://localhost:8000/documents/count" -H "accept: application/json" | jq
```

#### 4. Document Search
```bash
# 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)
```bash
# 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)
```bash
# 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

1. Start the server: `task dev`
2. Open http://localhost:8000/docs in your browser
3. Use the interactive API documentation to test endpoints
4. 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

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