web-debug-mcp

web-debug-mcp은 Codex 및 기타 MCP 클라이언트를 위한 로컬 에이전트 네이티브 웹 디버깅 서버입니다. 브라우저 세션, JavaScript 디버거, 제한된 런타임 증거, 재현 가능한 흐름 검증을 조정하는 작은 도구 표면을 노출합니다.

현재 증분은 프레임워크 중립 브라우저 대상, Chromium/CDP, WebDriver BiDi 증거를 포함한 Safari WebDriver, 자동으로 주입되는 React 개발 브리지, Vite 모듈 그래프/HMR 엔드포인트, 그리고 제한된 서버 로그, 라우트 컴파일, Server Action 조회, 관찰된 요청 실행 증거를 포함한 Next.js 개발 서버 메타데이터를 지원합니다. 브라우저별 제한은 명시적으로 유지됩니다. 이는 별도의 도구 카탈로그를 추가하는 대신 동일한 MCP 파사드 뒤에 프레임워크별 컨텍스트를 유지합니다.

포함 내용

• 프로세스를 시작하지 않는 프로젝트 기능 감지.

• 명시적 CDP 엔드포인트를 통한 로컬 Chromium 연결 모드.

• 명시적 원격 CDP 연결은 allowRemote: true인 경우에만 지원됩니다. 대상은 비격리로 표시되며 자동 검색되지 않습니다.

• 명시적 실행 파일 경로를 통한 로컬 Chromium 실행 모드.

• 로컬 safaridriver 또는 명시적 WebDriver 엔드포인트를 통한 Safari WebDriver 모드. 설치된 Safari가 노출하는 경우 BiDi 콘솔 이벤트 및 네트워크 이벤트를 지원합니다.

• 동일 출처 브라우저 작업: 탐색, 클릭, 입력, 대기, 새로고침.

• JavaScript 중단점, 일시 중지 제어, 제한된 호출 프레임, 기본적으로 읽기 전용 평가.

• 하나의 편집된 번들로 콘솔, 네트워크 메타데이터, DOM 요약, 스크린샷, 디버거 증거.

• 개발 빌드가 React 커밋을 노출할 때 React 컴포넌트 트리, 훅 값, 소스 위치, 렌더 횟수, 제한된 커밋 요약, 프로파일러 기간, 플랫 플레임그래프 뷰, 추론된 렌더 원인.

• webDebugVitePlugin() 개발 플러그인을 통한 Vite 모듈/임포터 그래프, HMR 상태, 변환 코드 diff, 소스 맵 요약.

• 로그가 감지된 프로젝트 루트 내에 유지될 때 제한되고 편집된 Next.js 개발 로그 꼬리.

• web_next_inspect를 통한 명시적 Next.js 라우트 컴파일 및 Server Action 조회, 브라우저가 Next-Action 요청을 보낼 때 정규화된 서버 요청 추적 및 요청 연결 실행 증거.

• 캡처의 제한된 재생 타임라인 및 web_replay_seek을 통한 프레임 조회. restore: true는 안전하게 유지된 작업만 재생하며 정제된 양식 입력을 거부합니다.

• 간단한 수정 후 검사가 포함된 재현 가능한 액션 시나리오.

• 결정적 바닐라 픽스처 및 프로젝트 네이티브 하네스 검사.

• 라이브 React/Vite 픽스처, 자동 React 브리지, 모듈 그래프/HMR 스모크 테스트.

• 라이브 Next.js App Router 픽스처 및 /_next/mcp 런타임 스모크 테스트.

Related MCP server: Kaboom Browser AI Devtools MCP

요구 사항

• Node.js 20 이상. Safari BiDi는 --experimental-websocket이 있는 Node 20.10+ 또는 Node 21+가 필요합니다. 이전 런타임은 Safari WebDriver 작업과 문서화된 네트워크 폴백을 유지하지만 BiDi 콘솔 제한을 보고합니다.

• 라이브 세션 실행 시 Chromium 기반 브라우저.

• web_session_start에 제공된 명시적 WEB_DEBUG_CHROME_EXECUTABLE_PATH 또는 명시적 cdpEndpoint.

개발 명령

npm install --no-audit --no-fund
npm test
npm run typecheck
npm run build
npm run harness:check
npm run smoke:live
npm run smoke:react-vite
npm run smoke:next
npm run smoke:safari

npm run serve:fixture로 픽스처를 실행합니다. 서버는 127.0.0.1에 바인딩되고 기본적으로 포트 4173을 사용합니다. 다른 포트를 사용하려면 WEB_DEBUG_FIXTURE_PORT를 설정하세요.

기본 macOS Chrome 경로를 사용할 수 없을 때 WEB_DEBUG_CHROME_EXECUTABLE_PATH를 설정한 후 npm run smoke:live를 실행합니다. 바닐라 픽스처를 시작하고, app.js에 중단점을 설정하고, 버튼을 클릭하고, 일시 중지 안전 증거 경로를 캡처하고, 소유한 브라우저 및 픽스처 프로세스를 정리합니다.

npm run smoke:react-vite를 실행하여 Vite 픽스처를 시작하고, React 컴포넌트/상태 증거를 확인하고, fixtures/react-vite/src/App.jsx에서 일시 중지하고, 제출된 결제 흐름을 재생합니다.

Vite 애플리케이션의 경우 vite.config.ts에 개발 전용 플러그인을 추가합니다:

import { webDebugVitePlugin } from "web-debug-mcp/vite";

export default {
  plugins: [webDebugVitePlugin()],
};

플러그인은 디버그 세션 중에 사용되는 로컬 읽기 전용 모듈 그래프 엔드포인트를 제공합니다. 프로덕션 서버에서는 활성화하면 안 됩니다.

npm run smoke:next를 실행하여 Next.js App Router 픽스처를 시작하고, 내장 /_next/mcp 엔드포인트를 쿼리하고, 라우트/프로젝트/컴파일 메타데이터와 제한된 서버 로그 꼬리를 확인하고, 클라이언트 라우트 핸들러 흐름을 실행합니다.

npm run smoke:safari를 실행하여 Safari WebDriver를 통해 바닐라 픽스처를 실행합니다. 먼저 Safari 설정 → 개발자 → 원격 자동화 허용을 활성화하세요. Safari가 표시된 상태로 실행되고, BiDi 콘솔 증거를 캡처하며, 네트워크 증거가 BiDi에서 왔는지 제한된 Performance Resource Timing 폴백에서 왔는지 보고합니다. Safari의 JavaScript 디버거는 이 어댑터를 통해 사용할 수 없습니다.

Safari 27 및 Safari Technology Preview 247에는 Apple의 공식 Safari MCP 서버가 포함되어 있습니다. 브라우저 네이티브 DOM, 네트워크, 콘솔, 스크린샷 도구가 원하는 표면일 때 해당 공식 서버를 사용하세요. 이 저장소는 중복된 공개 Safari MCP 카탈로그를 추가하지 않습니다. WebDriver 어댑터는 이전 Safari 버전과 공유 세션/증거 오케스트레이션을 위한 스위트의 단일 파사드 호환성 경로로 계속 유용합니다.

개발 중에는 npm run dev로 MCP 서버를 실행하고, npm run build 후에는 node dist/index.js로 실행합니다. MCP 프로토콜 메시지는 stdout을 사용합니다. 진단은 stderr에 유지해야 합니다.

MCP 워크플로

1. 프로젝트 루트로 web_project_detect를 호출합니다.

2. 루프백 URL과 명시적 브라우저 연결 또는 실행 파일로 web_session_start를 호출합니다.

3. web_browser_action 및 web_breakpoint_set을 사용하여 문제를 재현합니다.

4. 하나의 제한된 증거 번들로 web_issue_capture를 호출합니다.

5. Next.js의 경우 web_next_inspect를 호출하여 라우트를 컴파일하거나 Server Action ID를 해석합니다.

6. web_repro_record로 흐름을 저장하고 나중에 web_fix_verify로 실행합니다.

7. web_replay_seek을 사용하여 보존된 캡처 프레임 하나를 검사합니다. 프레임에 안전하고 민감하지 않은 작업이 포함된 경우에만 restore: true를 전달합니다.

8. 세션이 더 이상 필요하지 않을 때 web_session_close를 호출합니다.

서버는 일반 세션 중에 프로젝트에 쓰지 않습니다. 스크린샷은 임시 세션별 아티팩트 디렉터리에 저장되고 경로로 반환됩니다.

안전 기본값

• allowRemote가 명시적으로 활성화되지 않는 한 브라우저 URL은 루프백 전용입니다.

• 브라우저 탐색은 세션 출처에 유지됩니다.

• 외부 CDP 연결은 비격리로 표시됩니다.

• 콘솔, 네트워크, 디버거 로컬 변수, 평가 값은 편집되고 제한됩니다.

• 원시 응답 본문, 쿠키, 인증 값, 브라우저 저장소는 핵심 어댑터에서 수집되지 않습니다.

• allowSideEffects가 명시적으로 true가 아닌 한 평가는 부작용을 거부합니다.

현재 경계

이 저장소는 호스팅 서비스가 아닌 로컬 개발자 도구입니다. 프로덕션 배포, CI 워크플로, 인증되지 않은/자동 검색 원격 브라우저 제어, 또는 완전한 React DevTools 프로파일러/플레임그래프 동등성이 없습니다. React 기간 및 렌더 원인 세부 정보는 DevTools 훅에서 제한되고 추론됩니다. Vite 출처 및 소스 맵은 전체 소스 맵 디버거가 아닌 요약입니다. Next.js 실행 증거는 요청 연결 Server Action 메타데이터, 요청 인사이트, 제한된 로그로 제한됩니다. Safari 디버거 동등성은 사용할 수 없으며 Safari 26은 Performance Resource Timing 네트워크 폴백이 필요할 수 있습니다. 재생 복원은 안전하게 유지된 작업으로 제한되며 애플리케이션 상태 타임트래블이 아닙니다. 명시적 원격 CDP 연결, Safari WebDriver 작업/DOM/스크린샷, 명시적 기능 경고, 제한된 재생 복원을 사용할 수 있습니다. 해당 주장에는 승인된 외부 원격 호스트와 호출자가 제공한 하네스 인증 증거가 여전히 필요합니다.