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:

1. listContentNames - List all content names from the organization's database, optionally filtered by name
2. searchOrganizationContents - Search through the organization's content database using semantic search
3. deleteOrganizationContent - Delete specific content from the organization's database
4. uploadContentFileAboutOrganization - Upload content files about the organization
5. 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

1. Copy the example environment file:

cp env.example .env

2. 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 SDK
• fastapi==0.115.5 - Web framework (for potential future REST API)
• uvicorn==0.32.1 - ASGI server
• requests==2.32.3 - HTTP client library
• python-multipart==0.0.17 - Multipart form data handling
• pydantic==2.10.3 - Data validation
• python-dotenv==1.0.1 - Environment variable management

Development Dependencies

• pytest>=7.0.0 - Testing framework
• pytest-asyncio>=0.21.0 - Async testing support
• pytest-cov>=4.0.0 - Coverage reporting
• black>=23.0.0 - Code formatting
• ruff>=0.1.0 - Fast Python linter
• mypy>=1.0.0 - Type checking
• pre-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

1. Check if the content service is running on the configured URL
2. Verify environment variables in .env
3. Check Python version (requires Python 3.10+)

Missing dependencies

Dependencies are automatically managed by uv from pyproject.toml or inline declarations!