# rag-mcp-lab

A small, production shaped RAG service that speaks MCP. Ask a question, get the most relevant chunks of your documents back, or a written answer with sources. Good for learning how embeddings, vector search and MCP fit together.

## Try it

```bash
git clone https://github.com/loganathansellappa/rag-mcp-lab.git
cd rag-mcp-lab
pip install -r requirements.txt
python -m src.main
```

A sample knowledge base is already built (`data/knowledge_base.json`, from three short docs in `data/docs/`), so the server starts right away. It talks MCP over stdio, so point a client at it. See [`examples/mcp-client.json`](examples/mcp-client.json).

## Tools

| Tool | What it does | Needs |
|---|---|---|
| `rag-search` | Semantic search, returns chunks with relevance scores | nothing |
| `rag-generate` | Search, then an LLM writes the answer with sources | `LITELLM_KEY` |

Without a key, `rag-generate` returns an error and `rag-search` works as normal.

## Use your own docs

Drop markdown files into `data/docs/` and run `make kb`. Details in [UPDATING_THE_KB](docs/UPDATING_THE_KB.md).

## Layout

```
src/          config, retrieval, MCP server, entry point
scripts/      build_kb.py (chunk and embed)
data/         sample docs and the built knowledge base
config/       default.json, production.json
deployment/   Dockerfile, Kubernetes manifest
tests/        unit tests and an MCP stdio round trip
docs/         architecture, KB updates
examples/     MCP client config
```

More in [ARCHITECTURE](docs/ARCHITECTURE.md).

## Develop

```bash
pip install -r requirements-dev.txt
make test
```

## Deploy

```bash
make docker-build IMAGE=your-registry/rag-mcp:1.0.0
make k8s-deploy
```

The manifest expects a `rag-secrets` secret with `litellm-key` and a `rag-kb-data` ConfigMap holding the KB file.

## License

MIT