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 / ArduinoCore-avr), programs the target with avrdude, and verifies the result via serial readback. Code generation is out of scope.

Pipeline

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