HT32 Wiki MCP Server — 合泰 MCU 知识检索技能

技能简介

HT32 Wiki MCP Server 是一款专为 AI Agent 打造的合泰（Holtek）HT32 系列 MCU 选型与知识检索 MCP 服务器。它把 HT32 芯片页、外设页、概念页和 Datasheet 构成的知识库，通过 Model Context Protocol（MCP）暴露为 8 个可调用工具，让 AI Agent 在回答硬件选型、外设规格、参数对比等问题时，能够基于真实知识库而非凭记忆作答，从根源上减少 MCU 领域的「幻觉」问题。项目还内置了纠错反馈闭环：当 Agent 回答不准确或知识库存在缺失时，可调用 submit_feedback 提交反馈，帮助知识库持续迭代演进。

核心能力

• 全文知识检索（search_knowledge）：跨芯片页、外设页、概念页与 Datasheet 的全文搜索，一次查询即可定位相关知识条目
• 芯片详情查询（get_chip_info）：按型号获取芯片系列完整规格信息，包括内核、主频、存储、封装等
• 外设详情查询（get_peripheral_info）：按名称获取指定外设的功能说明与寄存器说明
• 多芯片对比（compare_chips）：一次传入多个型号，输出参数横向对比表，选型效率大幅提升
• 芯片/外设清单（list_chips / list_peripherals）：列出知识库收录的全部芯片与外设，快速了解覆盖范围
• Datasheet 全文获取（get_datasheet）：按系列获取完整 Datasheet 文本，供 Agent 深入分析
• 知识库版本查询（get_wiki_version）：返回当前知识库版本信息，确保引用数据时效性
• 纠错反馈机制（submit_feedback）：支持提交错误类型、正确答案、原始问题等结构化反馈，按日期分文件落盘

安装配置

配置一：stdio 模式（供 supergateway / 1Panel 包装为 SSE）

uvx ht32-wiki-mcp

这是最简部署方式，适用于需要把 MCP 包装成 SSE 服务暴露给上游客户端的场景。

配置二：Streamable HTTP 模式（推荐多客户端共享）

MCP_TRANSPORT=streamable-http uvx ht32-wiki-mcp

启动后监听 HTTP 端口，多个 AI 客户端可共享同一个知识库服务进程。

配置三：环境变量调优

配置四：本地开发调试

uv sync --frozen
uv run python -m ht32_wiki_mcp

使用步骤

第一步：部署 MCP 服务

选择上述任一配置方式启动服务。若使用 Docker 部署，记得把 FEEDBACK_DIR 挂载为持久卷，否则反馈数据会随容器销毁而丢失。

第二步：在 AI 客户端中注册 MCP

在 Open WebUI、Claude Desktop 或其他支持 MCP 的客户端中添加服务器配置，指向已启动的 stdio 命令或 HTTP 端点。

第三步：配置系统提示词（关键）

部署 Open WebUI 等客户端时，建议在系统提示词中加入以下内容，以确保 Agent 正确调用工具并触发反馈机制：

你是一个 HT32 MCU 技术专家助手，基于 HT32 Wiki 知识库回答问题。

工具使用规范：
1. 回答涉及芯片选型、外设规格、参数对比时，优先调用 search_knowledge / get_chip_info / get_peripheral_info / compare_chips 检索知识库，不要凭记忆回答。
2. 当出现以下情况时，必须调用 submit_feedback 工具提交反馈：
   - 用户明确指出你的回答有误
   - 你从知识库查到的数据与用户描述矛盾
   - 知识库查不到相关信息，你只能给出推测性回答
   - 用户提供了比你回答更准确的型号/规格/参数信息
3. submit_feedback 的 question 参数尽量完整抄录用户原始问题；correction 填写正确信息。
4. 不确定的信息要如实说明"知识库未覆盖"，不要编造参数。

第四步：典型问答与选型

直接向 Agent 提问，例如「F52231 的 GPTM 最高频率是多少？」「对比 HT32F52352 和 HT32F1655 的差异」，Agent 会自动调用相应工具检索知识库作答。

第五步：提交反馈并迭代

当 Agent 回答有误或用户指出问题时，反馈以 JSON Lines 格式写入 FEEDBACK_DIR，按日期分文件保存（feedback_YYYY-MM-DD.jsonl）。示例记录：

{"timestamp":"2026-08-10T10:00:00+00:00","question":"F52231 GPTM 最高频率？","issue_type":"wrong_spec","answer":"48MHz","correction":"72MHz，参考 UserManual 时钟章节","details":""}

适用场景

• 硬件工程师选型：需要快速对比多款 HT32 型号的主频、存储、外设资源时，一次对话即可拿到对比结论
• 嵌入式开发答疑：开发过程中查询外设寄存器配置、时钟树、引脚复用等细节，无需反复翻 Datasheet
• AI 客服/技术支持：为芯片原厂或代理商搭建基于知识库的智能技术支持机器人
• 技术文档检索：把散落在多个 Datasheet 与 Wiki 页面中的信息统一检索入口
• 教学与培训：高校嵌入式课程中作为 MCU 知识问答助手，帮助学生快速查证参数
• 知识库共建：通过 submit_feedback 机制，让一线用户的使用反馈反哺知识库质量

适用人群

• 合泰 HT32 系列 MCU 的嵌入式硬件/固件工程师
• 需要为芯片产品搭建智能技术支持系统的厂商团队
• 使用 AI Agent 辅助硬件开发、希望减少参数幻觉的开发者
• 嵌入式教学与培训机构的技术讲师
• 维护 MCU 知识库、需要收集用户反馈的内容运营者

工作原理

HT32 Wiki MCP Server 采用「知识库 + MCP 工具 + 反馈闭环」三层架构：

1. 知识库层：以 wiki 仓库根目录（WIKI_ROOT）为数据源，知识按 entities（芯片页）、concepts（概念页）、md（Datasheet 文档）三类组织，检索时对三类内容统一建立索引
2. 工具层：通过 MCP 协议将 8 个方法暴露为可调用工具。检索类工具（search_knowledge）执行全文匹配，查询类工具（get_chip_info / get_peripheral_info / get_datasheet）按标识符精确取数，对比类工具（compare_chips）聚合多个型号参数后结构化输出
3. 反馈层：Agent 遇到回答不准确、用户纠错或知识库缺漏时调用 submit_feedback，反馈以 JSON Lines 追加写入 FEEDBACK_DIR，按日期切分文件，便于后续人工审核与知识库修正。整个服务零第三方依赖，可完全离线部署

官方链接

• PyPI：https://pypi.org/project/ht32-wiki-mcp/
• 项目主页：https://pypi.org/project/ht32-wiki-mcp/
• 安装方式：uvx ht32-wiki-mcp（无需克隆仓库即可运行）
• 反馈目录：FEEDBACK_DIR（默认为 /app/feedback）