designer-mcp

Claude Code를 위한 커서 스타일의 디자이너 펜입니다. 헤드(headed) Chromium에서 웹페이지를 클릭하거나, 영역을 지정하거나, 그림을 그리면 Claude가 정확한 소스 파일, 줄 번호, CSS 선택자 및 스크린샷을 받아 즉시 편집하고 확인할 수 있습니다.

기능

시각적 요소에서 소스로 연결하는 세 가지 모드:

모든 스크린샷은 /tmp에 PNG 파일로 저장되고 경로로 반환되므로, MCP 클라이언트가 base64로 인한 컨텍스트 제한에 걸리지 않습니다.

React 소스 해석은 @babel/plugin-transform-react-jsx-source에 의해 연결된 _debugSource fiber 속성을 통해 Next.js 개발 모드에서 작동합니다. 프로덕션 빌드에서는 이 속성이 제거됩니다. 아래의 프로덕션 소스 매핑을 참조하세요.

데모

You:     "Make this button rounder"
Claude:  [designer_open http://localhost:3000/dashboard]
Claude:  [designer_pick mode=element]
You:     *click the button*
Claude:  → source: Button.tsx:42
Claude:  [Edit Button.tsx add rounded-full]
Claude:  [designer_screenshot selector=#cta-btn]  ← after screenshot for verification

설치

전제 조건: Node 18+, Claude Code, 작동 가능한 macOS/Linux (Playwright Chromium).

git clone https://github.com/YOUR_USER/designer-mcp.git
cd designer-mcp
npm install
npx playwright install chromium      # one-time browser download

Claude Code에 MCP를 등록합니다 (user-scope = 모든 세션에서 사용 가능):

claude mcp add --scope user designer-mcp node "$(pwd)/index.js"

향후 세션에서 워크플로우를 인식할 수 있도록 Claude 스킬을 설치합니다:

mkdir -p ~/.claude/skills/designer
cp SKILL.md ~/.claude/skills/designer/SKILL.md

Claude Code를 재시작합니다. 세션에서 designer_* 도구와 designer: 스킬을 확인할 수 있습니다.

사용법

Next.js 개발 서버를 시작합니다 (소스 매핑을 위해):

cd your-nextjs-app && npm run dev

그 다음, Claude Code에서:

"디자이너에서 http://localhost:3000/settings를 열고 헤더를 선택하게 해줘."

Claude가 designer_open(...)을 호출한 다음 designer_pick({ mode: "element" })를 호출합니다. Chromium 창이 앞으로 나타나고 커서가 십자선으로 바뀌면 헤더를 클릭합니다. Claude는 source.fileName과 lineNumber를 받아 직접 편집할 수 있습니다.

모드 요약

• 단일 요소 — element 사용

• 한 영역 내의 관련된 여러 요소 — area 사용 (박스를 드래그하면 중심이 박스 안에 포함된 모든 요소가 반환됨)

• 시각적 주석/설명 — draw 사용 (빨간 펜, Enter로 완료, Esc로 취소)

프로덕션 소스 매핑

_debugSource는 개발 전용입니다. 프로덕션 빌드에서 선택기를 사용하려면 next.config.js에서 소스 맵을 활성화하세요:

module.exports = {
  productionBrowserSourceMaps: true,
  // ...
};

현재 선택기는 프로덕션 환경에서 source: null을 반환합니다. 향후 버전에서는 배포된 소스 맵을 통해 선택기를 해석할 예정입니다. PR은 언제나 환영합니다.

도구 참조

모든 도구는 MCP를 통해 노출되며, Claude Code에서는 m Claude Code는 이를 mcp__designer-mcp__*`로 인식합니다.

designer_open(url: string)

헤드(headed) Chromium 인스턴스를 실행하거나 재사용하여 탐색합니다. bringToFront()와 AppleScript를 사용하여 macOS에서 창을 맨 앞으로 가져옵니다.

designer_pick({ mode?: "element" | "area" | "draw" })

선택기 오버레이를 활성화합니다. 사용자가 상호작용을 완료하면(또는 Esc로 취소하거나 180초 타임아웃 시) 반환됩니다.

designer_screenshot({ selector?: string })

페이지 또는 특정 요소의 PNG를 생성합니다. { path, bytes }를 반환합니다.

designer_close()

브라우저를 종료하고 Playwright 리소스를 해제합니다.

작동 원리

1. Playwright로 제어되는 Chromium이 헤드(headed) 모드로 실행됩니다. 프로세스당 싱글톤입니다.

2. designer_pick은 페이지에 작은 바닐라 JS 오버레이(picker.js)를 주입합니다. 오버레이 기능:

   • element 모드 — mousemove/click을 추적하고, 마우스가 올라간 대상을 파란색으로 표시하며, 고유한 CSS 선택자를 해석하고, _debugSource를 위해 React fiber 체인을 탐색한 후 MCP로 반환합니다.

   • area 모드 — 고무줄 방식의 마퀴(marquee) 선택; 마우스 버튼을 떼면 중심이 박스 안에 있는 모든 요소가 수집됩니다 (선택자로 중복 제거).

   • draw 모드 — 전체 뷰포트 캔버스 오버레이; 획을 점 배열로 캡처; Enter로 완료합니다.

3. 서버는 최대 180초 동안 200ms마다 window.__designerResult를 폴링합니다.

4. 완료 시 적절한 스크린샷(요소 / 영역 클립 / 전체 뷰포트)이 /tmp에 저장되고 경로가 반환됩니다.

기여

• 다음 분야에 대한 PR을 환영합니다:

  • 프로덕션 소스 맵 해석

  • Kestrel/React Native 선택기 (현재는 웹 전용)

  • 요소 모드에서 다중 요소 선택 (Cmd-클릭으로 추가)

  • VS Code "편집기에서 보기" 통합

라이선스

MIT