# MCP-RAG-Assistant

![Python](https://img.shields.io/badge/python-3.11+-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![ChromaDB](https://img.shields.io/badge/vector%20store-ChromaDB-yellow)
![MCP](https://img.shields.io/badge/MCP--server-enabled-purple)

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

```bash
# 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).

```bash
# 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

```bash
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)

```bash
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

```bash
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

```bash
pytest

# With verbose output
pytest -v

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

### Automated Startup

```bash
# 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](LICENSE) file for details.