beacon-mfg-mcp 1.12.4 → 1.12.6

package/MCP_HTTP.md

@@ -0,0 +1,178 @@
+# 远程 MCP 端点（POST /mcp）
+
+> 2026-11-13 上线。给「不想装 Node / 不会装 Node」的人一条接入路径。
+
+## 1. 为什么要有它
+
+在此之前分发只有 `packages.stdio` 一条：想用的人必须
+
+```
+node ≥ 18  →  npx beacon-mfg-mcp  →  客户端里配一个本地进程
+```
+
+而 Registry 首页 100 条里 **93 条**声明了 `remotes`。我们不但没有，还在用最重的那条路径。
+
+结果是可预测的：真正想查供应商的人（采购、外贸、货代）不会为了查 20 家公司去装开发者环境。
+2026-11-13 的暴露面审计显示「注册后三天，真实外部使用 0」—— 不是流量问题，是**接入路径只有一条，
+而且没人走**。
+
+远程端点把门槛从「装 Node 环境」降到「粘一个链接」。它修的是路径，不是流量。
+
+## 2. 端点契约
+
+```
+POST https://beacon-mfg.pages.dev/mcp
+Content-Type: application/json
+```
+
+传输是 **streamable-http 的无状态子集**：
+
+| 项 | 实现 |
+|---|---|
+| 传输 | 单次 POST ↔ 单个 JSON 响应（`application/json`，不升级 SSE） |
+| 会话 | **无** `Mcp-Session-Id`。每请求自带完整上下文 |
+| `GET /mcp` | 405 + `Allow: POST`（无状态实现没有服务端推送流，不假装支持） |
+| 批量 | 不支持，明确返回 `batch_not_supported`（不静默只处理第一个） |
+| 通知（无 `id`） | 202 + 空 body（`notifications/initialized` 走这里） |
+| 协议版本 | 认识 `2025-06-18` / `2025-03-26` / `2024-11-05`，其余回落最新 |
+
+支持的方法：`initialize`、`ping`、`tools/list`、`tools/call`。其余 `-32601`。
+
+### 为什么无状态
+
+有状态要 Durable Object，而 Pages Functions 只有一个无状态 worker。
+而 `tools/call` 本来就是**一问一答**，没有会话照样正确。
+代价只有一个：服务端主动推送（SSE 通知、sampling）做不了 —— 那就明说 405，而不是挂一个假的 GET 长连接。
+
+## 3. 身份与配额：纯 IP
+
+不要求注册、不认 `X-Beacon-Cid`、不发令牌。aid 由**出口 IP** 派生：
+
+```
+ipk = base64url(sha256("ip|" + salt + "|" + ip))[:16]
+aid = hex(sha256("mcp|" + ipk))[:16]      // 16 位 hex，满足 agentId 的格式要求
+```
+
+于是额度、审计、逐条计量**全部复用 `/v1` 那套**，不需要新表、新维度、新报表：
+
+| 闸 | 值 | 说明 |
+|---|---|---|
+| `V1_DAILY.anon` | 1,000 条 / 24h / IP | 一条记录算一条；重复看同一家不重复计 |
+| `V1_IP_DAILY` | 20,000 条 / 24h / IP | 防「同 IP 换 aid 消耗」，两条闸量同一个池子 |
+| `IP_DAILY_OP` | 5,000 次操作 / 24h / IP | 防「同 IP 换 cid 刷」。**操作数与记录数是两条尺子**，混算的后果见下 |
+
+一个真实买家一轮「搜一次 + 翻十家 + 看十张卡」≈ 21 条，1,000 条 ≈ 47 轮/天。
+
+**换 IP 才能换额度，换 header 无效。** 顺带实测确认：外部伪造 `cf-connecting-ip` 会被
+Cloudflare 直接拒（403 / error code 1000），所以这条闸没有「客户端自己声明 IP」的漏洞。
+
+> **2026-11-13 修的一处真事故**：`beacon_ip_op` 里一行代表**一条记录**（`ipChargeV1` 按条写），
+> 而门禁原来用 `COUNT(*)` 同时当「操作数」用 —— 一次检索回 200 条就抵掉 200 次操作。
+> 实测本机 IP 一天取 7,351 条，把 `IP_DAILY_OP`(5000) 撞满，之后所有受门禁保护的路径
+> （`/data/manifest.json`、`/skills/registry/capability/*`）全 429，部署校验读成
+> 「6/19 项未通过」。现在两条尺子分开：记录数按行数（上限 20000），操作数按
+> `#` 前缀归并（上限 5000），429 回执里带 `dimension: ops | records` 指明是哪一条。
+
+### 审计口径
+
+`logUsage` 的 `tool` 带 `mcp.` 前缀（`mcp.search_vendors` 等），`layer` 取 handler 给的
+（`index` / `record` / `capability`）。这样 D1 报表里能把**远程 MCP** 与**本地 stdio / App** 分开 ——
+否则「远程端点到底有没有人来」永远答不了，而那正是做这件事的原因。
+
+工具执行抛异常时**也写一行**（status 500）。第一版在 catch 里直接 return，等于最严重的那类失败静默。
+
+## 4. 已上线的工具（7 个：3 个取数 + 4 个寻源/指路）
+
+| 工具 | 映射到 | 说明 |
+|---|---|---|
+| `search_vendors` | `handleSearch` → `/v1/search` | 关键词/城市/国标码检索 |
+| `get_vendor` | `handleRec` → `/v1/rec/<token>` | 单家完整档案 |
+| `get_capability_card` | `handleCap` → `/v1/cap/<token>` | 能力卡；`found:false` 是正常结果，不算错误 |
+| `start_sourcing` | `handleSearch` + D1 会话 | 含糊需求 → 宽召回 + 1~2 个澄清问题，返回 `session_id` |
+| `answer_sourcing` | 会话续接 + 重检 | 把澄清答案写回，**重新检索**（不是在旧结果里二次过滤） |
+| `refine_sourcing` | 会话快照 | `best` / `more` / `filter` / `details` |
+| `vendor_onboarding` | 纯静态文案 | 入驻/认领指路（控制台深链 + Agent HTTP 契约） |
+
+**复用而不是重写**：检索打分、脱敏、逐条计量都在原 handler 里。在这里重写一份必然与 stdio 版分叉，
+而分叉的检索结果比慢一点糟得多。实现方式见 `pages/_worker.js` 的 `mcpInnerRequest()`。
+
+### 4.1 多轮寻源：会话在哪、活多久、谁的
+
+协议层的「无状态」没变（仍然不签 `Mcp-Session-Id`）。多轮状态是**业务状态**，落在 D1 的
+`beacon_mcp_session` 表，用 `session_id` 显式续接：
+
+| 项 | 值 |
+|---|---|
+| TTL | 2 小时（`expires`），过期即读不到、并在下一次 `start_sourcing` 时被清 |
+| 归属 | `aid`（由出口 IP 派生）。SQL 里带 `AND aid = ?`，别的 IP 拿到 `sid` 也读不到 |
+| 容量 | 单 IP 最多 20 个活会话（按最后使用时间淘汰），一轮最多存 40 家候选 |
+| 存什么 | 一句话 `demand` + 候选的**筛选字段**（名称/城市/区县/国标码/工艺/材料/认证/是否有电话/灯牌档） |
+| **不存什么** | 电话、坐标、来源 URL。电话是「一条一个额度」的取证动作（`get_vendor`），存进会话等于开第二条免费取号通道 |
+
+**城市先从需求里认。** `start_sourcing("东莞注塑代工，最好有 ISO9001")` 里的「东莞」会被
+认成 `city` 过滤条件（词表直接用检索侧的 `catalog/tree.json → cities`，所以认得就一定查得到），
+回执里用 `city` 字段明说是哪一座 —— 否则 agent 没法解释「为什么结果全是东莞的」。
+认不出来才由澄清问题去问。
+
+> 这条是线上实测补的：第一版没做提取，同一句需求返回的第一名是**重庆**的公司。
+> 它不是「问得浅」，是**方向错了** —— 比少问一句严重得多。
+
+**澄清问题由候选集自己生成，不是背行业知识表。** 只问三件事：城市、工艺、认证 ——
+选项全部取自这一轮候选，所以不会出现「选项里没有这个城市」，也不会问名录里没有的字段
+（交期、数量、开票方式一律不问）。这比本地 stdio 版（`skills/rfq-kernel/industry/*.json`
+的 10 个行业 pack）问得浅，是刻意的取舍：**与其问得像人却答不出，不如只问能兑现的**。
+
+### 4.2 没上的 4 类，以及为什么
+
+| 工具 | 缺什么 |
+|---|---|
+| `read_notes` / `report_note` | 语义是「本地笔记」，远程端点没有本地盘（要么改语义，要么不做） |
+| `suggest_filters` / `list_industries` | 依赖国标货架名称表（`industry-index.json` 6MB），要单独做缓存层 |
+
+**没上的工具不出现在 `tools/list` 里** —— 让 agent 看不到，比让它调了才报错好。
+
+## 5. 验收清单
+
+```bash
+B=https://beacon-mfg.pages.dev
+
+# 握手
+curl -s -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
+  $B/mcp
+
+# 工具清单（应恰好 7 个）
+curl -s -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' $B/mcp
+
+# 检索
+curl -s -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_vendors","arguments":{"query":"输送线","city":"上海"}}}' \
+  $B/mcp
+
+# 多轮寻源：start 拿 session_id，再 answer / refine（两条命令要在**同一个出口 IP** 下执行）
+curl -s -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"start_sourcing","arguments":{"demand_text":"东莞注塑代工，最好有 ISO9001"}}}' \
+  $B/mcp
+
+# 方向性检查：GET 必须 405，不是 200 也不是 404
+curl -s -o /dev/null -w "%{http_code}\n" $B/mcp
+```
+
+真正的客户端验收（比 curl 可信）：
+
+```bash
+npx @modelcontextprotocol/inspector
+# Transport: Streamable HTTP    URL: https://beacon-mfg.pages.dev/mcp
+```
+
+## 6. 已知边界
+
+1. **无状态 = 无推送**。需要 sampling / elicitation / 服务端通知的客户端功能用不了。
+2. **一次性工具调用没做去重**。客户端重试 = 重复计量（与 `/v1` 同口径，不为重试开豁免）。
+3. **`initialize` 的版本号** `MCP_SERVER_VERSION` 硬编码在 `_worker.js`，与 `mcp/package.json`
+   必须同步。不一致只影响回执里显示的数字，但会让「线上是不是新版」变成猜谜 —— 已纳入
+   `mcp/check_release.py` 闸门。
+4. **preview 环境跑不了**：Pages 的 preview 不继承 secrets，`BEACON_JWT_SECRET` 为空
+   → 端点 fail-closed 返回 503 `server_misconfigured`。这是刻意的（签不出令牌就用不了），
+   所以远程端点只能在生产验证。

package/README.md

@@ -1,6 +1,6 @@
 # Beacon-MFG 只读 MCP 服务
 
-**English**: Read-only MCP server for finding **Chinese suppliers, manufacturers and business entities** — 210k+ records across all GB/T 4754 industries, bilingual CN/EN, USCC-verified, with an RFQ sourcing kernel. Free, no API key: `npx -y beacon-mfg-mcp`.
+**English**: Read-only MCP server for finding **Chinese suppliers, manufacturers and business entities** — 210k+ records across all GB/T 4754 industries, bilingual CN/EN, USCC-verified, with an RFQ sourcing kernel. Free, no API key. **No install**: connect to the hosted Streamable HTTP endpoint `https://beacon-mfg.pages.dev/mcp`; or run locally with `npx -y beacon-mfg-mcp`.
 
 让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / 常见 MCP 客户端 等）能够**检索与调用**
 灯塔工厂供应商名录，**无需 clone 整个仓库、无需任何密钥、无需第三方依赖**。
@@ -10,6 +10,18 @@
 > 只记「怎么绕开」，不评数据对错；repo 模式存 `<repo>/mcp/notes/` 由操作员托管，
 > 联网模式存本机 `~/.beacon-mfg/notes/` 不上传云端）。
 
+> **两种接入形态，工具数不同**：
+> - **远程端点**（`https://beacon-mfg.pages.dev/mcp`，Streamable HTTP，无需安装）——
+>   提供 7 个工具：`search_vendors` / `get_vendor` / `get_capability_card`，
+>   多轮寻源 `start_sourcing` / `answer_sourcing` / `refine_sourcing`，以及 `vendor_onboarding`。
+>   额度按**出口 IP** 计（1,000 条记录/24h），不要注册、不要 API Key；寻源会话 2 小时过期，
+>   且只能在**同一个出口 IP** 下续接。
+> - **本地 stdio**（`npx -y beacon-mfg-mcp`）—— 下表全部 12 个，多轮寻源的澄清问题由行业 pack 驱动
+>   （远程版只问「答了能过滤」的城市/工艺/认证，选项取自候选集本身），另有踩坑留言区。
+>
+> 远程端点没上的工具**不会出现在 `tools/list` 里**（让 agent 看不到，比让它调了才报错好）。
+> 契约与验收清单见 https://github.com/eiry16/beacon-mfg/blob/main/mcp/MCP_HTTP.md。
+
 ## 提供的 tool（共 12 个：8 个只读检索 + 1 个身份自助 + 1 个入驻入口 + 2 个留言区读写）
 
 | tool | 用途 | 关键参数 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.12.4",
+  "version": "1.12.6",
   "mcpName": "io.github.eiry16/beacon-mfg-mcp",
   "description": "Read-only MCP server exposing the BeaconMFG灯塔 directory of business entities across ALL GB/T 4754 industry divisions (manufacturing, services, retail, logistics, catering, IT, and more) to any MCP-compatible agent. No signup and no API key: an anonymous identity is generated on first run, phone binding is optional (only needed for L2 capability cards).",
   "keywords": [
@@ -40,7 +40,8 @@
     "rfq-kernel/",
     "copy-rfk.js",
     "notes/",
-    "README.md"
+    "README.md",
+    "MCP_HTTP.md"
   ],
   "scripts": {
     "prepack": "node copy-rfk.js",