@bcdflow/dev-inspector

AI 코딩 어시스턴트(Claude Code)와 연동하여 웹 페이지를 실시간으로 검사, 어노테이션, 감사할 수 있는 Express 미들웨어입니다.

Claude Code → MCP Server (stdio) → Express API (SSE+REST) → Client JS (in-page) → DOM

Quick Start

1. 설치

npm install -D @bcdflow/dev-inspector

2. Express 앱에 미들웨어 추가

const { devInspector } = require('@bcdflow/dev-inspector');

// 개발 환경에서만 활성화 (production에서 자동 비활성)
app.use(devInspector({ autoInject: true }));

3. MCP 서버 등록 (Claude Code 연동)

npx dev-inspector setup

4. 사용

• 서버 시작 후 브라우저에서 페이지 열기
• 우하단 돋보기 버튼 클릭 또는 Ctrl+Shift+X로 인스펙터 토글
• Claude Code에서 MCP 도구로 DOM 검사, 어노테이션, 접근성 감사 등 사용

License Key (Pro)

Free tier는 11개 기본 도구를 제공합니다. Pro 라이선스를 활성화하면 34개 전체 도구를 사용할 수 있습니다.

활성화 방법

방법 1: CLI로 활성화 (권장)

npx dev-inspector activate DI-XXXX-XXXX-XXXX

키가 ~/.dev-inspector/config.json에 저장되어 모든 프로젝트에서 자동 적용됩니다.

방법 2: 환경변수

# .env
DEV_INSPECTOR_KEY=DI-XXXX-XXXX-XXXX

방법 3: 미들웨어 옵션

app.use(devInspector({
  licenseKey: process.env.DEV_INSPECTOR_KEY,
  autoInject: true,
}));

상태 확인

npx dev-inspector status

Free vs Pro

| 기능 | Free | Pro | |------|:----:|:---:| | DOM 검사 (inspect_element) | O | O | | 요소 선택/하이라이트 (select_element) | O | O | | 어노테이션 관리 (acknowledge, resolve, dismiss, reply) | O | O | | 버그 컨텍스트 (get_bug_context) | O | O | | 텍스트 어노테이션 (annotate_text) | - | O | | 애니메이션 제어 (pause_animations) | - | O | | React 컴포넌트 검사 (inspect_component, find_components) | - | O | | 스크린샷 캡처 (capture_page, capture_labeled) | - | O | | 접근성 감사 (audit_accessibility, check_contrast) | - | O | | CSS 규칙 검사 (inspect_css_rules) | - | O | | 디자인 토큰 추출 (extract_design_tokens) | - | O | | React 상태 검사 (inspect_react_state) | - | O | | 페이지 구조 검증 (validate_page_structure) | - | O | | Tailwind 매핑 (map_to_tailwind) | - | O | | 성능 메트릭 (get_performance_metrics) | - | O | | 테스트 코드 생성 (generate_test_code) | - | O | | 탭 순서 검사 (inspect_tab_order) | - | O | | 에셋 목록 (list_assets) | - | O | | 버그 리포트 내보내기 (export_bug_report) | - | O |

미들웨어 옵션

app.use(devInspector({
  // 라이선스 키 (없으면 DEV_INSPECTOR_KEY 환경변수 또는 ~/.dev-inspector/config.json)
  licenseKey: 'DI-XXXX-XXXX-XXXX',

  // API 라우트 접두사 (기본: '/api/v1/dev-inspector')
  prefix: '/api/v1/dev-inspector',

  // production에서도 활성화 (기본: false — production에서 자동 비활성)
  enabled: false,

  // HTML 응답에 클라이언트 스크립트 자동 주입 (기본: false)
  autoInject: true,
}));

autoInject 없이 수동으로 스크립트 추가

<script src="/api/v1/dev-inspector/client.js" defer></script>

CLI 명령어

npx dev-inspector setup              # Claude Code MCP 서버 등록
npx dev-inspector setup --global     # 전역 등록 (모든 프로젝트)
npx dev-inspector activate <key>     # Pro 라이선스 활성화
npx dev-inspector status             # 라이선스 상태 확인
npx dev-inspector mcp                # MCP 서버 직접 실행 (디버그)

API 엔드포인트

미들웨어가 자동으로 마운트하는 엔드포인트:

| Method | Path | 설명 | |--------|------|------| | GET | {prefix}/stream | SSE 스트림 (브라우저 연결) | | POST | {prefix}/call | 도구 호출 (MCP → 브라우저) | | POST | {prefix}/result | 도구 결과 (브라우저 → MCP) | | GET | {prefix}/tools | 사용 가능한 도구 목록 | | GET | {prefix}/license-status | 라이선스 상태 | | GET | {prefix}/status | 연결 상태 | | GET | {prefix}/client.js | 클라이언트 번들 |

스크린샷 기능

스크린샷 도구(capture_page, capture_labeled)를 사용하려면 html2canvas가 필요합니다:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html2canvas.min.js"></script>

아키텍처

┌─────────────┐     stdio      ┌─────────────┐     HTTP      ┌─────────────────┐
│ Claude Code │ ──────────────→ │ MCP Server  │ ────────────→ │ Express 미들웨어 │
│             │ ←────────────── │ (server.js) │ ←──────────── │  (SSE + REST)   │
└─────────────┘   JSON-RPC     └─────────────┘   POST/GET    └────────┬────────┘
                                                                      │ SSE
                                                                      ↓
                                                              ┌───────────────┐
                                                              │ Client JS     │
                                                              │ (브라우저 내)  │
                                                              │  → DOM 접근   │
                                                              └───────────────┘

요구 사항

• Node.js >= 16
• Express >= 4.0
• Claude Code (MCP 연동 시)

License

This software is proprietary. See LICENSE for details.