devtools-MCP CDP-first 재설계 — CDP passthrough whitelist + tool surface 축소

[DaveDev42]

배경

현재 MCP tool surface는 13개:

• read-only: `list_pages`, `list_console_messages`, `list_network_requests`, `get_dom_document`, `take_snapshot`, `take_screenshot`, `measure_safe_area`, `AIT_getOperationalEnvironment`, `AIT_getMockState`, `AIT_getSdkCallHistory`
• side-effect: `call_sdk`, `evaluate`, `build_attach_url`

대부분은 CDP method를 1:1 wrapping한 syntactic sugar. 예시:

• `evaluate` = `Runtime.evaluate` wrap
• `take_screenshot` = `Page.captureScreenshot` wrap
• `take_snapshot` = `DOMSnapshot.captureSnapshot` wrap
• `get_dom_document` = `DOM.getDocument` wrap
• `call_sdk` = `Runtime.evaluate("window.__sdk.X(...)")` wrap

이 sugar들은:

• agent 학습 비용 (한 시점에 13개 → 점점 늘어남)
• 유지 보수 비용 (CDP 시그니처 변경 시 우리도 갱신)
• 일관성 비용 (어떤 건 sugar, 어떤 건 raw가 가능 → 어디까지 sugar로 만들지 자의적)

대안: CDP를 raw passthrough로 노출하고, AIT 환경 특화 helper만 별도 유지. agent는 Chrome DevTools Protocol docs(표준)를 직접 학습 가능.

설계

A — `cdp_send(method, params)` raw passthrough + whitelist

미니앱 환경에서 유효한 CDP domain만 허용:

domain	유효	비고
`Runtime.*`	✅	evaluate, callFunctionOn, console
`DOM.`, `CSS.`, `DOMSnapshot.*`	✅
`Network.`, `Log.`, `Performance.*`	✅
`Page.*`	△	captureScreenshot/navigate/reload만. bringToFront 등 desktop은 거부
`Storage.`, `IndexedDB.`, `CacheStorage.*`	✅
`Profiler.`, `HeapProfiler.`, `Debugger.*`	△	iOS WebKit-CDP bridge(Chii) 지원 여부 확인 후
`Input.*`	△	iOS WebKit dispatchTouchEvent 지원 확인 후
`Memory.`, `Security.`, `Animation.*`	△	빈도 낮음, 검토 후
`Target.`, `Browser.`, `Tethering.*`	❌	multi-target/window 데스크톱 전용
`Emulation.*`	❌	실기기에서 무의미

화이트리스트 외 method 호출 → 명시 에러 + "이 domain은 미니앱 환경에서 유효하지 않습니다" 안내.

B — AIT helper 정말 필요한 것만

current	결정	이유
`build_attach_url`	유지	relay 진입 — CDP에 없음
`list_pages`	유지	Chii relay listTargets — `Target.getTargets`와 의미 다름
`measure_safe_area`	유지	다단 probe 패키지 (cssEnv + sdk + dom + viewport + dpr + UA)
`list_console_messages`	유지 (buffer)	CDP stream → buffer query — 다른 형태 없음
`list_network_requests`	유지 (buffer)	동상
`AIT_getMockState`	유지 (env 1 marker)	mock 환경 메모리 — raw CDP로 못 가져옴
`AIT_getSdkCallHistory`	유지 (env 1 marker)	동상
`call_sdk`	deprecate	`cdp_send("Runtime.evaluate", {expression: "window.__sdk.X(...)"})` 동등
`evaluate`	deprecate	`cdp_send("Runtime.evaluate", ...)` 동등
`take_screenshot`	deprecate	`cdp_send("Page.captureScreenshot", ...)` 동등
`take_snapshot`	deprecate	`cdp_send("DOMSnapshot.captureSnapshot", ...)` 동등
`get_dom_document`	deprecate	`cdp_send("DOM.getDocument", ...)` 동등
`AIT_getOperationalEnvironment`	deprecate	`cdp_send("Runtime.evaluate", {expression: "window.__sdk.getOperationalEnvironment()"})` 동등

최종 tool 8개: `cdp_send` + `build_attach_url` + `list_pages` + `measure_safe_area` + `list_console_messages` + `list_network_requests` + `AIT_getMockState` + `AIT_getSdkCallHistory`.

13 → 8 (38% 감소). 그리고 `cdp_send`는 CDP 전체를 노출하므로 실제 능력은 ↑.

마이그레이션

• 점진 deprecate: 한 번에 다 빼지 말고, 1.0.0까지는 deprecated tool도 작동하되 description에 "deprecated, use cdp_send instead" 명시.
• 1.0.0 시점에 모두 제거.
• agent-plugin / agent 사용 패턴 점검 — sdk-example skill, devtools panel skill 등이 어디까지 deprecated tool에 의존하는지 grep.

SECRET-HANDLING

• `cdp_send`의 params는 raw passthrough — caller가 attach URL/at= 코드를 expression에 넣으면 그대로 evaluate됨. tool description에 "params에 secret 노출 금지" 명시.
• whitelist 위반 시 method/domain은 에러 메시지에 노출 가능 (secret 아님).

acceptance

• `cdp_send(method, params)` MCP tool 추가, whitelist domain만 허용.
• 화이트리스트 명세 문서화 (`docs/cdp-passthrough.md` 또는 README).
• 위 13개 중 deprecate 6개를 description에 표기 (1.0.0에서 제거 예고).
• 단위 테스트: whitelist 통과 + 거부 + 1:1 passthrough.
• agent-plugin `/ait debug` skill 갱신 — 새 `cdp_send` 사용 패턴 안내.
• 1.0.0 시점에 deprecated 6개 제거.

Out of scope

• CDP event streaming을 MCP에서 SSE로 노출 — 별도 dashboard(MCP debug dashboard: tunnel URL 자동 갱신 + 연결 상태 라이브 (Phase 1) #247/MCP debug dashboard: mini DevTools UI (Chii client 같은 origin mount, Phase 2) #248)가 다룸.
• iOS WebKit-CDP bridge(Chii)의 method 지원 매트릭스 — 별도 audit.
• Chrome DevTools UI를 dashboard에 mount — MCP debug dashboard: mini DevTools UI (Chii client 같은 origin mount, Phase 2) #248.

관련

• build_attach_url: HTML 통합 강화 + 일본어 응답 라인 제거 #244 (HTTP 서버 기반)
• MCP debug dashboard: tunnel URL 자동 갱신 + 연결 상태 라이브 (Phase 1) #247 (Phase 1 dashboard)
• MCP debug dashboard: mini DevTools UI (Chii client 같은 origin mount, Phase 2) #248 (Phase 2 mini DevTools UI)
• hotfix: CDP sendCommand이 page 끊김/타임아웃 시 영원히 hang (timeout + detach reject 필요) #252 (hotfix — CDP sendCommand timeout — 이 재설계와 무관, 별도 진행)

[DaveDev42]

처분 권고: adopt-hybrid (구현 보류 — 사용자 결정 대기)

코드를 직접 확인한 결과(chii-connection.ts:500, server.ts:314-322), #253의 방향성은 옳지만 원안 그대로(13→8, 6개 deprecate)는 채택할 수 없다. tool마다 두께가 달라 "6개 동등 대체" 주장이 균일하게 참이 아니기 때문이다. 두께별로 분기한 하이브리드가 정답이다.

이 코멘트는 권고이며 구현이 아니다. surface 정본 변경 + 보안 경계 재배선(LIVE guard 이동)을 포함하는 큰 트레이드오프라, 한쪽을 자율 구현하지 않고 방향 결정을 기다린다.

코드로 확정된 사실 3가지

1. transport는 이미 raw passthrough다. ChiiCdpConnection.sendCommand가 method를 whitelist 없이 그대로 wire에 write한다(ws.send(JSON.stringify({id, method, params})), chii-connection.ts:500). AIT.*가 동작하는 이유도 이 완전 passthrough다. → cdp_send는 새 능력이 아니라 기존 transport 능력의 정직한 노출이다.
2. mock 서버엔 CDP 채널이 없다. evaluate·take_screenshot·get_dom_document·take_snapshot은 이미 CDP_ONLY_TOOL_NAMES(server.ts:314-322)에 들어 dev-mode에서 거부된다. #277의 13-tool "평행"은 raw CDP 대칭이 아니라 의미 shim(buildDevCallSdk, measure_safe_area provenance 라벨)으로 성립한다.
3. THICK tool은 wire wrapper가 아니라 도메인 로직이다. call_sdk의 시그니처 검증(fix(mcp): call_sdk 인자 시그니처 검증 — setDeviceOrientation 호출이 토스 앱 crash 가능성 #264 실기기 crash 방지)·recentException triage·sdk-absent 분기(feat(mcp): --target=local 세션의 AIT.* 브리지 — sdk-example dev-bridge 랜딩 #360)·JSON envelope(fix(mcp): --mode=dev call_sdk(getOperationalEnvironment) value shape — scalar로 정정 (docs↔code) #343), evaluate의 LIVE guard는 raw로 재현 불가. AIT.*는 비표준 도메인이라 표준 CDP whitelist로는 원리적 도달 불가.

권고 처분

deprecate는 THIN 3개만 (wire-identical 코드로 확정):

• take_snapshot → cdp_send('DOMSnapshot.captureSnapshot', {})
• take_screenshot → cdp_send('Page.captureScreenshot', {format:'png'})
• get_dom_document → cdp_send('DOM.getDocument', {depth:-1, pierce:true})

즉시 제거가 아니라 0.1.x 동안 descriptor 마킹 + envelope meta{deprecated, replacement} + 동작 유지, 코드 제거는 1.0.0 컷.

named 유지(deprecate 금지): call_sdk·evaluate(THICK), AIT.getOperationalEnvironment·getMockState·getSdkCallHistory(비표준 도메인), measure_safe_area·list_*·build_attach_url. → 결과 surface ≈ 10~11개(원안 8 아님).

cdp_send(신규, availableIn:'both') 안전 배선:

• side-effect method(Runtime.evaluate/callFunctionOn/Page.navigate 등)는 named tool과 동일 술어로 LIVE guard 강제(conn.kind==='relay' && fresh getLiveIntent() && confirm!==true → liveGuardError, feat(mcp): start_debug(mode) — dual-connection coexist, seamless env switch (#348) #354 race fix 상속). requiresLiveConfirm(conn,args) helper로 추출해 evaluate·call_sdk·cdp_send 3호출지 공유. 이 guard 없으면 cdp_send('Runtime.evaluate',{expression})가 LIVE guard 우회 백도어가 된다 — 이게 가장 큰 위험점.
• SECRET-HANDLING: params·result 불로깅(method 이름만).
• AIT.* 명시 거부 + 미등재 domain은 차단 말고 "WKWebView 미구현 가능" 경고를 meta에.
• mock-mode: CDP_ONLY_TOOL_NAMES 등재 → tools/list엔 보이되 호출 시 CDP_UNAVAILABLE_IN_DEV_MODE tier-filter 에러(RFC: MCP tool surface fidelity — mock ↔ relay 평행 + 환경 필터링 매트릭스 #277 평행성 invariant 유지).

#277 정본과의 관계

표면적으론 "방금 13-tool 평행성을 close했는데 곧바로 축소냐"는 번복처럼 보이지만 아니다. #277이 정본화한 것은 '13개가 신성불가침'이 아니라 '환경 간 평행 규율'(descriptor availableIn · filterToolsByEnvironment · tierRejectionError · fidelity-qa 정량 diff)이다. 이 안은 그 규율을 한 글자도 건드리지 않고 적용받는 tool 집합만 두께 기준으로 재편한다 — wire-identical 3개를 raw passthrough로 흡수, THICK·비표준은 보존. 즉 #253은 #277의 반대 방향이 아니라 #277이 깐 평행성 레일 위에서 slim화 욕구를 회귀 0으로 태우는 따름정리다. fidelity-qa whitelist(26항목)도 버리지 않고 재사용한다.

양면 트레이드오프 (결정 시 고려)

• 하이브리드 채택 시: 두 BLOCKER(mock CDP 부재로 평행성 붕괴, LIVE guard 우회)와 세 MAJOR(fix(mcp): call_sdk 인자 시그니처 검증 — setDeviceOrientation 호출이 토스 앱 crash 가능성 #264 crash, SECRET echo, AIT.* 도달 불가)가 모두 0건. 단 surface는 8까지 안 줄고 10~11에 멈춘다. LIVE guard를 tool-name 단위→method-payload 단위로 옮기는 보안 재배선 리스크가 있어 회귀 테스트 필수.
• devtools-MCP CDP-first 재설계 — CDP passthrough whitelist + tool surface 축소 #253 원안(13→8) 강행 시: surface는 최소화되지만 실기기 토스 앱 crash(fix(mcp): call_sdk 인자 시그니처 검증 — setDeviceOrientation 호출이 토스 앱 crash 가능성 #264) 재발·live 세션 무제한 실행·AIT.* 자기모순(whitelist 좁히면 도달 불가, 열면 LIVE 우회 표면 최대)이 확정.
• 현 RFC: MCP tool surface fidelity — mock ↔ relay 평행 + 환경 필터링 매트릭스 #277 유지(아무것도 안 함) 시: 회귀 0이지만 wire-identical 3개의 named 비용·tool 표면 인지 비용(M2-5: build_attach_url을 환경 detection affordance로 승격 — default-mock dead-lock 해소 #309 dead-lock 계열)이 영속.

권고는 분명히 adopt-hybrid다. 다만 cdp_send가 take_screenshot의 MCP image block 편의를 어떻게 처리할지(어댑터 vs 이 한 tool만 named 유지)는 명시적 결정 사항으로 남긴다.

---

이 권고는 설계 검토 산출물이며, 구현은 사용자 방향 결정 후 착수한다.

[DaveDev42]

트리아지: 구현 보류 (board Todo ≠ 실제 상태)

board에는 M2/no-blocker Todo로 보이지만 실제로는 설계 리뷰 완료 후 구현 보류 상태다. false "ready" 신호를 정정한다.

• 왜 보류: CDP-first redesign은 현 mock+panel 경로(환경 1)의 fidelity 천장 안에서는 즉시 필요가 없고, 실효는 환경 3·4(on-device CDP relay)가 자리잡은 뒤에 발생한다. 지금 구현하면 relay 인프라 확정 전이라 재작업 위험이 크다.
• 재진입 트리거: on-device CDP relay(relay attach TOTP 인증 (relay-side 권위 + in-app gate fail-fast) #194 인증 포함)가 안정화되고 환경 3 dog-food 루프가 정착하는 시점.
• 의존: MCP debug dashboard: mini DevTools UI (Chii client 같은 origin mount, Phase 2) #248(dashboard Phase 2)은 본 이슈(devtools-MCP CDP-first 재설계 — CDP passthrough whitelist + tool surface 축소 #253 CDP-first)에 의존한다 — dashboard Phase 2는 CDP-first 데이터 모델 위에서만 의미가 있으므로 devtools-MCP CDP-first 재설계 — CDP passthrough whitelist + tool surface 축소 #253 재진입 이후에 착수한다.

GA flip과 무관(external-block 아님). 재진입 트리거 충족 전까지 Todo가 아니라 보류로 읽어야 한다.