内容
# H7-TOOL MCP 助手
[中文说明](README.zh-CN.md)
本项目为 H7-TOOL 提供本地 MCP 服务器。在 AI 客户端启用后，AI 可以调用与 H7-TOOL 相关的工具来检查连接的编程器，搜索本地设备库，识别目标板，并读取开发诊断信息。
公开文档仅涵盖安装和使用。产品内部通信细节在此故意不予以记录。
## 功能概述
- 列出可用的 H7-TOOL USB 接口和本地桥接设置。
- 读取 H7-TOOL 状态和健康信息。
- 按供应商、系列或芯片名称搜索本地 H7-TOOL 设备 Lua 库。
- 搜索捆绑的 H7-TOOL Lua 示例和总线助手脚本，以便 AI 可以检查原始外设用法。
- 为 AI 编写的 H7-TOOL Lua 助手脚本提供公共安全和样式规则。
- 提供离线 Lua 草稿工作区，以创建、列出、读取和验证草稿，而无需执行它们。
- 静态审查 Lua 草稿，只有在显式执行确认后才能运行已验证的草稿。
- 为未来编程、擦除、解锁、保护、电源和原始 Lua 操作提供危险操作策略门。
- 解析设备配置文件以获取接口类型、预期 ID、UID 位置、内存范围、包含的库和算法条目。
- 总结配置文件功能，以便 AI 可以了解芯片配置文件支持的内容。
- 探测连接的 STM32H7 目标，并将实时结果与选定的本地配置文件结合起来。
- 读取有界目标内存范围以进行诊断。
- 读取由选定的本地配置文件描述的选项字节值。
- 在选定的配置文件提供所需规则时，总结保护状态。
- 通过 H7-TOOL UART 通道发送和接收短数据以进行环回测试、AT 命令和简单串行调试。
- 通过 H7-TOOL 发送有界 CAN/CAN-FD 帧。
- 扫描 I2C 地址或执行有界 I2C 写/读事务。
- 执行具有 CS0 或 CS1 的有界 SPI 写/读事务。
- 尝试从目标固件读取 SEGGER RTT 上缓冲区日志。
## 目录布局
推荐布局：
```text
h7toolPC_release/
EMMC/
H7-TOOL/
Programmer/
Device/
mcp/
h7tool_mcp.py
README.md
requirements.txt
config.json
```
换句话说，将此存储库作为 `mcp` 目录放置在 H7-TOOL PC 软件包根目录下，与 `EMMC` 并列。
示例：
```powershell
cd D:\Tools\h7toolPC_release
git clone https://github.com/zhe0523/h7tools-mcp.git mcp
```
此布局允许 MCP 服务器自动找到 H7-TOOL 设备库。
## 安装
使用 Python 3.11 或更新版本。
```powershell
cd D:\Tools\h7toolPC_release\mcp
python -m pip install -r requirements.txt
python h7tool_mcp.py --self-test
```
如果自检打印 `Self-test passed`，则 Python 端已正常工作。
## 配置 H7-TOOL 访问
从与您的连接方式匹配的示例创建本地 `config.json`。当前最常见的路径是 USB HID：
```powershell
copy config.usb-hid.example.json config.json
python h7tool_mcp.py --list-hid-devices
```
如果找到多个匹配的 H7-TOOL 接口，请将正确的 `serial_number` 复制到 `config.json` 中。
有用的本地检查：
```powershell
python h7tool_mcp.py --device-vendors
python h7tool_mcp.py --device-search STM32H743 --device-vendor ST
python h7tool_mcp.py --lua-example-search BH1750 --lua-example-interface i2c
python h7tool_mcp.py --lua-authoring-rules
python h7tool_mcp.py --lua-draft-list
python h7tool_mcp.py --lua-draft-review example.lua
python h7tool_mcp.py --dangerous-action-policy
python h7tool_mcp.py --device-profile ST/STM32H7xx/STM32H7x_2M.lua
python h7tool_mcp.py --lua-health
python h7tool_mcp.py --target-identity ST/STM32H7xx/STM32H7x_2M.lua
python h7tool_mcp.py --target-summary ST/STM32H7xx/STM32H7x_2M.lua
python h7tool_mcp.py --target-flash-info ST/STM32H7xx/STM32H7x_2M.lua
```
`config.json` 被 git 故意忽略，因为它包含本地设备设置。
默认情况下禁用危险操作。未来的编程、擦除、解锁、保护、电源控制和原始 Lua 工具必须检查 `config.json` 中的 `dangerous_actions`，并在每次请求时都需要匹配的确认短语。
## 启动 MCP 服务器
MCP 服务器使用 stdio。通常您不需要手动启动它；您的 AI 客户端会启动它。
在 Windows 上，优先使用启动器脚本：
```text
D:\Tools\h7toolPC_release\mcp\h7tool_mcp.cmd
```
将路径替换为机器上的绝对路径。启动器避免了许多与 Python 启动器、参数拆分、非 ASCII 路径和包含空格的路径相关的客户端特定差异。
对于手动命令行检查，请使用 `--help` 显示的标志之一：
```powershell
python h7tool_mcp.py --help
```
当未提供标志时，程序等待 stdin/stdout 上的 MCP JSON-RPC 消息，这是 MCP 客户端所期望的。
## 从 AI 工具连接
配置此存储库的 `h7tool_mcp.cmd` 作为本地 stdio MCP 服务器。
在连接 AI 客户端之前，请从终端验证服务器：
```powershell
cd D:\Tools\h7toolPC_release\mcp
.\h7tool_mcp.cmd --self-test
.\h7tool_mcp.cmd --lua-health
```
然后验证您计划公开给 AI 的任何硬件工作流程：
```powershell
.\h7tool_mcp.cmd --target-summary ST/STM32H7xx/STM32H7x_2M.lua --include-protection-status
.\h7tool_mcp.cmd --uart-transact --uart-channel 1 --uart-baud 115200 --uart-send-hex "48 37 0D 0A" --uart-rx-length 64
.\h7tool_mcp.cmd --i2c-transact --i2c-clock 100000 --i2c-scan
.\h7tool_mcp.cmd --spi-transact --spi-freq-id 0 --spi-cs 0 --spi-write-hex "9F" --spi-read-length 3
```
大多数 AI 客户端需要相同的字段：
- 名称：`h7tool`
- 类型：`stdio`
- 命令：`D:\Tools\h7toolPC_release\mcp\h7tool_mcp.cmd`
- 参数：空
如果客户端无法直接启动 `.cmd`，请使用 `cmd` 作为命令，并使用 `/c D:\Tools\h7toolPC_release\mcp\h7tool_mcp.cmd` 作为参数。
### Codex / ChatGPT Desktop / Codex IDE
打开 Codex MCP 设置并添加一个 stdio 服务器，或编辑 `~/.codex/config.toml`:
```toml
[mcp_servers.h7tool]
command = 'D:\Tools\h7toolPC_release\mcp\h7tool_mcp.cmd'
args = []
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60
```
您也可以使用 Codex CLI 添加它：
```powershell
codex mcp add h7tool -- D:\Tools\h7toolPC_release\mcp\h7tool_mcp.cmd
codex mcp list
```
添加服务器后，重启或重新加载 AI 客户端，如果它没有立即出现。请 AI 调用 `bridge_status` 以确认连接。
### Cherry Studio
在 Cherry Studio 中，打开 `Settings -> MCP Server -> Add server`，选择 `STDIO`，然后设置：
```text
Name: h7tool
Command: D:\Tools\h7toolPC_release\mcp\h7tool_mcp.cmd
Arguments: empty
```
中文逐步指南：[Cherry Studio 配置 H7-TOOL MCP 教程](docs/cherry-studio.zh-CN.md)。
### Claude Code / Claude Desktop / opencode
这些客户端使用相同的本地 stdio MCP 想法。中多客户端指南：[AI 客户端接入 H7-TOOL MCP 指南](docs/ai-clients.zh-CN.md)。
Lua 助手编写规则在中文此处记录：[AI 编写 H7-TOOL Lua 辅助脚本规则](docs/lua-authoring-rules.zh-CN.md)。
## 如何请求 AI 使用它
一旦 MCP 服务器连接，请请求 AI 直接使用 H7-TOOL 工具。示例提示：
```text
使用 h7tool MCP 服务器列出可用的 H7-TOOL 接口。
```
```text
使用 h7tool 在本地设备库中搜索 STM32H743。
```
```text
使用 h7tool lua_example_search 查找捆绑的 I2C BH1750 示例，并总结它们的使用方法。
```
```text
使用 h7tool lua_authoring_rules 在草拟自定义 H7-TOOL Lua 助手脚本之前。
```
```text
使用 h7tool lua_draft_create 草拟一个 I2C 注册表读取 Lua 助手，然后使用 lua_draft_validate 验证它而不执行它。
```
```text
使用 h7tool lua_draft_review 将 Lua 草稿分类为非破坏性或危险性，然后再运行它。
```
```text
使用 h7tool dangerous_action_policy 检查是否允许编程、擦除、解锁、保护和类似的危险操作。
```
```text
使用 h7tool target_identity 以及 ST/STM32H7xx/STM32H7x_2M.lua，并总结连接的目标。
```
```text
使用 h7tool target_summary 以及 ST/STM32H7xx/STM32H7x_2M.lua，并推荐下一步诊断。
```
```text
使用 h7tool protection_status 获取选定的 STM32H7 配置文件，并解释结果。
```
```text
使用 h7tool uart_transact 在通道 1 上，115200 8N1，发送十六进制：48 37 0D 0A，并读取最多 64 个响应字节。
```
```text
使用 h7tool can_transact 以 500K 波特率发送标准帧 ID 0x321 和数据 01 02 03 04。
```
```text
使用 h7tool i2c_transact 在 100K 时钟下扫描 I2C 地址。
```
```text
使用 h7tool spi_transact，频率 ID 为 0，相位为 0，极性为 0，CS0，发送十六进制 9F，并读取 3 个字节。
```
```text
使用 h7tool rtt_read 尝试读取目标 RTT 通道 0 日志。
```
良好的工作流程：
1. 请求 AI 检查 `bridge_status`。
2. 请求它搜索或检查目标设备配置文件。
3. 请求它运行 `lua_health` 或 `health_summary`。
4. 请求它运行 `target_summary`。
5. 仅在选择目标配置文件后，请求聚焦的内存、选项字节、RTT 或外设事务。
## 可用的 MCP 工具
- `bridge_status`
- `device_vendors`
- `device_search`
- `lua_example_search`
- `lua_authoring_rules`
- `lua_draft_create`
- `lua_draft_list`
- `lua_draft_read`
- `lua_draft_validate`
- `lua_draft_review`
- `lua_draft_run`
- `dangerous_action_policy`
- `dangerous_action_explain`
- `device_profile`
- `device_capabilities`
- `tool_status`
- `health_summary`
- `lua_health`
- `target_probe`
- `target_identity`
- `target_summary`
- `target_flash_info`
- `tool_registers`
- `read_option_bytes`
- `protection_status`
- `uart_transact`
- `can_transact`
- `i2c_transact`
- `spi_transact`
- `rtt_read`
- `log_tail`
- `read_memory`
## 注意
H7-TOOL 包中的设备脚本通常描述整个芯片系列而不是一个确切的零件编号。例如，搜索 `STM32H743` 可能会返回一个通用的 STM32H7 配置文件。当需要精确识别时，请将实时目标数据、配置文件元数据和芯片特定寄存器结合使用。
同一时间只有一个程序应该主动控制相同的 H7-TOOL 操作路径。如果 AI 调用超时或返回意外结果，请在 PC 工具中关闭冲突操作并重试。
连接信息
猜你喜欢
暂无推荐服务器