Related Pages

Related topics: System Architecture and Data Flow, MCP Tools and Capabilities

Overview and Getting Started

Design Context Bridge is an independent Model Context Protocol (MCP) server that supplies AI agents with real, structured Figma design context. It exposes two interchangeable transport modes — a Figma plugin for live selection-driven access and a REST API for any file reachable by URL plus a personal access token — so that the same MCP tool surface works whether or not the Figma desktop client is running. Source: README.md:1-40

Purpose and Scope

The server's role is to bridge the gap between design assets (colors, typography, spacing, components, frames) and code-generating or design-aware agents. Without it, an agent must rely on screenshots, hand-written specs, or the Figma UI to interpret a file; with it, the agent receives normalized, queryable values that can be reused across a tool chain. Source: README.md:14-38

The scope deliberately excludes rendering, code generation, and asset export. It focuses on three concerns:

• Context extraction — reading nodes, styles, variables, and tokens from a Figma document.
• Context navigation — walking the document tree by frame, page, or selection.
• Context delivery — exposing the above as MCP tools consumable by any compatible client.

Source: README.md:20-44

Architecture and the Two Modes

The MCP server is implemented in TypeScript and packaged as an npm module. The entry point composes the tool registry and wires up the transport, which is selected at startup based on configuration. Source: src/index.ts:1-80

                  ┌──────────────────────────┐
                  │   MCP-compatible client  │
                  │  (Claude, Cursor, etc.)  │
                  └────────────┬─────────────┘
                               │ MCP protocol
                  ┌────────────▼─────────────┐
                  │  design-context-bridge   │
                  │        (MCP server)      │
                  └─────┬───────────────┬────┘
                        │               │
              ┌─────────▼─────┐   ┌─────▼────────┐
              │  Figma plugin │   │   REST API   │
              │ (live select) │   │ (url+token)  │
              └─────────┬─────┘   └─────┬────────┘
                        │               │
                        └───────┬───────┘
                                ▼
                       Figma REST / Plugin API

The two modes are functionally equivalent for document and navigation tools, but only the plugin mode can read the user's currently selected node without a file URL. The REST mode requires a url parameter and a FIGMA_TOKEN for any read operation, and is therefore suitable for headless agents and CI workflows. Source: README.md:30-56, docs/rest-api.md:1-40

The plugin is not yet listed on the Figma Community page, so manual installation is the supported path. Source: docs/plugin-setup.md:1-30

Getting Started

Prerequisites are intentionally minimal:

• Node.js 18 or later (for the npm-published server). Source: package.json:18-42
• A Figma personal access token, exported as FIGMA_TOKEN. Source: README.md:46-58
• Either a Figma desktop client (plugin mode) or a file URL you have access to (REST mode). Source: docs/rest-api.md:8-22

REST API path

1. Install the server into your MCP-compatible client, or run it locally via npx design-context-bridge. Source: README.md:48-62
2. Set FIGMA_TOKEN in the environment so outgoing requests can authenticate. Source: docs/rest-api.md:12-26
3. Pass a url parameter — either a Figma file URL or a node URL — to tools such as extract_design or get_document. Source: docs/rest-api.md:20-44

Network behavior is hardened against Figma rate limits: a 30-second in-memory cache prevents redundant calls within a single tool chain, and 429 responses are retried up to three times with exponential backoff while honoring the Retry-After header. Source: README.md:64-72

Plugin path

1. Build the plugin bundle and load it as an unsaved plugin via Plugins → Development → Import plugin from manifest. Source: docs/plugin-setup.md:10-38
2. Start the local MCP server so the plugin can hand selections to it. Source: docs/plugin-setup.md:24-52
3. Select a node in Figma; the inspector surfaces colors, typography (family, size, weight, and full CSS), and spacing, and every value is one click away from being copied to the clipboard. Source: README.md:74-90

The plugin UI respects the host's appearance via Figma's themeColors, and typography values now include fontStyle so weight is reported explicitly. Source: README.md:78-92

Client Configuration

Both modes are exposed to clients through a standard MCP server entry point. Common clients (Claude Desktop, Cursor, and other MCP-aware tools) are configured by pointing the client at the package and providing the environment variables documented in docs/clients.md. Configuration snippets typically include:

• command: the server entry (commonly npx design-context-bridge).
• args: optional flags to force REST mode or set a default file.
• env: FIGMA_TOKEN and any optional cache/timeout overrides.

Source: docs/clients.md:1-60

After configuration, restart the client so it re-reads the MCP server list. New tools such as extract_design, get_document, and navigation helpers will appear under the server's namespace and can be invoked directly by the agent. Source: src/index.ts:60-120, docs/clients.md:30-72

Where to Go Next

• For tool-by-tool reference, see the dedicated pages generated from src/index.ts and the README's tool catalog. Source: README.md:90-130
• For transport-specific options, consult docs/plugin-setup.md and docs/rest-api.md.
• For client wiring examples, see docs/clients.md.

Related Pages

Related topics: Overview and Getting Started, MCP Tools and Capabilities, Figma Plugin, Reliability, Security, and Operations

System Architecture and Data Flow

Design Context Bridge is an independent Model Context Protocol (MCP) server that exposes Figma design data to AI agents. The codebase is split into two parallel data acquisition channels — a live plugin channel over WebSocket and a stateless REST channel against the Figma HTTP API — unified behind a single MCP tool surface so that agents get consistent shapes regardless of source. Source: src/index.ts:1-40

High-Level Architecture

The server entry point at src/index.ts boots the MCP transport, registers tool handlers, and routes each incoming tool call to either the plugin bridge or the REST client based on the arguments supplied. The tool surface is identical in both modes; only the acquisition backend differs. Source: src/index.ts:40-120

Shared type definitions live in src/core/types.ts and describe the normalized representations of nodes, styles, colors, typography, and spacing that both backends must return, so downstream analysis tools (such as extract_design_tokens) can consume either channel without branching. Source: src/core/types.ts:1-80

flowchart LR
  Agent[AI Agent] -->|MCP call| Server[design-context-bridge<br/>src/index.ts]
  Server -->|plugin tools| WS[ws-server.ts]
  WS <-->|WebSocket| Plugin[Figma Plugin]
  WS --> Store[store.ts<br/>selection cache]
  Server -->|REST tools| Client[client.ts<br/>+ cache + 429 retry]
  Resolve[resolve.ts] --> Client
  Client -->|HTTP| API[Figma REST API]
  Server -->|normalized types| Agent

Plugin Mode — Live Selection

When the user prefers live context from an open Figma file, the Figma plugin connects to a WebSocket server implemented in src/figma-bridge/ws-server.ts. The plugin pushes events such as selectionchange and documentinfo; the server accepts them, validates payloads against src/core/types.ts, and stores the latest snapshot. Source: src/figma-bridge/ws-server.ts:1-100

src/figma-bridge/store.ts is the in-memory state layer for this mode. It exposes read accessors keyed by session and node ID so MCP handlers can resolve the currently selected node synchronously without re-asking the plugin on every call. Because the plugin is the source of truth, there is no HTTP caching here — staleness is bounded by the plugin's event stream. Source: src/figma-bridge/store.ts:1-90

This mode is the foundation of the v1.1.0 copy-to-clipboard inspector, which reads selection state from the store and renders normalized values (hex colors, typography with fontStyle, spacing) back into the plugin UI. Source: src/core/types.ts:80-140

REST Mode — Stateless URL

When no plugin is connected, the server accepts a Figma file url plus a personal access token. src/figma-rest/resolve.ts parses the URL into the canonical file_key and optional node_id, producing a stable cache key for downstream requests. Source: src/figma-rest/resolve.ts:1-70

src/figma-rest/client.ts wraps the Figma REST endpoints (/v1/files/:key, /v1/files/:key/nodes, etc.) and applies two reliability layers introduced in v1.0.1:

• A 30-second in-memory cache keyed by (file_key, node_id, endpoint). This deduplicates calls inside a single tool chain where the agent may redundantly re-query the same node. Source: src/figma-rest/client.ts:1-90
• A 429 retry policy that retries up to 3 times with exponential backoff, respecting the Retry-After header set by Figma. Source: src/figma-rest/client.ts:90-160

REST parity ensures document and navigation tools work without the plugin, which is critical when the agent is working against a file the user does not have open in Figma.

Request Lifecycle and Dispatch

A typical tool call follows this path:

1. The MCP client (agent) invokes a tool by name with arguments.
2. src/index.ts resolves the handler; if arguments include a url, the REST resolver is engaged, otherwise the WebSocket store is queried for live selection.
3. The chosen backend returns raw Figma data, which is mapped through src/core/types.ts normalizers.
4. The server serializes the result as an MCP response; the cache layer records it for the configured TTL.

Because both backends converge on the same normalized types, higher-level analysis tools remain single-implementation. The plugin is currently distributed via manual install (documented as the primary path in v1.1.0), while the REST mode requires only a token — which lowers friction for cloud-hosted agents that cannot run the Figma desktop client.

This separation of concerns — shared types, two interchangeable backends, and reliability middleware in the REST client — is what lets the project describe itself as "an independent MCP server that gives AI agents real Figma design context" without coupling agents to a specific Figma session.

Related Pages

Related topics: Overview and Getting Started, System Architecture and Data Flow

MCP Tools and Capabilities

The design-context-bridge project exposes its functionality to AI agents through the Model Context Protocol (MCP). The MCP layer is a thin, well-typed contract surface: each design-context operation (inspecting colors, typography, spacing, interactions, the current selection) is implemented as a discrete MCP tool and registered with the MCP server via a central tool registry. Agents consume these tools through their normal MCP client, while humans inspect the same data visually through the Figma plugin UI.

1. Architectural Role

The MCP server acts as the protocol bridge between an LLM agent and two backends:

1. The Figma plugin backend, which forwards the live selection and document state from the user's Figma editor.
2. The REST API backend, which can resolve any Figma file by URL + personal access token without requiring the plugin to be installed.

Source: src/mcp-server/tool-registry.ts:1-40

Most tools are written so that both backends can satisfy them. Document- and navigation-style tools (get_current_selection style reads, structure queries) work over REST, while richer selection-bound tools (colors, text, spacing, interactions) prefer plugin data when available. This split is described as "REST parity" in the v1.0.0 release notes and is the reason a tool like get-current-selection can degrade gracefully when no plugin is connected.

2. Tool Registry and Dispatch

All MCP tools are registered through a single registry module. The registry owns:

• The canonical list of tool names and their MCP-compatible schemas (name, description, inputSchema).
• A dispatcher that resolves incoming tools/call requests to the correct handler.
• Shared cross-cutting concerns: the 30-second in-memory cache, the 429 retry policy with exponential backoff honoring Retry-After, and error normalization for the MCP response envelope.

Source: src/mcp-server/tool-registry.ts:41-90

Because each tool is registered as a small module under src/mcp-server/tools/, the registry can be extended without touching the server core. Adding a new capability means: implement the handler, declare its schema, and append it to the registry. This keeps the surface area auditable for an AI agent and easy to test in isolation.

3. Selection-Bound Tools

The selection-bound tools all follow the same shape: read the current Figma selection (from the plugin channel when available, otherwise from REST given a nodeId / URL), normalize the result into a deterministic JSON shape, and return it. The plugin side additionally renders an inspector panel where each emitted value can be clicked to copy it to the clipboard (hex colors, font properties, CSS, spacing values), as introduced in v1.1.0.

`get-current-selection`

Resolves the active selection and returns the node identifiers that downstream tools can pivot on. It is the typical entry point for an agent that wants to inspect what the user is currently looking at in Figma.

Source: src/mcp-server/tools/get-current-selection.ts:1-60

`get-selected-colors`

Walks the selection tree, collects solid fills and strokes, and emits normalized hex strings. The v1.1.0 plugin inspector renders each hex with a click-to-copy affordance, matching the JSON value the MCP client receives.

Source: src/mcp-server/tools/get-selected-colors.ts:1-80

`get-selected-texts`

Returns typography descriptors for each text node in the selection. As of v1.1.0, the payload includes fontStyle (weight) alongside fontFamily, fontSize, and a full CSS string for direct paste into stylesheets.

Source: src/mcp-server/tools/get-selected-texts.ts:1-80

`get-selected-spacing`

Reads layout spacing properties (padding, item spacing, constraints) from frames and auto-layout containers in the selection and emits them as discrete numeric values. The plugin inspector exposes these as click-to-copy values for design handoff.

Source: src/mcp-server/tools/get-selected-spacing.ts:1-80

`get-selected-interactions`

Enumerates prototype reactions on the selection — triggers, action types, and destination node ids — so agents can reason about user flows rather than just static visuals.

Source: src/mcp-server/tools/get-selected-interactions.ts:1-80

4. Resilience Layer

Two behaviors added in v1.0.1 apply uniformly across the tool surface:

• In-memory cache (30s TTL): redundant calls inside a single tool chain (for example, an agent that asks for selection, then colors, then texts in quick succession) hit the cache instead of round-tripping to Figma again.
• 429 retry with exponential backoff: when the Figma API rate-limits a request, the tool retries up to three times, honoring the Retry-After header between attempts.

Source: src/mcp-server/tool-registry.ts:91-140

These are deliberately implemented at the registry level rather than inside each tool, so every capability inherits the same stability guarantees without per-tool duplication.

5. Tool Flow

flowchart LR
    A[AI Agent / MCP Client] -->|tools/call| B[tool-registry.ts]
    B --> C{Plugin Connected?}
    C -- yes --> D[Plugin Channel]
    C -- no --> E[REST API + Token]
    D --> F[Selection Tools]
    E --> F
    F --> G[30s Cache]
    G --> H[429 Retry Layer]
    H --> I[Figma API]
    I --> H
    H --> G
    G --> F
    F --> J[Normalized JSON]
    J --> A

The flow illustrates that regardless of which tool the agent invokes, requests converge on the registry, are routed to the appropriate backend, and pass through the shared cache and retry layer before returning a normalized payload.

Summary

The MCP surface of design-context-bridge is intentionally small and uniform: a registry that owns dispatch, caching, and retries, plus a set of focused selection-bound tools (get-current-selection, get-selected-colors, get-selected-texts, get-selected-spacing, get-selected-interactions). The plugin backend and REST backend are interchangeable for document-level reads, and the v1.1.0 inspector mirrors the tool payloads visually for human design work.

Related Pages

Related topics: System Architecture and Data Flow, MCP Tools and Capabilities

Figma Plugin, Reliability, Security, and Operations

The design-context-bridge project exposes Figma design context to AI agents through two complementary surfaces: a Figma plugin that operates on the user's live selection, and an independent MCP server that talks to Figma's REST API. The topics below cover the plugin's runtime structure, the reliability safeguards that protect tool chains against throttling, the security posture of the system, and the operational steps required to run it.

1. Figma Plugin Architecture

The plugin lives entirely under figma-plugin/ and is shipped as an unpacked bundle that must be installed manually because it is not yet listed on the Figma Community marketplace. The bundle is intentionally small and uses Figma's standard sandboxed plugin model.

• figma-plugin/manifest.json declares the plugin identity, the document access level, and the entry points. It binds the plugin's main thread (code.js) and its UI (ui.html) and requests the network capability required to reach the MCP server. Source: figma-plugin/manifest.json
• figma-plugin/code.ts is the TypeScript source that runs in the plugin sandbox. It listens for selection changes, walks the current page tree, extracts styles (colors, typography, spacing), and posts structured payloads to the UI. Source: figma-plugin/code.ts
• figma-plugin/code.js is the compiled JavaScript produced from code.ts; Figma loads this file at runtime, so the build step is part of normal operations. Source: figma-plugin/code.js
• figma-plugin/ui.html renders the inspector panel. In v1.1.0 it gained a click-to-copy inspector (colors → hex, typography → family/size/weight or full CSS, spacing → pixels) and switched to native light/dark theming via Figma's themeColors. It also now exposes fontStyle for typography entries. Source: figma-plugin/ui.html
• figma-plugin/tsconfig.json configures the TypeScript build that produces code.js from code.ts. Source: figma-plugin/tsconfig.json

The plugin does not, by itself, talk to Figma's REST API for the document it is inspecting; it reads the live document through Figma's plugin APIs. The MCP server (src/figma-rest/client.ts) handles remote access via url plus a personal access token.

2. Reliability: Caching and 429 Handling

Reliability matters because a single agent workflow may chain many tool calls in quick succession, each of which can hit the Figma REST API. Version v1.0.1 introduced two safeguards inside src/figma-rest/client.ts:

• In-memory cache (30s TTL) — Identical requests issued within a 30-second window are served from cache instead of re-hitting Figma. This reduces redundant round-trips inside a single tool chain and lowers the chance of triggering rate limits. Source: src/figma-rest/client.ts
• 429 retry with exponential backoff — When the API responds with HTTP 429 (Too Many Requests), the client retries up to three times. Each retry waits exponentially longer and respects any Retry-After header returned by Figma, so the client yields backoff time the server actually requested rather than guessing. Source: src/figma-rest/client.ts

Together, these mechanisms turn transient throttling into transparent retries and collapse repeated calls within a workflow into a single network request, which keeps multi-step agent runs stable.

3. Security Posture

The project is designed so that credentials never leave the operator's machine unless explicitly configured:

• The Figma personal access token is supplied by the caller (CLI flag, environment variable, or MCP client config) and is forwarded per request inside src/figma-rest/client.ts. It is not persisted to disk by the server.
• The Figma plugin runs inside Figma's sandbox and only communicates with the MCP server endpoint the user configures. Because the plugin is installed manually from source, the user audits manifest.json, code.ts, and ui.html before loading it.
• No telemetry is collected by the MCP server; the only outbound traffic is the authenticated request to api.figma.com.

4. Operations: Install and Build

Operational steps reflect the "manual install is primary" guidance introduced with v1.1.0:

Because the plugin is not on the Figma Community, every operator must perform steps 2–3 locally. Keeping code.ts and manifest.json under version control makes the install auditable, and rebuilding code.js after edits to code.ts ensures the loaded bundle matches reviewed source. Source: figma-plugin/tsconfig.json, figma-plugin/manifest.json

Summary

The plugin surface (figma-plugin/code.ts, ui.html, manifest.json) gives AI agents low-latency access to the currently selected node, while src/figma-rest/client.ts provides a parity path for any file by URL. The 30-second cache and 429 retry logic introduced in v1.0.1 keep chained tool calls reliable, the security model keeps the Figma token local to the operator, and the manual install path keeps the deployment auditable — consistent with the v1.1.0 release notes that document manual install as the primary workflow.

Doramagic Pitfall Log

Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.1.0 — copy-to-clipboard inspector
• User impact: Upgrade or migration may change expected behavior: v1.1.0 — copy-to-clipboard inspector
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.1.0 — copy-to-clipboard inspector. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.1.0

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/CristinaFores/design-context-bridge

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/CristinaFores/design-context-bridge

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/CristinaFores/design-context-bridge

6. Runtime risk: Runtime risk requires verification

• Severity: low
• Finding: Developers should check this performance risk before relying on the project: v1.0.1 — fix: in-memory cache + 429 retry
• User impact: Upgrade or migration may change expected behavior: v1.0.1 — fix: in-memory cache + 429 retry
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.0.1 — fix: in-memory cache + 429 retry. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.0.1

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: Developers should check this maintenance risk before relying on the project: v1.0.0 — Design Context Bridge
• User impact: Upgrade or migration may change expected behavior: v1.0.0 — Design Context Bridge
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.0.0 — Design Context Bridge. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.0.0

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using design-context-bridge with real data or production workflows.

• v1.1.0 — copy-to-clipboard inspector - github / github_release
• v1.0.1 — fix: in-memory cache + 429 retry - github / github_release
• v1.0.0 — Design Context Bridge - github / github_release
• Capability evidence risk requires verification - GitHub / issue