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

• Any markdown repo as a source: a local path, or a git URL fetched on reindex
• Runs locally: sentence-transformers embeddings, no API keys, no answer LLM
• Path-based layers to narrow a search (e.g. guides vs. API reference)
• Full passages with heading paths and [n] citations, capped by a character budget
• No manual rebuilds: the index refreshes itself when local files, config, or the embedding model change

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@latest 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,
    "max_context_chars": 8000
  }
}

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, chunk_max_chars, and max_context_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:

Docs / queries	Recommended embedding_model
English-only (built-in when omitted)	sentence-transformers/all-MiniLM-L6-v2
Chinese-only	BAAI/bge-small-zh-v1.5
Multilingual (~50 langs)	sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

Changing embedding_model rebuilds the index on the next call; no reindex needed.

Field	Description
docs.<id>.source	Docs repo root: local path or git URL
docs.<id>.desc	Short description for discovery (list_docs)
docs.<id>.ref	Branch / tag / SHA for git URL sources only (default main; ignored for local paths)
docs.<id>.include	Globs relative to repo root (default **/*.md)
docs.<id>.exclude	Globs to skip
docs.<id>.layers.<name>.include	Path globs for that layer (first match wins)
docs.<id>.layers.<name>.desc	Short layer description for discovery
docs.<id>.embedding_model	Optional override (see recommendation above)
docs.<id>.top_k	Optional override for default retrieval count
docs.<id>.chunk_max_chars	Optional override for max body chars per heading chunk
docs.<id>.max_context_chars	Optional override for the answer_context passage budget
default.docs	Default docs collection id
default.embedding_model	Default sentence-transformers model id
default.top_k	Default retrieval count
default.chunk_max_chars	Default max body chars per heading chunk
default.max_context_chars	Default total passage chars in answer_context (min 500)

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

ask_docs layer	Meaning
all (default)	Every indexed chunk (named layers and paths outside them)
<named>	Only chunks whose path matched that named layer’s include globs

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

Tool	Description
list_docs	List configured docs collections, layer filters, and index state
ask_docs	Retrieve grounded passages + citations (layer: all or a named layer)
reindex	Sync git source (if URL) and rebuild the vector index

list_docs returns a default block with the same keys as the config default block (docs, embedding_model, top_k, chunk_max_chars, max_context_chars), plus a docs list where each entry carries its resolved values, a default flag, and an index block (null when the collection has never been indexed). Valid layer values are all plus the named layer ids — see Layers above.

Index block

list_docs and reindex return the same index keys: origin, root, rev, files, chunks, layers.

origin mirrors the configured source: file for a filesystem path, git for a URL the server clones into ~/.cache/mcp-docs-ask/repos/<docs-id>/ and fetches on reindex. root is where the files actually are — null only when a built index outlived its source directory. rev is the checkout HEAD when there is one, so a file source that is itself a git clone still reports one; its working tree may hold uncommitted edits, so rev labels the checkout, not the exact indexed content.

ask_docs carries only the two answer-scoped keys, root and rev: the checkout that produced the passages, and the revision they came from.

Passages

ask_docs retrieves up to top_k chunks, then assembles them into passages:

• Each passage is the full chunk text, with line breaks kept, labeled with its heading path (Guide > Configuration > Layers).
• Retrieved parts of one oversized section are joined back in file order; … marks parts in between that did not rank.
• Passages fill max_context_chars best-first. The one that overflows is trimmed at a line break and ends with …; the first passage is always kept.

So citations can hold fewer entries than top_k.

Reading a full source file

citations[].path is repo-relative and stable; answer_context holds the passage text once, keyed by the [n] markers that match citations[].n. To read a whole source file, join index.root from the same ask_docs response with a citation path:

/home/you/docs-repo  +  product/features/budget.md

Take root from the response that produced the citations rather than an earlier reindex — ask_docs rebuilds a stale index itself, so its rev is the one that matches the passages in hand.

MCP host examples

The examples below launch the server with uvx, which installs the package on first use. Run it once in a terminal beforehand so your host does not block on that install:

$ uvx mcp-docs-ask
Installed 84 packages in 275ms

The server then starts on stdio and waits for input — press Ctrl-C once you see the install line. Embedding model weights are fetched separately, on the first ask_docs or reindex call. uvx mcp-docs-ask --version prints the build uvx resolved.

Linux (including WSL, containers, and CI): the PyPI torch wheel for Linux is the CUDA build. It pulls ~15 nvidia-* packages whether or not the machine has an NVIDIA GPU — about 2.7 GB of wheels and ~4 GB on disk. Windows and macOS resolve to a CPU-only wheel (~1 GB) and never download CUDA. Pre-warming matters most here: expect the first uvx run to take minutes, not milliseconds.

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.
• The fingerprint also covers embedding_model, chunk_max_chars, layer globs, and the on-disk index format, so changing any of them rebuilds on the next call.