# STM32 Model Context Protocol (MCP) Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
[![Vitest](https://img.shields.io/badge/Tested%20with-Vitest-yellow.svg)](https://vitest.dev/)

An open-source **Model Context Protocol (MCP)** server that drives the official STMicroelectronics STM32 toolchain from the command line. Designed specifically for AI coding assistants—including **Claude Code** and **Google Antigravity**—enabling autonomous, reliable, and headless embedded firmware development.

---

## Key Features

- **100% Headless Operation**: Never launches or drives a GUI. Interacts exclusively via:
  - `STM32CubeMX` script mode (`config load`, `project generate`, `exit`)
  - `stm32cubeidec.exe` Eclipse CDT headless builder
  - `STM32_Programmer_CLI.exe` for hardware flashing and verification
  - `arm-none-eabi-gcc` and `arm-none-eabi-size` for compilation and memory analysis
- **Structured Compiler Diagnostics**: Parses GCC outputs into typed error/warning/note objects with precise file, line, and column coordinates. Never floods context windows with megabytes of unparsed build logs.
- **Safety Gates**: Destructive actions (`stm32_clean` and `stm32_flash`) require explicit confirmation (`confirm: true`), preventing accidental code loss or unwanted board programming.
- **Strict User-Code Boundaries**: `stm32_patch_user_code` enforces paired, non-nested, uncorrupted `/* USER CODE BEGIN */` and `/* USER CODE END */` blocks, ensuring CubeMX regeneration never erases user logic.
- **Zero Credential Handling**: Does not handle or store ST logins or scrape downloads. If a target MCU firmware package is missing, the tool returns a clear, actionable message directing the developer to download it manually from [st.com](https://www.st.com).
- **Enforced ASCII Path Validation**: ST's legacy CLI tools fail abruptly on Windows paths containing Cyrillic, spaces, or Unicode characters. This server intercepts and rejects non-ASCII paths immediately with diagnostic guidance before invoking external tools.

---

## Supported Environments

- **Operating Systems**: Windows 10/11, macOS, Linux
- **AI Clients**:
  - Claude Code (`.claude-plugin/plugin.json`)
  - Google Antigravity (`antigravity/mcp_config.json`)
  - Any MCP-compliant client (Cursor, Zed, etc.)

---

## Tool Reference

The MCP server exposes 9 dedicated tools covering the entire embedded development lifecycle:

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `stm32_doctor` | `forceRefresh?: boolean` | Checks discovery status of CubeIDE, CubeMX, Programmer CLI, GCC, and installed HAL firmware packages. |
| `stm32_create_project` | `name`, `mcu`, `path`, `pins?`, `clock?`, `debug?` | Initializes a complete STM32 project (`.ioc`, CDT `.project` / `.cproject`, linker scripts, and startup assembly). |
| `stm32_read_project` | `projectDir` | Inspects and parses an existing `.ioc` configuration, returning structured metadata, pins, and peripherals. |
| `stm32_configure_pins` | `iocPath`, `pins` | Idempotently updates GPIO functions, peripheral pin assignments, and labels in the `.ioc` file. |
| `stm32_generate_code` | `iocPath` or `projectDir` | Executes CubeMX in headless script mode to generate HAL drivers and peripheral initialization code. |
| `stm32_patch_user_code`| `filePath`, `marker`, `content`, `mode` | Safely inserts or replaces code inside matching `/* USER CODE BEGIN <marker> */` blocks (`mode: "replace" \| "append"`). |
| `stm32_build` | `projectDir`, `configuration?` | Builds the project headlessly using CubeIDE, extracting structured diagnostics and Flash/RAM memory sizes. |
| `stm32_clean` | `projectDir`, `configuration?`, `confirm: boolean` | Cleans build artifacts (`confirm: true` required). |
| `stm32_flash` | `projectDir`, `filePath?`, `verify?`, `reset?`, `confirm: boolean` | Flashes the compiled binary to hardware via ST-LINK (`confirm: true` required). |

---

## Installation & Setup

### Prerequisites
1. **Node.js**: >= 20.0.0
2. **STM32CubeIDE**: Recommended version 1.15.0 to 1.19.0 (installed at default path `C:\ST\STM32CubeIDE_*` or `/opt/st/stm32cubeide`).
3. **STM32Cube MCU Packages**: Download desired target families (e.g. `STM32Cube_FW_F1_V1.8.6`) from [st.com](https://www.st.com) and extract into `~/STM32Cube/Repository`.

### Build from Source
```bash
git clone https://github.com/irrumi/stm32-mcp.git
cd stm32-mcp
npm install
npm run build
npm test
```

---

## AI Client Configuration

### Claude Code
Add the plugin manifest to your project or Claude Code configuration:
```json
{
  "mcpServers": {
    "stm32": {
      "command": "node",
      "args": ["<PATH_TO_PLUGIN>/dist/index.js"]
    }
  }
}
```

### Google Antigravity
Reference the included `antigravity/mcp_config.json`:
```json
{
  "mcpServers": {
    "stm32": {
      "command": "node",
      "args": ["C:/path/to/stm32-mcp/dist/index.js"]
    }
  }
}
```
Load the `skills/stm32-firmware/SKILL.md` skill into your Antigravity skills repository:
```bash
# Windows PowerShell
Copy-Item -Recurse -Path ".\skills\stm32-firmware" -Destination "$HOME\.gemini\antigravity\skills\"
```

---

## Worked Walkthrough: Blinky on STM32F103 (Blue Pill)

### 1. Verify Environment
```json
// Prompt: "Check STM32 toolchain health"
// Tool called: stm32_doctor
{}
```
*Response: Reports paths to `stm32cubeidec.exe`, `STM32CubeMX.jar`, `STM32_Programmer_CLI.exe`, `arm-none-eabi-gcc`, and confirms `STM32Cube_FW_F1` package is present.*

### 2. Create Project
```json
// Prompt: "Create a new STM32F103C8 project called blinky-f103"
// Tool called: stm32_create_project
{
  "name": "blinky-f103",
  "mcu": "STM32F103C8Tx",
  "path": "C:/projects/stm32/blinky-f103",
  "debug": "swd"
}
```

### 3. Assign Pin Configurations
```json
// Prompt: "Configure PC13 as an output for the onboard LED"
// Tool called: stm32_configure_pins
{
  "iocPath": "C:/projects/stm32/blinky-f103/blinky-f103.ioc",
  "pins": [
    { "pin": "PC13", "mode": "GPIO_Output", "label": "LED_STATUS" }
  ]
}
```

### 4. Headless Code Generation
```json
// Prompt: "Generate HAL code with CubeMX"
// Tool called: stm32_generate_code
{
  "projectDir": "C:/projects/stm32/blinky-f103"
}
```

### 5. Insert Application Code
```json
// Prompt: "Add non-blocking blink logic using HAL_GetTick() inside while loop"
// Tool called: stm32_patch_user_code
{
  "filePath": "C:/projects/stm32/blinky-f103/Core/Src/main.c",
  "marker": "WHILE",
  "mode": "replace",
  "content": "    static uint32_t last_tick = 0;\n    if (HAL_GetTick() - last_tick >= 500) {\n      last_tick = HAL_GetTick();\n      HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);\n    }"
}
```

### 6. Headless Compilation & Memory Analysis
```json
// Prompt: "Build the Debug configuration"
// Tool called: stm32_build
{
  "projectDir": "C:/projects/stm32/blinky-f103",
  "configuration": "Debug"
}
```
*Structured Output:*
```json
{
  "success": true,
  "summary": "Build finished successfully with 0 errors and 0 warnings.",
  "diagnostics": [],
  "memoryUsage": {
    "flashBytes": 3844,
    "ramBytes": 1580,
    "text": 3824,
    "data": 20,
    "bss": 1560
  }
}
```

### 7. Program Target Hardware
```json
// Prompt: "Flash the firmware to my connected Blue Pill"
// Tool called: stm32_flash
{
  "projectDir": "C:/projects/stm32/blinky-f103",
  "verify": true,
  "reset": true,
  "confirm": true
}
```

---

## Architecture & Security Considerations

- **Process Execution**: All external commands are executed using `child_process.spawn` with explicit argument arrays and `shell: false`. Shell interpolation is strictly prohibited.
- **Path Sanitization**: All incoming file and directory paths are validated against ASCII character sets before any filesystem or process operation.
- **Non-Destructive Regeneration**: Code injection checks BEGIN/END balance, marker matching, duplicate detection, and nesting protection.

---

## License

MIT © [irrumi](https://github.com/irrumi)