Rag MCP server

rag-mcp

A minimal, honest RAG-over-a-corpus MCP retrieval tool. One tool,

searchknowledge(query, k, docclass=None), that embeds a query, vector-searches a local

corpus, and returns passages with citations (source + heading + chunk index) so answers

are traceable.

Built to slot into the mcp-factory manifest model. Fully local + $0 (no paid embedding API).

Why it's safe to put in front of a real corpus

(absolute paths, .. traversal) are refused.

• Cited - every hit carries source + heading + chunk_index.
• Auth-scoped - results are confined to the configured corpus root; sources that escape it

crashes the calling agent.

• Fail-soft - a down or empty store returns a structured error, never an exception that

• Bounded - k is clamped to [1, 20]; empty queries are rejected.
• Version-pinned deps (requirements.txt).

Stack

Protocol revision

Pinned to mcp==2.0.0, the first SDK release implementing MCP protocol revision 2026-07-28. The server serves both eras on the same stdio connection -- the client's first frame picks:

2026-07-28 is not reachable via the initialize handshake; it is a "modern" revision reached through server/discover or an inline _meta version stamp. Era selection is automatic and per-connection -- there is no server-side flag.

tests/testprotocolversion.py asserts both paths end-to-end, so a dependency rollback that silently drops the server to an older revision fails CI instead of passing quietly.

Quick start

python -m venv .venv && .venv/Scripts/python -m pip install -r requirements.txt

# Ingest a corpus (markdown). Incremental by default: only files whose content
# changed since the last run are re-embedded.
python -m rag_mcp.cli ingest path/to/docs --db ./store.chroma

# Force a rebuild in place (ignore the manifest, re-embed everything)
python -m rag_mcp.cli ingest path/to/docs --db ./store.chroma --full

# One-off query (corpus root = the auth scope)
python -m rag_mcp.cli query "your question" --db ./store.chroma --corpus path/to/docs -k 5

# Same, restricted to one doc_class ("note" or "handoff" -- see "Filtering by
# document class" below)
python -m rag_mcp.cli query "your question" --db ./store.chroma --corpus path/to/docs --doc-class note

# Run as an MCP server (stdio); configure via env first
#   RAG_MCP_CORPUS_ROOT, RAG_MCP_DB_PATH, RAG_MCP_COLLECTION, RAG_MCP_EMBEDDER
python run_server.py        # operational entrypoint (referenced by mcp.yaml)
python -m rag_mcp           # same server, via the packaged console entry point
rag-mcp                     # after `pip install jaimenbell-rag-mcp` -- console script

Keeping the index fresh (incremental ingest)

Ingest is incremental by default. A manifest inside the store dir records a SHA-256 of each file's decoded text; a run re-embeds only what actually changed, and prunes what upsert alone never could (chunks of deleted/renamed notes, and trailing chunks of notes that got shorter).

Measured on a live 2808-file / 26.6 MiB corpus (bge, CPU):

Shortened. The full README is on GitHub.