ht32-code-mcp 0.1.0__py3-none-any.whl

ht32_code_mcp/__init__.py

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

ht32_code_mcp/__main__.py

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

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)

ht32_code_mcp/index.py

@@ -0,0 +1,246 @@
+"""预构建 JSON 索引：扫描 raw/ 与知识页，生成库模块/例程/文件路径清单。
+
+生成产物：.work/mcp-server/index/code_index.json（gitignore，可随时重建）。
+生成入口：.work/build_index.py（薄 CLI）；server 启动时若索引缺失会自动构建。
+"""
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# 驱动源码文件名 → 库模块名的系列前缀（ht32f5xxxx_gpio.c → gpio）
+_MODULE_PREFIX_RE = re.compile(
+    r"^(?:ht32f5xxxx|ht32f652xx|ht32f65xxx_66xxx|ht32f66xxx|ht32f65xxx|ht32)_(?P<module>.+)$"
+)
+# 例程 readme 中的芯片型号 token（HT32F52352 / HT50F32002 …）
+_CHIP_RE = re.compile(r"\bHT(?:32|50)\w{3,}\b")
+# FWLib 包名 → 系列标签（5xxxx → HT32F5 / M0+）
+_SERIES_MAP = {
+    "5xxxx": ("HT32F5", "M0+"),
+}
+
+BRIEF_MAX = 200
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _rel(posix_path: str) -> str:
+    return posix_path.replace("\\", "/")
+
+
+def _parse_readme(readme: Path) -> tuple[str, list[str]]:
+    """从官方例程 readme.txt 提取简介与标注芯片。"""
+    if not readme.is_file():
+        return "", []
+    try:
+        text = readme.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return "", []
+    brief = ""
+    marker = "@par Example Description:"
+    i = text.find(marker)
+    if i >= 0:
+        seg = text[i + len(marker):]
+        j = seg.find("@par")
+        if j >= 0:
+            seg = seg[:j]
+        brief = " ".join(seg.split())[:BRIEF_MAX]
+    chips = sorted(set(_CHIP_RE.findall(text)))[:16]
+    return brief, chips
+
+
+class CodeIndex:
+    """索引构建与加载（构建慢扫描一次，之后秒级加载 JSON）。"""
+
+    def __init__(self, code_root: Path, index_file: Path | None = None) -> None:
+        self.root = Path(code_root)
+        self.index_file = Path(index_file) if index_file else (
+            self.root / ".work" / "mcp-server" / "index" / "code_index.json"
+        )
+        self.data: dict[str, Any] = {}
+
+    # ------------------------------------------------------------ 加载
+    def load(self) -> "CodeIndex":
+        """启动即加载：索引存在则读 JSON，否则现场构建并落盘。"""
+        if self.index_file.is_file():
+            with open(self.index_file, encoding="utf-8") as f:
+                self.data = json.load(f)
+        else:
+            self.build(force=True)
+        return self
+
+    # ------------------------------------------------------------ 构建
+    def build(self, force: bool = False) -> dict[str, Any]:
+        if not force and self.index_file.is_file():
+            return self.load().data
+        data: dict[str, Any] = {
+            "built_at": _now(),
+            "code_version": self._read_version(),
+            "fwlibs": [],
+            "templates": [],
+            "knowledge_pages": [],
+            "files": [],
+            "stats": {},
+        }
+        raw_dir = self.root / "raw"
+        if raw_dir.is_dir():
+            data["fwlibs"] = [self._scan_fwlib(p) for p in sorted(raw_dir.iterdir())
+                              if p.is_dir() and p.name != "templates"]
+            data["templates"] = [self._scan_template(p) for p in sorted((raw_dir / "templates").iterdir())
+                                 if p.is_dir()] if (raw_dir / "templates").is_dir() else []
+            data["files"] = sorted(
+                _rel(f.relative_to(self.root).as_posix())
+                for f in raw_dir.rglob("*") if f.is_file()
+            )
+        data["knowledge_pages"] = self._scan_knowledge()
+        fw = data["fwlibs"]
+        data["stats"] = {
+            "fwlib_packages": len(fw),
+            "library_modules": len({m["module"] for p in fw for m in p["modules"]}),
+            "examples": sum(len(p["examples"]) for p in fw),
+            "example_peripherals": len({e["peripheral"] for p in fw for e in p["examples"]}),
+            "templates": len(data["templates"]),
+            "raw_files": len(data["files"]),
+            "knowledge_pages": len(data["knowledge_pages"]),
+        }
+        self.data = data
+        self.index_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.index_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=1)
+        return data
+
+    # ------------------------------------------------------------ 子扫描
+    def _read_version(self) -> str:
+        v = self.root / "VERSION"
+        if v.is_file():
+            for line in v.read_text(encoding="utf-8", errors="replace").splitlines():
+                line = line.strip()
+                if line:
+                    return line
+        return "unknown"
+
+    def _scan_fwlib(self, pkg: Path) -> dict[str, Any]:
+        rel_pkg = _rel(pkg.relative_to(self.root).as_posix())
+        m = re.match(r"HT32_STD_(?P<key>\w+?)_FWLib", pkg.name)
+        series = []
+        family = ""
+        if m and m.group(1) in _SERIES_MAP:
+            series = [_SERIES_MAP[m.group(1)][0]]
+            family = _SERIES_MAP[m.group(1)][1]
+        info: dict[str, Any] = {
+            "name": pkg.name,
+            "path": rel_pkg,
+            "series": series,
+            "family": family,
+            "modules": [],
+            "examples": [],
+        }
+        # 驱动模块：src/*.c（一个 .c 一个驱动变体，同模块名合并展示）
+        for src in sorted(pkg.rglob("HT32F5xxxx_Driver/src/*.c")):
+            stem = src.stem
+            mm = _MODULE_PREFIX_RE.match(stem)
+            module = mm.group("module") if mm else stem
+            inc = src.with_name(stem + ".h")
+            entry = {
+                "module": module,
+                "src": _rel(src.relative_to(self.root).as_posix()),
+                "inc": _rel(inc.relative_to(self.root).as_posix()) if inc.is_file() else "",
+            }
+            info["modules"].append(entry)
+        # 例程：example/ 下任何含 main.c 的目录（外设=第一层目录名）
+        example_dir = pkg / "example"
+        if example_dir.is_dir():
+            for main_c in sorted(example_dir.rglob("main.c")):
+                ex_dir = main_c.parent
+                rel = ex_dir.relative_to(example_dir)
+                parts = rel.parts
+                brief, chips = _parse_readme(ex_dir / "readme.txt")
+                info["examples"].append({
+                    "peripheral": parts[0],
+                    "name": "/".join(parts[1:]) if len(parts) > 1 else parts[0],
+                    "path": _rel(ex_dir.relative_to(self.root).as_posix()),
+                    "brief": brief,
+                    "chips": chips,
+                    "files": [f.name for f in sorted(ex_dir.iterdir()) if f.is_file()],
+                })
+        return info
+
+    def _scan_template(self, tpl: Path) -> dict[str, Any]:
+        rel_tpl = _rel(tpl.relative_to(self.root).as_posix())
+        entry: dict[str, Any] = {
+            "name": tpl.name,
+            "path": rel_tpl,
+            "default_device": "",
+            "device_count": 0,
+            "devices": [],
+        }
+        dj = tpl / "devices.json"
+        if dj.is_file():
+            try:
+                meta = json.loads(dj.read_text(encoding="utf-8"))
+                devices = meta.get("devices", [])
+                entry["default_device"] = meta.get("default_device", "")
+                entry["device_count"] = len(devices)
+                entry["devices"] = [d.get("device", "") for d in devices]
+            except (OSError, json.JSONDecodeError):
+                pass
+        return entry
+
+    def _scan_knowledge(self) -> list[dict[str, Any]]:
+        pages: list[dict[str, Any]] = []
+        for sub, ptype in (("entities/libraries", "entity"),
+                           ("entities", "entity"),
+                           ("comparisons", "comparison")):
+            d = self.root / sub
+            if not d.is_dir():
+                continue
+            for md in sorted(d.rglob("*.md")):
+                title, tags = _parse_frontmatter(md)
+                pages.append({
+                    "title": title or md.stem,
+                    "type": ptype,
+                    "tags": tags,
+                    "path": _rel(md.relative_to(self.root).as_posix()),
+                })
+        # 去重（entities/libraries 会命中 entities 递归两次）
+        seen: set[str] = set()
+        uniq = []
+        for p in pages:
+            if p["path"] not in seen:
+                seen.add(p["path"])
+                uniq.append(p)
+        return uniq
+
+
+def _parse_frontmatter(md: Path) -> tuple[str, list[str]]:
+    title, tags = "", []
+    try:
+        text = md.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return "", []
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        fm = text[3:end] if end > 0 else ""
+        for line in fm.splitlines():
+            if line.startswith("title:"):
+                title = line.split(":", 1)[1].strip()
+            elif line.startswith("tags:"):
+                tags = [t.strip() for t in line.split(":", 1)[1].strip("[]").split(",") if t.strip()]
+    return title, tags
+
+
+# ---------------------------------------------------------------- 查询辅助
+def normalize_series(series: str) -> str:
+    """f5 / F5 / HT32F5 / 5xxxx → f5（用于系列过滤匹配）。"""
+    s = series.strip().lower()
+    for prefix in ("ht32f", "ht32", "ht"):
+        if s.startswith(prefix):
+            s = s[len(prefix):]
+            break
+    s = s.replace("xxxx", "").replace("_", "")
+    return s

ht32_code_mcp/knowledge.py

@@ -0,0 +1,100 @@
+"""知识页检索：entities/ 与 comparisons/ 的 .md 页面（词法打分，无向量层）。"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_TOKEN_RE = re.compile(r"[a-z0-9_]+|[\u4e00-\u9fff]+")
+
+
+@dataclass
+class KnowledgePage:
+    title: str
+    path: str
+    tags: list[str] = field(default_factory=list)
+    content: str = ""
+
+
+class KnowledgeSearch:
+    """加载并按相关性打分检索知识页（页面少，启动后首次查询时加载全文）。"""
+
+    def __init__(self, code_root: Path) -> None:
+        self.root = Path(code_root)
+        self._pages: list[KnowledgePage] | None = None
+
+    def _ensure(self) -> list[KnowledgePage]:
+        if self._pages is None:
+            pages: list[KnowledgePage] = []
+            for sub in ("entities/libraries", "comparisons"):
+                d = self.root / sub
+                if not d.is_dir():
+                    continue
+                for md in sorted(d.rglob("*.md")):
+                    try:
+                        text = md.read_text(encoding="utf-8", errors="replace")
+                    except OSError:
+                        continue
+                    pages.append(KnowledgePage(
+                        title=md.stem,
+                        path=md.relative_to(self.root).as_posix(),
+                        tags=_extract_tags(text),
+                        content=text,
+                    ))
+            self._pages = pages
+        return self._pages
+
+    def search(self, query: str, limit: int = 5) -> list[tuple[KnowledgePage, float, str]]:
+        """返回 (页面, 得分, 片段) 列表，按得分降序。"""
+        tokens = _TOKEN_RE.findall(query.lower())
+        if not tokens:
+            return []
+        scored: list[tuple[KnowledgePage, float, str]] = []
+        for page in self._ensure():
+            low = page.content.lower()
+            title = page.title.lower()
+            score = 0.0
+            for t in tokens:
+                if t in title:
+                    score += 6
+                score += sum(4 if t == tag else (2 if t in tag else 0)
+                             for tag in (p.lower() for p in page.tags))
+                score += min(low.count(t), 8)
+            if score <= 0:
+                continue
+            scored.append((page, score, _snippet(page.content, tokens)))
+        scored.sort(key=lambda x: x[1], reverse=True)
+        return scored[:limit]
+
+
+def _extract_tags(text: str) -> list[str]:
+    if not text.startswith("---"):
+        return []
+    end = text.find("\n---", 3)
+    fm = text[3:end] if end > 0 else ""
+    for line in fm.splitlines():
+        if line.startswith("tags:"):
+            return [t.strip() for t in line.split(":", 1)[1].strip("[]").split(",") if t.strip()]
+    return []
+
+
+def _snippet(content: str, tokens: list[str], width: int = 600) -> str:
+    """取命中 token 最多的行为锚点，截取附近片段。"""
+    lines = content.splitlines()
+    best_i, best_hits = 0, -1
+    for i, line in enumerate(lines):
+        if not line.strip() or line.startswith("---"):
+            continue
+        low = line.lower()
+        hits = sum(low.count(t) for t in tokens)
+        if hits > best_hits:
+            best_i, best_hits = i, hits
+    chunk: list[str] = []
+    total = 0
+    for line in lines[best_i:]:
+        chunk.append(line)
+        total += len(line) + 1
+        if total >= width:
+            break
+    snippet = "\n".join(chunk).strip()
+    return snippet[:width] + ("…" if len(snippet) > width else "")

ht32_code_mcp/server.py

@@ -0,0 +1,327 @@
+"""HT32 Code MCP Server。
+
+提供函数库/例程/模板检索与工程导出，供 AI Agent 调用。
+传输协议：stdio（P0 本地阶段；云端阶段见总纲 5.3）。
+"""
+from __future__ import annotations
+
+import os
+import sys
+from importlib.metadata import PackageNotFoundError, version as pkg_version
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from .exporter import ExportError, ProjectExporter
+from .index import CodeIndex, normalize_series
+from .knowledge import KnowledgeSearch
+
+# 知识库根目录（ht32-code 仓库根；src/ht32_code_mcp → 上溯 4 级）
+DEFAULT_CODE_ROOT = Path(__file__).resolve().parents[4]
+CODE_ROOT = Path(os.environ.get("CODE_ROOT", DEFAULT_CODE_ROOT))
+
+index = CodeIndex(CODE_ROOT).load()
+knowledge = KnowledgeSearch(CODE_ROOT)
+exporter = ProjectExporter(CODE_ROOT)
+
+try:
+    _MCP_VERSION = pkg_version("ht32-code-mcp")
+except PackageNotFoundError:
+    _MCP_VERSION = "unknown (开发模式)"
+
+_INSTRUCTIONS = """HT32 代码知识库（函数库/例程/工程模板），当前覆盖 HT32F5（M0+，官方固件库 V1.21.1 原档）。
+写 HT32 代码必须基于本库真实函数库知识，不要编造 API/宏/路径。
+
+## 按需求选工具
+- 确认版本/覆盖范围 → get_code_version
+- 问"某外设库怎么用/有哪些模块" → list_libraries → search_code_knowledge(模块名)
+- 找官方例程（按外设/系列/芯片） → find_example → get_file(例程路径) 看原码
+- 取 raw/ 真实源文件（驱动 .c/.h、例程、devices.json 等） → get_file
+- 检索知识页（初始化套路/易错点/子系列差异） → search_code_knowledge
+- 新建工程 → get_project_manifest 看模板 → export_project_bundle(chip, out_dir) 导出自包含工程
+
+## 通用约定
+- 路径一律为仓库相对 posix 路径（raw/... 开头），get_file 直接可用
+- 型号大小写自动归一（ht32f52352 = HT32F52352）
+- 知识页查不到时不要编造，改查 list_libraries + get_file 原码
+"""
+
+mcp = FastMCP("ht32-code", instructions=_INSTRUCTIONS)
+
+
+# ================================================================ MCP Tools
+
+
+def _series_of_chip(chip: str) -> tuple[str | None, str | None]:
+    """芯片型号 → (系列标签, 模板名)。对照模板 devices.json（如 HT32F52352 → f5, ht32f5-keil）。"""
+    want = chip.strip().upper()
+    for t in index.data.get("templates", []):
+        if any(d.upper() == want for d in t.get("devices", []) if d):
+            return normalize_series(t["name"].split("-")[0]), t["name"]
+    return None, None
+
+
+@mcp.tool()
+def get_code_version() -> str:
+    """获取代码知识库版本与 manifest 统计信息。
+
+    返回：知识库版本（VERSION 文件）、固件库覆盖、模板状态、
+    库模块/例程/知识页/raw 文件统计与索引构建时间。
+    """
+    version_file = CODE_ROOT / "VERSION"
+    version_text = version_file.read_text(encoding="utf-8", errors="replace").strip() \
+        if version_file.is_file() else "(VERSION 文件缺失)"
+    stats = index.data.get("stats", {})
+    lines = [
+        f"ht32-code 知识库版本：{index.data.get('code_version', 'unknown')}",
+        f"MCP server：ht32-code-mcp {_MCP_VERSION}",
+        "",
+        "VERSION 文件内容：",
+        version_text,
+        "",
+        "索引统计（预构建 JSON 索引，built_at "
+        f"{index.data.get('built_at', '?')}）：",
+        f"- 固件库包：{stats.get('fwlib_packages', 0)}",
+        f"- 库模块：{stats.get('library_modules', 0)}",
+        f"- 例程：{stats.get('examples', 0)}（{stats.get('example_peripherals', 0)} 个外设目录）",
+        f"- 工程模板：{stats.get('templates', 0)}",
+        f"- 知识页：{stats.get('knowledge_pages', 0)}",
+        f"- raw/ 文件总数：{stats.get('raw_files', 0)}",
+    ]
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def list_libraries() -> str:
+    """枚举函数库模块与覆盖系列。
+
+    返回每个库模块的驱动源码/头文件路径（raw/）、变体数、
+    对应官方例程数与知识页路径（entities/libraries/）。
+    """
+    lines = ["库模块清单（模块名按官方驱动 .c 文件名归一）："]
+    for pkg in index.data.get("fwlibs", []):
+        series = "/".join(pkg.get("series") or ["?"]) + (f"（{pkg['family']}）" if pkg.get("family") else "")
+        ex_counts: dict[str, int] = {}
+        for ex in pkg.get("examples", []):
+            ex_counts[ex["peripheral"].lower()] = ex_counts.get(ex["peripheral"].lower(), 0) + 1
+        page_paths = {p["path"] for p in index.data.get("knowledge_pages", [])}
+        modules: dict[str, list[dict]] = {}
+        for m in pkg.get("modules", []):
+            modules.setdefault(m["module"], []).append(m)
+        lines.append("")
+        lines.append(f"== 固件库 {pkg['name']}（系列 {series}）== "
+                     f"共 {len(modules)} 个模块")
+        for mod in sorted(modules):
+            variants = modules[mod]
+            srcs = "、".join(v["src"] for v in variants)
+            page = f"entities/libraries/{mod}.md"
+            page_note = page if page in page_paths else "—"
+            lines.append(
+                f"- {mod}：{len(variants)} 个驱动变体 | {srcs}"
+                f" | 例程 {ex_counts.get(mod, 0)} 个 | 知识页 {page_note}"
+            )
+    lines.append("")
+    lines.append("用法：模块详情查 search_code_knowledge(模块名)；原码用 get_file(路径)。")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def find_example(peripheral: str, series: str = "", chip: str = "", limit: int = 10) -> str:
+    """按外设/系列/芯片查找官方例程，返回路径与简介。
+
+    Args:
+        peripheral: 外设名（如 gpio / usart / adc / gptm），大小写不敏感，
+            支持精确或包含匹配（usart 亦命中 UART 目录的别名说明）
+        series: 系列过滤（f5 / HT32F5 / M0+），默认不过滤
+        chip: 芯片型号（如 HT32F52352）。官方例程为家族通用（readme 不标注
+            具体型号），本参数先对照模板 devices.json 确认型号受支持，
+            再按其所属系列过滤例程
+        limit: 返回上限，默认 10
+    """
+    pool = list(index.data.get("fwlibs", []))
+    chip_note = ""
+    if chip:
+        chip_series, tpl = _series_of_chip(chip.strip())
+        if chip_series is None:
+            devices: list[str] = []
+            for t in index.data.get("templates", []):
+                devices += [d for d in t.get("devices", []) if d]
+            return (f"芯片 '{chip}' 不在支持列表（当前 {len(devices)} 个型号，"
+                    "见 get_project_manifest / devices.json）。\n"
+                    f"可用示例（前 20）：{', '.join(devices[:20])}…")
+        pool = [p for p in pool
+                if chip_series in [normalize_series(s) for s in p.get("series", [])]]
+        chip_note = f"\n（例程为家族通用，已按 {chip.strip().upper()} 所属系列过滤；" \
+                    f"型号已在模板 {tpl} 支持列表确认）"
+    if series:
+        want = normalize_series(series)
+        want_family = series.strip().lower().rstrip("+")
+        pool = [p for p in pool
+                if any(normalize_series(s) == want for s in p.get("series", []))
+                or p.get("family", "").lower() == want_family]
+        if not pool:
+            return f"系列 '{series}' 不在覆盖范围。当前覆盖：" + "、".join(
+                f"{p['name']}" for p in index.data.get("fwlibs", []))
+    query = peripheral.strip().lower()
+    matches: list[dict] = []
+    for p in pool:
+        for ex in p.get("examples", []):
+            hay = f"{ex['peripheral']}/{ex['name']}".lower()
+            if ex["peripheral"].lower() == query or query in hay:
+                matches.append(ex)
+    if not matches:
+        known = sorted({ex["peripheral"] for p in pool for ex in p.get("examples", [])})
+        return (f"未找到外设 '{peripheral}' 的例程。可用外设目录（{len(known)} 个）："
+                + "、".join(known))
+    chip_filter_note = chip_note
+    matches = matches[:limit]
+    lines = [f"找到 {len(matches)} 个 '{peripheral}' 例程：{chip_filter_note}"]
+    for ex in matches:
+        brief = f" — {ex['brief']}" if ex.get("brief") else ""
+        files = ", ".join(ex.get("files", []))
+        lines.append(f"- {ex['peripheral']}/{ex['name']}{brief}\n"
+                     f"  路径: {ex['path']}\n  文件: {files}")
+    lines.append("原码获取：get_file(\"<路径>/main.c\")；知识页：search_code_knowledge(\""
+                 + peripheral.lower() + "\")。")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_file(path: str, max_length: int = 50000) -> str:
+    """获取 raw/ 下真实文件内容（只读原档，字节冻结）。
+
+    Args:
+        path: 仓库相对路径（raw/... 开头；可省略 raw/ 前缀自动补全），
+            如 "raw/HT32_STD_5xxxx_FWLib_V1.21.1/library/HT32F5xxxx_Driver/src/ht32f5xxxx_gpio.c"
+        max_length: 返回最大字符数，默认 50000；-1 取全文
+    """
+    norm = path.strip().replace("\\", "/")
+    while norm.startswith("./"):
+        norm = norm[2:]
+    if not norm:
+        return "错误：path 不能为空。"
+    if len(norm) > 2 and norm[1] == ":" or norm.startswith("/"):
+        return f"错误：只接受仓库相对路径（raw/...），拒绝绝对路径：{path}"
+    parts = norm.split("/")
+    if ".." in parts:
+        return f"错误：路径不允许包含 '..'：{path}"
+    if not norm.startswith("raw/"):
+        norm = "raw/" + norm
+    known = set(index.data.get("files", []))
+    target = CODE_ROOT / Path(*norm.split("/"))
+    if norm not in known and not target.is_file():
+        return (f"错误：文件不存在：{norm}\n"
+                f"提示：路径须为 raw/ 下真实文件（可用 find_example / list_libraries 取路径）。")
+    raw_root = (CODE_ROOT / "raw").resolve()
+    if raw_root not in target.resolve().parents:
+        return f"错误：路径越界（只允许 raw/ 下文件）：{path}"
+    try:
+        blob = target.read_bytes()
+    except OSError as e:
+        return f"错误：读取失败：{e}"
+    if b"\x00" in blob[:8192]:
+        return (f"错误：'{norm}' 是二进制文件（{len(blob)} 字节），不提供内容读取；"
+                "文本源码/头文件/例程均可读取。")
+    text = blob.decode("utf-8", errors="replace")
+    if max_length >= 0 and len(text) > max_length:
+        return (f"[{norm}]（截取前 {max_length}/{len(text)} 字符，"
+                f"如需更多请重传 max_length={min(max_length * 2, len(text))} 或 -1 取全文）\n\n"
+                + text[:max_length])
+    return text
+
+
+@mcp.tool()
+def search_code_knowledge(query: str, limit: int = 5) -> str:
+    """检索知识页（entities/libraries/ 函数库用法 + comparisons/ 系列差异）。
+
+    适合：库模块初始化套路、API 易错点、子系列差异、换型号 checklist。
+    知识页只写使用知识；原码用 find_example + get_file 获取。
+
+    Args:
+        query: 关键词，如 "GPIO 输出初始化"、"USART 中断"、"子系列差异"、"libcfg"
+        limit: 返回上限，默认 5
+    """
+    results = knowledge.search(query, limit=limit)
+    if not results:
+        return ("未找到匹配知识页。建议：换模块官方名小写重试（gpio/usart/adc…），"
+                "或用 list_libraries 看模块清单后 get_file 直取原码。")
+    lines = [f"找到 {len(results)} 条结果（按相关性排序）："]
+    for i, (page, score, snippet) in enumerate(results, 1):
+        lines.append(f"--- 结果 {i} [{page.title}]（相关度 {score:.0f}）---")
+        lines.append(f"路径: {page.path}")
+        lines.append(snippet)
+        lines.append("")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_project_manifest() -> str:
+    """获取工程模板清单（raw/templates/）。
+
+    返回模板结构、默认芯片、支持的型号数与用法；配合 export_project_bundle
+    导出自包含可编译工程。
+    """
+    templates = index.data.get("templates", [])
+    if not templates:
+        return "raw/templates/ 下暂无模板。"
+    lines = [f"工程模板清单（{len(templates)} 个）："]
+    for t in templates:
+        lines.append("")
+        lines.append(f"== {t['name']} ==")
+        lines.append(f"路径: {t['path']}")
+        lines.append(f"默认芯片: {t.get('default_device') or '—'}")
+        lines.append(f"支持型号: {t.get('device_count', 0)} 个（devices.json，"
+                     "完整参数表可 get_file(\"" + t["path"] + "/devices.json\")）")
+        lines.append(
+            "结构: Application/（main、it、conf）+ CMSIS/（设备头+system）+ "
+            "Drivers/（最小驱动集+libcfg）+ Startup/ + MDK-ARM/（Keil 工程文件）"
+        )
+    lines.append("")
+    lines.append("导出工程：export_project_bundle(chip, out_dir) —— 按型号参数化"
+                 "（Device/C 宏/汇编宏/system/startup/libcfg）并注入官方库源码，"
+                 "产出自包含可编译工程。")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def export_project_bundle(chip: str, out_dir: str) -> str:
+    """按芯片型号从模板组装自包含可编译 Keil 工程到本地目录。
+
+    动作：复制 raw/templates/ht32f5-keil 模板 → 按 devices.json 参数化
+    uvprojx（Device、C 宏、汇编宏）→ 从官方库注入对应 system/startup/libcfg
+    文件。产物可直接用 Keil MDK 打开编译（需 HT32_DFP pack）。
+    本阶段为本地目录导出；云端 token 下载 URL 后续阶段扩展。
+
+    Args:
+        chip: 芯片型号，如 "HT32F52352"（大小写不敏感）
+        out_dir: 输出目录（须为空目录或不存在；不会覆盖已有内容）
+    """
+    try:
+        return exporter.export(chip, out_dir)
+    except ExportError as e:
+        return f"导出失败：{e}"
+
+
+# ================================================================ 入口
+
+
+def main() -> None:
+    """入口：按 MCP_TRANSPORT 环境变量启动（默认 stdio，P0 本地阶段）。"""
+    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)
+    print(f"[ht32-code-mcp] 知识库版本: {index.data.get('code_version', '?')}"
+          f"（索引 built_at {index.data.get('built_at', '?')}）", file=sys.stderr)
+    print(f"[ht32-code-mcp] 知识库根目录: {CODE_ROOT}", file=sys.stderr)
+    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)
+        mcp.run(transport="stdio")
+    else:
+        print(f"[ht32-code-mcp] 传输模式 '{transport}' 暂未启用（P0 仅 stdio）", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

ht32_code_mcp-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+ht32_code_mcp/__init__.py,sha256=SBNKjUnBKjYQtw0TidyBOx2NFTcSpCJ-Gh9x7oujINs,109
+ht32_code_mcp/__main__.py,sha256=P3nY1dMtxQ9y8V1VICOufkO950OKDMRHIE-vXy8w3Aw,88
+ht32_code_mcp/exporter.py,sha256=vTCvVAZoydf-b7h3XpEo1ubIEsgz2CazMS8ECYHJQ8M,8177
+ht32_code_mcp/index.py,sha256=S0ghDMeyCSfI4NrTI1eOXI4FJQm_zHLtQHMOuqQR8pk,9622
+ht32_code_mcp/knowledge.py,sha256=P8XlNlCdDRzksQKqgkCzjFZkIfprIBoePPtRCEcM1qE,3566
+ht32_code_mcp/server.py,sha256=mUjfGo_2EI8YksIrtBTEQ8wCszQXKX6l1kzVe2DhcG0,15180
+ht32_code_mcp-0.1.0.dist-info/METADATA,sha256=Gz4vS8AoOoCN-q5_vMkUucSRY2EWQM_m-48Sizs_WfE,595
+ht32_code_mcp-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+ht32_code_mcp-0.1.0.dist-info/entry_points.txt,sha256=W0VlSn_R5exzRG2xKs_1kjayo0KEmeh8DphQKbUZPMo,60
+ht32_code_mcp-0.1.0.dist-info/RECORD,,

ht32_code_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

ht32_code_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ht32-code-mcp = ht32_code_mcp.server:main