figma-bridge-mcp

로컬 MCP 서버로, AI 어시스턴트가 Figma Desktop에서 디자인을 검사하고, 생성하고, 업데이트할 수 있게 해줍니다. 작은 Figma 개발 플러그인을 통해 연결되며, 스크린샷, 디자인 사양, JSX 렌더링, 토큰, 에셋, 컴포넌트, FigJam 및 Figma Slides를 위한 집중된 도구를 제공합니다.

모든 것은 127.0.0.1에서 실행됩니다. Figma 개인 액세스 토큰이 필요하지 않습니다. 클라우드가 없습니다. Figma 앱의 바이너리 패치가 없습니다.

선택적 REST 애드온은 버전 기록, 댓글 및 게시된 라이브러리 메타데이터를 추가합니다. 해당 Figma 토큰은 사용자 기기에 남아 있으며 MCP 클라이언트 구성이나 채팅에 절대 저장되지 않습니다.

요구 사항: Node.js 18 이상, Figma Desktop, 로컬 stdio 서버를 시작할 수 있는 MCP 클라이언트.

Codex, Claude Code 및 Cursor: 하나의 번들로 제공되는 MCP 및 스킬

Figma Bridge는 세 가지 집중된 공유 스킬과 세 클라이언트 모두를 위한 얇은 플러그인 어댑터를 제공합니다.

• figma-bridge-design-to-code — 대상 스택의 정확한 Figma 구현

• figma-bridge-code-to-figma — 코드로부터의 의미론적, 컴포넌트화된 화면

• figma-bridge-component-library — 토큰, 스타일, 컴포넌트, 변형 및 속성

어댑터는 모두 동일한 skills/ 디렉토리를 발견하고 동일한 로컬 MCP 패키지를 시작합니다. 사용자는 스킬을 별도로 다운로드하거나 유지 관리할 필요가 없습니다.

Codex의 경우, 이 저장소를 마켓플레이스로 추가하고 번들을 설치하십시오:

codex plugin marketplace add KaiUweHella/figma-bridge-mcp
codex plugin add figma-bridge-mcp@figma-bridge

이는 GitHub에서 호스팅되는 저장소 마켓플레이스이며, 범용 OpenAI 플러그인 디렉토리에 제출된 것이 아닙니다. 카탈로그는 저장소를 따르며, 각 릴리스된 플러그인 항목은 정확한 v<version> Git 태그를 고정하고 일치하는 npm 런타임 버전을 시작합니다. 따라서 main과 @latest는 설치된 스킬 번들을 다른 서버 계약으로 자동 이동시킬 수 없습니다.

Claude Code의 경우, 이 저장소를 마켓플레이스로 추가하고 번들을 설치하십시오:

claude plugin marketplace add KaiUweHella/figma-bridge-mcp
claude plugin install figma-bridge-mcp@figma-bridge

Claude 마켓플레이스는 동일한 고정 GitHub 릴리스와 공유 스킬 트리를 사용합니다. 일치하는 npm 패키지는 사용자가 해당 릴리스를 설치하기 전에 게시되어야 합니다. 플러그인이 npx를 통해 로컬 stdio 서버를 시작하기 때문입니다.

Cursor Teams 또는 Enterprise의 경우, 이 GitHub 저장소를 팀 마켓플레이스로 가져오고 Customize에서 Figma Bridge를 설치하십시오. 개별 사용자와 기여자는 중앙 Cursor 목록 없이 동일한 GitHub 소스를 사용할 수 있습니다: 태그가 지정된 릴리스를 클론하고, 해당 체크아웃을 Cursor에 연결한 후 창을 다시 로드하십시오:

mkdir -p ~/.cursor/plugins/local
ln -s /absolute/path/to/figma-bridge-mcp ~/.cursor/plugins/local/figma-bridge-mcp

Cursor는 루트 Agent Plugin 매니페스트를 감지하고 스킬과 MCP 서버를 모두 로드합니다.

플러그인 또는 Agent Skill을 지원하지 않는 클라이언트는 아래의 일반 서버 구성을 계속 사용합니다. MCP 명령어, 사용자가 호출하는 design-to-code, code-to-figma, create-figma-component MCP 프롬프트 및 figma_reference {name:"workflow"}를 통해 간결한 필수 워크플로우를 계속 제공받습니다.

빠른 시작

1. MCP 서버 추가 (MCP 전용 폴백)

전체 플러그인 설치가 불가능하거나 번들 스킬 없이 MCP 도구만 필요한 경우 이 방법을 사용하십시오. npx 설정은 클론이나 빌드 단계가 필요 없습니다. Claude Code의 경우:

claude mcp add figma-bridge -- npx -y figma-bridge-mcp@latest

다른 MCP 클라이언트의 경우, 동등한 서버 구성을 추가하십시오:

{
  "mcpServers": {
    "figma-bridge": {
      "command": "npx",
      "args": ["-y", "figma-bridge-mcp@latest"]
    }
  }
}

MCP 클라이언트가 서버를 즉시 발견하지 못하면 다시 시작하십시오. 의도적으로 env 블록이 없습니다: 브릿지는 페어링 중에 로컬 자격 증명을 생성합니다.

git clone https://github.com/KaiUweHella/figma-bridge-mcp.git
cd figma-bridge-mcp
npm install

{
  "mcpServers": {
    "figma-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/figma-bridge-mcp/src/server.js"]
    }
  }
}

2. Figma Desktop을 한 번 페어링

1. AI 어시스턴트에게 Figma에 연결하도록 요청하거나, figma_connect를 직접 호출하십시오. 로컬 브릿지를 시작하고 액세스 키와 플러그인 매니페스트 경로를 반환합니다.

2. Figma Desktop에서: Plugins → Development → Import plugin from manifest…를 선택하고 ~/.figma-bridge-mcp/plugin/manifest.json (figma_connect가 반환한 경로)을 선택하십시오.

3. Plugins → Development → Figma Bridge를 열고 액세스 키를 붙여넣은 후 Save & connect를 클릭하십시오.

4. 플러그인이 **Connected (authenticated)**를 표시하면, 어시스턴트가 해당 Figma 파일로 작업할 수 있습니다. 페어링은 기억됩니다; 이후 세션에서는 사용하려는 파일에서 플러그인을 다시 열기만 하면 됩니다.

Figma Dev Mode는 별도의 어댑터가 필요합니다. Figma가 기존 FigJam 편집기 대상을 dev와 하나의 매니페스트에서 결합하는 것을 지원하지 않기 때문입니다:

• Figma Bridge Dev Mode의 경우 ~/.figma-bridge-mcp/plugin/manifest.dev.json을 가져오십시오. 인증된 MCP 브릿지를 선택, 검사, 사양 및 내보내기에 연결된 상태로 유지합니다. Dev Mode는 읽기 전용이므로, 렌더링 및 캔버스 편집은 여전히 파일을 Design 모드로 전환하고 일반 Figma Bridge 플러그인을 거기서 열어야 합니다.

3. Figma와 함께 사용

Figma에서 프레임 또는 레이어를 선택하고 원하는 결과를 설명하십시오. 예를 들어:

• "현재 선택 영역을 검사하고 레이아웃을 설명해줘."

• "선택한 프레임 옆에 설정 카드를 만들어줘."

• "선택한 화면의 토큰과 에셋을 이 프로젝트로 내보내줘."

• "선택한 프레임을 구현한 다음, 결과를 Figma와 비교해줘."

어시스턴트는 현재 선택 영역을 읽고, 스크린샷과 사양을 캡처하고, JSX를 렌더링하고, 에셋을 내보내거나, 대상 편집을 적용할 수 있습니다. 어시스턴트가 액세스해야 하는 모든 문서에서 Figma Bridge 플러그인을 열어 두십시오. 둘 이상의 문서가 연결된 경우, 대상이 명확하도록 Figma URL 또는 파일 키를 전달하십시오.

Related MCP server: tellfigma

작동 방식

MCP client ──stdio──▶ figma-bridge-mcp (src/)
                        │
                    MCP tool adapters ─▶ Capability Catalog ─▶ CommandPlan
                                                                  │
                                          ┌───────────────────────┴──────────┐
                                  Command Application Modules   generic CLI adapter
                                             │            │
                                      Design Capture      │
                                      Asset Policy        │
                                             └──────┬─────┘
                                      Daemon Client Module
                                             │  HTTP: signed requests
                                             ▼
                                  local daemon :3456–3460
                                             │  WS: challenge/response
                                             ▼
                                  Figma Bridge plugin in Figma Desktop

• 엔진은 engine/ 아래에 있습니다. figma-ds-cli v2.1.0의 포크로 시작되었으며 그 이상으로 분기되었습니다(귀속 참조). Figma 앱 바이너리를 패치하는 Chrome DevTools "Yolo 모드"는 완전히 제거되었습니다. 해당 코드 경로는 존재하지 않습니다.

• 특수화된 MCP 읽기(figma_spec, figma_inspect, figma_screenshot)는 값을 반환하는 Command Application Modules을 통해 직접 실행됩니다. MCP와 CLI는 동일한 구현 위의 얇은 어댑터입니다. 일반적인 figma_run은 의도적으로 광범위한 하위 프로세스 CLI 어댑터로 남아 있습니다. 하나의 Daemon Client Module이 두 경로 모두에 대한 서명, 시간 초과 및 전송 오류를 관리합니다.

• Design Capture Module은 명시적 노드를 한 번 탐색하고 동일한 사실로부터 구조, 스타일 및 무손실 출력 형식을 로컬에서 투영합니다. 캡처는 저렴한 개정 프로브가 인증된 플러그인 연결과 Figma 문서 개정이 변경되지 않았음을 증명한 후에만 재사용됩니다. 누락되거나 불안정한 개정 메타데이터는 재사용을 비활성화합니다. 선택 및 명명된 섹션 호출은 이 첫 번째 Slice에서 캐시되지 않은 상태로 유지됩니다. 캡처는 작성된 Figma Auto Layout/Grid, Figma의 표시된 inferredAutoLayout 휴리스틱 및 지오메트리 폴백을 구분합니다. 또한 Code-to-Figma 의미론적/폴백 메타데이터를 이후의 기본 Figma 주석 및 전체 컴포넌트 및 변수-모드 계약과 별도로 보존합니다.

• Design Link Registry는 컴포넌트, 화면 또는 프레임에 하나의 내구성 있는 저장소 소유 Design Entity ID를 부여합니다. figma-bridge.json은 이식 가능한 코드/Storybook/Figma 링크를 보유합니다. Figma 플러그인 데이터는 동일한 ID와 종류만 보유합니다. 이 이중 앵커는 향후 에이전트가 저장소 경로를 Figma 문서에 넣지 않고도 양쪽에서 정확한 기존 컴포넌트를 확인할 수 있게 해줍니다.

• 보고 전용 Round-trip Planner는 현재 코드와 현재 정규화된 Figma 하위 트리를 명시적으로 Accepted Design Baseline과 비교합니다. Project Design Context는 해당 상태, 엔티티 링크 및 정확한 다음 읽기를 하나의 인-프로세스 Command Application을 통해 투영합니다. 의미론적 경로가 존재하는 경우, 변경된 하위 트리는 현재 노드 ID와 함께 보고됩니다. 플러그인 마커 자체는 시각적 변경으로 간주되지 않습니다.

• Design Contract는 연결된 하나의 Design Entity의 완전한 Design Capture를 결정론적 저장소 게이트로 전환합니다. figma_run ["contract", "capture","ui.button"]을 한 번 실행하고 JSON을 검토하십시오. 이후 figma_run ["contract","check","ui.button"]은 정규 드리프트를 보고하고 별도로 변형 매트릭스, 토큰 바인딩 플로어, 지오메트리 허용 오차 및 프로토타입 전환을 적용합니다. 휘발성 Figma 핸들은 무시되며 깊이 제한 캡처는 거부됩니다.

• 하나의 Capability Catalog는 MCP를 통해 들어오는 모든 Figma Command를 실행 어댑터 중 하나가 실행하기 전에 불변 계획으로 해결합니다. 해당 계획은 노출, Figma/작업공간/공유-상태 효과, 대상 필요, 확인, 정규화된 경로, 재시도, 시간 초과, 허용된 종료 코드 및 백그라운드 작업 ID에 대한 단일 소스입니다. 알 수 없는 명령은 기본적으로 거부/쓰기/재시도 없음으로 설정됩니다.

• 하나의 불변 Figma Target Context는 명시적 fileKey, 붙여넣은 Figma URL 또는 암시적 단일 창 타겟팅을 명령당 한 번 해결한 다음 계획, 감사, 작업 ID 및 데몬 실행을 수반합니다. 하나의 공유 Asset Policy는 Design Capture 투영 및 내보내기 모두에 대해 이미지 채우기, 벡터 아트 및 벡터 클러스터를 분류합니다.

• 런타임 프로토콜 검증기는 전송 경계에서 잘못된 HTTP 실행 페이로드와 플러그인 프레임을 거부합니다. TypeScript는 JavaScript 경계(Figama 플러그인 포함)를 검사하는 반면, 결정론적 컨텍스트, 페이로드 및 중간 및 꼬리 지연 시간 예산은 CI에서 아키텍처 회귀를 포착하지만, 짧은 공유 실행기 스케줄링 일시 중지를 지속적인 회귀로 취급하지 않습니다.

• 데몬은 로컬호스트 WebSocket을 통해 Figma 플러그인에 명령을 중개합니다. 두 개의 게이트가 이를 보호합니다:

  • HTTP 라우트(/health, /exec)는 세션 토큰으로 키가 지정된 요청당 HMAC 서명이 필요합니다. 0600 파일 — 토큰 자체는 절대 네트워크를 통해 전송되지 않습니다.

  • 플러그인 WebSocket(/plugin)은 액세스 키가 필요합니다: Origin/Host 허용 목록과 상호 챌린지-응답 핸드셰이크로, 키는 HMAC 비밀일 뿐이며 절대 네트워크를 통해 전송되지 않습니다. 이는 모든 로컬 프로세스가 플러그인 소켓에 연결하여 Figma 문서에서 코드를 실행할 수 있었던 업스트림 격차와, 로컬 포트에서 응답하는 모든 것이 정직한 플러그인을 구동할 수 있었던 역방향 격차를 해소합니다.

도구

노드 ID는 사용자가 가지고 있는 모든 형식으로 허용됩니다: 12:34, URL 형식 12-34, 또는 전체 Figma URL (파일 키는 실제로 열려 있는 파일과 비교 확인됩니다. 한 번에 여러 파일 참조).

쓰기 명령은 서버 환경에 FIGMA_WRITE_CONFIRM=1을 설정하여 명시적인 confirm:true로 제한할 수 있습니다. 이 제한은 하위 명령 수준에서 작동합니다: node tree 또는 component list 같은 읽기는 자유롭게 통과하지만, node delete, combos, tokens spacing 같은 변경은 확인이 필요합니다.

네이티브 JSX 인스턴스는 지속적인 Registry ID (entity와 게시된 key 또는 로컬 id)가 필요합니다. 편집 가능한 재정의는 컴포넌트의 실제 Figma 구조를 사용합니다:

<Instance entity="ui.card" key="..."
  prop:Selected="true"
  text:Title="New title"
  fill:StatusDot="var:status/healthy|#22c55e"
  swap:LeadingIcon="ui.icon.leaf" />

prop:는 컴포넌트 속성 정의를 해석합니다. text:와 fill:는 하나의 명명된 하위 요소를 해석합니다. swap: 값과 INSTANCE_SWAP 속성 값은 디자인 엔티티 ID이며, figma-bridge.json에서 해석됩니다. 컴포넌트 표시 이름은 의도적으로 스왑 ID로 허용되지 않습니다. 누락되었거나 모호하거나 연결되지 않은 대상은 첫 번째 캔버스 노드가 생성되기 전에 사전 점검을 중단합니다.

치수 및 타이포그래피는 동일한 var:name|fallback 형식을 허용합니다. 네이티브 실행기는 너비, 높이 및 최소/최대 제약 조건과 글꼴 패밀리/스타일, 두께, 크기, 줄 높이, 자간, 단락 간격 및 단락 들여쓰기를 바인딩합니다. 패밀리/스타일은 STRING 변수를 사용합니다. 다른 타이포그래피 및 치수 필드는 FLOAT 변수를 사용합니다. 바인딩된 글꼴이 없으면 사전 점검에서 설치하거나 다른 글꼴을 선택하라는 메시지와 함께 중단되며, 자동으로 대체되지 않습니다. 명명된 텍스트 스타일도 캔버스 생성 전에 조정됩니다: 명시적인 style="Typography/Eyebrow"는 완전한 타이포그래피가 일치할 때만 재사용됩니다. 동일한 이름의 스타일이 충돌하면 중단되며, 그 외에는 정확한 타이포그래피가 재사용되거나 결정론적인 Typography/Generated/... 이름으로 생성됩니다. Figma float32 메트릭 읽기 값은 안정적인 비교를 위해 정규화되며, DM Sans/Manrope SemiBold 및 ExtraBold와 같은 패밀리별 페이스는 대체 패밀리보다 먼저 시도됩니다. 성공적인 네이티브 렌더는 textStyleReport 및 variableReport 카운트(참조, 고유 재사용 변수, 생성된 변수, 바인딩된 속성)를 반환합니다. 모호하거나 지원되지 않는 사전 점검 오류는 해당하는 0/0이 아닌 카운트를 포함하며, 새로 생성된 변수나 캔버스 노드를 남기지 않습니다.

<Text>는 또한 편집 가능한 인라인 리치 텍스트를 보존합니다. 중첩된 <strong>/<b>, <em>/<i>, <u>, <Span ...> 및 <a href="..."> 마크업은 네이티브 Figma 범위가 됩니다. HTML 엔티티는 UTF-16 범위 오프셋이 계산되기 전에 디코딩됩니다. Span 실행은 font, fontStyle, weight, italic, size, color, letterSpacing, underline/decoration 및 안전한 링크를 지원합니다:

<Text font="Inter" size="14">
  Hello <strong>bold <em>and italic</em></strong>
  <Span color="#ef4444" size="18">red</Span>
  <a href="https://example.com">link</a>
</Text>

플러그인 창

Figma Bridge 플러그인 창은 연결 상태 이상을 제공합니다:

• 활동 — 에이전트가 실행하는 모든 명령을 실시간으로, 지속 시간 및 성공/오류와 함께 표시합니다. 쓰기 명령은 강조 표시됩니다. 접힌 행에는 합계가 표시됩니다 (12 ok · 1 failed). 연결된 포트와 왕복 지연 시간은 제목 표시줄에 있습니다.

• 에이전트 일시 중지 — 킬 스위치: 일시 중지된 동안 플러그인은 들어오는 모든 에이전트 명령을 명시적인 오류와 함께 거부합니다.

• 버전 저장 — 에이전트를 실행하기 전에 수동 복원 지점으로 Figma 자체 버전 기록에 레이블이 지정된 항목을 씁니다 (Figma Bridge — <timestamp>). 플러그인을 위한 복원 API는 없습니다. Figma의 버전 기록 패널을 통해 롤백합니다.

• 선택 영역 읽기 — 사용자가 선택한 모든 내용이 자동으로 에이전트에 푸시(디바운스됨)되고 "Agent sees: …"로 표시되므로 사용자는 항상 figma_selection이 반환할 내용을 볼 수 있습니다. 프레임을 선택하고 "이것을 만들어"라고 말하면 노드 ID를 복사할 필요가 없습니다.

• 설정 — 액세스 키 및 선택적 REST 토큰, 브리지가 연결되었는지 여부와 관계없이 항상 접근 가능합니다.

디자인-투-코드 워크플로우

디자인은 완전한 사양입니다 — 도구는 이를 해석하는 것보다 복사하는 것을 더 쉽게 만듭니다. Figma에서 화면을 여섯 단계로 구축하세요:

대상 프로젝트의 프레임워크와 스타일링 시스템을 유지하세요. 화면만을 위해 Tailwind, UI 키트 또는 아이콘 라이브러리를 추가하지 말고, 내보낸 Figma 아트워크를 편리한 근사치로 대체하지 마세요. 프로젝트 컴포넌트는 렌더링된 디자인과 상태가 실제로 일치할 때만 재사용하세요.

1. **figma_screenshot**을 대상 프레임에 대해 실행한 후 저장된 PNG를 읽습니다. 이것이 시각적 실측 자료(Ground Truth)입니다. 노드 트리만으로 빌드하지 마십시오.

2. figma_spec with phase: "structure" — 마크업 골격을 구축합니다: 실제 텍스트 문자, 해석된 아이콘/컴포넌트 이름(인스턴스는 하위로 내려가므로 오버라이드와 실제 메인 컴포넌트 이름이 나타납니다), 계층 구조 및 플렉스 방향. 텍스트와 아이콘을 그대로 복사합니다. layout:inferred (Figma heuristic — verify) 마커는 작성된 Auto Layout이 아닙니다. 이를 컴포넌트 계약으로 취급하기 전에 계층 구조를 확인하십시오.

3. 토큰 내보내기 (figma_run with ["export","css"] 또는 ["export","dtcg"]) — 이를 CSS 변수/테마로 연결합니다. 출력물은 소스 Figma 파일을 명명합니다 — 빌드 중인 파일인지 확인하십시오.

4. 에셋 내보내기 (figma_run with ["export","assets","<nodeId>","-o","/abs/path/src/assets"]) — 사양의 모든 → assets/… 참조는 이 명령이 작성하는 파일을 가리킵니다. 절대 경로를 전달하십시오. 대규모 내보내기는 백그라운드에서 계속 실행됩니다("still RUNNING") — 동일한 호출을 다시 실행하여 폴링하십시오. assets.json은 실행 간에 병합되며 바이트가 동일한 에셋은 중복 제거됩니다. 각 항목에는 배치 데이터(x/y 오프셋, parent 이름 경로, parentId, absolutePosition, overhang)가 포함되므로, 매니페스트만으로 오버레이를 배치할 수 있습니다 — 사양 참조가 필요하지 않습니다. 내보내기 요약에는 절대 위치 및 오버행 파일이 명시적으로 나열됩니다. 이들은 빌드에서 손실되는 파일입니다. 과도하게 큰 PNG는 기본적으로 Figma에서 가장 큰 사용처의 2배(레티나 밀도)로 다운샘플링되며, 업스케일링 없이 인코딩된 파일이 더 작아질 때만 수행됩니다. 종횡비, 매니페스트 배치 및 CSS 크롭 동작은 변경되지 않습니다. --raster-scale 0을 전달하면 원본 PNG 바이트를 유지합니다.

5. figma_spec with phase: "style" — 크기, 간격, 패딩, 정렬, fill/hug 크기 조정, 그라디언트를 포함한 페인트(→ var(name)은 디자인 토큰 바인딩을 표시), 반경, 그림자, 타이포그래피, opacity, clip(overflow hidden) 및 abs 위치 지정을 적용합니다. 장식용 벡터는 배치 정보와 함께 vector art → assets/… 줄로 나타납니다 — 내보낸 SVG를 배치하고 CSS로 근사하지 마십시오.

   구조화된 YAML/JSON은 추가로 정확한 컴포넌트 속성 정의 및 값(INSTANCE_SWAP 및 SLOT 포함), 속성 참조, 선호 값, 직접 오버라이드, 노출된 인스턴스 및 슬롯 위반을 유지합니다. 변수 바인딩에는 컬렉션 ID, 작성된 범위, 명시적/해결된 모드, codeSyntax.WEB 및 해결된 값이 포함됩니다. inferredVariables는 제안 전용 증거로 별도로 출력됩니다.

   큰 섹션의 경우 먼저 depth:0을 요청하십시오. 이는 하위 요소 없이 섹션 컨테이너 자체(배경, 테두리, 반경 및 레이아웃 포함)에 대한 완전한 계약입니다. 그런 다음 제한된 호출로 하위 노드 ID를 요청하십시오. 반복되는 카드/목록에는 dedup:true를 사용하십시오. 공유된 S<n> 참조는 무손실 상태를 유지하며 동일한 인스턴스 스타일이 결과 예산을 소진하는 것을 방지합니다.

6. 검증 — 빌드의 스크린샷을 찍어 1단계의 PNG와 비교한 후 기계적 검사를 실행합니다:

   figma_run ["verify-build", "/abs/path/to/project"]

   이는 프로젝트에서 assets.json을 grep하여 빌드에서 참조되지 않은 모든 내보낸 파일을 크기, 오프셋 및 부모와 함께 나열합니다. 따라서 배치는 한 단계로 가능합니다. 또한 border-image 린트(CSS border-image는 border-radius를 무시합니다. 둥근 상자의 그라디언트 획에는 래퍼 또는 마스크 패턴이 필요합니다)를 수행합니다. 파일이 누락되면 종료 코드 1을 반환하므로 CI 게이트로도 작동합니다.

   빌드 스크린샷이 있으면 시각적 검사도 실행합니다:

   figma_run ["verify-build", "/abs/path/to/project", "--compare", "/abs/build.png"]

   참조 렌더링은 Figma에서 실시간으로 가져오거나(--node <id>, 기본값: 매니페스트의 내보내기 루트) --design <png>를 통해 오프라인으로 제공됩니다. 두 이미지는 공통 너비로 정규화되고 픽셀 차이(안티앨리어싱 허용)가 계산됩니다. 출력은 전체 차이 비율, 높이 불일치 발견(빌드가 너무 높거나 낮음 = 삽입되거나 누락된 블록), 노드 픽셀 좌표(사양 및 assets.json이 사용하는 동일한 공간)에서 가장 차이가 큰 영역을 보고하고 차이 PNG(빨간색 = 차이, 흐릿한 디자인 위에)를 작성합니다. 기본적으로 정보 제공용입니다. --max-diff <pct>는 종료 코드를 제어합니다.

큰 화면의 경우, 섹션 수준 에이전트는 스크린샷, 구조 맵, 토큰 및 에셋이 고정된 후 선택적 경과 시간 최적화입니다. 분리된 컴포넌트/스타일 파일이 있는 큰 섹션에만 사용하십시오. 코디네이터는 공유 셸, 토큰, assets.json, 통합 및 최종 픽셀 차이에 대한 소유권을 유지합니다. 병렬 에이전트는 일반적으로 각각 프로젝트 컨텍스트가 필요하므로 더 많은 총 토큰을 소비합니다. 따라서 토큰 비용이 실제 시간보다 더 중요할 때는 순차 작업을 사용하십시오.

빌드 스크린샷을 위해 기존 브라우저 도구 또는 프로젝트 하네스를 사용하십시오. 사용자 승인 없이 캡처 전용으로 Playwright(또는 다른 브라우저 종속성)를 설치하지 마십시오. 이미 존재하는 경우 Figma Bridge 종속성보다 유효한 캡처 메커니즘입니다.

동일한 사양은 figma_run ["export", "code-spec", "<nodeId>"]로도 사용할 수 있습니다. 기본값은 읽기 쉬운 트리입니다. 표준 모델을 원하면 -f yaml 또는 -f json을 전달하십시오.

무손실 구조화된 사양 형식

figma_spec 및 export code-spec은 기본적으로 format:"tree"를 사용합니다. 이는 간결하고 줄 지향적인 에이전트 뷰로, 바닥글에 필요한 에셋 및 충실도 작업이 포함됩니다. 소비자가 버전이 있는 표준 모델을 필요로 할 때는 명시적으로 yaml 또는 형식화된 json을 사용하십시오. 두 구조화된 형식은 동일한 모델을 직렬화합니다. 구문만 다릅니다. 왕복 테스트는 모든 필드(텍스트, ID, 레이아웃 출처, 페인트, 타이포그래피, 모드 인식 변수, 에셋, 컴포넌트 계약, Bridge 의도, 네이티브 주석, 캡처 완전성 및 충실도 검사)가 정확히 유지되어야 합니다. 축소된 JSON은 제공되지 않습니다. 실제 에이전트 테스트에서 단일 거대한 줄은 동일한 원시 필드를 가지고 있음에도 불구하고 처리하기에 실질적으로 더 어렵다는 것이 밝혀졌습니다.

모델의 capture 필드는 요청된/실제 깊이, 페이로드 완전성, 숨겨진 노드 정책 및 요청된 깊이가 하위 요소를 잘라냈는지 여부를 명시적으로 보고합니다. 도구 결과의 자동 잘림은 없습니다. 사양이 구성된 출력 예산을 초과하면 호출은 complete:false를 반환하고 섹션별 재시도 레시피를 제공하며 오해의 소지가 있는 부분 설계를 반환하지 않습니다. depth:0은 의도적으로 "요청된 노드만"을 의미하며 완전하며 깊이가 잘린 트리가 아닙니다.

IMAGE-fill 파일 이름은 로컬 레이어 이름/경로가 아닌 Figma의 안정적인 이미지 해시를 키로 사용합니다. 이는 "Frame 64"와 같은 일반 레이어가 다른 루트를 통해 도달하더라도 figma_spec, 격리된 하위 호출, 에셋 내보내기 및 assets.json이 동일한 파일 이름을 유지하도록 합니다.

MCP 디자인-투-코드 호출의 경우 dedup:false가 기본값입니다. 모든 보이는 레이어는 자체 ID, 네이티브 Figma Inspect css{…}, 레이아웃/페인트/토큰 사실 및 완전한 텍스트를 유지합니다. 혼합 리치 텍스트 레이어는 개별 스타일 범위를 전달합니다. 바닥글은 라이브 보이는 레이어 수를 명시적 행, SVG 내부, 컴포넌트 내부 및 비렌더링 도우미와 조정합니다. 깊이 제한 또는 설명되지 않은 레이어가 추측을 강제할 때 스타일 프로젝션은 거부됩니다. 구조 맵의 노드 ID로 분할하십시오. 공유된 S<n> 스타일 및 반복 참조를 사용하는 간결한 개요를 위해서만 dedup:true를 설정하십시오.

반복되는 명시적 노드 호출의 경우 phase, format 및 중복 제거는 또 다른 전체 Figma 워크를 트리거하지 않습니다. 메모리 내 Design Capture 캐시는 기본적으로 8개 항목 / 8MiB로 제한됩니다(DESIGN_CAPTURE_CACHE_ENTRIES 및 DESIGN_CAPTURE_CACHE_BYTES). 모든 히트는 여전히 라이브 문서 리비전을 조사합니다. TTL이나 stale-while-revalidate 경로는 없습니다.

코드 ↔ Figma 디자인 메모리

각 중요한 컴포넌트, 화면 또는 프레임에 내구성 있는 Design Entity ID를 부여하십시오. ID는 현재 위치가 아닌 개념을 설명합니다. ui.button, ui.account-card 또는 screen.settings와 같은 이름을 사용하십시오.

Figma 노드를 선택하거나 식별한 후 에이전트는 다음을 사용하여 링크를 생성할 수 있습니다:

figma_run {args:["link","set","9:9","screen.settings","--kind","screen","--source","src/routes/settings.tsx","--export","SettingsScreen","--story","screens-settings--default"], confirm:true}

이는 두 개의 작은 어댑터를 수렴합니다:

• figma-bridge.json은 커밋되고 검토 가능한 레지스트리로, 저장소 상대 코드 경로와 선택적 Storybook 및 Figma 핸들을 포함합니다.

• Figma는 노드에 플러그인 데이터로 {version,id,kind}만 저장합니다. 로컬 경로, 자격 증명 또는 시스템별 상태를 포함하지 않습니다.

figma_run ["link","inspect","9:9"]를 사용하여 노드를 해결하고 figma_run ["link","list"]를 사용하여 Figma를 읽지 않고 저장소 메모리를 검사하십시오. 일단 링크되면 figma_selection 및 figma_spec은 자동으로 동일한 ID와 레지스트리의 코드/Storybook 대상을 노출합니다. 에이전트는 유사한 모양을 만드는 대신 해당 코드 컴포넌트를 재사용하거나 편집해야 합니다. 동일한 set 명령을 반복하는 것은 안전하며 중단된 쓰기 후 양쪽을 복구합니다.

코드와 Figma가 일치하는지 시각적으로 확인한 후 현재 지문을 명시적으로 기록하십시오. 화면 엔터티는 실제 브라우저 스크린샷과 통과 픽셀 임계값이 필요합니다:

figma_run ["link","accept","screen.settings","--compare","/abs/build.png","--max-diff","5"]

소스 코드는 레지스트리에 저장되지 않습니다. 초기 코드 어댑터는 연결된 전체 파일과 내보내기 ID를 해싱합니다. 따라서 공유 파일의 관련 없는 편집이 코드 변경을 보수적으로 보고할 수 있지만 실제 변경이 숨겨지지는 않습니다. Figma 어댑터는 정규화된 연결된 하위 트리를 해싱합니다. Code-to-Figma 노드의 경우 각 고유 figmaBridge.semanticPath와 해당 노드의 하위 트리 해시도 저장합니다. 이후 link status는 정확히 추가, 제거 또는 변경된 의미 경로를 나열하고 노드 범위 사양을 권장할 수 있습니다. 의미 마커만 변경해도 시각적 지문은 변경되지 않습니다. 중복 경로는 추측 대신 모호한 것으로 보고됩니다.

figma_run ["link","status","screen.settings"]
figma_run ["link","context","screen.settings"]

link context는 링크가 존재한 후 선호되는 에이전트 진입점입니다. 가장 작은 관련 프로젝션(엔터티, 코드/내보내기, Figma 루트, Storybook 스토리, 현재 왕복 계획, 발견된 DESIGN.md/토큰 파일 및 정확한 다음 읽기)을 반환합니다. 요청 시 생성되며 다른 메모리 파일로 유지되지 않습니다. link accept는 figma-bridge.json만 씁니다. Figma나 코드를 변경하지 않습니다. 화면의 경우 측정된 차이와 두 비교 이미지의 SHA-256 해시도 저장하므로 구조적 지문이 시각적으로 잘못된 기준선을 인증할 수 없습니다.

기존 DESIGN.md, design/DESIGN.md, tokens.json 및 design/tokens.json 위치는 자동으로 발견됩니다. 필요할 때 사용자 정의 저장소 상대 위치를 한 번 구성하십시오:

figma_run ["link","configure","--design-doc","docs/product-design.md","--tokens","src/theme/tokens.json"]

figma-bridge.json을 커밋하십시오. 여기에 비밀, 절대 경로 또는 생성된 자격 증명을 넣지 마십시오. 스키마 및 충돌 규칙은 docs/adr/0007-dual-anchor-design-entities.md에 문서화되어 있으며, 기준선 및 컨텍스트 결정은 ADR-0008 및 ADR-0009에 있습니다.

검토된 CSS ↔ Figma 경계 전략

의미론적 Code-to-Figma는 묵시적 시각적 대체 대신 안정적인 정책 ID를 사용합니다: minmax.native-grid, space-around.equal-slots, border.single-paint-native, sticky.metadata-only, filters.layer-stack, masks.vector-mask, font.named-faces 및 figma-effects.native. 전체 매트릭스와 남은 하드 스톱은 docs/css-figma-semantic-matrix.md에 있습니다.

검토된 손실 정책은 영향을 받는 정확한 의미 노드에 자동 네이티브 Figma 주석을 선택할 수 있습니다. 주석은 지원되지 않는 CSS 사실을 설명하고 관련 Figma 속성에 연결하며, 버전이 지정된 figmaBridge.fallbackAnnotations 플러그인 데이터로 미러링되어 향후 에이전트가 사용할 수 있습니다. 동등한 네이티브 변환은 검토 노이즈를 피하기 위해 주석이 추가되지 않습니다. 첫 번째 활성 정책은 border.single-paint-native입니다. Figma는 명시적으로 칠해진 첫 번째 CSS 측면을 공유 네이티브 획으로 수신하고, 네 가지 측면 두께를 모두 유지하며, strokes 및 strokeWeight를 표시합니다. 네이티브 렌더는 추가된 폴백 주석의 수, 중복 제거 또는 지원되지 않는 주석 수를 보고합니다.

고유한 단일 라인 DOM 텍스트는 Figma HUG 크기 조정에 매핑됩니다. 위치 지정 및 여러 줄 텍스트는 측정된 상자 형상을 유지합니다. 브리지는 줄바꿈을 방지하기 위해 임의의 백분율 너비 여유 공간을 추가하지 않습니다.

가변 글꼴 축은 캡처되지만, 구조적 게이트는 렌더링 전에 필요한 글꼴을 설치해야 하는지 아니면 사용 가능한 명명된 페이스를 사용해야 하는지 묻습니다. 네이티브 Figma Glass는 모든 효과 매개변수를 유지한 상태에서 편집 가능한 네이티브 효과로 유지됩니다. Figma의 CSS 내보내기가 해당 Glass 매개변수를 노출하지 않기 때문에 CSS backdrop-filter로 자동 처리되지 않습니다.

Storybook 미러링

Figma 컴포넌트는 안정적인 게시 키를 전달합니다(라이브러리 게시에도 유지됨, 노드 ID는 파일 로컬). 이 키는 이제 figma_spec(정식 구조화 모델 + "사용된 컴포넌트 세트" 트리 트레일러), figma_selection, component list, figma_inspect 및 DESIGN.md를 통해 전달됩니다.

코드 미러에 연결하려면:

figma_run ["map", "storybook", "http://localhost:6006"]

이것은 파일의 컴포넌트를 정규화된 이름으로 Storybook 인덱스와 일치시키고 프로젝트에 **figma-map.json**을 작성합니다: Figma 키 ↔ 스토리 ID / 가져오기 경로, 일치당 confidence와 일치하지 않는 두 목록이 포함됩니다. 항목을 수동으로 편집하고 "matchedBy": "manual"로 설정하여 고정합니다. 고정된 항목은 재실행 시 유지됩니다. 파일이 존재하면 figma_selection 및 figma_spec이 자동으로 ↔ story <id> (<importPath>)로 컴포넌트에 주석을 추가합니다.

figma-map.json은 레거시 읽기 어댑터로 유지되므로 기존 매핑이 계속 작동합니다. 새로운 내구성 있는 링크는 figma-bridge.json에 속합니다. link set은 레거시 행을 복사하지 않습니다. 다음에 컴포넌트를 건드릴 때 실제 Design Entity ID를 할당하고 --story를 통해 스토리를 전달하여 마이그레이션하세요. link list가 여전히 필요한 모든 매핑을 표시한 후에만 레거시 파일을 제거하세요.

자체 디자인 시스템 가져오기

이 프로젝트는 디자인 시스템을 제공하지 않습니다 — shadcn, Tailwind 프리셋, 아이콘 팩이 없습니다. 이는 의도적입니다: 번들 시스템은 다른 사람의 의견을 파일에 렌더링한 것입니다. 대신 제공하는 것은 여러분의 시스템을 한 명령으로 에이전트가 이해할 수 있게 만드는 방법입니다:

figma_run ["kit", "init", "./my-app", "--storybook", "http://localhost:6006"]

네 가지 읽기, 하나의 보고서:

마지막으로 아직 누락된 것(매핑되지 않은 Storybook, 스토리가 없는 컴포넌트, 두 가지를 동기화 상태로 유지하는 tokens sync 명령)을 명명합니다. 조용히 매핑이 누락된 설정은 에이전트가 필요로 할 때까지 완료된 것처럼 보이기 때문입니다.

DESIGN.md는 에이전트가 먼저 읽어야 할 것이고, tokens.json은 에이전트가 바인딩하는 대상입니다.

한 번에 여러 파일

브리지는 플러그인을 시작한 각 Figma 창당 하나의 연결을 유지합니다. 이것이 동의 모델입니다: 파일에 접근할 수 있는 이유는 사용자가 파일을 열고 거기서 플러그인을 실행했기 때문이지, 플래그가 범위를 넓혔기 때문이 아닙니다.

• 하나의 창 — 변경 사항 없음. 명령이 해당 창으로 전달됩니다.

• 여러 창 — 명령은 대상을 지정해야 하며, 그렇지 않으면 연결된 파일 목록과 함께 실패합니다:

  figma_status                                        # lists every connected window
  figma_run {args: ["canvas","info"], fileKey: "GY5SasBJ…"}
  figma_spec {nodeId: "12:34", fileKey: "GY5SasBJ…"}

  figma_render, figma_selection, figma_inspect, figma_screenshot 및 figma_spec은 동일한 fileKey 매개변수를 허용합니다. 전체 Figma 노드 URL도 자동으로 파일 키를 제공합니다. 대상이 없으면 figma_selection은 추측하는 대신 어떤 파일이 열려 있는지 알려줍니다. 엔진 CLI에서 플래그는 --figma-file이며 --file이 아닙니다: eval 및 spec은 이미 로컬 경로에 -f, --file을 사용합니다.

의도적으로 "모든 파일" 옵션은 없습니다. 모든 쓰기는 하나의 파일을 지정하므로 잘못된 명령이 라이브러리 전체에 퍼질 수 없습니다. 동일한 파일에 대한 두 개의 창은 라우팅에서 구분할 수 없으므로 최신 창이接管하고 이전 창은 브리지를 잃었다는 알림을 받습니다. 감사 항목은 파일 키를 전달하므로 여러 파일이 관련된 경우에도 figma_history를 읽을 수 있습니다.

열지 않은 파일에 접근하는 것은 범위를 벗어납니다: Figma의 REST API는 문서 콘텐츠를 쓸 수 없으므로 30개의 라이브러리 파일에 대한 대량 이름 변경은 이 도구가 정직하게 제공할 수 있는 것이 아닙니다.

FigJam

플러그인은 FigJam 보드에서도 동일한 브리지를 통해 실행됩니다. 두 번째 전송이나 추가 권한이 필요하지 않습니다:

figma_run ["jam", "sticky", "Ship the handshake", "--color", "green"]
figma_run ["jam", "stickies", "[\"Discovery\",\"Build\",\"Ship\"]", "--columns", "3"]
figma_run ["jam", "shape", "Decide?", "--type", "DIAMOND"]
figma_run ["jam", "connector", "1:2", "3:4", "--text", "yes"]
figma_run ["jam", "table", "3", "4", "--data", "[[\"Step\",\"Owner\"],[\"Handshake\",\"Alex\"]]"]
figma_run ["jam", "board"]      # read everything back, with connectors
figma_run ["jam", "arrange"]    # arrange only the current selection
figma_run ["jam", "arrange", "--ids", "1:2,3:4"]
figma_run ["jam", "arrange", "--all"] # explicit: whole page

새 노드는 --at x,y를 전달하지 않는 한 보드에 이미 있는 내용의 오른쪽에 배치되므로, 채워진 보드에 추가하는 에이전트가 모든 것을 원점에 쌓지 않습니다. 모든 명령은 먼저 figma.editorType을 확인하고 정의되지 않은 API에서 실패하는 대신 "이것은 Figma 파일이지 FigJam 보드가 아닙니다"라고 말합니다. figma_status는 브리지가 연결된 편집기를 보고합니다.

jam arrange는 의도적으로 선택 범위로 제한됩니다. 에이전트는 사용자의 선택을 변경하지 않고 정확한 노드 ID를 전달할 수 있습니다. 전체 페이지를 재정렬하려면 가시적인 --all 플래그가 필요합니다. 섹션과 커넥터는 이 명령으로 이동되지 않습니다. 공개 표면은 2026-08-10에 Figma Desktop에서 테스트되었습니다. 유지 관리자는 상세한 명령 및 읽기 확인 증거를 공개 저장소 외부에 보관합니다.

Figma Slides 베타

Slides는 동일한 인증된 플러그인 브리지를 사용합니다. 베타 표면은 덱 구조와 네이티브 슬라이드 속성을 다루며, 별도의 프레젠테이션 렌더러는 아닙니다:

figma_run ["slides", "inspect"]
figma_run ["slides", "create", "Agenda", "--row", "0", "--col", "1"]
figma_run ["slides", "duplicate", "Agenda", "--label", "Agenda alternative"]
figma_run ["slides", "move", "Agenda alternative", "1", "0"]
figma_run ["slides", "transition", "Agenda", "DISSOLVE", "--duration", "0.4"]
figma_run ["slides", "skip", "Appendix", "on"]
figma_run ["slides", "delete", "1:42"]

Figma는 캔버스 그리드가 변경될 때마다 네이티브 슬라이드 이름을 다시 번호를 매깁니다. 따라서 create의 선택적 인수와 duplicate의 --label은 플러그인 데이터에 내구성 있는 Bridge 레이블을 저장합니다. inspect는 네이티브 name과 안정적인 label을 모두 보고합니다. 참조는 ID, 정확한 네이티브 이름 또는 레이블, 그 다음 고유한 부분 문자열로 해결됩니다. 모호함은 오류이며, 삭제는 항상 명시적 참조가 필요하고, 중복/이동은 Figma의 폴백 배치를 수락하는 대신 존재하지 않는 대상 행을 거부합니다. 모든 작업은 Slides 전용 API를 건드리기 전에 figma.editorType === "slides"를 확인합니다. 공개 후보와 베타 종료 기준은 docs/slides-roadmap.md에 있습니다. 편집자 수락은 공개 저장소와 별도로 유지 관리자가 확인합니다.

토큰 동기화(양방향)

tokens import는 항상 생성만 하므로, 코드에서 편집된 값이 기존 Figma 변수에 도달하지 않고 Figma에서 편집된 값이 코드에 도달하지 않습니다. tokens sync가 이 루프를 닫습니다:

figma_run ["tokens", "sync", "src/tokens.json"]              # plan only
figma_run ["tokens", "sync", "src/tokens.json", "--apply"]   # write it

가져오기 표면은 동기화 표면보다 넓습니다. 일회성 import는 Tailwind v3 구성, Tailwind v4/CSS, Storybook 인덱스, DTCG/W3C JSON, 그리고 Style Dictionary 및 Tokens Studio에서 내보낸 DTCG 호환 토큰 형태를 허용합니다. 이 호환성에는 Tokens Studio 테마 의미론이나 임의의 전처리기가 포함되지 않습니다. $themes와 같은 메타데이터는 무시되고 토큰 세트와 별칭은 읽힙니다.

명시적인 spacing/* 또는 space/* 네임스페이스의 새로운 FLOAT 변수는 Figma의 GAP 소비자로만 범위가 지정됩니다. radius/* 및 radii/* 변수는 CORNER_RADIUS로만 범위가 지정됩니다. 추론은 의도적으로 네임스페이스에 정확합니다: spacingFactor와 같은 이름은 Figma의 기본 범위로 남겨지고, 렌더링은 기존 사용자 또는 라이브러리 변수의 범위를 자동으로 변경하지 않습니다. 다른 새로운 COLOR, FLOAT 또는 STRING 변수는 호환되는 Figma 선택 사항만 포함하여 SCOPE DECISION REQUIRED를 표시합니다. 에이전트는 좁히기 전에 물어봐야 합니다. figma_reference {name:"variable-scopes"}로 카탈로그를 검사하고 figma_run ["var","update","<name>","--collection", "<collection>","--scopes","TEXT_FILL,STROKE_COLOR"]로 답변을 적용하세요.

안전한 삼자 동기화는 DTCG / W3C 디자인 토큰(.json, export dtcg가 내보내는 것) 및 CSS 사용자 정의 속성(.css, export css가 내보내는 것)만 허용합니다. Sass $variables는 CSS 사용자 정의 속성이 아니며 .scss는 부분적으로 구문 분석되는 대신 거부됩니다. 참고로 export dtcg는 모든 로컬 변수를 하나의 파일에 쓰는 반면 동기화는 하나의 컬렉션을 대상으로 합니다. 그에 따라 --collection을 전달하세요. 파일의 대부분 이름이 이미 다른 컬렉션에 있는 경우 동기화는 중복을 제안하는 대신 그렇게 알려줍니다. Tailwind 구성은 가져오기 소스일 뿐입니다. 해당 파서는 값을 색상/간격/반경으로 버킷화하고 왕복할 수 없으므로 동기화는 이해하지 못한 토큰을 자동으로 삭제하는 대신 이름으로 거부합니다.

잠금 파일이 필요한 이유. 메모리가 없는 양방향 동기화는 "코드가 변경됨"과 "Figma가 변경됨"을 구분할 수 없습니다. 두 값이 다르다는 것만 보이며, 선택한 방향이 다른 쪽의 작업을 파괴합니다. figma-tokens.lock.json은 마지막 성공적인 동기화 시점의 상태를 기록하므로 모든 결정은 삼자 비교입니다:

충돌은 전체 실행을 중단합니다. 한쪽을 편집하여 해결하거나 --ours(코드 파일 승리) / --theirs(Figma 승리, Figma에 아무것도 쓰지 않음)로 한 번에 모두 결정하세요.

삭제에는 --prune이 필요하며, 그 경우에도 동기화 자체가 생성한 변수만 건드립니다. 추적하지 않은 변수는 추적되지 않음으로 보고되고 그대로 둡니다.

잠금 파일은 각 변수의 Figma ID도 저장하므로 이름 변경이 삭제 및 생성(모든 레이어 바인딩을 잃게 됨) 대신 하나의 이름 변경이 됩니다. 페어링은 값으로만 이루어지며 모호하지 않은 경우에만 수행됩니다. 동일한 커밋에서 토큰의 이름을 변경하고 값을 변경하면 생성 + 삭제로 대체되므로 바인딩이 중요하다면 두 단계로 수행하세요.

--apply 없이 명령은 변경 사항이 보류 중일 때 종료 코드 1을 반환하므로 "Figma가 저장소와 동기화되어 있습니까?"에 대한 CI 검사로 작동합니다.

바인딩, 그리고 디자인이 따르는 컬렉션 전환

tokens sync는 토큰 값을 씁니다. 의도적으로 수행하지 않는 두 가지 인접 작업:

figma_run ["node", "bind", "12:34", "radius", "radius/lg", "--collection", "TARGET_COLLECTION"]
figma_run ["tokens", "rebind", "TARGET_COLLECTION", "--node", "12:34"]            # plan
figma_run ["tokens", "rebind", "TARGET_COLLECTION", "--node", "12:34", "--apply"] # write

node bind는 변수를 기존 노드의 속성에 연결합니다 — fill, stroke, radius, gap, padding(또는 한쪽), opacity, stroke-width, width, height. 읽기 대응은 node bindings입니다. JSON 배열과 함께 --batch를 전달하여 한 번 호출로 여러 속성 또는 노드를 바인딩하세요.

고유하지 않은 변수 이름은 추측되지 않고 거부됩니다 — 이 파일에는 두 컬렉션에 radius/lg가 있으며, 답변은 두 컬렉션을 모두 명명하므로 --collection이 해결할 수 있습니다. 변수의 유형은 먼저 속성에 대해 확인되므로 radius에 COLOR가 있으면 플러그인 스택 추적 대신 문장으로 실패합니다.

서체 변수는 텍스트가 다른 문자 범위에 다른 바인딩을 가질 수 있으므로 자체 범위 인식 명령이 있습니다:

figma_run ["font", "bind", "12:36", "fontWeight", "type/weight", "--collection", "Typography"]
figma_run ["font", "bind", "12:36", "line-height", "type/line-height", "--start", "0", "--end", "12"]
figma_run ["font", "unbind", "12:36", "lineHeight", "--start", "0", "--end", "12"]

바인딩 가능한 필드는 fontFamily, fontSize, fontStyle, fontWeight, letterSpacing, lineHeight, paragraphSpacing, paragraphIndent이며, 케밥-케이스 철자도 허용됩니다. 기존 글꼴(그리고 family/style/weight 바인딩의 경우 관련 사용 가능한 패밀리 스타일)은 바인딩이 변경되기 전에 로드됩니다. 변수 이름은 모호할 경우 거부되며, Figma를 호출하기 전에 STRING과 FLOAT을 확인합니다. 숫자 fontWeight 바인딩은 여전히 일반적인 가변 글꼴 축 설정기가 아닙니다. Figma는 활성 글꼴에 대해 유효한 두께를 선택합니다.

tokens rebind는 테마 전환입니다. 하위 트리를 탐색하고 모든 바인딩을 대상 컬렉션의 동일한 이름을 가진 변수로 다시 가리킵니다. SOURCE_COLLECTION에 대해 카드를 디자인하고, TARGET_COLLECTION으로 리바인드를 실행하면 동일한 카드가 대상 컬렉션의 값을 따릅니다. 재설계가 필요 없습니다. 기본적으로 계획만 세우며, --apply가 실제로 적용합니다. 대상에 대응하는 항목이 없는 토큰은 나열되고 원래 위치를 그대로 유지하므로, 부분 테마는 절반만 망가진 디자인이 아닌 보고서가 됩니다.

node set은 이미 존재하는 노드의 속성을 변경합니다. fill, stroke, strokeWidth, radius, opacity, x, y, width/height, name, visible — 한 번에 하나의 노드 또는 --batch를 통해 여러 노드를 처리합니다. 이는 배치 형식이 단 한 번의 왕복이기 때문에 중요합니다:

figma_run ["node", "set", "12:34", "--name", "Card", "--radius", "12"]
figma_run ["node", "set", "--batch", "[{\"node\":\"12:35\",\"fill\":\"var:sage/50\",\"name\":\"Badge\"}]"]

색상은 16진수 또는 var:<name>을 사용합니다. 차이는 단순한 외형적 차이가 아닙니다. 16진수는 고정되고, var: 참조는 바인딩된 상태로 유지되므로, 나중에 tokens rebind로도 이동할 수 있습니다.

로컬 스타일, 변수 메타데이터 및 모드

이전에는 수동 UI 작업이 필요했던 로컬 디자인 시스템 기본 요소가 이제 일급 Figma 명령어로 제공됩니다. 이들은 REST가 아닌 라이브 Plugin API를 사용합니다:

figma_run ["style", "list", "--type", "TEXT"]
figma_run ["style", "show", "Heading/H1"]
figma_run ["style", "create", "PAINT", "Brand/Primary", "--properties", "{\"paints\":[{\"type\":\"SOLID\",\"color\":{\"r\":0.1,\"g\":0.3,\"b\":0.9}}]}"]
figma_run ["style", "apply", "Brand/Primary", "12:34,12:35", "--field", "fill"]
figma_run ["style", "consumers", "Brand/Primary"]
figma_run ["style", "publish-status", "Brand/Primary"]
figma_run ["style", "bind-font", "Body", "fontSize", "--variable", "type/size/body"]
figma_run ["style", "unbind-font", "Body", "fontSize"]

style은 로컬 PAINT, TEXT, EFFECT 및 GRID 스타일을 다룹니다. update는 create와 동일한 유형별 JSON 속성을 허용합니다. apply는 스타일 유형을 fill, stroke, text, effect 또는 grid에 대해 검증합니다. 이름 조회는 모호성을 거부합니다. 소비자는 getStyleConsumersAsync()에서 가져오며, 게시 상태는 Figma의 UNPUBLISHED, CURRENT 또는 CHANGED 값 중 하나입니다.

변수는 토큰 파일 동기화가 소유하지 않는 메타데이터 및 모드 작업을 노출합니다:

figma_run ["var", "show", "space/md", "--collection", "Primitives"]
figma_run ["var", "update", "space/md", "--description", "Medium spacing", "--scopes", "GAP"]
figma_run ["var", "set-value", "space/md", "12", "--mode", "Light"]
figma_run ["var", "set-value", "space/card", "--alias", "space/md", "--mode", "Light"]
figma_run ["var", "code-syntax", "space/md", "WEB", "var(--space-md)"]
figma_run ["var", "resolve", "space/md", "12:34"]
figma_run ["col", "mode-add", "Primitives", "Dark"]
figma_run ["col", "mode-rename", "Primitives", "Dark", "Dim"]
figma_run ["col", "extend", "Primitives", "Brand"]

var show는 모드별 값, 범위, 코드 구문, 컬렉션 메타데이터 및 게시 상태를 반환합니다. var resolve는 의도적으로 소비자 노드를 필요로 합니다. 별칭은 해당 노드의 선택된 모드에 따라 다르게 해석될 수 있기 때문입니다. 컬렉션 show, update, mode-add, mode-rename, mode-remove 및 publish-status는 동일한 ID/정확한 이름/고유 부분 문자열 조회 정책을 따릅니다. 모드 수에 대한 Figma 계획 제한은 여전히 Figma에 의해 적용되며 오류로 표시됩니다. 컬렉션 확장은 로컬 컬렉션에 대해 VariableCollection.extend()를 사용하고, 게시된 키에 대해 extendLibraryCollectionByKeyAsync()를 사용합니다. Figma는 이 기능을 Enterprise 요금제로 제한합니다. CLI는 Figma의 요금제 오류를 변경하지 않고 보고합니다. 텍스트 스타일 바인딩은 Figma가 바인딩 가능한 타이포그래피 필드(family, style, weight, size, line height, letter spacing, paragraph 값)만 정확히 지원합니다.

활성화된 팀 라이브러리

라이브러리 검색 및 가져오기도 인증된 플러그인 전송을 통해 유지됩니다:

figma_run ["library", "collections"]
figma_run ["library", "variables", "Acme/Primitives", "--type", "COLOR"]
figma_run ["library", "import-variable", "<published-variable-key>"]
figma_run ["library", "import-style", "<published-style-key>"]
figma_run ["library", "import-component", "<published-component-key>"]
figma_run ["library", "import-component-set", "<published-component-set-key>"]

collections와 variables는 읽기입니다. 네 가지 import-* 명령어는 현재 파일에 게시된 에셋을 구체화하므로 기능 카탈로그에서 쓰기입니다. Figma는 변수 컬렉션과 변수에 대해서만 검색을 노출합니다. 게시된 스타일, 컴포넌트 및 컴포넌트 세트는 안정적인 키가 이미 알려진 경우 가져올 수 있지만, Plugin API는 이를 열거할 수 없습니다.

라이브러리는 library collections가 이를 볼 수 있도록 Figma UI에서 현재 파일에 대해 활성화되어야 합니다. Plugin API는 라이브러리를 활성화할 수 없습니다. 제공된 플러그인은 이미 필요한 teamlibrary 권한을 선언합니다. 이름 조회는 컬렉션 키, 정확한 컬렉션 이름, 그리고 명확한 컬렉션 또는 라이브러리 이름 부분 문자열을 사용합니다. 라이브러리 검색은 Bridge 마감 시간 아래에 18초의 Plugin-API 타임아웃을 가지므로, 중단된 Figma 라이브러리 요청은 작업 이름을 지정하고 라이브러리가 활성화되어 있는지 확인할 것을 제안하며, 일반적인 실행 시간 초과로 이어지지 않습니다.

프로토타입, Dev Mode 측정 및 주석

이러한 문서 기능도 Plugin-API 우선입니다:

figma_run ["prototype", "inspect", "12:34"]
figma_run ["prototype", "add", "12:34", "--trigger", "click", "--navigate-to", "12:36"]
figma_run ["prototype", "set", "12:34", "--json", "[{\"trigger\":{\"type\":\"ON_CLICK\"},\"actions\":[{\"type\":\"BACK\"}]}]"]
figma_run ["measure", "add", "12:34:right", "12:36:left", "--offset", "16", "--text", "gap"]
figma_run ["annotate", "categories"]
figma_run ["annotate", "add", "Review spacing", "--node", "12:34", "--category", "Review", "--properties", "width,fontSize"]
figma_run ["annotate", "edit", "12:34", "0", "--text", "Resolved"]

prototype set --json은 Figma의 여러 동작(SET_VARIABLE, SET_VARIABLE_MODE, 조건부 블록)에 대한 무손실 형식입니다. setReactionsAsync()를 통해 작성되므로 동적 페이지 매니페스트가 지원됩니다. 측정 쓰기는 Figma Dev Mode로 보호되며 PageNode의 기본 측정 방법을 사용합니다. 주석 인덱스는 0부터 시작합니다. categories와 함께 사용자 정의 카테고리 생성/편집/제거 명령어도 제공됩니다. 이러한 수동 검토 노트는 의미론적 렌더러의 자동 경계 대체 주석과는 독립적입니다. 자동 경계 대체 주석은 명시적으로 옵트인한 손실 매핑 정책에 의해서만 생성되며, 플러그인 데이터를 통해 기계가 읽을 수 있는 상태로 유지됩니다.

2026 Plugin API: 비디오, 셰이더, 그리드, 슬롯 및 Draw

현재 공식 Plugin API 표면은 REST 호출 대신 Figma 명령어로 노출됩니다:

figma_run ["export", "video", "12:34", "--format", "mp4", "--fps", "30", "-o", "/abs/demo.mp4"]
figma_run ["shader", "list"]
figma_run ["shader", "import", "<shader-id>"]
figma_run ["shader", "apply", "12:34", "<shader-id>", "--field", "fill", "--properties", "{\"definition-id\":0.8}"]
figma_run ["layout", "grid", "set", "12:34", "--rows", "2", "--columns", "3", "--row-gap", "12"]
figma_run ["layout", "grid", "auto-flow", "12:34", "--auto-tracks", "rows", "--positioning", "row_auto_flow"]
figma_run ["slot", "create", "12:37", "Content", "--settings", "{\"minChildren\":1,\"maxChildren\":3}"]
figma_run ["slot", "validate", "12:37"]
figma_run ["draw", "inspect", "12:38"]
figma_run ["draw", "text-path", "12:38", "--text", "Around the curve"]
figma_run ["draw", "stroke-profile", "12:38", "--preset", "TAPER"]
figma_run ["draw", "pattern", "12:38", "12:39", "--field", "fill"]

비디오 내보내기는 선택된 하위 요소를 최상위 애니메이션 프레임으로 확인하고 Figma의 형식별 FPS 값만 허용합니다. 셰이더 속성은 표시 이름이 아닌 정의 ID로 키가 지정되며, 사용 가능한 셰이더는 적용되기 전에 가져와야 합니다. layout grid는 자동 레이아웃 GRID 모델을 의미합니다. 이전 최상위 grid 명령어는 레이아웃 가이드 관리로 남아 있습니다. 슬롯은 GA SlotSettings, 선호 값, 재설정 및 제한 위반을 노출합니다. JSX <Slot>은 이제 ComponentNode.createSlot()을 사용하며 렌더링 후 구성된 제한을 검증합니다. Draw 명령어는 텍스트 경로, 반복 변환 그룹, 늘이기/분산/동적 획, 가변 너비 프로필 및 비동기 패턴 채우기/획 설정기를 다룹니다. 익숙하지 않은 문서를 수정하기 전에 해당 inspect/validate 읽기를 먼저 실행하십시오.

수정이 필요한 항목 찾기

figma_run ["analyze", "lint", "--node", "12:34"]

디자인 시스템 검토가 처리하는 네 가지 항목을 한 번에 처리합니다: 기존 변수와 일치하지만 바인딩되지 않은 색상, 기본 이름을 그대로 사용하는 레이어, 스타일이 없는 텍스트, 12px 미만의 텍스트. --fail-on-issues는 CI 게이트 역할을 합니다. --kind는 범위를 좁히고, --json은 절대 잘리지 않습니다.

하드코딩된 색상은 변수가 이미 해당 정확한 값을 보유하고 있을 때만 보고됩니다. 그렇지 않으면 결과는 조치할 수 없는 노이즈입니다. 일치 항목이 알려져 있으므로 각 항목에는 이를 수정하는 명령어가 함께 제공됩니다:

unbound token colour — 1
  12:35    Badge  fill is #8a9a8d, which is sage/400
    fix: node bind 12:35 fill "sage/400" --collection "Sprout Primitives"

analyze colors|typography|spacing은 여전히 전체 인구 조사를 제공합니다. Lint는 어떤 작업이 필요한지 여부를 판단하는 패스입니다.

가변 글꼴 및 OpenType 사실

Figma는 Plugin API를 통해 일반적인 변형 축 튜플을 노출하지 않습니다. 따라서 브리지는 Figma가 실제로 보고하는 사실과 호출자가 명시적으로 기록하는 축 의도를 분리합니다:

figma_run ["font", "inspect", "12:36"]
figma_run ["font", "inspect", "12:36", "--start", "0", "--end", "12", "--all-open-type"]

font inspect는 fontName, 숫자 읽기 전용 fontWeight, 크기, 활성화된 OpenType 기능 태그 및 해결된 타이포그래피 변수 바인딩과 함께 스타일이 지정된 텍스트 범위를 반환합니다. --all-open-type은 false 기능 값도 포함합니다. 결과는 API 제한을 명시적으로 명명합니다. 보고된 fontWeight는 일반적인 wght/wdth/opsz/사용자 정의 축 튜플이 아니며, OpenType 기능은 읽기 전용입니다.

UI 또는 다른 글꼴 도구에서 정확한 축 값을 알고 있는 경우, 텍스트 노드에 범위 메타데이터로 보존하십시오:

figma_run ["font", "remember-axes", "12:36", "wght=357,wdth=82", "--start", "0", "--end", "12"]
figma_run ["font", "axes", "12:36"]
figma_run ["font", "forget-axes", "12:36", "--start", "0", "--end", "12"]
figma_run ["font", "forget-axes", "12:36"]  # clear every stored range

remember-axes는 플러그인 메타데이터만 변경합니다. 글꼴이나 렌더링된 글리프는 절대 변경하지 않으며, 따라서 기능 카탈로그에서 쓰기로 분류됩니다. figma_spec은 이러한 레코드를 axes-meta[start:end](tag=value,…) 형식으로, Figma가 보고한 fw… 값 및 활성화된 ot(…) 태그와 함께 전달하므로, 디자인-투-코드 캡처가 문서화된 의도를 조용히 버리지 않습니다.

네이티브 Plugin API 사실

두 개의 읽기 명령어는 REST API에 접촉하지 않고 Figma 자체 표현을 노출합니다:

figma_run ["node", "css", "12:34"]
figma_run ["node", "css", "12:34", "--json"]
figma_run ["export", "node-json", "12:34"]
figma_run ["export", "node-json", "12:34", "-o", "facts/card.json"]

node css는 getCSSAsync()를 호출하고 Figma가 검사 패널에 노출하는 선언을 반환합니다. 이는 디자인 토큰 사용자 정의 속성을 내보내는 export css와 의도적으로 분리됩니다. export node-json은 exportAsync({format:"JSON_REST_V1"})을 사용합니다. 형태는 REST 파일 스키마와 유사하지만, 바이트는 라이브 플러그인 문서에서 오며 토큰이나 네트워크 요청이 필요하지 않습니다.

버전 기록 및 차이점

Figma의 플러그인 API는 버전을 쓸 수 있지만 다시 읽을 수는 없으므로, "오늘 아침 이후로 무엇이 변경되었는가"에 대한 답은 브리지 단독으로는 없습니다. history는 자격 증명 없이 이를 제공합니다. 하위 트리의 구조를 기록하고, 나중에 다시 기록한 다음, 두 개를 비교합니다.

figma_run ["history", "save", "Before refactor", "--description", "Agent restore point"]
figma_run ["history", "snapshot", "--label", "before refactor"]
# … agent works …
figma_run ["history", "diff", "latest", "live"]

history save는 saveVersionHistoryAsync()를 통해 명명된 항목을 직접 생성하며 Figma 쓰기입니다. snapshot, list 및 diff는 로컬/읽기 전용 Figma 작업으로 남아 있습니다. Figma의 기본 기록 버전을 읽으려면 여전히 선택적 REST 추가 기능이 필요합니다.

스냅샷은 노드당 하나의 정규화된 레코드(기하학, 레이아웃, 페인트, 타이포그래피, 컴포넌트 키)와 콘텐츠 해시 및 하위 트리 해시를 저장하므로, 차이점 비교 도구가 건드리지 않은 섹션을 걷지 않고 보고할 수 있습니다. 이들은 ~/.figma-bridge-mcp/snapshots/<fileKey>/에 gzip으로 압축되어 저장되며, 최신 20개가 유지됩니다.

참조는 latest, previous, history list의 인덱스, 파일 이름 또는 현재 문서의 경우 live입니다. 보고서는 추가됨, 제거됨, 대체됨, 이동됨 및 변경됨을 구분합니다. 마지막 구분이 실제로 중요합니다. 프레임을 삭제하고 다시 렌더링하는 에이전트는 이름 경로를 유지하지만 새 노드 ID를 얻으며, 대체 감지가 없으면 모든 재렌더링이 수백 개의 삭제로 읽힐 것입니다. --changelog는 대신 마크다운을 출력합니다. diff는 차이가 있을 때 종료 코드 1을 반환하므로 CI 게이트로도 작동합니다.

MCP를 통해 이는 열세 번째 도구가 아닌 매개변수입니다:

figma_history {diff: {from: "latest", to: "live"}}
figma_history {diff: {from: "version:1234", to: "version:5678"}}   # REST add-on

version: 참조는 REST 계층을 통해 이동하며 디자이너가 저장한 내용을 동일한 차이점 비교 도구로 비교합니다. 두 소스는 하나의 diff에서 혼합될 수 없습니다. REST 문서와 플러그인 스냅샷은 다른 속성을 노출하므로 모든 노드가 변경된 것처럼 보일 것입니다. 도구는 오해의 소지가 있는 출력 대신 이를 명시합니다.

Motion

Figma Motion(Config 2026 Beta)은 figma_run과 ["motion", …]을 통해 접근할 수 있습니다. 키프레임 트랙(add), JSON의 전체 사양(apply), 명명된 프리셋(preset), 노드 간 안무 오프셋(stagger), Figma의 자사 애니메이션 스타일(styles, style), 프레임 지속 시간(timeline), 읽기(inspect) 및 제거(clear)를 포함합니다.

다른 모든 명령어와 마찬가지로 플러그인 브리지를 통해 실행됩니다. 별도의 전송이 없습니다. styles와 inspect는 읽기입니다. 그 외 모든 것(timeline 포함, 인수에 따라 읽기 또는 설정)은 FIGMA_WRITE_CONFIRM=1에서 쓰기로 간주됩니다.

Motion은 Figma Beta 플래그 뒤에 출시되고 있습니다. 액세스 권한이 없으면 명령어는 MOTION_DISABLED 오류와 함께 실패하며, 일반적인 API 실패 대신 Figma Desktop을 업데이트하라고 알려줍니다.

REST 추가 기능(선택 사항)

위의 모든 것은 Figma 자격 증명이 전혀 없이 작동합니다. 로컬 플러그인 브리지가 구조적으로 도달할 수 없는 세 가지 항목은 Figma의 REST API 뒤에 있으며, 개인 액세스 토큰으로 잠금 해제할 수 있습니다:

활성화 — 토큰이 기기를 떠나지 않음:

1. Figma에서 개인 액세스 토큰을 생성합니다(설정 → 보안 → 개인 액세스 토큰). 범위: 파일 콘텐츠(읽기), 파일 버전(읽기), 댓글(읽기 및 쓰기). *현재 사용자(읽기)*는 선택 사항입니다. 이는 figma_status에서 사용자 핸들을 표시하는 데만 사용됩니다.

2. Figma Desktop에서 Figma Bridge 플러그인을 열고 연결합니다(플러그인이 인증되면 필드가 나타납니다). **"REST 토큰(선택 사항)"**을 확장합니다. 토큰을 붙여넣고 토큰 저장을 클릭합니다.

3. figma_status는 원격 요청 없이 토큰이 구성되었음을 보고합니다. 명시적 유효성 검사가 필요할 때 figma_status {validateRest:true}를 실행하면 사용자 핸들을 보고하거나, 선택적 현재 사용자 범위가 없을 때 파일 액세스를 확인합니다.

토큰은 플러그인에서 인증된 localhost WebSocket을 통해 데몬으로 전송되며, 데몬은 이를 ~/.figma-bridge-mcp/rest-token(모드 0600)에 저장합니다. 토큰은 채팅에 입력되지 않으며, MCP 클라이언트 구성에 저장되지 않으며, 어떤 도구에서도 다시 에코되지 않으며, 감사 로그에 기록되지 않습니다(REST 호출은 메서드 + 경로만 기록됨). 플러그인의 토큰 지우기는 파일을 제거합니다.

헤드리스/CI 대안: FIGMA_REST_TOKEN 환경 변수를 설정하면 파일을 재정의합니다.

범위: 기본적으로 REST 호출은 Figma Desktop에서 현재 열려 있는 파일을 대상으로 합니다(플러그인이 파일 키를 푸시함). 다른 파일은 명시적 fileKey 매개변수(베어 키 또는 전체 Figma URL)가 필요합니다. PAT 자체는 해당 계정이 액세스할 수 있는 모든 파일을 읽을 수 있으므로 범위를 최소로 유지하십시오.

REST 클라이언트는 폐쇄된 내부 허용 목록이며, 일반 HTTP 이스케이프 해치가 아닙니다. 토큰 상태, 버전 목록, 버전 고정 문서 콘텐츠, 댓글, 파일 전체 게시된 컴포넌트 메타데이터를 허용합니다. 베어 현재 파일 가져오기 및 모든 노드/CSS/내보내기/변수/스타일/Dev-Resource 엔드포인트는 토큰을 읽거나 네트워크에 접촉하기 전에 거부됩니다. 이러한 작업은 위의 로컬 Plugin API 명령을 사용해야 합니다.

보안 모델

• Figma API 토큰 불필요 — Figma는 로컬 플러그인을 통해 구동되며, api.figma.com을 사용하지 않습니다. REST 추가 기능은 엄격히 옵트인입니다. 토큰이 없으면 코드 경로는 비활성화되며, 토큰이 있으면 MCP 클라이언트 구성이 아닌 0600 파일(또는 사용자 환경 변수)에 저장됩니다.

• 바이너리 패치 없음 — Yolo/CDP 모드는 벤더된 엔진에서 제거되었습니다.

• 기능 게이트 명령 — figma_run은 기능 카탈로그(Capability Catalog)에서 노출된 명령만 허용합니다. connect는 노출되지 않으므로 안전 모드 전용 연결이 강제됩니다. 동일한 해결된 계획이 쓰기 확인 게이트, 대상 요구 사항 및 재시도 정책을 구동하여 어댑터 드리프트를 방지합니다.

• 셸 없음 — 엔진은 execFile(shell:false)로 생성됩니다.

• 2계층 데몬 인증, 와이어에 비밀 없음 — 서명된 HTTP 요청(메서드/경로/본문에 대한 요청별 HMAC, 세션 토큰으로 키 지정, nonce 재생 방지) + 플러그인 소켓의 상호 challenge-response 핸드셰이크(Origin/Host 허용 목록). 세션 토큰이나 액세스 키는 어느 방향으로도 전송되지 않습니다. 핸드셰이크 참조.

• Localhost 잠금 플러그인 — plugin/manifest.json은 networkAccess.allowedDomains를 ws://127.0.0.1:3456–3460으로 제한합니다.

• 격리된 상태 — 토큰, pid, 키 및 감사 로그는 ~/.figma-bridge-mcp/ 아래에 있으며, 업스트림 figma-ds-cli 설치와 분리됩니다.

• 감사 로그 — 실행된 모든 명령은 ~/.figma-bridge-mcp/audit.log에 추가됩니다(터치된 노드 ID, 선택적 레이블, 성공/실패를 기록하는 완료 항목 포함 — figma_history의 데이터 소스). 5MB에서 순환됩니다. 이전 세대(audit.log.1) 하나가 유지되며 figma_history에서 계속 읽습니다.

포트 폴백. 데몬은 3456–3460 범위에서 첫 번째 사용 가능한 포트에 바인딩하고 ~/.figma-bridge-mcp/daemon-port에 게시합니다. CLI/MCP 계층은 호출 시 포트를 확인합니다(env DAEMON_PORT > 포트 파일 > 3456). 플러그인은 전체 범위를 스캔하므로, 외부 프로세스가 3456을 점유해도 더 이상 연결을 차단하지 않습니다. 점유자 확인은 인증되지 않은 /health 프로브이며, 인증된 요청은 HMAC 서명됩니다. 범위 포트의 점유자는 세션 토큰이나 재생 가능한 어떤 것도 볼 수 없습니다(서명은 타임스탬프, nonce, 메서드, 경로 및 본문을 바인딩하며, 데몬은 재사용된 nonce를 거부합니다). 플러그인 소켓은 동일한 이유로 모든 범위 포트에서 안전합니다. 아래 핸드셰이크는 비밀을 전달하지 않으며 실행된 포트를 바인딩합니다. DAEMON_PORT를 명시적으로 설정하면 폴백이 비활성화됩니다. 3456–3460 범위 밖의 값은 지원되지 않습니다. 플러그인 매니페스트는 Figma에 의해 강제되며 해당 범위에 도달할 수 없습니다.

핸드셰이크

플러그인 소켓은 상호 challenge-response(프로토콜 2, engine/src/lib/plugin-handshake.js)를 실행합니다.

daemon → plugin   {type:'challenge', proto:2, nonce:<dNonce>, port:<bound>}
plugin → daemon   {type:'hello', proto:2, nonce:<pNonce>, version, proof}
daemon → plugin   {type:'hello-ack', proof, restTokenConfigured}

여기서 proof = HMAC-SHA256(access key, transcript)는 두 nonce, 바인딩된 포트 및 플러그인 버전에 대한 것입니다. 방향별로 고유한 역할 레이블과 nonce 순서가 있으므로, 어느 proof도 다른 방향으로 재생될 수 없습니다. 세 가지 속성이 따릅니다:

• 키는 와이어를 절대 건너지 않습니다. 데몬보다 먼저 범위 포트를 바인딩하고 전체 교환을 기록하는 프로세스는 다시는 볼 수 없는 nonce에 대한 하나의 HMAC를 학습합니다. 이는 이전 버전에서 문서화된 잔여 위험(원시 키가 플러그인이 보낸 첫 번째 프레임이었던)을 제거합니다.

• 데몬도 자신을 증명합니다. 프로토콜 2 이전에는 플러그인이 응답하는 모든 것을 신뢰했으며, 전송된 모든 eval을 실행했습니다. 데몬을 가장하는 데 키가 전혀 필요하지 않았습니다. 이제 패널은 ack가 확인될 때까지 모든 명령을 거부합니다.

• 바인딩된 포트는 전사(transcript) 내에 있습니다. 3456의 점유자가 실제 데몬(3457)으로 전달하면 플러그인은 3456에 서명하고 데몬은 3457을 확인하므로 릴레이가 실패합니다.

프로토콜 1 폴백은 없습니다. figma_connect는 실행할 때마다 설치된 플러그인 파일을 새로 고칩니다. 따라서 업그레이드는 figma_connect를 실행한 다음 플러그인 창을 닫고 다시 열면 됩니다. 오래된 패널은 조용히 약한 핸드셰이크를 수행하는 대신 정확히 그 내용을 설명하는 명명된 오류를 받습니다.

패널은 자체 SHA-256/HMAC 구현을 포함합니다. 플러그인 UI는 샌드박스 처리된 null-origin iframe이며, WebCrypto 가용성은 보장할 수 없습니다. 인증 핸드셰이크에서 더 약한 것으로의 조용한 폴백은 최악의 결과입니다. tests/plugin-handshake.test.js는 Node의 crypto에 대해 해당 제공 코드를 실행하므로 두 구현이 분리될 수 없습니다.

알려진 제한 사항

• Figma Slides는 베타이며 의도적으로 제한됩니다. 그리드 검사, 슬라이드 생성/복제/이동/삭제, 건너뛰기 상태 및 전환이 지원됩니다. 발표자 노트, 대화형 투표/임베드, 발표자 컨트롤 및 완전한 콘텐츠 제작 워크플로는 지원되지 않습니다. 실행 가능한 후보와 Plugin API 경계는 Slides 로드맵을 참조하십시오.

• 로컬호스트가 아닌 네트워크 작업은 적고 명시적입니다. api setup(Figma Plugin API 문서 미러의 일회성 git clone, figma_reference용), api gap(설치된 공식 @figma/plugin-typings 패키지에 대해 측정), import/map storybook의 Storybook 인덱스 가져오기(전달하는 URL/디렉토리), 그리고 REST 추가 기능을 선택한 경우에만 api.figma.com 호출입니다. 그 외에는 네트워크와 통신하지 않습니다. 업스트림의 iconify/unsplash/remove.bg/screenshot-url 통합은 완전히 제거되었습니다. figma_render JSX의 <Icon>은 명명된 플레이스홀더로 렌더링됩니다(실제 아이콘은 export assets를 통해 Figma 파일에서 가져옵니다).

• 단일 전송, CDP 잔재 없음. 모든 명령은 동일한 방식으로 Figma에 도달합니다. 엔진 → 데몬 → 플러그인 eval. 업스트림의 Chrome-DevTools 클라이언트, figma-use 셸 왕복, 바이너리 패치 init 마법사 및 figma-use 종속성이 모두 제거되었습니다(약 5,600줄 제거). 따라서 플러그인 브리지를 우회할 수 있는 두 번째 코드 경로가 없습니다.

개발

npm run check:contracts       # static JavaScript seam + plugin contracts
npm run check:architecture-latency # warmed latency budget in an idle process
npm run measure:architecture  # context, payload and local latency baselines
npm test                      # all contracts and regression suites

현재 도메인 언어는 CONTEXT.md에, 수용된 아키텍처 결정은 docs/adr/에, API 적용 범위는 docs/figma-plugin-api-coverage.md에, 릴리스 지침은 docs/releasing.md에 있습니다. 공개 문서 색인은 docs/README.md입니다.

업스트림 figma-cli를 동시에 실행하지 마십시오. 데몬은 이제 3456이 사용 중일 때 3456–3460 범위 내에서 폴백하므로 둘 다 공존할 수 있지만, 플러그인은 전체 범위를 스캔하고 두 데몬은 다른 액세스 키를 사용합니다. 플러그인이 먼저 도달하는 데몬은 동전 던지기와 같습니다. 이 빌드는 자체 토큰/pid/포트 파일을 ~/.figma-bridge-mcp/ 아래에 격리합니다.

라이선스

figma-bridge-mcp는 MIT 라이선스에 따라 배포됩니다. "있는 그대로" 제공되며, 보증 없음; 정확한 보증 및 책임 조건은 라이선스 자체에 명시되어 있습니다. 타사 저작권 및 라이선스 고지는 NOTICE 및 engine/LICENSE에 보관됩니다.

영감 및 귀속

두 프로젝트가 각기 다른 방식으로 이 프로젝트를 형성했습니다.

figma-cli(Sil Bormüller)는 engine/ 디렉토리의 출처입니다. 2026년 7월 v2.1.0에서 벤더링되었으며 이후 분기되었습니다. CDP 전송 및 바이너리 패치 설치 프로그램은 제거되었고, 플러그인 소켓은 인증되었으며, 엔진이 현재 수행하는 대부분의 작업은 여기서 작성되었습니다. 4개의 파일이 업스트림과 바이트 단위로 동일하게 유지됩니다. 업스트림 MIT 라이선스는 engine/LICENSE에 전체가 보존되며, NOTICE는 변경된 사항을 기록합니다.

figma-console-mcp는 코드보다는 아이디어를 기여했습니다. Figma 브리지가 진정한 로컬(루프백 인터페이스의 플러그인 소켓, 클라우드 릴레이 없음, 패치된 바이너리 없음)이 될 수 있다는 것입니다. 여기에는 해당 소스에서 파생된 것이 없습니다. 도구 표면, 전송 및 플러그인은 관련이 없습니다. 이 프로젝트가 다른 점은 소켓이 상대방이 누구인지도 증명한다는 것입니다.

플러그인 ID. 개발 매니페스트는 제품 정렬 ID figma-bridge-mcp 및 figma-bridge-mcp-dev를 사용합니다. Figma는 clientStorage(페어링된 액세스 키가 저장되는 곳)를 플러그인 ID에 키잉합니다. 따라서 0.5.0 이전의 설치는 매니페스트를 다시 가져오고 기존 Bridge 액세스 키를 한 번 붙여넣어야 합니다.