mcp-docs-ask

Local RAG MCP for documentation. Point source at any markdown repository (local path or git URL).

The server does retrieval only (no answer LLM). ask_docs returns grounded passages and citations; the MCP host (Cursor / Claude) synthesizes the answer.

Features

• ask_docs retrieval with configurable path-based layer filters
• list_docs discovery for configured docs collections and layer filters
• reindex rebuilds the local vector index; for git URL sources it also fetches updates

Requirements

• Python 3.13+
• uv
• git on PATH (only if source is a git URL)
• Git credentials on the machine when source is a private git URL (gh auth login, HTTPS credential helper, or SSH). No tokens in config.
• First run downloads the embedding model weights once (sentence-transformers)

Quick start

git clone git@github.com:alyiox/mcp-docs-ask.git
cd mcp-docs-ask
uv sync
mkdir -p ~/.config/mcp-docs-ask
cp config.example.json ~/.config/mcp-docs-ask/config.json
# Prefer a local checkout while developing:
#   set docs.<id>.source to your docs repo path
npx -y @modelcontextprotocol/inspector uv run mcp-docs-ask

Configuration

Config path: ~/.config/mcp-docs-ask/config.json

Windows: %USERPROFILE%\.config\mcp-docs-ask\config.json

{
  "docs": {
    "product": {
      "source": "https://github.com/example/docs.git",
      "desc": "Product guides and API reference",
      "ref": "main",
      "include": ["**/*.md"],
      "exclude": ["archive/**"],
      "layers": {
        "guides": {
          "desc": "How-to and onboarding guides",
          "include": ["docs/guides/**"]
        },
        "api": {
          "desc": "HTTP API reference",
          "include": ["docs/api/**"]
        }
      },
      "embedding_model": "sentence-transformers/all-MiniLM-L6-v2"
    },
    "team-notes": {
      "source": "/path/to/docs",
      "desc": "Internal team notes (local path; ref unused)",
      "include": ["**/*.md"],
      "exclude": ["archive/**"]
    }
  },
  "default": {
    "docs": "product",
    "embedding_model": "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
    "top_k": 8,
    "chunk_max_chars": 1500
  }
}

product is a git URL (ref applies). team-notes is a filesystem path (ref unused). Optional desc on each docs collection and layer helps agents pick the right target.

embedding_model, top_k, and chunk_max_chars resolve as: docs.<id>.X → default.X → built-in. Omit per-docs keys to inherit.

Embedding model recommendation

Any Hugging Face id loadable by sentence-transformers works. Pick by language mix:

Changing embedding_model requires a reindex (the on-disk index stores the model name).

Layers partition indexed files by path glob. First match wins. Names are case-insensitive; all is reserved (cannot be configured as a layer name).

Paths that match no named-layer glob are still indexed and only appear under layer=all. Omit layers (or set "layers": {}) for flat repos — use layer=all.

Cache layout:

• Repos (git URL): ~/.cache/mcp-docs-ask/repos/<docs-id>/
• Indexes: ~/.cache/mcp-docs-ask/indexes/<docs-id>/

Tools

list_docs returns a default block with the same keys as the config default block (docs, embedding_model, top_k, chunk_max_chars), plus a docs list where each entry carries its resolved values and a default flag. layer_filters is all plus named layer ids — see Layers above.

MCP host examples

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "docs-ask": {
      "command": "uvx",
      "args": ["mcp-docs-ask"]
    }
  }
}

Claude Code

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "docs-ask": {
      "command": "uvx",
      "args": ["mcp-docs-ask"]
    }
  }
}

Codex

[mcp_servers.docs-ask]
command = "uvx"
args = ["mcp-docs-ask"]

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docs-ask": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "mcp-docs-ask"]
    }
  }
}

GitHub Copilot

{
  "inputs": [],
  "servers": {
    "docs-ask": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-docs-ask"]
    }
  }
}

Development

uv sync
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run pyright
uv run pytest

Notes

• Local path: ask_docs rebuilds the index automatically when file mtimes/sizes change (fingerprint check). You do not need reindex after editing local docs.
• Git URL: ask_docs never fetches. Call reindex to git fetch the configured ref and rebuild.
• Changing embedding_model invalidates the on-disk index (rebuild on next use / reindex).