@vietthai/figma-remote-mcp-go 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 vkhanhqui
+Copyright (c) 2026 vietthai104
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,334 @@
-# Temporary Holding Version
+# figma-remote-mcp-go
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Figma MCP with Remote Agent Support
+<p>
+  <a href="https://www.npmjs.com/package/@vietthai/figma-remote-mcp-go"><img src="https://img.shields.io/npm/v/@vietthai/figma-remote-mcp-go?color=blue" alt="npm version" /></a>
+  <a href="https://registry.modelcontextprotocol.io/?q=figma-remote-mcp-go"><img src="https://img.shields.io/badge/MCP-Registry-purple" alt="MCP Registry" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  <a href="https://github.com/vietthai104/figma-remote-mcp-go-main/stargazers"><img src="https://img.shields.io/github/stars/vietthai104/figma-remote-mcp-go-main?style=social" alt="GitHub stars" /></a>
+</p>
+
+Open-source Figma MCP server with full read/write access via plugin — **remote agent support with auth tokens**, no REST API, no rate limits. Turn text into designs and designs into real code. Works with Cursor, Claude, GitHub Copilot, and any MCP-compatible AI tool.
+
+**Highlights**
+- No Figma API token required
+- No rate limits — free plan friendly
+- **Read and Write** live Figma data via plugin bridge — 73 tools total
+- Full design automation — styles, variables, components, prototypes, and content
+- Design strategies included — read_design_strategy, design_strategy, and more prompts built in
+
+**Styles, Variables, Components, Prototypes, and Content**
+
+https://github.com/user-attachments/assets/eae41471-fc72-4574-8261-4f42c38b8c99
+
+**Text to Design, Design to Code**
+
+https://github.com/user-attachments/assets/17bda971-0e83-4f18-8758-8ac2b8dcba62
+
+---
+
+## Why this exists
+
+Most Figma MCP servers rely on the **Figma REST API**.
+
+That sounds fine… until you hit this:
+
+| Plan | Limit |
+|------|-------|
+| Starter / View / Collab | **6 tool calls/month** |
+| Pro / Org (Dev seat) | 200 tool calls/day |
+| Enterprise | 600 tool calls/day |
+
+If you're experimenting with AI tools, you'll burn through that in minutes.
+
+I didn't have enough money to pay for higher limits.
+So I built something that **doesn't use the API at all**.
+
+---
+
+## Installation & Setup
+
+Install via `npx` — no build step required. Watch the setup video or follow the steps below.
+
+[![Watch the video](https://img.youtube.com/vi/DjqyU0GKv9k/sddefault.jpg)](https://youtu.be/DjqyU0GKv9k)
+
+### 1. Configure your AI tool
+
+Choose one of the two modes below based on how you want to run the server:
+
+#### Mode A: Standalone Mode (IDE runs the Leader)
+If you don't run a separate Leader server in a terminal, configure it without `FIGMA_MCP_LEADER_URL`. The IDE will spawn the process, which will run as a **Leader** and bind to port `1994` (default). You then connect the Figma Desktop plugin directly to `127.0.0.1:1994`.
+
+**Cursor / VS Code (`.vscode/mcp.json`):**
+```json
+{
+  "servers": {
+    "figma-remote-mcp-go": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@vietthai/figma-remote-mcp-go"
+      ]
+    }
+  }
+}
+```
+
+**Claude Desktop / Other MCP clients (`.mcp.json`):**
+```json
+{
+  "mcpServers": {
+    "figma-remote-mcp-go": {
+      "command": "npx",
+      "args": ["-y", "@vietthai/figma-remote-mcp-go"]
+    }
+  }
+}
+```
+
+#### Mode B: Follower Mode (Separate Leader Process — Recommended)
+If you run a separate Leader process in a terminal (e.g., `npx @vietthai/figma-remote-mcp-go` to keep the Figma plugin connected when the IDE restarts), you **must** configure the IDE's MCP client as a **Follower** by setting the `FIGMA_MCP_LEADER_URL` environment variable. This prevents port conflicts on port `1994`.
+
+**Cursor / VS Code (`.vscode/mcp.json`):**
+```json
+{
+  "servers": {
+    "figma-remote-mcp-go": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@vietthai/figma-remote-mcp-go"
+      ],
+      "env": {
+        "FIGMA_MCP_LEADER_URL": "http://127.0.0.1:1994"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop / Other MCP clients (`.mcp.json`):**
+```json
+{
+  "mcpServers": {
+    "figma-remote-mcp-go": {
+      "command": "npx",
+      "args": ["-y", "@vietthai/figma-remote-mcp-go"],
+      "env": {
+        "FIGMA_MCP_LEADER_URL": "http://127.0.0.1:1994"
+      }
+    }
+  }
+}
+```
+
+**Claude Code CLI:**
+```bash
+claude mcp add -s project figma-remote-mcp-go -- npx -y @vietthai/figma-remote-mcp-go@latest
+# Note: Edit ~/.claude/mcp_servers.json to add FIGMA_MCP_LEADER_URL if using Follower mode
+```
+
+**Codex CLI:**
+```bash
+codex mcp add figma-remote-mcp-go -- npx -y @vietthai/figma-remote-mcp-go@latest
+```
+
+### 2. Install the Figma plugin
+
+1. In Figma Desktop: **Plugins → Development → Import plugin from manifest**
+2. Select `manifest.json` from the [plugin.zip](https://github.com/vietthai104/figma-remote-mcp-go-main/releases)
+3. Run the plugin inside any Figma file
+
+---
+
+## Available Tools
+
+### Write — Create
+
+| Tool | Description |
+|------|-------------|
+| `create_frame` | Create a frame with optional auto-layout, fill, and parent |
+| `create_rectangle` | Create a rectangle with optional fill and corner radius |
+| `create_ellipse` | Create an ellipse or circle |
+| `create_text` | Create a text node (font loaded automatically) |
+| `import_image` | Decode base64 image and place it as a rectangle fill |
+| `create_component` | Convert an existing FRAME node into a reusable component |
+| `create_section` | Create a Figma Section node to organise frames on a page |
+
+### Write — Modify
+
+| Tool | Description |
+|------|-------------|
+| `set_text` | Update text content of an existing TEXT node |
+| `set_fills` | Set solid fill color (hex) on a node |
+| `set_strokes` | Set solid stroke color and weight on a node |
+| `set_opacity` | Set opacity of one or more nodes (0 = transparent, 1 = opaque) |
+| `set_corner_radius` | Set corner radius — uniform or per-corner |
+| `set_auto_layout` | Set or update auto-layout (flex) properties on a frame |
+| `set_visible` | Show or hide one or more nodes |
+| `lock_nodes` | Lock one or more nodes to prevent accidental edits |
+| `unlock_nodes` | Unlock one or more nodes |
+| `rotate_nodes` | Set absolute rotation in degrees on one or more nodes |
+| `reorder_nodes` | Change z-order: `bringToFront`, `sendToBack`, `bringForward`, `sendBackward` |
+| `set_blend_mode` | Set blend mode (MULTIPLY, SCREEN, OVERLAY, …) on one or more nodes |
+| `set_constraints` | Set responsive constraints `{ horizontal, vertical }` on one or more nodes |
+| `move_nodes` | Move nodes to an absolute x/y position |
+| `resize_nodes` | Resize nodes by width and/or height |
+| `rename_node` | Rename a node |
+| `clone_node` | Clone a node, optionally repositioning or reparenting |
+| `reparent_nodes` | Move nodes to a different parent frame, group, or section |
+| `batch_rename_nodes` | Bulk rename nodes via find/replace, regex, or prefix/suffix |
+| `find_replace_text` | Find and replace text across all TEXT nodes in a subtree or page; supports regex |
+
+### Write — Delete
+
+| Tool | Description |
+|------|-------------|
+| `delete_nodes` | Delete one or more nodes permanently |
+
+### Write — Prototype
+
+| Tool | Description |
+|------|-------------|
+| `set_reactions` | Set prototype reactions (triggers + actions) on a node; mode `replace` or `append` |
+| `remove_reactions` | Remove all or specific reactions by zero-based index from a node |
+
+### Write — Styles
+
+| Tool | Description |
+|------|-------------|
+| `set_effects` | Apply drop shadow / blur effects directly on a node (no style required) |
+| `create_paint_style` | Create a named paint style with a solid color |
+| `create_text_style` | Create a named text style with font, size, and spacing |
+| `create_effect_style` | Create a named effect style (drop shadow, inner shadow, blur) |
+| `create_grid_style` | Create a named layout grid style (columns, rows, or grid) |
+| `update_paint_style` | Rename or recolor an existing paint style |
+| `apply_style_to_node` | Apply an existing local style to a node, linking it to that style |
+| `delete_style` | Delete any style (paint, text, effect, or grid) by ID |
+
+### Write — Variables
+
+| Tool | Description |
+|------|-------------|
+| `create_variable_collection` | Create a new local variable collection with an optional initial mode |
+| `add_variable_mode` | Add a new mode to an existing collection (e.g. Light/Dark) |
+| `create_variable` | Create a variable (COLOR/FLOAT/STRING/BOOLEAN) in a collection |
+| `set_variable_value` | Set a variable's value for a specific mode |
+| `bind_variable_to_node` | Bind a variable to a node property — supports `fillColor`, `strokeColor`, `visible`, `opacity`, `rotation`, `width`, `height`, corner radii, spacing, and more |
+| `delete_variable` | Delete a variable or an entire collection |
+
+### Write — Pages
+
+| Tool | Description |
+|------|-------------|
+| `add_page` | Add a new page to the document (optional name and index) |
+| `delete_page` | Delete a page by ID or name (cannot delete the only page) |
+| `rename_page` | Rename a page by ID or current name |
+
+### Write — Components & Navigation
+
+| Tool | Description |
+|------|-------------|
+| `navigate_to_page` | Switch the active Figma page by ID or name |
+| `group_nodes` | Group two or more nodes into a GROUP |
+| `ungroup_nodes` | Ungroup GROUP nodes, moving children to the parent |
+| `swap_component` | Swap the main component of an INSTANCE node |
+| `detach_instance` | Detach component instances, converting them to plain frames |
+
+### Read — Document & Selection
+
+| Tool | Description |
+|------|-------------|
+| `get_document` | Full current page tree |
+| `get_metadata` | File name, pages, current page |
+| `get_pages` | All pages (IDs + names) — lightweight, no tree loading |
+| `get_selection` | Currently selected nodes |
+| `get_node` | Single node by ID (optional `depth`) |
+| `get_nodes_info` | Multiple nodes by ID (optional `depth`) |
+| `get_design_context` | Depth-limited tree with `detail` level (`minimal`/`compact`/`full`); target = `nodeId` > selection > current page |
+| `search_nodes` | Find nodes by name substring and/or type within a subtree |
+| `scan_text_nodes` | All text nodes in a subtree |
+| `scan_nodes_by_types` | Nodes matching given type list |
+| `get_viewport` | Current viewport center, zoom, and visible bounds |
+
+#### Node output format
+
+`get_document`, `get_node`, `get_nodes_info`, `get_selection` and `get_design_context` share one node format:
+
+```json
+{
+  "id": "640:44", "name": "Data", "type": "FRAME",
+  "bounds": {"x": 421, "y": 8.5, "width": 373, "height": 36},
+  "layout": {"mode": "HORIZONTAL", "padding": [6, 12, 6, 12],
+             "align": "SPACE_BETWEEN", "counterAlign": "CENTER", "sizing": ["FIXED", "HUG"]},
+  "styles": {"cornerRadius": 6, "fills": "s1", "strokes": "s2"},
+  "childCount": 2
+}
+```
+
+- `bounds.x/y` are relative to the parent.
+- Default values are omitted: no empty `styles`/`children`, `visible` only when `false`, `opacity` only when ≠ 1, no `textAlignHorizontal: LEFT`. `fontWeight` only appears when `fontStyle` is `mixed`.
+- `layout.mode` is present only on auto-layout containers (`mode`, `gap`, `padding` `[top,right,bottom,left]`, `align`, `counterAlign`, `wrap`…). Children of auto-layout frames get `layout.sizing` (`[horizontal, vertical]`, e.g. `FILL`/`HUG`) and `positioning: "ABSOLUTE"` when applicable.
+- SOLID paints are hex strings (`#rrggbb` / `#rrggbbaa`). A SOLID paint bound to a color variable becomes `{"type":"SOLID","color":"#ffffff","variable":"Color/Background/Surface"}` (variable ID if the name can't be resolved). Other paints are objects, e.g. `{"type":"IMAGE","scaleMode":"FILL"}`, `{"type":"GRADIENT_LINEAR","stops":["#2606a6","#9a0ab1","#ff003d"],"positions":[0,0.36,1],"angle":90}`. `positions` only appear when stops are not evenly spaced; `angle` uses CSS `linear-gradient` degrees (0 = to top, 90 = to right) computed from the real node size; radial/angular/diamond gradients get `center: [x, y]` (fractions of the node) when off-centre. Hidden paints are dropped.
+- Nodes with visible strokes get `strokeWeight` (a number, or `[top,right,bottom,left]` when the sides differ), `strokeAlign` (`INSIDE` / `CENTER` / `OUTSIDE`) and `dashPattern` when dashed.
+- Figma reports `fontName`/`fontSize` as mixed as soon as one character range differs. The values shared by every range are still reported (e.g. `fontFamily: "Inter"`); only what really differs is `"mixed"`, and full detail adds `styles.textSegments`, e.g. `[{"characters":"Price: ","fontStyle":"Regular"},{"characters":"$99","fontStyle":"Bold"}]` (only the differing properties). `get_fonts` counts each font of such a node.
+- Fills/strokes used more than once are replaced by keys (`"s1"`) into a top-level `globalVars.styles` map.
+- When a `depth` limit cuts the tree, the deepest nodes report `childCount` instead of `children`.
+- `get_selection` and `get_nodes_info` return `{"nodes": [...], "globalVars"?: {...}}`. `get_design_context` returns `{fileName, currentPage, target, selectionCount, context: [...], globalVars?, componentDefs?}`, where `target` is `node` / `selection` / `page`. With `dedupe_components`, instance `overrides[].fills` use the same paint format.
+
+### Read — Styles & Variables
+
+| Tool | Description |
+|------|-------------|
+| `get_styles` | Paint, text, effect, and grid styles |
+| `get_variable_defs` | Variable collections and values |
+| `get_local_components` | All components + component sets with variant properties |
+| `get_annotations` | Dev-mode annotations |
+| `get_fonts` | All fonts used on the current page, sorted by frequency |
+| `get_reactions` | Prototype/interaction reactions on a node |
+
+### Export
+
+| Tool | Description |
+|------|-------------|
+| `get_screenshot` | Base64 image export of any node |
+| `save_screenshots` | Export images to disk (server-side, no API call) |
+| `export_frames_to_pdf` | Export multiple frames as a single multi-page PDF file saved to disk |
+| `export_tokens` | Export design tokens (variables + paint styles) as JSON or CSS |
+
+### MCP Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `read_design_strategy` | Best practices for reading Figma designs |
+| `design_strategy` | Best practices for creating and modifying designs |
+| `text_replacement_strategy` | Chunked approach for replacing text across a design |
+| `annotation_conversion_strategy` | Convert manual annotations to native Figma annotations |
+| `swap_overrides_instances` | Transfer overrides between component instances |
+| `reaction_to_connector_strategy` | Map prototype reactions into interaction flow diagrams |
+
+---
+
+## Related Projects
+
+- [magic-spells/figma-mcp-bridge](https://github.com/magic-spells/figma-mcp-bridge)
+- [grab/cursor-talk-to-figma-mcp](https://github.com/grab/cursor-talk-to-figma-mcp)
+- [gethopp/figma-mcp-bridge](https://github.com/gethopp/figma-mcp-bridge)
+
+---
+
+## Contributing
+
+Issues and PRs are welcome.
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=vietthai104%2Ffigma-remote-mcp-go-main&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=vietthai104/figma-remote-mcp-go-main&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=vietthai104/figma-remote-mcp-go-main&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=vietthai104/figma-remote-mcp-go-main&type=date&legend=top-left" />
+ </picture>
+</a>

package/bin/run.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { existsSync } = require('node:fs');
+const path = require('node:path');
+
+const PLATFORM_MAP = { darwin: 'darwin', linux: 'linux', win32: 'windows' };
+const ARCH_MAP = { x64: 'amd64', arm64: 'arm64' };
+
+const goos = PLATFORM_MAP[process.platform];
+const goarch = ARCH_MAP[process.arch];
+
+if (!goos || !goarch) {
+  process.stderr.write(`[figma-mcp-go] Unsupported platform: ${process.platform}/${process.arch}\n`);
+  process.exit(1);
+}
+
+const binaryName = process.platform === 'win32' ? 'figma-mcp-go.exe' : 'figma-mcp-go';
+const binaryPath = path.join(__dirname, `${goos}-${goarch}`, binaryName);
+
+if (!existsSync(binaryPath)) {
+  process.stderr.write(
+    '[figma-mcp-go] Binary not found. Try reinstalling: npm install @vietthai/figma-remote-mcp-go\n'
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: 'inherit' });
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,37 @@
-{
-  "name": "@vietthai/figma-remote-mcp-go",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+{
+  "name": "@vietthai/figma-remote-mcp-go",
+  "version": "0.2.0",
+  "description": "Figma MCP server with remote agent support — auth tokens, .env config, no API key, no rate limits",
+  "mcpName": "io.github.vietthai104/figma-remote-mcp-go-main",
+  "bin": {
+    "figma-mcp-go": "bin/run.js"
+  },
+  "files": [
+    "bin/run.js",
+    "bin/darwin-amd64/",
+    "bin/darwin-arm64/",
+    "bin/linux-amd64/",
+    "bin/linux-arm64/",
+    "bin/windows-amd64/",
+    "bin/windows-arm64/"
+  ],
+  "keywords": [
+    "figma",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "design"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vietthai104/figma-remote-mcp-go-main.git"
+  },
+  "homepage": "https://github.com/vietthai104/figma-remote-mcp-go-main#readme",
+  "bugs": {
+    "url": "https://github.com/vietthai104/figma-remote-mcp-go-main/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }