JannLeo/telinksdk-builder-mcp

English | 简体中文
通用、SDK 无关的构建编排工具,让 AI 编程助手(Trae / Claude Desktop / Cursor / Cline 等)通过自然语言调用任意 SDK 仓库的构建脚本。
打包为 **TraeCLI plugin**(含 skill + slash command + MCP server),同时其 **MCP server 是标准协议**,任何支持 MCP 的客户端都能直接接入。也可纯命令行使用,不依赖任何 AI 工具。
一键安装
**Trae CLI:**
**其他 MCP 客户端(Claude Desktop / Cursor / Cline):** 见下方给非 Trae 工具用。
Demo
在 Trae 里打开任意 Telink SDK 仓库,对话直接说:
**/build-init 输出**(自动检测,生成配置):
**/build b80_dongle_flash 输出**(真实编译,产物回传):
**/build info 输出**(查看配置):
组成
| 文件 | 作用 |
|------|------|
| trae_build_runner.py | 通用构建运行器。读取项目根的 builder.json(或旧名 robin_builder.json),按 preset / 参数调用配置中指定的构建脚本,收集产物。可独立命令行使用。 |
| trae_build_mcp.py | MCP stdio server(零依赖,纯 Python stdlib)。暴露 4 个工具,供任意 MCP 客户端调用。内部委托给 runner。 |
| trae_builder_schema.json | builder.json 的 JSON Schema,可用于校验/IDE 补全。 |
工作原理
1. 任意 SDK 仓库根放一个 builder.json,声明:构建脚本路径、参数列表、预设、产物目录。
2. trae_build_mcp.py 被 Trae 以 stdio 方式拉起,自动发现当前工作区的 builder.json。
3. 在 Trae 对话里说"用 rx_default 预设编译",agent 调用 build_run 工具,runner 据此生成命令并执行构建脚本,产物扫描后回传。
换仓库时只要新仓库自带 builder.json,同一份 trae_builder 工具链直接复用,无需改动。
暴露的 MCP 工具
| 工具 | 说明 |
|------|------|
| build_info | 显示当前项目的构建配置(参数、预设、产物配置、工具链)。不执行编译。 |
| build_presets | 列出 builder.json 里定义的预设。 |
| build_run | 执行一次构建。可传 preset 和/或 params 覆盖;dry_run 只打印命令不执行。 |
| build_list | 列出已收集的构建产物(按 artifacts.scan_dirs 和 max_age_hours 过滤)。 |
| serial_list | 列出本机可用串口(Windows COMx / Linux/macOS /dev/tty*)。需 pyserial。 |
| serial_capture | 抓取串口输出(默认 5 秒/200 行),用于烧录后验证固件行为。端口/波特率默认取 builder.json 的 serial 段;留空自动选第一个串口。agent 拿到日志原文自行判断"功能对不对"(如有没有 boot ok/版本号)。需 pyserial。 |
| flash_info | 显示 builder.json 的 flash 段(默认芯片、bdt.exe 路径、超时、是否自动复位)。不调用 bdt。 |
| flash_run | 调用 Telink bdt.exe 烧录/读写/复位芯片(wf 烧录、rf 读 flash、rst 复位等)。芯片名默认取 flash.default_chip;wf 不指定 input_file 时自动取 build_variants 下最新 .bin 产物,实现"编译→烧录"闭环;烧录成功后默认自动 rst -f 复位(可关)。 |
命令行直接使用(不经过 Trae)
完整闭环:编译 → 烧录 → 看串口
在 Trae 对话里一句话串起整个嵌入式开发流程:
依赖
- **Python 3.8+**
- **构建功能**:零第三方依赖(纯 stdlib)
- **串口抓取**:可选依赖 pyserial(pip install pyserial),未装时 serial_list/serial_capture 会给出友好提示
- **Eclipse headless 编译**:需对应平台的 Telink IoT Studio / Eclipse CDT
注册到 Trae CLI
在 ~/.trae/trae_cli.yaml(用户级,对所有项目生效)添加:
或在项目根放 .mcp.json(项目级):
注册后用 trae-cli doctor 检查连接状态;在交互模式用 /mcp 查看详情和工具列表。
> **关于 MCP 工具的可见性**:stdio MCP server 是异步加载,会话启动的 init 事件里 mcp_servers 可能为空(此时握手尚未完成),但通常 1 秒内握手完成,工具即可被 agent 调用。若首轮 prompt 调用 MCP 工具偶发失败,重试或等待片刻即可(详见 trae-cli 文档「首轮调用 MCP 工具失败/第二轮自动恢复」)。本工具链已在 tc_ble_lite_sdk-1.2.2_allinone 上实测 build_info 与 build_run 均可正常返回。
在 Trae 里直接编译: /build 自定义命令
除 MCP 外,还提供了 /build 自定义 prompt command(走 Bash 工具调 runner,不依赖 MCP),作为更直观的入口。
命令文件已放在 ~/.trae/commands/build.md(用户级,对所有项目生效)。在任意含 builder.json 的仓库根目录打开 Trae,输入:
/build 会自动用 ${workspaceFolder} 定位当前仓库,调用 trae_build_runner.py,并把结果整理后汇报。
> Windows 终端注意:在 cmd.exe 里用 trae-cli -p "/build ..." 带空格参数可能被截断;推荐在 VSCode 集成终端( PowerShell )里直接输入 /build ...,或用 trae-cli -p 时整体加引号并在 PowerShell 下运行。
让旧仓库接入: /build-init 自动生成 builder.json
旧仓库没有 builder.json 时,用 /build-init 一键扫描并生成:
/build-init 调用 trae_build_init.py,自动识别常见构建模式:
| 模式 | 识别方式 | 生成内容 |
|------|---------|---------|
| **Telink A 型**(release_sdk_tool) | 找 tools/release_sdk_tool/compile.bat | IDE 路径、芯片列表(B80/B80B/tc122x 等)、每芯片一个预设 |