mcp-rag

This MCP RAG Server provides a Retrieval-Augmented Generation capability that indexes and searches across multiple document formats (Markdown, text, PowerPoint, PDF) using a multilingual embedding model. It exposes a JSON-RPC over stdio interface and includes tools for vector search, document counting, and index management. By default, it uses the multilingual-e5-large embedding model (configurable via environment variables) and stores vector data in a PostgreSQL database with the pgvector extension. You can interact with the server via the CLI tools to index documents, clear or query indices, and perform searches with optional context and full-document retrieval. The provided search tool returns contextual chunks around hits, and can optionally fetch full documents for richer results, making it suitable for knowledge retrieval tasks and complex document contexts.

Prerequisites:

• Python 3.10+
• PostgreSQL 14+ with pgvector extension
• (Optional) uv (uvicorn/uv) for Python execution as described below

Installation steps:

1. Install uv if not present and set up dependencies:

# Install uv if not already installed
pip install uv

# Install project dependencies if a requirements file exists (adjust as needed)
uv sync

2. Set up PostgreSQL with pgvector (examples from README):

• Using Docker:

# Start PostgreSQL container with pgvector
docker run --name postgres-pgvector -e POSTGRES_PASSWORD=password -p 5432:5432 -d pgvector/pgvector:pg17

• Create the ragdb database inside the container:

docker exec -it postgres-pgvector psql -U postgres -c "CREATE DATABASE ragdb;"

3. Prepare environment variables (.env):

• Create a .env file with PostgreSQL connection info and directories:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=ragdb

SOURCE_DIR=./data/source
PROCESSED_DIR=./data/processed

EMBEDDING_MODEL=intfloat/multilingual-e5-large
EMBEDDING_DIM=1024
EMBEDDING_PREFIX_QUERY="query: "
EMBEDDING_PREFIX_EMBEDDING="passage: "

4. Run the server (example with uv as recommended):

uv run python -m src.main

If you prefer plain Python, you can run:

python -m src.main

Notes and tips:

• The embedding model and vector dimensions can be configured via environment variables. If you switch models, you may need to reindex because vector dimensions can change.
• The server supports incremental (差分) indexing to process only new or changed files. Use the CLI options described in the README to customize indexing behavior:
  • python -m src.cli index
  • python -m src.cli index --incremental or -i
• Ensure PostgreSQL with pgvector is accessible from your environment; if running in Docker, use the mapped host/port and correct credentials in .env.
• The MCP host config example demonstrates how to embed this server's launch within a host controller. Update /path/to/mcp-rag-server to the actual repository path.
• If you encounter embedding dimension mismatches after updating the embedding model, clear and re-run indexing to rebuild the vectors: python -m src.cli clear python -m src.cli index
• The RAG tooling includes search, get_document_count, and index management. Use these to validate the index health and perform retrieval with optional context and full document retrieval.