beacon-mfg-mcp 1.3.3 → 1.4.1

package/mcp_adapter.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+BeaconMFG MCP —— 标准协议适配层（adapter / shim）。
+
+为什么需要它：
+  beacon-mfg 的 mcp/server.py 用「换行分隔 JSON-RPC 子集」做传输
+  （`for raw in sys.stdin` + `json + "\n"`），并不是标准 MCP 的
+  `Content-Length` 分帧。标准 MCP 客户端（WorkBuddy 连接器、Claude Desktop
+  等）按 LSP 分帧跟它握手会解析失败。
+
+本适配层做什么：
+  - 对外（父进程 = MCP host）：讲标准 MCP stdio（Content-Length 分帧）。
+  - 对内（子进程 = server.py）：把请求转成换行分隔 JSON 转发，并把 server.py
+    的换行回包重新分帧后返回。
+  - 不修改 server.py 任何代码；server.py 的「通知无回包」语义天然保留
+    （转发通知后不等待回包）。
+
+用法：
+  python mcp_adapter.py
+环境变量（可选）：BEACON_REPO / BEACON_MASK_PHONE / BEACON_SOURCE
+"""
+import json
+import os
+import sys
+import subprocess
+import threading
+import queue
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+REPO = os.environ.get("BEACON_REPO") or os.path.dirname(_HERE)
+SERVER = os.path.join(_HERE, "server.py")
+MASK = os.environ.get("BEACON_MASK_PHONE", "1")
+
+
+def _spawn_server():
+    return subprocess.Popen(
+        [sys.executable, "-u", SERVER],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        env={**os.environ, "BEACON_REPO": REPO, "BEACON_MASK_PHONE": MASK},
+        bufsize=0, text=True, encoding="utf-8",
+    )
+
+
+def _read_stdin_framed():
+    """从父进程(stdio)读取一条标准 MCP 分帧消息，返回 dict；EOF 返回 None。"""
+    buf = b""
+    while True:
+        c = sys.stdin.buffer.read(1)
+        if not c:
+            return None
+        buf += c
+        if buf.endswith(b"\r\n\r\n") or buf.endswith(b"\n\n"):
+            break
+    clen = None
+    for line in buf.split(b"\n"):
+        low = line.strip().lower()
+        if low.startswith(b"content-length:"):
+            try:
+                clen = int(low.split(b":", 1)[1].strip())
+            except ValueError:
+                pass
+    if clen is None:
+        return None
+    body = b""
+    while len(body) < clen:
+        chunk = sys.stdin.buffer.read(clen - len(body))
+        if not chunk:
+            return None
+        body += chunk
+    try:
+        return json.loads(body.decode("utf-8"))
+    except Exception:
+        return None
+
+
+def _write_stdout_framed(obj):
+    """向父进程(stdio)写一条标准 MCP 分帧消息。"""
+    data = json.dumps(obj, ensure_ascii=False).encode("utf-8")
+    sys.stdout.buffer.write(b"Content-Length: %d\r\n\r\n" % len(data))
+    sys.stdout.buffer.write(data)
+    sys.stdout.buffer.flush()
+
+
+def main():
+    child = _spawn_server()
+    responses: "queue.Queue" = queue.Queue()
+    client_protocol = None  # 客户端在 initialize 里请求的协议版本
+
+    def reader():
+        # 子进程用换行分隔 JSON；逐行读、入队。
+        try:
+            for line in child.stdout:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except Exception:
+                    continue
+                responses.put(obj)
+        except Exception:
+            pass
+
+    threading.Thread(target=reader, daemon=True).start()
+
+    try:
+        while True:
+            msg = _read_stdin_framed()
+            if msg is None:
+                break
+            method = msg.get("method")
+            mid = msg.get("id")
+            is_notification = (mid is None) or (isinstance(method, str) and method.startswith("notifications/"))
+
+            if method == "initialize":
+                # 记下客户端请求版本，用于回包时回写（兼容严格客户端）
+                client_protocol = (msg.get("params") or {}).get("protocolVersion")
+
+            # 转发给子进程（换行分隔）
+            child.stdin.write(json.dumps(msg, ensure_ascii=False) + "\n")
+            child.stdin.flush()
+
+            if is_notification:
+                continue  # 通知无需回包，server.py 自身也是 continue
+
+            # 请求：等子进程回包（按到达顺序，server.py 严格顺序响应）
+            try:
+                resp = responses.get(timeout=60)
+            except queue.Empty:
+                if mid is not None:
+                    _write_stdout_framed({
+                        "jsonrpc": "2.0", "id": mid,
+                        "error": {"code": -32000, "message": "no response from server.py"},
+                    })
+                continue
+
+            # 兼容严格客户端：server.py 回的是固定 protocolVersion，
+            # 改写回客户端在 initialize 里请求的版本，避免握手因版本不一致卡住。
+            if method == "initialize" and client_protocol and isinstance(resp.get("result"), dict):
+                resp["result"]["protocolVersion"] = client_protocol
+
+            _write_stdout_framed(resp)
+    finally:
+        try:
+            child.terminate()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.3.3",
+  "version": "1.4.1",
   "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",
@@ -26,6 +26,8 @@
   "files": [
     "server.py",
     "http_server.py",
+    "mcp_adapter.py",
+    "test_protocol.py",
     "bin/",
     "rfq-kernel/",
     "copy-rfk.js",

package/server.py

@@ -43,6 +43,7 @@ import time
 import hmac
 import urllib.request
 import urllib.error
+import socket
 from typing import Any, Dict, List, Optional, Tuple
 import sys as _sys
 import uuid as _uuid
@@ -450,11 +451,74 @@ def _git_show(relpath: str) -> Optional[str]:
 _HTTP_TIMEOUT = 15
 
 
+# 记录最近一次全失败的诊断（供上层报错时引用，不进返回值以免破坏既有签名）
+_HTTP_LAST_ERROR: List[str] = [""]
+
+
+def _openers() -> List[Tuple[str, Any]]:
+    """构造 (标签, opener) 列表，**直连优先、代理兜底**。
+
+    为什么需要：urllib 默认读取环境里的 `*_proxy` 变量。客户机器上若配了
+    已失效的代理（VPN/Clash 退出、端口已关），所有请求都会被代理吃掉并失败，
+    表现为「无法取得 manifest.json」——报错完全没指向真因，客户无从下手。
+    这里把「绕过代理直连」作为**第一选择**，代理仅作兜底，并在全部失败时
+    给出明确诊断（见 `_http_diagnose`）。
+
+    仅在直连确实失败后才启用代理，因此不会破坏内网/反代等必须走代理的场景。
+    """
+    out: List[Tuple[str, Any]] = []
+    # 1) 直连（显式 no-proxy opener，忽略环境里的 *_proxy）
+    try:
+        out.append(("direct", urllib.request.build_opener(urllib.request.ProxyHandler({}))))
+    except Exception:
+        pass
+    # 2) 环境代理（若系统确实配置了可用代理，这里才会成功）
+    try:
+        if urllib.request.getproxies():
+            out.append(("proxy", urllib.request.build_opener()))
+    except Exception:
+        pass
+    # 3) 兜底：默认 opener
+    if not out:
+        out.append(("default", urllib.request.build_opener()))
+    return out
+
+
+def _http_diagnose(relpath: str, last_err: str = "") -> str:
+    """全部基址+全部连接方式都失败时，给出**指向真因**的诊断串。"""
+    hints = []
+    try:
+        proxies = urllib.request.getproxies()
+    except Exception:
+        proxies = {}
+    live = []
+    for k, v in proxies.items():
+        try:
+            host = v.split("//")[-1].split(":")[0].split("@")[-1]
+            port = v.rsplit(":", 1)[-1].split("/")[0]
+            s = socket.create_connection((host, int(port)), timeout=1.5)
+            s.close()
+            live.append("%s=%s" % (k, v))
+        except Exception:
+            hints.append("代理 %s=%s **不可用**（已退出/端口未监听）" % (k, v))
+    if live:
+        hints.append("可用代理: " + ", ".join(live))
+    if not hints:
+        hints.append("未检测到代理配置；可能是本机网络不可达或域名被阻断")
+    if last_err:
+        hints.append("最后错误: " + last_err)
+    return "；".join(hints)
+
+
 def _http_get(relpath: str) -> Tuple[Optional[str], Optional[str]]:
     """统一的 HTTP 读取：依次尝试 _http_bases() 中的基址（主源 + 兜底镜像），
-    任一成功即返回；全部失败则用本地缓存兜底（保证离线可用）。"""
+    任一成功即返回；全部失败则用本地缓存兜底（保证离线可用）。
+
+    连接方式上「直连优先、代理兜底」——避免失效代理把检索整体打挂。
+    """
     cached_body = None
     cached_etag = None
+    last_err = ""
     for base in _http_bases():
         url = base + "/" + relpath
         cap = _cache_path(url)
@@ -478,26 +542,29 @@ def _http_get(relpath: str) -> Tuple[Optional[str], Optional[str]]:
         req = urllib.request.Request(url, headers=headers)
         if etag:
             req.add_header("If-None-Match", etag)
-        try:
-            resp = urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT)
-            body = resp.read().decode("utf-8")
-            new_etag = resp.headers.get("ETag")
+        for _tag, opener in _openers():
             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:
-            # 当前基址不可达：尝试下一个兜底镜像；全部失败后在末尾用本地缓存兜底
-            continue
+                resp = opener.open(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
+                last_err = "HTTP %s" % e.code
+                break   # HTTP 层错误，换基址比重试连接方式有意义
+            except Exception as e:
+                last_err = "%s: %s" % (type(e).__name__, e)
+                continue   # 连接层失败（典型：代理不可用）→ 换连接方式
     # 全部基址失败：若有任何本地缓存也返回，保证离线可用
     if cached_body is not None:
         return cached_body, cached_etag
+    _HTTP_LAST_ERROR[0] = _http_diagnose(relpath, last_err)
     return None, None
 
 
@@ -565,7 +632,15 @@ def load_manifest() -> Dict[str, Any]:
     if _cache_stale(_manifest_cache, "data/manifest.json"):
         txt = fetch_text("data/manifest.json")
         if not txt:
-            raise RuntimeError("无法取得 manifest.json（检查 BEACON_SOURCE / BEACON_REPO / 网络）")
+            # 报错必须指向真因：把 _http_get 记下的连接层诊断（失效代理 / 网络不可达 /
+            # 域名阻断）带上，否则客户只看到「检查网络」却无从下手。
+            detail = _HTTP_LAST_ERROR[0] or "无缓存且所有镜像均不可达"
+            raise RuntimeError(
+                "无法取得 manifest.json。诊断：" + detail
+                + "。可尝试：① 检查系统代理/VPN 是否已退出或端口未监听；"
+                + "② 设置 BEACON_SOURCE 指向自建镜像；"
+                + "③ 设置 BEACON_REPO 指向本地仓库以完全离线使用。"
+            )
         _manifest_cache = (json.loads(txt), time.time(), _wt_mtime("data/manifest.json"))
     return _manifest_cache[0]
 

package/test_protocol.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+BeaconMFG MCP —— 发布前协议回归测试（pre-release smoke test）。
+
+为什么需要它
+------------
+`server.py` 同时服务两条链路：本地 stdio（npm / git 安装）与远程 Streamable HTTP
+（`http_server.py`）。业务逻辑一改，两条链路都可能悄悄坏掉，且**症状隐蔽**
+（能握手但查不出数据、或只有部分工具挂掉）。本脚本把「协议能握手 + 工具齐全 +
+真实检索有结果」三件事固化为一条命令，每次发版前跑一遍。
+
+用法
+----
+    python mcp/test_protocol.py                 # 自动起 HTTP 端点自测
+    python mcp/test_protocol.py --stdio         # 额外测 stdio(server.py)
+    python mcp/test_protocol.py --adapter       # 额外测标准分帧适配层
+    BEACON_REPO=/path/to/repo python mcp/test_protocol.py
+
+退出码：0 全部通过；1 有失败项。
+"""
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SERVER = os.path.join(HERE, "server.py")
+HTTP_SERVER = os.path.join(HERE, "http_server.py")
+ADAPTER = os.path.join(HERE, "mcp_adapter.py")
+
+EXPECT_TOOLS = {
+    "search_vendors", "get_vendor", "get_capability_card",
+    "start_sourcing", "answer_sourcing", "refine_sourcing",
+}
+
+# 三个城市各取一个高频词，覆盖不同行业与不同分片，避免「只测通一个分片」
+SMOKE_QUERIES = [("修车", "嘉兴"), ("面馆", "苏州"), ("米粉", "贵阳")]
+
+_results = []
+
+
+def _check(name, ok, detail=""):
+    _results.append((name, bool(ok), detail))
+    print("  %s %s%s" % ("PASS" if ok else "FAIL", name, ("  -> " + detail) if detail else ""))
+    return ok
+
+
+def _child_env():
+    env = dict(os.environ)
+    env.setdefault("BEACON_MASK_PHONE", "1")
+    env["PYTHONUTF8"] = "1"
+    env["PYTHONIOENCODING"] = "utf-8"
+    return env
+
+
+# --------------------------------------------------------------------------
+# 公共断言：拿到工具列表 + 跑真实检索
+# --------------------------------------------------------------------------
+def _assert_tools_and_search(call, label):
+    """call(method, params, session_id) -> result dict"""
+    r = call("initialize", {
+        "protocolVersion": "2024-11-05", "capabilities": {},
+        "clientInfo": {"name": "smoke", "version": "1"},
+    })
+    _check("%s initialize" % label, r is not None and "result" in r, "" if r else "无回包")
+
+    # 通知无回包（规范允许），不要等
+    try:
+        call("notifications/initialized", {}, r.get("__sid__") if isinstance(r, dict) else None)
+    except Exception:
+        pass
+
+    r2 = call("tools/list", {})
+    tools = set()
+    if r2 and "result" in r2:
+        tools = {t.get("name") for t in r2["result"].get("tools", [])}
+    missing = EXPECT_TOOLS - tools
+    _check("%s tools/list (6)" % label, not missing, ("缺: " + ",".join(missing)) if missing else "")
+
+    for q, city in SMOKE_QUERIES:
+        r3 = call("tools/call", {"name": "search_vendors",
+                                 "arguments": {"query": q, "city": city, "limit": 3}})
+        n, err = 0, ""
+        if r3 and "result" in r3:
+            try:
+                data = json.loads(r3["result"]["content"][0]["text"])
+                n = len(data.get("results", []))
+            except Exception as e:
+                err = "解析失败 %s" % e
+        else:
+            err = "无回包"
+        _check("%s search %s/%s" % (label, city, q), n > 0, err or "命中 %d" % n)
+
+
+# --------------------------------------------------------------------------
+# 1) Streamable HTTP（http_server.py）
+# --------------------------------------------------------------------------
+def test_http():
+    print("\n[1/3] Streamable HTTP  (mcp/http_server.py)")
+    port = int(os.environ.get("MCP_TEST_PORT", "8899"))
+    env = _child_env()
+    env["MCP_PORT"] = str(port)
+    proc = subprocess.Popen([sys.executable, "-u", HTTP_SERVER],
+                            env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    base = "http://127.0.0.1:%d/mcp" % port
+    try:
+        # 等端口起来
+        for _ in range(40):
+            try:
+                urllib.request.urlopen("http://127.0.0.1:%d/health" % port, timeout=1).read()
+                break
+            except Exception:
+                time.sleep(0.25)
+        else:
+            _check("HTTP 端点启动", False, "40 次探测仍未就绪")
+            return
+
+        def call(method, params, sid=None):
+            payload = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+            if method.startswith("notifications/"):
+                payload.pop("id")
+            data = json.dumps(payload).encode()
+            req = urllib.request.Request(base, data=data, method="POST")
+            req.add_header("Content-Type", "application/json")
+            req.add_header("Accept", "application/json, text/event-stream")
+            if sid:
+                req.add_header("Mcp-Session-Id", sid)
+            with urllib.request.urlopen(req, timeout=90) as resp:
+                new_sid = resp.headers.get("Mcp-Session-Id")
+                body = resp.read().decode()
+            if method.startswith("notifications/"):
+                return None
+            obj = json.loads(body)
+            if new_sid:
+                obj["__sid__"] = new_sid
+            return obj
+
+        _assert_tools_and_search(call, "http")
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except Exception:
+            proc.kill()
+
+
+# --------------------------------------------------------------------------
+# 2) 换行分隔 stdio（server.py）—— npm/git 安装走的默认链路
+# --------------------------------------------------------------------------
+def test_stdio():
+    print("\n[2/3] stdio 换行分隔  (mcp/server.py)")
+    proc = subprocess.Popen([sys.executable, "-u", SERVER], stdin=subprocess.PIPE,
+                            stdout=subprocess.PIPE, env=_child_env(),
+                            encoding="utf-8", bufsize=1)
+    try:
+        def send(method, params, notify=False):
+            msg = {"jsonrpc": "2.0", "method": method, "params": params}
+            if not notify:
+                msg["id"] = 1
+            proc.stdin.write(json.dumps(msg, ensure_ascii=False) + "\n")
+            proc.stdin.flush()
+            if notify:
+                return None
+            return json.loads(proc.stdout.readline())
+
+        def call(method, params, sid=None):
+            if method.startswith("notifications/"):
+                return send(method, params, notify=True)
+            return send(method, params)
+
+        _assert_tools_and_search(call, "stdio")
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except Exception:
+            proc.kill()
+
+
+# --------------------------------------------------------------------------
+# 3) 标准分帧适配层（mcp_adapter.py）—— 严格客户端走这条
+# --------------------------------------------------------------------------
+def test_adapter():
+    print("\n[3/3] 标准分帧适配层  (mcp/mcp_adapter.py)")
+    proc = subprocess.Popen([sys.executable, "-u", ADAPTER], stdin=subprocess.PIPE,
+                            stdout=subprocess.PIPE, env=_child_env(), bufsize=0)
+
+    def send(obj):
+        data = json.dumps(obj, ensure_ascii=False).encode()
+        proc.stdin.write(b"Content-Length: %d\r\n\r\n" % len(data) + data)
+        proc.stdin.flush()
+
+    def recv():
+        hdr = b""
+        while not hdr.endswith(b"\r\n\r\n"):
+            c = proc.stdout.read(1)
+            if not c:
+                return None
+            hdr += c
+        n = 0
+        for line in hdr.split(b"\r\n"):
+            if line.lower().startswith(b"content-length:"):
+                n = int(line.split(b":")[1].strip())
+        body = b""
+        while len(body) < n:
+            chunk = proc.stdout.read(n - len(body))
+            if not chunk:
+                return None
+            body += chunk
+        return json.loads(body.decode("utf-8"))
+
+    def call(method, params, sid=None):
+        msg = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+        if method.startswith("notifications/"):
+            msg.pop("id")
+            send(msg)
+            return None
+        send(msg)
+        return recv()
+
+    try:
+        _assert_tools_and_search(call, "adapter")
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except Exception:
+            proc.kill()
+
+
+def test_dead_proxy():
+    """死代理容错：环境里配了**不可用**代理时，仍应直连成功（回归 #100086）。
+
+    背景：客户机器上若配了已失效的代理（VPN/Clash 退出、端口已关），
+    urllib 会把所有请求喂给死代理 → 检索整体归零，且旧报错「检查网络」不指向真因。
+    修法见 server.py 的 `_openers()`：直连优先、代理兜底。
+    """
+    print("\n[*] 死代理容错  (直连优先)")
+    env = _child_env()
+    env.pop("BEACON_REPO", None)          # 强制走联网，才能真正触发网络取数
+    for k in ("http_proxy", "https_proxy", "HTTP_PROXY", "HTTPS_PROXY"):
+        env[k] = "http://127.0.0.1:9"     # 9 = discard 端口，几乎必然拒绝
+    env["BEACON_MIRRORS"] = ""             # 别被本地镜像配置干扰
+    proc = subprocess.Popen([sys.executable, "-u", SERVER], stdin=subprocess.PIPE,
+                            stdout=subprocess.PIPE, env=env, encoding="utf-8", bufsize=1)
+    try:
+        def send(method, params, notify=False):
+            msg = {"jsonrpc": "2.0", "method": method, "params": params}
+            if not notify:
+                msg["id"] = 1
+            else:
+                msg.pop("id", None)
+            proc.stdin.write(json.dumps(msg, ensure_ascii=False) + "\n")
+            proc.stdin.flush()
+            if notify:
+                return None
+            return json.loads(proc.stdout.readline())
+
+        send("initialize", {"protocolVersion": "2024-11-05", "capabilities": {},
+                            "clientInfo": {"name": "smoke", "version": "1"}})
+        send("notifications/initialized", {}, notify=True)
+        r = send("tools/call", {"name": "search_vendors",
+                                "arguments": {"query": "面馆", "city": "苏州", "limit": 3}})
+        n, err = 0, ""
+        if r and "result" in r:
+            try:
+                n = len(json.loads(r["result"]["content"][0]["text"]).get("results", []))
+            except Exception as e:
+                err = "解析失败 %s" % e
+        else:
+            err = "无回包（很可能被死代理拖累）"
+        _check("dead-proxy 苏州/面馆", n > 0, err or "命中 %d" % n)
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except Exception:
+            proc.kill()
+
+
+def main():
+    print("=" * 60)
+    print("BeaconMFG MCP 协议回归测试")
+    print("数据源: BEACON_REPO=%s" % (os.environ.get("BEACON_REPO") or "(默认/联网)"))
+    print("=" * 60)
+
+    test_http()
+    if "--stdio" in sys.argv:
+        test_stdio()
+    if "--adapter" in sys.argv:
+        test_adapter()
+    else:
+        print("\n[2/3] stdio  (跳过，加 --stdio 启用)")
+        print("[3/3] adapter (跳过，加 --adapter 启用)")
+    test_dead_proxy()
+
+    passed = sum(1 for _, ok, _ in _results if ok)
+    failed = [(n, d) for n, ok, d in _results if not ok]
+    print("\n" + "=" * 60)
+    print("结果: %d 通过, %d 失败" % (passed, len(failed)))
+    for n, d in failed:
+        print("  FAIL %s  %s" % (n, d))
+    print("=" * 60)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())