OpenImageDebugger MCP

oid-mcp

ライブの gdb/lldb セッションで、AI エージェントが OpenImageDebugger のバッファーを確認できるようにする MCP サーバーです。ブレークポイントで観測可能なシンボルの一覧表示、レンダリングの表示、正確な値の読み取り、ロスレスな .npy コピーのダンプ、人間向けビューアーへのバッファーのミラーリングができます。

⚠️ 実験的機能です。 新しい実験的機能のため、制御プロトコル、ツールの仕様、動作は予告なく変更される場合があり、安定性は保証されていません。オプトイン方式（OID_AGENT=1）であり、デバッグ対象プロセスのメモリをローカルプロセスに公開します。信頼できるローカル開発環境でのみ有効にしてください。フィードバックをお待ちしています。

仕組み

localhost ソケットを介して接続された、連携する 2 つの要素で構成されます。

• デバッガー内エンドポイント（OID の oid.py の一部で、標準ライブラリのみを使用）は、OID_AGENT=1 が設定されている場合、デバッガーに組み込まれた Python 内で起動します。セッションごとの検出ファイル（ホスト、ポート、ランダムなトークン）を、ユーザーごとのプライベートディレクトリに書き込みます。
• oid-mcp サーバー（このパッケージ）は MCP クライアントによって起動され、検出ファイルを読み取り、トークンを使って接続し、デコード、PNG レンダリング、統計、.npy などの処理を、脆弱なデバッガープロセスの外部で実行します。

デバッガーはユーザーが実行し、MCP クライアントは oid-mcp を実行します。検出ディレクトリを介して互いを見つけるため、両方が同じディレクトリを読み取れる必要があります（トラブルシューティングを参照）。

前提条件

• ビルドおよびインストール済みの OpenImageDebugger と、デプロイ済みの oid.py。トップレベルの README にあるOpen Image Debugger のビルドを参照してください。
• Python が組み込まれたデバッガー：gdb、または（macOS の場合）Homebrew の lldb — OID ですでに使用しているデバッガーと同じものです。
• uv — 管理された仮想環境でサーバーを実行するため、手動で pip install する必要はありません。curl -LsSf https://astral.sh/uv/install.sh | sh（または brew install uv）でインストールできます。
• MCP 対応クライアント（例：Claude Code）。

デプロイ

1. サーバーが起動することを確認します（任意ですが、推奨します）。シェルから実行します。

   uv run --directory /path/to/OpenImageDebugger/resources/oidmcp oid-mcp
   

   初回実行時に、mcp／numpy／pillow がローカルの venv に解決されます。標準エラー出力に実験的機能／セキュリティに関する警告が表示された後、標準入力で MCP の通信を待ちます。この待機状態になれば、正常に起動しています。終了するには Ctrl-C を押します。

2. MCP クライアントに登録します。 すべての stdio MCP クライアントで同じ mcpServers スキーマを使用します。異なるのはファイルの場所だけです。各クライアントはそれぞれ独自の oid-mcp プロセスを起動するため、複数のクライアントに同時に登録できます。どのクライアントからも同じデバッグセッションが検出されます。

   Claude Code — 1 行で登録：

   claude mcp add oid -- \
     uv run --directory /path/to/OpenImageDebugger/resources/oidmcp oid-mcp
   

   または、.mcp.json に追加します。

   {
     "mcpServers": {
       "oid": {
         "command": "uv",
         "args": ["run", "--directory",
                  "/path/to/OpenImageDebugger/resources/oidmcp",
                  "oid-mcp"]
       }
     }
   }
   

   Cursor — 同じエントリーを ~/.cursor/mcp.json（グローバル、すべてのプロジェクト）または <workspace>/.cursor/mcp.json（1 つのプロジェクト）に記述します。Settings → MCP / Tools & Integrations → Add new MCP server を選ぶと、そのファイルが開きます。ツールを使用できるのは、Cursor の Agent チャットからのみです。

   {
     "mcpServers": {
       "oid": {
         "command": "/absolute/path/to/uv",
         "args": ["run", "--directory",
                  "/path/to/OpenImageDebugger/resources/oidmcp",
                  "oid-mcp"]
       }
     }
   }
   

   デスクトップエディターでは、command に絶対パスを使用してください。 Cursor などの GUI IDE はシェルの PATH を引き継がないため、単に "uv" と指定すると起動に失敗することがよくあります。command -v uv の出力を使用してください（Apple Silicon の Homebrew の場合は、たとえば /opt/homebrew/bin/uv）。クライアントが自力で解決できないインタープリターについても同様です。

   環境変数は必要に応じて設定できます（クライアントの env フィールドを使ってサーバーのエントリーに設定し、OID_AGENT_DIR についてはデバッガーにも設定します）。

   変数	デフォルト	用途
   OID_MCP_MAX_BYTES	268435456（256 MiB）	転送前に、このサイズを超えるバッファーを拒否します
   OID_AGENT_DIR	~/.oid-agent/（Windows では %LOCALAPPDATA%\oid-agent）	デバッガーとサーバーで共有する検出用ディレクトリー

   検出用ディレクトリーの場所。 デフォルトのディレクトリーはホームディレクトリーから導出されます（パスワードデータベース経由）。そのため、GUI から起動した oid-mcp とターミナルのデバッガーは、$TMPDIR／$HOME にかかわらず同じパスを解決します。場所を変更するには、両方の環境で OID_AGENT_DIR に同じ絶対パスを設定します（~ は展開されません）。

使用方法

1. エンドポイントを有効にしてデバッガーを起動し、OID を読み込みます。

   OID_AGENT=1 gdb ./your-program
   (gdb) source /path/to/OpenImageDebugger/oid.py
   

   lldb も同じ方法で使用できます。

   OID_AGENT=1 lldb ./your-program
   (lldb) command script import /path/to/OpenImageDebugger/oid.py
   

   （oid.py がすでに ~/.gdbinit／~/.lldbinit にある場合は、環境変数 OID_AGENT=1 を設定してデバッガーを起動するだけです。）

2. ブレークポイントまで実行します。 最初に停止したときにエンドポイントが有効になり、検出用ファイルが公開されます。通常どおり OID ビューアーのウィンドウも開きます。plot には必要ですが、ほかのツールには不要です。

3. エージェントから操作します。 一般的な流れは次のとおりです。

   list_sessions()                       # confirm the server sees your debugger
   list_buffers()                        # what's observable at this stop
   view("frame")                         # look at the whole buffer
   view("frame", region=[100,100,64,64]) # zoom into a suspicious spot
   stats("frame")                        # min/max/mean/std, NaN/Inf/zero counts
   values("frame", x=100, y=100, w=4, h=4)  # exact numbers for a tiny crop
   dump("frame")                         # lossless .npy for offline analysis
   plot("frame")                         # mirror it into the human's viewer
   

   複数のデバッガーが同時に起動している場合は、各ツールで session=<pid> を指定すると対象のデバッガーを選べます。省略した場合は、最後に起動したセッションが選択されます。

ビューアーのセッション

ピクセルツール（view、stats、values、dump、list_buffers）は、デバッガーがなくても使用できます。エージェントエンドポイントを有効にしてビューアーを単独で起動すると、次のようになります。

OID_AGENT=1 oidwindow --open path/to/image.png

デバッガーが接続されていなくても同じエンドポイントが公開されるため、エージェントはユーザーが現在ビューアーで開いているものを調べられます。

デバッガーがビューアーを起動した場合、そのビューアーのセッションには debugger_pid の逆参照が含まれます。そのため、set_view／get_view ではビューアー自身の pid か、そのデバッガーの pid のどちらかを指定してウィンドウを指定できます。（ピクセルツール（view／stats／values／dump／list_buffers）にデバッガーの pid を指定すると、まずデバッガー自身のバッファーを使用し、実行中のデバッガーセッションがない場合にのみビューアーを使用します。）list_sessions() でペア関係を確認できます（下記参照）。

set_view／get_view は常にビューアーを対象とします（ビューアーのないデバッガーには移動できるものがありません）。対象は同じ方法で解決されます。ビューアーの pid、または実行中のビューアーとペアになっているデバッガーの pid を指定します。

ツール

ツール	用途
list_sessions()	{"debuggers": [...], "viewers": [...]} — ライブデバッグセッションとビューワーウィンドウ（すべてのツールで session=<pid> を指定します）。各ビューワーのエントリーには、対応する debugger_pid が表示されます（単独のビューワーの場合は null）
list_buffers()	現在の停止位置（デバッガーまたはビューワーのセッション）で観測可能なバッファーシンボル
view(symbol, region?, channel?, vmin?, vmax?, max_px?)	PNG 形式でレンダリングします。region は状態を保持しないズーム範囲です
stats(symbol, region?)	チャネルごとの最小値／最大値／平均値／標準偏差、NaN／Inf／ゼロの件数
values(symbol, x, y, w, h, channel?)	正確な数値（1 回の呼び出しにつき最大 1024 個）
dump(symbol, path?, overwrite?)	ユーザーごとのダンプディレクトリにロスレスの .npy ダンプを保存します。path はそのディレクトリ内のファイル名です（任意のパスは指定できません）。overwrite=true でない限り、既存のファイルへの上書きは拒否されます
plot(symbol)	人間向けのビューワーウィンドウにミラーリングします
set_view(session?, buffer?, center?, zoom?, rotation_deg?, channel?, auto_contrast?)	ビューワーの表示を絶対値で設定します（冪等です。状態を設定し、少しだけ動かす操作ではありません）。省略したフィールドは現在の値を維持します。channel は 0、1、2、または "all" です。auto_contrast はバッファーごとではなく、ビューワー全体に適用される切り替え設定です
get_view(session?)	ビューワーの現在の buffer／center／zoom／rotation_deg／channel／auto_contrast を読み取ります

注意事項

• エンドポイントは OID_AGENT=1 が設定されている場合にのみ起動し、セッションごとのトークンを使用して localhost にバインドします（検出ファイルは ~/.oid-agent/ に置かれます。OID_AGENT_DIR で変更できます）。これらのファイルを読み取れるローカルプロセスには、デバッグ対象のメモリが公開されます。これはユーザーアカウントと同じ信頼ドメインです。
• バッファーは停止位置ごとに初回アクセス時に全体が転送され、キャッシュされます。上限は OID_MCP_MAX_BYTES（デフォルトでは 256 MiB）です。
• シンボルの評価には、デバッグ対象が停止している必要があります。実行中は、ツールから再試行可能なエラーが返されます。
• ビューワーウィンドウは最初のデバッガー停止時に引き続き開きます（通常の OID の動作です）。plot にはこのウィンドウが必要ですが、ほかのツールには必要ありません。

トラブルシューティング

• no live OID debug session found — サーバーがセッションを認識できません。次の順に確認してください。デバッガーの環境で OID_AGENT=1 が設定されていること、oid.py が実際にソースまたはインポートされていること、デバッグ対象が少なくとも一度はブレークポイントで停止したこと、デバッガーと oid-mcp が同じ検出ディレクトリを使用していること。異なる TMPDIR の値で実行されている場合（macOS でよく見られます。プロセスごとにユーザー専用の一時ディレクトリが割り当てられることがあります）、両方で OID_AGENT_DIR に同じ絶対パスを設定してください。
• Refusing to read OID discovery files from …（stderr）— 検出ディレクトリがシンボリックリンクである、自分が所有していない、またはグループ／全ユーザーからアクセス可能なため、そこにあるトークンを信頼できません。OID_AGENT_DIR に、自分が所有するアクセス制限付きのディレクトリを指定し、モードを 0700 にしてください。
• The debuggee is running — ブレークポイントで一時停止するか、ステップ実行してブレークポイントまで進めてください。シンボルは停止中にのみ評価できます。その後、再試行してください。
• Buffer exceeds the transfer cap — サーバーエントリーで OID_MCP_MAX_BYTES（バイト数）を増やすか、取得する範囲を絞ってください。