telinksdk-builder-mcp

# Tool List [English](README.en.md) A universal, SDK-agnostic build orchestration tool that allows AI programming assistants (Trae / Claude Desktop / Cursor / Cline, etc.) to call build scripts from any SDK repository through natural language. Packaged as a **TraeCLI plugin** (including skill + slash command + MCP server), its **MCP server follows standard protocols**, allowing any MCP client that supports it to connect directly. It can also be used purely through the command line without relying on any AI tools.     ## One-Click Installation **Trae CLI:** ```bash trae-cli plugin marketplace add git@github.com:JannLeo/telinksdk-builder-mcp.git trae-cli plugin install telinksdk-builder ``` **Other MCP Clients (Claude Desktop / Cursor / Cline):** See [For Non-Trae Tools](#for-non-trae-toolsclaude-desktop--cursor--cline--command-line) below. ## Demo Open any Telink SDK repository in Trae and say: ``` > /build-init # One-click scan repository, automatically generate builder.json > /build b80_dongle_flash # Compile B80 dongle flash firmware ``` **`/build-init` Output** (automatic detection, generate configuration): ```text Detection result: Telink eclipse-only (C-type) Build script: scripts/eclipse_headless_build.py IDE path: C:\TelinkIoTStudio Presets (25): - 8366_dongle -> 8366_dongle_for_8373_km/8366_dongle - b80_dongle_flash -> B80_Driver_Demo/B80_dongle_flash - b80_dongle_otp -> B80_Driver_Demo/B80_dongle_otp - b80b_mouse_flash_sram -> B80B_Driver_Demo/B80b_mouse_flash_sram - lark_dongle_demo -> TC_PLATFORM_SDK_1211/Lark_Dongle_Demo ... (full coverage, no truncation) ``` **`/build b80_dongle_flash` Output** (actual compilation, product return): ```text ✓ build: success (exit=0, 42s) copied bin: build_variants/B80_Driver_Demo_b80_dongle_flash_20260717.bin (17400 bytes) ``` **`/build info` Output** (view configuration): ```text Project: telink_8373_kmd_2.4g_mode_sdk (eclipse) Configuration file: builder.json Parameters (5): IdePath / ProjectPath / BuildTarget / WorkspaceDir / OutputDir Presets (25): 8366_dongle, b80_dongle_flash, ... , lark_dongle_startup_from_boot Toolchain: TelinkIoTStudio.exe, default target 8366_dongle_for_8373_km/8366_dongle ``` ## Composition | File | Function | |------|------| | `trae_build_runner.py` | Universal build runner. Reads `builder.json` (or old name `robin_builder.json`) from the project root, calls the build script specified in the configuration by preset/parameter, and collects artifacts. Can be used independently through the command line. | | `trae_build_mcp.py` | MCP stdio server (zero dependency, pure Python stdlib). Exposes 4 tools for any MCP client to call. Internally delegates to the runner. | | `trae_builder_schema.json` | JSON Schema for `builder.json`, can be used for validation/IDE completion. | ## Working Principle 1. Place a `builder.json` in the root of any SDK repository, declaring build script paths, parameter lists, presets, and artifact directories. 2. `trae_build_mcp.py` is started by Trae in stdio mode, automatically discovering the `builder.json` of the current workspace. 3. In Trae conversation, say "Compile with rx_default preset", the agent calls the `build_run` tool, and the runner generates the command and executes the build script, scanning and returning the artifact. When changing repositories, as long as the new repository brings its own `builder.json`, the same `trae_builder` toolchain can be reused directly without modification. ## Exposed MCP Tools | Tool | Description | |------|------| | `build_info` | Displays the build configuration (parameters, presets, artifact configuration, toolchain) of the current project. Does not execute compilation. | | `build_presets` | Lists presets defined in `builder.json`. | | `build_run` | Executes a build. Can pass `preset` and/or `params` to override; `dry_run` only prints the command without execution. | | `build_list` | Lists collected build artifacts (filtered by `artifacts.scan_dirs` and `max_age_hours`). | | `serial_list` | Lists available serial ports on the local machine (Windows COMx / Linux/macOS /dev/tty*). Requires pyserial. | | `serial_capture` | Captures serial port output (default 5 seconds/200 lines) for verification of firmware behavior after burning. Port/baud rate defaults to the `serial` section in `builder.json`; leave blank to automatically select the first serial port. Requires pyserial. | | `flash_info` | Displays the `flash` section in `builder.json` (default chip, bdt.exe path, timeout, auto-reset). Does not call bdt. | | `flash_run` | Calls Telink `bdt.exe` to burn/write/reset chips (wf burning, rf read flash, rst reset, etc.). Chip name defaults to `flash.default_chip`; `wf` without specifying `input_file` automatically takes the latest `.bin` artifact to achieve a "compile→burn" closed loop; successful burning defaults to automatic `rst -f` reset (can be disabled). | ## Direct Command Line Usage (without Trae) ```powershell # View build configuration for a project python <BUILDER>/trae_build_runner.py --project <SDK path> info # Compile with preset (actual execution) python <BUILDER>/trae_build_runner.py --project <SDK path> build --preset rx_default # Custom parameters + timeout python <BUILDER>/trae_build_runner.py --project <SDK path> build --param Target=tx --param RomType=txrx --timeout 1200 # Only print command without execution python <BUILDER>/trae_build_runner.py --project <SDK path> build --preset rx_default --dry-run # List artifacts python <BUILDER>/trae_build_runner.py --project <SDK path> list # List serial ports (requires pyserial) python <BUILDER>/trae_build_runner.py --project <SDK path> serial list # Capture serial port output for 5 seconds (port/baud rate defaults to builder.json's serial section, leave blank to auto-select the first) python <BUILDER>/trae_build_runner.py --project <SDK path> serial capture --port COM3 --baud 115200 --duration 5 # Burn firmware (chip defaults to flash.default_chip; wf without --input automatically takes the latest artifact) python <BUILDER>/trae_build_runner.py --project <SDK path> flash --chip B80 --command wf --dry-run python <BUILDER>/trae_build_runner.py --project <SDK path> flash --chip B80 --command wf # Read flash to file / reset / erase then write python <BUILDER>/trae_build_runner.py --project <SDK path> flash --chip B80 --command rf --output dump.bin --size 12k python <BUILDER>/trae_build_runner.py --project <SDK path> flash --chip B80 --command rst python <BUILDER>/trae_build_runner.py --project <SDK path> flash --chip B80 --command wf --erase --size 512k ``` ## Complete Closed Loop: Compile → Burn → Serial Port In Trae conversation, say a sentence to string together the entire embedded development process: ``` > /build b80_dongle_flash # 1. Compile bin > Burn to B80 # 2. agent calls flash_run(wf), automatically takes the latest bin, burns and resets automatically > Capture 5 seconds of serial port output to see if there is boot ok # 3. agent calls serial_capture, reads UART log to judge ``` ## Dependencies - **Python 3.8+** - **Build Function**: Zero third-party dependencies (pure stdlib) - **Serial Port Capture**: Optional dependency `pyserial` (`pip install pyserial`), if not installed, `serial_list/serial_capture` will give friendly prompts - **Eclipse Headless Compilation**: Requires Telink IoT Studio / Eclipse CDT corresponding to the platform ## Register to Trae CLI Add to `~/.trae/trae_cli.yaml` (user-level, effective for all projects): ```yaml mcp_servers: - name: trae_builder type: stdio command: python args: - "<BUILDER>/trae_build_mcp.py" timeout: 30s ``` Or place `.mcp.json` in the project root: ```json { "mcpServers": { "trae_builder": { "type": "stdio", "command": "python", "args": ["D:\\work\\workspace\\trae_builder\\trae_build_mcp.py"], "timeout": 30 } } } ``` After registration, use `trae-cli doctor` to check the connection status; in interactive mode, use `/mcp` to view details and tool lists. > **About MCP Tool Visibility**: stdio MCP server is loaded asynchronously, and `mcp_servers` may be empty in the `init` event of session startup (at this point, handshake has not been completed), but usually, handshake is completed within 1 second, and tools can be called by the agent. If the first round of prompt calls MCP tools fails occasionally, retry or wait for a moment (see trae-cli documentation "Fail to call MCP tool for the first round / Automatically recovered for the second round"). This toolchain has been tested on `tc_ble_lite_sdk-1.2.2_allinone` to ensure `build_info` and `build_run` return normally. ## Direct Compilation in Trae: `/build` Custom Command In addition to MCP, it also provides `/build` custom prompt command (using Bash tool to call runner, not dependent on MCP), as a more intuitive entry. The command file is placed in `~/.trae/commands/build.md` (user-level, effective for all projects). Open Trae in any repository root directory containing `builder.json`, input: ``` /build info # View the build configuration (parameters/presets/artifacts) /build list # List collected build artifacts /build rx_default # Compile with preset rx_default (actual execution) /build rx_default --dry-run # Preview, only print command without compilation /build build --preset rx_default --param Target=tx # Explicit build subcommand + override parameters ``` `/build` will automatically use `${workspaceFolder}` to locate the current repository, call `trae_build_runner.py`, and report the result after sorting. > Note for Windows terminal: In `cmd.exe`, using `trae-cli -p "/build ..."` with spaces in parameters may be truncated; it is recommended to directly input `/build ...` in VSCode integrated terminal (PowerShell), or use `trae-cli -p` with the whole command in quotes and run in PowerShell. ## Let Old Repositories Access: `/build-init` Automatically Generate builder.json If an old repository does not have `builder.json`, use `/build-init` to scan and generate: ``` /build-init # Scan current repository, automatically generate builder.json /build-init --ide C:\TelinkIoTStudio # Specify IDE path to override default value ``` `/build-init` calls `trae_build_init.py`, automatically identifying common build patterns: | Pattern | Identification Method | Generated Content | |------|---------|---------| | **Telik A Type**(release_sdk_tool) | Find `tools/release_sdk_tool/compile.bat` | IDE path, chip list (B80/B80B/tc122x, etc.), one preset per chip | | **Telik B Type**(telink_ble post-processing) | Find `rom_lib.bat`/`flash_on_rom_lib.bat` + `.cproject` | Extract build configuration name and chip from `.cproject` | | **Telik C Type**(pure Eclipse project) | Has `.cproject` but no above scripts | Extract real project name from `.project`, all configurations from `.cproject`, one preset per project×configuration, using cross-platform `eclipse_headless_build.py` | | **Makefile** | Find `Makefile`/`makefile` | Parse target list, one preset per target | | **General Script** | Find root directory `build.ps1`/`build.bat`/`build.sh` | Basic configuration | | **Fallback Template** | Above all not hit | Prompt user to manually fill `build.script.path` | ## Cross-Platform Support (Windows / Linux / macOS) - **Runner / MCP Server / Generator**: Pure Python stdlib, universal across three platforms. - **C Type Build Script**: `scripts/eclipse_headless_build.py` (pure Python) universal across three platforms; on Windows, find `TelinkIoTStudio.exe`/`eclipse.exe`, on Linux/macOS, find `eclipse`/`TelinkIoTStudio`. - **A/B Type**: On Windows, use the `.bat` provided by the repository (preserving Telink multi-stage orchestration); on Linux/macOS, the generator automatically switches the build script to cross-platform `eclipse_headless_build.py`, and removes the `.exe` from the IDE launcher. - **Runner Automatic Interpreter Selection**: `.py`→python/python3, `.sh`→bash, `.ps1`→powershell/pwsh, `.bat`→cmd.exe. - **Dependencies**: Only Python 3.8+ required; Eclipse headless compilation also requires Telink IoT Studio / Eclipse CDT corresponding to the platform. The command file is in `~/.trae/commands/build-init.md`. You can also use the command line directly: ```powershell python <BUILDER>/trae_build_init.py <repository path> --dry-run # Preview without writing python <BUILDER>/trae_build_init.py <repository path> # Write builder.json python <BUILDER>/trae_build_init.py <repository path> --ide C:\TelinkIoTStudio ``` After generation, you can view `/build info`, compile `/build <preset name>`. If it is a fallback template, edit `builder.json` to complete `build.script.path` as prompted. ## Manually Writing `builder.json` You can also manually write `builder.json` by referring to `trae_builder_schema.json` or an existing `tc_ble_lite_sdk-1.2.2_allinone/robin_builder.json`. A minimal example: ```json { "schema_version": "1.0", "sdk": { "name": "my-sdk", "type": "make" }, "build": { "script": { "path": "build.ps1", "interpreter": "powershell.exe" }, "parameters": [ { "name": "Target", "type": "enum", "enum": ["debug","release"], "default": "release" } ], "presets": [ { "name": "dbg", "params": { "Target": "debug" } } ], "artifacts": { "scan_dirs": ["build"], "name_pattern": "*.bin", "max_age_hours": 168 }, "timeout_seconds": 600 } } ``` ## For Non-Trae Tools (Claude Desktop / Cursor / Cline / Command Line) The MCP server in this repository (`trae_build_mcp.py`) is a **standard MCP stdio protocol**, independent of Trae. Any MCP-supported client can connect and obtain the same `build_info` / `build_presets` / `build_run` / `build_list` tools. First, clone the repository (or download it) and note the path (denoted as `<BUILDER>` below). ### Claude Desktop Edit the configuration file: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "trae_builder": { "command": "python", "args": ["<BUILDER>/trae_build_mcp.py"] } } } ``` Restart Claude Desktop, and the dialog will display `build_info` and other tools. ### Cursor Create `.cursor/mcp.json` in the project root: ```json { "mcpServers": { "trae_builder": { "command": "python", "args": ["<BUILDER>/trae_build_mcp.py"] } } } ``` ### VSCode (Cline / Continue and other MCP extensions) Using Cline as an example, add to its MCP settings (usually `~/.cline/mcp_settings.json` or extension settings): ```json { "mcpServers": { "trae_builder": { "command": "python", "args": ["<BUILDER>/trae_build_mcp.py"] } } } ``` ### Any MCP Client (General) Start the stdio command: `python <BUILDER>/trae_build_mcp.py`, without parameters. The server automatically discovers the `builder.json` in the current workspace. > Note: Non-Trae clients do not have `/build` and `/build-init` commands and build skills (which are Trae-specific formats), but MCP tools are fully available. To generate `builder.json` for an SDK repository for the first time, use the command-line method below. ### Pure Command Line (No AI Client Dependency) ```bash # Generate builder.json (scan repository, auto-detect build mode) python <BUILDER>/trae_build_init.py /path/to/sdk-repo # View configuration python <BUILDER>/trae_build_runner.py --project /path/to/sdk-repo info # Build with preset python <BUILDER>/trae_build_runner.py --project /path/to/sdk-repo build --preset rx_default # List artifacts python <BUILDER>/trae_build_runner.py --project /path/to/sdk-repo list ``` ## Self-Testing ```powershell # Directly feed JSON-RPC to test MCP server (no Trae dependency) python <BUILDER>/trae_build_mcp.py < <BUILDER>/scripts/_mcp_probe_in.json ``` Verified: `initialize` / `tools/list` / `build_info` / `build_presets` / `build_run` (dry-run) / `build_list` / `shutdown` all return normally. ## Contributing and Promotion Feel free to submit issues or PRs. If you find this useful, give it a ⭐ to help more people discover it. **Suggested Topics in GitHub Repository Settings** (improve discoverability): `mcp` `mcp-server` `trae-plugin` `embedded` `firmware` `eclipse-cdt` `telink` `sdk-builder` `cross-platform` `ai-coding` **Share with communities**: - Trae / Claude / MCP communities (Discord, GitHub Discussions) - Embedded development forums (explaining: let AI directly compile Telink/embedded SDK firmware) - Technical blogs like掘金/知乎 (with demo screenshots or recording effects)