# MCP

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

---

LLMS 索引： [llms.txt](/llms.txt)

---

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

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

## 前提 {#prerequisites}

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

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

## 添加配置 {#configure}

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

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

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

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

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

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

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

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

## 工具 {#tools}

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

`search_documentation` 的参数：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | string | 是 | 搜索文本，最多 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 | | 期望的搜索世代 |
{.fields meta="type required"}

`load_documentation_page` 的参数：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `section_key` | string | 是 | 搜索结果里的 `section_key` |
| `generation` | string | 是 | 同一次搜索返回的 `generation` |
| `offset` | integer | | 起始位置，按 Unicode 标量计数，默认 0 |
| `limit` | integer | | 最多返回的 Unicode 标量数，默认 16,000，最大 50,000 |
{.fields meta="type required"}

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

## 分页与搜索世代 {#paging}

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

## 安全与限制 {#security}

- 每次调用都重新读取 `api/status.json` 和 `api/access-key`，所以 API 换了端口也能找到。
- 发送密钥前，程序检查记录的进程仍在运行，并完成 [`/auth/challenge` 验证](/docs/integrations/local-api/#server-proof)；验证失败就不发送密钥，工具返回错误。
- 拒绝符号链接、权限不安全、所有者不对或有多个硬链接的发现文件。只连接与状态文件一致的 `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。

---

反链：

- [文档](/docs/)
- [本地 API](/docs/integrations/local-api/)
- [版本与别名](/docs/library/versions/)
- [用户数据与迁移](/docs/reference/data/)