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 额度校验失败`。