@bcdflow/dev-inspector 2.0.0 → 2.0.1

package/README.md

@@ -0,0 +1,192 @@
+# @bcdflow/dev-inspector
+
+AI 코딩 어시스턴트(Claude Code)와 연동하여 웹 페이지를 실시간으로 검사, 어노테이션, 감사할 수 있는 Express 미들웨어입니다.
+
+```
+Claude Code → MCP Server (stdio) → Express API (SSE+REST) → Client JS (in-page) → DOM
+```
+
+## Quick Start
+
+### 1. 설치
+
+```bash
+npm install -D @bcdflow/dev-inspector
+```
+
+### 2. Express 앱에 미들웨어 추가
+
+```javascript
+const { devInspector } = require('@bcdflow/dev-inspector');
+
+// 개발 환경에서만 활성화 (production에서 자동 비활성)
+app.use(devInspector({ autoInject: true }));
+```
+
+### 3. MCP 서버 등록 (Claude Code 연동)
+
+```bash
+npx dev-inspector setup
+```
+
+### 4. 사용
+
+- 서버 시작 후 브라우저에서 페이지 열기
+- 우하단 돋보기 버튼 클릭 또는 `Ctrl+Shift+X`로 인스펙터 토글
+- Claude Code에서 MCP 도구로 DOM 검사, 어노테이션, 접근성 감사 등 사용
+
+---
+
+## License Key (Pro)
+
+Free tier는 11개 기본 도구를 제공합니다. Pro 라이선스를 활성화하면 34개 전체 도구를 사용할 수 있습니다.
+
+### 활성화 방법
+
+**방법 1: CLI로 활성화** (권장)
+
+```bash
+npx dev-inspector activate DI-XXXX-XXXX-XXXX
+```
+
+키가 `~/.dev-inspector/config.json`에 저장되어 모든 프로젝트에서 자동 적용됩니다.
+
+**방법 2: 환경변수**
+
+```bash
+# .env
+DEV_INSPECTOR_KEY=DI-XXXX-XXXX-XXXX
+```
+
+**방법 3: 미들웨어 옵션**
+
+```javascript
+app.use(devInspector({
+  licenseKey: process.env.DEV_INSPECTOR_KEY,
+  autoInject: true,
+}));
+```
+
+### 상태 확인
+
+```bash
+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 |
+
+---
+
+## 미들웨어 옵션
+
+```javascript
+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 없이 수동으로 스크립트 추가
+
+```html
+<script src="/api/v1/dev-inspector/client.js" defer></script>
+```
+
+---
+
+## CLI 명령어
+
+```bash
+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가 필요합니다:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/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
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bcdflow/dev-inspector",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "DOM inspector + MCP bridge for AI coding assistants. Express middleware that enables Claude Code to inspect, annotate, and audit web pages in real-time.",
   "main": "dist/middleware/index.js",
   "bin": {
@@ -17,7 +17,15 @@
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["mcp", "dom-inspector", "claude", "ai", "express-middleware", "accessibility", "devtools"],
+  "keywords": [
+    "mcp",
+    "dom-inspector",
+    "claude",
+    "ai",
+    "express-middleware",
+    "accessibility",
+    "devtools"
+  ],
   "license": "MIT",
   "peerDependencies": {
     "express": ">=4.0.0"
@@ -28,6 +36,7 @@
     }
   },
   "devDependencies": {
+    "@bcdflow/dev-inspector": "^2.0.0",
     "esbuild": "^0.24.0",
     "typescript": "^5.7.0"
   },