FirmForge

English · 中文（README_CN.md）

FirmForge is an MCP-based firmware verification toolchain for MCU development with AI coding agents. It provides a five-stage hardware pipeline — Detect, Review, Build, Flash, Verify — and exposes the stages to agents as MCP tools (ff_detect, ff_context, ff_build, ff_run, ff_flash, ff_monitor).

The toolchain compiles firmware with a real compiler (avr-gcc for AVR, arm-none-eabi-gcc + CMSIS for STM32), programs the target with avrdude (AVR) or OpenOCD over SWD (STM32), and verifies the result via serial readback. Code generation is out of scope.

Pipeline

FirmForge reports what came back and whether your assertion matched. It does not judge whether the output means the feature works — that belongs to the caller (agent or human), so pass --expected to make S5 verifiable.

Related MCP server: agentic-hil

Supported Targets

Custom boards are supported via --boards-dir.

Installation

Requirements: Python ≥ 3.10. Hardware is required only for the Flash and Verify stages.

pip install git+https://github.com/NotchStone/firmforge.git
ff setup

ff setup downloads and installs avr-gcc, avrdude, cppcheck, and ArduinoCore-avr to ~/.firmforge/. Re-running is idempotent.

For MCP support (agent integration):

pip install "firmforge[mcp] @ git+https://github.com/NotchStone/firmforge.git"

Stable wheels are attached to GitHub Releases.

A China mirror is available on Gitee: see README_CN.md (中文).

Usage

# Detect connected board
ff detect

# Review + compile only (no hardware required)
ff build arduino_mega --app path/to/source

# Full pipeline on hardware
ff run arduino_mega --app path/to/source --expected "Hello World"

# Flash a pre-built hex
ff flash arduino_mega --firmware firmware.hex

MCP Server

Register the server with your agent (CodeBuddy, Cursor, Claude Desktop, ...):

{
  "mcpServers": {
    "firmforge": {
      "command": "python",
      "args": ["-m", "firmforge.adapters.mcp_server"],
      "cwd": "/path/to/your/firmware/project"
    }
  }
}

Agent workflow: query ff_context for register/pin references before writing firmware, then ff_run to compile, flash, and verify. Bundled data (board definitions, chip knowledge, toolchain manifests) is resolved from inside the package; the server runs from any working directory.

Development

pip install -e .[test,mcp]
pytest

License

MIT © FirmForge Contributors