ht32-code-mcp 0.5.0__tar.gz → 0.5.2__tar.gz

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.2}/DEPLOY.md

@@ -25,7 +25,7 @@ MCP 与 bundle 都跑在应用机（Linux 本地机），云端 OpenResty 只做
             ht32-bundles-web   宿主 18082 → 容器 80     /ht32-bundles
 ```
 
-反代配置原文在**工作区** `maintenance/openresty/`（`ht32-code.conf` / `ht32-bundles.conf` / `default.conf`），
+反代配置原文在**工作区独立仓库** `ht32-mcp-maint/openresty/`（`ht32-code.conf` / `ht32-bundles.conf` / `default.conf`），
 手工贴进 1Panel 站点 `mcp.s621.work` 的同一个 server 块。`/ht32-bundles` **必须反代**
 到 `100.66.1.6:18082`，且 `proxy_pass` 不能带尾斜杠。
 
@@ -42,15 +42,14 @@ PyPI 包 → FastMCP 直接提供 Streamable HTTP（常驻单进程）
 
 ### 镜像与端点
 
-- 镜像 `ht32-code-mcp:0.5.0`：`ghcr.io/astral-sh/uv:python3.12-bookworm-slim` +
-  `git/curl/ca-certificates`，`uv tool install ht32-code-mcp==0.5.0`，入口直跑
+- 镜像 `ht32-code-mcp:0.5.1`：`ghcr.io/astral-sh/uv:python3.12-bookworm-slim` +
+  `git/curl/ca-certificates`，`uv tool install ht32-code-mcp==0.5.1`，入口直跑
   `ht32-code-mcp`（私有组件能力仍需服务端 git）。由 `.work/docker/Dockerfile` 构建。
 - 传输：生产 `MCP_TRANSPORT=streamable-http`，`path=/ht32-code`（`MCP_PATH` 注入）；
   本地调试保持默认 `/mcp`。`stdio` 仅供冒烟测试。
 - `MCP_JSON_RESPONSE=0`：保持 SSE，兼容现有客户端。
 - 健康检查：`GET /health` → `{"status":"ok","version":"<包版本>"}`，不触发检索。
-- 资源：`mem_limit: 1g` / `cpus: 1.0` / `pids_limit: 512`（常驻单进程与多会话对象）；
-  不再使用 V1 按「一会话一进程」算出的 `4g` / `1024` 熔断值。
+- 资源：`mem_limit: 1g` / `cpus: 1.0` / `pids_limit: 512`（常驻单进程与多会话对象）。
 
 ## compose 关键配置
 
@@ -66,7 +65,7 @@ PyPI 包 → FastMCP 直接提供 Streamable HTTP（常驻单进程）
 | `COMPONENTS_CONFIG` | `/app/code/.work/components/components.json` |
 | `COMPONENTS_STATE_FILE` | `/app/feedback/component-tag-lock.json` |
 | 凭据 | `.work/docker/.env` 的 `COMPONENTS_GIT_AUTH`（base64 用户名:只读 token），已 gitignore |
-| `MCP_TRANSPORT` | `streamable-http`（不经 supergateway） |
+| `MCP_TRANSPORT` | `streamable-http`（容器直跑，无中间网关） |
 | `MCP_HOST` / `MCP_PORT` | `0.0.0.0` / `8001` |
 | `MCP_PATH` | `/ht32-code`（须与反代 location 一致） |
 | `MCP_STATELESS_HTTP` | `0`（P0 保留进程内有状态会话） |
@@ -140,7 +139,7 @@ location ^~ /ht32-bundles {
 
 | 通道 | 文件 | 触发 | 内容 |
 |------|------|------|------|
-| 用量日志 | `usage_*.jsonl` | 服务端自动（middleware） | 工具名、参数原文、耗时、成败、session |
+| 用量日志 | `usage_*.jsonl` | 服务端自动（middleware） | 工具名、参数原文、耗时、成败、session、客户端身份（`client_name`/`client_version`，取自 initialize 的 `clientInfo`） |
 | 反馈 | `feedback_*.jsonl` | Agent 主动（`submit_feedback`） | 语义性问题 |
 
 - `FEEDBACK_ROOT` 为空 = 整体关闭（本地开发默认不落盘）；必须填**绝对路径**。
@@ -272,8 +271,8 @@ curl -s -o /dev/null -w "%{http_code}" https://mcp.s621.work/ht32-code   # 400 =
 ```
 
 - 启动日志应含 `启动服务: Streamable HTTP 0.0.0.0:8001/ht32-code（stateless=False, json=False）`；
-  若仍见 supergateway / `--stateful`，说明服务器 compose 未同步或镜像未重建
-- 协议版本被拒 → 旧镜像或旧客户端；本版直接由 FastMCP 4.x 提供，不再经 supergateway
+  否则检查服务器 compose 与镜像是否已同步
+- 协议版本被拒 → 检查镜像版本与客户端协议版本
 - `/health` 404 → 进程是旧版（`MCP_PATH` 之前的版本没有该路由）
 - 容器 126 退出 → 旧 compose 的 `$$(...)` 命令替换被吃掉；新版无 `command`，重新 `git pull` 即可
 - 首会话超时 → 冷启动（索引加载）；容器健康检查 `start_period: 60s` 已留余量

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.5.0
+Version: 0.5.2
 Summary: HT32 Code MCP Server - 为 AI Agent 提供 HT32 函数库/例程/模板检索与工程导出
 License-Expression: MIT
 Keywords: firmware,holtek,ht32,mcp,mcu

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.2}/README.md

@@ -1,8 +1,8 @@
 # .work/mcp-server/
 
-MCP server 代码目录（Python + FastMCP），实现 11 个检索/导出工具 + 版本检查 + 1 个反馈工具。
+MCP server 代码目录（Python + FastMCP），实现 **13 个工具**（检索/导出/组件/版本检查/反馈）。
 
-传输由 `MCP_TRANSPORT` 决定：`stdio`（默认，供 supergateway 包装）/ `streamable-http` / `sse`。
+传输由 `MCP_TRANSPORT` 决定：`stdio`（本地调试/冒烟）/ `streamable-http`（线上，FastMCP 常驻单进程）/ `sse`（旧客户端兼容）。
 部署与排错见 [DEPLOY.md](DEPLOY.md)。
 
 ## 私有组件（0.4.5+）

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ht32-code-mcp"
-version = "0.5.0"
+version = "0.5.2"
 description = "HT32 Code MCP Server - 为 AI Agent 提供 HT32 函数库/例程/模板检索与工程导出"
 requires-python = ">=3.11"
 license = "MIT"

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.2}/src/ht32_code_mcp/server.py

@@ -847,7 +847,9 @@ def check_skill_update(current: str = "") -> str:
     Args:
         current: 本机已安装的 ht32-skills 版本，取
             `python "<global-skill-root>\\_ht32-runtime\\ht32.py" version` 的
-            `skill_version`（如 "v0.1.0"）；拿不到就留空，报告会说明如何补
+            `skill_version`（如 "v0.1.0"）；拿不到就留空，报告会说明如何补。
+            传入的版本会记到本 MCP 会话，本次会话后续的 usage 记录均带上
+            `skill_version`（服务端拿不到客户端版本，只能靠这里带入）
     """
     return update_report(CODE_ROOT, current)
 

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.2}/src/ht32_code_mcp/usage.py

@@ -7,10 +7,14 @@
 两条采集通道，写入同一目录树：
 
 - **tool_call**（`UsageMiddleware`，服务端自动）：拦截所有工具调用，
-  记录工具名、参数原文、耗时、成败。不依赖 Agent 配合，数据完整。
+  记录工具名、参数原文、耗时、成败，以及 MCP `initialize` 请求里的客户端身份
+  （`client_info.name` / `client_info.version` → 日志字段 `client_name` /
+  `client_version`，老客户端未上报时为空串）。不依赖 Agent 配合，数据完整。
 - **feedback**（`record_feedback`，由各 server 的 `submit_feedback` 工具调用）：
   记录 Agent 主动上报的语义性问题，middleware 无法判断这些。其中 `skill_version`
   由 Agent 自报（服务端跨进程拿不到客户端 skill 版本），用于定位 ht32-skills 缺陷版本。
+  同一版本还会按 MCP 会话记住（见 `SKILL_VERSION_ARGS`），该会话后续的 tool_call
+  记录也会带上 `skill_version`；上报之前或无 session 的调用仍为空串。
 
 目录布局（同根 + 服务子目录）：
 
@@ -39,7 +43,7 @@ from typing import Any
 from fastmcp.server.middleware import Middleware, MiddlewareContext
 
 # 实现版本号：两仓库副本必须一致（各仓测试会校验，防止只改一边造成漂移）
-_IMPL_VERSION = "1.2.0"
+_IMPL_VERSION = "1.4.0"
 
 # 服务名 → 子目录名。新增服务在此登记。
 SERVICE_WIKI = "wiki"
@@ -124,12 +128,35 @@ def write_record(log_dir: str, prefix: str, record: dict[str, Any]) -> Path | No
         return None
 
 
+def _initialize_client(ctx: Any) -> tuple[str, str]:
+    """从 MCP `initialize` 的 `clientInfo` 取客户端名与版本。
+
+    FastMCP 4 / MCP SDK 2 把 initialize 参数常驻在会话底层 Connection 上
+    （`session.client_params.client_info`），initialize 时写一次、整段会话只读，
+    因此工具调用阶段可直接读取，无需另建缓存，也就不存在并发写竞态。
+    取不到（无会话 / 客户端未上报 / 字段缺失 / 访问抛错）一律返回空串。
+    """
+    try:
+        session = getattr(ctx, "session", None)
+        params = getattr(session, "client_params", None) if session is not None else None
+        info = getattr(params, "client_info", None) if params is not None else None
+        if info is None:
+            return "", ""
+        return str(getattr(info, "name", "") or ""), str(getattr(info, "version", "") or "")
+    except Exception:  # noqa: BLE001 - 采集失败绝不能影响工具调用本身
+        return "", ""
+
+
 def _client_info(context: MiddlewareContext) -> dict[str, str]:
-    """取客户端标识（内存调用等无 session 的场景返回空值）。"""
+    """取客户端标识（内存调用等无 session 的场景返回空值）。
+
+    `client_name` / `client_version` 恒定存在：老客户端未上报 clientInfo 时为空串，
+    保证日志行字段结构不变形。
+    """
+    out: dict[str, str] = {"client_name": "", "client_version": ""}
     ctx = getattr(context, "fastmcp_context", None)
     if ctx is None:
-        return {}
-    out: dict[str, str] = {}
+        return out
     for key in ("client_id", "session_id"):
         val = getattr(ctx, key, None)
         if val:
@@ -137,9 +164,68 @@ def _client_info(context: MiddlewareContext) -> dict[str, str]:
     transport = getattr(ctx, "transport", None)
     if transport:
         out["transport"] = str(transport)
+    out["client_name"], out["client_version"] = _initialize_client(ctx)
     return out
 
 
+# ---- 客户端 skill 版本（会话级）--------------------------------------------
+# usage 在服务端采集，跨进程拿不到客户端 ht32-skills 版本，只能由 Agent 在上报型
+# 工具里带入。这些工具的参数名登记如下：中间件记录调用时顺手把版本记到当前 MCP
+# 会话，该会话**后续所有** tool_call 都补 skill_version 字段。
+SKILL_VERSION_ARGS = {
+    "check_skill_update": "current",      # code：会话开始查更新（顺带上报版本）
+    "submit_feedback": "skill_version",   # code / wiki：提交反馈
+    "report_skill_version": "version",    # wiki：会话开始主动上报
+}
+# 常驻进程会持续接新会话，会话表设上限，超出按插入顺序淘汰最老的
+_MAX_SKILL_SESSIONS = 512
+_SESSION_SKILL_VERSION: dict[str, str] = {}
+
+
+def _session_key(context: Any) -> str:
+    """会话标识（MiddlewareContext 或工具 Context 皆可）；取不到返回空串。
+
+    stdio / in-memory 下 FastMCP 的 session_id 是每请求新生成的 UUID，直接拿来
+    做键会永远 miss；这两种传输一个进程只服务一个客户端，故统一用固定键。
+    HTTP 才有稳定的 mcp-session-id，按它隔离多用户会话。
+    """
+    ctx = getattr(context, "fastmcp_context", None)
+    if ctx is None:
+        ctx = context
+    try:
+        transport = str(getattr(ctx, "transport", "") or "")
+    except Exception:
+        transport = ""
+    if transport in ("", "memory", "stdio"):
+        return "local"
+    for key in ("session_id", "client_id"):
+        try:
+            val = getattr(ctx, key, None)
+        except Exception:
+            continue
+        if val:
+            return f"{key}:{val}"
+    return ""
+
+
+def remember_skill_version(context: Any, version: str) -> None:
+    """把客户端上报的 ht32-skills 版本记到当前会话（供 usage 打标）。"""
+    ver = (version or "").strip()
+    key = _session_key(context)
+    if not ver or not key:
+        return
+    _SESSION_SKILL_VERSION.pop(key, None)
+    while len(_SESSION_SKILL_VERSION) >= _MAX_SKILL_SESSIONS:
+        _SESSION_SKILL_VERSION.pop(next(iter(_SESSION_SKILL_VERSION)), None)
+    _SESSION_SKILL_VERSION[key] = ver
+
+
+def session_skill_version(context: Any) -> str:
+    """当前会话已上报的 ht32-skills 版本；没有则空串。"""
+    key = _session_key(context)
+    return _SESSION_SKILL_VERSION.get(key, "") if key else ""
+
+
 class UsageMiddleware(Middleware):
     """把所有工具调用落成 JSONL（服务端自动采集）。"""
 
@@ -156,6 +242,12 @@ class UsageMiddleware(Middleware):
 
         args = dict(context.message.arguments or {})
         recorded = {k: v for k, v in args.items() if k not in ARG_NOISE}
+        # 上报型工具：先把版本记到当前会话，本次记录也会带上它
+        ver_arg = SKILL_VERSION_ARGS.get(context.message.name)
+        if ver_arg:
+            val = args.get(ver_arg)
+            if isinstance(val, str):
+                remember_skill_version(context, val)
         started = time.perf_counter()
         error = ""
         ok = True
@@ -186,6 +278,7 @@ class UsageMiddleware(Middleware):
                 "error": error,
                 "mcp_version": self.mcp_version,
                 "kb_version": self.kb_version,
+                "skill_version": session_skill_version(context),
                 **_client_info(context),
             }
             write_record(self.log_dir, USAGE_PREFIX, record)

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.2}/tests/test_tools.py

@@ -679,13 +679,43 @@ def test_version_reports_skill_latest(monkeypatch):
 def test_usage_impl_version_pinned():
     """两仓库的 usage.py 是逐字节相同副本，实现版本号用于防止只改一边。"""
     from ht32_code_mcp import usage
-    assert usage._IMPL_VERSION == "1.2.0"
+    assert usage._IMPL_VERSION == "1.4.0"
     assert usage.SERVICE_CODE == "code"
     assert usage.SERVICE_WIKI == "wiki"
     # 噪声参数含 out_dir（code 特有：可能含用户本地路径）
     assert {"limit", "max_length", "out_dir"} <= usage.ARG_NOISE
 
 
+def test_usage_client_info_from_initialize():
+    """initialize 的 clientInfo 落到 client_name/client_version；缺失时不报错且为空串。"""
+    from types import SimpleNamespace
+
+    from fastmcp.server.middleware import MiddlewareContext
+
+    from ht32_code_mcp.usage import _client_info
+
+    def fake_ctx(**kwargs):
+        return MiddlewareContext(message=None, fastmcp_context=SimpleNamespace(**kwargs))
+
+    with_info = fake_ctx(
+        transport="streamable-http", session_id="s1", client_id=None,
+        session=SimpleNamespace(client_params=SimpleNamespace(
+            client_info=SimpleNamespace(name="Trae", version="3.4.15"))))
+    info = _client_info(with_info)
+    assert info["client_name"] == "Trae"
+    assert info["client_version"] == "3.4.15"
+
+    # 老客户端 / 现代协议未带 clientInfo：字段仍在，值为空串，且不抛错
+    for no_info in (
+        fake_ctx(transport="stdio", session_id="s2", client_id=None,
+                 session=SimpleNamespace(client_params=None)),
+        fake_ctx(transport="stdio", session_id="s3", client_id=None,
+                 session=SimpleNamespace(client_params=SimpleNamespace(client_info=None))),
+    ):
+        out = _client_info(no_info)
+        assert out["client_name"] == "" and out["client_version"] == ""
+
+
 def test_soft_failure_marker_semantics():
     """软失败判定口径 = 工具是否完成工作。
 
@@ -838,10 +868,66 @@ def test_usage_middleware_records_calls(tmp_path):
     assert ok_rec["duration_ms"] >= 0
     assert ok_rec["mcp_version"] == "0.1.4"
     assert ok_rec["kb_version"] == "v0.1.0"
+    # 客户端身份字段恒定存在（内存客户端可能未上报 clientInfo → 空串）
+    assert isinstance(ok_rec["client_name"], str)
+    assert isinstance(ok_rec["client_version"], str)
     assert fail_rec["tool"] == "boom" and fail_rec["ok"] is False
     assert "deliberate" in fail_rec["error"]
 
 
+def test_usage_middleware_tags_session_skill_version(tmp_path):
+    """上报型工具带来客户端 skill 版本：按会话记住，后续调用都带上；
+    没上报过的会话保持空串（不跨会话串号）。"""
+    import asyncio
+
+    from fastmcp import Client, FastMCP
+
+    app = FastMCP("mw-skill")
+    app.add_middleware(UsageMiddleware(str(tmp_path / "logs"), "code",
+                                       mcp_version="0.5.1", kb_version="v0.4.0"))
+
+    @app.tool()
+    def check_skill_update(current: str = "") -> str:
+        return f"current={current}"
+
+    @app.tool()
+    def probe(chip: str) -> str:
+        return "ok:" + chip
+
+    async def run():
+        # in-memory 传输按"本进程唯一客户端"归键：上报前 → 上报 → 上报后
+        async with Client(app) as c:
+            await c.call_tool("probe", {"chip": "before"})
+            await c.call_tool("check_skill_update", {"current": "v0.1.34"})
+            await c.call_tool("probe", {"chip": "after"})
+
+    asyncio.run(run())
+    recs = [json.loads(l) for l in
+            next((tmp_path / "logs").glob("usage_*.jsonl"))
+            .read_text(encoding="utf-8").splitlines()]
+    assert [r.get("skill_version") for r in recs] == ["", "v0.1.34", "v0.1.34"]
+    # 上报调用本身仍保留原始参数
+    assert recs[1]["args"] == {"current": "v0.1.34"}
+
+
+def test_skill_version_isolated_per_http_session():
+    """HTTP 传输按 session_id 隔离：A 上报的版本不会串到 B 的会话。"""
+    from types import SimpleNamespace
+
+    from ht32_code_mcp.usage import remember_skill_version, session_skill_version
+
+    def fake_ctx(sid: str):
+        return SimpleNamespace(fastmcp_context=SimpleNamespace(
+            transport="streamable-http", session_id=sid, client_id=None))
+
+    remember_skill_version(fake_ctx("sess-a"), "v0.1.34")
+    assert session_skill_version(fake_ctx("sess-a")) == "v0.1.34"
+    assert session_skill_version(fake_ctx("sess-b")) == ""
+    # 空版本 / 无会话不落表
+    remember_skill_version(fake_ctx("sess-b"), "  ")
+    assert session_skill_version(fake_ctx("sess-b")) == ""
+
+
 def test_usage_middleware_records_soft_failure(tmp_path):
     """工具返回错误字符串（不抛异常）时，middleware 应记 ok=false 并留错误原文。"""
     import asyncio

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.2}/uv.lock

@@ -440,7 +440,7 @@ wheels = [
 
 [[package]]
 name = "ht32-code-mcp"
-version = "0.5.0"
+version = "0.5.2"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },

ht32_code_mcp-0.5.0/.pytest_base_final_run.log

@@ -1,4 +0,0 @@
-........................................................................ [ 93%]
-.....                                                                    [100%]
-77 passed in 271.49s (0:04:31)
-EXIT=0