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: 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: ```bash # Install uv curl -LsSf https://astral.sh/uv/install.sh | sh # or pip install uv ``` ## Quick Start The fastest way to get started: ```bash # 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`: ```bash # 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: ```bash # 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 ```bash # 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: ```bash 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) ```bash ./run_server_uv.sh ``` *Script automatically detects pyproject.toml and uses it, falling back to inline dependencies* #### Option 2: Using the traditional startup script ```bash ./run_server.sh ``` #### Option 3: Direct execution with uv ```bash # 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) ```bash ./test_uv.sh # or uv run test_server.py # Uses pyproject.toml ``` ### Using traditional approach ```bash ./run_server.sh # This will set up venv and install dependencies source .venv/bin/activate && python test_server.py ``` ## Development ### Installing Development Dependencies ```bash # Install all dependencies including dev tools uv sync --dev # This includes: pytest, black, ruff, mypy, pre-commit ``` ### Code Formatting and Linting ```bash # 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 ```bash # 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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```bash # Install uv curl -LsSf https://astral.sh/uv/install.sh | sh # Restart your shell or source the path ``` ### Permission denied on scripts ```bash 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!