MCP-RAG-Assistant

A hybrid Retrieval-Augmented Generation pipeline that indexes documents and exposes them via an MCP (Model Context Protocol) server. Designed to feed relevant context to an external LLM (e.g., opencode CLI), acting as your intelligent knowledge assistant.

Comes pre-bundled with a curated corpus of 30 Data Science tutorials covering ML, Deep Learning, NLP, Computer Vision, and more — ready to index and query out of the box.

Architecture

Documents ──► Ingestion ──► ChromaDB (vector store)
                   │                                │
              Chunking                          Hybrid Search
              Embeddings                     ┌────┴────┐
                                           Vector    BM25
                                             └──┬───┘
                                            RRF Fusion
                                                │
                                          Cross-encoder
                                                │
                                           Results ──► MCP Server ──► LLM

Quickstart

Prerequisites

• Python 3.11+
• Virtual environment

Setup

# Create and activate virtual environment
python -m venv venv

# Windows
venv\Scripts\activate
# Linux / macOS
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# (Optional) Install in dev mode for test dependencies
pip install -e .[dev]

Index Documents

Place your documents in rag/documents/ (supports: .md, .txt, .pdf, .docx, .xlsx, .pptx, .html, images, and more).

# Index all documents
python -m rag ingest

# Or run the ingestion script directly
python rag/ingestion.py

Example output:

2026-07-28  [INFO]  Indexing documents...
2026-07-28  [INFO]  Processing  Day 1.md
2026-07-28  [INFO]    └─ 8 chunk(s)
2026-07-28  [INFO]  Processing  Day 2.md
2026-07-28  [INFO]    └─ 6 chunk(s)
...
2026-07-28  [INFO]  Indexing complete — 247 total chunk(s) in collection

Note: The first run will download the all-MiniLM-L6-v2 embedding model (~80 MB). Subsequent runs use only new/changed files.

Start the MCP Server

python mcp-servers/rag-mcp/server.py

The MCP server exposes a search_company_knowledge tool that returns relevant context chunks for any natural-language question.

Search (Interactive)

python -m rag search

Example session:

RAG interactive search — type :q to quit.

query> What is the difference between AI and ML?

Artificial Intelligence (AI) is the broad field of creating machines that...

query> :q

Evaluate Retrieval

python -m rag evaluate
# With cross-encoder reranking:
python -m rag evaluate --rerank

Example output:

  MRR       = 0.8923
  Recall@1  = 0.8276
  Recall@3  = 0.9655
  Recall@5  = 1.0000

Run Tests

pytest

# With verbose output
pytest -v

# With coverage
pip install pytest-cov
pytest --cov=rag tests/

Automated Startup

# Windows
start_rag.bat

# Linux / macOS
bash scripts/start.sh

Both scripts activate the virtual environment, install/verify dependencies, index documents, and start the MCP server.

Project Structure

├── rag/                          # Core RAG library
│   ├── __init__.py               # Package init
│   ├── __main__.py               # CLI entry point (python -m rag)
│   ├── settings.py               # Central configuration
│   ├── ingestion.py              # Document indexing pipeline
│   ├── retrieval.py              # Hybrid search (vector + BM25 + reranker)
│   ├── evaluate.py               # Retrieval evaluation (MRR, Recall@K)
│   ├── chroma_db/                # Persistent vector store (gitignored)
│   ├── documents/                # Place your documents here
│   │   └── 30 days md/           # Pre-bundled Data Science tutorials (29 Q&A test cases)
│   └── test_set.json             # Curated Q&A test cases
├── mcp-servers/
│   └── rag-mcp/
│       └── server.py             # MCP server exposing search tool
├── tests/                        # Test suite (pytest)
│   ├── test_ingestion.py
│   ├── test_retrieval.py
│   └── test_evaluate.py
├── scripts/
│   └── start.sh                  # Linux/macOS startup script
├── start_rag.bat                 # Windows startup script
├── pyproject.toml                # Project metadata & packaging
├── requirements.txt              # Python dependencies
├── .gitignore
└── README.md

Key Features

• Hybrid search: Semantic (vector) + keyword (BM25) fused via Reciprocal Rank Fusion
• Cross-encoder reranker: Optional precision boost with cross-encoder/ms-marco-MiniLM-L-6-v2
• Incremental indexing: Only processes new/changed files; prunes deleted file chunks
• Multi-format support: Plain text (.md, .txt, .py, etc.) + structured docs (.pdf, .docx, .xlsx, images) via Docling
• MCP-native: Exposed as a standard MCP tool — works with any MCP host (IDEs, agents, CLIs)
• Configurable: All tunable parameters in rag/settings.py
• Evaluation suite: 29 curated Q&A test cases with MRR and Recall@K metrics

Dependencies

Package	Purpose
chromadb	Vector store
sentence-transformers	Embeddings & cross-encoder
docling	Document parsing (PDF, DOCX, images)
rank-bm25	Keyword search
mcp	Model Context Protocol server

License

This project is licensed under the MIT License. See the LICENSE file for details.