MCP

用随 App 附带的 CribMCP 程序，让支持 MCP 的编辑器和 AI 客户端搜索、读取 Crib 中的文档：配置方法、三个工具、分页和搜索世代规则。

Crib 随 App 附带一个 stdio MCP 程序 Crib.app/Contents/MacOS/CribMCP，不需要安装 Python、uv 或 Node。它通过本地 API 只读地搜索和读取已启用的文档。

还没有在真实客户端中走通

协议已用官方 Python SDK 和一个本地 stdio 客户端验证：工具列表、搜索、读取、分页、别名和错误路径都通过。但还没有在任何真实编辑器或 AI 客户端中完成端到端验收。VS Code 已识别配置并显示 Start，工具发现、搜索和读取尚未完成验证。

前提

Crib 正在运行。
“设置 → 集成”中已启用本地 API。

MCP 程序不会自动启动 Crib，也不会替你启用 API。条件不满足时，工具调用返回 local_api_unavailable 和一句说明。

添加配置

打开“设置 → 集成”，在“MCP”中把“客户端”选为“通用”或“VS Code”。
点“复制配置”，粘贴到客户端的 MCP 设置里；VS Code 粘贴到工作区的 .vscode/mcp.json。已有配置时只合并 crib 条目，保留其他服务器。
客户端用其他配置格式时，点“复制命令”，从中取可执行文件路径和参数。

复制的内容已经带好实际路径，不含访问密钥。注意：

JSON 里要写绝对路径，~ 不会被展开。
移动 Crib.app 或换用别的用户目录后，需要重新复制。
Crib 不会修改任何客户端的配置文件。
设置页显示“此版本不含 MCP 程序”时，说明这个构建没有附带 CribMCP。

安装在 /Applications、使用默认用户目录时，“通用”格式如下（<用户主目录> 换成实际路径）：

{
  "mcpServers": {
    "crib": {
      "command": "/Applications/Crib.app/Contents/MacOS/CribMCP",
      "args": ["--user-data", "<用户主目录>/Library/Application Support/Crib"]
    }
  }
}

“VS Code”格式用 servers，并带 "type": "stdio"：

{
  "servers": {
    "crib": {
      "type": "stdio",
      "command": "/Applications/Crib.app/Contents/MacOS/CribMCP",
      "args": ["--user-data", "<用户主目录>/Library/Application Support/Crib"]
    }
  }
}

不传 --user-data 时，程序使用当前用户的 ~/Library/Application Support/Crib。

工具

工具	作用
`list_installed_docsets`	列出已启用的资料包、版本、语言和当前搜索世代；可传入期望的 `generation`
`search_documentation`	在已启用的手册和 Wiki 中搜索
`load_documentation_page`	用搜索结果中的 `section_key` 和 `generation` 读取一个章节的纯文本

search_documentation 的参数：

text , string , required: 搜索文本，最多 256 个字符；支持 Crib 的过滤语法和 PG96: SELECT 这类版本前缀，文本中的过滤优先
project , string: 默认 postgresql
branch , string: 版本线，如 18、9.6；默认 18，* 表示所有已启用版本
locale , string: zh-Hans 或 en；默认简体中文，* 表示所有语言
domain , string: 文档领域
collection , string: Wiki 集合
limit , integer: 每页条数，1–50，默认 20
offset , integer: 偏移，0–10000
generation , string: 期望的搜索世代

load_documentation_page 的参数：

section_key , string , required: 搜索结果里的 section_key
generation , string , required: 同一次搜索返回的 generation
offset , integer: 起始位置，按 Unicode 标量计数，默认 0
limit , integer: 最多返回的 Unicode 标量数，默认 16,000，最大 50,000

每个工具同时返回 JSON structuredContent 和等价的文本内容。

分页与搜索世代

搜索结果用 has_more 和 next_offset 翻页。timed_out、cancelled、candidate_truncated 为真时结果不完整。
读取章节时跟随 next_offset，直到它为 null。
搜索和列表都返回 generation。启用、停用或更新资料包后搜索世代会变，旧坐标的读取返回 generation_changed 错误；重新搜索，用新的 section_key 和 generation 再读。

安全与限制

每次调用都重新读取 api/status.json 和 api/access-key，所以 API 换了端口也能找到。
发送密钥前，程序检查记录的进程仍在运行，并完成 /auth/challenge 验证；验证失败就不发送密钥，工具返回错误。
拒绝符号链接、权限不安全、所有者不对或有多个硬链接的发现文件。只连接与状态文件一致的 127.0.0.1 地址和非特权端口；不走代理，不跟随重定向，不保存 cookie。单次请求 8 秒截止，响应最大 4 MiB。
工具只读文档：不包含个人资料，不能下载资料包、控制窗口或读取任意 URL。
每行一条 JSON-RPC 消息，单行最多 256 KiB，最多同时处理 8 个文档请求。标准输入关闭后取消全部请求并退出。
支持 MCP 2026-07-28 的 stdio 传输，以及 2025-11-25、2025-06-18、2025-03-26、2024-11-05 的 initialize 握手；后两个版本没有用真实 SDK 客户端验证过。不提供 resources、prompts 和 sampling。

工具名称参照 Dash 的官方 MCP 适配器，参数和结果遵循 Crib 自己的约定：读取用 section_key 加 generation，不接受 Dash 的 load_url。依赖 Dash 全部工具的客户端不能直接换成 Crib。