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

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

@@ -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.1 → ht32_code_mcp-0.5.2}/PKG-INFO

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

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

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

@@ -7,7 +7,9 @@
 两条采集通道，写入同一目录树：
 
 - **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 缺陷版本。
@@ -41,7 +43,7 @@ from typing import Any
 from fastmcp.server.middleware import Middleware, MiddlewareContext
 
 # 实现版本号：两仓库副本必须一致（各仓测试会校验，防止只改一边造成漂移）
-_IMPL_VERSION = "1.3.0"
+_IMPL_VERSION = "1.4.0"
 
 # 服务名 → 子目录名。新增服务在此登记。
 SERVICE_WIKI = "wiki"
@@ -126,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:
@@ -139,6 +164,7 @@ 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
 
 

{ht32_code_mcp-0.5.1 → 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.3.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,6 +868,9 @@ 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"]
 

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

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

ht32_code_mcp-0.5.1/.pytest_base_final_run.log

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