# figma-write-bridge

Write to Figma from Claude Code (or any MCP client) **without a Figma Dev/Full seat**.

This is a fork of [cursor-talk-to-figma-mcp](https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp) by Sonny Lazuardi (MIT). The original architecture is unchanged: a local WebSocket relay, a Figma **dev plugin** that runs inside the desktop app, and an MCP server that talks to the plugin through the relay. Dev plugins run on every Figma plan, so this works where the official Figma MCP's write-to-canvas does not.

## What this fork adds

Two plugin commands in `src/cursor_mcp_plugin/code.js`:

| Command | Params | Purpose |
|---|---|---|
| `recolor_tree` | `nodeId, textFills, shapeFills, strokes, skipNames, keepWhiteShapes` | Walk a node's subtree and remap solid fills and strokes by hex colour. Text and shapes use separate maps. Returns counts plus the colours that had no mapping. Used to generate a dark-mode page from light-mode frames in one call per frame. |
| `move_to_page` | `nodeId, pageId, x, y, name` | Move a node to another page (loads the page first), then position and rename it. |

These are **not** exposed through the MCP server. They are driven directly over the relay with the scripts in `bonarda-tools/`, which also sidesteps the MCP client's per-turn call limits.

| Script | What it does |
|---|---|
| `bonarda-tools/start-relay.sh` | Starts the relay on port 3055 if it is not already running. |
| `bonarda-tools/figma-cmd.ts` | One-shot command sender: `bun figma-cmd.ts <channel> <command> '<json>'`. Works for any plugin command, including the two above. |
| `bonarda-tools/dark-sync.ts` | Clones light-mode frames to a dark-mode page and recolours them with a light-to-dark colour map. Edit the `FRAMES` table and `MAPS` for your own file. |

## Setup

1. Install [Bun](https://bun.sh), then in this folder run `bun install`.
2. Start the relay: `bonarda-tools/start-relay.sh`.
3. In the Figma **desktop** app: Plugins, Development, *Import plugin from manifest*, and pick `src/cursor_mcp_plugin/manifest.json`. Run the plugin; it shows a channel ID.
4. Register the MCP server with your client. For Claude Code:

   ```bash
   claude mcp add --scope user TalkToFigma -- bun run /absolute/path/to/figma-write-bridge/dist/server.js
   ```

5. In your session, call `join_channel` with the channel ID from step 3. Keep the plugin panel open while working.

To use the custom commands directly:

```bash
bun bonarda-tools/figma-cmd.ts <channel> recolor_tree '{"nodeId":"1:2","textFills":{"#000000":"#e9f4f9"},"shapeFills":{"#ffffff":"#14191c"},"strokes":{}}'
```

## Notes

- The upstream Google Analytics usage tracking has been removed. The plugin only talks to `localhost:3055`.
- Rerun the plugin after editing `code.js`; Figma loads dev plugin code at run time.
- `dist/` is committed so the MCP server runs without a build step. Rebuild with `bun run build` after changing `src/talk_to_figma_mcp/server.ts`.
- Batching: an MCP client may cap how many tool calls run per turn. For bulk work, prefer the relay scripts.

## License

MIT, same as upstream. See `LICENSE`.