mcp-rag

Retrieval-Augmented Generation over any local markdown corpus, exposed as an MCP tool.

Point it at a directory of markdown files. It chunks them at heading boundaries (frontmatter becomes filterable metadata), embeds the chunks, and stores vectors in a local SQLite index. Query it from a CLI for grounded, cited answers - or connect it to any MCP-compatible client (Claude Code, Claude Desktop, Cursor) as a search_corpus tool and let the model drive retrieval itself.

Built as a deliberately transparent reference implementation of the full RAG component chain: ingestion, structure-aware chunking, embeddings, vector storage, retrieval, and grounded generation with citations. No vector database required - at reference-corpus scale, exact cosine search over SQLite is honest and simple.

Pipeline

index:  markdown dir -> parse frontmatter -> chunk at headings -> embed -> SQLite
query:  question -> embed -> cosine top-k (+ metadata filters) -> grounded answer + citations
serve:  the query pipeline behind an MCP tool, so the model decides when and what to retrieve

Status

Early scaffold. Roadmap:

• [ ] index command: ingest + chunk + embed a corpus directory into SQLite
• [ ] query command: retrieve top-k chunks, print with sources
• [ ] ask command: grounded generation with citations (Claude)
• [ ] serve command: MCP server exposing search_corpus
• [ ] Golden-question eval harness (recall@k over a labeled question set)
• [ ] Hybrid retrieval (BM25 + dense) when the eval shows vocabulary-mismatch misses