mcp-rag

mcp-rag-server is a local, zero-network after model load Retrieval-Augmented Generation helper that you plug into any client speaking the Model Context Protocol (MCP). It indexes a repository directory, creates local embeddings with the Hugging Face transformers, and exposes MCP tools such as rag_query for semantic search, read_file for safe file access, and list_files to browse the repo. You can run this server in stdio mode for IDE integration or in HTTP mode to watch logs and readiness from a distance. The server supports PDF extraction, per-language config, chunking with overlap for better recall, and incremental updates to avoid full rebuilds. Start via Node.js (dist/index.js) and configure environment variables like REPO_ROOT, MCP_TRANSPORT, and MODEL_NAME to tailor behavior. Tools like rag_query, read_file, and list_files are available through the MCP interface once the server reports readiness.

Prerequisites:\n- Node.js 18+ installed on your system.\n- A target repository directory you want to index (set via REPO_ROOT).\n- Optional: a local Transformer model cache path (TRANSFORMERS_CACHE).\n\nInstall steps:\n1) Install dependencies and build:\n\n``` npm install npm run build

2) Prepare environment and run the server locally:\n\n```
# Windows PowerShell / macOS/Linux shell examples
export REPO_ROOT="/path/to/your-repo"        # or set for Windows PowerShell
export MCP_TRANSPORT="stdio"                  # default; change to http for HTTP transport
# Optional: point to a model cache to speed up first run
export TRANSFORMERS_CACHE="/path/to/cache"

node dist/index.js

3. Verify readiness (if using HTTP): http://127.0.0.1:3000/health should indicate ready when embeddings exist.\n\nOptional: run inspector for MCP tooling:\n``` npx @modelcontextprotocol/inspector http://localhost:3000/mcp --transport http

Tips and notes:\n- Start with REPO_ROOT pointing to a local checkout of your repository. The server will read files relative to REPO_ROOT and will reject paths escaping that root for safety.\n- For large repos, prefer MCP_TRANSPORT=http to monitor progress and watch readiness. The health endpoint includes indexing progress: filesDiscovered, chunksTotal, and chunksEmbedded.\n- If you enable INDEX_STORE_PATH, embeddings persist across restarts, enabling faster warm starts.\n- PDF files are supported; text is cached in pdf-text-cache.json and treated like normal text for search.\n- LAZY/Incremental indexing helps avoid full rebuilds on small changes.\n- Fine-tuning: set ALLOWED_EXT to limit indexing to relevant languages and file types.\n- If you encounter slow startup, set TRANSFORMERS_CACHE to a fast local directory and ensure MODEL_NAME is reachable.