DECREASE-TOKEN-FIGMA

Figma 成本优化桥接器

Figma Cost Optimizer Bridge 是一个本地 MCP 服务，可将 Figma Desktop 的设计上下文转换为紧凑、可直接用于实现的网页交接内容，供 LLM 编码 Agent 使用。

它位于 MCP 客户端与本地 Figma Desktop MCP 端点之间。它不会转发充斥着元数据、绝对坐标、重复类名字符串和内联 SVG 的原始 get_design_context 输出，而是返回更精简的 Markdown 交接内容，其中包含清理后的 JSX 中间骨架代码、设计令牌、可复用的重复结构以及截图路径。交接内容可面向 React、Vue、Svelte 或 HTML，并可使用 Tailwind、styled-components、Emotion、CSS Modules 或内联样式。

这样既能降低输入令牌成本、减少上下文噪声，也能保留编码 Agent 准确构建 UI 所需的信息。

基准测试概览

最新的可复现测试样本：DashStack Dashboard，Figma 节点 2791-32584，于 2026-06-16 使用盲测 3 次运行的基准测试测得（anthropic / claude-sonnet-4-6、温度 0，进行一次仅编译修复）。

路径	输入字符数	估算文本令牌数	图像令牌数	估算令牌总数	像素相似度（平均值）
官方 Figma MCP 原始输出	51,543	12,886	1,040	13,926	83.12%
Bridge 交接内容	28,928	7,232	0	7,232	84.76%

输入令牌估算节省：48.07%；同时，Bridge 组与参考图的平均相似度高出 1.65 个百分点——输入令牌几乎减半，视觉准确度却没有损失。完整报告见 docs/BENCHMARK_RESULTS.md。

功能

• 高令牌效率的交接内容： 移除或压缩嘈杂的 Figma 元数据、绝对定位、重复的 Tailwind 令牌、data-* 属性和内联 SVG 代码块。
• 截图路径模式： 在本地保存截图，并返回其绝对路径，默认不内联图像数据。
• 重复子树去重： 将重复的 JSX 结构转换为一个组件定义加实例数据。
• 共享类提取： 在组件模板中保留所有实例共享的类令牌，仅将差异作为属性传递。
• 默认属性值： 将常用槽位值提升为组件默认值，使重复实例可以省略这些值。
• 哈希缓存： 原始 Figma 响应未发生变化时，复用先前的交接内容。
• 差异交接： 对于之前处理过的组件，仅返回变更行；当差异过大时自动回退到完整交接内容。
• 本地组件注册表： 记录提取或扫描到的项目组件，并在后续交接中建议复用。
• 目标配置： 为 React、Vue、Svelte 和 HTML 生成特定配置的指导，并支持 Tailwind、styled-components、Emotion、CSS Modules 和内联样式。
• 必须执行的 Ollama 预分析： 使用本地 Ollama 分析颜色、文本和摘要。MCP 服务会在启动时准备 Ollama；如果无法运行分析，交接生成将失败。
• 基准测试工具： 衡量原始输出与 Bridge 的输入令牌数，在 Playwright 中渲染输出，并使用 pixelmatch 计算像素相似度。

安装

从 npm 安装：

npm install -g decrease-token-figma
figma-bridge

直接从 GitHub 安装：

npm install -g github:junseo2323/decrease-token-figma
figma-bridge

用于本地开发：

git clone https://github.com/junseo2323/decrease-token-figma.git
cd decrease-token-figma
npm install
npm run build
npm link
figma-bridge

figma-bridge 启动时会自动准备 Ollama。若要手动准备：

npm run setup

MCP 客户端配置

在 Claude Desktop、Codex、Cursor 或其他 MCP 客户端中使用此配置：

{
  "mcpServers": {
    "figma-cost-optimizer-bridge": {
      "command": "npx",
      "args": ["-y", "decrease-token-figma"],
      "env": {
        "FIGMA_BRIDGE_ROOT": "/absolute/path/to/your/app"
      }
    }
  }
}

直接运行 GitHub 版本：

{
  "mcpServers": {
    "figma-cost-optimizer-bridge": {
      "command": "npx",
      "args": ["-y", "github:junseo2323/decrease-token-figma"],
      "env": {
        "FIGMA_BRIDGE_ROOT": "/absolute/path/to/your/app"
      }
    }
  }
}

Codex CLI

在要让 Bridge 写入资源/缓存的应用项目中运行：

codex mcp add figma-cost-optimizer-bridge \
  --env FIGMA_BRIDGE_ROOT="$PWD" \
  -- npx -y decrease-token-figma

codex mcp list

之后如需移除：

codex mcp remove figma-cost-optimizer-bridge

Claude Code

在你希望桥接工具写入资源／缓存的应用项目中：

claude mcp add -s local figma-cost-optimizer-bridge \
  -e FIGMA_BRIDGE_ROOT="$PWD" \
  -- npx -y decrease-token-figma

claude mcp list

之后如需移除：

claude mcp remove figma-cost-optimizer-bridge

设置完成后，保持 Figma Desktop 运行并启用本地 MCP，选择一个节点，然后让 Codex 或 Claude Code 调用 get_optimized_figma_handoff。

避免与官方 Figma MCP 工具冲突

不要同时注册官方 figma-mcp 服务和此桥接工具。如果两种工具都可用，大模型可能会优先选择原始官方 get_design_context 工具，而不是优化后的桥接交接内容。

使用内置的 doctor 和迁移助手：

figma-bridge doctor
figma-bridge migrate-config --yes

doctor 会检查已知的 Claude Desktop、Cursor、工作区 MCP 和 Codex 配置位置。migrate-config --yes 会备份 JSON 配置、移除冲突的官方 Figma MCP 条目，并确保该配置中的 Figma MCP 服务为 figma-cost-optimizer-bridge。Codex TOML 配置会显示出来，但不会自动重写；请使用 Codex CLI 移除其中的官方 Figma MCP 条目。

桥接工具启动时，还会确保 FIGMA_BRIDGE_ROOT 中存在 AGENTS.md 和 CLAUDE.md，并将以下防护规则置于文件首行：

IMPORTANT: For Figma design-to-code work, use only the `figma-cost-optimizer-bridge` MCP server. Do not use or fall back to the official Figma MCP / `figma-mcp` directly.

如果不希望桥接工具更新这些文件，请设置 FIGMA_BRIDGE_WRITE_AGENT_RULES=0。

要求

• Figma Desktop 正在运行。
• Figma 的本地 MCP 端点可通过 127.0.0.1:3845 访问。
• 请求交接内容前，已选中一个 Figma 节点。
• FIGMA_BRIDGE_ROOT 或工具参数 projectRoot 指向本地应用项目。

MCP 工具

get_optimized_figma_handoff

获取选中的 Figma 节点，并返回优化后的 Markdown 交接内容以及截图信息。

参数	值	默认值	描述
projectRoot	绝对路径	FIGMA_BRIDGE_ROOT 或 cwd	资源和缓存的项目根目录
screenshot	path / inline / none	path	path 会将 PNG 存入缓存，并仅返回其绝对路径。inline 适用于无法访问文件系统的客户端
mode	auto / full / diff	auto	如果存在先前版本，则返回差异；否则返回完整交接内容
force_refresh	布尔值	false	忽略缓存并重新获取，即使原始哈希值相同也不例外
target	react / vue / svelte / html	react	交接说明和代码围栏所针对的 Web 框架
styling	tailwind / styled-components / emotion / css-modules / inline	tailwind	用于转换设计令牌的样式系统

兼容性别名

桥接工具还将 get_design_context 和 get_figma_context 作为优化交接内容的别名提供。这些名称有意兼容常见的 Figma MCP 工作流，但返回的是桥接工具生成的 Markdown 交接内容，而不是官方 Figma 的原始上下文。

备用工具：

• get_raw_figma_context：返回 Figma 选中节点的原始上下文。
• get_screenshot / get_figma_screenshot：透传截图辅助工具。

sync_component_registry

使用目标配置中的组件扩展名扫描 <projectRoot>/src/components，并更新本地组件注册表。React 会扫描 .tsx／.jsx，Vue 会扫描 .vue，Svelte 会扫描 .svelte，HTML 会扫描 .html。后续交接内容可使用此注册表来建议或强制复用组件。

工作流

1. 在 Figma Desktop 中选择一个节点。
2. 大模型调用 get_optimized_figma_handoff。
3. 桥接工具从本地 Figma MCP 端点获取原始设计上下文和截图。
4. 图像资源会写入 src/assets 或已配置的资源目录。
5. 清理原始 TSX、去重重复结构，并添加必需的 Ollama 分析。
6. 大模型根据交接 Markdown 和截图实现 UI。

缓存布局

.figma_cache/
  nodes/ChatScreen_a3f29c01/
    raw.txt
    handoff.md
    diff.md
    screenshot.png
    meta.json
  registry.json

• 未更改的原始响应会复用缓存的交接内容。
• 每个组件会保留最新的两个版本。
• 有可用的先前版本时，mode: auto 会生成差异交接内容。

环境变量

变量	描述
FIGMA_BRIDGE_ROOT	资源和缓存的项目根目录
FIGMA_BRIDGE_CACHE_DIR	覆盖缓存目录
FIGMA_BRIDGE_ASSET_DIR	覆盖图像资源目录
FIGMA_BRIDGE_WRITE_AGENT_RULES=0	禁用自动更新 AGENTS.md 和 CLAUDE.md 防护规则
OLLAMA_BIN	指定 Ollama 二进制文件的路径
FIGMA_BRIDGE_OLLAMA_MODEL	要使用的 Ollama 模型。默认值：llama3.2
FIGMA_BRIDGE_OLLAMA_AUTO_INSTALL=0	禁用运行时自动安装 Ollama
FIGMA_BRIDGE_OLLAMA_AUTO_PULL=0	禁用运行时模型下载

npm 脚本

npm run build              # TypeScript build
npm test                   # Unit tests
npm run setup              # Install/start Ollama and pull the default model
npm run measure            # Estimate token size for .figma_cache/handoff.md
npm run benchmark:capture  # Capture a Figma benchmark fixture
npm run benchmark:tokens   # Measure raw vs bridge input tokens
npm run benchmark:diff     # Render with Vite and compute pixel diff
npm run benchmark:blind    # Run blind multi-run LLM benchmark
npm run benchmark:summary  # Rebuild blind benchmark summary

重现基准测试

npm install
npm run build
npx playwright install chromium

# Keep Figma Desktop open, enable local MCP on port 3845,
# and select the target node before capturing.
npm run benchmark:capture -- dashstack-dashboard 2791-32584 WlvYAu5ONnUe7kVcDtmuqk
npm run benchmark:tokens -- dashstack-dashboard
npm run benchmark:diff -- dashstack-dashboard

生成的文件将写入：

benchmarks/fixtures/<slug>/
benchmarks/results/<slug>/

如需进行更严格的比较，请使用相同的模型、温度、截图输入、输出约定和编译修复策略运行盲测基准测试，仅更改文本输入：

export ANTHROPIC_API_KEY=...

npm run benchmark:blind -- dashstack-dashboard \
  --provider anthropic \
  --model claude-sonnet-4-5-20250929 \
  --runs 5 \
  --temperature 0 \
  --max-repairs 1 \
  --experiment-id sonnet45-t0-r5

运行时模型

本项目的主要用途并非作为托管式 Web 服务运行。该桥接工具必须访问用户在本地 Figma Desktop 中的选区、本地文件系统和本地 Ollama 服务。实际运行时请使用 npm 或通过 GitHub 安装，并使用 GitHub Pages 发布文档和基准测试报告。

文档：

• 英文版 Pages：https://junseo2323.github.io/decrease-token-figma/
• 韩文版 Pages：https://junseo2323.github.io/decrease-token-figma/index.ko.html
• 基准测试报告：https://junseo2323.github.io/decrease-token-figma/BENCHMARK_RESULTS.html

大模型实现指南

• 使用截图确定视觉布局、间距节奏和对齐方式。
• 使用交付代码获取准确的文本、颜色、字体粗细和设计令牌。
• 实现时，将通过机械方式提取的资源变量重命名为语义化名称。
• 尽可能将内联 SVG 占位符替换为 lucide-react 等图标组件。

许可证

MIT