协议
MCP 协议
CrawlForge MCP 的完整 Model Context Protocol 规范。了解如何实现自定义 MCP 客户端并与任何 AI 框架集成。
什么是 MCP？
Model Context Protocol（MCP）是由 Anthropic 创建的开放标准，让 AI 助手能够安全地访问外部数据源和工具。它定义了一种标准化方式，供 AI 模型发现、调用外部服务并接收其结果。
JSON-RPC 2.0
基于标准 JSON-RPC 构建，具备通用兼容性
安全
内置 API 密钥身份验证和速率限制
可扩展
无需改动协议即可添加自定义工具
服务器配置
配置你的 MCP 客户端以连接到 CrawlForge MCP server。
Json
crawlforge-mcp 随全局安装的 crawlforge-mcp-server 一同提供。若未进行全局安装，请使用 "command": "npx" 和 "args": ["-y", "crawlforge-mcp-server"]。如果你运行过 crawlforge-setup，则 env 块为可选——密钥会从 ~/.crawlforge/config.json 读取。从控制台获取你的 API 密钥。
工具发现
MCP 客户端通过调用 tools/list 方法来发现可用工具。
Json
工具清单字段
| 名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
name | string | 必填 | 工具标识符（例如 "fetch_url"）· 示例：fetch_url |
description | string | 必填 | 便于阅读的工具说明 · 示例：从 URL 抓取并解析 HTML 内容 |
inputSchema | object | 必填 | 定义工具参数的 JSON Schema · 示例：{ "type": "object", "properties": {...} } |
工具调用
使用 tools/call 方法，并传入工具名称和参数来调用工具。
Typescript
异步执行： 所有工具调用都是异步的。在 JavaScript 中使用
await，或在 Python 中使用 async/await 来等待结果。响应格式
工具响应遵循标准 MCP 格式，包含内容、元数据和错误处理。
Json
MCP 消息结构
标准消息字段
| 名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
method | string | 必填 | MCP 方法名（例如 "tools/call"）· 示例：tools/call |
params | object | 必填 | 方法专属参数 · 示例：{ "name": "fetch_url", "arguments": {...} } |
id | string | 必填 | 用于关联的唯一请求标识符 · 示例：req_12345 |
错误代码
| 代码 | 名称 | 说明 |
|---|---|---|
-32700 | Parse Error | 无效的 JSON |
-32600 | Invalid Request | 请求对象格式错误 |
-32601 | Method Not Found | 未知的 MCP 方法 |
-32602 | Invalid Params | 参数缺失或无效 |
-32603 | Internal Error | 执行期间的服务器错误 |
-32001 | Insufficient Credits | credits 不足，无法执行工具 |
最佳实践
- 使用唯一请求 ID — 为每个请求生成唯一 ID，以便关联响应
- 优雅地处理错误 — 同时检查 JSON-RPC 错误和工具专属错误
- 设置超时 — 为工具调用设置合理的超时时间（10-30 秒）
- 监控 credits 用量 — 在响应中跟踪
_meta.credits_remaining
故障排查
连接出现问题？ 请确认你的 API 密钥有效且服务器路径正确。检查环境变量和网络连通性。
如需详细的故障排查，请参阅 Claude Desktop 指南或联系支持。
MCP Resources 与 Prompts
除工具之外，CrawlForge 还提供 MCP Resources（可通过 URI 寻址的数据）和 Prompts（预置工作流）。两者在通过任何兼容 MCP 的客户端使用服务器时均可用。
Resources
Resources 位于 crawlforge:// URI 方案下，用于寻址先前工具调用产生的长期存留产物——研究会话、批处理作业、爬取站点地图、截图和页面快照。已注册的五个 URI 模板为：
crawlforge://research/{sessionId}crawlforge://job/{jobId}crawlforge://crawl/{sessionId}/sitemapcrawlforge://screenshot/{actionId}crawlforge://snapshot/{urlHash}/{timestamp}
Resources 是只读的、有 TTL 限制的，并且不消耗 credits。
Json
Prompts
Prompts 是模型可以发现并调用的预置工作流。CrawlForge 开箱即提供五个：
| Prompt | 用途 |
|---|---|
competitive-analysis | 并排抓取并对比竞品站点 |
monitor-changes | 为目标 URL 设置变更跟踪工作流 |
rag-ingest | 爬取某个域并输出干净、分块的内容，供 RAG 流水线使用 |
site-audit | 对站点进行完整的 SEO + 无障碍 + 内容审计 |
research-deep-dive | 带引用的多阶段深度研究 |
示例：Claude Desktop 如何发现并调用某个 prompt。
Json
准备好集成了吗？
选择你的集成方式并开始构建。