README Documentation
RAG MCP Server (Python)
This is a Python implementation of the RAG (Retrieval-Augmented Generation) MCP (Model Context Protocol) server, equivalent to the Java version. It provides tools for managing organizational content through a content service API.
Features
The server provides the following MCP tools:
- listContentNames - List all content names from the organization's database, optionally filtered by name
- searchOrganizationContents - Search through the organization's content database using semantic search
- deleteOrganizationContent - Delete specific content from the organization's database
- uploadContentFileAboutOrganization - Upload content files about the organization
- uploadContentUrlAboutOrganization - Upload content URLs about the organization
Prerequisites
Install uv
for fast Python package management:
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# or
pip install uv
Quick Start
The fastest way to get started:
# Run tests
./test_uv.sh
# Start the server
./run_server_uv.sh
Installation Options
Option 1: Using uv with pyproject.toml (Recommended)
Dependencies are automatically managed from pyproject.toml
:
# Run directly (uv reads pyproject.toml automatically)
uv run mcp_server.py
# Or run tests
uv run test_server.py
# Install in development mode
uv sync
# Install with development dependencies
uv sync --dev
Option 2: Using uv with inline dependencies
No configuration files needed - dependencies declared inline:
# Run directly with inline dependencies
uv run \
--with mcp==1.0.0 \
--with fastapi==0.115.5 \
--with uvicorn==0.32.1 \
--with requests==2.32.3 \
--with python-multipart==0.0.17 \
--with pydantic==2.10.3 \
--with python-dotenv==1.0.1 \
mcp_server.py
Option 3: Traditional Virtual Environment with uv
# Create and activate virtual environment
uv venv
source .venv/bin/activate
# Install dependencies
uv pip install mcp==1.0.0 fastapi==0.115.5 uvicorn==0.32.1 requests==2.32.3 python-multipart==0.0.17 pydantic==2.10.3 python-dotenv==1.0.1
# Run the server
python mcp_server.py
Configuration
- Copy the example environment file:
cp env.example .env
- Edit
.env
file with your configuration:
USER_ID=your_user_id_here
CONTENT_SERVICE_URL=http://localhost:8080
Usage
Running the MCP Server
Option 1: Using the uv startup script (recommended)
./run_server_uv.sh
Script automatically detects pyproject.toml and uses it, falling back to inline dependencies
Option 2: Using the traditional startup script
./run_server.sh
Option 3: Direct execution with uv
# With pyproject.toml
uv run mcp_server.py
# Or with inline dependencies
uv run \
--with mcp==1.0.0 \
--with fastapi==0.115.5 \
--with uvicorn==0.32.1 \
--with requests==2.32.3 \
--with python-multipart==0.0.17 \
--with pydantic==2.10.3 \
--with python-dotenv==1.0.1 \
mcp_server.py
The server will start and listen for MCP protocol messages via stdin/stdout.
Environment Variables
USER_ID
: The user ID to use for API calls (defaults to "invalid")CONTENT_SERVICE_URL
: The URL of the content service API (defaults to "http://localhost:8080")
Testing
Using uv (recommended)
./test_uv.sh
# or
uv run test_server.py # Uses pyproject.toml
Using traditional approach
./run_server.sh # This will set up venv and install dependencies
source .venv/bin/activate && python test_server.py
Development
Installing Development Dependencies
# Install all dependencies including dev tools
uv sync --dev
# This includes: pytest, black, ruff, mypy, pre-commit
Code Formatting and Linting
# Format code with black
uv run black .
# Lint with ruff
uv run ruff check .
# Type check with mypy
uv run mypy .
Running Tests with pytest
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov
# Run only unit tests
uv run pytest -m unit
Architecture
The Python MCP server consists of three main components:
1. RagService (rag_service.py
)
- Handles all HTTP API calls to the content service
- Manages file uploads and URL submissions
- Provides error handling and logging
2. RagTools (rag_tools.py
)
- Defines the MCP tools that are exposed to clients
- Acts as a bridge between MCP tool calls and the RagService
- Handles parameter validation and response formatting
3. MCP Server (mcp_server.py
)
- Implements the MCP protocol using the Python MCP SDK
- Handles tool registration and execution
- Manages the server lifecycle and communication
Tool Schemas
listContentNames
{
"name": "listContentNames",
"description": "List all content names from the organization's database optionally filtered by name",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional name filter to search for specific content"
}
}
}
}
searchOrganizationContents
{
"name": "searchOrganizationContents",
"description": "Search through the organization's content database using semantic search",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query"
}
},
"required": ["query"]
}
}
deleteOrganizationContent
{
"name": "deleteOrganizationContent",
"description": "Delete specific content from the organization's database",
"inputSchema": {
"type": "object",
"properties": {
"contentId": {
"type": "string",
"description": "The ID of the content to delete"
}
},
"required": ["contentId"]
}
}
uploadContentFileAboutOrganization
{
"name": "uploadContentFileAboutOrganization",
"description": "Upload content file about the organization",
"inputSchema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"description": "The file content to upload"
},
"fileName": {
"type": "string",
"description": "The file name"
},
"role": {
"type": "string",
"description": "The roles of the user"
}
},
"required": ["file", "fileName"]
}
}
uploadContentUrlAboutOrganization
{
"name": "uploadContentUrlAboutOrganization",
"description": "Upload content url about the organization",
"inputSchema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The URL to upload"
},
"role": {
"type": "string",
"description": "The roles of the user"
}
},
"required": ["url"]
}
}
Dependencies
mcp==1.0.0
- MCP Python SDKfastapi==0.115.5
- Web framework (for potential future REST API)uvicorn==0.32.1
- ASGI serverrequests==2.32.3
- HTTP client librarypython-multipart==0.0.17
- Multipart form data handlingpydantic==2.10.3
- Data validationpython-dotenv==1.0.1
- Environment variable management
Development Dependencies
pytest>=7.0.0
- Testing frameworkpytest-asyncio>=0.21.0
- Async testing supportpytest-cov>=4.0.0
- Coverage reportingblack>=23.0.0
- Code formattingruff>=0.1.0
- Fast Python lintermypy>=1.0.0
- Type checkingpre-commit>=3.0.0
- Git hooks
Dependencies are managed via pyproject.toml with uv for modern Python packaging
File Structure
rag-mcp-py/
├── README.md # This documentation
├── pyproject.toml # Project configuration and dependencies
├── env.example # Environment configuration template
├── .env # Environment configuration (create from template)
├── .gitignore # Git ignore patterns
├── mcp_server.py # Main MCP server implementation
├── rag_service.py # HTTP service layer
├── rag_tools.py # MCP tools definitions
├── test_server.py # Test suite
├── run_server.sh # Traditional startup script (creates .venv)
├── run_server_uv.sh # uv-based startup script (recommended)
└── test_uv.sh # uv-based test script
Comparison with Java Version
This Python implementation mirrors the functionality of the Java MCP server:
Java Component | Python Equivalent | Description |
---|---|---|
RagMcp.java | mcp_server.py | Main server application |
RagTools.java | rag_tools.py | Tool definitions and handlers |
RagService.java | rag_service.py | Business logic and API calls |
The Python version maintains the same API contracts and tool schemas as the Java version, ensuring compatibility with existing MCP clients.
Why uv?
We use uv
for package management because it's:
- Fast: 10-100x faster than pip (installed 23 packages in 28ms!)
- Reliable: Better dependency resolution
- Modern: Built with Rust, designed for modern Python workflows
- Flexible: Works with pyproject.toml, inline dependencies, or traditional approaches
- Standards Compliant: Full support for PEP 621 and modern Python packaging
Troubleshooting
uv not found
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Restart your shell or source the path
Permission denied on scripts
chmod +x *.sh
Server won't start
- Check if the content service is running on the configured URL
- Verify environment variables in
.env
- Check Python version (requires Python 3.10+)
Missing dependencies
Dependencies are automatically managed by uv from pyproject.toml or inline declarations!