beacon-mfg-mcp 1.3.1 → 1.3.2

package/README.md

@@ -46,8 +46,18 @@ npm i -g beacon-mfg-mcp      # 或不安装直接用 npx beacon-mfg-mcp
 ```
 
 ```jsonc
-{ "mcpServers": { "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [] } } }
+{
+  "mcpServers": {
+    "beacon-mfg": {
+      "command": "beacon-mfg-mcp",
+      "args": [],
+      "env": { "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8" }
+    }
+  }
+}
 ```
+> 启动器（`bin/beacon-mfg-mcp.js`）已默认注入上述两个变量；此处写出仅为显式/可覆盖。
+> 二者保证 python 子进程以 UTF-8 输出，否则中文 Windows 上工具描述/结果会乱码。
 
 不填 `BEACON_REPO` 时默认走 `https://beacon-mfg.pages.dev`，即开即用。
 
@@ -92,6 +102,13 @@ npm i -g beacon-mfg-mcp      # 或不安装直接用 npx beacon-mfg-mcp
 HTTP 模式带正确 `User-Agent` 与 `ETag` 304 缓存（与 App 同款策略），并落盘 `~/.cache/beacon-mcp-cache`，
 重复查询零传输。CF 部署版手机号可能是全号——隐私敏感场景请用方式 A。
 
+> **CDN 兜底镜像（v1.3.2 新增）**：默认源 `beacon-mfg.pages.dev` 不可达（抖动/被墙）时，
+> MCP 会**自动回退**到 GitHub 兜底镜像拉 `manifest.json` 与分片——`cdn.jsdelivr.net/gh/eiry16/beacon-mfg@main`
+> 与 `raw.githubusercontent.com/eiry16/beacon-mfg/main`（与 Android App 同策略）。因此「免 clone 检索」
+> 在单一 CDN 失效时仍可工作。如需自定义/追加镜像，设 `BEACON_MIRRORS`（逗号分隔的基址列表）。
+> 注意：能力卡（`get_capability_card`）不在 git 内、仅存于 CF/R2，镜像兜底覆盖的是 manifest + 分片 + 档案这类主数据；
+> 在中国大陆等直连 GitHub 困难的网络，给 MCP 进程设 `HTTPS_PROXY=http://127.0.0.1:7890`（或你的代理）可让镜像链路走代理。
+
 ## 远程 HTTP 端点（Streamable HTTP）
 
 `server.py` 本体是 **stdio**；`http_server.py` 是它的 **HTTP 传输适配层**（复用同一份 `_dispatch`/`TOOLS`，
@@ -169,7 +186,7 @@ MCP 服务有两种发布渠道（详见 `mcp/RELEASE.md`）：
 
 - **GitHub Release（已配 CI）**：推送 `mcp-v*` 标签即由 `.github/workflows/mcp-release.yml`
   自动打包 `mcp/` 目录为 `beacon-mfg-mcp-mcp-vX.Y.Z.tar.gz` 并创建 Release。
-- **npm 包（已发布 ✅）**：`beacon-mfg-mcp` 已发布到 npm 公共仓库，当前版本 **`1.3.1`**
+- **npm 包（已发布 ✅）**：`beacon-mfg-mcp` 已发布到 npm 公共仓库，当前版本 **`1.3.2`**
   （<https://www.npmjs.com/package/beacon-mfg-mcp>）。第三方可直接 `npm i -g beacon-mfg-mcp`
   或 `npx beacon-mfg-mcp`，客户端配置 `"command": "beacon-mfg-mcp"` 即可，无需 clone、无需填路径。
   **1.3.0 起 npm 包自带 rfq-kernel**，安装 → MCP 握手 → `tools/list` 暴露 6 个 tool 且全部可用

package/RELEASE.md

@@ -1,4 +1,4 @@
-# Beacon-MFG 只读 MCP 服务 · v1.3.1
+# Beacon-MFG 只读 MCP 服务 · v1.3.2
 
 让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / WorkBuddy 等）能够
 **检索与调用**已发布到 Cloudflare Pages（或 GitHub）的灯塔工厂供应商数据，
@@ -21,7 +21,15 @@ MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流
 后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，
 依赖仓库平级的 `skills/rfq-kernel` 桥接模块。
 
-## 本次更新（v1.3.1）
+## 本次更新（v1.3.2）
+- **npm 启动器锁定 UTF-8**：`bin/beacon-mfg-mcp.js` 拉起 python 时注入 `PYTHONUTF8=1` / `PYTHONIOENCODING=utf-8`，
+  修复中文 Windows 上 python 按 GBK 写 stdout、被客户端按 UTF-8 解码导致的工具描述/结果乱码。
+- **HTTP 兜底镜像**：默认源 `beacon-mfg.pages.dev` 不可达时，自动回退到 GitHub 镜像
+  `cdn.jsdelivr.net/gh/eiry16/beacon-mfg@main` 与 `raw.githubusercontent.com/eiry16/beacon-mfg/main`
+  （与 Android App 同策略），保证「免 clone 检索」在单一 CDN 失效时仍可工作；可用 `BEACON_MIRRORS` 追加。
+- **serverInfo 版本对齐**：服务端自报版本改为读 `package.json`，不再硬编码，消除与 npm 包版本漂移。
+
+## 本次更新（v1.3.1，已发布）
 - **npm 包自带 rfq-kernel**：`prepack` 会把 `skills/rfq-kernel` 打进包内，因此 `npm i -g beacon-mfg-mcp`
   安装后 6 个 tool 全部可用（早于此版本的 npm 包不含该桥接，3 个寻源 tool 会降级）。
   GitHub Release tarball 同步包含 `rfq-kernel/`。
@@ -32,7 +40,7 @@ MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流
 ## 安装（三选一）
 
 ### 1. 从 GitHub Release 下载（推荐，零依赖）
-下载本 Release 的 `beacon-mfg-mcp-mcp-v1.3.1.tar.gz`，解压后：
+下载本 Release 的 `beacon-mfg-mcp-mcp-v1.3.2.tar.gz`，解压后：
 ```jsonc
 {
   "mcpServers": {
@@ -55,7 +63,7 @@ npx beacon-mfg-mcp
 ```jsonc
 {
   "mcpServers": {
-    "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [] }
+    "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [], "env": { "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8" } }
   }
 }
 ```
@@ -70,6 +78,8 @@ git clone https://github.com/eiry16/beacon-mfg.git
 - `BEACON_REPO`：本地 git 仓库路径；设了就用 `git show HEAD:` + 工作树 读（推荐：离线 + 掩码态隐私安全）。
 - `BEACON_SOURCE`：HTTP 基址，默认 `https://beacon-mfg.pages.dev`（可改自定义域名）。
 - `BEACON_WORKTREE`：本地模式是否优先读工作树（默认 `1`；设 `0` 恢复「只读已提交快照」）。
+- `BEACON_MIRRORS`：HTTP 模式追加的兜底镜像基址（逗号分隔）；默认源不可达时除内置的 jsDelivr/raw 外，可在此追加自有镜像。
+- `HTTPS_PROXY` / `HTTP_PROXY`：python 子进程的代理；在中国大陆等直连 GitHub 困难的网络，设 `HTTPS_PROXY=http://127.0.0.1:7890` 可让镜像链路走代理。
 
 ## 许可
 MIT

package/bin/beacon-mfg-mcp.js

@@ -26,5 +26,11 @@ if (!chosen) {
 
 const child = spawnSync(chosen, [serverPy, ...process.argv.slice(2)], {
   stdio: 'inherit',
+  // 显式锁定 UTF-8：中文 Windows 上 python 默认按 GBK 写 stdout，
+  // MCP 客户端按 UTF-8 解码会乱码。从启动器层面保证子进程用 UTF-8 输出。
+  env: Object.assign({}, process.env, {
+    PYTHONUTF8: '1',
+    PYTHONIOENCODING: 'utf-8',
+  }),
 });
 process.exit(child.status === null ? 1 : child.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Read-only MCP server exposing the BeaconMFG灯塔工厂 supplier directory (search vendors, get vendor detail, get capability card, multi-turn sourcing) to any MCP-compatible agent. No API key required.",
   "keywords": [
     "mcp",

package/server.py

@@ -208,6 +208,33 @@ _alias_cache: Optional[Dict[str, Any]] = None
 _gb_name_cache: Optional[Dict[str, str]] = None
 
 
+# 版本号单一来源：直接读同目录 package.json，避免 MCP 内部版本与发布包版本漂移。
+def _pkg_version() -> str:
+    try:
+        p = os.path.join(os.path.dirname(os.path.abspath(__file__)), "package.json")
+        with open(p, "r", encoding="utf-8") as f:
+            return json.load(f).get("version", "1.3.2")
+    except Exception:
+        return "1.3.2"
+
+
+# HTTP 基址列表（含兜底镜像）。默认部署 Cloudflare Pages 不可达时，自动回退到
+# GitHub 兜底镜像（与 Android App 同策略：pages.dev 主源 + jsDelivr / raw 镜像），
+# 保证「免 clone 检索」在单一 CDN 抖动/被墙时仍可工作。可用 BEACON_MIRRORS 追加自定义镜像。
+def _http_bases() -> List[str]:
+    bases = [BEACON_SOURCE]
+    if BEACON_SOURCE == DEFAULT_SOURCE:
+        bases.append("https://cdn.jsdelivr.net/gh/eiry16/beacon-mfg@main")
+        bases.append("https://raw.githubusercontent.com/eiry16/beacon-mfg/main")
+    m = os.environ.get("BEACON_MIRRORS")
+    if m:
+        for x in m.split(","):
+            x = x.strip().rstrip("/")
+            if x:
+                bases.append(x)
+    return bases
+
+
 # --------------------------------------------------------------------------- #
 # 使用量埋点（设计见 docs/MCP_USAGE_AUDIT.md §3.4 / §4 / §14）
 # --------------------------------------------------------------------------- #
@@ -362,48 +389,59 @@ def _git_show(relpath: str) -> Optional[str]:
     return None
 
 
+# 单基址 HTTP 超时（秒）。多镜像回退时每个基址各自计时，避免单一 CDN 卡死拖垮整体。
+_HTTP_TIMEOUT = 15
+
+
 def _http_get(relpath: str) -> Tuple[Optional[str], Optional[str]]:
-    url = BEACON_SOURCE + "/" + relpath
-    cap = _cache_path(url)
-    etag = None
-    if os.path.exists(cap):
+    """统一的 HTTP 读取：依次尝试 _http_bases() 中的基址（主源 + 兜底镜像），
+    任一成功即返回；全部失败则用本地缓存兜底（保证离线可用）。"""
+    cached_body = None
+    cached_etag = None
+    for base in _http_bases():
+        url = base + "/" + relpath
+        cap = _cache_path(url)
+        etag = None
+        if os.path.exists(cap):
+            try:
+                with open(cap, "r", encoding="utf-8") as f:
+                    blob = json.load(f)
+                etag = blob.get("etag")
+                cached_body = blob.get("body")
+                cached_etag = etag
+            except Exception:
+                etag = None
+        headers = {"User-Agent": UA, "Accept": "*/*"}
+        # 埋点头：服务端据此填 tool / tokens / hits 列。收不到也没关系 ——
+        # worker 那边**照样计数**，只是这三列为空（文档 §3.4）。
         try:
-            with open(cap, "r", encoding="utf-8") as f:
-                blob = json.load(f)
-            etag = blob.get("etag")
+            headers.update(_beacon_headers())
         except Exception:
-            etag = None
-    headers = {"User-Agent": UA, "Accept": "*/*"}
-    # 埋点头：服务端据此填 tool / tokens / hits 列。收不到也没关系 ——
-    # worker 那边**照样计数**，只是这三列为空（文档 §3.4）。
-    try:
-        headers.update(_beacon_headers())
-    except Exception:
-        pass
-    req = urllib.request.Request(url, headers=headers)
-    if etag:
-        req.add_header("If-None-Match", etag)
-    try:
-        resp = urllib.request.urlopen(req, timeout=30)
-        body = resp.read().decode("utf-8")
-        new_etag = resp.headers.get("ETag")
+            pass
+        req = urllib.request.Request(url, headers=headers)
+        if etag:
+            req.add_header("If-None-Match", etag)
         try:
-            with open(cap, "w", encoding="utf-8") as f:
-                json.dump({"etag": new_etag, "body": body}, f)
+            resp = urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT)
+            body = resp.read().decode("utf-8")
+            new_etag = resp.headers.get("ETag")
+            try:
+                with open(cap, "w", encoding="utf-8") as f:
+                    json.dump({"etag": new_etag, "body": body}, f)
+            except Exception:
+                pass
+            return body, new_etag
+        except urllib.error.HTTPError as e:
+            if e.code == 304 and cached_body is not None:
+                return cached_body, etag
+            continue
         except Exception:
-            pass
-        return body, new_etag
-    except urllib.error.HTTPError as e:
-        if e.code == 304 and os.path.exists(cap):
-            with open(cap, "r", encoding="utf-8") as f:
-                return json.load(f).get("body"), etag
-        return None, None
-    except Exception:
-        # 网络不通时若本地有缓存也返回，保证离线可用
-        if os.path.exists(cap):
-            with open(cap, "r", encoding="utf-8") as f:
-                return json.load(f).get("body"), etag
-        return None, None
+            # 当前基址不可达：尝试下一个兜底镜像；全部失败后在末尾用本地缓存兜底
+            continue
+    # 全部基址失败：若有任何本地缓存也返回，保证离线可用
+    if cached_body is not None:
+        return cached_body, cached_etag
+    return None, None
 
 
 def _worktree_read(relpath: str) -> Optional[str]:
@@ -1935,7 +1973,7 @@ def main() -> None:
                 "result": {
                     "protocolVersion": "2024-11-05",
                     "capabilities": {"tools": {}},
-                    "serverInfo": {"name": "beacon-mfg-readonly", "version": "1.3.0"},
+                    "serverInfo": {"name": "beacon-mfg-readonly", "version": _pkg_version()},
                 },
             })
         elif method == "notifications/initialized":