@biolab/talk-to-figma 0.3.3 → 0.4.0

package/README.md

@@ -1,262 +1,179 @@
 # Talk to Figma MCP
 
-This project implements a Model Context Protocol (MCP) integration between AI agent (Cursor, Claude Code) and Figma, allowing AI agent to communicate with Figma for reading designs and modifying them programmatically.
+MCP server that lets AI agents (Cursor, Claude Code) read and modify Figma designs programmatically.
 
-https://github.com/user-attachments/assets/129a14d2-ed73-470f-9a4c-2240b2a4885c
-
-## Project Structure
-
-- `src/talk_to_figma_mcp/` - TypeScript MCP server for Figma integration
-- `src/cursor_mcp_plugin/` - Figma plugin for communicating with Cursor
-- `src/socket.ts` - WebSocket server that facilitates communication between the MCP server and Figma plugin
-
-## How to use
-
-1. Install Bun if you haven't already:
-
-```bash
-curl -fsSL https://bun.sh/install | bash
 ```
-
-2. Run setup, this will also install MCP in your Cursor's active project
-
-```bash
-bun setup
+AI Agent ←(stdio)→ MCP Server ←(WebSocket)→ WebSocket Relay ←(WebSocket)→ Figma Plugin
 ```
 
-3. Start the Websocket server
-
-```bash
-bun socket
-```
-
-4. **NEW** Install Figma plugin from [Figma community page](https://www.figma.com/community/plugin/1485687494525374295/cursor-talk-to-figma-mcp-plugin) or [install locally](#figma-plugin)
-
-## Quick Video Tutorial
+## Setup
 
-[Video Link](https://www.linkedin.com/posts/sonnylazuardi_just-wanted-to-share-my-latest-experiment-activity-7307821553654657024-yrh8)
+### Prerequisites
 
-## Design Automation Example
+- [Bun](https://bun.sh) runtime
+- Figma desktop app
 
-**Bulk text content replacement**
+### 1. Add MCP server
 
-Thanks to [@dusskapark](https://github.com/dusskapark) for contributing the bulk text replacement feature. Here is the [demo video](https://www.youtube.com/watch?v=j05gGT3xfCs).
-
-**Instance Override Propagation**
-Another contribution from [@dusskapark](https://github.com/dusskapark)
-Propagate component instance overrides from a source instance to multiple target instances with a single command. This feature dramatically reduces repetitive design work when working with component instances that need similar customizations. Check out our [demo video](https://youtu.be/uvuT8LByroI).
-
-## Manual Setup and Installation
-
-### MCP Server: Integration with Cursor
-
-Add the server to your Cursor MCP configuration in `~/.cursor/mcp.json`:
+**Cursor** — add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
 
 ```json
 {
   "mcpServers": {
     "TalkToFigma": {
       "command": "bunx",
-      "args": ["cursor-talk-to-figma-mcp@latest"]
+      "args": ["@biolab/talk-to-figma@latest"]
     }
   }
 }
 ```
 
-### WebSocket Server
-
-Start the WebSocket server:
+**Claude Code** — add to `.mcp.json` in your project root, or via CLI:
 
 ```bash
-bun socket
+claude mcp add TalkToFigma -- bunx @biolab/talk-to-figma@latest
 ```
 
-### Figma Plugin
-
-1. In Figma, go to Plugins > Development > New Plugin
-2. Choose "Link existing plugin"
-3. Select the `src/cursor_mcp_plugin/manifest.json` file
-4. The plugin should now be available in your Figma development plugins
-
-## Windows + WSL Guide
-
-1. Install bun via powershell
+### 2. Start the WebSocket relay
 
 ```bash
-powershell -c "irm bun.sh/install.ps1|iex"
+bunx @biolab/talk-to-figma --relay
 ```
 
-2. Uncomment the hostname `0.0.0.0` in `src/socket.ts`
+Runs on port 3055 by default (configurable via `PORT` env).
 
-```typescript
-// uncomment this to allow connections in windows wsl
-hostname: "0.0.0.0",
-```
+### 3. Install the Figma plugin
 
-3. Start the websocket
+Download the plugin zip, unzip it, then in Figma: Plugins → Development → Link existing plugin → select `manifest.json`
 
-```bash
-bun socket
+```
+https://cdn.jsdelivr.net/npm/@biolab/talk-to-figma@latest/figma-plugin/figma-plugin.zip
 ```
 
-## Usage
+### 4. Connect
 
-1. Start the WebSocket server
-2. Install the MCP server in Cursor
-3. Open Figma and run the Cursor MCP Plugin
-4. Connect the plugin to the WebSocket server by joining a channel using `join_channel`
-5. Use Cursor to communicate with Figma using the MCP tools
+1. Open the plugin in Figma and join a channel
+2. In your AI agent, call `join_channel` with the same channel name
+3. Start using the MCP tools
 
-## Local Development Setup
+## MCP Tools
 
-To develop, update your mcp config to direct to your local directory.
+### Document & Selection
 
-```json
-{
-  "mcpServers": {
-    "TalkToFigma": {
-      "command": "bun",
-      "args": ["/path-to-repo/src/talk_to_figma_mcp/server.ts"]
-    }
-  }
-}
-```
+- `get_document_info` - Get document info
+- `get_selection` - Get current selection
+- `read_my_design` - Get detailed selection info with all node details
+- `get_node_info` - Get info about a specific node
+- `get_nodes_info` - Get info about multiple nodes
+- `set_focus` - Focus and scroll to a node
+- `set_selections` - Select multiple nodes
 
-## MCP Tools
+### Creating Elements
 
-The MCP server provides the following tools for interacting with Figma:
+- `create_rectangle` - Create a rectangle
+- `create_frame` - Create a frame with auto-layout support
+- `create_text` - Create a text node
+
+### Modifying Elements
+
+- `set_fill_color` - Set fill color (RGBA 0-1)
+- `set_stroke_color` - Set stroke color and weight
+- `set_corner_radius` - Set corner radius (per-corner support)
+- `set_text_content` - Set text content
+- `set_multiple_text_contents` - Batch update text nodes
+- `move_node` - Move a node
+- `resize_node` - Resize a node
+- `clone_node` - Clone a node
+- `delete_node` / `delete_multiple_nodes` - Delete nodes
+
+### Auto Layout
+
+- `set_layout_mode` - Set layout mode (NONE, HORIZONTAL, VERTICAL)
+- `set_padding` - Set frame padding
+- `set_axis_align` - Set axis alignment
+- `set_layout_sizing` - Set sizing mode (FIXED, HUG, FILL)
+- `set_item_spacing` - Set spacing between children
+
+### Variables
+
+- `get_local_variables` - Get all local variables with values per mode
+- `get_local_variable_collections` - Get variable collections with modes
+- `get_variable_by_id` - Get a specific variable
+- `create_variable_collection` - Create a variable collection
+- `create_variable` - Create a variable
+- `set_variable_value` - Set variable value for a mode
+- `set_variable_mode_name` - Rename a mode
+- `set_variable_binding` - Bind a variable to a node property
 
-### Document & Selection
+### Components & Styles
 
-- `get_document_info` - Get information about the current Figma document
-- `get_selection` - Get information about the current selection
-- `read_my_design` - Get detailed node information about the current selection without parameters
-- `get_node_info` - Get detailed information about a specific node
-- `get_nodes_info` - Get detailed information about multiple nodes by providing an array of node IDs
-- `set_focus` - Set focus on a specific node by selecting it and scrolling viewport to it
-- `set_selections` - Set selection to multiple nodes and scroll viewport to show them
+- `get_styles` - Get local styles
+- `get_local_components` - Get local components
+- `create_component_instance` - Instantiate a component
+- `get_instance_overrides` / `set_instance_overrides` - Copy/apply instance overrides
+- `get_team_library_components` - Get team library components
+- `get_team_library_variables` - Get team library variables
+- `import_variable_by_key` - Import a variable from team library
+
+### Scanning
+
+- `scan_text_nodes` - Scan text nodes (chunked for large designs)
+- `scan_nodes_by_types` - Scan nodes by type
 
 ### Annotations
 
-- `get_annotations` - Get all annotations in the current document or specific node
-- `set_annotation` - Create or update an annotation with markdown support
-- `set_multiple_annotations` - Batch create/update multiple annotations efficiently
-- `scan_nodes_by_types` - Scan for nodes with specific types (useful for finding annotation targets)
+- `get_annotations` - Get annotations
+- `set_annotation` / `set_multiple_annotations` - Create/update annotations
 
 ### Prototyping & Connections
 
-- `get_reactions` - Get all prototype reactions from nodes with visual highlight animation
-- `set_default_connector` - Set a copied FigJam connector as the default connector style for creating connections (must be set before creating connections)
-- `create_connections` - Create FigJam connector lines between nodes, based on prototype flows or custom mapping
+- `get_reactions` - Get prototype reactions
+- `set_default_connector` - Set default connector style
+- `create_connections` - Create connector lines between nodes
 
-### Creating Elements
+### Export
 
-- `create_rectangle` - Create a new rectangle with position, size, and optional name
-- `create_frame` - Create a new frame with position, size, and optional name
-- `create_text` - Create a new text node with customizable font properties
+- `export_node_as_image` - Export as PNG, JPG, SVG, or PDF
 
-### Modifying text content
+### Connection
 
-- `scan_text_nodes` - Scan text nodes with intelligent chunking for large designs
-- `set_text_content` - Set the text content of a single text node
-- `set_multiple_text_contents` - Batch update multiple text nodes efficiently
+- `join_channel` - Join a channel to communicate with Figma
 
-### Auto Layout & Spacing
+## Local Development
 
-- `set_layout_mode` - Set the layout mode and wrap behavior of a frame (NONE, HORIZONTAL, VERTICAL)
-- `set_padding` - Set padding values for an auto-layout frame (top, right, bottom, left)
-- `set_axis_align` - Set primary and counter axis alignment for auto-layout frames
-- `set_layout_sizing` - Set horizontal and vertical sizing modes for auto-layout frames (FIXED, HUG, FILL)
-- `set_item_spacing` - Set distance between children in an auto-layout frame
+```bash
+bun install      # Install dependencies
+bun run build    # Build MCP server + relay (tsup → dist/)
+bun run dev      # Build in watch mode
+bun socket       # Start WebSocket relay (Bun-native, dev only)
+```
 
-### Styling
+For local dev, point your MCP config to the built CLI:
 
-- `set_fill_color` - Set the fill color of a node (RGBA)
-- `set_stroke_color` - Set the stroke color and weight of a node
-- `set_corner_radius` - Set the corner radius of a node with optional per-corner control
+```json
+{
+  "mcpServers": {
+    "TalkToFigma": {
+      "command": "node",
+      "args": ["/path-to-repo/dist/cli.js"]
+    }
+  }
+}
+```
 
-### Layout & Organization
+Start the relay locally:
 
-- `move_node` - Move a node to a new position
-- `resize_node` - Resize a node with new dimensions
-- `delete_node` - Delete a node
-- `delete_multiple_nodes` - Delete multiple nodes at once efficiently
-- `clone_node` - Create a copy of an existing node with optional position offset
+```bash
+node dist/cli.js --relay
+```
 
-### Components & Styles
+## Project Structure
 
-- `get_styles` - Get information about local styles
-- `get_local_components` - Get information about local components
-- `create_component_instance` - Create an instance of a component
-- `get_instance_overrides` - Extract override properties from a selected component instance
-- `set_instance_overrides` - Apply extracted overrides to target instances
-
-### Export & Advanced
-
-- `export_node_as_image` - Export a node as an image (PNG, JPG, SVG, or PDF) - limited support on image currently returning base64 as text
-
-### Connection Management
-
-- `join_channel` - Join a specific channel to communicate with Figma
-
-### MCP Prompts
-
-The MCP server includes several helper prompts to guide you through complex design tasks:
-
-- `design_strategy` - Best practices for working with Figma designs
-- `read_design_strategy` - Best practices for reading Figma designs
-- `text_replacement_strategy` - Systematic approach for replacing text in Figma designs
-- `annotation_conversion_strategy` - Strategy for converting manual annotations to Figma's native annotations
-- `swap_overrides_instances` - Strategy for transferring overrides between component instances in Figma
-- `reaction_to_connector_strategy` - Strategy for converting Figma prototype reactions to connector lines using the output of 'get_reactions', and guiding the use 'create_connections' in sequence
-
-## Development
-
-### Building the Figma Plugin
-
-1. Navigate to the Figma plugin directory:
-
-   ```
-   cd src/cursor_mcp_plugin
-   ```
-
-2. Edit code.js and ui.html
-
-## Best Practices
-
-When working with the Figma MCP:
-
-1. Always join a channel before sending commands
-2. Get document overview using `get_document_info` first
-3. Check current selection with `get_selection` before modifications
-4. Use appropriate creation tools based on needs:
-   - `create_frame` for containers
-   - `create_rectangle` for basic shapes
-   - `create_text` for text elements
-5. Verify changes using `get_node_info`
-6. Use component instances when possible for consistency
-7. Handle errors appropriately as all commands can throw exceptions
-8. For large designs:
-   - Use chunking parameters in `scan_text_nodes`
-   - Monitor progress through WebSocket updates
-   - Implement appropriate error handling
-9. For text operations:
-   - Use batch operations when possible
-   - Consider structural relationships
-   - Verify changes with targeted exports
-10. For converting legacy annotations:
-    - Scan text nodes to identify numbered markers and descriptions
-    - Use `scan_nodes_by_types` to find UI elements that annotations refer to
-    - Match markers with their target elements using path, name, or proximity
-    - Categorize annotations appropriately with `get_annotations`
-    - Create native annotations with `set_multiple_annotations` in batches
-    - Verify all annotations are properly linked to their targets
-    - Delete legacy annotation nodes after successful conversion
-11. Visualize prototype noodles as FigJam connectors:
-
-- Use `get_reactions` to extract prototype flows,
-- set a default connector with `set_default_connector`,
-- and generate connector lines with `create_connections` for clear visual flow mapping.
+- `src/cli.ts` - CLI entry point (routes `--relay` flag)
+- `src/talk_to_figma_mcp/server.ts` - MCP server
+- `src/relay.ts` - WebSocket relay (Node-compatible, bundled in npm package)
+- `src/socket.ts` - WebSocket relay (Bun-native, local dev only)
+- `src/cursor_mcp_plugin/` - Figma plugin (`code.js`, `ui.html`, `manifest.json`)
 
 ## License