rag-mcp

name: rag-mcp type: local semantic-search MCP server for coding agents and document workflows

A coding agent should not have to choose between opening files one at a time and dumping an entire repository into context.

Install • Evals • How it works • State

Related MCP server: ContextCore

Quick start

git clone https://github.com/MasihMoafi/rag-mcp
cd rag-mcp
uv sync

Run the automated tests:

.venv/bin/python -m pytest tests/ -v

Then register the server with an MCP client.

Claude Code

claude mcp add rag -s user -- /absolute/path/to/rag-mcp/.venv/bin/python /absolute/path/to/rag-mcp/server.py

Codex / Elpis

Add to ~/.codex/config.toml:

[mcp_servers.rag]
command = "/absolute/path/to/rag-mcp/.venv/bin/python"
args = ["/absolute/path/to/rag-mcp/server.py"]

[mcp_servers.rag.env]
RAG_MCP_WORKSPACE_ROOT = "/absolute/path/to/your/project"

Expected result: the client discovers query_knowledge_base, and a query returns ranked passages with source paths from the requested scope.

What is rag-mcp

rag-mcp is a local hybrid-search MCP server: point it at a file or folder, ask a question in plain language, and get back the passages that actually answer it — with the exact file and location, not a guess.

Coding agents normally search a codebase by opening files one at a time or dumping an entire repository into the conversation. Both waste time and context. rag-mcp replaces that with one tool call: search by meaning, get ranked results with sources, keep going. Embeddings, vector search, and reranking all run locally; the server exposes one read-only MCP tool to compatible clients.

No third-party logo or benchmark — the image above is the actual retrieval-accuracy evidence this repo ships, not decoration.

Retrieval accuracy

Recorded, reproducible retrieval runs live under evals/ — not part of CI, kept as evidence. Every number below is a real call to query_knowledge_base through today's live server (hybrid BM25 + vector + reranking), graded against a known answer — not simulated.

The top result is a single real directory containing a 29-file Rust crate, 6 Python scripts, and a Jupyter notebook, searched with doc_path pointed at the whole directory — the server has to find the right file among three languages, not just the right passage in one document. The other four are one long document each (a paper, two books, a novel), same protocol, directly comparable to each other but not to the directory test above them.

No setting was changed between rows — same chunk size, top_k, and reranker throughout. Code and the short, explicitly-structured paper score highest because each fact sits in one place a chunk boundary can respect; the two long narrative works score lower because their answers are interpretive and spread across passages, which chunk-based retrieval handles worse regardless of tuning. Nothing here was tuned per corpus.

Per-question results for every corpus — including where each miss actually failed (vague topical overlap, a truncated chunk, or the fact genuinely absent from top-k).

An earlier, now-superseded Napoleon run with reranking manually disabled scored 93.3% — that number describes raw BM25+vector retrieval in isolation, not this server as it actually runs, and is kept in evals/napoleon/experiment_log.md only for its chunk-size finding (1000 characters beat 300). The earlier separate Rust-only and notebook-only runs are likewise superseded by the combined directory test above and kept under evals/elpis-memories-crate/ and evals/notebook/ only as raw evidence.

This is five corpora, one embedding model (qwen3-embedding:8b), one point in time — not a benchmark against other retrieval tools.

The problem

Coding agents commonly retrieve context by either opening files one by one or loading a large portion of the repository. The first can miss relevant files; the second consumes context with material the current task may not need.

rag-mcp moves retrieval into one local tool call so the agent can search by meaning without making the entire tree part of every prompt.

How it works

query + optional path
        ↓
chunking
        ↓
BM25 lexical search + local embeddings / Qdrant
        ↓
Reciprocal Rank Fusion
        ↓
CrossEncoder reranking
        ↓
ranked chunks + exact source paths

Repository structure:

rag-mcp/
├── server.py       # stdio JSON-RPC MCP host
├── rag/            # chunking, BM25, vector search, reranking
└── utils/proxy.py  # local proxy-environment handling

Technical boundaries:

• one MCP tool: query_knowledge_base(query, doc_path?);

• default embeddings: all-MiniLM-L6-v2 (~80MB, fast — overridable, see Configuration);

• reranking runs by default: cross-encoder/ms-marco-MiniLM-L-6-v2 (~80MB, fast — overridable, or disable it entirely);

• local embedded/on-disk Qdrant;

• doc_path can scope each call to a file or directory;

• per-path indexes are persisted under rag/rag_db_v2/;

• common large/build directories such as .git, node_modules, .venv, dist, build, and target are rejected;

• configurable depth/token limits fail explicitly instead of scanning an unbounded tree.

Configuration

Every retrieval knob is an environment variable, not a source edit. Unset means the default shown:

The shipped defaults are the small, fast pair (~80MB each) the evals above were run against — not the largest model available, and 100% local: no key, no network call, no per-query cost.

openai_compatible is the one non-local option: it leaves the machine. One client implementation covers real OpenAI, Ollama's own /v1 endpoint, and Qwen/DashScope's and Gemini's OpenAI-compatible modes — install the optional openai package (uv sync --extra openai), then set RAG_MCP_EMBED_PROVIDER=openai_compatible, RAG_MCP_EMBED_MODEL to the provider's model name, RAG_MCP_EMBED_API_KEY, and RAG_MCP_EMBED_BASE_URL if the provider isn't OpenAI itself. The client construction is verified; a real embedding call against a paid provider is not — test it against your own key before trusting it. A cross-encoder reranker type named llm also exists in the code but its scoring is unimplemented scaffolding (every passage gets the same score) — do not set it, it does nothing useful.

Swapping any of this is an environment variable in the server's MCP registration, no code change. Example, in ~/.codex/config.toml:

[mcp_servers.rag.env]
RAG_MCP_WORKSPACE_ROOT = "/absolute/path/to/your/project"
RAG_MCP_EMBED_PROVIDER = "ollama"
RAG_MCP_EMBED_MODEL = "qwen3-embedding:8b"

Current state

Implemented and verified

• MCP initialize → tools/list → tools/call protocol path.

• Read-only query_knowledge_base tool.

• Workspace-root and explicit doc_path scoping.

• Local hybrid retrieval and reranking.

• Guardrails for excluded directories and oversized scopes.

• End-to-end registration was exercised through a real MCP client during development.

Implemented but not yet covered by the current tests

• The alternative Ollama embedding-provider path in rag/core.py.

• The openai_compatible embedding provider: client construction is verified, a real call against a paid provider is not.

Planned

Nothing is formally tracked yet. Extend it when a concrete retrieval failure or client requirement appears.

Intentionally unsupported

• Hosted/remote vector databases.

• File types outside the extension allowlist in server.py.

• Write/mutation tools; this server is retrieval-only.

What sets this apart

These are design choices, not novelty claims:

• Local retrieval: source files, embeddings, vector search, and reranking stay on the machine.

• Small transport layer: the MCP host uses direct stdio JSON-RPC rather than depending on an MCP SDK.

• Per-call scope: one server can search different files/directories instead of requiring one fixed knowledge base per project.

• Evidence in the response: returned chunks include source paths rather than only synthesized prose.

Evals and test series

Five lightweight tests live under tests/:

uv sync --group dev
.venv/bin/python -m pytest tests/ -v

They cover:

• read-only tool annotations;

• default workspace scoping;

• explicit doc_path scoping;

• rejection of excluded directories;

• rejection of depth-limit violations.

Protocol-level check, without another MCP client:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"query_knowledge_base","arguments":{"query":"how does reciprocal rank fusion combine bm25 and vector results"}}}' \
  | RAG_MCP_WORKSPACE_ROOT="$PWD" .venv/bin/python server.py

A successful self-query should return evidence pointing at the RRF implementation in rag/core.py.

What the tests prove: MCP transport/scoping/guardrail behavior covered by those cases.

What they do not prove: retrieval quality across arbitrary corpora, cross-client compatibility, or superiority to grep/code-search/RAG alternatives.

Example

query_knowledge_base(
  "how does retry backoff work for failed jobs",
  doc_path="codex-rs/memories"
)

The response is intended for the calling agent: ranked source passages it can use as task context rather than a standalone chat answer.

Future development

Keep the surface small. Add capability only when real usage shows a retrieval, compatibility, or performance gap worth testing.

License

MIT — see LICENSE.