Content Server

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

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!

You must be authenticated.

security – no known vulnerabilities

license - not found

quality - confirmed to work

Tools

Stores Organizations content

Related MCP Servers

Algoliaofficial
algolia
-
security
A
license
-
quality
Algolia
Last updated -
18
Go
MIT License
Currentsofficial
currents-dev
-
security
F
license
-
quality
Currents
Last updated -
4
TypeScript
Crowdlistening
terrylinhaochen
-
security
A
license
-
quality
Crowdlistening
Last updated -
Python
MIT License
Liveblocksofficial
liveblocks
A
security
A
license
A
quality
Liveblocks
Last updated -
39
1
TypeScript
Apache 2.0

View all related MCP servers