onesvm-browser-server/docs/mcp-usage-20260901.md

type	status	created	step
runbook	active	2026-09-01	P3 / plan-20260901-02

onesvm-browser-server MCP 使用文档（消费者智能体接入指南）

面向消费方智能体（Vlepontas / EAI / 其它注册主体）的开发者。读完本文即可独立完成接入与正确使用。 版本：v0 设计版（2026-09-01）。§4 能力数据范围为真实实测（2026-09-01 本机 Docker，darwin arm64；生产 amd64 部署后同架构复测，数字可能微调）。 地址/端口为预设值，部署后以正式通知为准。

---

1. 接入信息

1.1 Endpoint

项	值（预设）
协议	MCP over Streamable HTTP（POST /mcp，2026 无状态规范；无 SSE 旧路径；2025 兼容腿待 O9 决策，首版不带）
内网直连（overlay）	http://browser-server:8640/mcp
经反代	{网关地址}/bs-api/mcp（urlapi 前缀 strip 后转发）
HTTP 兜底（非 MCP 消费者/调试用）	POST /bs-api/v1/search、POST /bs-api/v1/read（同一内核、同一错误码）

1.2 认证

• 头：X-Service-Token: bs_<你的key>。🔴 禁止把 key 放进 Authorization: Bearer（下游按 JWT 解析会 401）。
• key 形态：bs_ 前缀 + 随机串。明文只在签发时回传一次，服务端只存 hash，丢失只能吊销重签。

1.3 key 获取流程

你的主体（如 vlepontas）→ 向管理员注册（主体名 + 联系人 + 用途说明）
  → 管理员 CLI 签发 key（绑定 scopes/限额）→ 明文回传一次 → 你存入己方密钥管理
吊销：找管理员，即时生效（服务端缓存收敛 ≤10s）

1.4 Scopes（能力分级）

scope	默认	能做什么
search	✅ 默认	关键词搜索发现（search 工具）
read	✅ 默认	单 URL 精读（read 工具，fit markdown）
extract	❌ 特权申请	JSON Schema 结构化抽取（read 的 extract 参数）
browse	❌ 特权申请	多步交互（协议预留，首版未实现）
screenshot / rawHtml	❌ 特权申请	截图 / 原始 HTML 返回（token 与内存开销大）

每把 key 另有：rpm 速率、日/月配额、并发会话数上限（由管理员按主体需求设定）。

---

2. 工具清单与调用

2.1 search — 搜索发现

参数	类型	默认	说明
query	string	必填	关键词
region	domestic | overseas	必填，无默认	国内直连 / 国外代理（能力差异见 §4.1，请按你的数据需求显式选择）
max_results	int ≤20	5	返回条数
time_range	day/week/month/year	不限	时间过滤（引擎支持时生效）
lang	string	自动	如 zh-CN / en-US

调用示例 1（国内政策搜索，JSON-RPC）：

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "跨境电商 出口退税 政策 2026",
      "region": "domestic",
      "max_results": 5,
      "time_range": "year",
      "lang": "zh-CN"
    }
  }
}

调用示例 2（国外调研）：

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "best bluetooth earbuds 2026",
      "region": "overseas",
      "max_results": 10,
      "lang": "en-US"
    }
  }
}

典型响应（示例性质：由 2026-09-01 实测样本改写为统一信封格式，字段真实、数值为示例）：

{
  "ok": true,
  "kind": "search",
  "request_id": "01K3…ulid",
  "took_ms": 633,
  "query": "跨境电商 出口退税 政策 2026",
  "answer": null,
  "results": [
    {
      "id": "r1",
      "title": "海关总署 税务总局关于跨境电子商务出口退运商品税收优惠政策…",
      "url": "https://hainan.chinatax.gov.cn/xxgk_6_1/06163393.html",
      "content": "一、对自2026年1月1日至2027年12月31日期间在跨境电子商务海关监管代码(1210、9610、9710、9810)项下申报出口,因滞销、退货原因…",
      "score": 0.92,
      "engine": "baidu",
      "published_at": null
    },
    {
      "id": "r2",
      "title": "雨果跨境-跨境电商品牌出海产业互联网平台",
      "url": "https://m.cifnews.com/",
      "content": "雨果跨境以雨果网作为流量依托，致力于为跨境电商从业者提供全球产业出海…",
      "score": 0.71,
      "engine": "bing"
    }
  ],
  "usage": { "credits": 1, "engine": "searxng-cn", "tokens_estimate": 350 },
  "provenance": { "adapter": "searxng-cn", "proxy_exit": "none", "cached": false, "retrieved_at": "2026-09-01T11:41:15+08:00" },
  "error": null
}

字段纪律：results 为空时是 [] 而非 null；content 为 ≤800 字符的 query 相关片段（非全文，全文请用 read）；answer 恒为 null（本服务不做 LLM 答案合成）。

2.2 read — 单页精读

参数	类型	默认	说明
url	string	必填	目标页 URL（仅 http/https，80/443）
formats	string[]	["markdown"]	可选加 links / images；html / screenshot 为特权 scope
max_chars	int	20000	正文截断；截断时响应 truncated=true
extract	object	无	特权：{schema: {...}, prompt?: "…"}，JSON Schema 结构化抽取

调用示例 1（政策页精读）：

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "read",
    "arguments": { "url": "https://hainan.chinatax.gov.cn/xxgk_6_1/06163393.html" }
  }
}

调用示例 2（带结构化抽取，特权）：

{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": {
    "name": "read",
    "arguments": {
      "url": "https://example-shop.com/products/item-1",
      "formats": ["markdown"],
      "extract": { "schema": { "type": "object", "properties": { "price": {"type":"string"}, "title": {"type":"string"} } } }
    }
  }
}

典型响应（示例性质：由实测样本改写；该税务公告页实测 5/5 提取成功、1122 字、无导航残渣）：

{
  "ok": true,
  "kind": "read",
  "request_id": "01K3…ulid",
  "took_ms": 58,
  "url": "https://hainan.chinatax.gov.cn/xxgk_6_1/06163393.html",
  "final_url": "https://hainan.chinatax.gov.cn/xxgk_6_1/06163393.html",
  "title": "财政部 海关总署 税务总局关于跨境电子商务出口退运商品税收优惠政策的公告（…2026年第16号）",
  "description": null,
  "markdown": "| 索引号 | 11460000008174507Q/2026-14228 | …\n\n为支持跨境电子商务新业态发展，现将…公告如下：\n\n一、对自2026年1月1日至2027年12月31日期间…",
  "truncated": false,
  "char_count": 1122,
  "metadata": { "status_code": 200, "content_type": "text/html", "language": "zh", "retrieved_at": "2026-09-01T11:42:45+08:00" },
  "links": null, "images": null, "html": null, "screenshot_url": null,
  "extracted": null,
  "usage": { "credits": 1, "engine": "trafilatura", "tokens_estimate": 281 },
  "provenance": { "adapter": "trafilatura-http", "proxy_exit": "none", "cached": false, "retrieved_at": "2026-09-01T11:42:45+08:00" },
  "error": null
}

字段纪律：默认唯一内容字段是 markdown（fit 提纯后正文）；links/images/html/screenshot_url 只在 formats 点名时非 null；截图只给可过期 URL、绝不给 base64；extract 失败时 extracted=null + warnings，正文不吞。

---

3. 错误码与重试纪律

错误同时出现在 HTTP 状态码与 MCP isError 信封的 error.code，两面一致：

code	HTTP	语义	重试纪律
rate_limited	429	超 rpm/并发	按响应 Retry-After 秒数退避；带 X-RateLimit-* 头
quota	402	日/月配额耗尽	不重试，联系管理员提额或等窗口重置
timeout	504/200信封	上游超时	可重试，指数退避 ≤2 次
upstream	502/200信封	上游站点故障/反爬空结果	可重试 ≤2 次；持续出现见 FAQ-6
blocked	200信封	目标站拦截（WAF/CF/验证页）或超体积/类型限制	不要换参数硬刷；确认为能力边界（§4.2）
denied	403	合规拦截（域名/词表/robots/SSRF）	禁止重试对抗。被拦就是没数据
extract_failed	200信封	结构化抽取失败	去掉 extract 降级重试（正文仍可用）
401	401	key 缺失/无效/放错头	检查是否用了 X-Service-Token 而非 Bearer
503	503	队列满/系统压力（只拒新不杀旧）	按 Retry-After 退避；响应带 running/queued 现状

队列语义：请求被排队不算失败；ADMIT_MAX=60（running+queued 合计）超限时才返回 503。浏览器会话并发另有 X-Session-Remaining 提示头，请自行退避。

---

4. 能力数据范围（当前实测版 · 2026-09-01）

本节每个断言均来自 2026-09-01 本机 Docker 实测（bench/ 产物与站点矩阵探针），未测项标「未验证」。生产部署后可能有小幅漂移。

4.1 搜索发现（search）

国内（region=domestic）——SearXNG 聚合四引擎，单发质量满分（政策类 query 实测 5/5 断言通过）：

引擎	单发可用性	高并发突发表现（60 同发实测）	含义
必应中国	✅ 稳定	60/60 扛住	主力
360	✅ 稳定	53/60	主力
百度	✅ 单发好	4/60（CAPTCHA）	突发时可能缺席
搜狗	⚠️ 连续调用第 3 次起 CAPTCHA	0/60	仅低速补充

→ 你的体验：常规节奏搜索结果完整（多引擎聚合）；若你的上游短时间猛打，结果会变少（不是故障，是上游反爬）。服务端已做排队限速（对上游钳 4–8 并发 + 短缓存）尽量消化。

国外（region=overseas）——当前仅 Bing 可用：实测 Google / DuckDuckGo / Brave / Startpage / Qwant 在现有数据中心代理出口下全部 CAPTCHA/429。Bing 结果可能存在偏题（实测出现过把多词 query 截成首词的样本）。禁止假定多源聚合能力；需要对等多源质量请联系管理员（决策点：更优代理 / Brave API）。

4.2 URL 直取（read）——站点三分能力表（20 站 × 2 通道实测）

服务自动路由「纯 HTTP 提取 → 轻量 JS 渲染 → 保真渲染」降级链，你无需关心；只需知道边界：

分类	能力	实测站点
✅ 稳取	公开资讯 / 文档 / Wiki / 代码托管 / 政策页（走 JS 通道） / 企业公开页	Wikipedia、GitHub、MDN、BBC、TechCrunch、LinkedIn 公开公司页、gov.cn、36氪、HN、新华英文
⚠️ 部分	Shopify 系独立站：商品 URL 常 302 到集合页，能拿到系列与价格，不保证落到指定 SKU	Allbirds 实测
❌ 打不过（返回 blocked）	Amazon 详情页（WAF）、Medium（Cloudflare）、Reddit（匿名 403）、X（登录墙）、知乎（403）、微博（302 访客墙）、百度百科（滑块）、StackOverflow（CF）、YouTube（无正文结构）	当前代理出口客观限制，升级住宅代理/强对抗档前请勿规划这些源

4.3 性能档位（实测）

指标	值
国内搜索 p50 / p95	0.63s / 0.79s
国外搜索 p50 / p95	4.7s / 4.9s（Bing 经代理）
正文读取 p50 / p95	0.06s / 0.12s（纯 HTTP 通道）；JS 通道约 1–2s
渲染吞吐	轻渲染 2.13 jobs/s（4 槽）；保真渲染 0.81 jobs/s（单槽 FIFO）
队列深度	60（running+queued；超时硬顶 120s）

4.4 体积 / 类型 / 格式限制

• 下载体积上限 max_download_bytes（部署值以管理员通知为准）；Content-Type 白名单：html / xml / json / pdf / text。
• 默认只产 fit markdown；rawHtml / 截图为特权 scope。
• 单页正文默认截断 20000 字符（max_chars 可调，截断必显式 truncated=true）。

---

5. 合规使用规则（消费侧必须遵守）

以下规则同时写在 MCP server instructions 中；违反会被 denied 拦截并记入审计：

1. 不得将本服务用于任何违反中国法律法规的数据获取。
2. 不得用于绕过登录墙 / 支付墙 / 验证码（本服务默认也不具备此能力）。
3. 不得进行整站搬迁式 crawl（每 host 有频率上限；60 会话封顶本身也是合规阀）。
4. 不得把公开网页中的个人信息汇总成档案再分发；响应中的疑似 PII 默认已被脱敏，不要试图还原。
5. 不得把包含境内个人信息的 query 发给 region=overseas（query 会经境外代理出口）。

其它纪律：普通 key 遵守 robots.txt；denied / blocked 的语义是「没数据」，不要重试对抗、不要换出口绕过——反复对抗触发审计告警并可能导致 key 被吊销。

---

6. FAQ 与排错

Q1：401 Unauthorized？ 九成是把 key 塞进了 Authorization: Bearer。改用 X-Service-Token: bs_…。其余是 key 已吊销/过期，找管理员。

Q2：403 denied？ 合规拦截命中（域名黑名单 / 词表 / robots / SSRF 防护）。响应里有 rule_id；确认你的请求没踩 §5 红线。确属误判，带 request_id 找管理员复核规则。

Q3：429 / 503？ 429 = 你自己超 rpm，按 Retry-After 退避；503 = 系统队列满（60），同样按 Retry-After。两者都只拒新请求，在途任务不受影响。持续 503 说明该错峰或找管理员扩容。

Q4：402 quota？ 日/月配额耗尽，不可重试。找管理员提额。

Q5：read 返回的 markdown 很短或为空？ 两种典型：① 目标站是「壳页」（如部分政府网联播页），纯 HTTP 通道会宁可弃取也不给脏数据——服务端会自动升级 JS 通道重试；② 目标站在 §4.2 ❌ 清单里，此时应是 blocked 而非空正文。若 ok=true 但正文质量差，带 request_id 反馈。

Q6：搜索结果突然变少 / 引擎变少？ 上游反爬波动（尤其百度/搜狗在突发后 CAPTCHA）。服务端引擎矩阵在监控；非故障，通常数分钟自恢复。持续异常找管理员看引擎成功率矩阵。

Q7：国外搜索质量不满意？ 已知限制：当前仅 Bing（§4.1）。需要 Google/DDG 级多源质量，向管理员提（代理升级或官方 API 通道，涉出境合规评估）。

Q8：能不能爬 Amazon / Reddit / …？ 当前不能（§4.2 ❌ 清单）。这是出口 IP 信誉问题，不是服务故障；强对抗能力在预留档（Camoufox + 住宅代理），启用与否由产品决策。

---

机制细节权威：docs/design-arch-20260901.md；能力数据来源：docs/decision-candidates-20260901.md §6 与 .dsh/artifacts/run-20260901-browser-arch/site-matrix.md。