McuBuddy

McuBuddy — AI を活用した MCU および組み込みファームウェアのデバッグ用 MCP サーバー

言語： 英語 | 中国語

ファームウェア解析から実際の MCU にまで AI の機能を拡張し、検証済みの環境で診断、コード変更、ビルド、書き込み、検証までの一連の流れを実現します。

McuBuddy は、MCU ボードレベルのデバッグ用 Model Context Protocol (MCP) サーバーです。デバッグプローブ、Keil MDK プロジェクト、ELF/DWARF シンボル、CPU とメモリの状態、SVD 周辺機器レジスター、UART/RTT ログ、FreeRTOS の状態、Flash 操作、GDB サーバーを、AI アシスタントが呼び出せる構造化ツールとして公開します。

ファームウェア開発、ボードの初期立ち上げ、障害の切り分け、デバッグの自動化、AI を活用した検証向けに設計されています。

McuBuddy は、default ツールセットで19個の安定したツールから開始します。MCUBUDDY_TOOLSETS=probe,diagnose を指定して、ワークフローに必要なドメインだけを追加できます（利用可能なドメイン：probe、diagnose、build_flash、rtos、logs、experimental）。利用できるプロファイルは core のみです。起動時のツールセット選択は明示的で、変更できません。

重要

自動化によってエンジニアリング上の責任がなくなるわけではありません。目標と受け入れ基準、配線と電源の安全、高リスク操作の承認、コードレビュー、新しい環境での検証については、引き続き人間が責任を負います。モーター、リレーなどの安全に関わる機器には、復旧計画と独立した保護機構も必要です。

クイックリンク： クイックスタート · プロジェクトガイド · ツールリファレンス · サポート対象一覧

✨ 主な機能

• 実機デバッグ：ST-Link、J-Link、CMSIS-DAP などのプローブを検出して接続し、ターゲットの実行を制御して、レジスター、メモリ、ブレークポイント、ウォッチポイントを調べられます。
• Keil プロジェクトのワークフロー：.uvprojx / .uvproj ファイルを検出してターゲットを選択し、Keil MDK を UV4.exe 経由で呼び出してビルドやダウンロードを行い、生成された AXF/ELF をデバッグに利用できます。
• ソースレベルの障害診断：HardFault、起動失敗、スタックオーバーフロー、メモリ破損の調査時に、ELF/DWARF データを使用してアドレスを関数、ソース行、ローカル変数、コールスタックに対応付けられます。
• 周辺機器と RTOS の調査：CMSIS-SVD を使って周辺機器レジスターをデコードし、FreeRTOS のタスク、タスクコンテキスト、スタック使用量を調べられます。
• ログとランタイムの可観測性：UART、RTT、選択した J-Link SWO ログを読み取り、pyOCD/J-Link GDB サーバーのライフサイクルを管理できます。
• 証拠に基づく結果：ターゲット、状態、検証に関する構造化された証拠を返すため、AI は症状だけからコード変更を推測するのではなく、調査を続けられます。
• 実用的なハードウェア境界：MCU の制限、ファームウェアに適用できないツール、設定の問題、ツールの障害、証拠の不足を、その影響と次に行う安全な確認事項とともに区別します。これにより、サポート対象外の経路をファームウェアの不具合としてデバッグすることを防ぎます。

🏗️ 仕組み

flowchart LR
    AI["AI Client<br/>Codex / Claude Code"] --> MCP["McuBuddy<br/>MCP Server"]
    MCP --> EB["Execution Boundary<br/>Serialized Session"]
    EB --> TOOLS["Debugging Tools<br/>Diagnostics / Symbols / SVD / RTOS / Logs"]
    TOOLS --> KEIL["Keil MDK / UV4.exe<br/>Build / Optional Download"]
    TOOLS --> PROBE["Probe Backends<br/>pyOCD / J-Link / probe-rs"]
    KEIL --> IMAGE["AXF / ELF / HEX / BIN"]
    IMAGE --> TOOLS
    PROBE --> BOARD["Real MCU Board"]

MCP は Keil を呼び出すためのプロトコルではありません。AI は MCP 経由で McuBuddy を呼び出し、McuBuddy は必要に応じて UV4.exe、pyOCD、J-Link、または別の内部バックエンドを通じて Keil MDK を使用します。

🚀 クイックスタート

1. 前提条件

基本要件：

• Python 3.10 以降；
• 電源が入った MCU 開発ボード；
• 正しく接続された ST-Link、J-Link、または CMSIS-DAP プローブ；
• ターゲットのチップ名；
• できれば、デバッグ情報を含む ELF/AXF イメージ。

Keil のビルドとダウンロード機能には、Keil MDK がインストールされた Windows が必要です。McuBuddy は、Keil MDK v5 のインストール環境を含め、UV4.exe 経由で µVision を呼び出します。

2. インストール

pip install "McuBuddy @ git+https://github.com/cunjun/McuBuddy.git"

これにより、すべてのローカルファームウェアプロジェクトで McuBuddy を一度インストールするだけで使用できます。各対象プロジェクトに McuBuddy リポジトリをクローンまたはコピーしないでください。McuBuddy はローカル専用の MCP バックエンドです。クライアントは接続ごとに 1 つの stdio プロセスを起動し、McuBuddy は HTTP、SSE、WebSocket、その他の MCP ネットワークリスナーを公開しません。

対象プロジェクト、Keil のインストール環境、ELF/SVD ファイル、プローブ、シリアルポートは、McuBuddy を実行するマシンから直接アクセスできる必要があります。更新するには、公式リポジトリ https://github.com/cunjun/McuBuddy から再インストールしてください。McuBuddy が更新を自動で確認、ダウンロード、インストールすることはありません。

J-Link Python バックエンドを使用する場合は、オプションの依存関係をインストールしてください。

pip install "McuBuddy[jlink]"

ソースから開発する場合：

git clone https://github.com/cunjun/McuBuddy.git
cd McuBuddy
pip install -e ".[dev]"

3. MCP クライアントを設定する

{
  "mcpServers": {
    "McuBuddy": {
      "command": "McuBuddy",
      "args": []
    }
  }
}

Windows でソースをチェックアウトして使用する場合は、仮想環境の Python 実行ファイルと作業ディレクトリを明示的に設定してください。インストールと初回接続を参照してから、AI クライアントを再起動してください。

4. 最初の読み取り専用チェックを実行する

プローブを接続してボードの電源を入れたら、AI に次のように伝えてください。

Use McuBuddy to inspect the current debugging environment, discover connected probes,
and perform a first read-only check of the board without writing Flash.
Before starting, tell me what information is still missing.

推奨手順では、まず環境と対象を確認し、次にプローブを設定して、対象の状態を最小限読み取ります。

doctor()
list_connected_probes()
match_chip_name("py32f030x8")
configure_probe(target="py32f030x8", backend="pyocd")
probe_connect(target="py32f030x8")
read_stopped_context()

probe_connect と read_stopped_context は、デフォルトの core プロファイルで使用できます。安定した停止コンテキストを読み取ると、対象が停止する場合があるため、実行状態に影響します。デバイスを停止してはならない場合は、非侵襲的なプローブチェックと環境チェックのみを実行するよう AI に指示してください。

💬 自動デバッグの例

Use McuBuddy to debug <project path>. The MCU is <exact model>, and the probe is
<ST-Link/J-Link/CMSIS-DAP>. First collect board-level evidence and locate the problem. After
authorization, modify the code, build and flash it, then validate the result on the real board.

証拠を優先する判断順序と一般的なシナリオについては、一般的なデバッグワークフローを参照してください。

🧰 バックエンドとハードウェアの検証

経路	現在の役割	主な機能
pyOCD + ST-Link/CMSIS-DAP	プライマリバックエンド	制御、メモリ、Flash、ソースデバッグ、RTT、RTOS、GDB サーバー
J-Link	プライマリバックエンド	制御、メモリ、Flash、ソースデバッグ、ネイティブ RTT、DWT、GDB サーバー
probe-rs sidecar	拡張プレビュー	ARM/RISC-V/Xtensa の検出、設定可能なコア制御、レジスタ、メモリ、ハードウェアブレークポイント、Flash、RTT
Keil MDK（Windows、UV4.exe 経由）	ビルド／ダウンロード用バックエンド	プロジェクト検出、ターゲット設定、ビルド、ログ、オプションのダウンロード。MDK v5 のインストール環境に対応

主な検証対象は次のとおりです。

• STM32L496VETx + ST-Link / pyOCD；
• STM32F103C8 + J-Link；
• STM32F103ZE および PY32F030X8 用の組み込みターゲット事前チェックプロファイル。

「コードに実装済み」であっても、「すべてのボードで検証済み」という意味ではありません。正確な情報はサポートマトリックスと list_validation_records() を参照してください。

🛡️ 安全モデル

McuBuddy は、list_tool_safety() を通じて機械可読な安全分類を提供します。

カテゴリ	例	デフォルトの要件
読み取り専用	ターゲット照合、レジスタ／メモリの読み取り、シンボル解決、ログ、診断	確認は不要
実行状態を変更する操作	halt、resume、reset、continue、ステッピング	Flash への書き込みは行いませんが、実行状態を変更します
ランタイム状態への書き込み	メモリ／レジスタへの書き込み、ブレークポイント、ウォッチポイント、SVD フィールドへの書き込み	明示的な確認が必要
永続的で破壊的な操作	Flash の消去／書き込み、Keil によるファームウェアのダウンロード	明示的な確認が必要
ホストプロセス	Keil のビルド、GDB サーバーの起動／停止	ローカルプロセスを起動または停止します

安全性の原則：

1. 不明なターゲットでは、まずチップとプローブを照合し、アドレスを推測しないでください。
2. 停止、リセット、書き込みを行う前に、根拠となる情報を読み取ってください。
3. Flash 操作の前に、ターゲット、対象範囲、イメージ、復旧方法を確認してください。
4. モーター、リレー、電源スイッチなどのアクチュエーターでは、ブレークポイントと低エネルギーでのテストを優先してください。
5. uart_send_with_cleanup でアクチュエーターへのコマンドを送信し、最終的な結論を返す前に finish_debug_session を呼び出してください。サーバーのシャットダウン時には、フォールバックとして同じ冪等なクリーンアップを再度実行します。

🔒 セッションと並行処理

• プローブ、Keil、ELF／SVD、ログ、ランタイム設定を共有する操作は、同じ Session 内で直列化されます。
• 無関係なボードを制御する場合は、異なるセッションを並行して実行できます。
• ターゲット照合やツールの安全性情報など、ステートレスなクエリはセッション操作と並行して実行できます。
• 同期 SDK に入った呼び出しを、キャンセルによって強制終了することはできません。サーバーは、セッションロックを解放する前にワーカースレッドの終了を待ちます。

これにより、別のプローブ操作がまだ実行中のときに、あるリクエストがバックエンドを切り替えたり、プローブを切断したり、共有状態を変更したりするのを防ぎます。

📦 mcubuddy スキル

リポジトリには skills/mcubuddy が含まれており、MCP ツールを順不同のコマンド一覧として扱うのではなく、「まず根拠を集め、次に判断する」手順で Codex と Claude Code がこれらのツールを使用できるよう案内します。

このスキルは任意のワークフロー拡張であり、ハードウェアのデバッグに必須ではありません。正しくインストールおよび設定されたローカルの McuBuddy MCP サーバーは、スキルがなくても完全に使用できます。

インストール済みのリリースにはスキルが同梱されています。リポジトリをクローンせずに、Codex の永続的な統合を登録します：

uv tool install McuBuddy
McuBuddy setup codex --confirm --json

Codex にインストールする場合：

python .\skills\mcubuddy\scripts\install_skill.py --target codex --overwrite

Claude Code にインストールする場合：

python .\skills\mcubuddy\scripts\install_skill.py --target cc --overwrite

インストール後、クライアントを再起動するか、新しいセッションを開いてください。ソースチェックアウトからの復旧、インストール登録、使用上の境界について詳しくは、 境界：McuBuddy、MCP、スキル をご覧ください。

⚠️ 現在の制限事項

• Keil のビルドとダウンロードには、現在、Keil MDK を搭載した Windows が必要です。また、MDK v5 のインストール環境を含め、µVision を UV4.exe 経由で呼び出します。
• probe-rs サイドカーは Flash と RTT に対応していますが、ターゲットごとの実機検証が引き続き必要であり、公式バイナリはまだリリースされていません。
• RTOS の検査には FreeRTOS シンボルと、ターゲットのファームウェアに一致する ELF／AXF が必要です。
• すべてのチップに対応する SVD ファイルが自動的に同梱されるわけではなく、通常は CMSIS-Pack またはチップベンダーから入手します。
• SWO テキストのキャプチャは、チップの設定、プローブの機能、ピンの多重化、ボードの配線に依存します。
• デバイスパッチと接続方式は、完全なボードプラグインシステムではなく、軽量な仕組みとして提供されています。

📚 ドキュメント

• プロジェクトの全体像とワークフロー：プロジェクトガイド
• プロジェクトの全体像（中国語）：项目指南
• ツールの完全な一覧：ツールリファレンス
• ツールの使い方（中国語）：MCP 工具中文参考
• バックエンドとハードウェアの検証：サポートマトリックス
• プロジェクト設計：アーキテクチャ
• リリース履歴：変更履歴

🧪 ローカル開発

pip install -e ".[dev]"
pytest
ruff check src tests

リポジトリの構成とドキュメントの管理担当については、プロジェクトガイドを参照してください。

🙏 上流プロジェクトと謝辞

McuBuddy は SolarWang233/mcudbg をベースとしており、 追加のアーキテクチャ、安全境界、エビデンスを扱うワークフロー、バックエンドのサポート、 ドキュメントを加えながら、MIT ライセンスのもとで開発を続けています。元の著作権表示は LICENSEに保持されており、由来の詳細はNOTICEに記載されています。

📄 ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細はLICENSEを参照してください。

---

McuBuddy が MCU のデバッグワークフローに役立った場合は、プロジェクトにスターを付けてください。 ご提案があれば、Issue を作成するか、 [email protected]までメールでお知らせください。