DebugMCP (MCP Server) - AIエージェントに運用デバッグ機能を提供

AIエージェントにVS Code内でのコードデバッグを任せましょう - ブレークポイントの設定、ステップ実行、変数の検査、式の評価が可能です。Codex、GitHub Copilot、GitHub Copilot CLI、Cline、Cursor、Windsurf、Roo Code、およびMCP互換のあらゆるアシスタントで動作します。VS Codeがサポートするすべてのコーディング言語に対応しています。

⭐ DebugMCPが役立つと感じたら、GitHubでリポジトリにスターを付けてください! 他の人がこのプロジェクトを見つけやすくなり、継続的な開発の励みになります。

📢 開発者向けのお知らせ: この拡張機能はozzafar@microsoft.comとorbarila@microsoft.comによってメンテナンスされています。この拡張機能の改善にご意見やご貢献をお待ちしています。

🎬 DebugMCPの動作をご覧ください — AIアシスタントが自律的にブレークポイントを設定し、コードをステップ実行し、VS Code内で直接変数を検査します。

✨ 新機能

2.2

• クロスエージェントdebug-liveスキルのインストール — 体系的なデバッグワークフローがAgent Skillとして提供され、標準スキルディレクトリ — ~/.agents/skills/(スキル互換ハーネス(VS Codeエージェントモードを含む)が認識するクロスエージェントの場所)および存在する場合は~/.copilot/skills/ — にインストールされるようになりました。これにより、各エージェントの設定の隣にコピーされて誰もスキャンしないという問題が解消され、どこからでも検出可能になりました(#105を修正。VS Codeがスキルを読み込まない問題)。サーバーはMCP instructionsもアドバタイズし、start_debuggingツールは完全なワークフローのためにスキルを参照します。

• 実行中プログラムの一時停止 — 新しいpause_executionツールは、自由に実行中のプログラムを中断し、ブレークポイントが設定されていなくても現在の位置で停止します(ビジーループや組み込み/ベアメタルターゲットに最適)。その後、状態を検査したり、そこからステップ実行したりできます。

• VS Code Testing APIによる堅牢なデバッグ — testNameを指定したstart_debuggingは、VS Code Testing APIを使用してテストを検出・起動し、言語テストランナー(pytest、Jest/Vitest、Java、.NET、Goなど)全体で個々のテストケース内のブレークポイントヒットを一貫して生成します。

Related MCP server: MCP Server for VS Code

🚀 クイックインストール

VS Code Marketplaceからインストール または直接リンクを使用: vscode:extension/ozzafar.debugmcpextension

目次

• 概要

• 機能

• インストール

• クイックスタート

• 対応AIアシスタント

• 対応言語

• 設定

• FAQ

• トラブルシューティング

• 仕組み

• 貢献

• ライセンス

概要

DebugMCPは、AIコーディングエージェントにVS Codeデバッガーの完全な制御を提供するMCPサーバーです。ログを読んだり推測したりする代わりに、AIアシスタントは人間の開発者と同じように、自律的にブレークポイントを設定し、デバッグセッションを起動し、コードを1行ずつステップ実行し、変数の値を検査し、式を評価できます。100%ローカルで動作し、設定は不要で、MCP互換のあらゆるAIアシスタントですぐに使用できます。

機能

🔧 ツール

注: MCPサーバーはデバッガー操作のためのツールを公開し、手続き的な ワークフローガイダンス(いつデバッグするか、根本原因調査をどう構成するか、 言語固有の癖)は付属のAgent Skillにあります。 ツールの説明は簡潔で行動指向に保たれています。拡張機能はdebug-liveスキルを 標準スキルディレクトリ(~/.agents/skills/、および存在する場合は~/.copilot/skills/)に インストールするため、スキル互換ハーネスはオンデマンドで完全なワークフローを読み込みます。サーバーはまた、 デバッグ前にエージェントをそこに向けるMCP instructionsもアドバタイズします。

🎯 デバッグのベストプラクティス

DebugMCPは、効果的な問題解決のための体系的なデバッグ手法に従います:

• エントリポイントから始める: 関数のエントリポイントまたはメインの実行パスからデバッグを開始

• 実行フローに従う: ステップバイステップの実行でコードの流れを理解

• 根本原因分析: 症状で止まらない - 根本的な原因を見つける

🛡️ セキュリティと信頼性

• 安全な通信: すべてのMCP通信は安全なプロトコルを使用

• ローカル操作: MCPサーバーは100%ローカルで動作し、外部通信はなく、認証情報も不要

• 状態検証: デバッグ状態と操作の堅牢な検証

インストール

クイックインストールオプション

オプション1: 直接リンク(最速)

• このリンクをクリック: vscode:extension/ozzafar.debugmcpextension

• またはブラウザにコピー＆ペースト: vscode:extension/ozzafar.debugmcpextension

オプション2: VS Code Marketplace

• アクセス: https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension

• 「インストール」をクリック

オプション3: VS Code内から

1. VSCodeを開く

2. 拡張機能に移動(Ctrl+Shift+X / Cmd+Shift+X)

3. 「DebugMCP」を検索

4. インストールをクリック

5. 拡張機能が自動的にアクティブ化され、MCPサーバーとして登録されます

検証

インストール後、以下が表示されるはずです:

• インストール済み拡張機能にDebugMCP拡張機能

• ポート3001で自動的に実行されるMCPサーバー(設定可能)

• 接続されたAIアシスタントが利用可能なデバッグツール

📝 注: 追加のデバッグルールの指示は不要です - 拡張機能はそのまま動作します。

💡 ヒント: AIアシスタントでdebugmcpツールの自動承認を有効にすると、承認の中断なしにシームレスなデバッグワークフローを実現できます。

クイックスタート

1. 拡張機能をインストール(インストールを参照)

2. VSCodeでプロジェクトを開く

3. AIにデバッグを依頼 - ブレークポイントの設定、デバッグの開始、コードの分析が可能になります!

対応AIアシスタント

DebugMCPはMCP互換のあらゆるAIアシスタントで動作します。自動検出して、以下への登録を提案します:

対応言語

DebugMCPは、それぞれ対応するVSCode拡張機能を使用して、以下の言語のデバッグをサポートしています:

設定

MCPサーバー設定（推奨）

この拡張機能はMCPサーバーを自動的に実行します。AIアシスタントにMCPサーバーを自動登録するためのメッセージが表示されます。

コマンドパレットから手動で登録をトリガーすることもできます:

• DebugMCP: Show Agent Selection Popup

手動MCPサーバー登録（任意）

🔄 自動移行: 以前にSSEトランスポートでDebugMCPを設定していた場合、拡張機能はアクティベーション時に設定を新しいStreamable HTTPトランスポートへ自動的に移行します。

Cline

Clineの設定またはcline_mcp_settings.jsonに追加します:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - AI-powered debugging assistant"
    }
  }
}

GitHub Copilot

VS Codeの設定（settings.json）に追加します:

{
  "mcp": {
    "servers": {
      "debugmcp": {
        "type": "http",
        "url": "http://localhost:3001/mcp",
        "description": "DebugMCP - Multi-language debugging support"
      }
    }
  }
}

GitHub Copilot CLI

~/.copilot/mcp-config.jsonに追加します（COPILOT_HOMEが設定されている場合は${COPILOT_HOME}/mcp-config.json）:

{
  "mcpServers": {
    "debugmcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
      "tools": ["*"]
    }
  }
}

Cursor

CursorのMCP設定に追加します:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Codex

DebugMCPをCodexに登録します:

codex mcp add debugmcp --url http://localhost:3001/mcp

または、同等の設定を~/.codex/config.tomlに追加します（CODEX_HOMEが設定されている場合は${CODEX_HOME}/config.toml）:

[mcp_servers.debugmcp]
url = "http://localhost:3001/mcp"

Windsurf

WindsurfのMCP設定（~/.windsurf/mcp_settings.jsonまたはワークスペースの.windsurf/mcp_settings.json）に追加します:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Roo Code

Roo CodeのMCP設定に追加します:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Antigravity

AntigravityのMCP設定に追加します:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

拡張機能の設定

VSCodeの設定でDebugMCPの動作を構成します:

{
  "debugmcp.serverPort": 3001,
  "debugmcp.timeoutInSeconds": 180,
  "debugmcp.bindHost": ["127.0.0.1", "::1"]
}

セキュリティモデル

DebugMCPは、認証なしのローカルHTTPエンドポイント上で強力なデバッガプリミティブ（evaluate_expression、start_debuggingなど）を公開します。この面を安全に保つため、サーバーは4つの制御を強制します:

1. ループバックのみにバインド。 HTTPサーバーはデフォルトでIPv4およびIPv6のループバックアドレス（127.0.0.1と::1）にバインドするため、ネットワーク上の他のホストはhttp://<your-ip>:3001/mcpに到達できません。両方のアドレスファミリにバインドすることで、localhostをどちらのファミリに解決するクライアントでも接続が成功します。debugmcp.bindHost設定（文字列または文字列の配列）を使用すると、別のインターフェースを選択できます（たとえば、リモートコンテナにポートを転送する場合）。ただし、これを行うと、認証なしのデバッガがそのアドレスにルーティングできるすべてのものに公開されます。信頼できないネットワーク上で0.0.0.0やLANアドレスに向けないでください。

2. Host / Originヘッダーの検証。 すべてのリクエストは、ループバックアドレス（localhost、127.0.0.1、または[::1]）を指定するHostヘッダーを保持している必要があります。Host内のポート接尾辞もサーバーのリッスンポートと一致する必要があります。他のHostを持つリクエスト（悪意のあるWebページからのDNSリバインディングを経由して到着するものを含む）は、HTTP 403で拒否されます。Originヘッダーが存在する場合も同じループバックチェックが適用されます。

3. 最小権限の変数検査。 get_variables_valuesは明示的なvariableNamesリスト（最大50、ワイルドカードなし）を必要とし、それらの変数のみを返します。以前はスコープ内のすべての変数をダンプしていましたが、これはエージェントに要求していない無関係なプロセス状態を渡していました。何が存在するかを調べるにはlist_variable_namesを使用してください。このツールは名前と型のみを返し、値を読み取ることはありません。

4. 変数検査時のシークレットの編集。 資格情報を含む名前または既知の資格情報の形状に一致する値を持つ値は、応答が拡張機能を離れる前に<redacted: possible secret>に置き換えられます。evaluate_expressionが返す評価結果も対象です。get_variables_valuesまたはevaluate_expressionが複雑な値を展開する場合、子要素は名前と型のみでリストされます。その値が必要な場合は、正確な子要素パスを指定してevaluate_expressionを使用してください。再帰的な展開は、応答ごとに合計100の子フィールドに制限されます。Nullに近い値（None、undefined、''）は決して編集されないため、「トークンが空です」というバグはデバッグ可能なままです。編集は常に有効で、オフにすることはできません。

FAQ

DebugMCPは、GitHub Copilot、GitHub Copilot CLI、Cline、Cursor、Codex、Windsurf、Roo Code、Antigravityなど、MCP互換の任意のAIアシスタントで動作します。アシスタントがModel Context Protocolをサポートしていれば、DebugMCPを使用できます。

はい。DebugMCPはextensionKind: workspaceのVS Code拡張機能として実行されるため、コードが存在するリモート環境でアクティブになります。MCPサーバーはそのリモートコンテキスト内のlocalhostで実行されます。

いいえ。DebugMCPはファイルの言語/拡張子に基づいて適切なデバッグ設定を自動的に生成します。launch.jsonがある場合は、最も関連性の高い設定を自動的に選択します。

いいえ。DebugMCPは100%ローカルで実行されます。MCPサーバーはlocalhostで実行され、コード、変数、デバッグデータが外部サービスに送信されることはありません。AIアシスタントはMCPサーバーと完全にローカルマシン内で通信します。

VS Codeの設定でポートを変更してください: "debugmcp.serverPort": 3002（または利用可能な任意のポート）。次に、AIアシスタントのMCP設定を新しいポートを使用するように更新します。

はい。start_debuggingにtestNameパラメータを渡すと、特定のテストメソッドをデバッグできます。DebugMCPは、そのテスト内のブレークポイントで実行して一時停止するようにデバッグセッションを設定します。

DebugMCPがAIアシスタントのMCP設定に登録されていることを確認してください。拡張機能は自動的に検出して自己登録を提案するはずです。そうでない場合は、手動MCPサーバー登録セクションを参照してください。また、よりスムーズなワークフローのために、DebugMCPツールの自動承認を有効にしてください。

はい。DebugMCPは、ASP.NETアプリケーションを含むC#/.NETデバッグ用に.csファイルと.csprojプロジェクトファイルをサポートしています。

トラブルシューティング

一般的な問題

MCPサーバーが起動しない

• 症状: AIアシスタントがDebugMCPに接続できない

• 解決策:

  • ポート3001が利用可能か確認する

  • VSCodeを再起動する

  • 拡張機能がインストールされ、アクティブ化されていることを確認する

デバッグセッションがブレークポイントで停止しない

• 症状: ブレークポイントが設定されているが、実行が一時停止しない

• 解決策:

  • 正しいファイルがデバッグされていることを確認する

  • ブレークポイントの行番号が正しいことを確認する

  • 関連する言語のデバッガ拡張機能がインストールされていることを確認する

デバッグ停止時に別のVS Codeウィンドウがフォーカスを取得する

• 症状: 複数のVS Codeウィンドウが開いている場合、ブレークポイントにヒットするかステップが完了すると、デバッグ中のウィンドウがフォアグラウンドに表示される

• 解決策: ユーザー設定またはワークスペース設定で、VS Codeのネイティブのブレーク時フォーカス動作を無効にします:

  {
    "debug.focusWindowOnBreak": false,
    "debug.focusEditorOnBreak": false
  }

  debug.focusWindowOnBreakは、デバッグ中のウィンドウがオペレーティングシステムのフォーカスを取得するのを防ぎます。オプションのdebug.focusEditorOnBreak設定は、VS Codeが停止したソースエディタにフォーカスを移動するのも防ぎます。DebugMCPはこれらの永続的な設定を自動的に変更しません。

設定が自動検出されない

• 症状: 拡張機能がAIアシスタントへの登録を促さない

• 解決策:

  • コマンドパレットから DebugMCP: Show Agent Selection Popup を実行する (Ctrl+Shift+P / Cmd+Shift+P)

  • 手動で構成を追加する (手動MCPサーバー登録 を参照)

動作の仕組み

アーキテクチャ

AI Agent (Copilot/Cline/Cursor/Codex) → MCP/Streamable HTTP → DebugMCPServer → DebuggingHandler → VS Code Debug API

起動構成の統合

この拡張機能はデバッグ構成をインテリジェントに処理します:

• 既存の launch.json: .vscode/launch.json ファイルが存在する場合、次のことを行います:

  • 関連する構成を検索する

  • エージェントが明示的に指定した configurationName を尊重する

  • JSONC (コメントと末尾のカンマを含むJSON) をサポートする

• デフォルト構成: configurationName が省略されている場合、または一致する名前付き構成が見つからない場合、ファイル拡張子の検出に基づいて各言語に適切なデフォルト構成を作成します。

要件

• 適切な言語拡張機能がインストールされたVSCode:

  • Python: .py ファイル用の Python extension

  • JavaScript/TypeScript: 組み込みのNode.jsデバッガーまたは JavaScript Debugger extension

  • Java: Extension Pack for Java

  • C#/.NET: C# extension

  • C/C++: C/C++ extension

  • Go: Go extension

  • Rust: rust-analyzer extension

  • PHP: PHP Debug extension

  • Ruby: デバッグサポート付きの Ruby extension

• MCP互換のAIアシスタント (Copilot、Cline、Cursor、Codex、Windsurf、Roo Code など)

開発

拡張機能をビルドするには:

npm install
npm run compile

リンティングを実行するには:

npm run lint

テストを実行するには:

npm test

貢献

このプロジェクトでは、貢献と提案を歓迎します。ほとんどの貢献には、あなたの貢献を使用する権利を私たちに与える権利があることを宣言し、実際に与えることに同意するContributor License Agreement (CLA) への同意が必要です。詳細については、https://cla.opensource.microsoft.com をご覧ください。

プルリクエストを送信すると、CLAボットが自動的にCLAの提供が必要かどうかを判断し、PRを適切に装飾します (例: ステータスチェック、コメント)。ボットから提供される指示に従ってください。この作業は、当社のCLAを使用するすべてのリポジトリで一度だけ行う必要があります。

このプロジェクトは、Microsoft Open Source Code of Conduct を採用しています。詳細については、Code of Conduct FAQ を参照するか、追加の質問やコメントは opencode@microsoft.com までお問い合わせください。

セキュリティ

セキュリティの脆弱性は、https://aka.ms/SECURITY.md のガイダンスに従って報告してください。公開のGitHub issuesを通じてセキュリティの脆弱性を報告しないでください。

商標

このプロジェクトには、プロジェクト、製品、またはサービスの商標またはロゴが含まれる場合があります。Microsoftの商標またはロゴの承認された使用は、Microsoft's Trademark & Brand Guidelines に従う必要があります。このプロジェクトの修正版でのMicrosoftの商標またはロゴの使用は、混乱を引き起こしたり、Microsoftの後援を示唆したりしてはなりません。第三者の商標またはロゴの使用は、それらの第三者のポリシーに従うものとします。

⭐ DebugMCPをサポート

DebugMCPがより速くデバッグするのに役立ったなら、GitHubでスターを付けることを検討してください！スターはプロジェクトの認知度を高め、貢献者を引き付けるのに役立ちます。

⭐ GitHubでDebugMCPにスターを付ける

スター履歴

ライセンス

MITライセンス - 詳細は LICENSE を参照してください

この拡張機能は Oz Zafar、Ori Bar-Ilan、Karin Brisker によって作成されました。