dbgprobe-mcp-server

Debug Probe MCP サーバー

開発者向けツールや AI エージェント向けの、状態を保持するデバッグプローブ Model Context Protocol（MCP）サーバーです。 Claude Code、Copilot 搭載の VS Code、その他の MCP 対応ランタイムですぐに利用できます。stdio 経由で通信し、オンチップデバッグプローブ（まずは J-Link に対応。OpenOCD と pyOCD は今後対応予定）を操作して、組み込みターゲットへの書き込み、デバッグ、検査を行います。

例： Claude Code に接続中の J-Link プローブを一覧表示させ、nRF52840 に接続し、新しいファームウェアを書き込み、メモリを読み取り、ターゲットをリセットさせます。すべて会話形式で行えます。

デモ

動画による解説 — J-Link プローブへの接続、ファームウェアの書き込み、シンボル対応デバッグのための ELF と SVD の読み込み、RTT ログ、ブレークポイントを紹介します。

---

このプロジェクトの目的

J-Link Commander のコマンドを手入力したり、データシートとターミナルの間でメモリアドレスをコピー＆ペーストしたり、デバッグ中に同じファームウェアを20回再書き込みしたり、複数のツールウィンドウを行き来したりした経験がある方におすすめです。

デバッグプローブにマイコンが接続されています。それを AI エージェントで操作したいと考えているでしょう。接続、ファームウェアの書き込み、メモリの読み書き、リセット、停止、再開が可能です。このサーバーがそれを実現します。

MCP 対応エージェントに、デバッグプローブ用のツール一式を提供します。エージェントがツールを呼び出すと、構造化された JSON が返され、それをもとに次の操作を判断します。操作のたびに JLinkExe を手動で実行する必要はありません。

エージェントでできること：

• 書き込みと反復 — ファームウェアをビルドして書き込み、リセットし、動作を確認できます。すべて一度の会話で行えます
• メモリの検査 — 周辺機器レジスターの読み取り、RAM の内容確認、フラッシュへの書き込み検証ができます
• 対話形式のデバッグ — 停止、ステップ実行、ブレークポイント設定、状態の検査、再開ができます
• テストフローの自動化 — 書き込み → リセット → 出力の読み取り → 検証を行えます
• 複数プローブ構成 — それぞれ独自のセッションを持つ複数のプローブに同時接続できます

---

対象ユーザー

• 組み込みエンジニア — 会話形式でファームウェアを書き込み、デバッグし、メモリを検査することで、反復作業を高速化できます
• ホビイストやメーカー — JLinkExe のコマンド構文を覚えずにマイコンを操作できます
• QA・テストエンジニア — 複数のボードで書き込みとテストの一連の処理を自動化できます
• 研究者 — 組み込みシステムを体系的に調査し、レジスターを検査できます

---

クイックスタート（Claude Code）

pip install dbgprobe-mcp-server

# Register the MCP server with Claude Code
claude mcp add dbgprobe -- dbgprobe_mcp

# Or with explicit J-Link path
claude mcp add dbgprobe \
  -e DBGPROBE_JLINK_PATH=/Applications/SEGGER/JLink/JLinkExe \
  -- dbgprobe_mcp

次に、Claude Code で以下を試してみてください。

「接続中のデバッグプローブを一覧表示し、J-Link に接続して、アドレス 0x20000000 から16バイト読み取ってください。」

---

対応バックエンド

バックエンド	状態	プローブハードウェア
J-Link	動作中（v0）	SEGGER J-Link（EDU、EDU Mini、PLUS、PRO など）
OpenOCD	対応予定	ST-Link、CMSIS-DAP など多数
pyOCD	対応予定	CMSIS-DAP、ST-Link、J-Link（pyOCD 経由）

サーバーはバックエンドに依存しません。使用するプローブにかかわらず、ツール名（dbgprobe.*）は同じです。

J-Link の要件

SEGGER J-Link Software Pack をインストールしてください。サーバーは JLinkExe を PATH 上、または一般的なインストール先から自動検出します。

• macOS： /Applications/SEGGER/JLink/
• Linux： /opt/SEGGER/JLink/、/usr/bin/
• Windows： C:\Program Files\SEGGER\JLink\

または、実行ファイルを直接指定するように DBGPROBE_JLINK_PATH を設定してください。

このプロジェクトは SEGGER と提携・協賛関係にありません。J-Link は広く利用可能で、十分にサポートされているため採用しています。

---

ツール

カテゴリ	ツール
プローブ	dbgprobe.probes.list, dbgprobe.connect, dbgprobe.erase, dbgprobe.disconnect, dbgprobe.reset, dbgprobe.halt, dbgprobe.go, dbgprobe.step, dbgprobe.status, dbgprobe.flash, dbgprobe.mem.read, dbgprobe.mem.write, dbgprobe.breakpoint.set, dbgprobe.breakpoint.clear, dbgprobe.breakpoint.list
イントロスペクション	dbgprobe.connections.list
ELF	dbgprobe.elf.attach, dbgprobe.elf.info, dbgprobe.elf.lookup, dbgprobe.elf.symbols
SVD	dbgprobe.svd.attach, dbgprobe.svd.info, dbgprobe.svd.read, dbgprobe.svd.write, dbgprobe.svd.set_field, dbgprobe.svd.update_fields, dbgprobe.svd.list_peripherals, dbgprobe.svd.list_registers, dbgprobe.svd.list_fields, dbgprobe.svd.describe
RTT	dbgprobe.rtt.start, dbgprobe.rtt.stop, dbgprobe.rtt.read, dbgprobe.rtt.write, dbgprobe.rtt.status
プラグイン	dbgprobe.plugin.list, dbgprobe.plugin.template, dbgprobe.plugin.load, dbgprobe.plugin.reload
トレース	dbgprobe.trace.status, dbgprobe.trace.tail

スキーマと使用例の詳細は、docs/tools.md を参照してください。

---

インストール（開発環境）

# Editable install from repo root
pip install -e ".[test]"

# Or with uv
uv pip install -e ".[test]"

MCP はプロトコルです。このサーバーは、MCP 互換のあらゆるクライアントで動作します。以下に、最も一般的なクライアントのセットアップ手順を示します。

Claude Code に追加する

# Standard setup
claude mcp add dbgprobe -- dbgprobe_mcp

# With default target device
claude mcp add dbgprobe \
  -e DBGPROBE_JLINK_DEVICE=nRF52840_xxAA \
  -- dbgprobe_mcp

# Debug logging
claude mcp add dbgprobe -e DBGPROBE_MCP_LOG_LEVEL=DEBUG -- dbgprobe_mcp

VS Code / Copilot に追加する

プロジェクトの .vscode/mcp.json に追加するか、ファイルを新規作成します。

{
  "servers": {
    "dbgprobe": {
      "type": "stdio",
      "command": "dbgprobe_mcp",
      "args": [],
      "env": {
        "DBGPROBE_JLINK_DEVICE": "nRF52840_xxAA"
      }
    }
  }
}

env をターゲットに合わせて調整してください。DBGPROBE_JLINK_DEVICE にチップを設定するか、この項目を削除して接続時にデバイスを指定します。

Cursor に追加する

プロジェクトの .cursor/mcp.json に追加するか、ファイルを新規作成します。Cursor はツール名のドットをサポートしていないため、DBGPROBE_MCP_TOOL_SEPARATOR を _ に設定する必要があります。

{
  "mcpServers": {
    "dbgprobe": {
      "command": "dbgprobe_mcp",
      "args": [],
      "env": {
        "DBGPROBE_JLINK_DEVICE": "nRF52840_xxAA",
        "DBGPROBE_MCP_TOOL_SEPARATOR": "_"
      }
    }
  }
}

環境変数

サーバー

変数	デフォルト	説明
DBGPROBE_BACKEND	jlink	デバッグプローブのバックエンドです。将来的に openocd、pyocd をサポートする予定です。
DBGPROBE_MCP_LOG_LEVEL	WARNING	Python のログレベルです（DEBUG、INFO、WARNING、ERROR）。ログは stderr に出力されます。
DBGPROBE_MCP_TRACE	有効	すべてのツール呼び出しを JSONL 形式でトレースします。無効にするには 0、false、または no を設定します。
DBGPROBE_MCP_TRACE_PAYLOADS	無効	トレース対象の引数にメモリデータのペイロードを含めます（デフォルトでは除外されます）。
DBGPROBE_MCP_TRACE_MAX_BYTES	16384	切り詰める前のペイロードの最大文字数です（TRACE_PAYLOADS が有効な場合のみ）。
DBGPROBE_MCP_TOOL_SEPARATOR	.	ツール名のセグメントを区切る文字です。ツール名のドットを受け付けない MCP クライアント（Cursor など）では _ を設定します。
DBGPROBE_MCP_PLUGINS	無効	プラグインのポリシーです。all、またはカンマ区切りのプラグイン名（例：nrf52,stm32）を指定します。

J-Link バックエンド

変数	デフォルト	説明
DBGPROBE_JLINK_PATH	自動検出	JLinkExe（Windows では JLink.exe）への明示的なパスです。
DBGPROBE_JLINK_GDBSERVER_PATH	自動検出	JLinkGDBServerCLExe への明示的なパスです。
DBGPROBE_JLINK_DEVICE	(なし)	デフォルトのターゲットデバイス文字列です（例：nRF52840_xxAA）。セッションごとに上書きできます。
DBGPROBE_INTERFACE	SWD	デバッグインターフェースです。SWD または JTAG を指定します。
DBGPROBE_SPEED_KHZ	4000	インターフェースのクロック速度（kHz）です。
DBGPROBE_GDB_TRACE	無効	すべての GDB RSP パケットをファイルに記録します。有効にするには 1、true、または yes を設定します。
DBGPROBE_GDB_TRACE_FILE	/tmp/gdb_trace.log	GDB RSP トレースログのパスです（GDB_TRACE が有効な場合のみ）。

---

ELF サポート

セッションに ELF ファイルを添付すると、シンボルを認識したデバッグが有効になります。

• シンボル検索 — 関数名をアドレスに、またはアドレスを関数名に解決します
• 名前によるブレークポイント — 生のアドレスではなく、breakpoint.set(symbol="main") を使います
• 自動拡張される応答 — ELF を添付すると、status、step、halt に symbol と symbol_offset が含まれます
• フラッシュとの連携 — .elf をフラッシュすると自動的に添付されます。.hex／.bin をフラッシュすると、以前に添付した ELF が自動的に再読み込みされます。同じディレクトリにある .elf ファイルはヒントとして提案されます

> "Attach the ELF, set a breakpoint on main, run, and show me where it halted."

エージェントが elf.attach、breakpoint.set(symbol="main")、go、続いて status を呼び出すと、生の 16 進アドレスではなく "halted at main+0" が返されます。

---

SVD サポート

セッションに SVD（System View Description）ファイルを添付すると、レジスターレベルのペリフェラルアクセスが有効になります。

• 名前付きレジスターの読み取り — svd.read("GPIO.OUT") は生の値と、列挙型の名前を含むデコード済みフィールドをすべて返します
• フィールドレベルの読み取り — svd.read("GPIO.PIN_CNF[3].PULL") はフィールド値と列挙型の名前（"PullUp"）を返します
• 安全なフィールド書き込み — svd.set_field("GPIO.PIN_CNF[3].PULL", "PullUp") は読み取り・変更・書き込みを行います
• 複数フィールドの一括更新 — svd.update_fields("GPIO.PIN_CNF[3]", {"DIR": "Output", "PULL": "PullUp"}) — 読み取り 1 回、書き込み 1 回で更新します
• レジスターへの生の書き込み — svd.write("GPIO.OUT", 0x01) — レジスター全体に書き込み、RMW は行いません
• 検出 — ペリフェラル、レジスター、フィールドを一覧表示し、列挙型とともに説明します
• mem.read 時の自動デコード — SVD が添付されている状態で mem.read が既知のレジスターアドレスにアクセスすると、応答にデコード済みフィールドが含まれます

> "Attach the SVD, read GPIO.PIN_CNF[3], and set PULL to PullUp."

エージェントが svd.attach、svd.read("GPIO.PIN_CNF[3]")、続いて svd.set_field("GPIO.PIN_CNF[3].PULL", "PullUp") を呼び出すと、生の 16 進値ではなく、デコード済みのフィールド値が返されます。

---

RTT（リアルタイム転送）

SEGGER RTT チャネルの開始、停止、読み取り、書き込みができます。エージェントはターゲットのログ出力をストリーミングし、デバイスにデータを送信できます。UART ではなく RTT 経由で出力するファームウェアのデバッグに便利です。

> "Start RTT and show me the output."

デバイス ID の読み取り、セルフテストの実行、キャリブレーションの検証など、繰り返し行うワークフローは プラグイン としてパッケージ化できます。プラグインは、エージェントが直接呼び出せるカスタムツールを公開する Python モジュールです。DBGPROBE_MCP_PLUGINS=all で有効にできます。nrf52_info の例を参照してください。

---

トレーシング

すべてのツール呼び出しは .dbgprobe_mcp/traces/trace.jsonl とインメモリーのリングバッファ（直近 2000 件のイベント）に記録されます。トレーシングはデフォルトで有効です。無効にするには DBGPROBE_MCP_TRACE=0 を設定します。

ファイルを直接読み取らずにトレースを確認するには、dbgprobe.trace.status と dbgprobe.trace.tail を使います。

---

エージェントなしで試す

MCP Inspector を使って、サーバーを対話的にテストできます。

npx @modelcontextprotocol/inspector python -m dbgprobe_mcp_server

---

ロードマップ／TODO

• OpenOCD バックエンド — OpenOCD サブプロセスを介して、ST-Link、CMSIS-DAP、その他のプローブをサポートします
• pyOCD バックエンド — pyOCD ライブラリを介して、ネイティブの Python プローブアクセスを実現します
• マルチコアサポート — マルチコア SoC の特定のコアを対象にします
• Cortex-A/R サポート — ARM モードのブレークポイント（kind=4）。現在は Thumb のみ（Cortex-M）です

---

既知の制限事項

• シングルクライアントのみです。 サーバーは一度に 1 つの MCP セッションのみを処理します（stdio トランスポート）。
• RTT チャンネル 0 のみです。 RTT のサポートはチャンネル 0（ターミナル）に限定されています。マルチチャンネル RTT は今後の拡張項目です。
• フラッシュ書き込みでブレークポイントがクリアされます。 新しいファームウェアを書き込むと、ブレークポイントは無効になります（該当アドレスのコードが変更されている可能性があるためです）。セッションは維持されますが、ブレークポイントはクリアされます。
• Cortex-M のみです。 ブレークポイントは Thumb モード（kind=2）を使用します。Cortex-A/R ターゲット（ARM モード、kind=4）はまだサポートされていません。
• 命令単位のステップ実行のみです。 dbgprobe.step は CPU 命令を 1 つずつステップ実行します。ソースレベルのステップ実行（ステップイン／オーバー／アウト）はサポートされていません。

---

安全性

このサーバーは AI エージェントを実際のデバッグハードウェアに接続します。それが目的であり、純粋なソフトウェアツールよりも大きなリスクを伴うということでもあります。

プラグインは任意のコードを実行します。 プラグインが有効になっている場合、エージェントはサーバーのすべての権限を使って、マシン上で Python コードを作成・実行できます。エージェントが生成したプラグインは、読み込む前に確認してください。

書き込みは実際のハードウェアに影響します。 メモリへの不適切な書き込みやフラッシュ操作によって、デバイスが使用不能になったり、キャリブレーションデータが消去されたり、意図しない動作が引き起こされたりする可能性があります。エージェントがアクセスできる範囲を考慮してください。

ツールの承認は慎重に行ってください。 MCP クライアントからツール呼び出しの承認を求められたときは、今回だけ許可するか、常に許可するかを検討してください。

このソフトウェアは MIT License のもとで現状のまま提供されます。エージェントがハードウェアに対して行うことについては、利用者が責任を負います。

---

ライセンス

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