Changelog

All notable changes to this project are recorded here. The format follows Keep a Changelog and the project uses Semantic Versioning.

[Unreleased]

[0.6.2] - 2026-11-10

Changed

• Enable PostHog SDK intent context and missing-capability reporting using the release ingestion key by default, preserving token overrides, opt-outs, and a single remote sender.
• Ask agents to describe goals in context and report unsupported capabilities through get_more_tools; document agent participation and context delivery.

[0.6.1] - 2026-11-10

Added

• Report available model and reasoning-effort metadata with provenance on both analytics paths, with explicit environment fallbacks. Expose the running release as platformio_mcp_version alongside $mcp_server_version.
• Optional original prompt capture from explicit host metadata, disabled by default and bounded to 2,000 characters when users enable PLATFORMIO_MCP_CAPTURE_PROMPTS=1.
• Codex marketplace and compatibility manifest, portable MCP configuration, and documented Claude/Codex plugin installation. Plugin installs bundle PlatformIO Core through the existing extra.
• Enable the PostHog SDK's missing-capability reporting tool.

Fixed

• Wait for the GDB prompt following the initial stop before accepting commands, preventing a delayed startup prompt from making a running command appear complete on macOS.

[0.6.0] - 2026-11-10

Changed

• Add the PostHog MCP SDK when POSTHOG_PROJECT_TOKEN is set and remote analytics are allowed. The built-in recorder retains the local log and custom endpoint while the SDK handles PostHog delivery, preventing duplicate events.
• Allow PostHog SDK updates within >=7.86.6,<8.

Fixed

• Explicitly enable SDK context capture and infer intent from registered tool names when agents omit context or send an empty value. Preserve non-empty agent context and label fallback intent as inferred.
• Respect analytics opt-outs and CI before creating the SDK client. Importing the server no longer creates a PostHog client or emits a missing-token warning.
• Flush and close the SDK client during normal shutdown, ignoring cleanup failures. Remove the SDK SIGTERM handler and forced process exit.

[0.5.0] - 2026-11-10

Added

• PostHog events carry $session_id (the per-process session), $mcp_source, $lib_version, and $mcp_protocol_version, so PostHog's MCP analytics Sessions tab and per-tool session counts work.
• $mcp_initialize and $mcp_tools_list (with $mcp_listed_tool_names) go to PostHog once per process each. Tools listed and never called become visible.
• Tool-call events keep the board and platform argument values when they are PlatformIO registry ids such as esp32dev or espressif32. Paths and URLs in those arguments are dropped. All other argument values stay out.

Changed

• PostHog events go out through /batch/ in batches of up to 20 events or every 5 seconds, in place of one POST per event. Server shutdown flushes the open batch for up to 2 seconds. The local log and PLATFORMIO_MCP_ANALYTICS_URL are unchanged.

[0.4.1] - 2026-11-09

Changed

• PostHog usage events are now $mcp_tool_call with PostHog's MCP property names ($mcp_tool_name, $mcp_is_error, $mcp_error_type, $mcp_duration_ms, $mcp_client_name, ...). PostHog's MCP analytics views now break calls down by tool and client. 0.4.0 sent the same data as tool_call.

[0.4.0] - 2026-11-09

Added

• Usage analytics: one JSON line per tool call in ~/.platformio-mcp/analytics/usage.jsonl with tool, ok, error code, duration, argument names, and MCP client. Argument values, paths, ports, and serial output are never recorded. PLATFORMIO_MCP_ANALYTICS=off disables it, and PLATFORMIO_MCP_ANALYTICS_URL also POSTs each event to your own endpoint.
• Anonymous usage events to PostHog EU Cloud, keyed by a random install id with no person profile. Off under DO_NOT_TRACK=1, PLATFORMIO_MCP_ANALYTICS=local, or when CI is set. The first sending run prints a notice on stderr.
• platformio.mcp stats summarises the usage log: calls, ok rate, and p50/p95 duration per tool, top errors, and clients.

Changed

• Releases tag themselves: merging a pull request that bumps the version makes publish.yml create the vX.Y.Z tag, publish to PyPI, and create the GitHub release. A release no longer needs a separate PR or a manual tag push.

[0.3.1] - 2026-11-09

Security

• CI and release workflows now default the GITHUB_TOKEN to contents: read. Only the PyPI job (id-token: write) and the GitHub release job (contents: write) get more.

[0.3.0] - 2026-11-04

Added

• Declarative hardware test plans: pio_test_plan_validate, pio_test_plan_start, pio_test_plan_status, and pio_test_plan_cancel run a JSON plan for N iterations. Each iteration gets a verdict (pass, fail, timeout, infra_error), and evidence logs record the git and firmware identity. An example plan lives in examples/ch32h4-spi-loopback.
• Automated PyPI publishing through trusted publishing when a v* tag is pushed.
• scripts/release.py keeps every version string in sync, checks the changelog, and rolls [Unreleased] into a dated release. CI runs it on every pull request.

Fixed

• Cancelling a test-plan run before an iteration's upload no longer crashes the runner; the run now ends as cancelled instead of failed.
• pio_coredump decodes again on espressif32 6.x and later. GDB is now found in the separate tool-xtensa-esp-elf-gdb / tool-riscv32-esp-elf-gdb package, and --gdb is passed after the info_corefile subcommand as esp-coredump 1.x requires. A failed decode now returns error: "coredump_analyze_failed" and names the GDB it used (#21).

Changed

• Dependency updates: mcp 2.3.0, pyjwt 2.15.0, certifi 2026.10.18, opentelemetry-api 1.45.1, and newer actions/checkout and astral-sh/setup-uv.

[0.2.0] - 2026-09-18

Added

• 11 new tools (40 total):
  • pio_upload_ota: flash over Wi-Fi to ArduinoOTA (espota) boards with a reachability pre-check and failures mapped to the fix.
  • pio_port_diagnose: explain why a serial port cannot be used (our session, another process via lsof/fuser, permissions, board not answering).
  • pio_partition_table: validate the ESP32 partition CSV (alignment, overlaps, flash fit, OTA slots, app fit) and, with read_device, diff it against the table on the chip.
  • pio_coredump: read the core dump partition over esptool and decode it with the optional esp-coredump analyzer.
  • pio_memory_watch: heap and stack telemetry parsed from serial output with leak, fragmentation, and stack-headroom verdicts.
  • pio_power_profile: current draw from a serial meter or a Nordic PPK2 with sleep/active split, energy, and battery estimate.
  • pio_deps_check: library name collisions, unpinned specs, missing and leftover libraries, circular dependencies, and the LDF dependency graph.
  • pio_debug_start / pio_debug_cmd / pio_debug_stop / pio_debug_list: live GDB sessions over pio debug --interface=gdb with GDB/MI parsed into structured results.
• stop_open_sessions on pio_upload and pio_run_target releases our own monitor sessions before flashing; upload failures now carry port_error and port_diagnosis.
• Optional extras coredump (esp-coredump) and power (ppk2-api).
• Community files: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue forms, PR template, Dependabot config.
• Open Plugins layout (.mcp.json, plugin.json, skills/platformio/SKILL.md, rules/platformio.mdc) so the repo installs as a Claude Code or Cursor plugin and lists on cursor.directory.
• bad_regex structured error when a wait_for, until, expect, fail_on, or filter pattern is not a valid regular expression.
• Log pruning: the log directory keeps the newest 200 files (PLATFORMIO_MCP_MAX_LOGS overrides).
• server.json and the README ownership marker for the official MCP Registry.
• GitHub Actions CI on Linux, macOS, and Windows, plus an integration job that builds the native fixture with real PlatformIO.

Fixed

• Toolchain prefix derivation kept the caller's path separator, fixing pio_decode_backtrace and pio_size_report on Windows.
• Any unexpected exception inside a tool now returns ok: false with the exception text instead of a bare "Error executing tool".

Security

• Raised the mcp floor from >=1.0 to >=2.2. The old floor let scanners resolve to SDK releases affected by CVE-2025-53365, CVE-2025-53366, CVE-2025-66416, CVE-2026-52869, and CVE-2026-59950 (all fixed by mcp 1.28.1). The server already required the 2.x API, so no behaviour changes.

[0.1.0] - 2026-09-16

First release.

Added

• 29 MCP tools over the PlatformIO CLI: system info, board search, project init and inspection, build / upload / clean / targets, serial device listing, background serial monitor sessions and one-shot capture, Unity tests, static analysis, and package management.
• pio_flash_and_verify: flash, then watch the boot log until an expect regex (pass), a crash signature (fail), or a timeout; failures are decoded automatically.
• pio_decode_backtrace: resolve ESP32 Guru Meditation backtraces and Cortex-M HardFault dumps to function, file, and line with the toolchain's addr2line.
• pio_size_report: PlatformIO's RAM/Flash percentages plus GNU size/nm breakdowns of sections, biggest symbols, and per-file totals.
• Safety policy via PLATFORMIO_MCP_POLICY (full, build_only, read_only).
• install subcommand that registers the server with Claude Code, Claude Desktop, Cursor, Codex, and Windsurf, or prints the JSON snippet.
• Optional [platformio] extra so uvx "platformio.mcp[platformio]" works on machines without PlatformIO.