{"id":"48138013-370e-4f30-aaa9-cdcbc130ca77","slug":"decrease-token-figma","kind":"mcp","name":"decrease-token-figma","summary":"decrease token in figma mcp by using DTF!","owner":"junseo2323","repoUrl":"https://github.com/junseo2323/decrease-token-figma","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-03-13T21:07:59.000Z","addedAt":"2026-10-21T17:02:13.861Z","logoUrl":"https://avatars.githubusercontent.com/u/26485905?u=77c3e1df4e4ec650ac752e49956311a0bb280deb&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T04:05:16.279Z","sample":false,"url":"https://conduits.dev/tools/decrease-token-figma","language":"TypeScript","transports":["stdio"],"install":{"npm":"decrease-token-figma"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Figma Cost Optimizer Bridge\n\n<div align=\"right\">\n  <strong>English</strong> | <a href=\"./README_KR.md\">Korean</a>\n</div>\n\n![Figma Cost Optimizer Bridge system overview](./docs/assets/system-overview.svg)\n\nFigma Cost Optimizer Bridge is a local MCP server that turns Figma Desktop design context into compact, implementation-ready web handoffs for LLM coding agents.\n\nIt sits between an MCP client and the local Figma Desktop MCP endpoint. Instead of forwarding raw `get_design_context` output full of metadata, absolute coordinates, repeated class strings, and inline SVG, the bridge returns a smaller Markdown handoff with cleaned JSX intermediate skeleton code, design tokens, reusable repeated structures, and a screenshot path. The handoff can target React, Vue, Svelte, or HTML, with Tailwind, styled-components, Emotion, CSS Modules, or inline styles.\n\nThe result is lower input-token cost and less context noise while still preserving the information a coding agent needs to build the UI accurately.\n\n## Benchmark Snapshot\n\nLatest reproducible fixture: `DashStack Dashboard`, Figma node `2791-32584`, measured on `2026-06-16` with a blind 3-run benchmark (`anthropic / claude-sonnet-4-6`, temperature `0`, one compile-only repair).\n\n| Path | Input chars | Est. text tokens | Image tokens | Total est. tokens | Pixel similarity (mean) |\n|---|---:|---:|---:|---:|---:|\n| Official Figma MCP raw | 51,543 | 12,886 | 1,040 | 13,926 | 83.12% |\n| Bridge handoff | 28,928 | 7,232 | 0 | 7,232 | 84.76% |\n\n**Estimated input-token saving: 48.07%**, while the bridge arm was **+1.65 pp** more similar to the reference on average — nearly half the input tokens with no loss of visual accuracy. See the full report in [docs/BENCHMARK_RESULTS.md](./docs/BENCHMARK_RESULTS.md).\n\n## Features\n\n- **Token-efficient handoffs:** removes or compresses noisy Figma metadata, absolute positioning, repeated Tailwind tokens, `data-*` attributes, and inline SVG blocks.\n- **Screenshot path mode:** saves the screenshot locally and returns its absolute path instead of inlining image data by default.\n- **Repeated subtree dedupe:** converts repeated JSX structures into one component definition plus instance data.\n- **Shared class extraction:** keeps class tokens shared by all instances in the component template and only passes differences as props.\n- **Default prop values:** promotes common slot values to component defaults so repeated instances can omit them.\n- **Hash cache:** reuses previous handoffs when the raw Figma response has not changed.\n- **Diff handoff:** returns only changed lines for previously seen components, with automatic fallback to full handoff when the diff is too large.\n- **Local component registry:** records extracted or scanned project components and suggests reuse in later handoffs.\n- **Target profiles:** generates profile-specific guidance for React, Vue, Svelte, and HTML, plus Tailwind, styled-components, Emotion, CSS Modules, and inline styling.\n- **Required Ollama pre-analysis:** uses local Ollama for color, text, and summary analysis. The MCP server prepares Ollama on startup, and handoff generation fails if analysis cannot run.\n- **Benchmark harness:** measures raw vs bridge input tokens, renders outputs in Playwright, and computes pixel similarity with `pixelmatch`.\n\n## Install\n\nInstall from npm:\n\n```bash\nnpm install -g decrease-token-figma\nfigma-bridge\n```\n\nInstall directly from GitHub:\n\n```bash\nnpm install -g github:junseo2323/decrease-token-figma\nfigma-bridge\n```\n\nFor local development:\n\n```bash\ngit clone https://github.com/junseo2323/decrease-token-figma.git\ncd decrease-token-figma\nnpm install\nnpm run build\nnpm link\nfigma-bridge\n```\n\nOllama is prepared automatically when `figma-bridge` starts. To prepare it manually:\n\n```bash\nnpm run setup\n```\n\n## MCP Client Configuration\n\nUse this configuration in Claude Desktop, Codex, Cursor, or another MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"figma-cost-optimizer-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"decrease-token-figma\"],\n      \"env\": {\n        \"FIGMA_BRIDGE_ROOT\": \"/absolute/path/to/your/app\"\n      }\n    }\n  }\n}\n```\n\nTo run the GitHub version directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"figma-cost-optimizer-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github:junseo2323/decrease-token-figma\"],\n      \"env\": {\n        \"FIGMA_BRIDGE_ROOT\": \"/absolute/path/to/your/app\"\n      }\n    }\n  }\n}\n```\n\n### Codex CLI\n\nFrom the app project you want the bridge to write assets/cache into:\n\n```bash\ncodex mcp add figma-cost-optimizer-bridge \\\n  --env FIGMA_BRIDGE_ROOT=\"$PWD\" \\\n  -- npx -y decrease-token-figma\n\ncodex mcp list\n```\n\nTo remove it later:\n\n```bash\ncodex mcp remove figma-cost-optimizer-bridge\n```\n\n### Claude Code\n\nFrom the app project you want the bridge to write assets/cache into:\n\n```bash\nclaude mcp add -s local figma-cost-optimizer-bridge \\\n  -e FIGMA_BRIDGE_ROOT=\"$PWD\" \\\n  -- npx -y decrease-token-figma\n\nclaude mcp list\n```\n\nTo remove it later:\n\n```bash\nclaude mcp remove figma-cost-optimizer-bridge\n```\n\nAfter setup, keep Figma Desktop running with local MCP enabled, select a node, then ask Codex or Claude Code to call `get_optimized_figma_handoff`.\n\n### Avoiding Official Figma MCP Tool Conflicts\n\nDo not register the official `figma-mcp` server alongside this bridge. If both tools are available, an LLM may choose the raw official `get_design_context` tool before the optimized bridge handoff.\n\nUse the built-in doctor and migration helper:\n\n```bash\nfigma-bridge doctor\nfigma-bridge migrate-config --yes\n```\n\n`doctor` inspects known Claude Desktop, Cursor, workspace MCP, and Codex config locations. `migrate-config --yes` backs up JSON configs, removes competing official Figma MCP entries, and ensures `figma-cost-optimizer-bridge` is the Figma MCP server in that config. Codex TOML configs are reported but not rewritten automatically; remove official Figma MCP entries there with the Codex CLI.\n\nWhen the bridge starts, it also ensures `AGENTS.md` and `CLAUDE.md` exist in `FIGMA_BRIDGE_ROOT` and prepends this guardrail as the first line:\n\n```text\nIMPORTANT: 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.\n```\n\nSet `FIGMA_BRIDGE_WRITE_AGENT_RULES=0` if you do not want the bridge to update those files.\n\n## Requirements\n\n- Figma Desktop is running.\n- Figma's local MCP endpoint is available on `127.0.0.1:3845`.\n- A Figma node is selected before requesting a handoff.\n- `FIGMA_BRIDGE_ROOT` or the tool argument `projectRoot` points to the local app project.\n\n## MCP Tools\n\n### `get_optimized_figma_handoff`\n\nFetches the selected Figma node and returns an optimized Markdown handoff plus screenshot information.\n\n| Argument | Values | Default | Description |\n|---|---|---|---|\n| `projectRoot` | absolute path | `FIGMA_BRIDGE_ROOT` or cwd | Project root for assets and cache |\n| `screenshot` | `path` / `inline` / `none` | `path` | `path` stores the PNG in cache and returns only its absolute path. `inline` is for clients without filesystem access |\n| `mode` | `auto` / `full` / `diff` | `auto` | Return a diff when a previous version exists, otherwise a full handoff |\n| `force_refresh` | boolean | `false` | Ignore the cache and capture again even if the raw hash matches |\n| `target` | `react` / `vue` / `svelte` / `html` | `react` | Target web framework for handoff instructions and code fence |\n| `styling` | `tailwind` / `styled-components` / `emotion` / `css-modules` / `inline` | `tailwind` | Styling system for token conversion guidance |\n\n### Compatibility aliases\n\nThe bridge also exposes `get_design_context` and `get_figma_context` as optimized handoff aliases. These names are intentionally compatible with common Figma MCP workflows, but they return bridge handoff Markdown rather than raw official Figma context.\n\nEscape hatches:\n\n- `get_raw_figma_context`: returns raw Figma selected-node context.\n- `get_screenshot` / `get_figma_screenshot`: pass-through screenshot helpers.\n\n### `sync_component_registry`\n\nScans `<projectRoot>/src/components` using the target profile's component extensions and updates the local component registry. React scans `.tsx`/`.jsx`, Vue scans `.vue`, Svelte scans `.svelte`, and HTML scans `.html`. Later handoffs can use this registry to recommend or enforce component reuse.\n\n## Workflow\n\n1. Select a node in Figma Desktop.\n2. The LLM calls `get_optimized_figma_handoff`.\n3. The bridge fetches raw design context and a screenshot from the local Figma MCP endpoint.\n4. Image assets are written to `src/assets` or the configured asset directory.\n5. Raw TSX is cleaned, repeated structures are deduped, and required Ollama analysis is added.\n6. The LLM implements the UI from the handoff Markdown and screenshot.\n\n## Cache Layout\n\n```text\n.figma_cache/\n  nodes/ChatScreen_a3f29c01/\n    raw.txt\n    handoff.md\n    diff.md\n    screenshot.png\n    meta.json\n  registry.json\n```\n\n- Unchanged raw responses reuse cached handoffs.\n- The two latest versions per component are retained.\n- `mode: auto` creates a diff handoff when a previous version is available.\n\n## Environment Variables\n\n| Variable | Description |\n|---|---|\n| `FIGMA_BRIDGE_ROOT` | Project root for assets and cache |\n| `FIGMA_BRIDGE_CACHE_DIR` | Override cache directory |\n| `FIGMA_BRIDGE_ASSET_DIR` | Override image asset directory |\n| `FIGMA_BRIDGE_WRITE_AGENT_RULES=0` | Disable automatic `AGENTS.md` and `CLAUDE.md` guardrail updates |\n| `OLLAMA_BIN` | Path to a specific Ollama binary |\n| `FIGMA_BRIDGE_OLLAMA_MODEL` | Ollama model to use. Default: `llama3.2` |\n| `FIGMA_BRIDGE_OLLAMA_AUTO_INSTALL=0` | Disable runtime Ollama auto-install |\n| `FIGMA_BRIDGE_OLLAMA_AUTO_PULL=0` | Disable runtime model download |\n\n## npm Scripts\n\n```bash\nnpm run build              # TypeScript build\nnpm test                   # Unit tests\nnpm run setup              # Install/start Ollama and pull the default model\nnpm run measure            # Estimate token size for .figma_cache/handoff.md\nnpm run benchmark:capture  # Capture a Figma benchmark fixture\nnpm run benchmark:tokens   # Measure raw vs bridge input tokens\nnpm run benchmark:diff     # Render with Vite and compute pixel diff\nnpm run benchmark:blind    # Run blind multi-run LLM benchmark\nnpm run benchmark:summary  # Rebuild blind benchmark summary\n```\n\n## Reproduce The Benchmark\n\n```bash\nnpm install\nnpm run build\nnpx playwright install chromium\n\n# Keep Figma Desktop open, enable local MCP on port 3845,\n# and select the target node before capturing.\nnpm run benchmark:capture -- dashstack-dashboard 2791-32584 WlvYAu5ONnUe7kVcDtmuqk\nnpm run benchmark:tokens -- dashstack-dashboard\nnpm run benchmark:diff -- dashstack-dashboard\n```\n\nArtifacts are written to:\n\n```text\nbenchmarks/fixtures/<slug>/\nbenchmarks/results/<slug>/\n```\n\nFor a stricter comparison, run the blind benchmark with the same model, temperature, screenshot input, output contract, and compile-repair policy while changing only the text input:\n\n```bash\nexport ANTHROPIC_API_KEY=...\n\nnpm run benchmark:blind -- dashstack-dashboard \\\n  --provider anthropic \\\n  --model claude-sonnet-4-5-20250929 \\\n  --runs 5 \\\n  --temperature 0 \\\n  --max-repairs 1 \\\n  --experiment-id sonnet45-t0-r5\n```\n\n## Runtime Model\n\nThis project is not meant to run primarily as a hosted web service. The bridge must access the user's local Figma Desktop selection, local filesystem, and local Ollama server. Use npm or GitHub installation for the actual runtime, and use GitHub Pages for documentation and benchmark reports.\n\nDocumentation:\n\n- English Pages: https://junseo2323.github.io/decrease-token-figma/\n- Korean Pages: https://junseo2323.github.io/decrease-token-figma/index.ko.html\n- Benchmark report: https://junseo2323.github.io/decrease-token-figma/BENCHMARK_RESULTS.html\n\n## LLM Implementation Guidelines\n\n- Use the screenshot to decide visual layout, spacing rhythm, and alignment.\n- Use the handoff code for exact text, colors, font weights, and design tokens.\n- Rename mechanically extracted asset variables to semantic names when implementing.\n- Replace inline SVG placeholders with icon components such as `lucide-react` when possible.\n\n## License\n\nMIT\n"}