# dryad-rag-mcp

A small [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes a
RAG document-search API as agent-callable tools — `rag_health`, `rag_ingest`, and
`rag_query`. It wraps [dryad-rag-pipeline](https://github.com/DryadAI/dryad-rag-pipeline),
so any MCP client (Claude Code, Claude Desktop, or your own client) can index and search
markdown docs through tool calls instead of hand-rolled HTTP glue.

## Why this exists

Most MCP server examples are toys that echo a string back. This one wraps a real, separately
running HTTP service and is proven against it: the test suite spins up the actual FastAPI
RAG service, spawns this server as a subprocess, connects a real MCP client over stdio, and
asserts the retrieved chunks are semantically correct — not just that the tool call didn't
crash.

## Tools

| Tool | Description |
|---|---|
| `rag_health` | Checks whether the RAG service is reachable. |
| `rag_ingest` | Re-indexes the configured document set. |
| `rag_query` | Searches the index; returns cited chunks with a similarity score. `question` (required), `top_k` (1-20, default 4). |

## Quickstart

```bash
npm install
npm run build
```

Point it at a running [dryad-rag-pipeline](https://github.com/DryadAI/dryad-rag-pipeline)
instance:

```bash
RAG_API_BASE_URL=http://127.0.0.1:8000 npm start
```

### Add to Claude Code

```bash
claude mcp add dryad-rag -- node /path/to/dryad-rag-mcp/dist/server.js
```

Or in `.mcp.json`:

```json
{
  "mcpServers": {
    "dryad-rag": {
      "command": "node",
      "args": ["/path/to/dryad-rag-mcp/dist/server.js"],
      "env": { "RAG_API_BASE_URL": "http://127.0.0.1:8000" }
    }
  }
}
```

## Running the tests

The test suite needs a checkout of `dryad-rag-pipeline` as a sibling directory (or set
`RAG_PIPELINE_DIR`), with its Python virtualenv already set up:

```bash
git clone https://github.com/DryadAI/dryad-rag-pipeline ../dryad-rag-pipeline
cd ../dryad-rag-pipeline && python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
cd ../dryad-rag-mcp

npm run build
npm test
```

This starts the real RAG API on a test port, spawns this MCP server as a subprocess,
connects an MCP `Client` over stdio, and exercises all three tools end to end — including
asserting that a health question actually retrieves the FAQ/API-reference chunks that
answer it, and that an out-of-range `top_k` is rejected.

## Architecture

```mermaid
sequenceDiagram
    participant Agent as MCP Client (e.g. Claude)
    participant Server as dryad-rag-mcp (stdio)
    participant API as dryad-rag-pipeline (HTTP)

    Agent->>Server: callTool("rag_ingest")
    Server->>API: POST /ingest
    API-->>Server: {documents_ingested, chunks_created}
    Server-->>Agent: "Indexed 3 document(s)..."

    Agent->>Server: callTool("rag_query", {question})
    Server->>API: POST /query
    API-->>Server: ranked, cited chunks
    Server-->>Agent: formatted, citable text
```

## License

MIT — see [LICENSE](LICENSE).