Documentation Search

mcp-docs-ask

用于文档的本地 RAG MCP。将 source 指向任意 Markdown 仓库 （本地路径或 Git URL）。

该服务仅负责检索（不使用回答大模型）。ask_docs 会返回有依据的 段落和引用；MCP 宿主（Cursor / Claude）负责综合生成答案。

功能

• 可将任意 Markdown 仓库作为来源：本地路径，或在 reindex 时获取的 Git URL
• 在本地运行：使用 sentence-transformers 生成嵌入，无需 API 密钥，也不使用回答大模型
• 基于路径的分层筛选搜索范围（例如指南与 API 参考）
• 返回完整段落，包含标题路径和 [n] 引用，并受字符数预算限制
• 无需手动重建：本地文件、配置或嵌入模型变更时，索引会自动刷新

要求

• Python 3.13+
• uv
• PATH 中需有 git（仅当 source 为 Git URL 时需要）
• 当 source 为私有 Git URL 时，机器上需配置 Git 凭据 （gh auth login、HTTPS 凭据助手或 SSH）。配置中无需填写令牌。
• 首次运行时会下载一次嵌入模型权重（sentence-transformers）

快速开始

git clone [email protected]: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

配置

配置路径：~/.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 是一个 git URL（ref 适用）。team-notes 是一个文件系统路径（不使用 ref）。 每个文档集合和层都可以使用可选的 desc，帮助 Agent 选择合适的目标。

embedding_model、top_k、chunk_max_chars 和 max_context_chars 的解析顺序为： docs.<id>.X → default.X → 内置值。省略各文档集合的键即可继承默认值。

嵌入模型推荐

任何可由 sentence-transformers 加载的 Hugging Face ID 均可使用。请根据语言组合选择：

文档 / 查询	推荐的 embedding_model
仅英语（省略时使用内置值）	sentence-transformers/all-MiniLM-L6-v2
仅中文	BAAI/bge-small-zh-v1.5
多语言（约 50 种语言）	sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

更改 embedding_model 后，下次调用时会重建索引；无需执行 reindex。

字段	描述
docs.<id>.source	文档仓库根目录：本地路径或 git URL
docs.<id>.desc	用于发现的简短描述（list_docs）
docs.<id>.ref	仅适用于 git URL 来源的分支 / 标签 / SHA（默认 main；本地路径会忽略此项）
docs.<id>.include	相对于仓库根目录的 Glob 模式（默认 **/*.md）
docs.<id>.exclude	要跳过的 Glob 模式
docs.<id>.layers.<name>.include	该层的路径 Glob 模式（以第一个匹配项为准）
docs.<id>.layers.<name>.desc	用于发现的简短层描述
docs.<id>.embedding_model	可选覆盖项（参见上方推荐）
docs.<id>.top_k	默认检索数量的可选覆盖项
docs.<id>.chunk_max_chars	每个标题分块的正文最大字符数的可选覆盖项
docs.<id>.max_context_chars	answer_context 段落预算的可选覆盖项
default.docs	默认文档集合 ID
default.embedding_model	默认 sentence-transformers 模型 ID
default.top_k	默认检索数量
default.chunk_max_chars	每个标题分块的正文最大字符数
default.max_context_chars	answer_context 中段落的默认总字符数（最小值为 500）

层按路径 Glob 模式划分已编入索引的文件。以第一个匹配项为准。名称不区分大小写；all 为保留名称（不能配置为层名称）。

ask_docs layer	含义
all（默认）	每个已编入索引的分块（命名层中的分块以及层外路径中的分块）
<named>	仅包含路径匹配该命名层 include Glob 模式的分块

未匹配任何命名层 Glob 模式的路径仍会编入索引，但只会出现在 layer=all 下。对于扁平仓库，省略 layers（或设置 "layers": {}）即可——使用 layer=all。

缓存布局：

• 仓库（git URL）：~/.cache/mcp-docs-ask/repos/<docs-id>/
• 索引：~/.cache/mcp-docs-ask/indexes/<docs-id>/

工具

工具	描述
list_docs	列出已配置的文档集合、层筛选条件和索引状态
ask_docs	检索有依据的段落 + 引文（layer：all 或某个命名层）
reindex	同步 git 来源（如果是 URL）并重建向量索引

list_docs 会返回一个 default 块，其中包含与配置 default 块相同的键（docs、embedding_model、top_k、chunk_max_chars、max_context_chars），以及一个 docs 列表。列表中的每个条目都包含解析后的值、一个 default 标志和一个 index 块（如果该集合从未编入索引，则为 null）。有效的 layer 值为 all 和命名层 ID — 参见上方的层。

索引块

list_docs 和 reindex 返回相同的 index 键：origin、root、rev、 files、chunks、layers。

origin 对应配置的来源：如果是文件系统路径，则为 file；如果是服务器克隆到 ~/.cache/mcp-docs-ask/repos/<docs-id>/ 并在 reindex 时获取的 URL，则为 git。root 是文件的实际位置——只有当已构建的索引比其来源目录存续得更久时才为 null。如果有 checkout HEAD，rev 就是该 HEAD，因此自身为 git 克隆的 file 来源也会报告一个 rev；其工作树可能包含未提交的编辑，因此 rev 标识的是 checkout，而非确切的索引内容。

ask_docs 仅携带两个与答案相关的键：root 和 rev，分别表示生成这些段落的 checkout，以及这些段落所对应的修订版本。

段落

ask_docs 最多检索 top_k 个块，然后将它们组装成段落：

• 每个段落都是完整的块文本，保留换行，并标注其标题路径（Guide > Configuration > Layers）。
• 同一个超大章节中检索到的部分会按文件顺序重新拼接；中间未排上名的部分以 … 标记。
• 段落按优先级顺序填充 max_context_chars。超出限制的段落会在换行处截断，并以 … 结尾；始终保留第一个段落。

因此，citations 中的条目数可能少于 top_k。

阅读完整的源文件

citations[].path 是相对于仓库的稳定路径；answer_context 按照与 citations[].n 匹配的 [n] 标记保存段落文本，且每段只保存一次。要读取完整的源文件， 请将同一 ask_docs 响应中的 index.root 与引用路径拼接：

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

请使用生成这些引用的响应中的 root，而不是较早一次 reindex 中的值—— ask_docs 会自行重建过期索引，因此其 rev 才与当前段落相匹配。

MCP 宿主示例

以下示例使用 uvx 启动服务，首次使用时会安装软件包。请先在终端中运行一次，避免宿主因安装而阻塞：

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

随后，服务会通过 stdio 启动并等待输入——看到安装提示行后按一次 Ctrl-C 即可。嵌入模型权重会在首次调用 ask_docs 或 reindex 时另行获取。uvx mcp-docs-ask --version 会打印 uvx 解析到的构建版本。

Linux（包括 WSL、容器和 CI）： Linux 上的 PyPI torch wheel 是 CUDA 构建版本。无论机器是否配备 NVIDIA GPU，它都会拉取约 15 个 nvidia-* 软件包——wheel 约占 2.7 GB，磁盘上约占 4 GB。Windows 和 macOS 会解析为 仅支持 CPU 的 wheel（约 1 GB），且不会下载 CUDA。预先完成缓存对此处尤为重要： 首次运行 uvx 预计需要几分钟，而非几毫秒。

Cursor

添加到 .cursor/mcp.json：

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

Claude Code

添加到 Claude Code MCP 配置中：

{
  "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"]
    }
  }
}

开发

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

备注

• 本地路径： 文件的修改时间或大小发生变化时，ask_docs 会自动重建索引（指纹检查）。编辑本地文档后无需运行 reindex。
• Git URL： ask_docs 不会获取更新。请调用 reindex，以对配置的 ref 执行 git fetch 并重建索引。
• 指纹还涵盖 embedding_model、chunk_max_chars、层级 glob 和磁盘上的索引格式，因此更改其中任何一项都会在下次调用时触发重建。