platformio.mcp 0.1.0__tar.gz

platformio_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: platformio.mcp
+Version: 0.1.0
+Summary: MCP server that lets AI coding agents drive PlatformIO: boards, projects, build, flash, serial monitor, tests, static analysis, libraries.
+Keywords: mcp,platformio,embedded,esp32,arduino,firmware,ai-agent
+Author: Mihir Gandecha
+Author-email: Mihir Gandecha <mihirgandecha.2002@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: platformio>=6.1 ; extra == 'platformio'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/powerdragonfire/platformio.mcp
+Project-URL: Issues, https://github.com/powerdragonfire/platformio.mcp/issues
+Provides-Extra: platformio
+Description-Content-Type: text/markdown
+
+<h1 align="center">platformio.mcp</h1>
+
+<p align="center">
+  <b>Give your AI coding agent hands on real hardware.</b><br>
+  An <a href="https://modelcontextprotocol.io">MCP</a> server for <a href="https://platformio.org">PlatformIO</a>: build, flash, watch serial, run tests, decode crashes, shrink firmware.
+</p>
+
+<p align="center">
+  <a href="https://github.com/powerdragonfire/platformio.mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/powerdragonfire/platformio.mcp/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://pypi.org/project/platformio.mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/platformio.mcp?color=blue"></a>
+  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-blue">
+  <img alt="Tools" src="https://img.shields.io/badge/MCP%20tools-29-6f42c1">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+</p>
+
+<p align="center">
+  Python native · no Node · one line to install · works with Claude Code, Claude Desktop, Cursor, Codex, Windsurf, Cline
+</p>
+
+---
+
+## ⚡ 60-second install
+
+You need [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`). Then:
+
+```bash
+uvx platformio.mcp install --claude-code      # or --cursor  --claude-desktop  --codex  --windsurf
+```
+
+No PlatformIO on this machine? Add `--with-platformio` and the server brings PlatformIO Core along.
+
+<details>
+<summary><b>Any other MCP client</b> (Cline, Zed, Continue, ...)</summary>
+
+```bash
+uvx platformio.mcp install --print
+```
+
+```json
+{ "mcpServers": { "platformio": { "command": "uvx", "args": ["platformio.mcp"] } } }
+```
+
+Use `"args": ["platformio.mcp[platformio]"]` to bundle PlatformIO Core.
+</details>
+
+<details>
+<summary><b>Already have PlatformIO?</b></summary>
+
+The server finds `platformio` / `pio` on your PATH or in `~/.platformio/penv`. Override with `PLATFORMIO_MCP_PIO=/path/to/pio`. Run `uvx platformio.mcp doctor` to see what the agent will see.
+</details>
+
+## 🎬 What it looks like
+
+> **You:** flash the `view` env and make sure it boots.
+>
+> **Agent** → `pio_flash_and_verify(env="view", expect="setup done")`
+>
+> ```
+> FAIL: firmware flashed but the boot log matched the failure pattern:
+> 'Guru Meditation Error: Core 1 panic'ed (LoadProhibited)'.
+> Cause: LoadProhibited. 3/3 addresses resolved:
+>   DisplayTask::run() (display_task.cpp:22) <- DisplayTask::run() (display_task.cpp:23) <- vPortTaskWrapper (port.c:143)
+> ```
+>
+> **Agent:** null pointer on line 22 of `display_task.cpp`, `tft_` is used before `begin()`. Fixing, rebuilding, flashing again.
+>
+> ```
+> PASS: flashed env view in 14.2s and saw 'setup done' on /dev/cu.usbserial-0001 after 2.1s of boot output.
+> ```
+
+No 40 KB build logs in the context window. No human reading the serial monitor. The agent gets a verdict, a file and a line.
+
+## 🔁 The loop the agent runs
+
+```mermaid
+flowchart LR
+    A[pio_project_envs] --> B[edit code]
+    B --> C[pio_build]
+    C -- errors with file:line --> B
+    C -- ok --> D[pio_flash_and_verify]
+    D -- PASS --> E([done])
+    D -- FAIL: decoded backtrace --> B
+    D -- TIMEOUT --> F[pio_monitor_capture]
+    F --> B
+```
+
+## 🧰 The 29 tools
+
+<table>
+<tr><th>Group</th><th>Tools</th><th>What the agent gets back</th></tr>
+<tr>
+<td>🔍 <b>Discover</b></td>
+<td><code>pio_system_info</code> · <code>pio_list_boards</code> · <code>pio_board_info</code> · <code>pio_list_devices</code></td>
+<td>PlatformIO version and policy; ~1,700 boards with MCU, clock, RAM and flash sizes; serial ports with the likely dev boards flagged</td>
+</tr>
+<tr>
+<td>📁 <b>Project</b></td>
+<td><code>pio_project_init</code> · <code>pio_project_envs</code> · <code>pio_project_metadata</code></td>
+<td>A real <code>pio project init</code> (never a hand-written ini); every env with board, framework, monitor and upload settings; defines and include paths</td>
+</tr>
+<tr>
+<td>🔨 <b>Build &amp; flash</b></td>
+<td><code>pio_build</code> · <code>pio_upload</code> · <code>pio_clean</code> · <code>pio_list_targets</code> · <code>pio_run_target</code></td>
+<td>Status, parsed errors and warnings (file, line, column), RAM/Flash %, last 40 lines, full log path. Extra targets like <code>buildfs</code>, <code>erase</code></td>
+</tr>
+<tr>
+<td>📟 <b>Serial</b></td>
+<td><code>pio_monitor_start</code> / <code>read</code> / <code>write</code> / <code>stop</code> / <code>list</code> · <code>pio_monitor_capture</code></td>
+<td>Background sessions with a ring buffer, cursor reads, and <code>wait_for</code> regex; or a one-shot capture with nothing to manage</td>
+</tr>
+<tr>
+<td>✅ <b>Verify</b></td>
+<td><code>pio_test</code> · <code>pio_check</code></td>
+<td>Unity tests with per-case pass/fail and messages; cppcheck / clang-tidy defects by severity with CWE ids</td>
+</tr>
+<tr>
+<td>📦 <b>Packages</b></td>
+<td><code>pio_pkg_search</code> / <code>install</code> / <code>uninstall</code> / <code>list</code> / <code>outdated</code> / <code>update</code></td>
+<td>Registry search and dependency changes that keep <code>platformio.ini</code> in sync</td>
+</tr>
+<tr>
+<td>🧠 <b>Analyse</b></td>
+<td><code>pio_flash_and_verify</code> · <code>pio_decode_backtrace</code> · <code>pio_size_report</code></td>
+<td>Hardware-in-the-loop pass/fail; crash dumps resolved to file:line; where every byte of flash and RAM goes</td>
+</tr>
+</table>
+
+Every tool returns `ok`, a one-paragraph `summary` written for the model, structured fields, and a `log_path` to the full output. Long output stays on disk under `~/.platformio-mcp/logs` (newest 200 files kept).
+
+### The three tools that go beyond the CLI
+
+| | What it does | Under the hood |
+|---|---|---|
+| 🚀 **`pio_flash_and_verify`** | Flash, open the port, read until `expect` matches (**pass**), a crash signature matches (**fail**, auto-decoded), or the timeout passes (**timeout**) | `pio run -t upload` + pyserial; `fail_on` defaults to Guru Meditation, HardFault, `abort()`, `assert failed`, watchdog, brownout, heap corruption |
+| 🩺 **`pio_decode_backtrace`** | Turn an ESP32 `Backtrace: 0x400d...` dump or a Cortex-M `pc`/`lr` dump into function, file, line, inlined frames, cause, reset reason | Toolchain located from `pio project metadata`, then `<target>-addr2line -pfiaC` on `firmware.elf`; fixes Xtensa `A0` window bits |
+| 📊 **`pio_size_report`** | Why is the firmware this big? Flash/RAM %, loaded sections, biggest symbols with `file:line`, per-file totals, regex `filter` | `pio run -t checkprogsize` (partition-aware) + GNU `size -A` + `nm -S -C -l --size-sort` |
+
+## 🔒 Safety policy
+
+Set `PLATFORMIO_MCP_POLICY` in the server's `env`, or pass `--policy` to `install`:
+
+| Policy | Can build | Can flash / erase / write serial | Use it for |
+|---|:-:|:-:|---|
+| `full` (default) | ✅ | ✅ | Your own bench |
+| `build_only` | ✅ | ❌ | Shared labs, CI, "look but don't touch" |
+| `read_only` | ❌ | ❌ | Code review, onboarding, untrusted prompts |
+
+MCP clients also prompt before each tool call. Policies are the second layer, not the only one.
+
+## ⚙️ Settings
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `PLATFORMIO_MCP_POLICY` | `full`, `build_only`, `read_only` | `full` |
+| `PLATFORMIO_MCP_PROJECT_DIR` | Project used when a tool is called without `project_dir` | server's cwd |
+| `PLATFORMIO_MCP_PIO` | Explicit path to the `pio` executable | auto-detect |
+| `PLATFORMIO_MCP_LOG_DIR` | Where full command logs go | `~/.platformio-mcp/logs` |
+| `PLATFORMIO_MCP_MAX_LOGS` | How many log files to keep | `200` |
+
+## 📝 Serial monitor notes
+
+Sessions talk to the port with pyserial directly, because PlatformIO's own monitor needs an interactive terminal. PlatformIO monitor filters such as `esp32_exception_decoder` therefore do not apply; `pio_decode_backtrace` does that job. Baud and port default from `monitor_speed` / `monitor_port` in `platformio.ini` when `project_dir` is passed, otherwise the single detected dev board at 115200. Opening the port resets most dev boards, which is why `pio_flash_and_verify` sees the boot log from the top.
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/powerdragonfire/platformio.mcp && cd platformio.mcp
+uv sync
+uv run pytest                    # unit tests, no hardware or network
+uv run pytest -m integration     # builds the bundled native fixture with your PlatformIO
+uv run platformio-mcp doctor     # what the agent's pio_system_info sees
+npx @modelcontextprotocol/inspector uv run platformio-mcp   # poke tools interactively
+```
+
+To use your checkout in Claude Code instead of the PyPI release:
+
+```bash
+claude mcp add platformio -- uv run --directory /path/to/platformio.mcp platformio-mcp
+```
+
+Changes are tracked in [CHANGELOG.md](CHANGELOG.md).
+
+## 🤝 Prior art
+
+[jl-codes/platformio-mcp](https://github.com/jl-codes/platformio-mcp) is a TypeScript server with the same goal, a web dashboard, and a GPIO pin audit. This project exists for people who want a Python-only install through `uvx`, one that can bundle PlatformIO itself, and crash decoding and size budgeting built in.
+
+## License
+
+MIT
+
+<!-- mcp-name: io.github.powerdragonfire/platformio.mcp -->

platformio_mcp-0.1.0/README.md

@@ -0,0 +1,191 @@
+<h1 align="center">platformio.mcp</h1>
+
+<p align="center">
+  <b>Give your AI coding agent hands on real hardware.</b><br>
+  An <a href="https://modelcontextprotocol.io">MCP</a> server for <a href="https://platformio.org">PlatformIO</a>: build, flash, watch serial, run tests, decode crashes, shrink firmware.
+</p>
+
+<p align="center">
+  <a href="https://github.com/powerdragonfire/platformio.mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/powerdragonfire/platformio.mcp/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://pypi.org/project/platformio.mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/platformio.mcp?color=blue"></a>
+  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-blue">
+  <img alt="Tools" src="https://img.shields.io/badge/MCP%20tools-29-6f42c1">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+</p>
+
+<p align="center">
+  Python native · no Node · one line to install · works with Claude Code, Claude Desktop, Cursor, Codex, Windsurf, Cline
+</p>
+
+---
+
+## ⚡ 60-second install
+
+You need [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`). Then:
+
+```bash
+uvx platformio.mcp install --claude-code      # or --cursor  --claude-desktop  --codex  --windsurf
+```
+
+No PlatformIO on this machine? Add `--with-platformio` and the server brings PlatformIO Core along.
+
+<details>
+<summary><b>Any other MCP client</b> (Cline, Zed, Continue, ...)</summary>
+
+```bash
+uvx platformio.mcp install --print
+```
+
+```json
+{ "mcpServers": { "platformio": { "command": "uvx", "args": ["platformio.mcp"] } } }
+```
+
+Use `"args": ["platformio.mcp[platformio]"]` to bundle PlatformIO Core.
+</details>
+
+<details>
+<summary><b>Already have PlatformIO?</b></summary>
+
+The server finds `platformio` / `pio` on your PATH or in `~/.platformio/penv`. Override with `PLATFORMIO_MCP_PIO=/path/to/pio`. Run `uvx platformio.mcp doctor` to see what the agent will see.
+</details>
+
+## 🎬 What it looks like
+
+> **You:** flash the `view` env and make sure it boots.
+>
+> **Agent** → `pio_flash_and_verify(env="view", expect="setup done")`
+>
+> ```
+> FAIL: firmware flashed but the boot log matched the failure pattern:
+> 'Guru Meditation Error: Core 1 panic'ed (LoadProhibited)'.
+> Cause: LoadProhibited. 3/3 addresses resolved:
+>   DisplayTask::run() (display_task.cpp:22) <- DisplayTask::run() (display_task.cpp:23) <- vPortTaskWrapper (port.c:143)
+> ```
+>
+> **Agent:** null pointer on line 22 of `display_task.cpp`, `tft_` is used before `begin()`. Fixing, rebuilding, flashing again.
+>
+> ```
+> PASS: flashed env view in 14.2s and saw 'setup done' on /dev/cu.usbserial-0001 after 2.1s of boot output.
+> ```
+
+No 40 KB build logs in the context window. No human reading the serial monitor. The agent gets a verdict, a file and a line.
+
+## 🔁 The loop the agent runs
+
+```mermaid
+flowchart LR
+    A[pio_project_envs] --> B[edit code]
+    B --> C[pio_build]
+    C -- errors with file:line --> B
+    C -- ok --> D[pio_flash_and_verify]
+    D -- PASS --> E([done])
+    D -- FAIL: decoded backtrace --> B
+    D -- TIMEOUT --> F[pio_monitor_capture]
+    F --> B
+```
+
+## 🧰 The 29 tools
+
+<table>
+<tr><th>Group</th><th>Tools</th><th>What the agent gets back</th></tr>
+<tr>
+<td>🔍 <b>Discover</b></td>
+<td><code>pio_system_info</code> · <code>pio_list_boards</code> · <code>pio_board_info</code> · <code>pio_list_devices</code></td>
+<td>PlatformIO version and policy; ~1,700 boards with MCU, clock, RAM and flash sizes; serial ports with the likely dev boards flagged</td>
+</tr>
+<tr>
+<td>📁 <b>Project</b></td>
+<td><code>pio_project_init</code> · <code>pio_project_envs</code> · <code>pio_project_metadata</code></td>
+<td>A real <code>pio project init</code> (never a hand-written ini); every env with board, framework, monitor and upload settings; defines and include paths</td>
+</tr>
+<tr>
+<td>🔨 <b>Build &amp; flash</b></td>
+<td><code>pio_build</code> · <code>pio_upload</code> · <code>pio_clean</code> · <code>pio_list_targets</code> · <code>pio_run_target</code></td>
+<td>Status, parsed errors and warnings (file, line, column), RAM/Flash %, last 40 lines, full log path. Extra targets like <code>buildfs</code>, <code>erase</code></td>
+</tr>
+<tr>
+<td>📟 <b>Serial</b></td>
+<td><code>pio_monitor_start</code> / <code>read</code> / <code>write</code> / <code>stop</code> / <code>list</code> · <code>pio_monitor_capture</code></td>
+<td>Background sessions with a ring buffer, cursor reads, and <code>wait_for</code> regex; or a one-shot capture with nothing to manage</td>
+</tr>
+<tr>
+<td>✅ <b>Verify</b></td>
+<td><code>pio_test</code> · <code>pio_check</code></td>
+<td>Unity tests with per-case pass/fail and messages; cppcheck / clang-tidy defects by severity with CWE ids</td>
+</tr>
+<tr>
+<td>📦 <b>Packages</b></td>
+<td><code>pio_pkg_search</code> / <code>install</code> / <code>uninstall</code> / <code>list</code> / <code>outdated</code> / <code>update</code></td>
+<td>Registry search and dependency changes that keep <code>platformio.ini</code> in sync</td>
+</tr>
+<tr>
+<td>🧠 <b>Analyse</b></td>
+<td><code>pio_flash_and_verify</code> · <code>pio_decode_backtrace</code> · <code>pio_size_report</code></td>
+<td>Hardware-in-the-loop pass/fail; crash dumps resolved to file:line; where every byte of flash and RAM goes</td>
+</tr>
+</table>
+
+Every tool returns `ok`, a one-paragraph `summary` written for the model, structured fields, and a `log_path` to the full output. Long output stays on disk under `~/.platformio-mcp/logs` (newest 200 files kept).
+
+### The three tools that go beyond the CLI
+
+| | What it does | Under the hood |
+|---|---|---|
+| 🚀 **`pio_flash_and_verify`** | Flash, open the port, read until `expect` matches (**pass**), a crash signature matches (**fail**, auto-decoded), or the timeout passes (**timeout**) | `pio run -t upload` + pyserial; `fail_on` defaults to Guru Meditation, HardFault, `abort()`, `assert failed`, watchdog, brownout, heap corruption |
+| 🩺 **`pio_decode_backtrace`** | Turn an ESP32 `Backtrace: 0x400d...` dump or a Cortex-M `pc`/`lr` dump into function, file, line, inlined frames, cause, reset reason | Toolchain located from `pio project metadata`, then `<target>-addr2line -pfiaC` on `firmware.elf`; fixes Xtensa `A0` window bits |
+| 📊 **`pio_size_report`** | Why is the firmware this big? Flash/RAM %, loaded sections, biggest symbols with `file:line`, per-file totals, regex `filter` | `pio run -t checkprogsize` (partition-aware) + GNU `size -A` + `nm -S -C -l --size-sort` |
+
+## 🔒 Safety policy
+
+Set `PLATFORMIO_MCP_POLICY` in the server's `env`, or pass `--policy` to `install`:
+
+| Policy | Can build | Can flash / erase / write serial | Use it for |
+|---|:-:|:-:|---|
+| `full` (default) | ✅ | ✅ | Your own bench |
+| `build_only` | ✅ | ❌ | Shared labs, CI, "look but don't touch" |
+| `read_only` | ❌ | ❌ | Code review, onboarding, untrusted prompts |
+
+MCP clients also prompt before each tool call. Policies are the second layer, not the only one.
+
+## ⚙️ Settings
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `PLATFORMIO_MCP_POLICY` | `full`, `build_only`, `read_only` | `full` |
+| `PLATFORMIO_MCP_PROJECT_DIR` | Project used when a tool is called without `project_dir` | server's cwd |
+| `PLATFORMIO_MCP_PIO` | Explicit path to the `pio` executable | auto-detect |
+| `PLATFORMIO_MCP_LOG_DIR` | Where full command logs go | `~/.platformio-mcp/logs` |
+| `PLATFORMIO_MCP_MAX_LOGS` | How many log files to keep | `200` |
+
+## 📝 Serial monitor notes
+
+Sessions talk to the port with pyserial directly, because PlatformIO's own monitor needs an interactive terminal. PlatformIO monitor filters such as `esp32_exception_decoder` therefore do not apply; `pio_decode_backtrace` does that job. Baud and port default from `monitor_speed` / `monitor_port` in `platformio.ini` when `project_dir` is passed, otherwise the single detected dev board at 115200. Opening the port resets most dev boards, which is why `pio_flash_and_verify` sees the boot log from the top.
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/powerdragonfire/platformio.mcp && cd platformio.mcp
+uv sync
+uv run pytest                    # unit tests, no hardware or network
+uv run pytest -m integration     # builds the bundled native fixture with your PlatformIO
+uv run platformio-mcp doctor     # what the agent's pio_system_info sees
+npx @modelcontextprotocol/inspector uv run platformio-mcp   # poke tools interactively
+```
+
+To use your checkout in Claude Code instead of the PyPI release:
+
+```bash
+claude mcp add platformio -- uv run --directory /path/to/platformio.mcp platformio-mcp
+```
+
+Changes are tracked in [CHANGELOG.md](CHANGELOG.md).
+
+## 🤝 Prior art
+
+[jl-codes/platformio-mcp](https://github.com/jl-codes/platformio-mcp) is a TypeScript server with the same goal, a web dashboard, and a GPIO pin audit. This project exists for people who want a Python-only install through `uvx`, one that can bundle PlatformIO itself, and crash decoding and size budgeting built in.
+
+## License
+
+MIT
+
+<!-- mcp-name: io.github.powerdragonfire/platformio.mcp -->

platformio_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "platformio.mcp"
+version = "0.1.0"
+description = "MCP server that lets AI coding agents drive PlatformIO: boards, projects, build, flash, serial monitor, tests, static analysis, libraries."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mihir Gandecha", email = "mihirgandecha.2002@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = ["mcp", "platformio", "embedded", "esp32", "arduino", "firmware", "ai-agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Embedded Systems",
+]
+dependencies = [
+    "mcp>=1.0",
+    "pyserial>=3.5",
+]
+
+[project.optional-dependencies]
+# `uvx "platformio.mcp[platformio]"` brings PlatformIO Core along for machines that have never installed it.
+platformio = ["platformio>=6.1"]
+
+[project.urls]
+Homepage = "https://github.com/powerdragonfire/platformio.mcp"
+Issues = "https://github.com/powerdragonfire/platformio.mcp/issues"
+
+[project.scripts]
+platformio-mcp = "platformio_mcp.cli:main"
+"platformio.mcp" = "platformio_mcp.cli:main"
+
+[tool.uv.build-backend]
+module-name = "platformio_mcp"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["integration: needs a working `pio` on PATH and network access"]
+addopts = "-m 'not integration'"

platformio_mcp-0.1.0/src/platformio_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""PlatformIO MCP server: gives AI coding agents hands on real embedded hardware."""
+
+__version__ = "0.1.0"

platformio_mcp-0.1.0/src/platformio_mcp/cli.py

@@ -0,0 +1,132 @@
+"""`platformio.mcp` command line: serve (default), install, doctor."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__
+
+CLIENTS = ("claude-code", "claude-desktop", "cursor", "codex", "windsurf", "print")
+
+
+def server_command(with_platformio: bool, policy: str | None) -> dict:
+    pkg = 'platformio.mcp[platformio]' if with_platformio else "platformio.mcp"
+    entry = {"command": "uvx", "args": [pkg]}
+    if policy:
+        entry["env"] = {"PLATFORMIO_MCP_POLICY": policy}
+    return entry
+
+
+def _merge_json(path: Path, key_path: list[str], entry: dict) -> None:
+    data = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8") or "{}")
+        except json.JSONDecodeError as exc:
+            sys.exit(f"{path} is not valid JSON ({exc}); fix it or add the entry by hand:\n{json.dumps(entry, indent=2)}")
+    node = data
+    for key in key_path[:-1]:
+        node = node.setdefault(key, {})
+    node[key_path[-1]] = entry
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def claude_desktop_config() -> Path:
+    system = platform.system()
+    if system == "Darwin":
+        return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    if system == "Windows":
+        return Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) / "Claude" / "claude_desktop_config.json"
+    return Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+
+
+def install(client: str, with_platformio: bool, policy: str | None, scope: str) -> None:
+    entry = server_command(with_platformio, policy)
+    if client == "print":
+        print(json.dumps({"mcpServers": {"platformio": entry}}, indent=2))
+        return
+    if client == "claude-code":
+        claude = shutil.which("claude")
+        if not claude:
+            sys.exit("`claude` CLI not found on PATH. Install Claude Code, or run: uvx platformio.mcp install --print")
+        cmd = [claude, "mcp", "add", "--scope", scope, "--transport", "stdio"]
+        for k, v in entry.get("env", {}).items():
+            cmd += ["--env", f"{k}={v}"]
+        cmd += ["platformio", "--", entry["command"], *entry["args"]]
+        print("$ " + " ".join(cmd))
+        subprocess.run(cmd, check=False)
+        return
+    if client == "claude-desktop":
+        path = claude_desktop_config()
+        _merge_json(path, ["mcpServers", "platformio"], entry)
+        print(f"Added 'platformio' to {path}. Restart Claude Desktop.")
+        return
+    if client == "cursor":
+        path = Path.home() / ".cursor" / "mcp.json" if scope == "user" else Path.cwd() / ".cursor" / "mcp.json"
+        _merge_json(path, ["mcpServers", "platformio"], entry)
+        print(f"Added 'platformio' to {path}. Reload Cursor's MCP settings.")
+        return
+    if client == "windsurf":
+        path = Path.home() / ".codeium" / "windsurf" / "mcp_config.json"
+        _merge_json(path, ["mcpServers", "platformio"], entry)
+        print(f"Added 'platformio' to {path}. Restart Windsurf.")
+        return
+    if client == "codex":
+        path = Path.home() / ".codex" / "config.toml"
+        block = "\n[mcp_servers.platformio]\ncommand = \"uvx\"\nargs = [" + ", ".join(json.dumps(a) for a in entry["args"]) + "]\n"
+        if entry.get("env"):
+            block += "[mcp_servers.platformio.env]\n" + "".join(f'{k} = "{v}"\n' for k, v in entry["env"].items())
+        existing = path.read_text(encoding="utf-8") if path.exists() else ""
+        if "[mcp_servers.platformio]" in existing:
+            print(f"{path} already has [mcp_servers.platformio]; edit it by hand if needed:\n{block}")
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(existing.rstrip("\n") + "\n" + block, encoding="utf-8")
+        print(f"Appended [mcp_servers.platformio] to {path}. Restart Codex.")
+        return
+    sys.exit(f"unknown client {client}; choose from {', '.join(CLIENTS)}")
+
+
+def doctor() -> None:
+    from .tools.system import pio_system_info
+
+    print(json.dumps(pio_system_info(), indent=2))
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="platformio.mcp", description="MCP server for PlatformIO. With no subcommand it serves over stdio.")
+    parser.add_argument("--version", action="version", version=f"platformio.mcp {__version__}")
+    sub = parser.add_subparsers(dest="cmd")
+    sub.add_parser("serve", help="run the MCP server on stdio (default)")
+    p_install = sub.add_parser("install", help="register this server with an MCP client")
+    p_install.add_argument("--client", choices=CLIENTS, help="which client to configure")
+    for c in CLIENTS:
+        p_install.add_argument(f"--{c}", dest="client", action="store_const", const=c, help=f"shortcut for --client {c}")
+    p_install.add_argument("--with-platformio", action="store_true", help="bundle PlatformIO Core via the [platformio] extra so nothing else needs installing")
+    p_install.add_argument("--policy", choices=("full", "build_only", "read_only"), help="set PLATFORMIO_MCP_POLICY for the server")
+    p_install.add_argument("--scope", choices=("user", "project"), default="user", help="where the client stores the config (claude-code, cursor)")
+    sub.add_parser("doctor", help="print pio_system_info as JSON")
+
+    args = parser.parse_args(argv)
+    if args.cmd == "install":
+        if not args.client:
+            p_install.error("choose a client, e.g. --claude-code, --cursor, --claude-desktop, --codex, --windsurf, or --print")
+        install(args.client, args.with_platformio, args.policy, args.scope)
+    elif args.cmd == "doctor":
+        doctor()
+    else:
+        from .server import serve
+
+        serve()
+
+
+if __name__ == "__main__":
+    main()