Skip to main content
Glama

STM32 Forge

STM32CubeMX CLI、IOC 离线编译工具、MCP Server 与开发 Skill 集合。

本仓库的 mcp/cubemx1/、mcp/mcp_server.py、docs/ 和 skills/stm32cubemx1-config/ 移植自 sanrenmu/STM32CubeMX-Config-Skill-and-MCP,按其 MIT License 再发布;版权与许可声明见 LICENSE。其余 src/stm32_forge/ 为本项目适配代码。

能力

  • 离线将目标 JSON 编译为 STM32CubeMX .ioc

  • 导入 .ioc、校验/反解配置及项目生成

  • 从本机 CubeMX 数据库查询器件、外设、引脚、板卡和时钟

  • stdio MCP 工具与 MCP resources

  • stm32cubemx1-config Skill,含命令、协议与工作流参考

  • 兼容的 stm32-forge CLI,用于 IOC JSON 导入/导出与 CubeMX 调用

上游实现固定面向 STM32CubeMX 1.x,并在 Skill/协议文档中注明已验证的版本边界。实际生成仍依赖本机 CubeMX 与对应固件包。

Related MCP server: vscode-cube-mcp

快速开始

需要 Python 3.8+。移植的核心和 MCP Server 使用 Python 标准库,无需安装 MCP SDK。

cd F:\deepseek\stm32-forge
$env:PYTHONPATH = (Join-Path (Get-Location) 'mcp')
python -m cubemx1 --help

Windows 也可以直接调用仓库根目录的启动器:

.\cubemx1.cmd --help

配置 CubeMX

创建 %USERPROFILE%\.cubemx1\machine.json,至少提供安装目录:

{
  "cubemx_home": "C:\\Users\\<user>\\AppData\\Local\\Programs\\STM32CubeMX",
  "repository": "C:\\Users\\<user>\\STM32Cube\\Repository"
}

也可使用 CUBEMX1_MACHINE 指向配置文件。离线 ioc build 与查询读取 CubeMX 安装目录数据库;原生项目生成需要 CubeMX 和对应固件包。

主要工作流

$env:PYTHONPATH = (Join-Path (Get-Location) 'mcp')
python -m cubemx1 ioc build .\target.json
python -m cubemx1 ioc generate .\project.ioc
python -m cubemx1 probe peripherals --device <device>
python -m cubemx1 probe describe --device <device> <IP>

目标 JSON 字段和 MCP 工具契约见 docs/PROTOCOL.md 与 mcp/PROTOCOL.md。更完整的示例和按需参考入口见 Skill。

MCP 注册

将下列配置加入 MCP 客户端,并把路径替换为本机仓库绝对路径:

{
  "mcpServers": {
    "cubemx1": {
      "command": "python",
      "args": ["<repo>/mcp/mcp_server.py"],
      "cwd": "<repo>"
    }
  }
}

MCP 提供 IOC build/import/check/generate、探测查询和会话状态工具;支持资源 cubemx1://protocol/target 与 cubemx1://protocol/mcp。完整清单在 mcp/mcp.json。

安装后推荐使用:

cubemx1-mcp

源码目录也可以直接运行:

python .\mcp\mcp_server.py

安装后同时提供 cubemx1(离线 IOC/查询 CLI)、stm32-forge(兼容 CLI)和 stm32-forge-mcp(原生 Forge MCP)入口。

原有 Forge 命令

安装本项目的兼容工具:

python -m pip install -e .
stm32-forge config
stm32-forge ioc-import .\project.ioc --output .\project.json
stm32-forge ioc-create --input .\target.json --output .\project.ioc

兼容工具配置自动探测常见 Windows CubeMX 安装目录;独立的 cubemx1 核心则遵循上述 CUBEMX1_MACHINE 配置格式。

Available Tools

6 tools
cubemx1_ioc_buildA

Compile a target JSON offline into a canonical .ioc that CubeMX loads directly. Does not start CubeMX and runs no command sequence. The target describes: device, pins and signals, peripheral modes and parameters, clock target frequencies or explicit RCC parameters, interrupts, DMA, middleware, RTOS scalar parameters, project name / output directory / toolchain. Unsupported or malformed fields are reported as unsupported/unknown/conflict and are never silently ignored.

Inputs: target (required), output.

cubemx1_ioc_checkA

[development/acceptance only, not a required step for release use] Hand the .ioc to CubeMX: load -> save as -> verify that every key the target requires is present with the same value, and scan the load log. Needs a CubeMX session; writes _roundtrip.ioc into save_dir. Normal project generation does not call it.

Inputs: ioc (required), save_dir.

cubemx1_ioc_generateA

Hand the compiled .ioc to native CubeMX generation of a CMake project and check the artifacts: the startup file exists and is referenced by the project, and the target's numeric parameters appear in the generated code. Successful generation does not mean the project compiles, let alone runs on the board. Needs a CubeMX session and the firmware pack of the matching family.

Inputs: ioc (required).

cubemx1_ioc_importA

Import a .ioc into an advanced target JSON (cubemx1.ioc/2): understood objects go into advanced fields, unknown keys go into extensions.ioc and are reported one by one. Does not start CubeMX.

Inputs: ioc (required), output.

cubemx1_probe_describeA

Offline queries. kind=describe: device/IP definitions (modes, parameters, types and ranges, candidate values, owning RefMode and conditions, true/false/unknown under the current target), pin candidates. kind=boards/board: official ST boards (details include the seed base configuration and native BSP definitions); with board, queries and compilation share the same board context and board-level instances (instance name = board name) are queryable. kind=peripherals: every peripheral/middleware instance the device declares (with the IP type from its modes file). kind=pins: one IP's signals and their candidate pins in both directions, and with mode the leaf mode's required signals, candidate pins, must-be-explicit signals and conflicts; without mode it gives a per-mode summary. kind=clock: the device's clock topology as a graph, the upstream of one readout (view=upstream, all MUX branches and the fractional input kept), or the original clock-definition XML / one element fragment (view=raw). The clock views keep RAW facts separate from interpretation: every attribute, every condition, document order, all candidates of an ambiguous reference. Does not start CubeMX and does not solve any frequency.

Inputs: ip, seq, kind, mode, +9 more.

cubemx1_statusA

Show the cubemx1 background process and session status. ioc_build does not need it; take a look before ioc_generate.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation4/5

    The four .ioc tools form a clear pipeline: import converts .ioc -> target JSON, build converts target JSON -> .ioc, generate runs CubeMX project generation, and check does an acceptance round-trip. The main soft spot is check vs. generate (both involve CubeMX and touching .ioc files, distinguished mainly by the '[acceptance only]' tag) and the very broad probe_describe multiplexer, but descriptions keep them separable.

    Naming Consistency3/5

    All tools share the cubemx1_ prefix, but the suffix grammar is mixed: ioc_<verb> (ioc_check, ioc_generate, ioc_import, ioc_build) alongside a bare noun (status) and verb_verb (probe_describe). It reads fine in practice but is not a single predictable pattern.

    Tool Count4/5

    Six tools is a well-scoped surface for an offline .ioc/target-JSON toolchain, with no obviously redundant entries. Slight imbalance in that probe_describe absorbs five query kinds (describe/boards/peripherals/pins/clock) while others are single-purpose.

    Completeness4/5

    The set covers the full conversion lifecycle in both directions, project generation, acceptance verification, session status, and offline discovery of devices/boards/peripherals/pins/clocks. Gaps remain: no tool for editing or patching an existing target JSON (must be hand-authored), no cleanup/removal of generated artifacts, and nothing to compile or run the generated firmware.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      MCP server for scaffolding, building, and flashing bare-metal STM32C011 firmware using the STM32CubeCLT toolchain. Exposes tools for project scaffold, build, flash, and probe listing.
      4
      -
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that wraps STM32CubeMX CLI to let AI load .ioc projects, modify pin/peripheral configurations, generate HAL code, and export pinout tables.
      5
      36 PyPI
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for debugging STM32 microcontrollers over ST-LINK using STM32CubeCLT tools (GDB, ST-LINK_gdbserver, STM32_Programmer_CLI) with session management, flashing, breakpoints, memory/register access, and expression evaluation.
      19
      1
      GPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables local stdio-based MCP integration with InoProShop/CODESYS for project structure reading, POU editing with verified writes, compilation, task configuration, and persistent session recovery.
      4
      MIT