内容
以下是翻译后的文档：
# 工具列表
为 Claude、Cursor 和任何与 MCP 兼容的 AI 助手提供可查询的最新技术文档访问权限。该 Apify Actor 运行一个持久的 MCP 服务器，索引文档站点，通过模型上下文协议公开搜索和获取工具，并缓存页面以实现快速后续查询。
自带五个可立即使用的模板（Next.js、Tailwind CSS、React、TypeScript、Prisma）。通过提供 URL 和 CSS 内容选择器，可以在无需代码更改的情况下，为任何文档站点进行 fork。
## 适用对象
- **使用 AI 编程助手** 的开发者，他们希望获得基于 *当前* 文档的答案，而不是可能已经过时的训练数据快照
- **拥有内部文档** 的团队，他们希望 AI 工具能够根据自己的文档回答问题，而不仅仅是公共来源
- **MCP 构建者**，他们希望拥有一个可用的 Standby 模式参考实现来进行 fork
## 功能
- 启动时爬取和索引最多 10 个文档源
- 通过 JSON-RPC 在持久的 HTTP 端点上公开四个 MCP 工具
- 将获取的页面缓存在 LRU 缓存（默认为 50）中，以便重复查询能够立即返回
- 默认情况下，以干净的 markdown 格式返回内容，或在请求时返回原始文本
## 用例
- **保持 AI 助手更新**。将 Next.js、React 或 TypeScript 文档指向 Claude 或 Cursor，以便它们从今天的 API 表面回答问题，而不是几个月前的训练快照。
- **查询团队内部文档**。索引私有或内部文档站点（任何静态 HTML），让 AI 工具根据您自己的源回答问题，而不仅仅是公共源。
- **无 RAG 的文档层**。为 AI 代理提供可搜索、可获取的文档，而无需建立向量存储、嵌入管道或重新索引作业 — 关键字搜索超过实时页面。
- **将其 fork 为 MCP 参考实现**。运送您自己的 Standby 模式 MCP 服务器？从这里开始 — 索引、缓存和 JSON-RPC 连接已经完成。
## 输入
| 字段 | 类型 | 默认值 | 备注 |
| --- | --- | --- | --- |
| `sources` | 数组（1-10） | 必需 | 每个源需要一个 `name` 加上一个 `template` ID 或自定义 `url` + `contentSelector`。可选 `sitemapUrl`。 |
| `maxPagesPerSource` | 整数（1-500） | 200 | 每个源启动时索引的页面数量上限。降低此值可加快大型文档站点的启动速度。 |
| `cacheMaxPages` | 整数（1-200） | 50 | 所有源共享的 LRU 页面缓存。提高此值如果您反复查询相同的页面。 |
| `markdownOutput` | 布尔值 | `true` | 将提取的页面 HTML 转换为 markdown。设置为 `false` 以返回原始文本。 |
### 精选模板
`nextjs`、`tailwind`、`react`、`typescript`、`prisma`
### 自定义源示例
```json
{
"sources": [
{ "name": "Apify SDK", "url": "https://docs.apify.com/sdk/js", "contentSelector": "main article" }
]
}
```
## MCP 工具
| 工具 | 目的 | 必需参数 |
| --- | --- | --- |
| `list_sources` | 列出已配置的源及其页面数量 | — |
| `get_toc` | 返回源的页面索引（目录） | `source` |
| `search_docs` | 标题和缓存内容的大小写不敏感关键字搜索 | `query`（可选：`source`、`maxResults` ≤ 30） |
| `get_page` | 获取完整页面内容；首先检查 LRU 缓存 | `url` |
### 工具调用示例
```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "list_sources", "arguments": {} } }
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": { "name": "search_docs",
"arguments": { "query": "server actions", "source": "Next.js Docs", "maxResults": 5 } } }
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": { "name": "get_page",
"arguments": { "url": "https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions" } } }
```
### 工具输出示例
每个工具都在标准 MCP `result.content[].text` 信封内返回 JSON。内部有效载荷如下所示：
`search_docs` →
```json
{
"query": "server actions",
"source": "Next.js Docs",
"results": [
{
"title": "Server Actions and Mutations",
"url": "https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions",
"source": "Next.js Docs",
"snippet": "Server Actions are asynchronous functions executed on the server…",
"matchType": "content"
}
]
}
```
`get_page` → 以 markdown 格式的页面内容（或 `markdownOutput` 为 `false` 时为原始文本）：
```json
{
"url": "https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions",
"title": "Server Actions and Mutations",
"source": "Next.js Docs",
"content": "# Server Actions and Mutations\n\nServer Actions are asynchronous functions…",
"cachedAt": "2026-05-30T12:00:00.000Z"
}
```
`list_sources` → `{ "sources": [{ "name": "Next.js Docs", "url": "https://nextjs.org/docs", "pageCount": 200 }] }`
## 工作原理
1. **启动：** `Actor.init()`，验证输入，解析任何精选模板
2. **索引：** 对于每个源，获取站点地图（或从入口 URL 发现），上限为 `maxPagesPerSource`，并构建页面索引（`url` + `title`）
3. **服务：** 在 `ACTOR_STANDBY_PORT`（默认为 `4321`）上启动 HTTP 服务器；接受带有 JSON-RPC MCP 消息的 POST 请求
4. **缓存：** `get_page` 在可用时返回缓存内容；如果未命中，则获取，提取（通过源的 `contentSelector`），可选地转换为 markdown，并存储在 LRU 中
5. **搜索：** `search_docs` 扫描所有源索引中的页面标题和 LRU 缓存中的内容 — 不会预先索引页面正文；通过调用 `get_page` 预热缓存，以便使您想要的页面可搜索
## 在 Apify 上运行
该 Actor 在 **Standby 模式** 下运行 — 一个持久的 HTTP 服务器，而不是批处理作业。在部署后，通过 Apify 暴露的 Standby URL 连接 MCP 客户端。服务器在索引完成后启动；在发送请求之前，在运行日志中查找 `MCP server listening.`。
在 Apify 上运行还意味着该平台的优势是免费的：**调度** 按需重新索引，**监控和警报** 服务器健康状况，**API 访问** 每个运行，**集成** 与您的堆栈的其他部分 — 这些都不是您自己托管文档服务器所能获得的。
## 定价
该 Actor 在 Standby 模式下运行，因此它会根据服务器处于活动状态的 **计算时间** 计费 — 没有按结果计费。由于 Standby **在空闲时缩减为零**，您只需在实际提供 MCP 请求时付费（加上一个短暂的保持活动窗口），而不是全天候付费。
- **索引在启动时发生一次**，然后查询从内存页面索引和 LRU 缓存中回答 — 因此，即使频繁使用，稳定状态成本仍然保持较低。
- **降低 `maxPagesPerSource`** 以加快大型文档站点的启动速度；**提高 `cacheMaxPages`** 如果您反复查询相同的页面。
- 在 **Apify 免费层** 上试用，查看您的源的实际计算使用情况，然后再提交计划。
查看 Actor 详细页面上的 **定价** 部分以获取当前费率。
## 连接您的 AI 助手
该 Actor 通过 JSON-RPC 在其 Standby URL 上使用 MCP。获取 Apify 控制台中 Actor 的 **Standby** 选项卡中的确切 URL 和访问令牌。
### Claude Desktop / Cursor（stdio 客户端）
大多数桌面 MCP 客户端都使用 stdio，因此使用 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) 桥接到远程 HTTP 端点。将以下内容添加到您的 MCP 配置中 — `claude_desktop_config.json`（适用于 Claude Desktop）或您的 Cursor MCP 设置：
```json
{
"mcpServers": {
"docs": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://<your-standby-url>.apify.actor?token=<APIFY_TOKEN>"
]
}
}
}
```
用 Standby 选项卡中的值替换 `<your-standby-url>` 和 `<APIFY_TOKEN>`。（如果您的客户端支持自定义标头，也可以将令牌作为 `Authorization: Bearer` 标头发送。）
### HTTP / 流式 MCP 客户端
能够通过 HTTP 使用 MCP 的客户端可以直接指向 Standby URL，并根据其身份验证设置提供 Apify 令牌。连接后，四个工具 — `list_sources`、`get_toc`、`search_docs`、`get_page` — 自动出现。
## 设计选择（v1）
- **关键词搜索，而不是向量**。无需嵌入成本，无需维护向量存储，行为可预测。适用于文档查找的术语精确的场景。
- **仅静态 HTTP 获取**。适用于任何由静态生成器提供的文档站点（Hugo、Next.js 静态导出、Docusaurus、WordPress、MkDocs 等）。需要 JS 执行或位于机器人挑战（Cloudflare、登录墙）后面的站点将无法索引 — 而是选择底层静态源。
- **搜索读取缓存正文；未缓存页面与标题匹配**。通过调用 `get_page` 预热缓存，以便使您想要的页面可全文搜索。
- **上限**。最多 10 个源，500 个页面/源，200 个页面/缓存。
## 常见问题
**如何将其连接到 Claude Desktop 或 Cursor？**
参见 [连接您的 AI 助手](#connect-your-ai-assistant)。桌面客户端使用 `mcp-remote` 桥接到 Standby URL；支持 HTTP 的客户端直接指向 URL。
**它是否适用于私有或内部文档？**
是的 — 任何静态 HTML 文档站点都可以通过 HTTP 访问。提供 `url` + `contentSelector` 代替精选模板。位于登录墙或机器人挑战（Cloudflare、身份验证门）后面的站点将无法索引；指向底层静态源。
**它与向量 RAG 管道有何不同？**
无需嵌入，无需向量存储。它在页面标题和缓存的页面正文中运行关键词搜索 — 因此没有嵌入成本，结果可预测且可调试。对于文档术语已经精确的场景，这是一个合适的选择。对于跨大批量语料库的模糊语义召回，向量方法可能更适合您。
**哪些文档站点开箱即用？**
五个精选模板：Next.js、Tailwind CSS、React、TypeScript 和 Prisma。其他静态文档站点通过自定义 `url` + `contentSelector` 工作。
**为什么搜索会错过某些页面？**
`search_docs` 匹配所有索引页面的标题，但全文匹配仅涵盖已缓存的页面。通过调用 `get_page` 预热缓存，以便使您想要的页面可全文搜索（参见 [工作原理](#how-it-works)）。
**它是否支持 JavaScript 渲染的文档？**
否 — v1 仅使用静态 HTTP 获取。JS 渲染或机器人挑战的站点将无法索引；使用底层静态源代替。
## 本地开发
```bash
npm install
npm test # 流水线、缓存、索引器、提取器、mcp、搜索引擎、站点地图套件
apify run # 本地 Standby — 服务器监听 ACTOR_STANDBY_PORT 或 4321
```
## 此集合中的其他 Actor
一组专注的、可组合的开发工具 Actor — 相同的哲学：做一件事，保持可测试，并连接到管道。
- **[GitHub Repo Intelligence MCP](https://apify.com/joeslade/github-repo-intelligence-mcp)** — 一个 MCP 服务器，为您的 AI 代理提供关于 GitHub 仓库是否处于积极维护状态还是已废弃的意见。
- **[Changelog Triage Agent](https://apify.com/joeslade/changelog-triage-agent)** — 监视产品变更日志，并将每个条目分类为 BREAKING、WARNING 或 INFO，以便您尽早发现废弃。
- **[SERP Topic Gap Monitor](https://apify.com/joeslade/serp-topic-gap-monitor)** — 查找您的竞争对手排名而您的站点缺失的主题。
## 许可证
Apache-2.0
