Metadata-Version: 2.5
Name: ht32-wiki-mcp
Version: 0.3.7
Summary: HT32 Wiki MCP Server - 为 AI Agent 提供 HT32 MCU 选型与知识检索
License-Expression: MIT
Keywords: holtek,ht32,mcp,mcu,wiki
Classifier: Development Status :: 4 - Beta
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
Description-Content-Type: text/markdown

# HT32 Wiki MCP Server

为 AI Agent 提供 HT32 MCU 选型与知识检索能力的 MCP Server。

## 功能

- `search_knowledge(query)` — 全文搜索 wiki 知识库（芯片页、外设页、概念页、Datasheet）
- `get_chip_info(model)` — 获取芯片系列详情
- `get_peripheral_info(name)` — 获取外设详情
- `compare_chips(models)` — 对比多个芯片型号
- `list_chips()` / `list_peripherals()` — 列出芯片/外设清单
- `get_datasheet(series)` — 获取 Datasheet 全文
- `get_wiki_version()` — 获取知识库版本信息
- `submit_feedback(question, issue_type, ...)` — 提交纠正反馈，帮助改进知识库

## 使用方法

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `WIKI_ROOT` | 当前目录 | wiki 仓库根目录（含 entities/concepts/md） |
| `MCP_TRANSPORT` | `stdio` | `stdio` / `sse` / `streamable-http` |
| `MCP_HOST` | `0.0.0.0` | HTTP 模式监听地址 |
| `MCP_PORT` | `8100` | HTTP 模式监听端口 |
| `FEEDBACK_DIR` | `/app/feedback` | 反馈写入目录（需可写，建议挂载持久卷） |

### stdio 模式（供 supergateway/1Panel 包装为 SSE）

```bash
uvx ht32-wiki-mcp
```

### Streamable HTTP 模式

```bash
MCP_TRANSPORT=streamable-http uvx ht32-wiki-mcp
```

## 反馈机制（submit_feedback）

用户 Agent 在回答不准确、用户指出错误、或知识库信息缺失时，可调用 `submit_feedback` 提交纠正反馈。反馈以 JSON Lines 格式写入 `FEEDBACK_DIR`（默认 `/app/feedback`），按日期分文件（`feedback_YYYY-MM-DD.jsonl`）。

示例记录：

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

## System Prompt 提示词模板

部署 Open WebUI 或其他 MCP 客户端时，建议在系统提示词中加入以下内容，提升反馈触发率：

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

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

## 开发

```bash
uv sync --frozen
uv run python -m ht32_wiki_mcp
```
