auto-chrome-mcp-doctor

auto-chrome-mcp doctor

이 스킬은 사용자가 auto-chrome-mcp (hangwin/mcp-chrome fork) 의 MCP 서버, 확장, bridge, 또는 도구 호출과 관련된 문제를 보고할 때 자동으로 진단·복구합니다.

모든 명령은 Bash tool 로 직접 실행하고 stdout/stderr 를 캡처해서 해석한 뒤 사용자에게 자연어로 답변하세요. "이 명령어를 직접 쳐주세요" 라고 사용자에게 넘기지 마세요.

먼저 auto-chrome-mcp-bridge -V 로 auto-chrome-mcp fork 인지 확인하세요. 명령이 없거나 다른 패키지 (mcp-chrome-bridge 등) 면 이 스킬은 종료하고 사용자에게 fork 안내만 합니다.

---

(A) Architecture in 1 minute

사용자 증상 듣고 어느 layer 가 깨졌는지 분류용 mental model:

Claude Code session                              ← 사용자가 작업하는 곳
   ↓ (stdio, .mcp.json 의 env 가 여기서 적용)
mcp-server-stdio.js                              ← bridge npm 패키지의 일부
   ↓ (HTTP fetch, URL = CHROME_PORT env override)
http://127.0.0.1:<port>/mcp                      ← bridge HTTP listener (chrome profile 별 분리)
   ↓ (in-process)
bridge (Native Messaging Host process)           ← Chrome 이 connectNative 로 spawn
   ↑ (chrome.runtime.connectNative)
extension service worker                         ← profile-scoped (각 chrome profile 마다 1개)
   ↑ (popup ↔ service worker, chrome.runtime.sendMessage)
popup UI                                         ← port 입력, 강제포커스 토글, 강제 재연결

핵심 invariant:

• stdio-config.json 의 url 은 hardcoded 이고, mcp-server-stdio.js 가 process.env.CHROME_PORT 가 있으면 그 port 로 override (v1.0.27+)
• chrome profile 별로 bridge process 가 분리 spawn 됨 (각자 다른 port listen)
• popup 의 port 입력 → service worker → connectNative → bridge 가 그 port 로 listen
• 강제포커스 토글 (chrome.storage.local 의 forceFocusOnToolCall, default false) = chrome.windows.update({focused:true}) 게이트

---

(B) Diagnostic playbook — 증상 → 명령 (Claude 가 직접 실행)

중요: 모든 명령은 Bash tool 로 Claude 가 직접 실행. 사용자에게 "이거 한 번 쳐보세요" 하지 마세요. stdout/stderr 캡처해서 해석한 뒤 자연어로 답합니다.

분기 알고리즘

1. 증상 listening → 아래 trigger 표에서 최초 매칭 1개 골라 1st command 실행.
2. stdout 캡처 → doctor 결과면 (B-doctor-output) 표 따라 ❌ 항목별 후속 결정.
3. 후속 명령 실행 후 사용자에게 결과 요약 ('doctor 결과 권한 항목 빨간불. --fix 실행해서 chmod 755 적용함. 이제 popup 다시 열어봐줄래?' 같이).
4. 3회 시도 후 미해결 → (E) escalate → report --copy + GH Issue URL 안내.