# Stitch MCP Auto 🎨
**[English](README.md)** | **[한국어](README.ko.md)**
> **한 번의 명령. 즉각적인 UI.**
> Google Stitch를 위한 가장 자동화된 MCP 서버.
**💡 AI에게 이 링크만 전달하세요:** `https://github.com/GreenSheep01201/stitch-mcp-auto`
<p align="center">
<a href="https://www.npmjs.com/package/stitch-mcp-auto"><img src="https://img.shields.io/npm/v/stitch-mcp-auto" alt="npm"></a>
<a href="https://www.npmjs.com/package/stitch-mcp-auto"><img src="https://img.shields.io/npm/dm/stitch-mcp-auto" alt="Downloads"></a>
<a href="https://github.com/GreenSheep01201/stitch-mcp-auto/stargazers"><img src="https://img.shields.io/github/stars/GreenSheep01201/stitch-mcp-auto" alt="GitHub stars"></a>
<img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20WSL-blue" alt="Platform">
<img src="https://img.shields.io/badge/License-Apache%202.0-green" alt="License">
<img src="https://img.shields.io/badge/Node.js-18%2B-brightgreen" alt="Node.js">
</p>
---
## 왜 stitch-mcp-auto인가?
| 기능 | stitch-mcp | stitch-mcp-auto |
|------|------------|-----------------|
| 설정 시간 | ~30분 (수동) | ~2분 (마법사) |
| gcloud 설정 | 수동 | 자동 |
| MCP 등록 | 수동 | 자동 |
| 다중 CLI 지원 | ❌ | ✅ Claude/Gemini/Codex |
| AI 이미지 생성 | ❌ | ✅ Gemini 3 Pro |
| 커스텀 명령어 | ❌ | ✅ 7개 워크플로우 |
---
**주요 기능:**
- **자동 설정** - 한 번의 명령으로 모든 것을 설치 (gcloud 인증, API 활성화, MCP 설정)
- **다중 CLI 지원** - Claude Code, Gemini CLI, Codex CLI에서 모두 작동
- **커스텀 19개 도구 + Stitch 핵심 기능** - 디자인 생성, 접근성 검사, 토큰/반응형, 디자인 시스템 내보내기
- **7개 워크플로우 명령** - `/design`, `/design-system`, `/design-flow`, `/design-qa`, `/design-export`, `/generate-asset`, `/design-full`
- **🎨 AI 이미지 생성** - Gemini 3 Pro를 통한 로고, 아이콘, 히어로 이미지 생성 ([Antigravity](#ai-이미지-생성-도구-v110) - Google의 실험적 이미지 생성 API)
- **🎭 오케스트레이션 모드** - 한 번의 프롬프트로 에셋 생성 + 완전한 UI 디자인
- **🌐 다국어 지원** - 시스템 언어 자동 감지 (영어/한국어) - 설정 마법사 및 콘솔 메시지
---
## 목차
- [왜 stitch-mcp-auto인가?](#왜-stitch-mcp-auto인가)
- [사전 요구사항 (먼저 설치하세요)](#사전-요구사항-먼저-설치하세요)
- [1. Node.js 설치 (v18 이상)](#1-nodejs-설치-v18-이상)
- [2. Google Cloud CLI (gcloud) 설치](#2-google-cloud-cli-gcloud-설치)
- [빠른 시작](#빠른-시작)
- [AI 에이전트 빠른 시작 (반자동)](#ai-에이전트-빠른-시작-반자동)
- [수동 설치 (대안)](#수동-설치-대안)
- [1단계: 자동 설정 실행](#1단계-자동-설정-실행)
- [3단계: MCP 클라이언트 설정](#3단계-mcp-클라이언트-설정)
- [사용 가능한 도구](#사용-가능한-도구)
- [자동 프로젝트 관리 (신규)](#자동-프로젝트-관리-신규)
- [Stitch 핵심 도구 (API + 편의 래퍼)](#stitch-핵심-도구-api--편의-래퍼)
- [전문 웹 디자인 도구](#전문-웹-디자인-도구)
- [디자인 일관성 도구](#디자인-일관성-도구)
- [생산성 도구](#생산성-도구)
- [품질 및 분석 도구](#품질-및-분석-도구)
- [디자인 향상 도구](#디자인-향상-도구)
- [AI 이미지 생성 도구 (v1.1.0)](#ai-이미지-생성-도구-v110)
- [이미지 생성 지원 모델](#이미지-생성-지원-모델)
- [배경 제거 기능 (NEW)](#배경-제거-기능-new)
- [MCP Prompts (자동 검색)](#mcp-prompts-자동-검색)
- [커스텀 명령어 (멀티 CLI 지원)](#커스텀-명령어-멀티-cli-지원)
- [지원 CLI](#지원-cli)
- [사용 가능한 명령어](#사용-가능한-명령어)
- [CLI 사용 예시](#cli-사용-예시)
- [명령어 설치 위치](#명령어-설치-위치)
- [사용 예시](#사용-예시)
- [새 프로젝트 생성](#새-프로젝트-생성)
- [화면 생성](#화면-생성)
- [특정 스타일로 생성](#특정-스타일로-생성)
- [한국어 페이지 생성](#한국어-페이지-생성)
- [디자이너 플로우](#디자이너-플로우)
- [디자인 토큰 활용](#디자인-토큰-활용)
- [트렌딩 디자인 생성](#트렌딩-디자인-생성)
- [배치 화면 생성](#배치-화면-생성)
- [접근성 검사](#접근성-검사)
- [디자인 시스템 내보내기](#디자인-시스템-내보내기)
- [AI 이미지 생성 (v1.1.0 신규)](#ai-이미지-생성-v110-신규)
- [전체 디자인 오케스트레이션 (v1.1.0 신규)](#전체-디자인-오케스트레이션-v110-신규)
- [문제 해결](#문제-해결)
- ["gcloud: command not found"](#gcloud-command-not-found)
- ["Stitch API has not been used in project" 오류](#stitch-api-has-not-been-used-in-project-오류)
- [토큰 만료 / 인증 오류](#토큰-만료--인증-오류)
- [Google 로그인 후 "연결 거부" 페이지](#google-로그인-후-연결-거부-페이지)
- [브라우저가 자동으로 열리지 않음 (WSL)](#브라우저가-자동으로-열리지-않음-wsl)
- [전체 초기화](#전체-초기화)
- [아키텍처](#아키텍처)
- [파일 구조](#파일-구조)
- [설정 파일](#설정-파일)
- [스크립트](#스크립트)
- [요구 사항](#요구-사항)
- [보안 안내](#보안-안내)
- [라이선스](#라이선스)
- [크레딧](#크레딧)
- [지원](#지원)
---
## 사전 요구사항 (먼저 설치하세요)
### 1. Node.js 설치 (v18 이상)
#### Windows
```powershell
# winget 사용 (Windows 10/11)
winget install OpenJS.NodeJS.LTS
# 또는 https://nodejs.org/ 에서 설치 프로그램 다운로드
```
#### macOS
```bash
# Homebrew 사용
brew install node@22
# 또는 https://nodejs.org/ 에서 설치 프로그램 다운로드
```
#### Linux / WSL
```bash
# nvm 사용 (권장)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
# 또는 apt 사용 (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
```
**Node.js 설치 확인:**
```bash
node --version # v18.x.x 이상이어야 함
npm --version # 9.x.x 이상이어야 함
```
---
### 2. Google Cloud CLI (gcloud) 설치
#### Windows
**방법 A: 설치 프로그램 (권장)**
1. [Google Cloud SDK](https://cloud.google.com/sdk/docs/install)에서 다운로드
2. 설치 프로그램 실행 ("Run gcloud init" 옵션 체크)
3. 터미널 재시작
**방법 B: PowerShell**
```powershell
(New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:TEMP\gcloud.exe")
Start-Process "$env:TEMP\gcloud.exe" -Wait
# 설치 후 터미널 재시작
```
#### macOS
```bash
# Homebrew 사용 (권장)
brew install --cask google-cloud-sdk
# 또는 직접 설치
curl https://sdk.cloud.google.com | bash
exec -l $SHELL
```
#### Linux / WSL
```bash
# 다운로드 및 설치
curl -sSL https://sdk.cloud.google.com | bash -s -- --disable-prompts --install-dir=$HOME
# PATH에 추가
echo 'export PATH="$HOME/google-cloud-sdk/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
**gcloud 설치 확인:**
```bash
gcloud --version
# Google Cloud SDK xxx.x.x 형태로 출력되어야 함
```
---
## 빠른 시작
Node.js와 gcloud CLI 설치 후:
```bash
npx stitch-mcp-auto-setup
```
설정 마법사가 자동으로:
1. `http://localhost:51121`에서 웹 기반 설정 페이지 열기
2. Google 로그인 안내
3. 프로젝트 선택 또는 생성
4. Stitch API 활성화
5. 설정 저장
> **참고:** MCP 서버를 직접 실행(`npx stitch-mcp-auto` 또는 에디터에서 실행)하면 설정 마법사가 `http://localhost:8086`에서 열립니다.
> **🤖 AI 에이전트 참고 (WSL 환경):**
> WSL에서 실행 시 브라우저가 자동으로 열리지 않습니다. 터미널에 표시된 URL(보통 `http://localhost:51121` 또는 `http://localhost:8086`)을 Windows 브라우저로 여세요:
> ```powershell
> # PowerShell에서 실행 (WSL 터미널 아님)
> Start-Process "http://localhost:51121"
> # 8086이 표시될 경우:
> Start-Process "http://localhost:8086"
> ```
> 또는 사용자에게 표시된 URL을 Windows 브라우저에서 직접 열도록 안내하세요.
---
## 🤖 AI 에이전트 빠른 시작 (반자동)
이 저장소는 **반자동 설치**를 지원하며, 일부 단계는 수동 승인이 필요합니다 (OAuth 로그인).
**체크리스트 (에이전트용):**
1. 설정 실행: `npm run setup` (또는 `npx -p stitch-mcp-auto stitch-mcp-auto-setup`)
2. 터미널에 표시된 URL 열기 (보통 `http://localhost:51121`)
3. 브라우저에서 Google 로그인 완료 (gcloud + Stitch API 활성화)
4. **⚠️ 중요: MCP 등록 확인** (아래 참조)
5. 서버 시작: `npm start` 또는 에디터에서 자동 실행
**수동이 필요한 단계:**
- 브라우저 OAuth 동의 (Google 로그인)
- WSL 브라우저 열기 (URL 수동 입력)
**환경별 명령:**
- **Windows (PowerShell):**
- 설정 URL 열기: `Start-Process "http://localhost:51121"` (또는 `http://localhost:8086`)
- **macOS:**
- 설정 URL 열기: `open "http://localhost:51121"` (또는 `http://localhost:8086`)
- **Linux:**
- 설정 URL 열기: `xdg-open "http://localhost:51121"` (또는 `http://localhost:8086`)
- **WSL (Windows 호스트):**
- Windows PowerShell에서 실행: `Start-Process "http://localhost:51121"`
### ⚠️ 설치 후 MCP 등록 확인 (필수)
설정 완료 후 **반드시** MCP 서버가 등록되었는지 확인하세요:
```bash
# Claude Code
claude mcp list | grep stitch
# Gemini CLI
gemini mcp list | grep stitch
# Codex CLI
codex mcp list | grep stitch
```
**`stitch`가 목록에 없으면** 수동으로 등록:
| CLI | 수동 등록 명령 |
|-----|--------------|
| Claude Code | `claude mcp add -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID -s user stitch -- npx -y stitch-mcp-auto` |
| Gemini CLI | `gemini mcp add stitch -- npx -y stitch-mcp-auto --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID` |
| Codex CLI | `codex mcp add stitch -- npx -y stitch-mcp-auto --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID` |
> **확인이 필요한 이유:** 설정 마법사가 config 파일(`~/.claude.json`, `~/.gemini/settings.json`, `~/.codex/config.toml`)에 직접 등록하지만, 설정이 올바른지 확인하는 것이 좋습니다. "MCP 서버를 찾을 수 없음" 오류를 방지하려면 항상 확인하세요.
**기타 검증 (선택):**
- `node auth.js --status` (토큰 + 프로젝트 상태 확인)
- `npm start` (서버가 "Ready" 로그 출력)
---
## 수동 설치 (대안)
### 1단계: 자동 설정 실행
```bash
npx -p stitch-mcp-auto stitch-mcp-auto-setup
```
또는 저장소를 클론한 경우:
```bash
node setup.js
```
#### 설정 과정
1. **시작 페이지** - "Google로 로그인" 버튼 클릭
2. **Google 로그인** - 새 브라우저 창에서 인증 진행
- 로그인 후 "연결 거부" 페이지가 나오면 **그냥 닫으세요**
- 설정 페이지가 자동으로 로그인을 감지합니다
3. **프로젝트 선택** - 기존 프로젝트 선택 또는 새로 생성
4. **API 활성화** - 버튼을 클릭하여 Stitch API 활성화
- 활성화까지 몇 초 걸릴 수 있음
5. **완료** - MCP 설정을 복사하여 에디터에 추가
> **⚠️ WSL 사용자 - 중요:**
> WSL은 브라우저를 직접 열 수 없습니다. 설정 마법사가 시작되면:
> 1. URL `http://localhost:51121`을 복사하세요
> 2. **Windows 브라우저** (Chrome, Edge 등)에서 직접 열기
> 3. 또는 PowerShell에서 실행: `Start-Process "http://localhost:51121"`
>
> WSL과 Windows는 localhost를 공유하므로 인증이 정상 작동합니다.
---
### 3단계: MCP 클라이언트 설정
설정이 완료되면 MCP 클라이언트에 설정을 추가합니다.
#### Claude Desktop
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"stitch": {
"command": "npx",
"args": ["-y", "stitch-mcp-auto"],
"env": {
"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
}
}
}
}
```
#### Claude Code
**🌐 방법 1: CLI 명령어 (권장)**
설정 마법사가 자동으로 `~/.claude.json`에 등록합니다.
CLI로 수동 추가하려면:
```bash
claude mcp add -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID -s user stitch -- npx -y stitch-mcp-auto
```
또는 `~/.claude.json`을 직접 편집:
```json
{
"mcpServers": {
"stitch": {
"command": "npx",
"args": ["-y", "stitch-mcp-auto"],
"env": {
"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
}
}
}
}
```
**📁 방법 2: 프로젝트별 설정**
프로젝트 루트에 `.mcp.json` 파일 생성:
```json
{
"mcpServers": {
"stitch": {
"command": "npx",
"args": ["-y", "stitch-mcp-auto"],
"env": {
"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
}
}
}
}
```
#### Gemini CLI
**🌐 방법 1: CLI 명령어 (권장)**
```bash
gemini mcp add stitch -- npx -y stitch-mcp-auto --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
```
또는 `~/.gemini/settings.json`을 직접 편집:
```json
{
"mcpServers": {
"stitch": {
"command": "npx",
"args": ["-y", "stitch-mcp-auto"],
"env": {
"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
}
}
}
}
```
#### Codex CLI
**🌐 방법 1: CLI 명령어 (권장)**
```bash
codex mcp add stitch -- npx -y stitch-mcp-auto --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
```
또는 `~/.codex/config.toml`을 직접 편집:
```toml
[mcp_servers.stitch]
command = "npx"
args = ["-y", "stitch-mcp-auto"]
[mcp_servers.stitch.env]
GOOGLE_CLOUD_PROJECT = "YOUR_PROJECT_ID"
```
#### Cursor
**Settings > MCP > Add New Server**에서 추가:
- Command: `npx`
- Args: `-y stitch-mcp-auto`
- Environment: `GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID`
**선택 사항:** `GOOGLE_CLOUD_PROJECT`는 Stitch 이미지 폴백과 `auth.js --status`에서만 사용됩니다. 설정 마법사는 활성 프로젝트를 `~/.stitch-mcp-auto/config.json`에 저장하고, 워크스페이스 도구는 현재 폴더에 `.stitch-project.json`을 저장합니다.
---
## 사용 가능한 도구
### 🔄 자동 프로젝트 관리 (신규)
**더 이상 projectId를 수동으로 전달할 필요가 없습니다!** 서버가 자동으로 프로젝트 컨텍스트를 관리합니다:
1. **자동 감지**: `generate_screen_from_text` 등을 `projectId` 없이 호출하면 워크스페이스 프로젝트를 자동으로 사용
2. **자동 저장**: `create_project`로 프로젝트를 생성하면 현재 폴더의 `.stitch-project.json`에 자동 저장
3. **세션 연속성**: 같은 폴더로 돌아오면 프로젝트가 자동으로 로드됨
**동작 방식:**
```
┌─────────────────────────────────────────────────────────────┐
│ projectId 없이 도구 호출 │
│ ↓ │
│ 1. 현재 세션의 활성 프로젝트 확인 │
│ 2. 없으면 → .stitch-project.json에서 로드 │
│ 3. 없으면 → "PROJECT_REQUIRED" 오류와 옵션 반환 │
│ ↓ │
│ 사용자가 프로젝트 생성/선택 → 워크스페이스에 자동 저장 v │
└─────────────────────────────────────────────────────────────┘
```
**수동 워크스페이스 도구 (선택사항):**
| 도구 | 설명 |
|------|------|
| `get_workspace_project` | 🔍 현재 워크스페이스 프로젝트 상태 확인 |
| `set_workspace_project` | 💾 수동으로 프로젝트를 워크스페이스에 연결 |
| `clear_workspace_project` | 🗑️ 워크스페이스 프로젝트 연결 해제 |
### Stitch 핵심 도구 (API + 편의 래퍼)
| 도구 | 설명 |
|------|------|
| `create_project` | 새 Stitch 프로젝트를 생성합니다. 프로젝트는 UI 디자인과 프론트엔드 코드를 담는 컨테이너입니다. |
| `get_project` | 프로젝트 이름을 사용하여 특정 Stitch 프로젝트의 세부 정보를 조회합니다. |
| `list_projects` | 사용자가 접근 가능한 모든 Stitch 프로젝트를 나열합니다. 기본적으로 소유한 프로젝트를 표시합니다. |
| `list_screens` | 특정 Stitch 프로젝트 내의 모든 화면을 나열합니다. |
| `get_screen` | 프로젝트 내 특정 화면의 세부 정보를 조회합니다. |
| `generate_screen_from_text` | 텍스트 프롬프트를 기반으로 프로젝트 내에 새 화면을 생성합니다. |
| `fetch_screen_code` | 화면의 실제 HTML/코드 콘텐츠를 가져옵니다. |
| `fetch_screen_image` | 화면의 스크린샷/미리보기 이미지를 가져옵니다. |
### 🎨 전문 웹 디자인 도구
#### 디자인 일관성 도구
| 도구 | 설명 |
|------|------|
| `extract_design_context` | 기존 화면에서 디자인 DNA(색상, 타이포그래피, 간격, 컴포넌트)를 추출하여 여러 화면에서 시각적 일관성을 유지합니다. |
| `apply_design_context` | 추출된 디자인 컨텍스트를 사용하여 시각적 일관성을 유지하는 새 화면을 생성합니다. |
| `compare_designs` | 두 화면을 비교하여 디자인 차이점, 불일치 사항을 식별하고 조화로운 개선을 제안합니다. |
#### 생산성 도구
| 도구 | 설명 |
|------|------|
| `generate_design_tokens` | 화면 디자인에서 디자인 토큰(CSS 변수, Tailwind 설정, SCSS, JSON)을 생성합니다. |
| `generate_responsive_variant` | 다른 디바이스 타입을 위한 기존 화면의 반응형 변형을 생성합니다. |
| `batch_generate_screens` | 일관된 디자인으로 여러 관련 화면을 한 번에 생성합니다. |
#### 품질 및 분석 도구
| 도구 | 설명 |
|------|------|
| `analyze_accessibility` | WCAG 2.1 접근성 준수 여부를 분석하고 실행 가능한 권장 사항을 제공합니다. |
| `extract_components` | 재사용 가능한 UI 컴포넌트 패턴(버튼, 카드, 폼)과 스타일을 추출합니다. |
#### 디자인 향상 도구
| 도구 | 설명 |
|------|------|
| `suggest_trending_design` | 2024-2025 UI 트렌드(글래스모피즘, 벤토 그리드, 그라데이션 메시 등)를 화면 생성에 적용합니다. |
| `generate_style_guide` | 기존 디자인에서 종합적인 스타일 가이드/디자인 문서를 생성합니다. |
| `export_design_system` | 개발자 핸드오프를 위한 완전한 디자인 시스템 패키지(토큰, 컴포넌트, 문서)를 내보냅니다. |
### 🎨 AI 이미지 생성 도구 (v1.1.0)
각 도구는 다른 인증 요구사항을 가집니다:
| 도구 | 필요 인증 | 설명 |
|------|----------|------|
| `generate_design_asset` | **Antigravity** | Gemini 모델로 디자인 에셋(로고, 아이콘, 일러스트, 히어로, 와이어프레임, 배경, 패턴)을 생성합니다. **Antigravity 인증 필수.** 모델 선택 지원 (gemini-3-pro, gemini-2.5-pro) 및 강제 인증 지원. |
| `orchestrate_design` | Stitch + Antigravity | 전체 오케스트레이션: 에셋(로고, 아이콘, 히어로)을 자동 생성한 후 완전한 UI를 만듭니다. Stitch만 인증한 사용자도 커스텀 에셋 없이 UI 페이지 생성 가능. |
| `check_antigravity_auth` | 없음 | 이미지 생성 기능을 위한 Antigravity OAuth 인증 상태를 확인합니다. |
#### 이미지 생성 지원 모델
| 모델 | 상태 | 이미지 생성 | 설명 |
|------|------|-------------|------|
| `gemini-3-pro` | ✅ 사용 가능 | ✅ 지원 | **기본값.** 최신 Gemini 3 Pro 모델, 이미지 생성 지원 |
| `gemini-2.5-pro` | ✅ 사용 가능 | ✅ 지원 | Gemini 2.5 Pro 모델, 이미지 생성 지원 |
> **참고:** 전체 모델 목록/Thinking 변형/엔드포인트는 `ANTIGRAVITY-MODELS.md`(EN) / `ANTIGRAVITY-MODELS.ko.md`(KO) 참고.
> **💡 모델 선택:**
> `generate_design_asset` 호출 시 모델을 지정할 수 있습니다:
> ```json
> {
> "assetType": "logo",
> "prompt": "모던한 테크 회사 로고",
> "model": "gemini-3-pro"
> }
> ```
**주요 파라미터 (`generate_design_asset`):**
- `assetType`: logo, icon, illustration, hero, wireframe, background, pattern
- `aspectRatio`: 1:1, 16:9, 9:16, 4:3, 3:4
- `saveToFile`: 기본값 `true` (현재 디렉토리에 저장)
- `forceAntigravityAuth`: `true`면 브라우저 인증 강제
> **📋 역할 분리:**
> - **Stitch API (gcloud 인증):** UI 페이지/화면 생성 - 모든 사용자 이용 가능
> - **Antigravity OAuth:** 이미지 에셋 생성 (로고, 아이콘, 히어로) - 별도 인증 필요
>
> Stitch만 인증한 사용자도 `generate_screen_from_text`로 완전한 UI 페이지를 생성할 수 있습니다. Antigravity는 커스텀 AI 생성 에셋으로 이를 확장합니다.
#### 🔲 배경 제거 기능 (NEW)
`generate_design_asset`은 투명 에셋을 위한 자동 배경 제거를 지원합니다:
| 파라미터 | 타입 | 기본값 | 설명 |
|----------|------|--------|------|
| `removeBackground` | boolean | `false` | 자동 배경 제거 활성화 |
| `backgroundRemovalMode` | `"white"` \| `"auto"` | `"white"` | `white`: 흰색 배경 제거. `auto`: 단색 배경 자동 감지. |
| `backgroundThreshold` | number | `240` | 감지 임계값 (0-255). 높을수록 더 공격적. |
**예시:**
```json
{
"assetType": "logo",
"prompt": "추상적인 형태의 현대적인 테크 회사 로고",
"removeBackground": true,
"backgroundRemovalMode": "white",
"backgroundThreshold": 240
}
```
투명 PNG가 생성되어 다음 용도에 적합합니다:
- **로고** - 색상 배경에 배치해도 흰색 테두리 없음
- **아이콘** - UI 디자인에 깔끔하게 통합
- **일러스트** - 어떤 배경에도 자연스러운 오버레이
---
## MCP Prompts (자동 검색)
MCP Prompts는 서버가 연결되면 **자동으로 사용 가능**합니다 - 별도 설치가 필요 없습니다. MCP 클라이언트의 프롬프트 목록에 표시됩니다.
| 프롬프트 | 설명 |
|----------|------|
| `/stitch:design` | 자동 스타일 감지를 통한 스마트 UI 디자인 생성 |
| `/stitch:design-system` | 디자인 일관성을 유지하며 새 화면 생성 |
| `/stitch:design-flow` | 완전한 사용자 플로우를 위한 여러 화면 생성 |
| `/stitch:design-qa` | 접근성 (WCAG 2.1) 및 디자인 품질 검사 |
| `/stitch:design-export` | 개발자 핸드오프를 위한 디자인 시스템 패키지 내보내기 |
**Claude Code에서 사용:**
```
/stitch:design 다크 모드 로그인 페이지
/stitch:design-system 설정 페이지
/stitch:design-flow 온보딩: 환영 -> 가입 -> 완료
/stitch:design-qa all --level AA
/stitch:design-export --token_format tailwind
```
> **참고:** MCP Prompts에는 AI가 복잡한 디자인 작업을 자동으로 수행하도록 안내하는 상세한 워크플로우 지침이 포함되어 있습니다.
---
## 커스텀 명령어 (멀티 CLI 지원)
`npx -p stitch-mcp-auto stitch-mcp-auto-setup`을 실행하면 **커스텀 명령어**가 모든 주요 AI CLI 도구(Claude Code, Gemini CLI, Codex CLI)에 자동으로 설치됩니다.
### 지원 CLI
| CLI | 명령어 형식 | 설치 경로 |
|-----|------------|----------|
| **Claude Code** | `/design` | `~/.claude/commands/` |
| **Gemini CLI** | `/stitch:design` | `~/.gemini/commands/stitch/` |
| **Codex CLI** | `$stitch-design` | `~/.codex/skills/stitch/` |
### 사용 가능한 명령어
| 명령어 | Claude Code | Gemini CLI | Codex CLI | 설명 |
|--------|-------------|------------|-----------|------|
| design | `/design` | `/stitch:design` | `$stitch-design` | 스마트 UI 디자인 생성 |
| design-system | `/design-system` | `/stitch:design-system` | `$stitch-design-system` | 디자인 일관성 유지 |
| design-flow | `/design-flow` | `/stitch:design-flow` | `$stitch-design-flow` | 사용자 플로우 생성 |
| design-qa | `/design-qa` | `/stitch:design-qa` | `$stitch-design-qa` | 접근성 및 품질 검사 |
| design-export | `/design-export` | `/stitch:design-export` | `$stitch-design-export` | 디자인 시스템 내보내기 |
| generate-asset | `/generate-asset` | `/stitch:generate-asset` | `$stitch-generate-asset` | AI 이미지 생성 (v1.1.0) |
| design-full | `/design-full` | `/stitch:design-full` | `$stitch-design-full` | 전체 오케스트레이션 모드 (v1.1.0) |
### CLI 사용 예시
**Claude Code:**
```bash
/design login page dark mode
/design-system settings page
/design-flow onboarding: welcome -> signup -> complete
```
**Gemini CLI:**
```bash
/stitch:design login page dark mode
/stitch:design-system settings page
/stitch:design-flow onboarding: welcome -> signup -> complete
```
**Codex CLI:**
```bash
$stitch-design login page dark mode
$stitch-design-system settings page
$stitch-design-flow onboarding: welcome -> signup -> complete
```
### 명령어 설치 위치
명령어는 모든 CLI 디렉토리에 자동 설치됩니다:
```
~/.claude/commands/ # Claude Code (Markdown)
├── design.md
├── design-system.md
├── design-flow.md
├── design-qa.md
├── design-export.md
├── generate-asset.md # v1.1.0 신규
└── design-full.md # v1.1.0 신규
~/.gemini/commands/stitch/ # Gemini CLI (TOML)
├── design.toml
├── design-system.toml
├── design-flow.toml
├── design-qa.toml
├── design-export.toml
├── generate-asset.toml # v1.1.0 신규
└── design-full.toml # v1.1.0 신규
~/.codex/skills/stitch/ # Codex CLI (Skills)
├── design.md
├── design-system.md
├── design-flow.md
├── design-qa.md
├── design-export.md
├── generate-asset.md # v1.1.0 신규
└── design-full.md # v1.1.0 신규
```
---
## 사용 예시
### 새 프로젝트 생성
```
"내 앱"이라는 새 Stitch 프로젝트를 만들어줘
```
### 화면 생성
```
이메일과 비밀번호 입력 필드,
"비밀번호 찾기" 링크,
Google과 Apple 소셜 로그인 버튼이 있는 로그인 페이지를 만들어줘.
모던한 그라데이션 배경을 사용해.
```
### 특정 스타일로 생성
```
다음 요소가 있는 대시보드 화면을 만들어줘:
- 다크 테마
- 사이드바 네비게이션
- 상단에 4개의 통계 카드
- 주간 데이터를 보여주는 라인 차트
- 최근 활동 목록
```
### 한국어 페이지 생성
```
다음 요소가 포함된 한국어 쇼핑몰 상품 상세 페이지를 만들어줘:
- 상품 이미지 캐러셀
- 가격 및 할인 배지
- 사이즈 선택기
- 장바구니 담기 버튼
- 고객 리뷰 섹션
```
### "디자이너 플로우"
여러 화면에서 일관된 UI를 위해:
1. **기존 화면에서 디자인 컨텍스트 추출:**
```
프로젝트 X의 홈 스크린에서 디자인 컨텍스트를 가져와줘
```
2. **같은 스타일로 새 화면 생성:**
```
그 디자인 컨텍스트를 사용해서 같은 비주얼 스타일의 설정 화면을 생성해줘
```
### 디자인 토큰 활용
개발 워크플로우에 맞는 디자인 토큰 내보내기:
```
대시보드 화면의 디자인에서 CSS 변수를 생성해줘
```
```
홈 화면을 기반으로 Tailwind 설정을 만들어줘
```
### 트렌딩 디자인 생성
최신 UI/UX 트렌드 자동 적용:
```
글래스모피즘과 그라데이션 메시 효과를 적용한 가격 페이지를 만들어줘
```
```
벤토 그리드 레이아웃과 다크 모드를 사용한 대시보드를 디자인해줘
```
### 배치 화면 생성
일관된 스타일로 여러 화면을 한 번에 생성:
```
완전한 온보딩 플로우를 생성해줘: 환영, 기능 소개, 가입, 확인 화면
```
### 접근성 검사
디자인의 접근성 확보:
```
로그인 페이지가 WCAG AA를 준수하는지 확인해줘
```
### 디자인 시스템 내보내기
개발자 핸드오프를 위한 내보내기:
```
이 프로젝트의 완전한 디자인 시스템을 토큰과 컴포넌트 포함해서 내보내줘
```
### AI 이미지 생성 (v1.1.0 신규)
AI로 디자인 에셋 생성:
```
/generate-asset logo "친환경 유기농 식품 배달 서비스 GreenBite"
```
```
/generate-asset hero "금융 성장을 보여주는 모던한 핀테크 앱" --style gradient --ratio 16:9
```
```
/generate-asset icon "체크마크가 있는 쇼핑 카트" --style flat --colors "#4CAF50"
```
### 전체 디자인 오케스트레이션 (v1.1.0 신규)
한 번의 프롬프트로 완전한 디자인 - 자동으로 에셋을 생성하고 UI를 만듭니다:
```
/design-full "친환경 유기농 식품 쇼핑몰 메인 페이지. 녹색 테마, 신선한 느낌, 모던한 디자인"
```
```
/design-full "AI 기반 프로젝트 관리 도구 랜딩 페이지. 전문적인 느낌, 블루 그라데이션 테마, 가격 섹션 포함"
```
> **참고:** 오케스트레이션 모드는 자동으로:
> 1. 필요한 에셋 분석 (로고, 히어로, 아이콘)
> 2. Gemini 3 Pro로 각 에셋 생성 (Antigravity 인증 필요)
> 3. Stitch API로 완전한 UI 화면 생성
> 4. 모든 에셋 + 최종 UI를 한 번에 반환
>
> **Antigravity 미인증 시:** UI 화면은 생성되지만, 커스텀 이미지 에셋 없이 생성됩니다.
---
## 문제 해결
### "gcloud: command not found"
**Linux/macOS/WSL:**
```bash
export PATH="$HOME/google-cloud-sdk/bin:$PATH"
echo 'export PATH="$HOME/google-cloud-sdk/bin:$PATH"' >> ~/.bashrc
```
**Windows:** gcloud 설치 후 터미널을 재시작하세요.
---
### "Stitch API has not been used in project" 오류
API를 수동으로 활성화:
```bash
gcloud services enable stitch.googleapis.com --project=YOUR_PROJECT_ID
```
또는 방문: `https://console.cloud.google.com/apis/library/stitch.googleapis.com?project=YOUR_PROJECT_ID`
---
### 토큰 만료 / 인증 오류
인증 갱신:
```bash
gcloud auth login
```
또는 설정 재실행:
```bash
npx -p stitch-mcp-auto stitch-mcp-auto-setup
```
---
### Google 로그인 후 "연결 거부" 페이지
이것은 **정상적인 동작**입니다. Google 인증이 완료되면 브라우저가 gcloud가 사용하는 임시 콜백 서버인 `localhost:8085`로 리다이렉트됩니다. 인증이 완료되면 이 서버는 종료됩니다.
**해결:** 이 탭을 닫고 설정 페이지로 돌아가세요. 자동으로 로그인을 감지합니다.
---
### 브라우저가 자동으로 열리지 않음 (WSL)
WSL에서 브라우저가 자동으로 열리지 않으면:
1. 터미널에 표시된 URL을 복사
2. Windows 브라우저에 수동으로 붙여넣기
3. 로그인 완료
4. 설정 페이지로 돌아가기
---
### 전체 초기화
문제가 발생하면 모든 것을 초기화:
```bash
# stitch-mcp-auto 설정 삭제
rm -rf ~/.stitch-mcp-auto
# gcloud 자격 증명 취소
gcloud auth revoke --all
# 설정 재실행
npx -p stitch-mcp-auto stitch-mcp-auto-setup
```
---
## 아키텍처
```
┌──────────────────────────────────────────────────────────────┐
│ 사용자 요청 │
│ "로그인 페이지를 만들어줘..." │
│ "/design-full 친환경 쇼핑몰" │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ AI 에디터 (Claude/Cursor) │
│ MCP 클라이언트 │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ stitch-mcp-auto │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ setup.js │ │ index.js │ │ auth.js │ │
│ │ (자동 설정) │ │ (MCP 서버) │ │ (OAuth) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 디자인 도구 │ │ 이미지 생성 │ │ 오케스트레이션 │ │
│ │ (UI+QA) │ │ (Antigrav.) │ │ (에셋+UI) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
┌─────────────────┼─────────────────┐
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ Google Cloud Platform │ │ Antigravity (선택사항) │
│ ┌─────────┐ ┌─────────┐ │ │ ┌─────────────────────┐ │
│ │ gcloud │ │ Stitch │ │ │ │ Gemini 3 Pro │ │
│ │ CLI │ │ API │ │ │ │ (이미지 생성) │ │
│ │ (인증) │ │ (UI생성) │ │ │ │ OAuth를 통해 무료 │ │
│ └─────────┘ └─────────┘ │ │ └─────────────────────┘ │
└─────────────────────────────┘ └─────────────────────────────┘
```
> **📋 역할 분리:**
> - **Stitch API (gcloud):** 모든 UI 페이지/화면 생성 담당
> - **Antigravity OAuth:** 이미지 에셋 생성 담당 (로고, 아이콘, 히어로 이미지)
>
> Antigravity 인증 없이 `generate_design_asset`을 사용하면 에러가 반환됩니다. UI 페이지는 Stitch의 `generate_screen_from_text`를 사용하세요.
### 파일 구조
```
stitch-mcp-auto/
├── index.js # 메인 MCP 서버 (Antigravity OAuth 포함)
├── setup.js # 웹 기반 자동 설정 마법사
├── auth.js # OAuth 헬퍼 유틸리티
├── package.json # 의존성 및 스크립트
├── README.md # 영문 문서
├── README.ko.md # 한국어 문서
├── ANTIGRAVITY-MODELS.md # Antigravity 모델 목록 (EN)
├── ANTIGRAVITY-MODELS.ko.md # Antigravity 모델 목록 (KO)
├── AGENTS.md # 저장소 가이드
└── skills/ # 명령어 소스(Claude/Gemini/Codex)
├── design.md
├── design-system.md
├── design-flow.md
├── design-qa.md
├── design-export.md
├── generate-asset.md # 신규: AI 이미지 생성
└── design-full.md # 신규: 전체 오케스트레이션
```
### 설정 파일
| 파일 | 위치 | 용도 |
|------|------|------|
| `tokens.json` | `~/.stitch-mcp-auto/` | OAuth 액세스 토큰 (gcloud) |
| `antigravity_tokens.json` | `~/.stitch-mcp-auto/` | Antigravity OAuth 토큰 (선택사항) |
| `config.json` | `~/.stitch-mcp-auto/` | 프로젝트 설정 |
| `.stitch-project.json` | 워크스페이스 루트(AI CLI 실행 폴더) | 워크스페이스용 프로젝트 매핑(자동 저장) |
| **MCP 설정** | | |
| `.claude.json` | `~/` | Claude Code MCP 서버 (user scope) |
| `settings.json` | `~/.gemini/` | Gemini CLI MCP 서버 |
| `config.toml` | `~/.codex/` | Codex CLI MCP 서버 (TOML 형식) |
| **명령어** | | |
| `commands/` | `~/.claude/commands/` | Claude Code 명령어 (자동 설치) |
| `commands/stitch/` | `~/.gemini/commands/stitch/` | Gemini CLI 명령어 (자동 설치) |
| `skills/stitch/` | `~/.codex/skills/stitch/` | Codex CLI 스킬 (자동 설치) |
---
## 스크립트
| 명령 | 설명 |
|------|------|
| `npm start` | MCP 서버 시작 (`node index.js`) |
| `npm run setup` | 설정 마법사 실행 (`node setup.js`, `http://localhost:51121` 열림) |
| `npm run auth -- --status|--login|--logout|--setup|--project <id>` | OAuth 헬퍼 명령 |
| `npx -p stitch-mcp-auto stitch-mcp-auto-setup` | 대화형 설정 마법사 실행 |
| `npx stitch-mcp-auto` | MCP 서버 시작 (에디터에서 사용) |
| `node auth.js --status` | 인증 상태 확인 |
| `node auth.js --login` | 수동 로그인 |
| `node auth.js --logout` | 저장된 토큰 삭제 |
| `node auth.js --setup` | OAuth 설정 가이드 출력 |
| `node auth.js --project <id>` | 프로젝트 ID 저장(선택사항) |
---
## 요구 사항
- **Node.js:** 18.0.0 이상
- **Google Cloud CLI:** 최신 버전
- **Google 계정:** Google Cloud Console 접근 권한 필요
- **MCP 클라이언트:** Claude Desktop, Claude Code, Cursor 또는 호환 에디터
---
## 보안 안내
이 프로젝트는 인증을 위해 Google의 공개 OAuth 클라이언트를 사용합니다. 소스 코드에 보이는 클라이언트 ID는 **의도적으로 공개된 것**입니다 (OAuth 2.0 스펙에 따른 Desktop App 타입). 토큰은 `~/.stitch-mcp-auto/`에 로컬로 저장되며 제3자에게 전송되지 않습니다.
---
## 라이선스
**Apache 2.0** - 오픈 소스, 무료 사용 가능
---
## 크레딧
- **제작자:** [GreenSheep01201 (Wongil Seo)](https://github.com/GreenSheep01201)
- **원본 컨셉:** Aakash Kargathara [stitch-mcp](https://github.com/Kargatharaakash/stitch-mcp)
---
## 지원
- **이슈:** [GitHub Issues](https://github.com/GreenSheep01201/stitch-mcp-auto/issues)
- **문서:** [Google Stitch API](https://cloud.google.com/stitch)
---
*AI 커뮤니티를 위해 사랑을 담아 제작*
