PIO Agent

Explicitly claim the hardware queue lock for multi-step tasks. Throws if already held.

Runs build_project and returns rich structured diagnostics with error taxonomy, evidence, severity, retry-safety, and resource usage (RAM/Flash).

Builds (optionally), flashes firmware with monitor restart, then verifies runtime serial output against expected/rejected patterns and stability criteria.

Generates a compact board intelligence report and caches it in .pio-mcp-workspace/boardReport.json.

Returns the last persisted agent report from .pio-mcp-workspace/lastAgentReport.json.

Resolves one device, performs a bounded serial capture, evaluates health markers, and persists change-only automation state when automationKey is provided.

Resolves exactly one PlatformIO environment, board, and attached physical device. Returns ambiguity instead of guessing and issues a short-lived binding for write workflows.

Heuristic static pin audit for board-specific GPIO risks (ESP32 strapping/input-only/flash pins).

Agent-oriented pre-flight validation for a PlatformIO project. Reports environments, board IDs, source-file presence, config gaps, connected devices, and recommended next actions.

Compiles the project and generates the firmware binary via PlatformIO. PREFERRED over running `pio run` directly in a shell — this tool integrates with the hardware lock, the content-hash build cache (skips toolchain work when src/ is unchanged), and a structured-error parser that returns `structuredErrors` + `nextSteps` alongside the raw log. Returns immediately on a cache hit (no compilation). Set `verbose=true` only when you need the full log; otherwise the response stays compact. Use `background=true` for very long first-time builds to avoid MCP timeouts and poll with `check_task_status`.

Idempotently cancels one known background task and releases only resources proven to be owned by that task.

Acquires a bounded serial-monitor lease, captures redacted incremental output, and restores or releases resources on every exit path.

Static analysis validation.

Polls the status of an ongoing background task. Returns a JSON object where `status` indicates the success of the polling operation itself, and `targetStatus` (running, failed, completed) indicates the state of the actual background task.

Removes build artifacts and compiled files from the project.

Inspect an ESP core dump from a file or explicitly authorized device partition read, optionally analyzing it against an explicit ELF. Device reads can reset hardware and require separate device and host-command grants.

Send a classified GDB/MI or console command to this connection's session. Inspection, target mutation and privileged host commands are authorized separately. Timeout does not halt a running target.

List this connection's debugger sessions, observed target state and pending cleanup. Does not enumerate another connection's sessions or contact hardware.

Build and start a connection-owned GDB session using PlatformIO's generated initialization, an identified USB probe and a local OpenOCD or J-Link backend. Host execution and target effects require separate permissions. Probe custody remains held until owned descendant groups close.

Run the configured reset/run hook with host and target permissions, then close owned GDB/backend process groups and release probe custody. Set process_only for recovery without target commands; failed cleanup retains the session for retry.

Decode crash addresses against the selected current or retained ELF. Requires build permission for metadata; does not prove flashed-device identity.

Audit declared and installed project dependencies, with optional separately authorized build and LDF graph evidence.

Build and upload firmware, verify fresh owned serial boot output, and decode crashes when authorized. Preserves quiet-window/crash checks; reports incomplete evidence and unverified firmware identity explicitly.

Reads one approval request and expiry without exposing approve or deny mutations to the agent.

Gets detailed information about a specific board including MCU, frequency, flash, RAM, and supported frameworks.

Retrieves the address and auth token for the MCP Web Dashboard. Automatically starts the web server on demand if offline.

Reveals who currently owns the hardware queue lock.

Reports active, inactive, or stale serial monitor state with a bounded incremental cursor.

Returns the active policy profile and allowed/approval-required/denied operations.

Dumps platformio.ini JSON.

Returns a compact pre-flight snapshot of a PlatformIO project: declared environments, source files under src/, `lib_deps`, build-cache state, firmware artifact path, connected serial devices, and a `nextSteps` checklist. Call this FIRST when starting work on a project instead of issuing several read_file/list_devices/cat-log calls — it collapses that ritual into a single deterministic response. Pure I/O, no toolchain invocation; safe to call repeatedly.

Initializes a new PlatformIO project with the specified board and optional framework. Creates project structure with src/, include/, lib/, and test/ directories.

Installs a library from the PlatformIO registry either globally or to a specific project. Supports version specification.

Lists all available PlatformIO boards with optional filtering by platform, framework, or MCU. Supports 1000+ boards across 30+ platforms.

Lists all connected serial devices that can be used for firmware upload and monitoring.

Lists all installed libraries either globally or for a specific project.

Lists pending project-scoped approval requests without exposing any approval mutation.

List structured target metadata for selected or all environments. Requires build permission; does not execute the listed targets.

Returns compact project-scoped task history after reconciling stale tracked processes.

Collect bounded heap/stack telemetry from an owned session or an authorized temporary monitor. Reports sample-window trends, explicit unknown units and incomplete collection; does not prove a memory leak.

Open, read and close an owned serial monitor. Both opening and reading must be authorized before startup; unconfirmed closure retains device ownership.

Inspect ESP partition artifacts and firmware fit. Optional buildMetadata requires build permission and can execute project scripts. Optional readDevice resets/reads an explicitly selected serial device with separate permissions.

Install a library, platform or tool in a project and save dependencies through PlatformIO.

List project packages and environments. Requires build permission because PlatformIO loads platform code.

Report outdated project packages. Requires build permission because PlatformIO loads platform code.

Search PlatformIO library, platform or tool registry packages by type and page.

Remove a library, platform or tool from a project and its declared dependencies.

Update project dependencies within declared version constraints, with retained output and configuration change hashes.

Inspect serial-port presence, permissions and observed holders without opening or closing the device. Missing holder evidence does not prove availability.

Collect bounded serial current samples or PPK2 meter windows. PPK2 requires explicit mode, voltage/current limits, DUT port plus configured PIO_MCP_PPK2_ENV. An omitted meter port selects one matching PPK2 USB endpoint; ambiguous endpoints require explicit selection. Source mode requires independent power permission. operation=list/cleanup inspects or retries this connection's retained meter cleanup. An owned serial trigger retains DUT custody through meter cleanup. Explicit multi-interface selection pins the observed interface set and retains whole-device exclusion; physical acceptance is pending.