vastark-seo-spider MCP服务

# vastark-seo-spider 校验 MCP 服务 以 MCP(Model Context Protocol)方式暴露爬虫校验能力。传输层为 **JSON-RPC 2.0 over Streamable HTTP**:仅支持 `POST`,服务端直接返回单个 JSON 响应,不提供 SSE 流。 ## 接入方法 * 先在[www.vastark.cn](https://www.vastark.cn)注册一个合作者角色的用户 * 进入[https://www.vastark.cn/interviewer/membership/upgrade](https://www.vastark.cn/interviewer/membership/upgrade)选择一个“搜索引擎spider校验1千次”虚拟商品花1元钱就能调用1000次 * 进入[https://www.vastark.cn/interviewer/open-platform#api-keys](https://www.vastark.cn/interviewer/open-platform#api-keys)页面获得你的api-key * 最后按下面的“客户端配置”方法配置就行 ## 端点 | 项目 | 说明 | |------|------| | URL | `POST /saas/mcp` | | 协议 | JSON-RPC 2.0,Streamable HTTP(请求-响应模式,无 SSE) | | 认证 | 请求头 `X-API-Key: <你的 API Key>` | | IP 白名单 | 与 REST 一致:客户开启白名单后,调用方 IP 必须命中 IP/CIDR 列表 | | GET 请求 | 不提供 SSE,返回 `405 Method Not Allowed`,响应头 `Allow: POST`,错误体为 JSON-RPC `-32600`(`仅支持 POST`) | | 计费权益码 | `seo_spider` | 认证与[IP白名单](https://www.vastark.cn/interviewer/open-platform#ip-whitelist)在解析 JSON-RPC 之前完成,因此这两类错误响应中不包含 `id` 字段。 ## 客户端配置 所有客户端都只需要三项信息: | 配置项 | 值 | |--------|----| | 服务地址 `url` | `https://api.vastark.cn/saas/mcp` | | 鉴权头 | `X-API-Key: YOUR_API_KEY` | | 传输方式 | Streamable HTTP(仅 `POST`,无 SSE) | 通用配置片段(大多数支持 `mcpServers` 的客户端可直接粘贴): ```json { "mcpServers": { "vastark-seo-spider": { "type": "streamable-http", "url": "https://api.vastark.cn/saas/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` > `type` 字段并非所有客户端都识别:Trae Work、WorkBuddy 的 HTTP 配置只认 `url` / `headers`,多写通常会被忽略;千问办公的连接器要求 `streamable-http`。如果客户端报协议或格式错误,先删掉 `type` 再试。 ### Trae / Trae Work 1. 左下角 **头像 → 设置**,左侧导航选择 **MCP**,进入 MCP Servers 管理面板。 2. 桌面版需要先选择运行环境:**本地** 或 **云端**。 3. 点击右上角 **创建 → 手动配置**。 4. 粘贴以下内容后点击 **确认**: ```json { "mcpServers": { "vastark-seo-spider": { "url": "https://api.vastark.cn/saas/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` Trae Work 的 HTTP 类型还支持在 `headers` 里设置超时(毫秒): ```json "headers": { "X-API-Key": "YOUR_API_KEY", "START_MCP_TIMEOUT_MS": "60000", "RUN_MCP_TIMEOUT_MS": "60000" } ``` 配置完成后在对话里直接说「校验 66.249.66.1 这个 IP 是不是 Googlebot」即可触发 `verify_seo_spider`。官方说明见 [https://docs.trae.cn/work_remote-mcp-server](https://docs.trae.cn/work_remote-mcp-server)。 ### 腾讯 WorkBuddy 1. 鼠标放左侧边栏 **专家·技能·连接器**上,点击展开的 **连接器**,进入 `mcp.json` 编辑界面(文件也可直接编辑 `~/.workbuddy/mcp.json`)。 2. 粘贴: ```json { "mcpServers": { "vastark-seo-spider": { "url": "https://api.vastark.cn/saas/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` 3. 保存并启用该 MCP Server,工具会出现在会话的可用工具列表里。 ### 千问办公 1. 打开左侧 **扩展 → 连接器**,点击右上角 **+ 添加**。 2. 选择手动填写或直接粘贴 JSON 配置: ```json { "mcpServers": { "vastark-seo-spider": { "type": "streamable-http", "url": "https://api.vastark.cn/saas/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` 3. 保存后新建会话,工具列表里应出现 `verify_seo_spider`、`verify_seo_spider_batch`、`list_seo_spider_engines`。 > 千问办公的 `type` 必须写 `streamable-http`(连字符写法),部分编码类客户端用 `streamableHttp`,以客户端表单提示为准。 ### 豆包工作 字节侧客户端目前没有公开统一的 MCP 配置入口文档,不同版本可能叫「MCP 服务器」「连接器」「插件」或「工具」。如果你的版本提供这类入口,按下面的通用片段填写;如果用的是 Trae Work,直接按上面「Trae / Trae Work」的步骤操作即可。 ```json { "mcpServers": { "vastark-seo-spider": { "url": "https://api.vastark.cn/saas/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` ### 其他 Agent 只要客户端支持 **Streamable HTTP** 类型的 MCP Server,填法都一样:地址 `https://api.vastark.cn/saas/mcp`,请求头带 `X-API-Key`。不支持自定义请求头的客户端无法接入(本服务用 `X-API-Key` 鉴权,没有 URL 参数形式的 Key)。 ### 配置验证 配置完成后,让 Agent 调用 `tools/list` 或直接问「你有哪些爬虫校验工具」,应能看到 3 个工具。也可以绕过客户端直接验证服务是否可达: ```bash curl -s -X POST 'https://api.vastark.cn/saas/mcp' \ -H 'Content-Type: application/json' \ -H 'X-API-Key: YOUR_API_KEY' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ### 注意:IP 白名单与云端 Agent **如果您在[开放平台设置](https://www.vastark.cn/interviewer/open-platform#ip-whitelist)中开启了IP白名单校验, 那需要额外关注这条**, 客户端以「云端」方式运行(如 Trae Work 云端环境)时,调用方出口 IP 是云厂商的地址,不固定。如果你的 API Key 开启了 IP 白名单,常见表现是返回 `-32003 IP 不在白名单`。两种处理方式: - 把对应云端的出口网段加进白名单; - 或者改用本地运行的客户端,让请求从你自己的固定出口 IP 发起。 ## 握手:initialize 请求: ```json { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-client", "version": "1.0.0" } } } ``` 响应: ```json { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false } }, "serverInfo": { "name": "vastark-seo-spider", "version": "1.0.0" } } } ``` 说明: - `protocolVersion` 固定返回 `2025-06-18`,服务端不校验客户端传入的版本。 - 仅声明 `tools` 能力,`listChanged = false`(工具清单固定)。 - 不支持 `resources`、`prompts`、`sampling` 等其它能力。 ## 通知:notifications/initialized ```json { "jsonrpc": "2.0", "method": "notifications/initialized" } ``` 响应为 `HTTP 202 Accepted`,**无 JSON-RPC 响应体**(通知类消息不需要响应)。该请求同样需要携带 `X-API-Key` 并通过 IP 白名单。 ## 心跳:ping ```json { "jsonrpc": "2.0", "id": 2, "method": "ping" } ``` 响应: ```json { "jsonrpc": "2.0", "id": 2, "result": {} } ``` ## 工具清单:tools/list 请求: ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/list" } ``` 响应 `result` 中包含 3 个工具: ```json { "jsonrpc": "2.0", "id": 3, "result": { "tools": [ { "name": "verify_seo_spider", "description": "校验单个 IP + User-Agent 是否属于可信 SEO 爬虫,按次计费", "inputSchema": { "type": "object", "properties": { "ip": { "type": "string", "description": "待校验的 IPv4/IPv6 地址" }, "user_agent": { "type": "string", "description": "请求的 User-Agent" } }, "required": ["ip", "user_agent"] } }, { "name": "verify_seo_spider_batch", "description": "批量校验 IP + User-Agent 是否属于可信 SEO 爬虫(1-100 条,按条数计费)", "inputSchema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "待校验的 IPv4/IPv6 地址" }, "user_agent": { "type": "string", "description": "请求的 User-Agent" } }, "required": ["ip", "user_agent"], "additionalProperties": false } } }, "required": ["items"] } }, { "name": "list_seo_spider_engines", "description": "列举支持的 SEO 爬虫引擎(标识与展示名),免费", "inputSchema": { "type": "object", "properties": {} } } ] } } ``` ### 工具说明 | 工具 | 参数 | 计费 | |------|------|------| | `verify_seo_spider` | `ip`(必填)、`user_agent`(必填) | 1 次 | | `verify_seo_spider_batch` | `items`(必填,1–100 条,每条含 `ip`、`user_agent`) | 按条数 | | `list_seo_spider_engines` | 无参数 | 免费(不查询余额、不计费) | > `user_agent` 原样透传请求头即可,服务端按**小写子串包含**匹配引擎,不要求完整 UA、不区分大小写,官方 UA 里的 `+http://www.google.com/bot.html` 之类注释可省略。UA 只决定按哪家规则校验,不代表身份可信。 ## 调用工具:tools/call ### 单条校验 请求: ```json { "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "verify_seo_spider", "arguments": { "ip": "66.249.66.1", "user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" } } } ``` 响应: ```json { "jsonrpc": "2.0", "id": 4, "result": { "content": [ { "type": "text", "text": "{\"verified\":true,\"engine\":\"googlebot\",\"verdict\":\"ok\",\"cached\":false,\"elapsed_ms\":31}" } ], "isError": false } } ``` `result.content[0].text` 是一个**可解析的 JSON 字符串**,其字段与 REST 接口 `data` 完全一致:`verified` / `engine` / `verdict` / `cached` / `elapsed_ms`。 ### 批量校验 请求: ```json { "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "verify_seo_spider_batch", "arguments": { "items": [ { "ip": "66.249.66.1", "user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" }, { "ip": "203.0.113.10", "user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" } ] } } } ``` 响应(`text` 内容格式化展示): ```json { "jsonrpc": "2.0", "id": 5, "result": { "content": [ { "type": "text", "text": "{\"results\":[{\"verified\":true,\"engine\":\"googlebot\",\"verdict\":\"ok\",\"cached\":false,\"elapsed_ms\":35},{\"verified\":false,\"engine\":\"googlebot\",\"verdict\":\"ptr_mismatch\",\"cached\":false,\"elapsed_ms\":12}],\"count\":2}" } ], "isError": false } } ``` `text` 解析后的结构为 `{"results": [...], "count": N}`,与 RESTful 批量接口的 `data` 一致。 ### 引擎清单 请求: ```json { "jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": { "name": "list_seo_spider_engines", "arguments": {} } } ``` 响应: ```json { "jsonrpc": "2.0", "id": 6, "result": { "content": [ { "type": "text", "text": "{\"engines\":[{\"engine\":\"bingbot\",\"label\":\"Bingbot\"}]}" } ], "isError": false } } ``` `text` 中的 `engines` 数组结构与 REST `GET /saas/api/v1/seo-spider/engines` 的 `data` 完全一致(`engine` / `label`),只返回引擎标识与展示名,不暴露具体校验策略。上例为排版只保留第一项,真实返回包含全部 12 个引擎。 ## 错误码 JSON-RPC 层错误统一返回 `{"jsonrpc":"2.0","error":{"code":...,"message":"..."}}`。 | JSON-RPC code | HTTP | 场景 | |---------------|------|------| | `-32600` | 200 | 请求体不是合法 JSON、`jsonrpc != "2.0"` 或 `method` 为空 | | `-32600` | 405 | 使用 `GET /saas/mcp`(仅支持 POST,响应头带 `Allow: POST`) | | `-32600` | 413 | 请求体超过 `seo_spider.max_body_bytes`(默认 256KB),message 为 `请求体过大`,不查额度、不计费 | | `-32601` | 200 | 未知方法,message 为 `未知方法: ` | | `-32602` | 200 | `params` 解析失败、工具参数非法(IP 格式错误、UA 为空或超长、批量条数不在 1–100)、未知工具 | | `-32603` | 500 | 白名单查询失败(`系统错误`) | | `-32603` | 200 | 余额查询失败(`额度校验失败`)、结果序列化失败 | | `-32001` | 401 | API Key 缺失或无效(`API KEY 无效`) | | `-32002` | 200 | 额度不足(`额度不足`) | | `-32003` | 403 | 调用方 IP 不在白名单(`IP 不在白名单`) | 示例: ```json { "jsonrpc": "2.0", "id": 4, "error": { "code": -32002, "message": "额度不足" } } ``` ## 计费 与 REST 接口完全一致: - `verify_seo_spider`:每次调用扣减 `seo_spider` 1 次。 - `verify_seo_spider_batch`:按 `items` 实际校验条数扣减。 - `list_seo_spider_engines`:免费,不查询余额、不计费。 - 校验前先查询权益余额,余额 `<= 0` 返回 `-32002 额度不足`;余额查询失败返回 `-32603 额度校验失败`。