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

{ht32_code_mcp-0.5.0 → ht32_code_mcp-0.5.1}/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` 不能带尾斜杠。
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.5.0
+Version: 0.5.1
 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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ht32-code-mcp"
-version = "0.5.0"
+version = "0.5.1"
 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.1}/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.1}/src/ht32_code_mcp/usage.py

@@ -11,6 +11,8 @@
 - **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 +41,7 @@ from typing import Any
 from fastmcp.server.middleware import Middleware, MiddlewareContext
 
 # 实现版本号：两仓库副本必须一致（各仓测试会校验，防止只改一边造成漂移）
-_IMPL_VERSION = "1.2.0"
+_IMPL_VERSION = "1.3.0"
 
 # 服务名 → 子目录名。新增服务在此登记。
 SERVICE_WIKI = "wiki"
@@ -140,6 +142,64 @@ def _client_info(context: MiddlewareContext) -> dict[str, str]:
     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 +216,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 +252,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.1}/tests/test_tools.py

@@ -679,7 +679,7 @@ 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.3.0"
     assert usage.SERVICE_CODE == "code"
     assert usage.SERVICE_WIKI == "wiki"
     # 噪声参数含 out_dir（code 特有：可能含用户本地路径）
@@ -842,6 +842,59 @@ def test_usage_middleware_records_calls(tmp_path):
     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.1}/uv.lock

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