dryad-rag-mcp

A small Model Context Protocol server that exposes a RAG document-search API as agent-callable tools — rag_health, rag_ingest, and rag_query. It wraps 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

npm install
npm run build

Point it at a running dryad-rag-pipeline instance:

RAG_API_BASE_URL=http://127.0.0.1:8000 npm start

Add to Claude Code

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

Or in .mcp.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:

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

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.