协议

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

{
  "mcpServers": {
    "crawlforge": {
      "command": "crawlforge-mcp",
      "env": {
        "CRAWLFORGE_API_KEY": "cf_live_YOUR_KEY_HERE"
      }
    }
  }
}

crawlforge-mcp 随全局安装的 crawlforge-mcp-server 一同提供。若未进行全局安装，请使用 "command": "npx" 和 "args": ["-y", "crawlforge-mcp-server"]。如果你运行过 crawlforge-setup，则 env 块为可选——密钥会从 ~/.crawlforge/config.json 读取。

从控制台获取你的 API 密钥。

工具发现

MCP 客户端通过调用 tools/list 方法来发现可用工具。

Json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list",
  "params": {}
}

工具清单字段

名称	类型	是否必填	说明
`name`	string	必填	工具标识符（例如 "fetch_url"）· 示例：fetch_url
`description`	string	必填	便于阅读的工具说明 · 示例：从 URL 抓取并解析 HTML 内容
`inputSchema`	object	必填	定义工具参数的 JSON Schema · 示例：{ "type": "object", "properties": {...} }

工具调用

使用 tools/call 方法，并传入工具名称和参数来调用工具。

Typescript

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'crawlforge-mcp',
  env: {
    CRAWLFORGE_API_KEY: process.env.CRAWLFORGE_API_KEY!
  }
});

const client = new Client({
  name: 'my-ai-app',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

const result = await client.callTool({
  name: 'fetch_url',
  arguments: {
    url: 'https://example.com',
    timeout: 10000
  }
});

console.log(result);

异步执行：

所有工具调用都是异步的。在 JavaScript 中使用 await，或在 Python 中使用 async/await 来等待结果。

响应格式

工具响应遵循标准 MCP 格式，包含内容、元数据和错误处理。

Json

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "<!DOCTYPE html>\n<html>..."
      }
    ],
    "isError": false,
    "_meta": {
      "credits_used": 1,
      "credits_remaining": 999,
      "processing_time": 245
    }
  }
}

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}/sitemap
crawlforge://screenshot/{actionId}
crawlforge://snapshot/{urlHash}/{timestamp}

Resources 是只读的、有 TTL 限制的，并且不消耗 credits。

Json

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "resources/read",
  "params": {
    "uri": "crawlforge://research/ses_a1b2c3"
  }
}

Prompts

Prompts 是模型可以发现并调用的预置工作流。CrawlForge 开箱即提供五个：

Prompt	用途
`competitive-analysis`	并排抓取并对比竞品站点
`monitor-changes`	为目标 URL 设置变更跟踪工作流
`rag-ingest`	爬取某个域并输出干净、分块的内容，供 RAG 流水线使用
`site-audit`	对站点进行完整的 SEO + 无障碍 + 内容审计
`research-deep-dive`	带引用的多阶段深度研究

示例：Claude Desktop 如何发现并调用某个 prompt。

Json

// 1. Client lists available prompts
{ "jsonrpc": "2.0", "id": "4", "method": "prompts/list", "params": {} }

// 2. Client invokes a prompt with arguments
{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "prompts/get",
  "params": {
    "name": "competitive-analysis",
    "arguments": {
      "competitors": ["https://stripe.com", "https://paddle.com"]
    }
  }
}

准备好集成了吗？

选择你的集成方式并开始构建。

Claude Desktop 配置 LangChain 集成