ht32-code-mcp 0.2.1__tar.gz → 0.2.2__tar.gz

{ht32_code_mcp-0.2.1 → ht32_code_mcp-0.2.2}/DEPLOY.md

@@ -25,6 +25,44 @@ PyPI 发布包 → 1Panel 原生 MCP 管理（类型 uvx，启动命令 uvx ht32
 代码默认走 `stdio`（`MCP_TRANSPORT` 未设置时），supergateway 负责 stdio→Streamable HTTP 转换。
 与 ht32-wiki 同构：SSE 无心跳会被 OpenResty 空闲切断，故走 streamableHttp stateful。
 
+## 传输模式（0.2.2+ 支持原生 HTTP）
+
+`server.py` 按 `MCP_TRANSPORT` 分派三种传输，**与 ht32-wiki 同构**：
+
+| `MCP_TRANSPORT` | 行为 | 典型用途 |
+|---|---|---|
+| `stdio`（默认） | 标准输入输出 | 本地开发；或供 supergateway 包装为 Streamable HTTP |
+| `streamable-http` | 单端点 HTTP，**默认有状态会话**（FastMCP `stateless_http=False`） | 直接对外暴露，无需 supergateway 这一层 |
+| `sse` | 旧式 SSE（无心跳，易被反代空闲切断） | 兼容旧客户端，不推荐 |
+
+HTTP 模式监听地址由 `MCP_HOST`（默认 `0.0.0.0`）/ `MCP_PORT`（默认 `8101`，
+**避开 wiki 的 8100**）控制；端点路径为 FastMCP 默认的 `/mcp`。
+
+```bash
+# 原生 Streamable HTTP（stateful），供反代直连
+MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8101 uvx ht32-code-mcp
+```
+
+> **stateful 是默认值而非开关**：FastMCP 4.0.5 的 `stateless_http` 默认 `False`，
+> 即同一 `mcp-session-id` 复用同一会话，子进程/进程内状态不每次 POST 重建——
+> 与 supergateway 的 `--stateful --sessionTimeout 3600000` 语义一致。
+> 若将来需要 stateless，须显式改 FastMCP 设置，届时 Wiki/Code 两端要一起对照。
+
+### 生产接线：一律用 supergateway 包装（2026-09-23 定）
+
+两个 MCP（wiki 与 code）**统一由 supergateway 包装**，不接受「服务自身原生 HTTP」形态：
+
+- 容器里 `uvx ht32-code-mcp` 保持 stdio，由网关转 Streamable HTTP + stateful
+- 好处：**网关这一层统一管协议版本与会话**（`--protocolVersion 2025-06-18`
+  `--stateful --sessionTimeout 3600000`），云端反代只认固定的容器端口/路径，
+  换服务或改内部实现时反代无需跟着动
+
+原生 `streamable-http` / `sse` 保留为**能力**（本地直跑、调试、将来去网关时可用），
+但**当前生产不启用**；本地 compose 部署方案见本仓库 `.work/docker/docker-compose.yml`（按此约定编写）。
+
+无论走哪种，**监听端口必须绑 `0.0.0.0`**（默认值），否则网关/反代从容器外连不上。
+验证：`ss -ltnp | grep -E '1808[0-2]'` 应显示 `0.0.0.0`，而非 `127.0.0.1`。
+
 ## 关键配置
 
 1Panel MCP 表单：
@@ -191,6 +229,20 @@ docker exec 1Panel-openresty-ih7J nginx -t
 反馈通道补 middleware 判断不了的语义问题。每条记录都带 `service` 字段
 （`code`），便于两服务日志合并分析。
 
+### `ok` 字段的口径（0.2.1+）
+
+工具用**字符串**返回错误而不抛异常，middleware 拿不到协议级 `is_error`，
+故靠返回值文本判断。口径是**工具是否完成了它的工作**：
+
+| 返回值 | `ok` | 说明 |
+|---|---|---|
+| `错误：…` / `导出失败…` | `false` | 参数校验、路径越界、IO 失败、无法产出工程 |
+| `未找到…` / `不在支持列表` / `不在覆盖范围` / `暂无模板` | `true` | **"无数据"≠失败** |
+
+"无数据"刻意记为成功：`用户搜 BLDC 但知识库没有` 正是指导 P2-1 补内容的
+最强信号，若标成失败会被分析工具当作噪声剔除。标记表在 `usage.py` 的
+`SOFT_FAILURE_MARKERS`，**改动工具返回值文案时需同步维护**。
+
 ### 目录布局
 
 ```
@@ -205,9 +257,14 @@ docker exec 1Panel-openresty-ih7J nginx -t
 
 | 变量 | 默认 | 说明 |
 |------|------|------|
-| `FEEDBACK_ROOT` | 空（= **关闭**，本地开发默认不落盘） | 日志根目录，服务名子目录自动拼接 |
+| `FEEDBACK_ROOT` | 空（= **关闭**，本地开发默认不落盘） | 日志根目录，服务名子目录自动拼接；**必须填绝对路径**（如 `/app/feedback`，不要写 `app/feedback`） |
 | `CODE_LOG_DIR` | — | 已废弃，改用 `FEEDBACK_ROOT` |
 
+> ⚠️ **必须用绝对路径**：`FEEDBACK_ROOT=app/feedback` 会相对容器 WORKDIR
+> 解析。实测云端曾因漏写前导 `/`，`get_code_version` 显示为
+> `反馈与用量日志：启用（app/feedback/code）`——靠 WORKDIR 恰为 `/` 才侥幸
+> 落对位置，改镜像 WORKDIR 后会静默写到别处。验证时看输出路径是否以 `/` 开头。
+
 > **隐私**：参数按原文记录，`query` / `question` 可能含用户项目信息。
 > 该目录只应挂在受控服务器上，**不要提交进仓库**（定时脚本是
 > `git reset --hard` 镜像模式，写进仓库也会被覆盖丢失）。
@@ -305,10 +362,11 @@ uv lock && uv build && uv publish
 | # | 任务 | 说明 | 状态 |
 |---|------|------|------|
 | 3.1 | MCP 工具实现（7 检索/导出 + 1 反馈） | `.work/mcp-server/src/ht32_code_mcp/`（FastMCP） | ✅ |
-| 3.2 | 工具级测试 | `pytest` 44 用例全绿 | ✅ |
-| 3.3 | PyPI 发布（hatchling） | `ht32-code-mcp` 0.2.0（2026-09-21，含 bundle 通道 + 统一反馈/用量日志） | ✅ |
+| 3.2 | 工具级测试 | `pytest` 46 用例全绿 | ✅ |
+| 3.3 | PyPI 发布（hatchling） | `ht32-code-mcp` 0.2.2（2026-09-23，含 bundle 通道 + 统一反馈/用量日志 + 软失败识别 + 原生 Streamable HTTP） | ✅ |
 | 3.4 | 云端 git clone + 挂载 | `/opt/ht32-code:/app/code` | ✅ |
 | 3.5 | 1Panel 部署（uvx + supergateway → streamableHttp stateful，镜像 next-uvx） | `https://mcp.s621.work/ht32-code` | ✅ |
 | 3.6 | OpenResty 超时修复（`proxy_read_timeout 3600s`） | 修复 60s 空闲断连；2026-09-21 复核两端空闲 100s 后调用仍 200，未被 1Panel 回退 | ✅ |
 | 3.7 | 云端 zip 下载通道（P1-3） | 服务器侧已上线：下载 1608157 字节 / SHA256 一致 / 解压 455 文件 / UV4 0E0W | ✅ |
-| 3.8 | 定时同步脚本含 bundle 清理（P1-2） | `ht32-code-mcp-update.md` 第 6 步 `find … -mmin +60 -delete` | ✅ |
+| 3.8 | 定时同步脚本含 bundle 清理（P1-2） | `ht32-code-mcp-update.md` 第 6 步 `find … -mmin +60 -delete` | ✅ |
+| 3.9 | 反馈与用量日志（P1-5，与 wiki 统一） | 0.2.1；云端已启用，但 `FEEDBACK_ROOT` 漏写前导 `/`（显示 `app/feedback/code`），需改绝对路径 | ⚠️ |

{ht32_code_mcp-0.2.1 → ht32_code_mcp-0.2.2}/PKG-INFO

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

ht32_code_mcp-0.2.2/README.md

@@ -0,0 +1,6 @@
+# .work/mcp-server/
+
+MCP server 代码目录（Python + FastMCP），实现 7 个检索/导出工具 + 1 个反馈工具。
+
+传输由 `MCP_TRANSPORT` 决定：`stdio`（默认，供 supergateway 包装）/ `streamable-http` / `sse`。
+部署与排错见 [DEPLOY.md](DEPLOY.md)。

{ht32_code_mcp-0.2.1 → ht32_code_mcp-0.2.2}/pyproject.toml

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

ht32_code_mcp-0.2.2/smoke_http.py

@@ -0,0 +1,193 @@
+"""Streamable HTTP 冒烟测试：以子进程起 server（MCP_TRANSPORT=streamable-http），
+用真 HTTP 客户端走 initialize → notifications/initialized → tools/list → tools/call，
+并验证**会话复用**（stateful：同一 mcp-session-id 持续可用）。
+
+为什么必须真起进程 + 真 HTTP：与 smoke_stdio.py 同理——直接 import 调库测不到
+握手时序、传输层会话管理、stdout 洁净度；而这两者正是线上故障的高发面
+（wiki 侧曾因 smoke 缺失漏掉协议层两个缺陷到线上）。
+
+用法（从 .work/mcp-server/ 目录，需已安装依赖）：
+    python smoke_http.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+SRC = SCRIPT_DIR / "src"
+sys.path.insert(0, str(SRC))
+
+from fastmcp import Client  # noqa: E402
+
+# server.py 里 FastMCP.run("streamable-http") 的默认端点路径
+MCP_PATH = "/mcp"
+EXPECTED_TOOLS = {
+    "get_code_version", "list_libraries", "find_example", "get_file",
+    "search_code_knowledge", "get_project_manifest", "export_project_bundle",
+}
+START_TIMEOUT = 60.0
+REQUEST_TIMEOUT = 60.0
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return int(s.getsockname()[1])
+
+
+def _wait_port(port: int, proc: subprocess.Popen, deadline: float) -> None:
+    while time.monotonic() < deadline:
+        if proc.poll() is not None:
+            raise RuntimeError(f"服务进程提前退出，退出码 {proc.returncode}")
+        with socket.socket() as s:
+            s.settimeout(0.5)
+            if s.connect_ex(("127.0.0.1", port)) == 0:
+                return
+        time.sleep(0.2)
+
+    raise TimeoutError(f"端口 {port} 在 {START_TIMEOUT}s 内未监听")
+
+
+def _parse_sse(text: str) -> dict:
+    """从 SSE 文本中取第一条 data: 的 JSON（FastMCP 默认 json_response=False）。"""
+    for line in text.splitlines():
+        if line.startswith("data:"):
+            return json.loads(line[len("data:"):].strip())
+
+    raise AssertionError(f"响应中没有 SSE data 行：{text[:300]!r}")
+
+
+def _rpc(url: str, payload: dict, session_id: str | None = None):
+    """POST 一次 JSON-RPC（标准库实现，避免为测试引入 httpx 依赖）。"""
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+    }
+    if session_id:
+        headers["mcp-session-id"] = session_id
+
+    req = urllib.request.Request(
+        url, data=json.dumps(payload).encode("utf-8"), headers=headers, method="POST")
+    with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT) as resp:
+        return resp.status, dict(resp.headers), resp.read().decode("utf-8", "replace")
+
+
+def check_transport_layer(url: str) -> str:
+    """协议层：initialize 拿 session → initialized 通知 → 复用同一 session 调 tools/list。"""
+    status, headers, body = _rpc(url, {
+        "jsonrpc": "2.0", "id": 1, "method": "initialize",
+        "params": {
+            "protocolVersion": "2025-06-18",
+            "capabilities": {},
+            "clientInfo": {"name": "smoke-http", "version": "0"},
+        },
+    })
+    assert status == 200, f"initialize 非 200：{status} {body[:300]}"
+    session_id = headers.get("mcp-session-id")
+    assert session_id, f"initialize 未返回 mcp-session-id（头：{headers}）"
+    print(f"✅ initialize 成功，会话 id = {session_id[:16]}…")
+
+    proto = _parse_sse(body).get("result", {}).get("protocolVersion")
+    assert proto, f"initialize 响应缺少 protocolVersion：{body[:300]}"
+    print(f"✅ 协议版本协商 = {proto}")
+
+    status, _, _ = _rpc(url, {"jsonrpc": "2.0", "method": "notifications/initialized"},
+                        session_id=session_id)
+    assert status in (200, 202), f"initialized 通知非 2xx：{status}"
+
+    status, headers, body = _rpc(
+        url, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session_id=session_id)
+    assert status == 200, f"tools/list 非 200：{status}"
+    assert headers.get("mcp-session-id") == session_id, "tools/list 换用了新会话（非 stateful）"
+
+    tools = {t["name"] for t in _parse_sse(body)["result"]["tools"]}
+    missing = EXPECTED_TOOLS - tools
+    assert not missing, f"缺失工具：{missing}"
+    print(f"✅ 同一会话复用成功（stateful），工具 {len(tools)} 个：{sorted(tools)}")
+
+    return session_id
+
+
+async def check_client_layer(url: str) -> None:
+    """客户端层：用 FastMCP 官方 Client 走完整 tools/call（含结果反序列化）。"""
+    async with Client(url) as client:
+        tools = {t.name for t in await client.list_tools()}
+        missing = EXPECTED_TOOLS - tools
+        assert not missing, f"Client 视角缺失工具：{missing}"
+
+        r = await client.call_tool("get_code_version", {})
+        print("✅ get_code_version:", (r.content[0].text or "").splitlines()[0])
+
+        r = await client.call_tool("find_example", {"peripheral": "GPIO", "limit": 3})
+        text = r.content[0].text or ""
+        assert "example/GPIO" in text, text
+        print(f"✅ find_example(GPIO): {text.splitlines()[0]}")
+
+
+def main() -> int:
+    port = _free_port()
+    url = f"http://127.0.0.1:{port}{MCP_PATH}"
+
+    env = dict(os.environ)
+    env["PYTHONPATH"] = str(SRC) + os.pathsep + env.get("PYTHONPATH", "")
+    env["MCP_TRANSPORT"] = "streamable-http"
+    env["MCP_HOST"] = "127.0.0.1"
+    env["MCP_PORT"] = str(port)
+    env.pop("FEEDBACK_ROOT", None)   # 不带日志落盘，保持测试无副作用
+
+    # stdout 丢弃（HTTP 模式下 uvicorn 访问日志走 stdout，与协议无关）；
+    # 启动与异常信息走 stderr，失败时打印出来供排查
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "ht32_code_mcp"],
+        cwd=str(SCRIPT_DIR),
+        env=env,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+    def stop() -> str:
+        """服务是长驻进程，须先 terminate 再取输出，不能直接 communicate。"""
+        if proc.poll() is None:
+            proc.terminate()
+        try:
+            _, err = proc.communicate(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            _, err = proc.communicate()
+        return err or ""
+
+    try:
+        _wait_port(port, proc, time.monotonic() + START_TIMEOUT)
+        print(f"✅ 服务已监听 http://127.0.0.1:{port}{MCP_PATH}")
+
+        check_transport_layer(url)
+
+        import anyio
+        anyio.run(check_client_layer, url)
+
+        stop()
+
+        print("✅ Streamable HTTP 冒烟全部通过（stateful 会话复用已证实）")
+        return 0
+
+    except Exception:
+        print("❌ 冒烟失败，服务 stderr：", file=sys.stderr)
+        print(stop().strip()[:3000], file=sys.stderr)
+        raise
+
+    finally:
+        stop()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ht32_code_mcp-0.2.2/src/ht32_code_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""ht32-code-mcp：HT32 代码知识库 MCP Server（7 检索/导出工具 + 1 反馈工具）。
+
+传输：stdio（默认）/ streamable-http / sse，由 MCP_TRANSPORT 决定。
+"""

{ht32_code_mcp-0.2.1 → ht32_code_mcp-0.2.2}/src/ht32_code_mcp/server.py

@@ -1,7 +1,7 @@
 """HT32 Code MCP Server。
 
 提供函数库/例程/模板检索与工程导出，供 AI Agent 调用。
-传输协议：stdio（P0 本地阶段；云端阶段见总纲 5.3）。
+传输协议：stdio（供 supergateway 包装为 Streamable HTTP）或 Streamable HTTP / SSE。
 """
 from __future__ import annotations
 
@@ -49,6 +49,11 @@ CLOUD_BUNDLE = bool(BUNDLE_DIR and BUNDLE_BASE_URL)
 FEEDBACK_ROOT = os.environ.get("FEEDBACK_ROOT", "").strip()
 LOG_DIR = resolve_log_dir(FEEDBACK_ROOT, SERVICE_CODE)
 
+# HTTP 传输模式监听地址（MCP_TRANSPORT 非 stdio 时生效）
+# 默认 8101 而非 8100：wiki 占用 8100，两服务常同机部署，避开默认端口冲突
+HOST = os.environ.get("MCP_HOST", "0.0.0.0")
+PORT = _env_int("MCP_PORT", 8101)
+
 index = CodeIndex(CODE_ROOT).load()
 knowledge = KnowledgeSearch(CODE_ROOT)
 exporter = ProjectExporter(CODE_ROOT)
@@ -427,7 +432,12 @@ def submit_feedback(
 
 
 def main() -> None:
-    """入口：按 MCP_TRANSPORT 环境变量启动（默认 stdio，P0 本地阶段）。"""
+    """入口：按 MCP_TRANSPORT 环境变量启动对应传输模式的服务器。
+
+    - stdio: 供 supergateway 包装为 Streamable HTTP（默认）
+    - streamable-http: 直接对外暴露的单端点 HTTP（有状态会话）
+    - sse: FastMCP 内置 SSE 服务器（旧式，无心跳易被反代空闲切断）
+    """
     transport = os.environ.get("MCP_TRANSPORT", "stdio").lower()
     stats = index.data.get("stats", {})
     print(f"[ht32-code-mcp] 程序版本: ht32-code-mcp {_MCP_VERSION}", file=sys.stderr)
@@ -437,11 +447,15 @@ def main() -> None:
     print(f"[ht32-code-mcp] 索引就绪: {stats.get('library_modules', 0)} 模块 / "
           f"{stats.get('examples', 0)} 例程 / {stats.get('raw_files', 0)} raw 文件", file=sys.stderr)
     if transport == "stdio":
-        print("[ht32-code-mcp] 启动服务: stdio", file=sys.stderr)
+        print("[ht32-code-mcp] 启动服务: stdio（供 supergateway 包装为 Streamable HTTP）",
+              file=sys.stderr)
         mcp.run(transport="stdio")
+    elif transport == "sse":
+        print(f"[ht32-code-mcp] 启动服务: SSE {HOST}:{PORT}", file=sys.stderr)
+        mcp.run(transport="sse", host=HOST, port=PORT)
     else:
-        print(f"[ht32-code-mcp] 传输模式 '{transport}' 暂未启用（P0 仅 stdio）", file=sys.stderr)
-        sys.exit(2)
+        print(f"[ht32-code-mcp] 启动服务: Streamable HTTP {HOST}:{PORT}", file=sys.stderr)
+        mcp.run(transport="streamable-http", host=HOST, port=PORT)
 
 
 if __name__ == "__main__":

{ht32_code_mcp-0.2.1 → ht32_code_mcp-0.2.2}/uv.lock

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

ht32_code_mcp-0.2.1/README.md

@@ -1,5 +0,0 @@
-# .work/mcp-server/
-
-MCP server 代码目录（Python/FastMCP），P0-2 在此实现 7 工具（本地 stdio）。
-
-当前为占位：仓库初始化（P0-1）时建立骨架，保证目录结构随 git 入库。

ht32_code_mcp-0.2.1/src/ht32_code_mcp/__init__.py

@@ -1,3 +0,0 @@
-"""ht32-code-mcp：HT32 代码知识库 MCP Server（7 工具，本地 stdio）。"""
-
-__version__ = "0.1.0"