title: rag-mcp type: project-readme tags: [rag, retrieval, embeddings, mcp]

rag-mcp

A minimal, honest RAG-over-a-corpus MCP retrieval tool. One tool, search_knowledge(query, k), 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

• Cited - every hit carries source + heading + chunk_index.
• Auth-scoped - results are confined to the configured corpus root; sources that escape it (absolute paths, .. traversal) are refused.
• Fail-soft - a down or empty store returns a structured error, never an exception that crashes the calling agent.
• Bounded - k is clamped to [1, 20]; empty queries are rejected.
• Version-pinned deps (requirements.txt).

Stack

Quick start

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

# Ingest a corpus (markdown)
python -m rag_mcp.cli ingest path/to/docs --db ./store.chroma

# 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

# 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

As an MCP server

Register via mcp.yaml (validated against mcp-factory's Manifest loader). The tool is search_knowledge(query, k); it reads the store configured by the RAG_MCP_* env vars.

Tests

python -m pytest        # 68 passed

Layout

rag_mcp/
  chunking.py   heading-scoped, overlapping markdown chunks
  store.py      VectorStore (Chroma) + Embedder protocol (MiniLM default + BgeEmbedder opt-in + offline HashEmbedder)
  ingest.py     idempotent ingest pipeline with source/heading/chunk-index metadata
  search.py     search_knowledge: cited, auth-scoped, fail-soft, bounded
  server.py     MCP stdio server exposing search_knowledge
  config.py     env-driven Config
  cli.py        ingest + query CLI
  __main__.py   console entrypoint (`python -m rag_mcp` / `rag-mcp` script); fails loud on missing config
run_server.py   operational MCP entrypoint (referenced by mcp.yaml)
mcp.yaml        manifest (mcp-factory model)

mcp-name: io.github.jaimenbell/rag-mcp