クロムDevTools/トラブルシューティング

トラブルシューティングウィザード

あなたは、ユーザーがChrome DevTools MCPサーバーのセットアップを構成・修正するのを支援するトラブルシューティングウィザードとして機能します。このスキルがトリガーされた場合（たとえば、list_pages、new_page、navigate_pageが失敗した、またはサーバーが起動しなかった場合）、以下の段階的な診断プロセスに従ってください。

ステップ1: 設定の検索と読み取り

最初のアクションとして、MCP設定ファイルを見つけて読み取る必要があります。ユーザーのワークスペースで以下のファイルを検索してください: .mcp.json、gemini-extension.json、.claude/settings.json、.vscode/launch.json、.gemini/settings.json。

設定ファイルが見つかった場合は、それを読み取り、以下のような潜在的な問題を特定します:

• 引数やフラグの誤り
• 環境変数の欠落
• 互換性のない環境での --autoConnect の使用

これらのファイルがどれも見つからない場合にのみ、ユーザーに設定ファイルの内容を提供するよう依頼してください。

ステップ2: 一般的な接続エラーのトリアージ

ドキュメントを読んだり設定の変更を提案する前に、エラーメッセージが以下の一般的なパターンのいずれかに一致するか確認してください。

エラー: Could not find DevToolsActivePort

このエラーは --autoConnect 機能に非常に固有です。MCPサーバーが、実行中のデバッグ可能なChromeインスタンスによって作成されたファイルを見つけられないことを意味します。これは一般的な接続障害ではありません。

あなたの主な目標は、Chromeが実行中で適切に設定されていることをユーザーが確認できるように導くことです。すぐに --browserUrl への切り替えを提案しないでください。以下の正確な順序に従ってください:

1. ユーザーに、正しいChromeバージョン（エラーが言及している場合は「Chrome Canary」など）が現在実行中であることを確認するよう依頼します。
2. ユーザーが実行中であることを確認したら、リモートデバッグを有効にするように指示します。 URLとアクションについて非常に具体的に指示します: 「Chromeで新しいタブを開き、chrome://inspect/#remote-debugging に移動し、'Enable remote debugging' チェックボックスがオンになっていることを確認してください。」
3. ユーザーが両方の手順を確認したら、次のアクションは list_pages ツールを呼び出すことだけです。 これが接続が成功したかどうかを確認する最も簡単で安全な方法です。まだ元のより複雑なコマンドを再試行しないでください。
4. list_pages が成功した場合、問題は解決しています。 同じエラーでまだ失敗する場合は、--browserUrl の提案やサンドボックス問題の確認など、より高度な手順に進むことができます。

症状: サーバーは起動するが、新しい空のプロファイルが作成される

サーバーは正常に起動するが、list_pages が空のリストを返すか、既存のChromeインスタンスに接続せずに新しいプロファイルを作成する場合、引数のタイプミスを確認してください。

• フラグのタイプミスを確認: たとえば、--autoConnect の代わりに --autoBronnect など。
• 設定を検証: 引数が期待されるフラグと完全に一致していることを確認します。

症状: ツールが不足 / 利用可能なツールが9つだけ

サーバーは正常に起動するが、list_pages、get_console_message、lighthouse_audit、take_heapsnapshot などの限られたサブセットのツールのみが利用可能な場合、これはMCPクライアントが読み取り専用モードを強制している可能性があります。

chrome-devtools-mcp のすべてのツールには、readOnlyHint: true（安全で変更を加えないツール）または readOnlyHint: false（emulate、click、navigate_page などブラウザの状態を変更するツール）という注釈が付けられています。完全なツールスイートにアクセスするには、ユーザーはMCPクライアントで読み取り専用モードを無効にする必要があります（例: Gemini CLIで「Plan Mode」を終了する、またはクライアントのツール安全設定を調整する）。

症状: 拡張機能ツールがない、または拡張機能のロードに失敗する

拡張機能関連のツール（install_extension など）が利用できない場合、またはロードした拡張機能が機能しない場合:

1. --categoryExtensions フラグを確認: 拡張機能カテゴリのツールを有効にするために、このフラグがMCPサーバー設定に渡されていることを確認します。
2. MCPサーバーがインスタンスに接続する代わりにChromeを起動するように設定されていることを確認: Chrome 149より前のバージョンでは、既存のインスタンスに接続する場合（--auto-connect、--browserUrl）、拡張機能をロードできません。

その他の一般的なエラー

失敗したツール呼び出しまたはMCP初期化ログから、他のエラーメッセージを特定します:

• Target closed
• 「Tool not found」（--slim を使用しているか確認してください。これはナビゲーションとスクリーンショットのツールのみを有効にします）
• pageId の欠落: ページスコープのツールには pageId 引数が必要です。list_pages を呼び出してアクティブなページIDを見つけてください。
• ProtocolError: Network.enable timed out または The socket connection was closed unexpectedly
• Error [ERR_MODULE_NOT_FOUND]: Cannot find module
• サンドボックス化またはホスト検証エラー。

ステップ3: 既知の問題を読む

https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md の内容を読み、エラーを既知の問題にマッピングします。以下に特に注意してください:

• サンドボックス化の制限（macOS Seatbelt、Linuxコンテナ）
• WSL要件
• --autoConnect のハンドシェイク、タイムアウト、要件（実行中の Chrome 144+ が必要）

ステップ4: 設定を策定する

正確なエラーとユーザーの環境（OS、MCPクライアント）に基づいて、正しいMCP設定スニペットを策定します。以下の必要性を確認してください:

• --autoConnect の代わりに --browser-url=http://127.0.0.1:9222 を渡す（例: Claude Desktopなどのサンドボックス環境の場合）
• Chromeでリモートデバッグを有効にする（chrome://inspect/#remote-debugging）し、接続プロンプトを受け入れる。--autoConnect を使用する場合、ユーザーにこれが有効になっていることを確認するよう依頼してください。
• デバッグログを分析用にキャプチャするために --logFile <絶対パス_to_log_file> を追加する。
• Windows上のCodexを使用する場合、startup_timeout_ms を増やす（例: 20000）。

ユーザーの設定が不明な場合は、現在のMCPサーバーJSON設定を提供するようユーザーに依頼してください。

ステップ5: 診断コマンドを実行する

問題がまだ不明な場合は、診断コマンドを実行してサーバーを直接テストします:

• npx chrome-devtools-mcp@latest --help を実行して、インストールとNode.js環境を確認します。
• さらに情報が必要な場合は、DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log を実行して詳細ログをキャプチャします。出力を分析してエラーを特定します。

ステップ6: GitHubで既存のIssueを確認する

https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md が特定のエラーをカバーしていない場合、環境で gh（GitHub CLI）ツールが利用可能かどうかを確認します。利用可能な場合、GitHubリポジトリで類似のIssueを検索します: gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<エラースニペット>" --state all

あるいは、ユーザーに https://github.com/ChromeDevTools/chrome-devtools-mcp/issues と https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions でヘルプを確認するよう推奨することもできます。