UI Inspector MCP

Live UI preview server with built-in inspector, responsive viewport switching, and multi-framework export — powered by MCP (Model Context Protocol).

Vite 기반 라이브 UI 프리뷰 + 인스펙터 + 반응형 뷰포트 전환 + 멀티프레임워크 내보내기를 지원하는 MCP 서버.

---

Features / 주요 기능

Feature	Description
Live Preview	Vite dev server with HMR — changes reflect instantly / Vite HMR로 즉시 반영되는 라이브 프리뷰
Inspector	Click any element to see source location, design term, styles, and size / 엘리먼트 클릭 시 소스 위치, 디자인 용어, 스타일, 크기 표시
Viewport Switching	Mobile (375px), Tablet (768px), Desktop — real CSS @media breakpoints via iframe / iframe 기반 실제 CSS 미디어쿼리 반응
Multi-Framework Export	Export to Next.js, Remix, Nuxt, Astro, Vue (Vite), React (Vite) as ZIP / 6개 프레임워크로 ZIP 내보내기
Design Tokens	Inject CSS custom properties at session start / 세션 시작 시 디자인 토큰 주입
WebSocket Bridge	Real-time communication between inspector UI and MCP server / 인스펙터 UI와 MCP 서버 간 실시간 통신

---

Architecture / 아키텍처

┌─────────────────────────────────────────────────────┐
│  AI Assistant (Claude, etc.)                        │
│  ─── MCP Protocol (stdio) ───                       │
├─────────────────────────────────────────────────────┤
│  UI Friend MCP Server (index.mjs)                   │
│  ├── PreviewManager     세션 관리 / Session manager  │
│  ├── ProjectScaffold    템플릿 생성 / Scaffolding    │
│  ├── ViteLauncher       Vite 프로세스 / Dev server   │
│  ├── WSBridge           WebSocket 통신 / Comms       │
│  └── ExportEngine       프레임워크 변환 / Conversion  │
├─────────────────────────────────────────────────────┤
│  Browser                                            │
│  ├── PreviewShell       툴바 + iframe 래퍼           │
│  │   ├── Viewport switcher (Mobile/Tablet/Desktop)  │
│  │   ├── Inspector toggle                           │
│  │   ├── Export controls                            │
│  │   └── CodePanel (element details)                │
│  └── iframe (preview-content)                       │
│      ├── App component (user code)                  │
│      ├── IframeWrapper (WS + postMessage listener)  │
│      └── InspectorOverlay (hover/click highlight)   │
└─────────────────────────────────────────────────────┘

---

Installation / 설치

Prerequisites / 사전 요구사항

• Node.js >= 18
• npm >= 9

1. Clone & Install / 클론 및 설치

git clone https://github.com/beyondworks/UI-Friend-MCP.git
cd UI-Friend-MCP
npm install

2. Configure MCP Client / MCP 클라이언트 설정

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

claude_desktop_config.json에 아래 내용을 추가하세요:

{
  "mcpServers": {
    "ui-friend": {
      "command": "node",
      "args": ["/absolute/path/to/UI-Friend-MCP/index.mjs"]
    }
  }
}

Claude Code (CLI)

Add to .claude/settings.json or ~/.claude.json:

.claude/settings.json 또는 ~/.claude.json에 추가:

{
  "mcpServers": {
    "ui-friend": {
      "command": "node",
      "args": ["/absolute/path/to/UI-Friend-MCP/index.mjs"]
    }
  }
}

Cursor / VS Code (Copilot)

Add to .cursor/mcp.json or VS Code MCP settings:

{
  "mcpServers": {
    "ui-friend": {
      "command": "node",
      "args": ["/absolute/path/to/UI-Friend-MCP/index.mjs"]
    }
  }
}

3. Restart your AI client / AI 클라이언트 재시작

After configuration, restart your AI client to load the MCP server.

설정 후 AI 클라이언트를 재시작하면 MCP 서버가 로드됩니다.

---

Usage / 사용 방법

Tools Overview / 도구 목록

Tool	Description
preview_start	Start a live preview session / 라이브 프리뷰 세션 시작
preview_update	Update files with HMR / 파일 업데이트 (HMR 즉시 반영)
preview_status	Check session status / 세션 상태 확인
preview_stop	Stop a session / 세션 종료
preview_select_element	Inspector: get/enable/disable / 인스펙터 제어
preview_export	Export to framework ZIP / 프레임워크 ZIP 내보내기
preview_screenshot	Capture screenshot / 스크린샷 캡처

Example Workflow / 사용 예시

1. Start a Preview / 프리뷰 시작

"Create a landing page preview called my-landing"
→ Calls preview_start with project_name: "my-landing"
→ Opens http://localhost:5173 in browser

"my-landing이라는 랜딩페이지 프리뷰를 시작해줘"
→ preview_start 호출 (project_name: "my-landing")
→ 브라우저에서 http://localhost:5173 자동 열림

Parameters:

{
  "project_name": "my-landing",
  "framework": "react",
  "initial_code": {
    "src/App.tsx": "export default function App() { return <h1>Hello</h1> }"
  },
  "design_tokens": {
    "colorPrimary": "#3b82f6",
    "colorBackground": "#020617"
  }
}

2. Update Files / 파일 업데이트

"Update the hero section with a gradient background"
→ Calls preview_update with session_id and new file content
→ Vite HMR applies changes instantly (no page reload)

"히어로 섹션에 그라데이션 배경을 적용해줘"
→ preview_update 호출 (session_id + 새 파일 내용)
→ Vite HMR로 즉시 반영 (새로고침 없음)

Parameters:

{
  "session_id": "prev_abc123",
  "files": {
    "src/components/Hero.tsx": "... updated code ..."
  }
}

3. Inspect Elements / 엘리먼트 검사

The toolbar in the browser provides:

• Inspector ON/OFF — Toggle element selection mode
• Click any element → Code panel shows:
  • Source file and line number (e.g., src/components/Hero.tsx:26)
  • Design term (e.g., "Hero Section", "Call to Action", "Navigation Bar")
  • Computed styles, size, text content

브라우저 툴바에서:

• Inspector ON/OFF — 엘리먼트 선택 모드 토글
• 엘리먼트 클릭 → Code 패널에 표시:
  • 소스 파일과 라인 번호 (예: src/components/Hero.tsx:26)
  • 디자인 용어 (예: "Hero Section", "Call to Action", "Navigation Bar")
  • 계산된 스타일, 크기, 텍스트 내용

4. Switch Viewports / 뷰포트 전환

Click Mobile (375px), Tablet (768px), or Desktop in the toolbar. The preview uses a real iframe, so CSS @media queries respond correctly.

툴바에서 Mobile (375px), Tablet (768px), Desktop을 클릭합니다. 실제 iframe을 사용하므로 CSS @media 쿼리가 정확히 반응합니다.

5. Export Project / 프로젝트 내보내기

"Export this project as Next.js to ~/Desktop"
→ Calls preview_export with target_framework: "nextjs"
→ Saves ZIP to ~/Desktop/gemini-export-my-landing-nextjs.zip

"이 프로젝트를 Next.js로 ~/Desktop에 내보내줘"
→ preview_export 호출 (target_framework: "nextjs")
→ ~/Desktop/gemini-export-my-landing-nextjs.zip 저장

Parameters:

{
  "session_id": "prev_abc123",
  "target_framework": "nextjs",
  "output_path": "~/Desktop"
}

Supported frameworks / 지원 프레임워크:

• vite-react — React + Vite (default)
• nextjs — Next.js (App Router)
• vite-vue — Vue 3 + Vite
• nuxt — Nuxt 3
• astro — Astro
• remix — Remix

6. Stop Session / 세션 종료

{
  "session_id": "prev_abc123",
  "keep_files": false
}

---

Inspector Design Terms / 인스펙터 디자인 용어

The inspector automatically identifies UI patterns and labels them with design terminology:

인스펙터가 UI 패턴을 자동 식별하여 디자인 용어를 표시합니다:

Category	Terms
Structure	Header, Footer, Main Content, Sidebar, Section, Divider
Navigation	Navigation Bar, Sticky Header, Breadcrumb, Tabs, Pagination, Menu
Content	Card, Hero Section, Panel, Widget, Dashboard, Metric Card
Interactive	Button, Call to Action, Link, Dropdown, Toggle Switch, Search
Form	Form, Input Field, Text Area, Select Dropdown, Date Picker
Data	Data Table, List, Tree View, Timeline, Chart
Feedback	Modal, Toast, Alert, Progress Bar, Skeleton, Spinner
Media	Image, Avatar, Icon, Video Player, Carousel
Layout	Grid, Container, Stack, Spacer, Sticky Element

---

Project Structure / 프로젝트 구조

UI-Friend-MCP/
├── index.mjs                 MCP server entry point / MCP 서버 진입점
├── package.json
├── src/
│   ├── preview-manager.mjs   Session orchestrator / 세션 오케스트레이터
│   ├── project-scaffold.mjs  Template scaffolding / 템플릿 생성
│   ├── vite-launcher.mjs     Vite process manager / Vite 프로세스 관리
│   ├── ws-bridge.mjs         WebSocket bridge / WebSocket 브릿지
│   ├── export-engine.mjs     Framework export / 프레임워크 변환 엔진
│   ├── converters/            Framework converters / 프레임워크 변환기
│   │   ├── nextjs.mjs
│   │   ├── vite-react.mjs
│   │   ├── vite-vue.mjs
│   │   ├── nuxt.mjs
│   │   ├── astro.mjs
│   │   └── remix.mjs
│   └── templates/             Project templates / 프로젝트 템플릿
│       ├── react/             React + Vite + Inspector
│       ├── vue/               Vue 3 + Vite
│       └── vanilla/           Vanilla + Vite

---

How It Works / 동작 원리

1. Session Start: preview_start scaffolds a project from a template, runs npm install, and launches Vite dev server + WebSocket bridge.

2. Live Editing: preview_update writes files to the project directory. Vite HMR detects changes and hot-reloads the browser.

3. Inspector: The preview runs inside an iframe. When Inspector is ON, an overlay captures hover/click events, identifies the element's source location (via Babel source-loc plugin), maps it to a design term, and displays details in the Code panel.

4. Viewport: The iframe's actual width changes, triggering real CSS @media breakpoints — not just visual scaling.

5. Export: The export engine copies user code (stripping inspector files), runs a framework-specific converter, and creates a ZIP file.

---

1. 세션 시작: preview_start가 템플릿에서 프로젝트를 생성하고, npm install 후 Vite 개발 서버 + WebSocket 브릿지를 실행합니다.

2. 라이브 편집: preview_update가 프로젝트 디렉토리에 파일을 쓰면, Vite HMR이 변경을 감지하여 브라우저를 핫리로드합니다.

3. 인스펙터: 프리뷰가 iframe 안에서 실행됩니다. Inspector ON 시 오버레이가 hover/click 이벤트를 캡처하고, Babel source-loc 플러그인으로 소스 위치를 식별하며, 디자인 용어를 매핑하여 Code 패널에 표시합니다.

4. 뷰포트: iframe의 실제 너비가 변경되어 CSS @media 브레이크포인트가 실제로 반응합니다 — 단순 시각적 축소가 아닙니다.

5. 내보내기: 내보내기 엔진이 사용자 코드를 복사(인스펙터 파일 제거)하고, 프레임워크별 변환기를 실행한 뒤 ZIP 파일을 생성합니다.

---

License

MIT