문제 해결 마법사
당신은 사용자가 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로 전환을 제안하지 마세요. 다음 정확한 순서를 따르세요:
- 사용자에게 올바른 Chrome 버전(예: 오류에서 언급된 경우 "Chrome Canary")이 현재 실행 중인지 확인하도록 요청하세요.
- 사용자가 실행 중임을 확인하면 원격 디버깅을 활성화하도록 지시하세요. URL과 작업에 대해 매우 구체적으로 설명하세요: "Chrome에서 새 탭을 열고
chrome://inspect/#remote-debugging으로 이동한 후 'Enable remote debugging' 확인란이 선택되어 있는지 확인하세요." - 사용자가 두 단계를 모두 확인하면 유일한 다음 작업은
list_pages도구를 호출하는 것입니다. 이것이 연결이 성공했는지 확인하는 가장 간단하고 안전한 방법입니다. 아직 원래의 더 복잡한 명령을 다시 시도하지 마세요. 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)를 사용할 수 없거나 로드한 확장 프로그램이 작동하지 않는 경우:
--categoryExtensions플래그 확인: 확장 프로그램 카테고리 도구를 활성화하려면 MCP 서버 설정에 이 플래그가 전달되었는지 확인하세요.- 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 unexpectedlyError [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 <절대_경로_로그_파일>추가. - 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에서 기존 문제 확인
https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md 에서 특정 오류를 다루지 않는 경우, 환경에 gh(GitHub CLI) 도구를 사용할 수 있는지 확인하세요. 사용 가능한 경우 GitHub 저장소에서 유사한 문제를 검색하세요:
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 에서 도움을 확인하도록 권장할 수 있습니다.