# 🌉 mcp-rag-bridge

Connect any AI agent to your document knowledge base via **MCP (Model Context Protocol)**.

This server wraps a RAG (Retrieval-Augmented Generation) pipeline as MCP tools — so Claude, Qwen Code, or any MCP client can **query your documents, add new ones, and get grounded answers with citations**.

## Why this exists

> *"A RAG pipeline without an agent interface is just a search engine. An agent without RAG is just a chatbot. The bridge makes both smarter."*

This project connects the two worlds: your documents become the agent's knowledge, and the agent becomes the interface to that knowledge.

## Architecture

```
┌─────────────────────┐
│   MCP Client (AI)   │
│  Claude / Qwen Code │
└──────────┬──────────┘
           │ stdio (JSON-RPC)
┌──────────▼──────────┐
│   MCP RAG Bridge    │
│                     │
│  query_kb ──────────────┐
│  add_document ─────┐    │
│  list_sources ──┐  │    │
│  delete_doc ─┐  │  │    │
│  search ──┐  │  │  │    │
└──────────┼──┼──┼──┼────┘
           │  │  │  │
     ┌─────▼──▼──▼──▼────┐
     │   ChromaDB +      │
     │   Embeddings      │
     └───────────────────┘
```

## Tools (6)

| Tool | What it does |
|---|---|
| `query_knowledge_base` | Search documents + optional LLM-generated answer with citations |
| `list_sources` | List all indexed documents with chunk counts |
| `add_document` | Index a file (txt, md, pdf, csv, json) into the knowledge base |
| `add_text` | Index raw text (notes, snippets, API responses) |
| `delete_document` | Remove a document from the knowledge base |
| `search_similar` | Find documents similar to a given text |

## Quick start

```bash
git clone https://github.com/zyay/mcp-rag-bridge.git
cd mcp-rag-bridge
python -m venv venv && venv\Scripts\activate
pip install -r requirements.txt

# Start the MCP server
python server.py

# Or test with the included client
python client_test.py
```

## Connect an MCP client

### Qwen Code
```bash
qwen mcp add rag-bridge -- python /full/path/to/mcp-rag-bridge/server.py
```

### Claude Code
```bash
claude mcp add rag-bridge -- python /full/path/to/mcp-rag-bridge/server.py
```

### Claude Desktop
```json
{
  "mcpServers": {
    "rag-bridge": {
      "command": "python",
      "args": ["/full/path/to/mcp-rag-bridge/server.py"]
    }
  }
}
```

## Usage examples

Once connected, the agent can interact with your knowledge base naturally:

```
User: "What documents do you know about?"
Agent: [calls list_sources()]

User: "Index the file at ./docs/architecture.md"
Agent: [calls add_document("./docs/architecture.md")]

User: "How does our authentication system work?"
Agent: [calls query_knowledge_base("authentication system", use_llm=True)]

User: "Find documents similar to 'database migration strategy'"
Agent: [calls search_similar("database migration strategy")]
```

## LLM generation

Set `use_llm=True` in `query_knowledge_base` to get grounded answers:

- **Ollama (default):** Local, free, no API key. Set `OLLAMA_MODEL=llama3.2`.
- **OpenAI fallback:** Set `LLM_PROVIDER=openai` and `OPENAI_API_KEY=sk-...`

The bridge tries the primary provider first, then falls back automatically.

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `RAG_DATA_DIR` | `data` | Document directory |
| `RAG_CHROMA_DIR` | `.chroma` | Vector store path |
| `RAG_COLLECTION` | `docs` | ChromaDB collection name |
| `RAG_CHUNK_SIZE` | `600` | Text chunk size (chars) |
| `RAG_CHUNK_OVERLAP` | `120` | Overlap between chunks |
| `LLM_PROVIDER` | `ollama` | LLM provider (ollama/openai) |
| `OLLAMA_URL` | `http://localhost:11434` | Ollama server URL |
| `OLLAMA_MODEL` | `llama3.2` | Ollama model name |
| `OPENAI_API_KEY` | *(empty)* | OpenAI API key |
| `OPENAI_MODEL` | `gpt-4o-mini` | OpenAI model name |

## Design decisions

| Decision | Why |
|---|---|
| **Self-contained** | No dependency on rag-docs-assistant — works as a standalone project |
| **Hybrid search** | 70% semantic + 30% lexical for better recall |
| **Two-step LLM** | Retrieve first, then generate — grounded answers with citations |
| **ChromaDB** | Zero-config, persistent, no separate server needed |
| **stdio transport** | Works with any MCP client, no HTTP server needed |

## Relationship to other projects

- **[rag-docs-assistant](https://github.com/zyay/rag-docs-assistant)** — Full RAG pipeline with web UI, evals, reranking. This project shares the same core concepts but is self-contained.
- **[mcp-agent-tools](https://github.com/zyay/mcp-agent-tools)** — General-purpose MCP tools (file, MySQL, web, calc). This project is the RAG-specific counterpart.

Together, these three projects demonstrate a complete AI agent ecosystem: general tools + knowledge retrieval + the bridge between them.

## License

MIT