mcp-debugger

MCP ACS Debugger Server

🔗 リポジトリ

このパッケージは現在、専用のリポジトリで保守されています：https://github.com/Digital-Defiance/mcp-debugger-server

このリポジトリは、GitHub の AI Capabilitites Suite の一部です。

Chrome DevTools Protocol を介して、Node.js および JavaScript アプリケーション向けの包括的なデバッグ機能を提供する、エンタープライズグレードの Model Context Protocol（MCP）サーバーです。このサーバーにより、AI エージェント（Kiro、Amazon Q、GitHub Copilot）は、基本的なブレークポイント管理から高度な CPU／メモリプロファイリングやハング検出まで、25 種類以上の専用ツールを使って Node.js コードを対話形式でデバッグできます。Python、Java、Go など複数言語のデバッグには、Debug Adapter Protocol を活用する VS Code 拡張機能をご利用ください。

🎯 主な機能

コアデバッグ機能

• Node.js／JavaScript のサポート：Chrome DevTools Protocol を介して、Node.js アプリケーションと JavaScript コードをデバッグします
• TypeScript のサポート：ソースマップ解決に対応した、完全な TypeScript デバッグ機能
• ブレークポイント管理：条件、ヒット数、ログポイントを任意で指定して、ブレークポイントの設定、削除、切り替え、一覧表示を行います
• 実行制御：実行を継続、ステップオーバー、ステップイン、ステップアウト、一時停止し、正確に制御します
• 変数の検査：ローカル変数とグローバル変数の検査、式の評価、変更検出による変数の監視を行います
• コールスタックのナビゲーション：コンテキストを切り替えながら、コールスタックのフレームを表示、移動します

高度な機能

• ハング検出：設定可能なタイムアウトとサンプリング間隔で、無限ループやハングしたプロセスを検出します
• ソースマップのサポート：元のソース位置を示しながら、TypeScript とトランスパイル済み JavaScript をデバッグするための完全なソースマップサポート
• パフォーマンスプロファイリング：CPU プロファイリング、メモリプロファイリング、ヒープスナップショット、パフォーマンスタイムラインの追跡
• テストフレームワークとの統合：Jest、Mocha、Vitest のテストをデバッグします
• セッション管理：完全に分離された複数のデバッグセッションを同時にサポートします
• Chrome DevTools Protocol：低レベルのデバッグのため、Node.js Inspector Protocol と直接統合します

エンタープライズ機能

• 可観測性：構造化ログ、メトリクス収集、ヘルスチェックエンドポイント、Prometheus メトリクスのエクスポート
• セキュリティ：認証、レート制限、機密データのマスキング、監査ログ、セッションタイムアウトの適用
• 本番環境対応：サーキットブレーカー、指数バックオフによるリトライ処理、グレースフルシャットダウン、リソース制限
• モニタリング：パフォーマンスメトリクス、セッション記録、包括的なエラー追跡

📦 インストール

システム要件

• Node.js：>= 18.0.0
• NPM：>= 8.0.0
• オペレーティングシステム：macOS、Linux、Windows
• CPU アーキテクチャ：x64、arm64

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

# Install globally
npm install -g @ai-capabilities-suite/mcp-debugger-server

# Verify installation
ts-mcp-server --version

その他のインストール方法

NPX を使用する（インストール不要）

# Run directly without installing
npx @ai-capabilities-suite/mcp-debugger-server

Docker を使用する

# Pull and run the Docker image
docker pull digitaldefiance/mcp-debugger-server:latest
docker run -d --name mcp-debugger digitaldefiance/mcp-debugger-server:latest

# Or use docker-compose (see DOCKER-DEPLOYMENT.md)
docker-compose up -d

ソースからインストールする

# Clone the repository
git clone https://github.com/digital-defiance/ai-capabilities-suite.git
cd ai-capabilities-suite

# Install dependencies
npm install

# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server

# Run the server
node packages/mcp-debugger-server/dist/src/cli.js

⚙️ 設定

Kiro の設定

.kiro/settings/mcp.json に追加します：

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": [],
      "env": {
        "NODE_ENV": "production"
      },
      "disabled": false,
      "autoApprove": [
        "debugger_start",
        "debugger_set_breakpoint",
        "debugger_continue",
        "debugger_step_over",
        "debugger_inspect",
        "debugger_get_stack"
      ]
    }
  }
}

Claude Desktop の設定

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

VS Code の設定

.vscode/settings.json に追加します。

{
  "mcp.servers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": [],
      "enabled": true
    }
  }
}

環境変数

高度な設定用のオプションの環境変数です。

# Enable debug logging
DEBUG=mcp:*

# Set custom timeout (milliseconds)
MCP_DEBUGGER_TIMEOUT=60000

# Enable authentication
MCP_DEBUGGER_AUTH_TOKEN=your-secret-token

# Enable rate limiting
MCP_DEBUGGER_RATE_LIMIT=100

# Enable audit logging
MCP_DEBUGGER_AUDIT_LOG=true

🛠️ 利用可能なツール

MCP ACS Debugger Server は、8 つのカテゴリに分類された 25 個の専用ツールを提供します。

セッション管理

1. debugger_start

Node.js プロセスで新しいデバッグセッションを開始します。

パラメーター：

• command（string、必須）：実行するコマンド（例：「node」、「npm」）
• args（string[]、任意）：コマンドの引数（例：["test.js"]）
• cwd（string、任意）：プロセスの作業ディレクトリ
• timeout（number、任意）：タイムアウト時間（ミリ秒、デフォルト：30000）

例：

{
  "command": "node",
  "args": ["app.js"],
  "cwd": "/path/to/project",
  "timeout": 30000
}

レスポンス：

{
  "status": "success",
  "sessionId": "session-123",
  "state": "paused",
  "pid": 12345
}

2. debugger_stop_session

デバッグセッションを停止し、すべてのリソースをクリーンアップします。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

例：

{
  "sessionId": "session-123"
}

ブレークポイント管理

3. debugger_set_breakpoint

指定したファイルと行番号にブレークポイントを設定します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID
• file（string、必須）：ファイルパス（絶対パスまたは相対パス）
• line（number、必須）：行番号（1 始まり）
• condition（string、任意）：条件式（例：「x > 10」）

例：

{
  "sessionId": "session-123",
  "file": "/path/to/file.js",
  "line": 42,
  "condition": "count > 5"
}

4. debugger_remove_breakpoint

セッションからブレークポイントを削除します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID
• breakpointId（string、必須）：削除するブレークポイント ID

5. debugger_toggle_breakpoint

ブレークポイントの有効状態と無効状態を切り替えます。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID
• breakpointId（string、必須）：切り替えるブレークポイント ID

6. debugger_list_breakpoints

デバッグセッションのすべてのブレークポイントを取得します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

レスポンス：

{
  "status": "success",
  "breakpoints": [
    {
      "id": "bp-1",
      "file": "/path/to/file.js",
      "line": 42,
      "condition": "x > 10",
      "enabled": true,
      "verified": true
    }
  ]
}

実行制御

7. debugger_continue

次のブレークポイントまたはプログラムの終了まで実行を再開します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

8. debugger_step_over

現在の行を実行し、同じスコープ内の次の行で一時停止します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

9. debugger_step_into

現在の行を実行し、呼び出された関数のいずれかの先頭行で一時停止します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

10. debugger_step_out

現在の関数が戻るまで実行し、呼び出し元の位置で一時停止します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

11. debugger_pause

実行中のデバッグセッションを一時停止します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

変数の調査

12. debugger_inspect

現在の実行コンテキストで JavaScript 式を評価します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID
• expression（string、必須）：評価する JavaScript 式

例：

{
  "sessionId": "session-123",
  "expression": "user.name + ' ' + user.age"
}

13. debugger_get_local_variables

現在のスコープ内のすべてのローカル変数を取得します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

14. debugger_get_global_variables

現在のスコープからアクセスできるグローバル変数を取得します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID

15. debugger_inspect_object

ネストした解決を行いながら、オブジェクトのプロパティを調査します。

パラメーター：

• sessionId（string、必須）：デバッグセッション ID
• objectId（string、必須）：以前の調査で取得したオブジェクト ID
• maxDepth（number、任意）：たどる最大の深さ（デフォルト：2）

変数の監視

16. debugger_add_watch

式をウォッチリストに追加します。

パラメーター：

• sessionId (string, 必須)：デバッグセッション ID
• expression (string, 必須)：ウォッチする式

17. debugger_remove_watch

式をウォッチリストから削除します。

パラメーター：

• sessionId (string, 必須)：デバッグセッション ID
• watchId (string, 必須)：削除するウォッチ ID（式）

18. debugger_get_watches

ウォッチ中のすべての式と現在の値を取得します。

パラメーター：

• sessionId (string, 必須)：デバッグセッション ID

コールスタック

19. debugger_get_stack

関数名とファイルの場所を含む、現在のコールスタックを取得します。

パラメーター：

• sessionId (string, 必須)：デバッグセッション ID

レスポンス：

{
  "status": "success",
  "stack": [
    {
      "function": "myFunction",
      "file": "/absolute/path/to/file.js",
      "line": 42,
      "column": 10
    }
  ]
}

20. debugger_switch_stack_frame

実行コンテキストを特定のスタックフレームに切り替えます。

パラメーター：

• sessionId (string, 必須)：デバッグセッション ID
• frameIndex (number, 必須)：フレームのインデックス（0 = 最上位フレーム）

ハング検出

21. debugger_detect_hang

プロセスがハングしているか、無限ループに入っているかを検出します。

パラメーター：

• command (string, 必須)：実行するコマンド
• args (string[], 任意)：コマンド引数
• cwd (string, 任意)：作業ディレクトリ
• timeout (number, 必須)：タイムアウト時間（ミリ秒）
• sampleInterval (number, 任意)：ループ検出のサンプル間隔（デフォルト：100ms）

例：

{
  "command": "node",
  "args": ["script.js"],
  "timeout": 5000,
  "sampleInterval": 100
}

レスポンス（ハング時）：

{
  "status": "success",
  "hung": true,
  "location": "/path/to/file.js:42",
  "stack": [...],
  "message": "Process hung at /path/to/file.js:42",
  "duration": 5000
}

レスポンス（完了時）：

{
  "status": "success",
  "hung": false,
  "completed": true,
  "exitCode": 0,
  "duration": 1234
}

🚀 クイックスタートガイド

1. サーバーをインストールする

npm install -g @ai-capabilities-suite/mcp-debugger-server

2. AI エージェントを設定する

MCP 設定ファイル（例：.kiro/settings/mcp.json）に追加します。

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

3. デバッグを開始する

AI エージェントにコードのデバッグを依頼します。

"Debug my Node.js script app.js and set a breakpoint at line 42"

AI エージェントは MCP ACS Debugger Server を使用して、次の操作を行います。

1. デバッグセッションを開始する
2. ブレークポイントを設定する
3. コードを実行する
4. ブレークポイントで一時停止する
5. 変数を調べ、問題の修正を支援する

📚 よくあるデバッグのシナリオ

シナリオ 1：シンプルなスクリプトをデバッグする

// 1. Start a debug session
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["my-script.js"]
  }
}
// Returns: { sessionId: "session-123", state: "paused" }

// 2. Set a breakpoint
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/my-script.js",
    "line": 10
  }
}

// 3. Continue execution
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. When paused at breakpoint, inspect variables
{
  "tool": "debugger_get_local_variables",
  "args": {
    "sessionId": "session-123"
  }
}

// 5. Step through code
{
  "tool": "debugger_step_over",
  "args": {
    "sessionId": "session-123"
  }
}

// 6. Stop the session
{
  "tool": "debugger_stop_session",
  "args": {
    "sessionId": "session-123"
  }
}

シナリオ 2：失敗するテストをデバッグする

// 1. Start debugging a Jest test
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"],
    "timeout": 60000
  }
}

// 2. Set breakpoint in test file
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/my-test.spec.js",
    "line": 25
  }
}

// 3. Continue to breakpoint
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. Inspect test variables
{
  "tool": "debugger_inspect",
  "args": {
    "sessionId": "session-123",
    "expression": "expect.getState()"
  }
}

シナリオ 3：無限ループを検出する

// Use hang detection to identify infinite loops
{
  "tool": "debugger_detect_hang",
  "args": {
    "command": "node",
    "args": ["potentially-hanging-script.js"],
    "timeout": 5000,
    "sampleInterval": 100
  }
}
// Returns hang location and stack trace if hung

シナリオ 4：TypeScript コードをデバッグする

// TypeScript debugging works automatically with source maps
// 1. Ensure your tsconfig.json has "sourceMap": true

// 2. Start debugging the compiled JavaScript
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["--enable-source-maps", "dist/app.js"]
  }
}

// 3. Set breakpoints using TypeScript file paths
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/src/app.ts",  // TypeScript source file
    "line": 42
  }
}
// The debugger automatically maps to the compiled JavaScript location

シナリオ 5：変数の変更をウォッチする

// 1. Start session and set breakpoint
// ... (as in Scenario 1)

// 2. Add watched variables
{
  "tool": "debugger_add_watch",
  "args": {
    "sessionId": "session-123",
    "expression": "user.balance"
  }
}

// 3. Continue execution
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. Check watched variables at each pause
{
  "tool": "debugger_get_watches",
  "args": {
    "sessionId": "session-123"
  }
}
// Returns: { watches: [{ watchId: "user.balance", value: 100, changed: true, oldValue: 50, newValue: 100 }] }

🎬 デモとスクリーンショット

デバッグの動作

Node.js アプリケーションでブレークポイントを設定し、変数を調べる

無限ループを検出して診断する

ソースマップに対応した TypeScript コードのデバッグ

注：プレースホルダー画像を、デバッガーの動作を示す実際のスクリーンショットまたはアニメーション GIF に置き換えてください。ガイドラインについては、images/README.md を参照してください。

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

よくある問題と解決方法

問題：「Session not found」

症状：セッション ID を使用しようとするとエラーが発生する 原因：セッション ID が無効であるか、セッションが終了している 解決方法：

# Start a new debug session
{
  "tool": "debugger_start",
  "arguments": {
    "command": "node",
    "args": ["your-script.js"]
  }
}

問題：「Process must be paused」

症状：変数を調べたり、式を評価したりできない 原因：プロセスの実行中に変数を調べようとしている 解決方法：

• ブレークポイントを設定し、そこまで実行する、または
• debugger_pause を使用して、すぐに実行を一時停止する

問題：ブレークポイントで停止しない

症状：ブレークポイントで実行が停止しない 原因：ブレークポイントの位置が無効であるか、コードパスが実行されていない 解決方法：

1. ファイルパスが正しいことを確認します（絶対パスを使用してください）。

   "file": "/absolute/path/to/your/file.js"  // ✅ Good
   "file": "file.js"                          // ❌ Avoid
   

2. 行番号に実行可能なコードがあることを確認します（コメントや空行ではないこと）。

3. ブレークポイントが設定され、検証済みであることを確認します。

   {
     "tool": "debugger_list_breakpoints",
     "arguments": { "sessionId": "your-session-id" }
   }
   

問題：ハング検出の誤検知

症状：スクリプトが正常に実行されているのに、ハングが検出されます 原因：タイムアウトがスクリプトの通常の実行時間に対して短すぎます 解決策：

{
  "tool": "debugger_detect_hang",
  "arguments": {
    "command": "node",
    "args": ["script.js"],
    "timeout": 60000,  // Increase timeout to 60 seconds
    "sampleInterval": 200  // Increase sample interval
  }
}

問題：TypeScript のブレークポイントが機能しない

症状：.ts ファイル内のブレークポイントで実行が一時停止しません 原因：ソースマップが有効になっていないか、見つかりません 解決策：

1. tsconfig.json で "sourceMap": true に設定します：

   {
     "compilerOptions": {
       "sourceMap": true
     }
   }
   

2. Node.js の起動時に --enable-source-maps フラグを使用します：

   node --enable-source-maps dist/app.js
   

3. コンパイル済み JavaScript と同じ場所に .map ファイルがあることを確認します：

   ls dist/*.js.map
   

問題：「Cannot find module」エラー

症状：サーバーの起動時にモジュールが見つからないというエラーが発生します 原因：パッケージがビルドされていないか、依存関係がインストールされていません 解決策：

# Install dependencies
npm install

# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server

# Or if installed globally, reinstall
npm install -g @ai-capabilities-suite/mcp-debugger-server

問題：WebSocket 接続エラー

症状：「Failed to connect to inspector」または WebSocket エラーが発生します 原因：Inspector Protocol の起動に失敗しました 解決策：

1. Node.js のバージョンが 18 以上であることを確認します：

   node --version  # Should be >= 18.0.0
   

2. 他のデバッガーがプロセスに接続されていないことを確認します

3. プロセスが正常に起動することを確認します：

   node --inspect-brk your-script.js
   # Should output: Debugger listening on ws://...
   

問題：メモリ使用量が多い

症状：サーバーが過剰なメモリを消費します 原因：同時セッション数が多すぎるか、ヒープスナップショットが大きすぎます 解決策：

1. 同時セッション数を制限します

2. 使用していないセッションを停止します：

   {
     "tool": "debugger_stop_session",
     "arguments": { "sessionId": "session-id" }
   }
   

3. リソース制限を設定します（「環境変数」セクションを参照）

問題：パフォーマンスが遅い

症状：デバッグ操作が遅くなります 原因：オブジェクトが大きい、検査が深い、またはブレークポイントが多すぎます 解決策：

1. オブジェクトの検査の深さを制限します：

   {
     "tool": "debugger_inspect_object",
     "arguments": {
       "sessionId": "session-id",
       "objectId": "obj-id",
       "maxDepth": 2  // Limit depth
     }
   }
   

2. 条件付きブレークポイントを使用して一時停止を減らします

3. 不要なブレークポイントを削除します

サポートを受ける

ここに記載されていない問題が発生した場合：

1. ログを確認する：DEBUG=mcp:* を使用してデバッグログを有効にします
2. 既存の問題を検索する：GitHub の Issues
3. 新しい Issue を作成する：以下を含めてください：
   • Node.js のバージョン（node --version）
   • サーバーのバージョン（ts-mcp-server --version）
   • エラーメッセージとスタックトレース
   • 再現手順
4. サポートにメールする：[email protected]

💡 使用例

1. AI 支援デバッグ

AI エージェントが自律的にコードをデバッグできるようにします：

• Kiro：「失敗しているテストをデバッグして、失敗する理由を教えて」
• Amazon Q：「スクリプト内の無限ループを見つけて」
• GitHub Copilot：「ブレークポイントを設定して、user オブジェクトを調べて」

2. 自動テストと CI/CD

デバッグを CI/CD パイプラインに統合します：

• 失敗したテストを自動的にデバッグする
• パフォーマンスのリグレッションを検出する
• デプロイ前にメモリリークを特定する

3. 本番環境の問題調査

本番環境に近い環境を安全にデバッグします：

• 本番環境の問題をローカルで再現する
• コードを変更せずに状態を調べる
• パフォーマンスのボトルネックを分析する

4. 学習と教育

開発者がデバッグ手法を学べるよう支援します：

• コードの実行をステップ実行する
• コールスタックとスコープを理解する
• 変数の変更を視覚化する

5. パフォーマンス最適化

パフォーマンスの問題を特定して解決します：

• CPU 使用率をプロファイルする
• メモリ割り当てを分析する
• メモリリークを検出する
• パフォーマンス指標を追跡する

📊 機能比較

機能	MCP ACS Debugger Server	VS Code Debugger	Chrome DevTools	Node Inspector
AI エージェント連携	✅ MCP を完全サポート	❌ なし	❌ なし	❌ なし
ブレークポイント	✅ 高度な機能（条件付き、ヒット数、ログポイント）	✅ あり	✅ あり	✅ 基本
変数の検査	✅ 型情報を含む詳細な検査	✅ あり	✅ あり	✅ 基本
TypeScript サポート	✅ ソースマップを完全サポート	✅ あり	✅ あり	⚠️ 限定的
ハング検出	✅ サンプリングによる自動検出	❌ なし	❌ なし	❌ なし
CPU プロファイリング	✅ あり	✅ あり	✅ あり	❌ なし
メモリプロファイリング	✅ リーク検出機能付き	✅ あり	✅ あり	❌ なし
複数セッション	✅ 分離された並行セッション	⚠️ 限定的	⚠️ 限定的	❌ なし
テストフレームワーク連携	✅ Jest、Mocha、Vitest	✅ あり	❌ なし	❌ なし
リモートデバッグ	✅ MCP プロトコル経由	✅ あり	✅ あり	✅ あり
監査ログ	✅ エンタープライズ水準	❌ なし	❌ なし	❌ なし
レート制限	✅ あり	❌ なし	❌ なし	❌ なし
メトリクスのエクスポート	✅ Prometheus	❌ なし	❌ なし	❌ なし

📋 エラーコード

サーバーは、次のコードを含む構造化されたエラーレスポンスを返します。

エラーコード	説明	主な原因	解決策
SESSION_NOT_FOUND	セッション ID が存在しません	無効な ID、または終了したセッション	新しいセッションを開始します
SESSION_START_FAILED	デバッグセッションの開始に失敗しました	無効なコマンド、または権限の不足	コマンドとファイルパスを確認します
BREAKPOINT_SET_FAILED	ブレークポイントの設定に失敗しました	無効なファイルパス、または行番号	絶対パスと有効な行番号を使用します
BREAKPOINT_NOT_FOUND	ブレークポイントが存在しません	無効なブレークポイント ID	ブレークポイント一覧で ID を確認します
CONTINUE_FAILED	実行の再開に失敗しました	プロセスがクラッシュ、または終了しました	プロセスの状態を確認します
STEP_OVER_FAILED	ステップオーバーに失敗しました	一時停止されていない、または無効な状態	プロセスが一時停止中であることを確認します
STEP_INTO_FAILED	ステップインに失敗しました	一時停止されていない、または関数呼び出しがない	関数呼び出し箇所であることを確認します
STEP_OUT_FAILED	ステップアウトに失敗しました	関数内にいません	呼び出しスタックを確認します
PAUSE_FAILED	実行の一時停止に失敗しました	プロセスが実行されていません	プロセスが実行中であることを確認します
INSPECT_FAILED	式の評価に失敗しました	無効な式、または一時停止されていません	構文と一時停止状態を確認します
GET_STACK_FAILED	呼び出しスタックの取得に失敗しました	一時停止されていません	まず実行を一時停止します
NOT_PAUSED	この操作には一時停止状態が必要です	プロセスが実行中です	一時停止するか、ブレークポイントを設定します
HANG_DETECTION_FAILED	ハングの検出に失敗しました	無効なパラメーター	タイムアウトと間隔を確認します
WATCH_NOT_FOUND	ウォッチ式が存在しません	無効なウォッチ ID	ウォッチ一覧で ID を確認します
RATE_LIMIT_EXCEEDED	リクエストが多すぎます	レート制限を超過しました	待ってから再試行します
AUTH_FAILED	認証に失敗しました	無効なトークン	認証トークンを確認します

テスト

単体テストの実行

npx nx test @ai-capabilities-suite/mcp-core
npx nx test @ai-capabilities-suite/mcp-server

E2E テストの実行

npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e --testTimeout=60000

手動テスト

node packages/mcp-server/test-mcp-manual.js

包括的なテストのドキュメントについては、TESTING.md を参照してください。

🏗️ アーキテクチャ

技術スタック

MCP ACS Debugger Server は、エンタープライズグレードのテクノロジーを基盤として構築されています。

• MCP SDK：AI エージェントとの通信を実現する Model Context Protocol の実装
• Chrome DevTools Protocol (CDP)：低レベルのデバッグを行う Node.js Inspector Protocol
• WebSocket：Node.js Inspector とのリアルタイム双方向通信
• TypeScript：完全な型定義を備えた、型安全な実装
• Zod：ツールパラメーターのランタイム型検証
• Prometheus：メトリクスの収集とエクスポート

コンポーネントアーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                        AI Agent Layer                        │
│  (Kiro, Amazon Q, GitHub Copilot, Claude Desktop)          │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio/JSON-RPC)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   MCP ACS Debugger Server                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Session    │  │  Breakpoint  │  │   Variable   │     │
│  │   Manager    │  │   Manager    │  │  Inspector   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Hang     │  │     CPU      │  │    Memory    │     │
│  │   Detector   │  │   Profiler   │  │   Profiler   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Source     │  │    Audit     │  │    Metrics   │     │
│  │  Map Manager │  │    Logger    │  │  Collector   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │ Inspector Protocol (CDP/WebSocket)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Node.js Inspector                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Debugger   │  │   Runtime    │  │   Profiler   │     │
│  │    Domain    │  │    Domain    │  │    Domain    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Target Node.js Process                     │
│              (Application, Test Runner, etc.)                │
└─────────────────────────────────────────────────────────────┘

データフロー

1. AI エージェントのリクエスト：エージェントが stdio 経由で MCP ツールのリクエストを送信します
2. ツールの検証：サーバーが Zod スキーマを使用してパラメーターを検証します
3. セッション管理：サーバーがデバッグセッションを作成または取得します
4. CDP 通信：サーバーが WebSocket 経由で CDP コマンドを送信します
5. Inspector の応答：Node.js Inspector がデバッグデータを返します
6. データ処理：サーバーが応答を処理して整形します
7. MCP の応答：サーバーが構造化された JSON 応答をエージェントに返します

セキュリティアーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                      Security Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Auth     │  │     Rate     │  │     Data     │     │
│  │   Manager    │  │   Limiter    │  │    Masker    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Session    │  │    Audit     │  │   Circuit    │     │
│  │   Timeout    │  │    Logger    │  │   Breaker    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

⚡ パフォーマンス

ベンチマーク

MacBook Pro（M1、16GB RAM）でのパフォーマンス指標：

操作	平均レイテンシー	スループット	備考
セッション開始	150ms	6.6/sec	プロセスの起動を含みます
ブレークポイントの設定	5ms	200/sec	単一のブレークポイント
実行の継続	2ms	500/sec	次のブレークポイントまで再開
ステップオーバー	8ms	125/sec	単一ステップ操作
変数の検査	12ms	83/sec	ローカル変数のみ
式の評価	15ms	66/sec	単純な式
コールスタックの取得	10ms	100/sec	完全なスタックトレース
ハング検出	5000ms	0.2/sec	5s のタイムアウト時
CPU プロファイルの開始	3ms	333/sec	プロファイリングの開始
CPU プロファイルの停止	50ms	20/sec	分析を含みます
ヒープスナップショット	200ms	5/sec	10MB のヒープ

リソース使用量

一般的なリソース消費量：

• メモリ：ベースで 50-100MB ＋ アクティブなセッションごとに 10-20MB
• CPU：アイドル時 < 1%、デバッグ中 5-10%
• ネットワーク：最小限（ローカル WebSocket のみ）
• ディスク：ログとメトリクス用に < 1MB

スケーラビリティ

• 同時セッション数：100 以上の同時セッションでテスト済み
• ブレークポイント：セッションごとに 1000 以上のブレークポイントをサポート
• セッション時間：24 時間以上のセッションでテスト済み
• メモリの安定性：48 時間の連続負荷テストでメモリリークは検出されていません

コントリビューション

コントリビューションを歓迎します！以下のガイドラインに従ってください：

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. テストを追加して変更を加えます
4. テストスイートを実行します
5. プルリクエストを送信します

NPM への公開

メンテナーとして更新を公開する場合：

• クイックセットアップ：NPM-SETUP-GUIDE.md - 初回セットアップを 5 分で行えます
• 完全ガイド：PUBLISHING.md - 公開に関する包括的なドキュメント
• 自動化：GitHub Actions のワークフローがリリース時の公開を処理します

ドキュメント

• README.md - このファイル、メインドキュメント
• API.md - 詳細な API ドキュメント
• TOOL-REFERENCE.md - ツールの完全なリファレンス
• AI-AGENT-INTEGRATION.md - AI エージェントの統合ガイド
• VSCODE-INTEGRATION.md - VS Code の統合ガイド
• TESTING.md - テストに関するドキュメント
• PUBLISHING.md - NPM 公開ガイド
• NPM-SETUP-GUIDE.md - 公開者向けクイックセットアップ

🙏 謝辞

このプロジェクトは、優れたオープンソース技術を基盤としています：

• Model Context Protocol - プロトコル仕様と SDK
• Chrome DevTools Protocol - デバッグプロトコル
• Node.js Inspector - Node.js デバッグ API
• TypeScript - 型安全な JavaScript
• Zod - 実行時の型検証

特に感謝します：

• フィードバックやコントリビューションを寄せてくださった MCP コミュニティ
• このプロジェクトの改善に協力してくださったすべてのコントリビューター
• 問題の報告や改善の提案をしてくださるユーザーの皆さま

📜 ライセンス

MIT License - 詳細はLICENSEファイルをご覧ください。

Copyright (c) 2024 Digital Defiance

本ソフトウェアおよび関連ドキュメントファイル（以下「本ソフトウェア」）の複製を取得するすべての人に対し、無償で、本ソフトウェアを制限なく取り扱う許可をここに付与します。これには、本ソフトウェアを使用、複製、変更、結合、公開、配布、サブライセンス、販売する権利、および本ソフトウェアの提供を受けた人にこれらを許可する権利が含まれますが、これらに限定されません。ただし、以下の条件に従うものとします。

上記の著作権表示および本許諾表示は、本ソフトウェアのすべての複製または実質的な部分に含めるものとします。

本ソフトウェアは「現状有姿」で提供され、明示的か黙示的かを問わず、商品性、特定目的への適合性、および権利非侵害の保証を含むがこれらに限定されない、いかなる保証も伴いません。作者または著作権者は、契約、不法行為、その他いかなる行為であるかを問わず、本ソフトウェアまたはその使用、その他の取引に起因または関連して生じる請求、損害、その他の責任について、一切責任を負いません。

🔗 リンク

• ホームページ：https://digitaldefiance.org
• GitHub：https://github.com/digital-defiance/ai-capabilities-suite
• NPM：https://www.npmjs.com/package/@ai-capabilities-suite/mcp-debugger-server
• Docker Hub：https://hub.docker.com/r/digitaldefiance/mcp-debugger-server
• ドキュメント：https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger-server
• 課題：https://github.com/digital-defiance/ai-capabilities-suite/issues
• ディスカッション：https://github.com/digital-defiance/ai-capabilities-suite/discussions

---

❓ よくある質問（FAQ）

一般的な質問

Q：Model Context Protocol（MCP）とは何ですか？ A：MCP は、AI エージェントが外部のツールやサービスとやり取りできるようにするプロトコルです。MCP ACS Debugger Server は MCP を実装し、AI エージェントにデバッグ機能を提供します。

Q：どの AI エージェントに対応していますか？ A：このサーバーは、以下を含む、MCP 互換のあらゆる AI エージェントで動作します。

• Kiro
• Amazon Q
• GitHub Copilot
• Claude Desktop
• カスタム MCP クライアント

Q：本番環境のデバッグに使用できますか？ A：はい！このサーバーには、本番環境での使用を想定した、認証、レート制限、監査ログ、サーキットブレーカーなどのエンタープライズ機能が含まれています。ただし、必ず最初にステージング環境でテストしてください。

Q：無料で使用できますか？ A：はい。MCP ACS Debugger Server は MIT ライセンスのオープンソースで、個人利用・商用利用のどちらも無料です。

技術に関する質問

Q: 対応している Node.js のバージョンは何ですか？ A: Node.js >= 18.0.0 が必要です。最新の LTS バージョンの使用をおすすめします。

Q: TypeScript で動作しますか？ A: はい！ソースマップを含め、TypeScript を完全にサポートしています。.ts ファイルにブレークポイントを設定し、元の TypeScript の名前で変数を調べることができます。

Q: リモートプロセスをデバッグできますか？ A: サーバーは Inspector Protocol を介してローカルの Node.js プロセスに接続します。リモートデバッグには、SSH トンネリングを使用するか、リモートマシン上にサーバーをデプロイしてください。

Q: 同時にいくつのデバッグセッションを実行できますか？ A: サーバーは 100 件以上の同時セッションをサポートしています。各セッションは分離されており、ほかのセッションに影響しません。

Q: Docker コンテナで動作しますか？ A: はい！公式の Docker イメージを提供しています。詳細は DOCKER-DEPLOYMENT.md をご覧ください。

デバッグに関する質問

Q: ブレークポイントで停止しないのはなぜですか？ A: よくある原因は次のとおりです。

1. ファイルパスが絶対パスではなく相対パスになっている
2. 指定した行に実行可能なコードがない
3. そのコードパスが実行されていない
4. ソースマップがない（TypeScript の場合）

Q: 特定のテストをデバッグするにはどうすればよいですか？ A: テストランナーを使ってデバッグセッションを開始してください。

{
  "tool": "debugger_start",
  "arguments": {
    "command": "node",
    "args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"]
  }
}

Q: 非同期コードをデバッグできますか？ A: はい！デバッガーは async/await、Promise、コールバックを完全にサポートしています。非同期関数にブレークポイントを設定し、通常どおりステップ実行できます。

Q: メモリーリークを検出するにはどうすればよいですか？ A: メモリープロファイリングツールを使用してください。

1. 開始時にヒープスナップショットを取得します
2. コードを実行します
3. もう一度ヒープスナップショットを取得します
4. スナップショットを比較し、増加しているオブジェクトを特定します

パフォーマンスに関する質問

Q: デバッグするとアプリケーションの動作は遅くなりますか？ A: はい。デバッグによるオーバーヘッドが発生します。デバッグ中は 2～5 倍遅くなることが予想されます。影響を最小限に抑えるには、条件付きブレークポイントを使用し、不要なブレークポイントを無効にしてください。

Q: サーバーはどのくらいのメモリーを使用しますか？ A: 基本のメモリー使用量は 50～100MB で、これにアクティブなデバッグセッションごとに 10～20MB が加わります。

Q: CI/CD パイプラインで使用できますか？ A: はい！サーバーは自動化向けに設計されています。CI/CD パイプラインでハング検出とテストのデバッグを使用して、問題を早期に発見してください。

セキュリティに関する質問

Q: 本番環境で安全に使用できますか？ A: サーバーにはエンタープライズ向けのセキュリティ機能（認証、レート制限、監査ログ）が含まれていますが、本番環境でのデバッグは慎重に、必要な場合に限って行ってください。

Q: 機密データはどのように保護されますか？ A: サーバーには、一般的なパターン（メールアドレス、SSN、クレジットカード）に対する PII の自動マスキング機能が含まれています。必要に応じて追加のマスキングルールを設定してください。

Q: 許可する操作を制限できますか？ A: はい！認証を使用し、ユーザーまたはトークンごとに許可する操作を設定してください。詳細はドキュメントの「Security」セクションをご覧ください。

統合に関する質問

Q: VS Code と統合するにはどうすればよいですか？ A: 統合手順の詳細は VSCODE-INTEGRATION.md をご覧ください。

Q: GitHub Copilot と一緒に使用できますか？ A: はい！GitHub Copilot は MCP サーバーを使用できます。Copilot の設定でサーバーを構成してください。

Q: Mocha/Jest/Vitest で動作しますか？ A: はい！サーバーには主要なテストフレームワークすべてに対するサポートが組み込まれています。テストランナーのコマンドを使ってデバッグセッションを開始するだけです。

💬 サポートとコミュニティ

ヘルプを利用する

• 📖 ドキュメント：完全なドキュメント
• 🐛 バグ報告：GitHub Issues
• 💡 機能リクエスト：GitHub Discussions
• 📧 メールサポート：[email protected]
• 💬 コミュニティチャット：Discord に参加 (近日公開)

リソース

• NPM Package: @ai-capabilities-suite/mcp-debugger-server
• Docker Hub: digitaldefiance/mcp-debugger-server
• GitHub Repository: ai-capabilities-suite
• API Documentation: API.md
• Tool Reference: TOOL-REFERENCE.md

コントリビューション

コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.mdをご覧ください。

スポンサー

プロジェクトをご支援ください：

• GitHub Sponsors: Digital Defiance をスポンサーする
• Open Collective: プロジェクトを支援する (近日公開)

📝 変更履歴

Version 1.0.4（現行）

リリース日：2025年12月

新機能：

• 包括的な例を追加し、ドキュメントを拡充
• エラーメッセージとトラブルシューティングガイドを改善
• パフォーマンスベンチマークとメトリクスを追加
• セキュリティ機能のドキュメントを拡充

バグ修正：

• WebSocket 接続の安定性に関する問題を修正
• 特殊なケースでのソースマップ解決を改善
• 長時間実行されるセッションでのメモリーリークを修正

パフォーマンス：

• セッションの起動時間を20％短縮
• 大きなオブジェクトの変数検査を最適化
• CPU プロファイリングの精度を改善

Version 1.0.2

リリース日：2024年11月

新機能：

• 公式イメージによる Docker サポートを追加
• Prometheus メトリクスのエクスポートを実装
• ヘルスチェックエンドポイントを追加
• 構造化形式による監査ログを強化

改善点：

• CDP プロトコルエラーのエラー処理を改善
• TypeScript ソースマップのサポートを改善
• セッションの分離を強化

Version 1.0.1

リリース日：2024年11月

新機能：

• CPU プロファイリングのサポートを追加
• メモリープロファイリングとヒープスナップショットを追加
• パフォーマンスのタイムライン追跡を実装
• 高度なブレークポイントの種類（ログポイント、ヒット回数）を追加

改善点：

• ハング検出アルゴリズムを強化
• 変数検査のパフォーマンスを改善
• 非同期コードの処理を改善

Version 1.0.0

リリース日：2024年10月

初回リリース：

• 包括的なデバッグツール25個
• ソースマップによる TypeScript の完全サポート
• サンプリングを設定可能なハング検出
• 分離された複数の同時セッション
• テストフレームワークとの統合（Jest、Mocha、Vitest）
• 変更検出機能付きの変数監視
• コールスタックのナビゲーション
• 条件付きブレークポイント
• ネストされた解決に対応したオブジェクト検査
• エンタープライズ向けセキュリティ機能
• 可観測性とモニタリング

🗺️ ロードマップ

Version 1.1.0（予定 - 2025年第1四半期）

• タイムトラベルデバッグ（記録と再生）
• AI を活用したスマートなブレークポイントの提案
• VS Code 拡張機能の強化
• WebAssembly のデバッグサポート
• 分散トレーシングとの統合

Version 1.2.0（予定 - 2025年第2四半期）

• ブラウザーのデバッグサポート（Chrome、Firefox）
• モバイルデバッグ（React Native）
• 共同デバッグセッション
• 高度な可視化ツール
• カスタムツール用のプラグインシステム

Version 2.0.0（予定 - 2025年第3四半期）

• マルチ言語サポート（Python、Go、Rust）
• クラウドネイティブなデバッグ
• Kubernetes との統合
• AI を活用した高度なデバッグ支援
• リアルタイムの共同作業機能

ロードマップに影響を与えたいですか？ アイデアを共有する