内容
# Pear 文档 MCP 服务器
一个 [模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，公开了完整的 **Pear by Holepunch** 文档（[docs.pears.com](https://docs.pears.com)），供 AI 代理和兼容 MCP 的客户端使用。
它允许助手直接浏览、搜索和阅读 Pear 文档，而无需依赖记忆或过时的信息。整个文档集被快照到一个本地 JSON 文件中，因此服务器可以完全离线运行，并在无需网络往返的情况下回答每个请求。
---
## 目录
- [概述](#概述)
- [为什么存在](#为什么存在)
- [架构](#架构)
- [工作原理](#工作原理)
- [工具](#工具)
- [安装](#安装)
- [注册到 MCP 客户端](#注册到-mcp-客户端)
- [使用示例](#使用示例)
- [更新文档快照](#更新文档快照)
- [项目结构](#项目结构)
- [开发和测试](#开发和测试)
- [数据快照格式](#数据快照格式)
- [故障排除](#故障排除)
- [许可证](#许可证)
---
## 概述
Pear 是 Holepunch 的对等运行时和部署平台，基于 Bare 运行时和 Hypercore 生态系统（Hyperswarm、HyperDHT、Hyperbee、Hyperdrive、Autobase 等）。其文档涵盖了 100 多页的概念解释、操作方法指南和 API 参考。
该项目将这些文档作为 MCP 服务器打包。注册到诸如 Claude Code 或 Claude Desktop 之类的客户端后，助手可以按需调用三个工具来探索文档，而无需依赖记忆或过时的信息。
| 属性 | 值 |
| --- | --- |
| 文档页数 | 123 |
| 章节 | 概述、解释、入门、操作方法、参考 |
| 快照大小 | 约 1.2 MB 的 Markdown |
| 传输 | stdio（标准输入/输出） |
| 运行时 | Node.js 18 或更新版本 |
| 运行时网络 | 无；内容从本地快照提供 |
---
## 为什么存在
- **准确性**。答案来自当前的权威文档，而不是模型回忆，这减少了虚构的 API 和过时的指导。
- **速度**。文档本地捆绑，因此查找是即时的，并且可以在离线状态下工作。
- **焦点**。代理可以检索相关页面，而无需将整个文档集加载到其上下文窗口中。
- **可重复性**。快照是一个提交的工件，因此每个存储库用户在有意刷新之前查询相同的内容。
---
## 架构
系统有两个独立的部分：一个离线的 **构建管道**，用于生成文档快照，以及一个 **运行时服务器**，用于通过 MCP 提供该快照。
```mermaid
flowchart TB
subgraph Build["构建管道（偶尔运行）"]
direction TB
SITE["docs.pears.com"]
FETCH["scripts/fetch-docs.mjs"]
SNAP["data/docs.json<br/>(提交的快照)"]
SITE -->|sitemap.xml, 每页 .md, llms.txt| FETCH
FETCH -->|规范化和捆绑| SNAP
end
subgraph Runtime["运行时服务器（每个会话）"]
direction TB
SERVER["src/index.js<br/>MCP 服务器"]
TOOLS["list_docs / search_docs / get_doc"]
SERVER --> TOOLS
end
subgraph Clients["MCP 客户端"]
direction TB
CC["Claude Code"]
CD["Claude Desktop"]
OTHER["任何兼容 MCP 的客户端"]
end
SNAP -->|启动时加载| SERVER
CC -->|stdio| SERVER
CD -->|stdio| SERVER
OTHER -->|stdio| SERVER
```
---
## 工作原理
### 构建管道
文档站点对机器消费非常友好，获取脚本依赖于其三个端点：
1. `sitemap.xml` 提供了每个文档 URL 的规范列表。
2. 每个页面通过在其路径后附加 `.md` 来公开干净的 Markdown 版本（例如，`/explanation/workers` 可在 `/explanation/workers.md` 处获得）。
3. `llms.txt` 为每个页面提供了一行描述。
脚本将这些源合并成一个规范化的 `data/docs.json` 文件。
```mermaid
sequenceDiagram
participant S as fetch-docs.mjs
participant D as docs.pears.com
S->>D: GET /sitemap.xml
D-->>S: 123 个页面 URL 的列表
S->>D: GET /llms.txt
D-->>S: 每个页面的单行描述
loop 每个页面（6 个并发）
S->>D: GET {page}.md
D-->>S: 干净的 Markdown 内容
end
S->>S: 规范化路径，附加标题<br/>和描述，按章节分组
S->>S: 写入 data/docs.json
```
### 运行时服务器
服务器在启动时将 `data/docs.json` 加载到内存中，构建路径索引和章节列表，并在 MCP 的 `stdio` 传输上注册三个工具。从那时起，它完全从内存中回答工具调用。
```mermaid
sequenceDiagram
participant C as MCP 客户端
participant S as Pear Docs MCP 服务器
participant M as 内存快照
Note over S,M: 启动时，将 data/docs.json 加载到内存中
C->>S: 初始化
S-->>C: 服务器信息和功能
C->>S: 工具/列表
S-->>C: list_docs, search_docs, get_doc
C->>S: 工具/调用 search_docs { 查询: "hyperswarm 主题" }
S->>M: 评分和排名页面
M-->>S: 顶部匹配项和片段
S-->>C: 排名结果和路径
C->>S: 工具/调用 get_doc { 路径: "/reference/building-blocks/hyperswarm" }
S->>M: 解析路径
M-->>S: 完整页面 Markdown
S-->>C: 页面内容
```
### 搜索排名
`search_docs` 使用轻量级加权评分模型，而不是全文搜索引擎。每个查询项根据其出现位置为页面的评分做出贡献：
| 匹配位置 | 每个术语的权重 |
| --- | --- |
| 标题 | 10 |
| 路径 | 6 |
| 描述 | 4 |
| 正文 | 每个出现 1，最高 8 |
| 标题中的确切短语 | 15（奖励） |
| 正文中的确切短语 | 5（奖励） |
评分为零的页面被排除，其余页面按相关性降序返回。这使得服务器依赖轻量级，同时仍然显示最相关的页面。
---
## 工具
服务器公开了三个工具。典型的流程是使用 `search_docs` 定位相关页面，然后使用 `get_doc` 读取全文。使用 `list_docs` 可以系统地浏览某个章节。
### `list_docs`
浏览文档目录。
| 参数 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `section` | 枚举 | 否 | 限制在某一章节：`overview`、`explanation`、`getting-started`、`how-to`、`reference`。 |
| `filter` | 字符串 | 否 | 标题、路径和描述中匹配的不区分大小写的子字符串。 |
返回按章节分组的匹配页面，每个页面都有其路径、标题和描述。
### `search_docs`
对每个页面进行全文、相关性排序的搜索。
| 参数 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `query` | 字符串 | 是 | 搜索词，例如 `hyperswarm 主题发现` 或 `OTA 更新`。 |
| `section` | 枚举 | 否 | 限制结果在单个章节内。 |
| `limit` | 整数 | 否 | 最大结果数（1 至 25，默认 8）。 |
返回排名结果，每个结果包含页面标题、路径、章节、相关性评分和显示匹配上下文的片段。
### `get_doc`
检索单个页面的完整 Markdown 内容。
| 参数 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `path` | 字符串 | 是 | 页面路径（`/explanation/workers`）、裸 slug（`workers`）或完整 docs URL。 |
路径解析接受精确路径、带有唯一后缀匹配的裸 slug 和完整的 `docs.pears.com` URL。当找不到页面时，工具建议接近的匹配项。
---
## 安装
### 先决条件
- Node.js 18 或更新版本
- npm
### 步骤
```bash
# 1. 安装依赖
npm install
# 2. 生成文档快照（data/docs.json）。
# 存储库中已包含快照，因此仅在文件丢失或您想要最新内容时才需要此步骤。
npm run fetch
# 3. （可选）直接运行服务器以确认其启动
npm start
```
启动后，服务器将就绪行打印到标准错误，然后等待标准输入上的 MCP 消息。这是预期的；服务器通过 stdio 进行通信，通常由 MCP 客户端启动，而不是交互式运行。
---
## 注册到 MCP 客户端
将下面的路径替换为您的机器上 `src/index.js` 的绝对路径。
### Claude Code
为当前项目注册服务器：
```bash
claude mcp add pear-docs -- node /绝对路径/到/pear_tool/src/index.js
```
全局注册，以便在每个项目中都可用：
```bash
claude mcp add -s user pear-docs -- node /绝对路径/到/pear_tool/src/index.js
```
验证注册和健康状况：
```bash
claude mcp list
```
服务器应显示为 `pear-docs`，状态为 `Connected`。工具在会话开始时加载，因此请在注册后打开新的 Claude Code 会话。
### Claude Desktop 和其他客户端
在客户端的 `mcpServers` 配置中添加一个条目：
```json
{
"mcpServers": {
"pear-docs": {
"command": "node",
"args": ["/绝对路径/到/pear_tool/src/index.js"]
}
}
}
```
---
## 使用示例
注册后，助手可以自然地调用工具。以下示例显示了工具名称和参数，以及结果描述。
浏览 Hypercore 相关模块的参考章节：
```json
list_docs { "section": "reference", "filter": "hyper" }
```
搜索有关连接对等方的指导：
```json
search_docs { "query": "通过公共密钥打孔连接两个对等方", "limit": 3 }
```
使用裸 slug 读取特定页面：
```json
get_doc { "path": "workers" }
```
使用完整路径读取页面：
```json
get_doc { "path": "/reference/building-blocks/hyperswarm" }
```
---
## 更新文档快照
上游文档会随着时间的推移而发生变化。要刷新本地快照：
```bash
npm run refresh
```
这重新运行获取管道并用最新内容覆盖 `data/docs.json`。提交更新的文件以将新快照发布给使用存储库的任何人。快照记录了一个 `generatedAt` 时间戳，因此您可以知道它是什么时候更新的。
---
## 项目结构
```
pear_tool/
├── src/
│ └── index.js MCP 服务器：加载快照并注册三个工具
├── scripts/
│ ├── fetch-docs.mjs 构建管道：捕获 docs.pears.com 进入 data/docs.json
│ └── smoke-test.mjs 最小的 stdio MCP 客户端，测试所有三个工具
├── data/
│ └── docs.json 提交的文档快照（生成）
├── package.json 包元数据、依赖项和脚本
├── README.md 本文档
└── .gitignore
```
---
## 开发和测试
一个自包含的烟雾测试执行完整的 MCP 握手并调用每个工具，这是确认服务器在更改后工作的最快方法：
```bash
node scripts/smoke-test.mjs
```
脚本生成服务器，发送 `initialize` 和 `tools/list`，然后调用 `list_docs`、`search_docs` 和 `get_doc`（包括故意丢失以验证错误处理），并打印每个响应的摘要。
### npm 脚本
| 脚本 | 描述 |
| --- | --- |
| `npm start` | 在 stdio 上运行 MCP 服务器。 |
| `npm run fetch` | 构建文档快照到 `data/docs.json`。 |
| `npm run refresh` | `fetch` 的别名；重新生成快照。 |
### 依赖项
- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)：官方 MCP 服务器实现和 stdio 传输。
- [`zod`](https://www.npmjs.com/package/zod)：用于工具输入验证的模式定义。
---
## 数据快照格式
`data/docs.json` 是一个具有顶级元数据和 `pages` 数组的单个 JSON 对象：
```json
{
"source": "https://docs.pears.com",
"generatedAt": "2026-07-03T18:23:42.524Z",
"count": 123,
"pages": [
{
"path": "/explanation/workers",
"url": "https://docs.pears.com/explanation/workers/",
"title": "Workers",
"section": "explanation",
"description": "为什么 Pear 应用程序的对等逻辑在一个 Bare 工作线程中...",
"content": "# Workers\n\n...完整 Markdown...",
"chars": 13048,
"ok": true
}
]
}
```
| 字段 | 描述 |
| --- | --- |
| `source` | 快照获取来源。 |
| `generatedAt` | 快照生成的 ISO 8601 时间戳。 |
| `count` | 包含的页面数量。 |
| `path` | 规范化的页面路径，用作主要标识符。 |
| `url` | 页面的规范文档 URL。 |
| `title` | 从 `llms.txt` 或第一个标题获取的页面标题。 |
| `section` | 从路径派生的顶级章节。 |
| `description` | 来自 `llms.txt` 的单行摘要。 |
| `content` | 页面的完整内容为 Markdown。 |
| `chars` | 内容的字符数。 |
---
## 故障排除
**服务器立即退出，并显示有关 `data/docs.json` 的消息。**
快照丢失。运行 `npm run fetch` 以生成它。
**客户端显示服务器已失败或未连接。**
确认客户端配置中的路径是绝对的，并且指向 `src/index.js`，并且已运行 `npm install` 以确保存在依赖项。运行 `node scripts/smoke-test.mjs` 以隔离测试服务器。
**工具已注册，但在辅助程序中不可用。**
MCP 工具在会话开始时加载。在注册服务器后启动新会话。
**搜索返回无结果。**
尝试更广泛或更少的术语，或使用 `list_docs` 直接浏览某个部分。搜索将整个术语与标题、路径、描述和正文进行匹配。
---
## 归属和内容来源
本项目是一个独立的非官方工具。它与 Holepunch 或 Pear 项目无关、未获得其认可或赞助。
`data/docs.json` 中捆绑的文档内容从官方 Pear 文档 [docs.pears.com](https://docs.pears.com) 检索，并仍为其各自所有者（Holepunch）的财产。该内容在此重新分发，仅用于通过模型上下文协议使文档可查询，其版权和条款为原始发布者所有。请参阅 [pears.com](https://pears.com) 和 [holepunch.to](https://holepunch.to) 以获取权威来源。
下面的 MIT 许可证仅适用于此存储库中的原始代码（服务器、脚本和配置），不适用于捆绑的文档内容。如果您打算重新分发快照，请先查看上游文档的条款，或者使用 `npm run fetch` 从源重新生成。
## 许可证
存储库中的源代码在 MIT 许可证下发布。有关完整文本，请参见 [LICENSE.md](LICENSE.md)。
