Stitch MCP은(는) 무엇을 하나요?
개요
Google Stitch는 프롬프트로 UI 화면을 생성하고 각 화면을 HTML 문서와 스크린샷으로 저장합니다. stitch-mcp(npm 패키지 @_davideast/stitch-mcp, 독립적인 오픈소스 프로젝트)는 코드베이스와의 브릿지 역할을 합니다. 세 가지 작업을 수행합니다: 코딩 에이전트에 Stitch를 MCP 서버로 등록하고, 에이전트가 단일 호출로 화면의 마크업을 전달받을 수 있는 헬퍼 도구를 추가하며, 화면을 미리보거나 Astro 프로젝트로 내보낼 수 있습니다. 아래 정보는 버전 0.9.0을 기준으로 확인되었습니다. 플래그가 거부되면 모든 명령어에 --help를 추가하여 실행하세요.
에이전트의 실제 작업은 가져오기 이후에 시작됩니다: Stitch 출력은 화면당 하나의 정적 HTML 페이지이며, 이를 대상 저장소에 맞는 컴포넌트로 변환하는 것이 과제입니다.
지침
1. 시작점 확인
다음 순서로 질문하거나 조회하세요:
- 어떤 MCP 클라이언트를 사용 중인지(Claude Code, Cursor, VS Code, Codex, OpenCode, Gemini CLI, Antigravity) 그리고
stitch서버가 이미 등록되어 있는지. - 사용자가 Stitch API 키를 가지고 있는지. 키가 없으면 설정이 Google Cloud OAuth를 거쳐야 하며, 이는 브라우저와 결제가 활성화된 프로젝트가 필요합니다.
- Stitch 프로젝트와 구현할 화면. 프로젝트 ID는
7302915846120394175와 같은 긴 숫자입니다. 화면 ID는 32자리 16진수 문자열입니다. 표시 이름은 허용되지 않습니다. - 대상 스택: 저장소에서 읽어온 프레임워크, 스타일링 시스템, 기존 컴포넌트 및 디자인 토큰. React와 Tailwind를 가정하지 마세요.
2. 인증 방식 선택
| 모드 | 제공 방법 | 선택 조건 |
|---|---|---|
| API 키 | 환경 변수 STITCH_API_KEY, .env 파일 또는 MCP 서버의 env 블록 | 기본값. 무인, CI, SSH에서 작동하며 갱신이 필요 없음 |
| OAuth via wizard | init이 자체 gcloud SDK를 ~/.stitch-mcp/에 다운로드하고 로그인 | 키는 없지만 Google Cloud 프로젝트를 소유한 사용자 |
| OAuth via 기존 gcloud | STITCH_USE_SYSTEM_GCLOUD=1 및 아래 세 가지 명령어 | gcloud가 이미 설치되어 있고 로그인된 상태 |
기존 gcloud 경로는 브라우저를 열어야 하므로 사용자가 직접 실행해야 합니다:
gcloud auth application-default login
gcloud config set project orchard-design-prod
gcloud beta services mcp enable stitch.googleapis.com --project=orchard-design-prod
키가 없으면 CLI는 OAuth를 가정합니다. 확인 실행 시, doctor는 깨끗한 머신에서 약 500MB의 gcloud SDK를 ~/.stitch-mcp/에 다운로드한 후에야 결과를 보고하므로, 키 경로를 의도했다면 먼저 키를 내보내세요.
3. 연결 방식 선택
| 프록시 over stdio | 직접 HTTP | |
|---|---|---|
| 클라이언트가 시작하는 것 | npx @_davideast/stitch-mcp proxy를 하위 프로세스로 | 없음. https://stitch.googleapis.com/mcp를 호출 |
| 에이전트가 보는 도구 | Stitch 자체 도구 + 6단계의 네 가지 헬퍼 | Stitch 자체 도구만 |
| OAuth 토큰 수명 | 프록시가 자동 갱신 | 1시간 후 수동 교체 |
| 적합한 상황 | 인터랙티브 디자인-투-코드 세션 | 프로세스를 생성할 수 없는 파이프라인 및 샌드박스 |
특별한 이유가 없다면 프록시를 선택하세요. get_screen_code 없이 에이전트는 get_screen을 호출하고, 다운로드 URL을 찾아 마크업을 직접 가져와야 합니다.
4. 서버 등록
Claude Code, 셸 환경에서 API 키를 가져와 프록시 사용:
claude mcp add stitch -e STITCH_API_KEY="$STITCH_API_KEY" -- npx @_davideast/stitch-mcp proxy
Claude Code, 직접 HTTP (-s user는 ~/.claude.json에, -s project는 ./.mcp.json에 기록):
claude mcp add stitch --transport http https://stitch.googleapis.com/mcp \
--header "X-Goog-Api-Key: $STITCH_API_KEY" -s user
Cursor (.cursor/mcp.json)와 Antigravity는 동일한 형식을 공유합니다. 이 변형은 OAuth를 사용하므로 파일에 비밀이 포함되지 않아 커밋해도 안전합니다:
{
"mcpServers": {
"stitch": {
"command": "npx",
"args": ["@_davideast/stitch-mcp", "proxy"],
"env": { "STITCH_PROJECT_ID": "orchard-design-prod" }
}
}
}
API 키 경로의 경우 env 블록에 STITCH_API_KEY를 대신 넣습니다. 해당 파일은 버전 관리에서 제외하거나 클라이언트 자체 환경 변수 보간을 사용하세요.
다른 클라이언트에서의 차이점:
- VS Code (
.vscode/mcp.json): 최상위 키는servers이며, 각 항목은"type": "stdio"(또는url및headers와 함께"type": "http")가 필요합니다. - Codex (
~/.codex/config.toml):[mcp_servers.stitch]테이블에command = "npx"및args = ["@_davideast/stitch-mcp", "proxy"]를 입력하고 변수는[mcp_servers.stitch.env]아래에 넣습니다. - OpenCode (
opencode.json):"mcp": { "stitch": { "type": "local", "command": ["npx", "@_davideast/stitch-mcp", "proxy"], "environment": { } } }. - Antigravity, 직접 모드 전용: 필드는
url이 아닌serverUrl입니다. - Gemini CLI:
gemini extensions install https://github.com/gemini-cli-extensions/stitch.
npx @_davideast/stitch-mcp init는 프롬프트를 통해 동일한 구성을 기록합니다. -c, --client (claude-code, cursor, vscode, codex, opencode, gemini-cli, antigravity) 및 -t, --transport (stdio 또는 http) 플래그를 받아 두 가지 단계를 건너뛸 수 있지만, 여전히 마법사 방식이므로 에이전트 셸에서 실행하는 대신 사용자에게 전달하세요.
MCP 구성 변경 후에는 클라이언트를 다시 시작하세요.
5. 의존하기 전에 확인
npx @_davideast/stitch-mcp doctor --verbose # --json 추가 시 기계 판독 가능 결과
npx @_davideast/stitch-mcp tool # CLI가 접근 가능한 모든 도구 나열
doctor는 모드에 따라 다음을 확인합니다: 키 존재 여부, API가 키를 수락하는지, gcloud 400.0.0 이상, 사용자 로그인 상태, 애플리케이션 기본 자격 증명, 활성 프로젝트, API 접근 가능 여부. tool 목록에 build_site가 포함되어 있으면 헬퍼 도구를 사용할 수 있습니다.
6. 화면 찾기 및 가져오기
일부 명령어는 터미널 UI를 열어 에이전트 셸에서 중단됩니다: init, screens, view, 그리고 --routes 또는 JSON 플래그 없이 site를 실행하는 경우. 대신 다음을 사용하세요:
npx @_davideast/stitch-mcp tool list_projects -o json
npx @_davideast/stitch-mcp site -p 7302915846120394175 --list-screens
npx @_davideast/stitch-mcp tool get_screen_code -o json \
-d '{"projectId":"7302915846120394175","screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12"}'
site --list-screens는 { success, projectId, screens: [{ screenId, title, suggestedRoute, hasHtml }] }를 출력합니다. hasHtml: false인 화면은 아직 가져올 마크업이 없습니다.
| 도구 | 출처 | 입력 | 반환 내용 |
|---|---|---|---|
list_projects, get_project | Stitch | 없음 / name (projects/ID) | 계정이 열 수 있는 프로젝트 |
list_screens, get_screen | Stitch | projectId / name (projects/ID/screens/SCREEN_ID) | 메타데이터 및 다운로드 URL, 마크업 아님 |
generate_screen_from_text, edit_screens, generate_variants | Stitch | 프롬프트 기반 | 프로젝트의 새 화면 또는 변경된 화면 |
get_screen_code | 프록시 | projectId, screenId | { screenId, projectId, htmlContent } |
get_screen_image | 프록시 | projectId, screenId | { screenId, projectId, imageContent }, base64로 인코딩된 스크린샷 |
build_site | 프록시 | projectId, routes[] ({ screenId, route }) | { success, pages: [{ screenId, route, title, html }], message } |
list_tools | 프록시 | 없음 | 이름, 설명 및 입력 스키마 |
tool NAME -s는 모든 도구의 입력 스키마를 출력합니다. -f, --data-file은 JSON 본문을 파일에서 읽고, -o는 json, pretty (기본값) 또는 raw를 받습니다.
7. 마크업을 프로젝트 코드로 변환
- 각 화면에 대해
get_screen_code와get_screen_image를 가져옵니다. HTML에는 정확한 색상, 간격 및 글꼴 스택이 포함되어 있고, 이미지는 결과물이 어떻게 보여야 하는지 보여줍니다. - 파일을 작성하기 전에 화면 간에 반복되는 요소(네비게이션, 푸터, 버튼, 카드)를 인벤토리로 정리하고, 각각을 기존 컴포넌트 또는 새로운 공유 컴포넌트에 매핑합니다.
- 원시 값을 프로젝트의 토큰에 매핑합니다. 테마 변수와 일치하는 16진수 색상은 변수로 바꾸고, 일회성 값은 리터럴로 유지하며 인계 노트에 나열합니다.
- 의미론적 요소, 실제 링크 및 폼 컨트롤, 프로젝트의 데이터 레이어를 사용하여 하드코딩된 샘플 콘텐츠 대신 구조를 재구축합니다.
- 실행 중인 페이지를 디자인 너비에서 스크린샷과 비교한 다음, 모바일 너비에서 비교하고 모든 의도적인 차이점을 보고합니다.
생성 도구인 create_project, delete_project 및 디자인 시스템 도구는 사용자의 Stitch 계정을 변경합니다. 사용자가 요청할 때만 호출하고, 디자인을 구현하는 부작용으로 절대 호출하지 마세요.
8. 에이전트 없이 미리보기 또는 내보내기
| 명령어 | 목적 | 알아두면 좋은 플래그 |
|---|---|---|
serve -p ID | 로컬 Vite 서버, /screens/ 아래 화면당 하나의 URL | --list-screens는 경로를 JSON으로 출력; --json은 무인 모드로 서버가 준비되면 JSON 출력 |
site -p ID | 화면-경로 맵에서 Astro 프로젝트 작성 | -o DIR 출력 폴더; -r JSON은 맵을 제공하고 UI 건너뜀; -e는 맵을 build_site 입력으로 출력 |
upload -p ID -f FILE | PNG, JPG, WEBP 또는 HTML 파일을 새 화면으로 추가 | --title |
proxy | MCP 서버 자체 | --debug는 /tmp/stitch-proxy-debug.log에 로깅 |
logout | OAuth 로그인 해제 | --force, --clear-config (사용자에게 먼저 물어봄: 번들된 gcloud 설정을 삭제) |
Astro 출력에는 src/layouts/Layout.astro, src/pages/의 경로당 하나의 파일, public/assets/의 다운로드된 에셋이 포함됩니다. npm install && npm run dev로 시작하며 포트 4321에서 실행됩니다.
예제
예제 1: 기존 Next.js 앱에서 하나의 Stitch 화면 구현
Ilse Brandt는 예약 앱(Next.js App Router, tailwind.config.ts에 토큰이 있는 Tailwind)을 유지 관리합니다. 그녀는 Claude Code를 사용하고 셸 프로필에 Stitch API 키를 가지고 있으며, "내 Stitch 프로젝트에서 Pricing 화면을 구현해줘"라고 요청합니다.
claude mcp add stitch -e STITCH_API_KEY="$STITCH_API_KEY" -- npx @_davideast/stitch-mcp proxy
npx @_davideast/stitch-mcp site -p 7302915846120394175 --list-screens
목록은 {"screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12","title":"Pricing","suggestedRoute":"/pricing","hasHtml":true}를 보여줍니다. 클라이언트를 다시 시작한 후 에이전트는 해당 ID로 get_screen_code와 get_screen_image를 호출하고 다음을 보고합니다:
화면: Pricing (c41f0a9e…5a12) -> app/pricing/page.tsx
재사용: components/SiteHeader.tsx, components/Button.tsx (variant "primary")
생성: components/pricing/PlanCard.tsx, components/pricing/BillingToggle.tsx
토큰: #1F6F5C -> colors.brand.600; 24px 카드 간격 -> gap-6; 44px 제목은 text-[44px]로 유지
의도적으로 변경: 요금제 가격은 샘플 수치 대신 lib/plans.ts에서 읽음
확인: 1440px 및 390px에서 스크린샷과 비교; 토글은 키보드 작동 가능
예제 2: 헤드리스 셸에서 세 개의 화면을 Astro 사이트로 내보내기
Tomasz Wrona는 빌드 호스트에서 SSH를 통해 작업하며, 터미널 UI 없이 Stitch 프로젝트에서 정적 마케팅 사이트를 원합니다. 키는 세션에 이미 내보내져 있습니다.
npx @_davideast/stitch-mcp site -p 5518204776390142068 --list-screens > screens.json
npx @_davideast/stitch-mcp site -p 5518204776390142068 -o ./harbour-site -r '[
{"screenId":"0b7e3c915ad84f2e9c6d1a8f4e2b7c30","route":"/"},
{"screenId":"9a2d6f1c4b8e47a3b5c0e7d19f3a6b48","route":"/services"},
{"screenId":"e5c81b07d3f24a69a1b4c92d6e0f7a15","route":"/contact"}
]'
cd harbour-site && npm install && npm run build
결과: src/pages/index.astro, services.astro 및 contact.astro가 공유 레이아웃으로 래핑되고, 이미지와 폰트는 public/assets/ 아래에 있습니다. 그런 다음 에이전트는 세 페이지에서 중복된 헤더와 푸터 마크업을 각각 하나의 Astro 컴포넌트로 대체하고, 두 경로가 경로를 공유하지 않을 수 있으며 알 수 없는 화면 ID는 누락된 ID를 나열하여 빌드를 중단한다는 점을 기록합니다.
가이드라인
- OAuth에서 "Permission Denied" 응답은 일반적으로 세 가지 중 하나를 의미합니다: 결제가 비활성화됨, 프로젝트에서 Stitch API가 활성화되지 않음, 또는 계정에 Owner 또는 Editor 역할이 없음.
doctor --verbose가 HTTP 오류를 보여줍니다. - 두 개의 gcloud 설치는 일반적인 함정입니다. 번들된 것은
~/.stitch-mcp/config/에 자격 증명을 보관합니다.STITCH_USE_SYSTEM_GCLOUD=1이 설정되지 않으면 시스템 gcloud로 로그인해도 번들된 것에는 영향을 미치지 않습니다. - CLI가 읽는 다른 변수:
STITCH_ACCESS_TOKEN(다른 곳에서 얻은 토큰),STITCH_PROJECT_ID또는GOOGLE_CLOUD_PROJECT(프로젝트 재정의),STITCH_HOST(대체 엔드포인트). - WSL, SSH 및 컨테이너에서는 OAuth 링크가 열리지 않고 출력됩니다. 사용자가 브라우저에 복사합니다. API 키를 사용하면 이 문제를 완전히 피할 수 있습니다.
snapshot은 CLI 자체의 터미널 화면을 데이터 파일에서 개발자용으로 렌더링합니다. Stitch 디자인을 저장하거나 버전 관리하지 않습니다. 기록이 필요하면 가져온 HTML을 저장소에 보관하세요.- 가져온 HTML을 디자인 참조로 취급하세요. 그대로 페이지에 붙여넣으면 인라인 스타일, 원격 글꼴 및 이미지 URL, 접근성 작업 부재 상태가 발생합니다.
- 공유 구성에서 패키지(
@_davideast/[email protected])를 고정하면 모든 팀원과 CI가 동일한 도구 세트를 실행합니다. 이 프로젝트는 실험적이며 Google과 제휴 관계가 아닙니다. - 구현 후 시각적 마무리 작업을 위해 이 스킬을
impeccable및frontend-design스킬과 함께 사용하세요. - 디자인이 Figma에 있거나 정적 목업 이미지로 제공되는 경우, 또는 사용자가 디자인 생성을 원하지만 구현을 원하지 않는 경우에는 적합한 도구가 아닙니다. 후자의 경우 Stitch의 웹 UI로 충분합니다.