Skip to main content
Glama

# BYO Firmware MCP

BYO Firmware MCP is a local, stdio-based MCP server for guarded embedded-board setup, inspection, serial I/O, debug control, firmware deployment, and recovery through pyOCD.

Current state

The server implementation lives in src/pyocd_debug_mcp. It is distributable without bundled board profiles, firmware, packs, generated reports, or hardware state. Board-specific state is created in the firmware project's .firm/ directory, never in this server checkout.

The server is intentionally headless and client-neutral. It exposes its current tool surface through the MCP protocol; a visible tool is not, by itself, authorization for a guarded operation.

Related MCP server: dbgprobe-mcp-server

Run

Install the locked environment:

uv sync --locked

Start the stdio server:

uv run --locked pyocd-debug-mcp

Register this command with an MCP-compatible client, preferably from the firmware project's directory:

uv run --project <absolute-path-to-BYO-Firmware-MCP> --locked pyocd-debug-mcp

If the client does not start the server from the firmware project, set BYO_MCP_ARTIFACT_ROOT to that project's absolute path. Do not point it at this repository.

To isolate passive monitor records for one launch, set BYO_MCP_MONITOR_ROOT to an absolute directory before starting the server:

BYO_MCP_MONITOR_ROOT=/absolute/path/to/byo-monitor uv run --locked pyocd-debug-mcp

A nonblank monitor root is exclusive: server_data/ and simulated_remote/ are created beneath it, never beneath per-user app data or the artifact root. If that directory cannot be resolved or written, monitoring buffers in memory; server startup and hardware behavior continue normally.

Server documentation

Firmware MCP capabilities

Tiered capability routing

Each named logical board has an explicit project-local safety tier. A newly named board is no-setup: use connect (optionally with its explicit probe_uid or target) and the *_raw tools when the operator deliberately owns unbounded-address risk. setup-lite adds confirmed coarse map containment and retains raw escape hatches; every lite raw response instructs the agent to display that bypass warning to the human. setup-full preserves the existing validated/guarded workflow and refuses new raw routes.

Use get_capabilities(board_id) or get_setup_status(board_id) before acting; both report the per-board tier, policy status and authoritative project root. An incomplete initial setup (or a post-downgrade no-setup policy) remains raw. An interrupted escalation from lite or full retains its prior active tier and records the incomplete attempt separately. A corrupt committed policy is never treated as raw and must be repaired before hardware access.

$downgrade and $mass-erase are manual-only workspace skills. The server uses their project-local grants under .agent-workspace/runtime/manual-permissions, resets those grants at every startup, and consumes each authorization once. Ask the human to invoke the named skill; do not create or edit a grant directly. Mass erase reserves that exact disclosure before plan acceptance and consumes it before the backend call; a cancelled, changed, or failed plan discards the old grant and requires a fresh skill invocation.

Raw memory, flash, and UART routes are deliberately bounded: raw serial reads, writes, exchanges, payloads, and captured output have finite operation limits. Existing planned full UART behavior is preserved. Lite safe routes require the explicitly confirmed region/config/backend facts for that operation; full safe routes additionally retain their normal live identity and plan prerequisites.

The server provides a guarded board-development surface:

  • Board readiness: discover connections, route familiar board names to validation or setup, establish board profiles, validate live hardware, and report readiness. When a machine cannot enumerate a debugger or serial port natively, an agent can author a local discovery hook under the project's .firm/discovery_hooks so the server can see it; hook output names hardware and grants no authority.

  • Debug and inspection: inspect board, CPU, execution, symbol, and bounded-memory state; control breakpoints, stepping, reset/run, and other bounded diagnostic actions.

  • Serial evidence: capture UART output and run controlled serial exchanges for declared tests or diagnosis.

  • Firmware deployment: bind the selected build output in a flash plan, verify it against the reviewed stable map at execution time, and flash the approved application. A successful flash is deployment evidence, not proof of behavior.

find_symbol, read_memory_symbol, and symbol-backed write_memory accept the current project's ELF explicitly. Pass elf_artifact after a server restart; within one uninterrupted Server Run, a successful application flash also creates a temporary convenience binding. The server never swaps in implicit checkout firmware as another project's symbol table, and symbol addresses remain subject to the board's memory-map containment policy.

  • Guarded mutation and recovery: writes, execution changes, bootloader work, and recovery require the current board gate, the exact *-plan action, and any required human permission.

  • Per-board safety: validation, plans, permissions, budgets, and results never transfer between connections. Disconnects and new server runs require validation; stable-map problems use the server's refresh path.

Always follow live MCP guidance. Visibility is not authorization: guarded actions use an all-null *-plan guidance call, the returned populated plan submission, then the paired action.

Included command-line utilities

uv run --locked pyocd-pack-repair --help
uv run --locked pyocd-native-build --help
uv run --locked pyocd-collect-artifacts --help

Portable native-build artifacts

The server does not require a particular IDE or build system. Build with the project's native tooling, then optionally normalize its explicit outputs with the small collector (pyocd-collect-artifacts, above).

Historical implementation notes, progress material, test material, and generated runtime state are kept outside the server in ../archive/BYO-Firmware-MCP-20260731/.

Available Tools

20 tools
connectA

Open a debug session to a connected probe.

Args:
    unique_id: Whole or partial probe serial/unique ID to select a specific
        probe. Omit when exactly one probe is attached. Defaults to the
        ``PYOCD_PROBE_UID`` environment variable if unset.
    target: Target type override, e.g. "stm32f407vg" or "nrf52833". Takes
        precedence over a board config. Omit to use the selected board's
        target (when ``board_id`` is given), else the ``PYOCD_TARGET``
        environment variable, else pyOCD auto-detection.
    board_id: Load facts from ``boards/<board_id>.yaml`` through the shared
        board-config loader — pyOCD target, recover policy, silicon id, baud.
        Lets a custom ST/nRF board connect by id with no hand-passed target;
        call ``get_board_info`` to see the loaded facts. Defaults to the
        ``PYOCD_BOARD_ID`` environment variable.
    board_config: Path to an extra board-config file outside the tracked
        ``boards/`` directory, for a custom board. Defaults to the
        ``PYOCD_BOARD_CONFIG`` environment variable.

Inputs: target, board_id, unique_id, board_config. Returns: result

disconnectA

Close the active debug session and release the probe.

Inputs: no named parameters. Returns: result

flash_firmwareA

Flash firmware through the shared target-control service layer.

Args:
    path: Optional explicit artifact path. When omitted, resolve the default
        flash artifact for the connected session's loaded board config.
        Returns the resolved path in the success text.
    halt_after_reset: If True, leave the target halted after flashing.
        If False, reset and let it run.

Inputs: path, halt_after_reset. Returns: result

get_board_infoA

Return the facts from the board config the session was opened with.

Reports the ``boards/<board>.yaml`` definition active for this session —
pyOCD target, MCU and probe family, recover policy, silicon-id expectation,
default UART baud, and the smoke-test read address. Returns a notice when
``connect`` was called without a ``board_id`` (raw-target mode), where these
facts were not loaded.

Inputs: no named parameters. Returns: result

get_stateA

Return the current core run state (e.g. HALTED, RUNNING, RESET).

Inputs: no named parameters. Returns: result

haltB

Halt the core.

Inputs: no named parameters. Returns: result

read_core_registerA

Read a core register by name (e.g. "pc", "sp", "r0", "xpsr").

Returns the value as a hex string.

Inputs: name (required). Returns: result

read_memoryA

Read a single value from memory.

Args:
    address: Memory address, hex (0x...) or decimal.
    word_size: Transfer size in bits: 8, 16, or 32.

Inputs: address (required), word_size. Returns: result

read_memory_blockB

Read length bytes from memory starting at address.

Returns the bytes as a space-separated hex string.

Inputs: length (required), address (required). Returns: result

read_serialA

Capture bounded UART output through the shared serial-resolution and UART services.

Defaults come from the connected board config only for baudrate and
serial-port selection heuristics. ``expected_text=None`` means no explicit
text expectation: any observed UART output counts as a match.
Set ``port`` to override serial resolution explicitly. Set ``reset_on_open``
to trigger a target reset immediately after the UART port opens so early
boot text is captured deterministically.

Inputs: port, baudrate, read_seconds, expected_text, +1 more. Returns: result

read_symbol_u32B

Resolve symbol_name in elf_path and read its 32-bit value from target memory.

Inputs: elf_path (required), symbol_name (required). Returns: result

remove_breakpointB

Remove the breakpoint at address.

Inputs: address (required). Returns: result

resetA

Reset the target.

Args:
    halt_after: If True, halt at the reset vector (reset-and-halt).
        If False, reset and let the target run.

Inputs: halt_after. Returns: result

resumeC

Resume execution of the core.

Inputs: no named parameters. Returns: result

set_breakpointC

Set a hardware/software breakpoint at address.

Inputs: address (required). Returns: result

stepB

Single-step one instruction and return the new program counter.

Inputs: no named parameters. Returns: result

unlock_recoverA

Run the shared recover/unlock path for the connected board.

This is a destructive action. When ``confirm`` is false the tool refuses
without touching hardware. Boards whose tracked config has no supported
``recover_mode`` fail deterministically instead of pretending success.

Inputs: confirm. Returns: result

write_core_registerB

Write a core register by name. value may be hex (0x...) or decimal.

Inputs: name (required), value (required). Returns: result

write_memoryA

Write a single value to memory.

Args:
    address: Memory address, hex (0x...) or decimal.
    value: Value to write, hex (0x...) or decimal.
    word_size: Transfer size in bits: 8, 16, or 32.

Inputs: value (required), address (required), word_size. Returns: result

write_serialA

Write bounded UTF-8 text to the connected board UART.

The tool uses the same board-aware serial-port resolution as ``read_serial``.
It never executes host commands and only writes bytes to the resolved UART
transport for the active connected session. Set ``port`` to override serial
resolution explicitly. Set ``append_newline`` when the target firmware
expects line-oriented UART input.

Inputs: text (required), port, baudrate, append_newline, +1 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: connect/disconnect, flash, board info, state control, memory/register access, breakpoints, serial, symbol reading, and recovery. No overlap.

    Naming Consistency4/5

    Most tools follow verb_noun pattern (e.g., flash_firmware, read_memory), with some simple verbs (connect, halt). 'unlock_recover' is slightly inconsistent, but overall patterns are clear.

    Tool Count4/5

    20 tools for a debug probe server is reasonable. It covers core debug operations without being excessive, though some tools could potentially be combined.

    Completeness4/5

    The tool set covers all essential debug operations: connect, flash, state control, memory/register R/W, breakpoints, serial I/O, symbol reading, and recovery. Minor gaps like conditional breakpoints are acceptable.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A basic MCP server implementation for testing purposes. Communicates via stdio and is designed to work with MCP-compliant clients.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Stateful MCP server for driving debug probes (J-Link) to flash, debug, and inspect embedded targets. Enables AI agents to perform flash, memory, breakpoint, and ELF/SVD-aware operations conversationally.
      41
      87 PyPI
      11
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A headless MCP server that enables AI tools (like Claude Code) to read and analyze serial logs from embedded boards (ESP32, STM32) for firmware debugging, with read-only tools for log retrieval and a built-in web viewer.
      6
      1
      -