DECREASE-TOKEN-FIGMA

Figma Cost Optimizer Bridge

Figma Cost Optimizer Bridge は、Figma Desktop のデザインコンテキストを、LLM コーディングエージェント向けのコンパクトで実装にすぐ使える Web 引き継ぎ資料に変換するローカル MCP サーバーです。

MCP クライアントとローカルの Figma Desktop MCP エンドポイントの間で動作します。メタデータ、絶対座標、繰り返されるクラス文字列、インライン SVG が大量に含まれる生の get_design_context 出力をそのまま転送するのではなく、整形済み JSX 中間スケルトンコード、デザイントークン、再利用可能な繰り返し構造、スクリーンショットのパスを含む、より小さな Markdown 形式の引き継ぎ資料を返します。引き継ぎ資料は React、Vue、Svelte、HTML を対象とし、Tailwind、styled-components、Emotion、CSS Modules、インラインスタイルを使用できます。

その結果、コーディングエージェントが UI を正確に構築するために必要な情報を維持しながら、入力トークンのコストとコンテキストのノイズを削減できます。

ベンチマークの概要

最新の再現可能なフィクスチャ：DashStack Dashboard、Figma ノード 2791-32584。anthropic / claude-sonnet-4-6、temperature 0、コンパイルのみの修正 1 回という条件で、2026-06-16 にブラインド 3 回実行のベンチマークを測定しました。

経路	入力文字数	推定テキストトークン数	画像トークン数	推定合計トークン数	ピクセル類似度（平均）
公式 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 構造を、1 つのコンポーネント定義とインスタンスデータに変換します。
• 共通クラスの抽出： コンポーネントテンプレート内で、すべてのインスタンスに共通するクラスのトークンを保持し、差分のみを props として渡します。
• デフォルトの props 値： 共通するスロット値をコンポーネントのデフォルト値に設定し、繰り返しインスタンスで値を省略できるようにします。
• ハッシュキャッシュ： 生の 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 サーバーをこのブリッジと併せて登録しないでください。両方のツールが利用可能な場合、LLM は最適化されたブリッジのハンドオフより先に、生の公式 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	boolean	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 ワークフローとの互換性を意図したものですが、公式 Figma の生のコンテキストではなく、ブリッジのハンドオフ Markdown を返します。

代替手段：

• 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. LLM が get_optimized_figma_handoff を呼び出します。
3. ブリッジがローカル Figma MCP エンドポイントから生のデザインコンテキストとスクリーンショットを取得します。
4. 画像アセットが src/assets または設定済みのアセットディレクトリに書き込まれます。
5. 生の TSX を整理し、繰り返し構造を重複排除して、必須の Ollama 分析を追加します。
6. LLM がハンドオフ Markdown とスクリーンショットをもとに UI を実装します。

キャッシュのレイアウト

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

• 変更されていない生のレスポンスでは、キャッシュ済みのハンドオフを再利用します。
• コンポーネントごとに最新の 2 バージョンを保持します。
• 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

LLM 実装ガイドライン

• スクリーンショットを使って、視覚的なレイアウト、間隔のリズム、配置を判断してください。
• 正確なテキスト、色、フォントの太さ、デザイントークンには、引き継ぎ用コードを使用してください。
• 実装時に、機械的に抽出されたアセット変数を意味のある名前に変更してください。
• 可能であれば、インライン SVG のプレースホルダーを lucide-react などのアイコンコンポーネントに置き換えてください。

ライセンス

MIT