# lightrag-docs-rag-mcp

An MCP server that exposes a [LightRAG](https://github.com/HKUDS/LightRAG) instance as
three tools, so any MCP-capable agent can ground its answers in your indexed docs
instead of relying on recall.

LightRAG ships a REST server but **no MCP server of its own**, and the community package
uses different tool names. This one is a thin, auditable wrapper over four LightRAG HTTP
routes, with tool names chosen to match how tool-calling corpora actually name them.

| Tool | Purpose |
| --- | --- |
| `docs_query` | Ask the knowledge graph a question; returns a grounded answer **and the source files** that grounded it |
| `docs_ingest` | Add documents to the index |
| `docs_stats` | Document counts by pipeline stage, whether indexing is running, and the model endpoints in use |

## Why these names

Registered under a server named `docs_rag`, the tools surface as
`mcp__docs_rag__docs_query`, `mcp__docs_rag__docs_ingest`, `mcp__docs_rag__docs_stats`.
That matches the naming used by existing agent tool-calling datasets, so a corpus
generated against this server validates without a rename layer.

## Install

```bash
uv tool install lightrag-docs-rag-mcp
# or, from a checkout:
uv tool install .
```

Requires a running LightRAG server (`lightrag-server`). Python 3.10+.

## Configure

### Hermes Agent

```bash
hermes mcp add docs_rag --command lightrag-docs-rag-mcp
```

or in `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  docs_rag:
    command: "lightrag-docs-rag-mcp"
    env:
      LIGHTRAG_BASE_URL: "http://127.0.0.1:9621"
    timeout: 900
```

### Claude Desktop / other MCP clients

```json
{
  "mcpServers": {
    "docs_rag": {
      "command": "lightrag-docs-rag-mcp",
      "env": { "LIGHTRAG_BASE_URL": "http://127.0.0.1:9621" }
    }
  }
}
```

## Environment

| Variable | Default | Meaning |
| --- | --- | --- |
| `LIGHTRAG_BASE_URL` | `http://127.0.0.1:9621` | LightRAG server root |
| `LIGHTRAG_API_KEY` | *(unset)* | Sent as `X-API-Key` when the server requires one |
| `LIGHTRAG_TIMEOUT` | `900` | Per-request timeout, seconds |
| `DOCS_RAG_DEBUG` | *(unset)* | Verbose logging to **stderr** |

## Operational notes

These are the things that will actually bite you.

**Queries are slow, and that is the server's model choice, not this wrapper.** A hybrid
query over a ~20-chunk context measured **~212 s** on a local 9B. Context size dominates.
If you need faster answers, cap the server's `MAX_TOTAL_TOKENS` /
`MAX_ENTITY_TOKENS` / `MAX_RELATION_TOKENS` and raise `LLM_TIMEOUT`. The default timeout
here is 900 s so a slow-but-correct answer does not become an error.

**The LightRAG LLM must have thinking disabled.** With a thinking model, the query's
final answer call returns empty `content` with `finish_reason=length`, which surfaces as
`OpenAI API Timeout Error` — while retrieval looks perfectly healthy. That is an LLM-tier
bug that reads like a retrieval bug. For llama.cpp-served models, serve a dedicated entry:

```
llama-server ... --n-predict 4096 --chat-template-kwargs '{"enable_thinking":false}'
```

**An empty answer is not an empty index.** `llm_generated: false` with no references
means the LLM or embedding tier is unreachable, not that retrieval found nothing. Check
`docs_stats` first — and note that ingestion completeness (`processed: N`) says nothing
about queryability.

**Indexing is graph extraction, not a vector write.** Budget roughly a minute per chunk
on a local model; a corpus stays queryable-but-partial while extraction runs.

## Development

```bash
uv venv && uv pip install -e '.[dev]'
ruff check .
pytest
```

## License

MIT