mcp-rag-server

# MCP RAG Server MCP RAG Server is a Python server with RAG (Retrieval-Augmented Generation) capabilities, compliant with the Model Context Protocol (MCP). It indexes documents in various formats, including Markdown, text, PowerPoint, and PDF, using the multilingual-e5-large model, and provides relevant information through vector search. ## Overview This project provides a basic implementation of an MCP server with RAG capabilities. It can index documents in multiple formats and retrieve relevant information based on natural language queries. ## Features - **Basic MCP Server Implementation** - Operates on JSON-RPC over stdio - Mechanism for tool registration and execution - Error handling and logging - **RAG Capabilities** - Loading and parsing of documents in multiple formats (Markdown, text, PowerPoint, PDF) - Support for source directories with hierarchical structures - Conversion of PowerPoint and PDF to Markdown using the `markitdown` library - Embedding generation using selectable models (multilingual-e5-large, ruri, etc.) - Vector database using PostgreSQL's pgvector - Retrieval of relevant information through vector search - Context continuity ensured through chunk retrieval before and after - Full document retrieval capability - Incremental indexing capability (processing only new and changed files) - **Tools** - Vector search tool (MCP) - Document count retrieval tool (MCP) - Index management tool (CLI) ## Prerequisites - Python 3.10 or higher - PostgreSQL 14 or higher (with pgvector extension) ## Installation ### Installing Dependencies ```bash # Install uv if not already installed # pip install uv # Install dependencies uv sync ``` ### Setting Up PostgreSQL and pgvector #### Using Docker ```bash # Start PostgreSQL container with pgvector docker run --name postgres-pgvector -e POSTGRES_PASSWORD=password -p 5432:5432 -d pgvector/pgvector:pg17 ``` #### Creating a Database After starting the PostgreSQL container, create a database with the following command: ```bash # Create ragdb database docker exec -it postgres-pgvector psql -U postgres -c "CREATE DATABASE ragdb;" ``` #### Installing pgvector on Existing PostgreSQL ```sql -- Install pgvector extension CREATE EXTENSION vector; ``` ### Configuring Environment Variables Create a `.env` file and set the following environment variables: ``` # PostgreSQL connection information POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_USER=postgres POSTGRES_PASSWORD=password POSTGRES_DB=ragdb # Document directory SOURCE_DIR=./data/source PROCESSED_DIR=./data/processed # Embedding model settings EMBEDDING_MODEL=intfloat/multilingual-e5-large EMBEDDING_DIM=1024 EMBEDDING_PREFIX_QUERY="query: " EMBEDDING_PREFIX_EMBEDDING="passage: " ``` ## Embedding Model Settings The server allows selection of embedding models through environment variables. ### Supported Models #### multilingual-e5-large (Default) ```env EMBEDDING_MODEL=intfloat/multilingual-e5-large EMBEDDING_DIM=1024 EMBEDDING_PREFIX_QUERY="query: " EMBEDDING_PREFIX_EMBEDDING="passage: " ``` #### cl-nagoya/ruri-v3-30m ```env EMBEDDING_MODEL=cl-nagoya/ruri-v3-30m EMBEDDING_DIM=256 EMBEDDING_PREFIX_QUERY="検索クエリ: " EMBEDDING_PREFIX_EMBEDDING="検索文書: " ``` ### Prefixes Many embedding models (especially E5 series) improve performance with prefixes based on text types: - **Query Prefix**: `EMBEDDING_PREFIX_QUERY` - Automatically added to user's search query - **Document Prefix**: `EMBEDDING_PREFIX_EMBEDDING` - Automatically added to indexed documents Prefixes are handled automatically, so MCP clients do not need to be aware of them. ### Notes on Model Changes When changing the embedding model, the vector dimensions may change, so clear and re-create the existing index: ```bash python -m src.cli clear python -m src.cli index ``` ## Usage ### Starting the MCP Server #### Using uv (Recommended) ```bash uv run python -m src.main ``` With options: ```bash uv run python -m src.main --name "my-rag-server" --version "1.0.0" --description "My RAG Server" ``` #### Using Regular Python ```bash python -m src.main ``` ### Using Command-Line Tools (CLI) CLI tools are available for index clearing and indexing. #### Displaying Help ```bash python -m src.cli --help ``` #### Clearing Index ```bash python -m src.cli clear ``` #### Indexing Documents ```bash # Indexing with default settings (./data/source directory) python -m src.cli index # Indexing a specific directory python -m src.cli index --directory ./path/to/documents # Indexing with chunk size and overlap specified python -m src.cli index --directory ./data/source --chunk-size 300 --chunk-overlap 50 # Or in short form python -m src.cli index -d ./data/source -s 300 -o 50 # Incremental indexing (processing only new and changed files) python -m src.cli index --incremental # Or in short form python -m src.cli index -i ``` #### Retrieving Document Count ```bash python -m src.cli count ``` ### MCP Host Configuration To use this server on an MCP host (Claude Desktop, Cline, Cursor, etc.), make the following settings. Refer to the documentation of each MCP host for the JSON file configuration. #### Example Configuration ```json { "mcpServers": { "mcp-rag-server": { "command": "uv", "args": [ "run", "--directory", "/path/to/mcp-rag-server", "python", "-m", "src.main" ] } } } ``` #### Configuration Points - `command`: `uv` (recommended) or `python` - `args`: Array of execution arguments - `/path/to/mcp-rag-server`: Replace with the actual path to this repository #### Without uv If `uv` is not installed, use regular Python: ```json { "command": "python", "args": [ "-m", "src.main" ], "cwd": "/path/to/mcp-rag-server" } ``` ## Using RAG Tools ### search Performs vector search. ```json { "jsonrpc": "2.0", "method": "search", "params": { "query": "What are Python generators?", "limit": 5, "with_context": true, "context_size": 1, "full_document": false }, "id": 1 } ``` #### Parameter Explanation - `query`: Search query (required) - `limit`: Number of results to return (default: 5) - `with_context`: Whether to retrieve preceding and following chunks (default: true) - `context_size`: Number of chunks to retrieve before and after (default: 1) - `full_document`: Whether to retrieve the full document (default: false) #### Improving Search Results This tool provides better search results through: 1. **Chunk Retrieval Before and After**: - Retrieves chunks before and after those hit by the search and includes them in the results - Can be toggled with the `with_context` parameter - Adjustable number of chunks to retrieve before and after with the `context_size` parameter 2. **Full Document Retrieval**: - Retrieves the full text of documents hit by the search and includes them in the results - Can be toggled with the `full_document` parameter - Useful especially for short documents or when the entire context is important 3. **Result Formatting Improvement**: - Groups search results by file - Visually distinguishes between "search hits," "surrounding context," and "full document" - Maintains document flow by sorting with chunk indexes ### get_document_count Retrieves the number of documents in the index. ```json { "jsonrpc": "2.0", "method": "get_document_count", "params": {}, "id": 2 } ``` ## Examples 1. Place document files in the `data/source` directory. Supported formats include: - Markdown (.md, .markdown) - Text (.txt) - PowerPoint (.ppt, .pptx) - Word (.doc, .docx) - PDF (.pdf) 2. Index documents using CLI commands: ```bash # Initial indexing of all documents python -m src.cli index # Subsequent incremental indexing for efficient updates python -m src.cli index -i ``` 3. Start the MCP server: ```bash uv run python -m src.main ``` 4. Perform a search using the `search` tool. ## Backup and Restore To use the indexed database on another PC, follow these steps for backup and restore. ### Minimal Backup (PostgreSQL Database Only) If you only need to use the RAG search functionality on another PC, a PostgreSQL database backup is sufficient. #### PostgreSQL Database Backup Backup the PostgreSQL database using the `pg_dump` command within the Docker container: ```bash # Backup database within Docker container docker exec -it postgres-pgvector pg_dump -U postgres -d ragdb -F c -f /tmp/ragdb_backup.dump # Copy backup file from container to host docker cp postgres-pgvector:/tmp/ragdb_backup.dump ./ragdb_backup.dump ``` This creates a PostgreSQL database backup file (e.g., 239MB) in the current directory. #### Minimal Restore Procedure 1. Set up PostgreSQL and pgvector on the new PC: ```bash # Using Docker docker run --name postgres-pgvector -e POSTGRES_PASSWORD=password -p 5432:5432 -d pgvector/pgvector:pg17 # Create database docker exec -it postgres-pgvector psql -U postgres -c "CREATE DATABASE ragdb;" ``` 2. Restore database from backup: ```bash # Copy backup file to container docker cp ./ragdb_backup.dump postgres-pgvector:/tmp/ragdb_backup.dump # Restore database within container docker exec -it postgres-pgvector pg_restore -U postgres -d ragdb -c /tmp/ragdb_backup.dump ``` 3. Verify environment settings: Ensure PostgreSQL connection information in the `.env` file is correctly set for the new PC. 4. Verify functionality: ```bash python -m src.cli count ``` This displays the number of documents in the index. If it matches the original PC, the restore is successful. ### Full Backup (Optional) If you plan to add new documents in the future or use incremental indexing, consider backing up the following: #### Backup of Processed Documents Backup the processed documents directory: ```bash # Backup processed documents directory to ZIP file zip -r processed_data_backup.zip data/processed/ ``` #### Backup of Environment Settings File Backup the `.env` file: ```bash # Copy .env file cp .env env_backup.txt ``` #### Full Restore Procedure 1. Prerequisites The new PC must have: - Python 3.10 or higher - PostgreSQL 14 or higher (with pgvector extension) - MCP RAG server codebase 2. Restore PostgreSQL database as in "Minimal Restore Procedure." 3. Restore processed documents: ```bash # Extract ZIP file unzip processed_data_backup.zip -d /path/to/mcp-rag-server/ ``` 4. Restore environment settings file: ```bash # Restore .env file cp env_backup.txt /path/to/mcp-rag-server/.env ``` Edit the `.env` file settings (especially PostgreSQL connection information) as needed for the new PC environment. 5. Verify functionality: ```bash python -m src.cli count ``` ### Notes - Ensure PostgreSQL and pgvector versions are compatible between the original and new PCs. - Backup and restore may take time for large datasets. - Install required Python packages (e.g., `sentence-transformers`, `psycopg2-binary`) on the new PC. ## Directory Structure ``` mcp-rag-server/ ├── data/ │ ├── source/ # Original files (supports hierarchical structure) │ │ ├── markdown/ # Markdown files │ │ ├── docs/ # Document files │ │ └── slides/ # Presentation files │ └── processed/ # Processed files (text extracted) │ └── file_registry.json # Processed file information (for incremental indexing) ├── docs/ │ └── design.md # Design document ├── logs/ # Log files ├── src/ │ ├── __init__.py │ ├── document_processor.py # Document processing module │ ├── embedding_generator.py # Embedding generation module │ ├── example_tool.py # Sample tool module │ ├── main.py # Main entry point │ ├── mcp_server.py # MCP server module │ ├── rag_service.py # RAG service module │ ├── rag_tools.py # RAG tool module │ └── vector_database.py # Vector database module ├── tests/ │ ├── __init__.py │ ├── conftest.py │ ├── test_document_processor.py │ ├── test_embedding_generator.py │ ├── test_example_tool.py │ ├── test_mcp_server.py │ ├── test_rag_service.py │ ├── test_rag_tools.py │ └── test_vector_database.py ├── .env # Environment variable settings file ├── .gitignore ├── LICENSE ├── pyproject.toml └── README.md ``` ## License This project is released under the MIT License. See the [LICENSE](LICENSE) file for details.