아키텍처#

이 문서는 Figma Agent Kit의 구조(패키지, 런타임 역할, 데이터 경로, 설계 원칙)를 설명합니다.

#목표

• AI 에이전트(Cursor, Claude Code, Codex, …)가 Figma Desktop에서 현재 열린 Figma 파일을 읽고 쓸 수 있게 합니다
• 캔버스 트래픽을 localhost에 유지합니다 — 브리지 도구는 Figma REST로 문서를 업로드하지 않습니다
• 단일 브리지 포트에서 Leader / Follower 선출을 통해 여러 MCP 클라이언트를 동시에 지원합니다
• MCP 자격 증명과 독립적인 선택 사항의 플러그인 내 AI 경로(이름 변경 / 그룹화)를 제공합니다

#모노레포 구조

figma-agent-kit/
├── bridge.config.json          # Single source of truth for default WS port (1998)
├── packages/
│   ├── figma-agent-mcp/        # npm: stdio MCP + HTTP/WS bridge server
│   └── figma-agent-plugin/     # Figma Desktop plugin (bridge client + AI + slice export)
├── scripts/
│   ├── sync-bridge-config.mjs  # Sync port → MCP + plugin + manifest
│   └── release-kit.mjs         # Co-release MCP + plugin at the same version
└── docs/                       # This documentation set

버전은 함께 관리됩니다(0.1.x). 한쪽만 릴리스하는 대신 pnpm release:kit:* 사용을 권장합니다.

#시스템 개요

종단 간 흐름:

1. 에이전트가 stdio를 통해 figma-agent-mcp 프로세스와 MCP로 통신합니다.
2. 이 프로세스는 Leader(localhost:PORT 바인딩) 또는 Follower(Leader로 전달)입니다.
3. 플러그인 UI iframe은 Leader에 WebSocket을 열고 MessagePack으로 통신합니다.
4. UI는 RPC를 플러그인 main 스레드로 전달하고, 이 스레드는 Figma Plugin API(documentAccess: dynamic-page)를 호출합니다.

#기술 스택

#모듈 맵(MCP)

#모듈 맵(플러그인)

#Leader / Follower 선출

여러 에이전트 창은 종종 여러 MCP 프로세스를 실행합니다. 브리지 포트는 하나의 프로세스만 바인딩할 수 있습니다.

• Leader: 포트를 바인딩하고 플러그인 소켓을 수락하며 탐색 + RPC를 처리합니다.
• Follower: 모든 도구 호출을 Leader의 POST /rpc(MsgPack)로 전달하고, list_files는 GET /files로 처리합니다.
• 상태 폴링(~3–5초): Leader가 종료되면 Follower가 선출을 재시도하여 인계할 수 있습니다.

#RPC 경로(도구 호출)

주요 세부 사항:

• 와이어 도구 이름은 type 또는 tool로 표시될 수 있습니다.
• 스크린샷 data는 브리지에서 base64가 아닌 원본 PNG 바이트(MsgPack bin)입니다.
• 로그는 stderr로만 출력합니다. stdout은 MCP stdio용으로 예약됩니다.

#스크린샷 및 슬라이스 내보내기 경로

#두 가지 AI 경로

MCP 브리지 도구에는 LLM API 키가 필요하지 않습니다. 선택 사항인 이름 변경/그룹화 AI는 플러그인 UI 내부에서만 실행됩니다.

#포트 구성

1. 루트 bridge.config.json의 defaultPort를 편집합니다.
2. pnpm sync:bridge를 실행합니다(predev / prebuild에서도 실행됨).
3. 플러그인을 다시 빌드하고 MCP를 다시 시작합니다.

MCP 전용 런타임 재정의인 FIGMA_AGENT_MCP_PORT는 플러그인 manifest / UI에 포함된 포트와 일치해야 합니다.

#원칙

1. Local-first — 브리지 트래픽은 localhost에 머무르며, MCP 도구용 디자인 데이터는 업로드되지 않습니다.
2. 핫 패스의 MsgPack — WS + follower RPC에는 MsgPack을 사용하며, 작은 탐색 엔드포인트는 JSON을 유지합니다.
3. Stdout 순수성 — MCP 프로세스에서 stdout에 진단 정보를 출력하지 않습니다.
4. 비동기 노드 조회 — dynamic-page 플러그인은 figma.getNodeByIdAsync를 사용합니다.
5. 버전 동시 릴리스 — 프로토콜 변경 후 플러그인과 MCP를 함께 업그레이드합니다.
6. 기능 정직성 — Motion 도구에는 motion API를 노출하는 Figma 빌드가 필요하며, 그렇지 않으면 명확한 오류를 반환합니다.

#추가 읽을거리

• 브리지 프로토콜 — 와이어 형식 및 엔드포인트
• MCP 도구 — 전체 도구 카탈로그
• 시작하기 — 설치 및 연결
• FAQ — 일반적인 실패 모드