# Design Gallery

> design.gujo.ai 의 화면 갤러리와 문서, 디자인 MCP, 에이전트 토큰. 무엇이 공개이고 무엇에 로그인이나 토큰이 필요한지.

[design.gujo.ai](https://design.gujo.ai) 는 디자인 토큰·컴포넌트·패턴 문서와 실제 앱 화면 갤러리를 보여 줍니다. 사람은 브라우저로 보고, 에이전트는 같은 내용을 디자인 MCP 와 에이전트 API 로 읽습니다.

## 무엇에 무엇이 필요한가

| 내용 | 사람(브라우저) | 에이전트 |
|---|---|---|
| 랜딩, 스타일, 토큰, 컴포넌트, 패턴 문서, MCP 안내(`GET /mcp`) | 누구나 | 누구나 |
| 실화면 갤러리: 탐색, 화면과 화면 코드, 제품, 브랜드, 앱, 검색과 검색 제안, 리서치, 에이전트 소개, 디자인 이미지, 코드 자산 | 로그인한 Gujo 회원 | `read` 역할 토큰 |
| 화면 갤러리 JSON(`/api/v1/*`) | 로그인한 Gujo 회원 | `read` 역할 토큰 |
| 디자인 MCP(`POST /mcp`) | 없음 | `read` 역할 토큰만 |
| 문서 읽기(`/api/agent/manifest`, `docs/{slug}`, `docs/{slug}/versions`) | 로그인한 Gujo 회원 | `read` 역할 토큰 |
| 문서 쓰기·제출 | 없음 | `write` 역할 토큰만 |
| 문서 검수 | 없음 | `review` 역할 토큰만 |
| 원격 수집(`/api/agent/collect/*`) | 없음 | `collect` 역할 토큰만 |

- 실화면 갤러리는 Gujo 계정으로 로그인한 회원이면 누구나 봅니다. 로그인하지 않은 사람이 화면을 열면 로그인 벽이 나오고, 로그인한 뒤 원래 주소로 돌아옵니다. JSON 과 이미지 요청은 401 JSON 을 받습니다.
- 공개 문서 화면 안에 들어 있는 실화면 그리드는 로그인했거나 토큰이 있을 때만 보입니다.
- 근거는 판결 2026-mr329 입니다.

## 에이전트 토큰

에이전트는 디자인 에이전트 토큰을 `Authorization: Bearer <토큰>` 으로 보냅니다. 이 토큰은 계정 API 키와 다른 자격입니다.

| 역할 | 할 수 있는 일 |
|---|---|
| `read` | 디자인 MCP, 실화면 갤러리와 화면 JSON, 문서 읽기 |
| `write` | 문서의 새 판 만들기와 검수 제출 |
| `review` | 검수 대기 목록과 검수 기록 |
| `collect` | 원격 수집 실행 열기, 캡처·자산 올리기, 제출 |

- 토큰은 Gujo 스태프가 에이전트마다 발급하고 폐기합니다. 회원이 직접 발급하는 화면은 없습니다. [확인 필요] 외부 개발자가 토큰을 요청하는 창구.
- 토큰이 없거나, 모르는 토큰이거나, 폐기된 토큰이면 401 입니다. 역할이 모자라면 403 입니다.
- 토큰을 내밀었으면 로그인 세션이 있어도 토큰이 판정합니다. 틀린 토큰은 세션이 있어도 401 입니다.

## 디자인 MCP

| 항목 | 값 |
|---|---|
| 주소 | `POST https://design.gujo.ai/mcp` |
| 인증 | `read` 역할 디자인 에이전트 토큰. 없으면 401 |
| 형식 | JSON-RPC 2.0. 요청 하나에 JSON 응답 하나이고 SSE 는 없습니다 |
| 메서드 | `initialize`, `tools/list`, `tools/call`, `ping` |

클라이언트 설정은 [MCP 연결하기](mcp/index.md)의 디자인 MCP 탭에 있고, 토큰은 `GUJO_DESIGN_TOKEN` 환경 변수에 둡니다.

도구는 읽기 전용 13개입니다.

| 영역 | 도구 |
|---|---|
| 제품·브랜드 | `gujo_search_products`, `gujo_get_brand` |
| 스타일 | `gujo_search_styles`, `gujo_get_style` |
| 화면 | `gujo_search_screens`, `gujo_get_screen`, `gujo_get_screen_image`, `gujo_get_screen_code`, `gujo_get_code_asset`, `gujo_get_similar_screens` |
| 흐름 | `gujo_search_flows`, `gujo_get_flow` |
| 리서치 | `gujo_research` |

`gujo_get_*` 도구는 한 번에 10건까지 묶어 받습니다.

프로토콜 세부:

- `initialize` 는 요청한 프로토콜 버전을 알면 그 버전으로, 모르면 서버가 아는 최신 버전으로 답합니다.
- `MCP-Protocol-Version` 머리글이 모르는 값이면 400 입니다.
- 알림과 응답 메시지는 202 빈 본문, JSON 이 아니면 `-32700`, 배치 요청은 `-32600` 입니다.
- 모르는 메서드나 도구는 JSON-RPC 오류이고, 도구 실행 실패는 `result.isError` 입니다.
- `GET /mcp` 는 사람용 안내 화면입니다. `Accept: text/event-stream` 으로 탐침하면 405 와 `Allow: POST` 를 받습니다.

## 문서 API

`https://design.gujo.ai/api/agent/*` 는 디자인 문서를 판(version) 단위로 읽고 씁니다.

- 목록은 한 쪽에 24개이고 `{data: [...], meta: {...}}` 꼴입니다.
- 낡은 `base_version` 위에 새 판을 만들면 409, 다른 에이전트가 쓴 초안을 제출하면 403 입니다.
- 원격 수집은 실행을 연 에이전트만 이어 갈 수 있고, 다른 실행이 수집 중이면 열기가 409 입니다. 캡처와 자산은 `multipart/form-data` 로 올립니다.

경로와 입력 칸 전체는 [API 참조](api-reference.md)의 `design` 묶음에 있습니다.