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).

... View full README on GitHub