ht32-code-mcp 0.1.0__tar.gz

ht32_code_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+index/
+dist/
+build/
+uv.lock.tmp

ht32_code_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: ht32-code-mcp
+Version: 0.1.0
+Summary: HT32 Code MCP Server - 为 AI Agent 提供 HT32 函数库/例程/模板检索与工程导出
+License-Expression: MIT
+Keywords: firmware,holtek,ht32,mcp,mcu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'

ht32_code_mcp-0.1.0/README.md

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

ht32_code_mcp-0.1.0/e2e_scenario_a.py

@@ -0,0 +1,142 @@
+"""P0-4 场景 a 端到端驱动：双 MCP 本地 stdio 真实子进程跑通新建工程链路。
+
+流程（对应 ht32-skills/ht32-project-create）：
+  wiki-mcp: get_model + get_chip_info（HT32F52352 规格核对）
+  code-mcp: tools/list（7 工具）→ get_project_manifest → export_project_bundle → 落盘核对
+
+用法：
+    <code-venv-python> e2e_scenario_a.py [--chip HT32F52352]
+输出：
+    %TEMP%/ht32_p0_4_e2e/wiki_chip_info.txt | manifest.txt | export.txt
+    %TEMP%/ht32_p0_4_e2e/stage/<chip>_demo/  导出产物（编译对象）
+退出码 0 全通过；1 失败。
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+
+CODE_MCP_DIR = Path(__file__).resolve().parent
+WIKI_MCP_DIR = Path(r"d:\HoltekWork\WorkDesktop\ht32_ai_mcp\ht32-wiki\.work\mcp-server")
+WIKI_ROOT = WIKI_MCP_DIR.parents[1]
+
+CODE_PY = CODE_MCP_DIR / ".venv" / "Scripts" / "python.exe"
+WIKI_PY = WIKI_MCP_DIR / ".venv" / "Scripts" / "python.exe"
+
+EXPECTED_TOOLS = {
+    "get_code_version", "list_libraries", "find_example", "get_file",
+    "search_code_knowledge", "get_project_manifest", "export_project_bundle",
+}
+
+WORK = Path(os.environ.get("TEMP", ".")) / "ht32_p0_4_e2e"
+
+failed = 0
+
+
+def check(name: str, cond: bool, detail: str = "") -> bool:
+    global failed
+    suffix = f" — {detail}" if detail else ""
+    print(f"{'✅' if cond else '❌'} [{name}]{suffix}")
+    if not cond:
+        failed += 1
+    return cond
+
+
+async def call_text(client: Client, tool: str, args: dict) -> str:
+    r = await client.call_tool(tool, args)
+    parts = [c.text for c in r.content if getattr(c, "text", None)]
+    return "\n".join(parts)
+
+
+def wiki_transport() -> StdioTransport:
+    env = dict(os.environ)
+    env.update({"WIKI_ROOT": str(WIKI_ROOT), "MCP_TRANSPORT": "stdio",
+                "MCP_WARMUP": "1", "DS_RAG_AUTOBUILD": "0"})
+    for key in ("EMBED_API_KEY", "SILICONFLOW_API_KEY", "RERANK_API_KEY"):
+        env.pop(key, None)
+    return StdioTransport(str(WIKI_PY), ["-m", "ht32_wiki_mcp"],
+                          env=env, cwd=str(WIKI_MCP_DIR))
+
+
+def code_transport() -> StdioTransport:
+    env = dict(os.environ)
+    env["CODE_ROOT"] = str(CODE_MCP_DIR.parents[1])
+    return StdioTransport(str(CODE_PY), ["-m", "ht32_code_mcp"],
+                          env=env, cwd=str(CODE_MCP_DIR))
+
+
+async def phase_wiki(chip: str) -> str:
+    print("\n========== 阶段 1 · wiki-mcp 规格核对 ==========")
+    async with Client(wiki_transport()) as client:
+        model_text = await call_text(client, "get_model", {"model": chip})
+        check("get_model 返回系列映射", "系列：" in model_text,
+              model_text.splitlines()[0] if model_text else "(空)")
+        chip_text = await call_text(client, "get_chip_info", {"model": chip})
+        check("get_chip_info 命中系列页", "未找到" not in chip_text and len(chip_text) > 200,
+              f"{len(chip_text)} 字符")
+        (WORK / "wiki_chip_info.txt").write_text(
+            f"== get_model({chip}) ==\n{model_text}\n\n== get_chip_info({chip}) ==\n{chip_text}",
+            encoding="utf-8")
+        print(f"规格核对全文已存 {WORK / 'wiki_chip_info.txt'}")
+        return chip_text
+
+
+async def phase_code(chip: str) -> Path:
+    print("\n========== 阶段 2 · code-mcp manifest + export ==========")
+    stage = WORK / "stage" / f"{chip.lower()}_demo"
+    if stage.exists():
+        shutil.rmtree(stage)
+    stage.parent.mkdir(parents=True, exist_ok=True)
+
+    async with Client(code_transport()) as client:
+        tools = {t.name for t in await client.list_tools()}
+        check("7 工具注册齐全", EXPECTED_TOOLS <= tools,
+              f"{len(tools)} 个" if EXPECTED_TOOLS <= tools else f"缺 {EXPECTED_TOOLS - tools}")
+
+        manifest = await call_text(client, "get_project_manifest", {})
+        check("manifest 返回模板清单", "工程模板清单" in manifest,
+              manifest.splitlines()[0] if manifest else "(空)")
+        (WORK / "manifest.txt").write_text(manifest, encoding="utf-8")
+
+        export = await call_text(client, "export_project_bundle",
+                                  {"chip": chip, "out_dir": str(stage)})
+        check("export_project_bundle 成功", "导出失败" not in export and stage.is_dir(),
+              export.splitlines()[0] if export else "(空)")
+        (WORK / "export.txt").write_text(export, encoding="utf-8")
+
+    uvprojx = list(stage.rglob("*.uvprojx"))
+    check("落盘核对：.uvprojx 存在", len(uvprojx) == 1, str(uvprojx))
+    files = [p for p in stage.rglob("*") if p.is_file()]
+    check("落盘核对：工程文件数 > 20", len(files) > 20, f"{len(files)} 个文件")
+    print(f"导出产物：{stage}")
+    return stage
+
+
+async def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--chip", default="HT32F52352")
+    args = parser.parse_args()
+    WORK.mkdir(parents=True, exist_ok=True)
+    if not (WIKI_PY.is_file() and CODE_PY.is_file()):
+        print("❌ 找不到 venv 解释器", file=sys.stderr)
+        return 1
+
+    await phase_wiki(args.chip)
+    stage = await phase_code(args.chip)
+
+    print("\n========== 摘要 ==========")
+    print(f"工作目录: {WORK}")
+    print(f"导出工程: {stage}")
+    print(f"结果: {'✅ 全部通过' if failed == 0 else f'❌ {failed} 项失败'}")
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))

ht32_code_mcp-0.1.0/e2e_scenario_b.py

@@ -0,0 +1,76 @@
+"""P0-4 场景 b 冒烟：检索辅助写码三工具各一次，确认返回真实库内容。
+
+  search_code_knowledge("UART 用法") → 知识页命中
+  find_example(peripheral="UART", chip="HT32F52352") → 官方例程路径
+  get_file(例程 main.c) → 官方库真实源码
+
+用法：
+    <code-venv-python> e2e_scenario_b.py
+退出码 0 全通过；1 失败。
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import sys
+from pathlib import Path
+
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+
+CODE_MCP_DIR = Path(__file__).resolve().parent
+CODE_PY = CODE_MCP_DIR / ".venv" / "Scripts" / "python.exe"
+
+failed = 0
+
+
+def check(name: str, cond: bool, detail: str = "") -> bool:
+    global failed
+    suffix = f" — {detail}" if detail else ""
+    print(f"{'✅' if cond else '❌'} [{name}]{suffix}")
+    if not cond:
+        failed += 1
+    return cond
+
+
+async def call_text(client: Client, tool: str, args: dict) -> str:
+    r = await client.call_tool(tool, args)
+    return "\n".join(c.text for c in r.content if getattr(c, "text", None))
+
+
+async def main() -> int:
+    env = dict(os.environ)
+    env["CODE_ROOT"] = str(CODE_MCP_DIR.parents[1])
+    transport = StdioTransport(str(CODE_PY), ["-m", "ht32_code_mcp"],
+                               env=env, cwd=str(CODE_MCP_DIR))
+
+    async with Client(transport) as client:
+        print("== 场景 b 冒烟（检索辅助写码）==")
+
+        s = await call_text(client, "search_code_knowledge", {"query": "UART 用法 中断 发送", "limit": 3})
+        check("search_code_knowledge 命中知识页", "找到" in s and "entities/" in s,
+              s.splitlines()[0] if s else "(空)")
+        print("\n".join(s.splitlines()[:12]), "…\n")
+
+        # 官方例程目录名为 USART（无 UART 目录）：find_example 词法匹配不含 uart→usart 别名
+        f = await call_text(client, "find_example",
+                            {"peripheral": "USART", "chip": "HT32F52352", "limit": 3})
+        check("find_example 返回 USART 例程", "找到" in f and "example" in f,
+              f.splitlines()[0] if f else "(空)")
+        m = re.search(r"路径: (raw/\S+)", f)
+        check("例程含 main.c 路径", bool(m), m.group(1) if m else "(未匹配)")
+        print("\n".join(f.splitlines()[:10]), "…\n")
+
+        if m:
+            g = await call_text(client, "get_file", {"path": f"{m.group(1)}/main.c", "max_length": 4000})
+            has_api = ("HT_" in g) and ("UART" in g or "USART" in g)
+            check("get_file 返回官方库真实源码", has_api, f"{len(g)} 字符")
+            print("\n".join(g.splitlines()[:10]), "…")
+
+    print(f"\n结果: {'✅ 场景 b 冒烟通过' if failed == 0 else f'❌ {failed} 项失败'}")
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))

ht32_code_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ht32-code-mcp"
+version = "0.1.0"
+description = "HT32 Code MCP Server - 为 AI Agent 提供 HT32 函数库/例程/模板检索与工程导出"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["ht32", "mcu", "mcp", "firmware", "holtek"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Embedded Systems",
+]
+dependencies = [
+    "fastmcp>=0.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+ht32-code-mcp = "ht32_code_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ht32_code_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ht32_code_mcp-0.1.0/smoke_stdio.py

@@ -0,0 +1,58 @@
+"""stdio 冒烟测试：以子进程 stdio 启动 server，验证 7 工具全部可调用。
+
+用法（从 .work/mcp-server/ 目录，需已安装依赖）：
+    python smoke_stdio.py
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+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
+from fastmcp.client.transports import StdioTransport  # noqa: E402
+
+EXPECTED_TOOLS = {
+    "get_code_version", "list_libraries", "find_example", "get_file",
+    "search_code_knowledge", "get_project_manifest", "export_project_bundle",
+}
+
+
+async def run() -> int:
+    env = dict(os.environ)
+    env["PYTHONPATH"] = str(SRC) + os.pathsep + env.get("PYTHONPATH", "")
+    transport = StdioTransport(sys.executable, ["-m", "ht32_code_mcp"], env=env)
+    async with Client(transport) as client:
+        tools = {t.name for t in await client.list_tools()}
+        missing = EXPECTED_TOOLS - tools
+        print(f"工具清单（{len(tools)}）：{sorted(tools)}")
+        if missing:
+            print(f"❌ 缺失工具：{missing}")
+            return 1
+        print(f"✅ 7 工具注册齐全")
+
+        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]}")
+
+        r = await client.call_tool("get_file", {
+            "path": "raw/HT32_STD_5xxxx_FWLib_V1.21.1/library/HT32F5xxxx_Driver/inc/ht32f5xxxx_gpio.h",
+            "max_length": -1,
+        })
+        assert "GPIO_DirectionConfig" in (r.content[0].text or "")
+        print("✅ get_file(gpio.h) 内容正确")
+        print("✅ stdio 冒烟全部通过")
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(run()))

ht32_code_mcp-0.1.0/src/ht32_code_mcp/__init__.py

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

ht32_code_mcp-0.1.0/src/ht32_code_mcp/__main__.py

@@ -0,0 +1,4 @@
+"""允许 `python -m ht32_code_mcp` 直接启动。"""
+from .server import main
+
+main()

ht32_code_mcp-0.1.0/src/ht32_code_mcp/exporter.py

@@ -0,0 +1,166 @@
+"""export_project_bundle：从模板 + 官方库源码组装自包含可编译 Keil 工程到本地目录。
+
+本阶段（P0-2）不做 token 下载 URL，云端阶段再扩展。
+参数化依据：raw/templates/ht32f5-keil/devices.json（device/cdef/adef/sys/startup）。
+"""
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+
+_REDIRECT_RE = re.compile(r"#ifdef\s+(USE_\w+)\s*\n\s*#define\s+(USE_\w+)")
+
+
+class ExportError(Exception):
+    """导出失败（型号未知 / 源文件缺失 / 目标目录非空等）。"""
+
+
+def _read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+class ProjectExporter:
+    def __init__(self, code_root: Path) -> None:
+        self.root = Path(code_root)
+        self.template_dir = self.root / "raw" / "templates" / "ht32f5-keil"
+        self.fwlib_dir = self.root / "raw" / "HT32_STD_5xxxx_FWLib_V1.21.1"
+
+    # ------------------------------------------------------------ 主流程
+    def export(self, chip: str, out_dir: str) -> str:
+        if not self.template_dir.is_dir():
+            raise ExportError(f"模板目录不存在：{self.template_dir}")
+        device, entry = self._resolve_device(chip)
+
+        # 1. 预检目标目录
+        out = Path(out_dir).expanduser().resolve()
+        if out.exists() and any(out.iterdir()):
+            raise ExportError(f"目标目录非空，拒绝覆盖：{out}（请指定新目录或先清空）")
+
+        # 2. 预检官方源文件（先验证后落盘，失败不产生半成品）
+        sys_c = self.fwlib_dir / "library" / "Device" / "Holtek" / "HT32F5xxxx" / "Source" / entry["sys"]
+        sys_h = sys_c.parent.parent / "Include" / (sys_c.stem + ".h")
+        startup = (self.fwlib_dir / "library" / "Device" / "Holtek" / "HT32F5xxxx"
+                   / "Source" / "ARM" / entry["startup"])
+        libcfg_name = self._resolve_libcfg(entry["cdef"])
+        libcfg = (self.fwlib_dir / "library" / "HT32F5xxxx_Driver" / "inc" / libcfg_name
+                  if libcfg_name else None)
+        missing = [str(p) for p in (sys_c, sys_h, startup, libcfg) if p is not None and not p.is_file()]
+        if missing:
+            raise ExportError("官方库缺少所需源文件：\n- " + "\n- ".join(missing))
+
+        # 3. 复制模板树
+        out.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(self.template_dir, out, dirs_exist_ok=True)
+
+        # 4. 参数化 uvprojx
+        uvprojx = out / "MDK-ARM" / "ht32f5-template.uvprojx"
+        old_sys_stem = "system_ht32f5xxxx_01"
+        old_startup_stem = "startup_ht32f5xxxx_01"
+        text = _read_text(uvprojx)
+        text = re.sub(r"(<Device>)[^<]*(</Device>)", rf"\g<1>{device}\g<2>", text, count=1)
+        text = _replace_define(text, "USE_HT32_DRIVER", entry["cdef"])
+        text = _replace_define(text, "USE_HT32_CHIP", entry["adef"])
+        text = text.replace(old_sys_stem, sys_c.stem).replace(old_startup_stem, startup.stem)
+        with open(uvprojx, "w", encoding="utf-8", newline="") as f:
+            f.write(text)
+
+        # 5. 替换设备相关文件
+        replaced: list[str] = []
+        for old in out.glob("CMSIS/system_ht32f5xxxx_*.c"):
+            old.unlink()
+        for old in out.glob("CMSIS/system_ht32f5xxxx_*.h"):
+            old.unlink()
+        shutil.copyfile(sys_c, out / "CMSIS" / sys_c.name)
+        shutil.copyfile(sys_h, out / "CMSIS" / sys_h.name)
+        replaced += [f"CMSIS/{sys_c.name}", f"CMSIS/{sys_h.name}"]
+
+        for old in out.glob("Startup/startup_*.s"):
+            old.unlink()
+        shutil.copyfile(startup, out / "Startup" / startup.name)
+        replaced.append(f"Startup/{startup.name}")
+
+        if libcfg is not None:
+            for old in out.glob("Drivers/*_libcfg.h"):
+                old.unlink()
+            shutil.copyfile(libcfg, out / "Drivers" / libcfg.name)
+            replaced.append(f"Drivers/{libcfg.name}")
+
+        return self._report(out, device, entry, replaced, libcfg_name)
+
+    # ------------------------------------------------------------ 辅助
+    def _resolve_device(self, chip: str) -> tuple[str, dict]:
+        import json
+        dj = self.template_dir / "devices.json"
+        if not dj.is_file():
+            raise ExportError(f"模板型号参数表缺失：{dj}")
+        meta = json.loads(dj.read_text(encoding="utf-8"))
+        want = chip.strip().upper()
+        for d in meta.get("devices", []):
+            if d.get("device", "").upper() == want:
+                return d["device"], d          # 重名取首条（官方板级变体）
+        # 宽松匹配：型号主体包含（HT32F52352 含于 HT32F52352_SK 场景已由上面精确处理）
+        for d in meta.get("devices", []):
+            if want in d.get("device", "").upper():
+                return d["device"], d
+        names = [d.get("device", "") for d in meta.get("devices", [])][:20]
+        raise ExportError(
+            f"型号 '{chip}' 不在模板参数表（共 {meta.get('count', '?')} 个型号）。\n"
+            f"可用型号（前 20）：{', '.join(names)}…\n"
+            "完整清单：get_file('raw/templates/ht32f5-keil/devices.json') 或 get_project_manifest()"
+        )
+
+    def _resolve_libcfg(self, cdef: str) -> str | None:
+        """从 cdef 宏解析 libcfg 文件名，沿 ht32_config.h 重定向链（USE_HT50F32002 → USE_HT32F50220_30）。"""
+        inc_dir = self.fwlib_dir / "library" / "HT32F5xxxx_Driver" / "inc"
+        config = (self.template_dir / "CMSIS" / "ht32_config.h")
+        redirects: dict[str, str] = {}
+        if config.is_file():
+            redirects = {m.group(1): m.group(2)
+                         for m in _REDIRECT_RE.finditer(_read_text(config))}
+        for token in [t.strip() for t in cdef.split(",")]:
+            if not token.startswith("USE_"):
+                continue
+            cur, seen = token, set()
+            while cur and cur not in seen:
+                seen.add(cur)
+                candidate = inc_dir / (cur[4:].lower() + "_libcfg.h")
+                if candidate.is_file():
+                    return candidate.name
+                cur = redirects.get(cur, "")
+        return None
+
+    def _report(self, out: Path, device: str, entry: dict,
+                replaced: list[str], libcfg_name: str | None) -> str:
+        n_files = sum(1 for p in out.rglob("*") if p.is_file())
+        libcfg_note = (f"Drivers/{libcfg_name}" if libcfg_name
+                       else "（未解析出 libcfg，保留模板默认，请人工核对）")
+        lines = [
+            f"自包含 Keil 工程已导出：{out}",
+            f"目标芯片：{device}（{entry.get('sys')} / {entry.get('startup')}）",
+            f"C 宏（Cads）：{entry['cdef']}",
+            f"汇编宏（Aads）：{entry['adef']}",
+            f"libcfg：{libcfg_note}",
+            f"工程文件：MDK-ARM/ht32f5-template.uvprojx（已按上述宏参数化）",
+            f"文件总数：{n_files}",
+            "",
+            "按目标芯片替换/注入的文件：",
+            *[f"- {r}" for r in replaced],
+            "",
+            "目录结构：Application（main/it/conf）、CMSIS（设备头+system）、"
+            "Drivers（最小驱动集+libcfg）、Startup、MDK-ARM（工程文件）、README.md、devices.json",
+            "",
+            "后续步骤：",
+            "1. Keil MDK 打开 MDK-ARM/ht32f5-template.uvprojx（需 Holtek HT32_DFP pack ≥1.0.67）",
+            "2. 如需精确 IROM/IRAM 内存布局，在 Options → Device 重新选择该型号由 DFP 刷新",
+            "3. 基线编译验证（P0-4.2 将用 UV4 命令行复核 0 Error 0 Warning）",
+        ]
+        return "\n".join(lines)
+
+
+def _replace_define(text: str, anchor: str, new_value: str) -> str:
+    """替换 uvprojx 中包含 anchor 的 <Define> 行内容（Cads/Aads 各一条）。"""
+    pattern = re.compile(r"(<Define>)[^<]*" + re.escape(anchor) + r"[^<]*(</Define>)")
+    if not pattern.search(text):
+        raise ExportError(f"uvprojx 中未找到含 {anchor} 的 <Define>，模板结构可能已变化")
+    return pattern.sub(rf"\g<1>{new_value}\g<2>", text, count=1)