PIO Agent

PIO エージェント

PIO Agent は、PlatformIO MCP ランタイムを基盤とする、組み込み開発向けのオープンソースでエージェントファーストのハードウェア実行レイヤーです。

リリース状況

正式版の 3.1.0 ランタイムが公開されています。3.2.0 候補版では、 pio-agent CLI を主要なアダプターとして採用し（要求がない限り、何も実行状態のまま残りません）、 ネイティブの Codex パネルと公開プラグイン一覧のメタデータを追加しています。実装済みの 動作と各パッケージ名の公開状況については、 changelog、compatibility guide、 distribution readinessをご覧ください。

ブランドと互換性

PIO Agent は製品名および Codex プラグイン名です。PlatformIO MCP は基盤となる MCP ランタイムであり、既存のインストールで使用されている互換性上の識別名です。Codex プラグイン ID、マーケットプレイス ID、設定キー、スキルの名前空間は、引き続き platformio-mcp です。npm では、platformio-mcp が正式なパッケージであり、pio-mcp と pio-agent はこれに処理を委譲する薄い互換パッケージです。正式なパッケージは、platformio-mcp と pio-agent の両方の実行ファイル名もインストールします。これにより、既存の利用者は移行せずにアップグレードでき、新しい利用者にはインターフェース全体で PIO Agent が表示されます。

以下を通じて、ボードの検出、プロジェクトのセットアップ、ビルド、書き込み、モニター、診断、タスクのオーケストレーションといった PlatformIO のワークフローを提供します。

• MCP サーバーアダプター
• ファーストクラスの CLI アダプター（platformio-mcp / pio-agent）
• 可視化と制御のためのオプションのローカルダッシュボード

MCP はアダプターの 1 つです。PlatformIO は最初のバックエンドです。

クイックスタート（推奨）

npm install -g platformio-mcp
pio-agent devices
pio-agent build --project-dir . --json

サーバーも、クライアント設定も不要で、コマンドの実行間に何も起動状態のまま残りません。

コーディングエージェントでの使用

スキルをインストールし、エージェントに pio-agent バイナリを指定します。 pio-manager スキルでは、すべてのコマンドについて説明しています。

MCP サーバー（任意）

MCP を利用するクライアント向けに、引き続き完全にサポートしています。

claude mcp add platformio -- node /path/to/platformio-mcp/build/index.js

この方法で接続する各セッションは、それぞれ独自のサーバープロセスを実行する点に ご注意ください。上記の CLI ではこれを回避できます。他のホストについては、 以下の手動 MCP 設定をご覧ください。

エージェントファーストの機能

• プロジェクトの準備状況の検証（agent_validate_project）
• 構造化されたエラー分類による詳細なビルド診断（agent_build_diagnose）
• ボードを考慮した GPIO の安全性監査（agent_safe_pin_audit）
• 書き込み＋モニター＋実行時アサーション（agent_flash_monitor_verify）
• .pio-mcp-workspace/ 内の永続的なワークフロー成果物（lastAgentReport.json、boardReport.json）
• ボード情報レポート（agent_generate_board_report）
• ポリシープロファイルの詳細確認（get_policy_status）
• プロジェクト／環境／デバイスの厳密な紐付け（agent_resolve_target）
• カーソルベースで範囲を限定したシリアルのヘルスチェック（agent_monitor_health）
• 冪等なタスクキャンセルと簡潔な履歴（cancel_task、list_task_history）
• エージェント向けの読み取り専用の承認状況。承認は引き続き人間が管理します

リスクを伴うすべての操作には、引き続きポリシーと承認のルールが適用されます。

クイックスタート

1. ダッシュボードを起動する

npx platformio-mcp dashboard --serve

2. CLI を使用する

npm の 3 つの名前すべてがサポートされています。platformio-mcp が正式なパッケージで、pio-mcp と pio-agent は依存関係のみの薄いエイリアスを通じて同じ CLI をインストールします。

npx platformio-mcp --help
npx pio-mcp --help
npx pio-agent --help

npx --package platformio-mcp pio-agent devices
npx --package platformio-mcp pio-agent boards --filter esp32
npx platformio-mcp init --board esp32dev --framework arduino --project-dir ./firmware
npx platformio-mcp build --project-dir ./firmware
npx platformio-mcp flash --project-dir ./firmware --port auto
npx platformio-mcp monitor --project-dir ./firmware --port auto --expect BOOT_OK --timeout 30
npx platformio-mcp agent-validate --project-dir ./firmware
npx platformio-mcp agent-build-diagnose --project-dir ./firmware
npx platformio-mcp agent-safe-pin-audit --project-dir ./firmware --board esp32dev
npx platformio-mcp agent-flash-monitor-verify --project-dir ./firmware --expect-all BOOT_OK --reject-patterns "Guru Meditation,Brownout detector,WDT reset" --timeout 45
npx platformio-mcp agent-last-report --project-dir ./firmware
npx platformio-mcp policy-status --project-dir ./firmware
npx platformio-mcp task-status <task-id>

機械可読な出力には --json を使用します。

npx platformio-mcp build --project-dir ./firmware --json

3. AI ホストにインストールする

npx platformio-mcp install --cline
npx platformio-mcp install --claude
npx platformio-mcp install --vscode
npx platformio-mcp install --antigravity
npx platformio-mcp install --codex

4. 完全版 Codex Plugin をインストールする

PIO Agent Codex Plugin には、バンドルされた MCP ランタイム、目的に特化した組み込みスキル、安全なアプリ内ダッシュボードのフロー、モニタリング自動化のガイダンスが追加されています。Codex では安定したプラグイン識別子が 1 つ必要なため、インストールセレクターとスキルの名前空間は platformio-mcp のままです。インストール後の製品名は PIO Agent と表示されます。リポジトリをクローンした場合：

npm install
npm --prefix web install
npm run plugin:build
node build/cli.js install --codex-plugin

npm からインストールする場合：

npx -y platformio-mcp install --codex-plugin

インストール後、新しい Codex タスクを開始してください。従来の install --codex コマンドも、MCP のみの設定用として引き続き利用できます。更新、アンインストール、ブラウザーのフォールバック、ポリシー、自動化、ロールバックについては、Codex Plugin 完全ガイドを参照してください。

プラグインのリリースゲートは Windows、macOS、Linux で実行され、Chromium で認証済みダッシュボードをテストし、バンドルされたランタイムと公開ツールレジストリを検証します。実機ボードのエビデンスは、独立した手動ワークフローで管理されます。このワークフローでアップロードされるのは、範囲が限定されサニタイズされたエビデンスのみです。未加工のハードウェアログはセルフホストランナーに保持されます。リリースと検証のガイドを参照してください。

ヘッドレス検証とステータス確認には、同じ CLI で plugin validate、target-resolve、monitor-status、monitor-health、task-history、approval-status、pending-approvals も利用できます。範囲が限定されたオプションと JSON 出力のサポートについては、platformio-mcp --help を実行してください。

MCP の手動設定

{
  "mcpServers": {
    "platformio": {
      "command": "npx",
      "args": ["-y", "platformio-mcp", "serve"]
    }
  }
}

Windows では、ホストで明示的な shim の解決が必要な場合、npx.cmd を使用してください。

主な機能

• PlatformIO 対応ハードウェアのボードとデバイスの検出
• プロジェクトの初期化と設定の確認
• ビルド、アップロード、モニタリング、バックグラウンドタスクのポーリング
• ビルド／アップロード／シリアル通信の失敗に関する構造化診断
• 安全性とポリシーのガードレール（承認ゲート、監査ログ、秘匿化）
• コマンド、ログ、ロック、安全状態をダッシュボードで確認

安全性モデル

PIO Agent は CLI と MCP の各フローでポリシーに基づく判断を適用します。

• アクションには allow、deny、requires_approval を指定できます
• リスクの高い操作（ファームウェアのアップロード／リセットなど）には明示的な承認が必要です
• すべてのアクションを監査できます
• 公開されるログストリームではシークレットが秘匿化されます

.pio-mcp-policy.json を使用すると、プロジェクトごとにポリシープロファイルを選択できます。

{
  "profile": "flash_requires_approval"
}

対応プロファイル：

• read_only
• build_only
• monitor_only
• flash_requires_approval
• lab_runner（明示的で有効期限付きの無人ラボポリシーが必要）
• lab_admin

CLI の承認ワークフロー：

npx platformio-mcp approvals --status pending --json
npx platformio-mcp approve <approval-id> --json
npx platformio-mcp deny <approval-id> --json

Codex の使用方法

Codex 向けのドキュメントとプロンプト集：

• Codex 使用ガイド
• Codex プロンプト集

ドキュメント

はじめに：

• LLM インストールガイド

ガイドとリファレンス：

• エージェントカスタマイズガイド
• MCP サーバーコマンドリファレンス
• トラブルシューティングガイド
• エージェント優先の組み込みワークフロー
• 競争上のポジショニング
• MCP-U 統合テンプレート
• エージェントスキルディレクトリ

仕様：

• PIO Agent 設計仕様
• Web UX 設計仕様
• 開発ガイド

開発

前提条件：

• Node.js >= 20（同梱の direct-serial ランタイムを含む）
• PlatformIO Core CLI（インストールガイド）

ローカル環境のセットアップ：

git clone https://github.com/jl-codes/platformio-mcp.git
cd platformio-mcp
npm install
npm run build
npm run test
npm run smoke-test

CI/CD のテスト段階：

• npm run test:ci:unit は、クロスプラットフォーム CI で使用するユニット／コンポーネントのカバレッジを実行します。
• npm run test:e2e:ci は、エージェントのワークフローと CLI の連携を対象とする、CI で安全に実行できるエンドツーエンドテストを実行します。
• .github/workflows/ci.yml は、プルリクエスト／プッシュ時に型チェック、テスト、パッケージのスモークテストを実行します。
• .github/workflows/hardware-e2e.yml は、明示的に確認された物理ボードへの書き込み、同梱プラグインのプロトコルチェック、書き込み後の ID／シリアル番号の検証、クリーンアップの証明、サニタイズ済みの証拠を対象とする、手動実行のセルフホストランナー用ワークフローです。

貢献

貢献を歓迎します。

• バグや機能リクエストについては、issue を作成してください。
• 該当する場合はテストを添えてプルリクエストを送信してください。

ライセンス

MIT。詳細は LICENSE を参照してください。

ファームウェアのクラッシュとサイズの分析

MCP ツール decode_backtrace と size_report は、登録済みの GNU ツールチェーンを使用して、明示的に選択されたプロジェクト／環境を分析します。メタデータとメモリのチェックではプロジェクトのスクリプトを実行する可能性があるため、ビルド権限が必要です。レポートには対象の ELF が正確に示され、解決できないクラッシュアドレスが保持されます。また、PlatformIO のメモリ使用量と GNU の推定値が区別されます。これらのツールは、デバイス上のファームウェアを特定するものではありません。入力、承認の動作、証拠、現在の制限については、ファームウェア分析を参照してください。