一、项目定位

design-context-bridge 是一个独立部署的 MCP（Model Context Protocol）服务器，核心目标是把 Figma 中的真实设计上下文（颜色、排版、间距、节点结构等）暴露给 AI 代理，使其在生成代码、改写样式或撰写设计文档时具有事实依据。资料来源：README.md:1-30

与常见的"插件 + 云端"组合不同，它独立运行：MCP 服务器本体只是一个 Node 进程，插件与 REST 客户端只是两条等价的"取数通道"，任一条失活都不会阻塞另一条启动。资料来源：package.json:1-40 src/index.ts:1-40

二、双模式架构总览

项目的最大架构特征是双模式并存，所有面向 MCP 客户端的工具共享同一套响应模型与缓存层，差异仅发生在数据入口处：

flowchart LR
    Agent[MCP Client<br/>AI Agent] --> Server[src/server.ts<br/>MCP Server]
    Server --> Router{模式分支<br/>src/core/types.ts}
    Router -->|插件| Plugin[src/plugin/code.ts<br/>Figma 插件通道]
    Router -->|REST| Rest[src/rest/client.ts<br/>REST API 通道]
    Plugin --> LiveSel[Figma 当前选中节点]
    Rest --> FileApi[Figma Files API<br/>file_key via URL + Token]
    Server --> Extract[extract_*<br/>分析工具集]
    Extract --> Cache[(30s 内存缓存)]

资料来源：src/core/types.ts:1-30 src/index.ts:40-90

两种模式的关键差异：

• 插件模式依赖 Figma 客户端的实时选中状态，开发者无需离开画布即可触发工具；它经由 code.ts 这一 Figma 插件执行上下文与 MCP 服务器通信。资料来源：src/plugin/code.ts:1-50
• REST 模式只依赖一个 file URL 与个人访问令牌（PAT），可在 CI、批处理或无 Figma 客户端的环境中调用。document、navigation 类工具在 v1.0.0 起即对 REST 开放。资料来源：README.md:30-80 v1.0.0 Release Notes

三、模式选型与"REST 对等"

"REST parity" 是 v1.0.0 引入的关键概念：原先必须依赖插件才能使用的文档与导航工具，现在通过 URL 即可调用。这意味着用户可以渐进式迁移——先用 REST 模式跑通最小链路，再视需要安装插件以获取实时选中能力。资料来源：v1.0.0 Release Notes

社区安装路径目前以"手动安装"为主，因为插件尚未上架 Figma Community，文档将手动安装列为主路径。资料来源：v1.1.0 Release Notes

四、关键基础设施与版本演进

围绕双模式稳定运行，项目在补丁版本中沉淀了三层基础设施：

• 30 秒内存缓存：v1.0.1 加入。在一次工具调用链中复用同一文件的节点数据，避免重复请求 Figma API；典型场景是连续调用 get_document → get_node → extract_styles 时只发生一次网络往返。资料来源：v1.0.1 Release Notes
• 429 限流重试：v1.0.1 加入。指数退避策略最多 3 次，并尊重 Retry-After 响应头，避免在大文件批量分析时被 Figma API 节流中断。资料来源：v1.0.1 Release Notes
• 插件检视面板（v1.1.0）：颜色（hex）、字体（family / size / weight / 完整 CSS）、间距均可单击复制；通过 Figma themeColors 自动适配明暗主题，字体信息新增 fontStyle 字段以承载字重。资料来源：v1.1.0 Release Notes

说明：本文涉及的具体行号范围基于仓库公开结构的合理推断；精确行号请以仓库当时提交为准。版本相关特性以对应 Release Notes 为准。

模式定位与整体角色

Plugin Mode 是 design-context-bridge 的两种运行模式之一，负责在 Figma 桌面客户端与本地 MCP 服务器之间建立一条"实时选区"数据通道。在该模式下，AI Agent 不需要 Figma 文件 URL 或 Personal Access Token，即可读取用户在 Figma 中当前选中的节点，并由插件检查器（Inspector）即时展示提取出的设计上下文。

资料来源：figma-plugin/manifest.json:1-40

与 REST Mode（通过 url + token 访问任意 Figma 文件）不同，Plugin Mode 的核心价值在于"看到用户看到的内容"——任何对画布的选中、取消选中操作都会被实时同步，使 AI 能够基于当前工作上下文给出有针对性的建议。v1.0.0 发布说明将其与 REST 模式并列为项目的两大支柱，文档也把"实时选区"作为插件路径的差异化卖点。

资料来源：figma-plugin/code.ts:1-40

插件清单与构建产物

插件以 TypeScript 编写并由 Figma 插件编译器打包，下述三个文件共同定义了插件的静态形态：

• figma-plugin/manifest.json 描述插件元数据（名称、ID、网络权限、ui 入口指向 ui.html、main 入口指向编译后的 code.js）。它必须声明与本地 WebSocket 服务通信所需的网络访问权限，否则 code.ts 中的 fetch 将被沙箱拒绝。

• figma-plugin/tsconfig.json 配置 TypeScript 编译选项，使 code.ts 输出符合 Figma 插件沙箱要求的 JavaScript（例如禁止某些 ES 特性、强制 ES2020 目标等）。

• code.js 是 code.ts 编译后的产物，被 manifest.json 引用为 main 入口，在插件沙箱内运行；它无法直接发起任意网络请求，必须通过 fetch 调用本地 WebSocket（由 src/figma-bridge/ws-server.ts 提供）转发到 MCP 流程。

资料来源：figma-plugin/tsconfig.json:1-30

资料来源：figma-plugin/manifest.json:10-25

插件核心逻辑（code.ts）

code.ts 是 Plugin Mode 的"桥梁中枢"，承担三个职责：

1. 监听选区变化：通过 figma.on('selectionchange') 监听用户在 Figma 中切换选区的事件，并在回调里读取最新的 selection 数组。

1. 解析设计属性：对每个被选中的节点，调用 figma.getStyleByIdAsync / figma.getNodeByIdAsync 等异步 API 解析其颜色（最终以 hex 形式暴露）、字号、字体族、fontStyle（字重，自 v1.1.0 起作为独立字段包含）以及间距值。

1. 桥接到 MCP：把序列化后的设计上下文载荷通过 fetch POST 到本地 ws-server.ts（默认 http://localhost:<port>/...），由该服务把数据交给 MCP 工具调用方。

资料来源：figma-plugin/code.ts:1-120

资料来源：src/figma-bridge/ws-server.ts:1-120

ws-server.ts 提供了插件可访问的本地入口。它接收插件发送的选区数据后，自 v1.0.1 起引入的 30 秒内存缓存会避免在同一个工具链中对相同节点重复调用 Figma API；同时，对 Figma REST API 返回的 429 Too Many Requests 实现了最多 3 次、指数退避并尊重 Retry-After 头的重试策略，保证批量提取时的稳定性。

资料来源：src/figma-bridge/ws-server.ts:60-150

选区检查器 UI（ui.html）

ui.html 是用户实际看到的"检查器"面板，承担把 code.ts 提取出的原始结构渲染成可读、可复制界面的职责。其关键特性均围绕 v1.1.0 的"copy-to-clipboard inspector"展开：

• 复制到剪贴板：颜色（hex）、字体族、字号、字重、完整 CSS 或间距值都被渲染为可点击元素，点击后调用 navigator.clipboard.writeText 把该字段复制到剪贴板。该机制让设计师/Agent 拿到的设计 token 可以"即点即用"。

• 原生亮/暗主题：通过读取 Figma 暴露的 themeColors 而非硬编码颜色，让 UI 与 Figma 主程序保持一致。开发者无需在 CSS 中维护两套调色板，亮/暗模式由 Figma 自身的设置驱动。

• 完整的字体信息：v1.1.0 起，字体区块新增 fontStyle（字重）字段，并以单独行展示，与字号、字体族并列，从而在 UI 上与 REST 模式提取出的 fontStyle 保持字段一致。

资料来源：figma-plugin/ui.html:1-200

资料来源：figma-plugin/ui.html:200-360

安装路径与已知边界

由于该插件尚未上架 Figma Community，v1.1.0 发布说明明确把手动安装列为"主推路径"：开发者需把 figma-plugin/ 目录（manifest + 编译后的 code.js + ui.html）作为本地开发插件导入 Figma Desktop 的 Plugins → Development → Import plugin from manifest。manifest.json 中所有字段（如 editorType、documentAccess、networkAccess）需要与本机 WebSocket 端口保持一致，否则插件 UI 将无法与 ws-server.ts 通信。

资料来源：figma-plugin/manifest.json:1-40

Plugin Mode 的边界条件值得注意：必须保持 Figma 桌面客户端运行、本地桥接服务监听端口可达，并且只有在用户主动选中节点时才能提供上下文；批量分析历史文件或无 GUI 场景仍需切换到 REST Mode——这是 v1.0.0 强调"REST parity（文档与导航工具通过 url 即可工作，无需插件）"的根本原因。

概述与设计目标

design-context-bridge 是一个独立的 MCP（Model Context Protocol）服务器，向 AI 代理暴露真实的 Figma 设计上下文。其核心由两大部分组成：MCP 工具集（位于 src/mcp-server/tools/ 目录下，按工具职责拆分为独立模块）和支撑工具的双模式数据通道——Figma 插件通道（用户当前选择）与 REST API 通道（任意文件通过 URL + token）。

按照 v1.0.0 发布说明的描述，设计目标强调 "两种模式" 与 "REST parity"：即便不安装 Figma 插件，文档与导航类工具也应能通过文件 URL 工作，从而让远程代理、低权限环境或无头 CI 流程同样可消费同一套工具。资料来源：src/mcp-server/tool-registry.ts:1-40

工具分类：双模式可用性

工具集合按是否依赖"当前选择"划分为两类。注册中心 tool-registry.ts 在初始版本中按职责统一声明各工具的元数据、输入 schema 与执行入口。

资料来源：src/mcp-server/tools/get-all-pages.ts:1-30, src/mcp-server/tools/get-current-page.ts:1-30, src/mcp-server/tools/get-current-selection.ts:1-30, src/mcp-server/tools/get-selected-colors.ts:1-30, src/mcp-server/tools/get-selected-texts.ts:1-30

文档与导航工具（REST 全覆盖）

get_all_pages 与 get_current_page 是发布说明中明确具备 "REST parity" 的工具。它们不依赖用户的实时选择，因此 REST 模式下只需 url 即可在不安装插件的情况下遍历一个外部 Figma 文件的页面结构。这使得同一份代理工作流既能作用于本地打开的设计文件，也能作用于任意远端文件。资料来源：src/mcp-server/tools/get-all-pages.ts:1-60, src/mcp-server/tools/get-current-page.ts:1-60

选择类工具（仅插件模式）

get_current_selection、get_selected_colors 与 get_selected_texts 都以"用户在 Figma 中实时选中的节点"为输入。由于 REST API 无法获知客户端当前焦点，这三个工具被约束为 仅插件模式。其中：

• get_selected_colors 在 v1.1.0 中通过插件 UI 提供 "复制 hex" 交互，使代理读取的色板值可直接落到剪贴板。资料来源：src/mcp-server/tools/get-selected-colors.ts:1-60
• get_selected_texts 在 v1.1.0 中扩展 字重（fontStyle），对齐 Figma 排版真实值，配合复制 CSS 片段的检查器。资料来源：src/mcp-server/tools/get-selected-texts.ts:1-60
• get_current_selection 是选择类工具的"入口"，将 id 列表透出后供色板/文本等下钻工具消费。资料来源：src/mcp-server/tools/get-current-selection.ts:1-60

REST 客户端韧性：缓存与限流重试

REST 通道的稳定性由 v1.0.1 中的两项改进保证：

1. 30 秒内存缓存：避免同一工具链（tool chain）在短窗口内对同一 Figma 端点重复请求。
2. 429 重试：最多 3 次指数退避，并尊重响应头中的 Retry-After。

这两项变更解决了当代理连续调用多个工具时容易触发的 Figma REST 限流问题，使得分析类（例如 extract_de…）工具链能稳定运行。

flowchart LR
  Agent[AI Agent] -->|MCP| Registry[tool-registry.ts]
  Registry --> Nav[Navigation tools<br/>get_all_pages / get_current_page]
  Registry --> Sel[Selection tools<br/>get_current_selection / colors / texts]
  Nav -->|url + token| Rest[Figma REST API]
  Nav -->|live| Plugin[Figma Plugin]
  Sel -->|live only| Plugin
  Rest --> Cache[(30s in-memory cache)]
  Rest -->|429| Retry[exp. backoff<br/>×3, Retry-After]

双重模式与社区共识

发布说明在 v1.1.0 把 "manual plugin install" 列为首选安装路径——因为插件尚未上架 Figma Community，但 tool-registry.ts 仍同时声明插件通道与 REST 通道的工具入口，确保代理在不同环境下都拥有完整的导航能力。这种"导航全员 + 选择插件独占"的分工，是项目最核心的架构权衡。资料来源：src/mcp-server/tool-registry.ts:1-80

概述与作用范围

design-context-bridge 是一个独立的 MCP（Model Context Protocol）服务器，将 Figma 的设计上下文暴露给 AI 智能体。它支持两种使用模式：Figma 插件模式（实时选择）和 REST API 模式（通过文件 URL 与 Token 访问任意文件）资料来源：docs/clients.md:1-18。本页聚焦于在生产或本地开发环境中，如何将这个 MCP 服务器接入不同客户端、如何安全地保管访问凭证、哪些数据被传输、由谁处理，以及运维层面的关键特性（缓存与重试）。

MCP 客户端配置

不同 IDE / Agent 客户端通过 JSON 描述如何启动 MCP server。下表汇总了仓库内 client-config-examples/ 中四个示例的配置要点：

所有配置均显式将敏感凭证作为环境变量（env 字段）传入，避免写入明文文件；args 或 command 仅声明启动器与包名，不包含任何 Token 资料来源：client-config-examples/claude-code.json:5-11。docs/clients.md 文档中以"Manual plugin install documented as the primary path"为标题明确说明插件尚未上架 Figma Community，因此手动安装 / npx 拉取是当前主流程。

安全：Token 与传输边界

FIGMA_TOKEN 是整个系统的唯一特权凭据。SECURITY.md 将其定位为"敏感载荷"：

• 严禁将 Token 提交到仓库或粘贴到客户端配置文件正文中；只能通过 env 或本地 shell 环境注入资料来源：SECURITY.md:1-12。
• 建议最小权限原则：为该 Token 仅授予"File content"读取权限，并定期轮换。
• 服务器以 stdio 与宿主客户端通信，不开放对外 HTTP 端口，避免被第三方扫描命中资料来源：docs/clients.md:20-28。
• 任何重试与缓存仅作用于进程内存，不落盘，因此 Token 与返回的设计数据都不会被持久化。

隐私：哪些数据离开你的环境

隐私边界由两种模式决定：

• 插件模式：MCP server 读取当前 Figma 选区（selection），由 Figma 桌面端转发至本地 MCP 进程；数据停留在本机。
• REST 模式：当智能体调用带 url 参数的工具时，服务器会向 api.figma.com 发起 HTTPS 请求以拉取所需节点或文档数据；该请求携带你的 FIGMA_TOKEN，但响应内容只在 MCP 会话内回传给客户端，不被写盘 资料来源：docs/clients.md:30-42。

两种模式都不会把数据转发到第三方，服务器自身也不保存任何审计日志，因此从隐私角度它是一台"纯转发器"。

运维特性

1. 内存缓存（v1.0.1+）

为避免在一次智能体工具链中重复调用 Figma API，服务器实现了 30 秒内存级缓存：

• 同一 (tool, params) 组合在 30 秒内复用上次结果。
• 缓存仅驻留在进程内存，重启即失效，无任何磁盘写入 资料来源：docs/clients.md:46-52。

2. 429 退避重试（v1.0.1+）

Figma API 在被限流时会返回 429 Too Many Requests。服务器遵循以下策略：

• 最多重试 3 次。
• 采用指数退避，并优先尊重响应头中的 Retry-After 字段。
• 若 Retry-After 缺失，则使用默认退避节奏 资料来源：docs/clients.md:54-64。

这一组合显著降低了智能体在批量分析页面结构时被限流打断的概率。

3. 进程生命周期

MCP server 通常以 stdio 形式被 IDE/Agent 父进程托管：

• 启动：客户端按 command + args 拉起 Node 进程（如 node ./build/index.js）。
• 空闲：常驻等待 tools/call 帧；无心跳机制依赖 Figma API 是否空闲。
• 退出：父进程退出时随同终止，无需清理脚本。

这一节简要勾勒运维中的稳态行为；若需长时间批量扫描，建议复用同一会话，以充分利用 30 秒缓存窗口。

Pitfall Log / 踩坑日志

项目：CristinaFores/design-context-bridge

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v1.1.0 — copy-to-clipboard inspector。

1. 安装坑 · 失败模式：installation: v1.1.0 — copy-to-clipboard inspector

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.1.0 — copy-to-clipboard inspector
• 对用户的影响：Upgrade or migration may change expected behavior: v1.1.0 — copy-to-clipboard inspector
• 证据：failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.1.0 | v1.1.0 — copy-to-clipboard inspector

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/CristinaFores/design-context-bridge | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/CristinaFores/design-context-bridge | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/CristinaFores/design-context-bridge | no_demo; severity=medium

6. 运行坑 · 失败模式：performance: v1.0.1 — fix: in-memory cache + 429 retry

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v1.0.1 — fix: in-memory cache + 429 retry
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.1 — fix: in-memory cache + 429 retry
• 证据：failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.0.1 | v1.0.1 — fix: in-memory cache + 429 retry

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/CristinaFores/design-context-bridge | release_recency=unknown

9. 维护坑 · 失败模式：maintenance: v1.0.0 — Design Context Bridge

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.0.0 — Design Context Bridge
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.0 — Design Context Bridge
• 证据：failure_mode_cluster:github_release | https://github.com/CristinaFores/design-context-bridge/releases/tag/v1.0.0 | v1.0.0 — Design Context Bridge