This is page 1 of 2. Use http://codebase.md/sonnylazuardi/cursor-talk-to-figma-mcp?page={x} to view the full context.
# Directory Structure
```
├── .gitignore
├── bun.lock
├── Dockerfile
├── DRAGME.md
├── LICENSE
├── package.json
├── readme.md
├── scripts
│ └── setup.sh
├── smithery.yaml
├── src
│ ├── cursor_mcp_plugin
│ │ ├── code.js
│ │ ├── manifest.json
│ │ ├── setcharacters.js
│ │ └── ui.html
│ ├── socket.ts
│ └── talk_to_figma_mcp
│ ├── bun.lock
│ ├── package.json
│ ├── server.ts
│ └── tsconfig.json
├── tsconfig.json
└── tsup.config.ts
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
node_modules/
.cursor/
dist/
docs/
```
--------------------------------------------------------------------------------
/readme.md:
--------------------------------------------------------------------------------
```markdown
# Cursor Talk to Figma MCP
This project implements a Model Context Protocol (MCP) integration between Cursor AI and Figma, allowing Cursor to communicate with Figma for reading designs and modifying them 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
## Get Started
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
```
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
[Video Link](https://www.linkedin.com/posts/sonnylazuardi_just-wanted-to-share-my-latest-experiment-activity-7307821553654657024-yrh8)
## Design Automation Example
**Bulk text content replacement**
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).
## Development Setup
To develop, update your mcp config to direct to your local directory.
```json
{
"mcpServers": {
"TalkToFigma": {
"command": "bun",
"args": ["/path-to-repo/src/talk_to_figma_mcp/server.ts"]
}
}
}
```
## Manual Setup and Installation
### MCP Server: Integration with Cursor
Add the server to your Cursor MCP configuration in `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"TalkToFigma": {
"command": "bunx",
"args": ["cursor-talk-to-figma-mcp@latest"]
}
}
}
```
### WebSocket Server
Start the WebSocket server:
```bash
bun socket
```
### 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
```bash
powershell -c "irm bun.sh/install.ps1|iex"
```
2. Uncomment the hostname `0.0.0.0` in `src/socket.ts`
```typescript
// uncomment this to allow connections in windows wsl
hostname: "0.0.0.0",
```
3. Start the websocket
```bash
bun socket
```
## Usage
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
## MCP Tools
The MCP server provides the following tools for interacting with Figma:
### Document & Selection
- `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
### 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)
### 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
### Creating Elements
- `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
### Modifying text content
- `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
### Auto Layout & Spacing
- `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
### Styling
- `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
### Layout & Organization
- `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
### Components & Styles
- `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.
## License
MIT
```
--------------------------------------------------------------------------------
/tsup.config.ts:
--------------------------------------------------------------------------------
```typescript
import { defineConfig } from 'tsup';
export default defineConfig({
entry: ['src/talk_to_figma_mcp/server.ts'],
format: ['cjs', 'esm'],
dts: true,
clean: true,
outDir: 'dist',
target: 'node18',
sourcemap: true,
minify: false,
splitting: false,
bundle: true,
});
```
--------------------------------------------------------------------------------
/scripts/setup.sh:
--------------------------------------------------------------------------------
```bash
#!/bin/bash
# Create .cursor directory if it doesn't exist
mkdir -p .cursor
bun install
# Create mcp.json with the current directory path
echo "{
\"mcpServers\": {
\"TalkToFigma\": {
\"command\": \"bunx\",
\"args\": [
\"cursor-talk-to-figma-mcp@latest\"
]
}
}
}" > .cursor/mcp.json
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Use the Bun image as the base image
FROM oven/bun:latest
# Set the working directory in the container
WORKDIR /app
# Copy the current directory contents into the container at /app
COPY package*.json ./
RUN bun install
# Expose the port on which the API will listen
EXPOSE 3055
# Run the server when the container launches
CMD ["bun", "src/talk_to_figma_mcp/server.ts"]
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"esModuleInterop": true,
"strict": false,
"skipLibCheck": true,
"declaration": true,
"outDir": "dist",
"rootDir": "src",
"lib": ["ES2022"],
"types": ["bun-types"]
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
startCommand:
type: stdio
configSchema:
# JSON Schema defining the configuration options for the MCP.
{}
commandFunction:
# A JS function that produces the CLI command based on the given config to start the MCP on stdio.
|-
(config) => ({
command: 'bunx',
args: ['cursor-talk-to-figma-mcp']
})
```
--------------------------------------------------------------------------------
/src/talk_to_figma_mcp/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2020",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": false,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"outDir": "dist",
"rootDir": ".",
"declaration": true,
"experimentalDecorators": false,
"emitDecoratorMetadata": false
},
"include": ["./**/*.ts"],
"exclude": ["node_modules", "dist"]
}
```
--------------------------------------------------------------------------------
/src/cursor_mcp_plugin/manifest.json:
--------------------------------------------------------------------------------
```json
{
"name": "Cursor MCP Plugin",
"id": "cursor-mcp-plugin",
"api": "1.0.0",
"main": "code.js",
"ui": "ui.html",
"editorType": [
"figma",
"figjam"
],
"permissions": [],
"networkAccess": {
"allowedDomains": [
"https://google.com"
],
"devAllowedDomains": [
"http://localhost:3055",
"ws://localhost:3055"
]
},
"documentAccess": "dynamic-page",
"enableProposedApi": true,
"enablePrivatePluginApi": true
}
```
--------------------------------------------------------------------------------
/src/talk_to_figma_mcp/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "talk-to-figma-mcp",
"version": "1.0.0",
"description": "MCP server for Figma integration",
"main": "server.ts",
"type": "module",
"scripts": {
"start": "node --loader ts-node/esm server.ts",
"build": "tsc",
"dev": "node --loader ts-node/esm --watch server.ts"
},
"keywords": [
"figma",
"mcp",
"cursor",
"ai"
],
"dependencies": {
"@modelcontextprotocol/sdk": "1.13.1",
"uuid": "^9.0.1",
"ws": "^8.16.0",
"zod": "3.22.4"
},
"devDependencies": {
"@types/node": "^20.10.5",
"@types/uuid": "^9.0.7",
"@types/ws": "^8.5.10",
"ts-node": "^10.9.2",
"typescript": "^5.3.3"
}
}
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "cursor-talk-to-figma-mcp",
"description": "Cursor Talk to Figma MCP",
"version": "0.3.3",
"module": "dist/server.js",
"main": "dist/server.js",
"bin": {
"cursor-talk-to-figma-mcp": "dist/server.js"
},
"files": [
"dist",
"README.md"
],
"type": "module",
"scripts": {
"start": "bun run dist/server.js",
"socket": "bun run src/socket.ts",
"setup": "./scripts/setup.sh",
"build": "tsup",
"build:watch": "tsup --watch",
"dev": "bun run build:watch",
"pub:release": "bun run build && npm publish"
},
"devDependencies": {
"@types/bun": "latest",
"bun-types": "^1.2.5",
"tsup": "^8.4.0",
"typescript": "^5.0.0"
},
"dependencies": {
"@modelcontextprotocol/sdk": "1.13.1",
"uuid": "latest",
"ws": "latest",
"zod": "3.22.4"
}
}
```
--------------------------------------------------------------------------------
/src/socket.ts:
--------------------------------------------------------------------------------
```typescript
import { Server, ServerWebSocket } from "bun";
// Store clients by channel
const channels = new Map<string, Set<ServerWebSocket<any>>>();
function handleConnection(ws: ServerWebSocket<any>) {
// Don't add to clients immediately - wait for channel join
console.log("New client connected");
// Send welcome message to the new client
ws.send(JSON.stringify({
type: "system",
message: "Please join a channel to start chatting",
}));
ws.close = () => {
console.log("Client disconnected");
// Remove client from their channel
channels.forEach((clients, channelName) => {
if (clients.has(ws)) {
clients.delete(ws);
// Notify other clients in same channel
clients.forEach((client) => {
if (client.readyState === WebSocket.OPEN) {
client.send(JSON.stringify({
type: "system",
message: "A user has left the channel",
channel: channelName
}));
}
});
}
});
};
}
const server = Bun.serve({
port: 3055,
// uncomment this to allow connections in windows wsl
// hostname: "0.0.0.0",
fetch(req: Request, server: Server) {
// Handle CORS preflight
if (req.method === "OPTIONS") {
return new Response(null, {
headers: {
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
"Access-Control-Allow-Headers": "Content-Type, Authorization",
},
});
}
// Handle WebSocket upgrade
const success = server.upgrade(req, {
headers: {
"Access-Control-Allow-Origin": "*",
},
});
if (success) {
return; // Upgraded to WebSocket
}
// Return response for non-WebSocket requests
return new Response("WebSocket server running", {
headers: {
"Access-Control-Allow-Origin": "*",
},
});
},
websocket: {
open: handleConnection,
message(ws: ServerWebSocket<any>, message: string | Buffer) {
try {
console.log("Received message from client:", message);
const data = JSON.parse(message as string);
if (data.type === "join") {
const channelName = data.channel;
if (!channelName || typeof channelName !== "string") {
ws.send(JSON.stringify({
type: "error",
message: "Channel name is required"
}));
return;
}
// Create channel if it doesn't exist
if (!channels.has(channelName)) {
channels.set(channelName, new Set());
}
// Add client to channel
const channelClients = channels.get(channelName)!;
channelClients.add(ws);
// Notify client they joined successfully
ws.send(JSON.stringify({
type: "system",
message: `Joined channel: ${channelName}`,
channel: channelName
}));
console.log("Sending message to client:", data.id);
ws.send(JSON.stringify({
type: "system",
message: {
id: data.id,
result: "Connected to channel: " + channelName,
},
channel: channelName
}));
// Notify other clients in channel
channelClients.forEach((client) => {
if (client !== ws && client.readyState === WebSocket.OPEN) {
client.send(JSON.stringify({
type: "system",
message: "A new user has joined the channel",
channel: channelName
}));
}
});
return;
}
// Handle regular messages
if (data.type === "message") {
const channelName = data.channel;
if (!channelName || typeof channelName !== "string") {
ws.send(JSON.stringify({
type: "error",
message: "Channel name is required"
}));
return;
}
const channelClients = channels.get(channelName);
if (!channelClients || !channelClients.has(ws)) {
ws.send(JSON.stringify({
type: "error",
message: "You must join the channel first"
}));
return;
}
// Broadcast to all clients in the channel
channelClients.forEach((client) => {
if (client.readyState === WebSocket.OPEN) {
console.log("Broadcasting message to client:", data.message);
client.send(JSON.stringify({
type: "broadcast",
message: data.message,
sender: client === ws ? "You" : "User",
channel: channelName
}));
}
});
}
} catch (err) {
console.error("Error handling message:", err);
}
},
close(ws: ServerWebSocket<any>) {
// Remove client from their channel
channels.forEach((clients) => {
clients.delete(ws);
});
}
}
});
console.log(`WebSocket server running on port ${server.port}`);
```
--------------------------------------------------------------------------------
/src/cursor_mcp_plugin/setcharacters.js:
--------------------------------------------------------------------------------
```javascript
function uniqBy(arr, predicate) {
const cb = typeof predicate === "function" ? predicate : (o) => o[predicate];
return [
...arr
.reduce((map, item) => {
const key = item === null || item === undefined ? item : cb(item);
map.has(key) || map.set(key, item);
return map;
}, new Map())
.values(),
];
}
export const setCharacters = async (node, characters, options) => {
const fallbackFont = options?.fallbackFont || {
family: "Roboto",
style: "Regular",
};
try {
if (node.fontName === figma.mixed) {
if (options?.smartStrategy === "prevail") {
const fontHashTree = {};
for (let i = 1; i < node.characters.length; i++) {
const charFont = node.getRangeFontName(i - 1, i);
const key = `${charFont.family}::${charFont.style}`;
fontHashTree[key] = fontHashTree[key] ? fontHashTree[key] + 1 : 1;
}
const prevailedTreeItem = Object.entries(fontHashTree).sort(
(a, b) => b[1] - a[1]
)[0];
const [family, style] = prevailedTreeItem[0].split("::");
const prevailedFont = {
family,
style,
};
await figma.loadFontAsync(prevailedFont);
node.fontName = prevailedFont;
} else if (options?.smartStrategy === "strict") {
return setCharactersWithStrictMatchFont(node, characters, fallbackFont);
} else if (options?.smartStrategy === "experimental") {
return setCharactersWithSmartMatchFont(node, characters, fallbackFont);
} else {
const firstCharFont = node.getRangeFontName(0, 1);
await figma.loadFontAsync(firstCharFont);
node.fontName = firstCharFont;
}
} else {
await figma.loadFontAsync({
family: node.fontName.family,
style: node.fontName.style,
});
}
} catch (err) {
console.warn(
`Failed to load "${node.fontName["family"]} ${node.fontName["style"]}" font and replaced with fallback "${fallbackFont.family} ${fallbackFont.style}"`,
err
);
await figma.loadFontAsync(fallbackFont);
node.fontName = fallbackFont;
}
try {
node.characters = characters;
return true;
} catch (err) {
console.warn(`Failed to set characters. Skipped.`, err);
return false;
}
};
const setCharactersWithStrictMatchFont = async (
node,
characters,
fallbackFont
) => {
const fontHashTree = {};
for (let i = 1; i < node.characters.length; i++) {
const startIdx = i - 1;
const startCharFont = node.getRangeFontName(startIdx, i);
const startCharFontVal = `${startCharFont.family}::${startCharFont.style}`;
while (i < node.characters.length) {
i++;
const charFont = node.getRangeFontName(i - 1, i);
if (startCharFontVal !== `${charFont.family}::${charFont.style}`) {
break;
}
}
fontHashTree[`${startIdx}_${i}`] = startCharFontVal;
}
await figma.loadFontAsync(fallbackFont);
node.fontName = fallbackFont;
node.characters = characters;
console.log(fontHashTree);
await Promise.all(
Object.keys(fontHashTree).map(async (range) => {
console.log(range, fontHashTree[range]);
const [start, end] = range.split("_");
const [family, style] = fontHashTree[range].split("::");
const matchedFont = {
family,
style,
};
await figma.loadFontAsync(matchedFont);
return node.setRangeFontName(Number(start), Number(end), matchedFont);
})
);
return true;
};
const getDelimiterPos = (str, delimiter, startIdx = 0, endIdx = str.length) => {
const indices = [];
let temp = startIdx;
for (let i = startIdx; i < endIdx; i++) {
if (
str[i] === delimiter &&
i + startIdx !== endIdx &&
temp !== i + startIdx
) {
indices.push([temp, i + startIdx]);
temp = i + startIdx + 1;
}
}
temp !== endIdx && indices.push([temp, endIdx]);
return indices.filter(Boolean);
};
const buildLinearOrder = (node) => {
const fontTree = [];
const newLinesPos = getDelimiterPos(node.characters, "\n");
newLinesPos.forEach(([newLinesRangeStart, newLinesRangeEnd], n) => {
const newLinesRangeFont = node.getRangeFontName(
newLinesRangeStart,
newLinesRangeEnd
);
if (newLinesRangeFont === figma.mixed) {
const spacesPos = getDelimiterPos(
node.characters,
" ",
newLinesRangeStart,
newLinesRangeEnd
);
spacesPos.forEach(([spacesRangeStart, spacesRangeEnd], s) => {
const spacesRangeFont = node.getRangeFontName(
spacesRangeStart,
spacesRangeEnd
);
if (spacesRangeFont === figma.mixed) {
const spacesRangeFont = node.getRangeFontName(
spacesRangeStart,
spacesRangeStart[0]
);
fontTree.push({
start: spacesRangeStart,
delimiter: " ",
family: spacesRangeFont.family,
style: spacesRangeFont.style,
});
} else {
fontTree.push({
start: spacesRangeStart,
delimiter: " ",
family: spacesRangeFont.family,
style: spacesRangeFont.style,
});
}
});
} else {
fontTree.push({
start: newLinesRangeStart,
delimiter: "\n",
family: newLinesRangeFont.family,
style: newLinesRangeFont.style,
});
}
});
return fontTree
.sort((a, b) => +a.start - +b.start)
.map(({ family, style, delimiter }) => ({ family, style, delimiter }));
};
const setCharactersWithSmartMatchFont = async (
node,
characters,
fallbackFont
) => {
const rangeTree = buildLinearOrder(node);
const fontsToLoad = uniqBy(
rangeTree,
({ family, style }) => `${family}::${style}`
).map(({ family, style }) => ({
family,
style,
}));
await Promise.all([...fontsToLoad, fallbackFont].map(figma.loadFontAsync));
node.fontName = fallbackFont;
node.characters = characters;
let prevPos = 0;
rangeTree.forEach(({ family, style, delimiter }) => {
if (prevPos < node.characters.length) {
const delimeterPos = node.characters.indexOf(delimiter, prevPos);
const endPos =
delimeterPos > prevPos ? delimeterPos : node.characters.length;
const matchedFont = {
family,
style,
};
node.setRangeFontName(prevPos, endPos, matchedFont);
prevPos = endPos + 1;
}
});
return true;
};
```
--------------------------------------------------------------------------------
/src/cursor_mcp_plugin/ui.html:
--------------------------------------------------------------------------------
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Cursor MCP Plugin</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
Helvetica, Arial, sans-serif;
margin: 0;
padding: 20px;
color: #e0e0e0;
background-color: #1e1e1e;
}
.container {
display: flex;
flex-direction: column;
height: 100%;
}
h1 {
font-size: 16px;
font-weight: 600;
margin-bottom: 10px;
color: #ffffff;
}
h2 {
font-size: 14px;
font-weight: 600;
margin-top: 20px;
margin-bottom: 8px;
color: #ffffff;
}
button {
background-color: #18a0fb;
border: none;
color: white;
padding: 8px 12px;
border-radius: 6px;
margin-top: 8px;
margin-bottom: 8px;
cursor: pointer;
font-size: 14px;
transition: background-color 0.2s;
}
button:hover {
background-color: #0d8ee0;
}
button.secondary {
background-color: #3d3d3d;
color: #e0e0e0;
}
button.secondary:hover {
background-color: #4d4d4d;
}
button:disabled {
background-color: #333333;
color: #666666;
cursor: not-allowed;
}
input {
border: 1px solid #444444;
border-radius: 4px;
padding: 8px;
margin-bottom: 12px;
font-size: 14px;
width: 100%;
box-sizing: border-box;
background-color: #2d2d2d;
color: #e0e0e0;
}
label {
display: block;
margin-bottom: 4px;
font-size: 12px;
font-weight: 500;
color: #cccccc;
}
.status {
margin-top: 16px;
padding: 12px;
border-radius: 6px;
font-size: 14px;
}
.status.connected {
background-color: #1a472a;
color: #4ade80;
}
.status.disconnected {
background-color: #471a1a;
color: #ff9999;
}
.status.info {
background-color: #1a3147;
color: #66b3ff;
}
.section {
margin-bottom: 24px;
}
.hidden {
display: none;
}
.logo {
width: 50px;
height: 50px;
}
.header {
display: flex;
align-items: center;
margin-bottom: 16px;
}
.header-text {
margin-left: 12px;
}
.header-text h1 {
margin: 0;
font-size: 16px;
}
.header-text p {
margin: 4px 0 0 0;
font-size: 12px;
color: #999999;
}
.tabs {
display: flex;
border-bottom: 1px solid #444444;
margin-bottom: 16px;
}
.tab {
padding: 8px 16px;
cursor: pointer;
font-size: 14px;
font-weight: 500;
color: #999999;
}
.tab.active {
border-bottom: 2px solid #18a0fb;
color: #18a0fb;
}
.tab-content {
display: none;
}
.tab-content.active {
display: block;
}
.link {
color: #18a0fb;
text-decoration: none;
cursor: pointer;
}
.link:hover {
text-decoration: underline;
}
.header-logo {
padding: 16px;
border-radius: 16px;
background-color: #333;
}
.header-logo-image {
width: 24px;
height: 24px;
object-fit: contain;
}
/* Progress styles */
.operation-complete {
color: #4ade80;
}
.operation-error {
color: #ff9999;
}
</style>
</head>
<body>
<div class="container">
<div class="header">
<div class="header-logo">
<img
class="header-logo-image"
src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAMAAAANIilAAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAJcEhZcwAAEJwAABCcASbNOjQAAAB1UExURUdwTP////////////////39/f////////////////////////////7+/v////////////39/f////////////////////////////////////////////////////39/fn5+ejo6P///+rq6uXl5f////Ly8gf4a04AAAAkdFJOUwAOdkZCfz04zIgbT0pkIagnm7C9b6C2LWqSxBMyB11W2Ovsy3D12ZYAAALtSURBVEjHndcJt6ogEADgXNAUcWlxSQVN3/3/P/EBAgJpWdM9p5ue78xANE2n05vIUduffgvn1oA0bX+hvRc1DYjTPHe+tiGIoqhx4zTNq/y72lMURQtmqasuPc4dAmgwfWuZrqquiw8uNnC5BRJT3YXhIZ7Xris0oLjlmOrArz7VHpOb6wpNee0ITVMHvvd25/qgvtFwla8dpxV7xnTi7dbed7iuTY16lZoV7iXQb3cqRgjVgoviKTZSUw2719pbD2OEVu5yjnqeOpZ75lMMobVzfUcwC6lrofGJpdb3jGtj6TkkNKRWtXMsU+ciNdfQUwe+zZ7/vo1CYYgv39G/kShMS6mHL+g8F96K2Uqi52E6j3DFnsc4uR/hMwugYd9bOLoeSTvPE1yx4/sLh9B9fKbziHVM3z/G+dKb5wdKdysxsNCc4+2l/yk7EnrOVhwGBt9auqJ0t9gR13C4cl77bdil88SPuK9jxrXksHjab48Mwo+4ha3aSbZJ52JpC4GFbY7OdsVst4Lls/mKZe1y6fXTonS3RFsIN7C5dAJsO+WiI21jbd8xesFEtoUdLLjH+qGNJ9WRuj3MOOQNycaV6khvsLc0MxsD2Uq7bhcHuBZh4rFdujjT1c6GkaXtszCx3sW3MRRfNjwiI7EjGjGfFjZwUgM9CuNggqRVXz+vOGDTBOCP5UnHE73ghjK1jYNlEIma9UnHBb/qdkvq1MSQjk4yCvGk4UneQylLbWAIio3I1t26q4sNTuM01tqQe9+My5pYv9wk8Ypv92w7JpXYulGoD8aJ3C/bUUp8tW5EuTa2oXI7ZGLzahZYE0l03QqZWI8Lfh1lw+zxEoNIrF8Dm/NQT8rzgz+WP/oQmL6Ud4pud/4DZzMWPKjXZfJufOyiVzzKV4/609yelDaWiZsDc6+DSwOLxNqxeD/6Ah3zf674+Kyf3xUeDi3WDFIKzCpOv/5phB4MD+cs/OWXVdych/GBf/xJd4pL9+1i/wOElMO5v/co4wAAAABJRU5ErkJggg=="
/>
</div>
<div class="header-text">
<h1>Cursor Talk To Figma Plugin</h1>
<p>Connect Figma to Cursor AI using MCP</p>
</div>
</div>
<div class="tabs">
<div id="tab-connection" class="tab active">Connection</div>
<div id="tab-about" class="tab">About</div>
</div>
<div id="content-connection" class="tab-content active">
<div class="section">
<label for="port">WebSocket Server Port</label>
<div style="display: flex; gap: 8px">
<input
type="number"
id="port"
placeholder="3055"
value="3055"
min="1024"
max="65535"
/>
<button id="btn-connect" class="primary">Connect</button>
</div>
</div>
<div id="connection-status" class="status disconnected">
Not connected to Cursor MCP server
</div>
<div class="section">
<button id="btn-disconnect" class="secondary" disabled>
Disconnect
</button>
</div>
<!-- Add Progress Bar Section -->
<div id="progress-container" class="section hidden">
<h2>Operation Progress</h2>
<div id="progress-message">No operation in progress</div>
<div style="width: 100%; background-color: #444; border-radius: 4px; margin-top: 8px;">
<div id="progress-bar" style="width: 0%; height: 8px; background-color: #18a0fb; border-radius: 4px; transition: width 0.3s;"></div>
</div>
<div style="display: flex; justify-content: space-between; margin-top: 4px; font-size: 12px;">
<div id="progress-status">Not started</div>
<div id="progress-percentage">0%</div>
</div>
</div>
</div>
<div id="content-about" class="tab-content">
<div class="section">
<h2>About Cursor Talk To Figma Plugin</h2>
<p>
This plugin allows Cursor AI to communicate with Figma, enabling
AI-assisted design operations.
<a
class="link"
onclick="window.open(`https://github.com/grab/cursor-talk-to-figma-mcp`, '_blank')"
>Github</a
>
</p>
<p>Version: 1.0.0</p>
<h2>How to Use</h2>
<ol>
<li>Make sure the MCP server is running in Cursor</li>
<li>Connect to the server using the port number (default: 3055)</li>
<li>Once connected, you can interact with Figma through Cursor</li>
</ol>
</div>
</div>
</div>
<script>
// WebSocket connection state
const state = {
connected: false,
socket: null,
serverPort: 3055,
pendingRequests: new Map(),
channel: null,
};
// UI Elements
const portInput = document.getElementById("port");
const connectButton = document.getElementById("btn-connect");
const disconnectButton = document.getElementById("btn-disconnect");
const connectionStatus = document.getElementById("connection-status");
// Tabs
const tabs = document.querySelectorAll(".tab");
const tabContents = document.querySelectorAll(".tab-content");
// Add UI elements for progress tracking
const progressContainer = document.getElementById("progress-container");
const progressBar = document.getElementById("progress-bar");
const progressMessage = document.getElementById("progress-message");
const progressStatus = document.getElementById("progress-status");
const progressPercentage = document.getElementById("progress-percentage");
// Initialize UI
function updateConnectionStatus(isConnected, message) {
state.connected = isConnected;
connectionStatus.innerHTML =
message ||
(isConnected
? "Connected to Cursor MCP server"
: "Not connected to Cursor MCP server");
connectionStatus.className = `status ${
isConnected ? "connected" : "disconnected"
}`;
connectButton.disabled = isConnected;
disconnectButton.disabled = !isConnected;
portInput.disabled = isConnected;
}
// Connect to WebSocket server
async function connectToServer(port) {
try {
if (state.connected && state.socket) {
updateConnectionStatus(true, "Already connected to server");
return;
}
state.serverPort = port;
state.socket = new WebSocket(`ws://localhost:${port}`);
state.socket.onopen = () => {
// Generate random channel name
const channelName = generateChannelName();
console.log("Joining channel:", channelName);
state.channel = channelName;
// Join the channel using the same format as App.tsx
state.socket.send(
JSON.stringify({
type: "join",
channel: channelName.trim(),
})
);
};
state.socket.onmessage = (event) => {
try {
const data = JSON.parse(event.data);
console.log("Received message:", data);
if (data.type === "system") {
// Successfully joined channel
if (data.message && data.message.result) {
state.connected = true;
const channelName = data.channel;
updateConnectionStatus(
true,
`Connected to server on port ${port} in channel: <strong>${channelName}</strong>`
);
// Notify the plugin code
parent.postMessage(
{
pluginMessage: {
type: "notify",
message: `Connected to Cursor MCP server on port ${port} in channel: ${channelName}`,
},
},
"*"
);
}
} else if (data.type === "error") {
console.error("Error:", data.message);
updateConnectionStatus(false, `Error: ${data.message}`);
state.socket.close();
}
handleSocketMessage(data);
} catch (error) {
console.error("Error parsing message:", error);
}
};
state.socket.onclose = () => {
state.connected = false;
state.socket = null;
updateConnectionStatus(false, "Disconnected from server");
};
state.socket.onerror = (error) => {
console.error("WebSocket error:", error);
updateConnectionStatus(false, "Connection error");
state.connected = false;
state.socket = null;
};
} catch (error) {
console.error("Connection error:", error);
updateConnectionStatus(
false,
`Connection error: ${error.message || "Unknown error"}`
);
}
}
// Disconnect from websocket server
function disconnectFromServer() {
if (state.socket) {
state.socket.close();
state.socket = null;
state.connected = false;
updateConnectionStatus(false, "Disconnected from server");
}
}
// Handle messages from the WebSocket
async function handleSocketMessage(payload) {
const data = payload.message;
console.log("handleSocketMessage", data);
// If it's a response to a previous request
if (data.id && state.pendingRequests.has(data.id)) {
const { resolve, reject } = state.pendingRequests.get(data.id);
state.pendingRequests.delete(data.id);
if (data.error) {
reject(new Error(data.error));
} else {
resolve(data.result);
}
return;
}
// If it's a new command
if (data.command) {
try {
// Send the command to the plugin code
parent.postMessage(
{
pluginMessage: {
type: "execute-command",
id: data.id,
command: data.command,
params: data.params,
},
},
"*"
);
} catch (error) {
// Send error back to WebSocket
sendErrorResponse(
data.id,
error.message || "Error executing command"
);
}
}
}
// Send a command to the WebSocket server
async function sendCommand(command, params) {
return new Promise((resolve, reject) => {
if (!state.connected || !state.socket) {
reject(new Error("Not connected to server"));
return;
}
const id = generateId();
state.pendingRequests.set(id, { resolve, reject });
state.socket.send(
JSON.stringify({
id,
type: "message",
channel: state.channel,
message: {
id,
command,
params,
},
})
);
// Set timeout to reject the promise after 30 seconds
setTimeout(() => {
if (state.pendingRequests.has(id)) {
state.pendingRequests.delete(id);
reject(new Error("Request timed out"));
}
}, 30000);
});
}
// Send success response back to WebSocket
function sendSuccessResponse(id, result) {
if (!state.connected || !state.socket) {
console.error("Cannot send response: socket not connected");
return;
}
state.socket.send(
JSON.stringify({
id,
type: "message",
channel: state.channel,
message: {
id,
result,
},
})
);
}
// Send error response back to WebSocket
function sendErrorResponse(id, errorMessage) {
if (!state.connected || !state.socket) {
console.error("Cannot send error response: socket not connected");
return;
}
state.socket.send(
JSON.stringify({
id,
type: "message",
channel: state.channel,
message: {
id,
error: errorMessage,
result: {}
},
})
);
}
// Helper to generate unique IDs
function generateId() {
return (
Date.now().toString(36) + Math.random().toString(36).substr(2, 5)
);
}
// Add this function after the generateId() function
function generateChannelName() {
const characters = "abcdefghijklmnopqrstuvwxyz0123456789";
let result = "";
for (let i = 0; i < 8; i++) {
result += characters.charAt(
Math.floor(Math.random() * characters.length)
);
}
return result;
}
// Tab switching
tabs.forEach((tab) => {
tab.addEventListener("click", () => {
tabs.forEach((t) => t.classList.remove("active"));
tabContents.forEach((c) => c.classList.remove("active"));
tab.classList.add("active");
const contentId = "content-" + tab.id.split("-")[1];
document.getElementById(contentId).classList.add("active");
});
});
// Connect to server
connectButton.addEventListener("click", () => {
const port = parseInt(portInput.value, 10) || 3055;
updateConnectionStatus(false, "Connecting...");
connectionStatus.className = "status info";
connectToServer(port);
});
// Disconnect from server
disconnectButton.addEventListener("click", () => {
updateConnectionStatus(false, "Disconnecting...");
connectionStatus.className = "status info";
disconnectFromServer();
});
// Function to update progress UI
function updateProgressUI(progressData) {
// Show progress container if hidden
progressContainer.classList.remove("hidden");
// Update progress bar
const progress = progressData.progress || 0;
progressBar.style.width = `${progress}%`;
progressPercentage.textContent = `${progress}%`;
// Update message
progressMessage.textContent = progressData.message || "Operation in progress";
// Update status text based on operation state
if (progressData.status === 'started') {
progressStatus.textContent = "Started";
progressStatus.className = "";
} else if (progressData.status === 'in_progress') {
progressStatus.textContent = "In Progress";
progressStatus.className = "";
} else if (progressData.status === 'completed') {
progressStatus.textContent = "Completed";
progressStatus.className = "operation-complete";
// Hide progress container after 5 seconds
setTimeout(() => {
progressContainer.classList.add("hidden");
}, 5000);
} else if (progressData.status === 'error') {
progressStatus.textContent = "Error";
progressStatus.className = "operation-error";
}
}
// Send operation progress update to server
function sendProgressUpdateToServer(progressData) {
if (!state.connected || !state.socket) {
console.error("Cannot send progress update: socket not connected");
return;
}
console.log("Sending progress update to server:", progressData);
state.socket.send(
JSON.stringify({
id: progressData.commandId,
type: "progress_update",
channel: state.channel,
message: {
id: progressData.commandId,
type: "progress_update",
data: progressData
}
})
);
}
// Reset progress UI
function resetProgressUI() {
progressContainer.classList.add("hidden");
progressBar.style.width = "0%";
progressMessage.textContent = "No operation in progress";
progressStatus.textContent = "Not started";
progressStatus.className = "";
progressPercentage.textContent = "0%";
}
// Listen for messages from the plugin code
window.onmessage = (event) => {
const message = event.data.pluginMessage;
if (!message) return;
console.log("Received message from plugin:", message);
switch (message.type) {
case "connection-status":
updateConnectionStatus(message.connected, message.message);
break;
case "auto-connect":
connectButton.click();
break;
case "auto-disconnect":
disconnectButton.click();
break;
case "command-result":
// Forward the result from plugin code back to WebSocket
sendSuccessResponse(message.id, message.result);
break;
case "command-error":
// Forward the error from plugin code back to WebSocket
sendErrorResponse(message.id, message.error);
break;
case "command_progress":
// Update UI with progress information
updateProgressUI(message);
// Forward progress update to server
sendProgressUpdateToServer(message);
break;
}
};
</script>
</body>
</html>
```
--------------------------------------------------------------------------------
/DRAGME.md:
--------------------------------------------------------------------------------
```markdown
# README for AI Agent: Cursor-Figma MCP Setup Guide
## 🤖 AI Agent Decision Flow
```mermaid
flowchart TD
A[Start Setup] --> B{System Check}
B -->|✅ Pass| C{Admin Access?}
B -->|❌ Failed| Z[❌ Fix Prerequisites]
C -->|✅ Yes| D[Method A: Full Install<br/>Homebrew + Bun]
C -->|❌ No| E[Method B: Cursor-Only<br/>No System Changes]
D --> F[Clone in Cursor]
E --> F
F --> G[Configure MCP]
G --> H{MCP Connected?}
H -->|✅ Yes| I[Start WebSocket]
H -->|❌ No| J[Debug & Retry]
I --> K[Install Figma Plugin]
K --> L[Test Integration]
L --> M[✅ Complete]
J --> H
```
## 🎯 Objective
Install and configure Cursor-Figma MCP integration with **AI-agent-friendly decision trees** and fail-safe checkpoints at each step. This guide uses Cursor's built-in Git clone functionality to directly clone the official repository, simplifying the setup process.
### 🤖 For AI Agents Reading This Guide
This guide is **specifically designed for AI agents** to understand, parse, and execute setup instructions autonomously. Each section includes:
- **Clear boolean decision points** for branching logic
- **Explicit command verification steps** with expected outputs
- **Fallback strategies** when primary methods fail
- **Environment-specific instructions** based on system capabilities
- **Checkpoint validations** before proceeding to next steps
**AI Agent Instructions**:
1. Execute each command and verify the expected output
2. Follow the branching logic based on system environment
3. If any step fails, use the provided fallback methods
4. Always validate checkpoints before continuing
5. **CRITICAL**: Create and update visual progress tracking using Mermaid diagrams at each major checkpoint
## 📋 System Environment Detection
**CRITICAL FOR AI AGENTS**: Execute these detection commands and use results for branching decisions.
```bash
# System Detection Commands - Execute ALL and store results
echo "=== SYSTEM ENVIRONMENT DETECTION ==="
# 1. Operating System Check
OS_TYPE=$(uname -s)
echo "OS_TYPE: $OS_TYPE"
# 2. Shell Type Detection
echo "SHELL_TYPE: $SHELL"
# 3. Homebrew Availability
HOMEBREW_AVAILABLE=$(which brew >/dev/null 2>&1 && echo "YES" || echo "NO")
echo "HOMEBREW_AVAILABLE: $HOMEBREW_AVAILABLE"
# 4. Node.js Availability
NODE_AVAILABLE=$(which node >/dev/null 2>&1 && echo "YES" || echo "NO")
if [ "$NODE_AVAILABLE" = "YES" ]; then
NODE_VERSION=$(node --version 2>/dev/null || echo "UNKNOWN")
echo "NODE_VERSION: $NODE_VERSION"
fi
# 5. Bun Availability
BUN_AVAILABLE=$(which bun >/dev/null 2>&1 && echo "YES" || echo "NO")
if [ "$BUN_AVAILABLE" = "YES" ]; then
BUN_VERSION=$(bun --version 2>/dev/null || echo "UNKNOWN")
echo "BUN_VERSION: $BUN_VERSION"
fi
# 6. Cursor IDE Availability
CURSOR_AVAILABLE=$(which cursor >/dev/null 2>&1 && echo "YES" || echo "NO")
echo "CURSOR_AVAILABLE: $CURSOR_AVAILABLE"
# 7. Git Availability
GIT_AVAILABLE=$(which git >/dev/null 2>&1 && echo "YES" || echo "NO")
if [ "$GIT_AVAILABLE" = "YES" ]; then
GIT_VERSION=$(git --version 2>/dev/null || echo "UNKNOWN")
echo "GIT_VERSION: $GIT_VERSION"
fi
# 8. Admin/Sudo Access Check
SUDO_AVAILABLE=$(sudo -n true 2>/dev/null && echo "YES" || echo "NO")
echo "SUDO_AVAILABLE: $SUDO_AVAILABLE"
echo "=== DETECTION COMPLETE ==="
```
## 📊 AI Agent Progress Tracking Templates
**MANDATORY FOR AI AGENTS**: Use these Mermaid templates to show progress at each checkpoint.
### 🎯 Progress Status Template
Use these exact status indicators:
- ✅ **COMPLETED** - Step finished successfully
- 🔄 **CURRENT** - Currently executing this step
- ⏳ **PENDING** - Not started yet
- ❌ **FAILED** - Step failed, needs attention
- ⚠️ **WARNING** - Step completed with warnings
### 📋 Standard Progress Tracking Template
**AI AGENTS MUST CREATE THIS DIAGRAM** after environment detection and update it at each checkpoint:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method Selection]
B --> C[⚡ Dependency Installation]
C --> D[⚙️ MCP setup and configuration]
D --> E[🌐 WebSocket Server]
E --> F[🔌 Figma Plugin]
F --> G[🧪 Integration Test]
G --> H[✅ Setup Complete]
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
classDef failed fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
classDef warning fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
```
### 🎨 How to Update Progress Status
**AI Agents must use this exact format** at each checkpoint:
```
## 📊 Current Progress Status
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method Selection]
B --> C[⚡ Dependency Installation]
C --> D[⚙️ MCP setup and configuration]
D --> E[🌐 WebSocket Server]
E --> F[🔌 Figma Plugin]
F --> G[🧪 Integration Test]
G --> H[✅ Setup Complete]
class A completed
class B current
class C,D,E,F,G,H pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
classDef failed fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
classDef warning fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
```
### 🛠️ Method-Specific Progress Templates
#### For Method A (Full Installation):
```mermaid
graph LR
A1[🍺 Homebrew Check] --> A2[📦 Install Dependencies]
A2 --> A3[⚙️ MCP Setup]
A3 --> A4[✅ Ready for WebSocket]
```
#### For Method B (Cursor-Only):
```mermaid
graph LR
B1[🖥️ Project Already Open] --> B2[📖 Setup Dependencies]
B2 --> B3[⚙️ MCP Setup]
B3 --> B4[✅ Ready for WebSocket]
```
### 📍 Mandatory Progress Update Points
**AI Agents MUST update progress diagram at these checkpoints:**
1. **After Environment Detection** (Step 1)
2. **After Method Selection** (Step 2)
3. **After Dependency Installation** (Step 3)
4. **After MCP Setup and Configuration** (Step 4)
5. **After WebSocket Start** (Step 5)
6. **After Figma Plugin Install** (Step 6)
7. **After Integration Test** (Step 7)
8. **Final Completion** (Step 8)
### 🤖 AI Agent Progress Update Commands
**Use these exact commands at each checkpoint:**
```
CHECKPOINT [STEP_NUMBER]: [STEP_NAME]
Please create/update the progress tracking diagram to show:
- Current step: [STEP_NAME]
- Status: [✅ COMPLETED / 🔄 CURRENT / ❌ FAILED]
- Next step: [NEXT_STEP_NAME]
- Any warnings or issues encountered
Update the Mermaid diagram with appropriate class assignments and show the overall progress percentage.
```
### 🤖 AI Agent Decision Logic
Based on the detection results above, AI agents should follow this decision tree:
```bash
# AI Agent Decision Variables (set based on detection above)
HOMEBREW_AVAILABLE="YES" # or "NO"
NODE_AVAILABLE="YES" # or "NO"
BUN_AVAILABLE="YES" # or "NO"
CURSOR_AVAILABLE="YES" # or "NO"
SUDO_AVAILABLE="YES" # or "NO"
```
**Decision Tree**:
- IF `HOMEBREW_AVAILABLE="YES"` AND `SUDO_AVAILABLE="YES"` → **Method A1: Homebrew Installation**
- ELIF `SUDO_AVAILABLE="YES"` AND `HOMEBREW_AVAILABLE="NO"` → **Method A2: Direct Installation**
- ELIF `CURSOR_AVAILABLE="YES"` AND `SUDO_AVAILABLE="NO"` → **Method B: Cursor-Only Setup**
- ELSE → **Error: Insufficient System Access**
## 🛡️ Method Selection Based on Environment
### 🌟 Method A1: Homebrew Installation (Recommended)
**Conditions**: `HOMEBREW_AVAILABLE="YES"` AND `SUDO_AVAILABLE="YES"`
- Uses Homebrew package manager
- Cleanest dependency management
- Best for macOS systems with Homebrew
### 🔧 Method A2: Direct Installation
**Conditions**: `SUDO_AVAILABLE="YES"` AND `HOMEBREW_AVAILABLE="NO"`
- Direct installation without package manager
- For systems without Homebrew but with admin access
- Manual dependency management
### 📱 Method B: Cursor-Only Setup
**Conditions**: `CURSOR_AVAILABLE="YES"` AND `SUDO_AVAILABLE="NO"`
- No system-wide installations
- Uses Cursor's built-in capabilities
- For restricted environments
---
## 🚀 Method A1: Homebrew Installation
### 📊 Progress Tracking for Method A1
**AI AGENTS**: Start by creating initial progress diagram:
```
CHECKPOINT 1: STARTING METHOD A1 - HOMEBREW INSTALLATION
Please create the Method A1 progress tracking diagram:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method A1 Selected]
B --> C[🍺 Homebrew Check]
C --> D[📦 Install Dependencies]
D --> E[⚙️ MCP Setup]
E --> F[🚀 Ready for WebSocket]
class A completed
class B current
class C,D,E,F pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
```
### Prerequisites Check for Method A1
```bash
# Verify Homebrew functionality
brew --version && echo "✅ Homebrew functional" || echo "❌ ERROR: Homebrew broken"
# Check brew permissions
brew doctor && echo "✅ Homebrew healthy" || echo "⚠️ WARNING: Homebrew has issues"
```
### Step A1.1: Install Dependencies via Homebrew
```bash
# Update Homebrew first
brew update
# Install Node.js if not available
if [ "$NODE_AVAILABLE" = "NO" ]; then
echo "Installing Node.js via Homebrew..."
brew install node
NODE_AVAILABLE="YES"
NODE_VERSION=$(node --version)
echo "✅ Node.js installed: $NODE_VERSION"
else
echo "✅ Node.js already available: $NODE_VERSION"
fi
# Install Bun if not available
if [ "$BUN_AVAILABLE" = "NO" ]; then
echo "Installing Bun via Homebrew..."
brew install bun
BUN_AVAILABLE="YES"
BUN_VERSION=$(bun --version)
echo "✅ Bun installed: $BUN_VERSION"
else
echo "✅ Bun already available: $BUN_VERSION"
fi
# Verify installations
echo "=== DEPENDENCY VERIFICATION ==="
node --version && echo "✅ Node.js working"
bun --version && echo "✅ Bun working"
git --version && echo "✅ Git working"
which cursor && echo "✅ Cursor available" || echo "❌ Install Cursor IDE manually"
```
**CHECKPOINT A1.1**: All dependencies must show ✅ before proceeding.
**AI AGENTS**: Update progress after dependency installation:
```
CHECKPOINT 2: DEPENDENCIES INSTALLED
Update Method A1 progress - mark Homebrew Check and Dependencies as completed:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method A1 Selected]
B --> C[🍺 Homebrew Check]
C --> D[📦 Install Dependencies]
D --> E[⚙️ MCP Setup]
E --> F[🚀 Ready for WebSocket]
class A,B,C,D completed
class E current
class F pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
```
### Step A1.2: MCP Setup via Homebrew Method
**🎯 Project is already cloned and open in Cursor IDE**
1. **Verify project structure**:
```bash
# Verify current directory (should already be in cursor-talk-to-figma-mcp)
pwd | grep "cursor-talk-to-figma-mcp" && echo "✅ Correct directory" || echo "❌ ERROR: Wrong directory"
# Verify project structure
ls package.json src && echo "✅ Project structure valid" || echo "❌ ERROR: Invalid project structure"
# Install dependencies and setup
bun install
bun run build
# Run setup (this configures MCP automatically)
bun setup && echo "✅ Setup complete" || echo "❌ ERROR: Setup failed"
# Verify MCP config was created
test -f .cursor/mcp.json && echo "✅ MCP config created" || echo "❌ ERROR: MCP config missing"
```
**AI AGENTS**: Update progress after Method A1 completion:
```
CHECKPOINT 3: METHOD A1 COMPLETE
Method A1 fully completed, ready for common steps:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method A1 Selected]
B --> C[🍺 Homebrew Check]
C --> D[📦 Install Dependencies]
D --> E[⚙️ MCP Setup]
E --> F[🚀 Ready for WebSocket]
class A,B,C,D,E,F completed
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
```
Progress: Method A1 100% Complete ✅ - Proceeding to Common Steps
```
**Continue to Common Steps below.**
---
## 🔧 Method A2: Direct Installation
### 📊 Progress Tracking for Method A2
**AI AGENTS**: Start by creating Method A2 progress diagram:
```
CHECKPOINT 1: STARTING METHOD A2 - DIRECT INSTALLATION
Please create the Method A2 progress tracking diagram:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method A2 Selected]
B --> C[⚡ Install Bun Direct]
C --> D[⚙️ MCP Setup]
D --> E[🚀 Ready for WebSocket]
class A completed
class B current
class C,D,E pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
```
### Prerequisites Check for Method A2
```bash
# Verify we have sudo access but no Homebrew
[ "$SUDO_AVAILABLE" = "YES" ] && echo "✅ Sudo access confirmed" || exit 1
[ "$HOMEBREW_AVAILABLE" = "NO" ] && echo "✅ Direct installation path confirmed" || echo "⚠️ Homebrew available, consider Method A1"
```
### Step A2.1: Install Bun Directly
```bash
# Install Bun directly (requires internet access)
curl -fsSL https://bun.sh/install | bash
# Reload shell environment
if [[ "$SHELL" == *"zsh"* ]]; then
source ~/.zshrc 2>/dev/null || echo "⚠️ No .zshrc found"
echo "🐚 Using Zsh shell"
elif [[ "$SHELL" == *"bash"* ]]; then
source ~/.bashrc 2>/dev/null || source ~/.bash_profile 2>/dev/null || echo "⚠️ No .bashrc or .bash_profile found"
echo "🐚 Using Bash shell"
fi
# Verify installation
bun --version && echo "✅ Bun installed successfully" || echo "❌ ERROR: Bun installation failed"
BUN_AVAILABLE="YES"
BUN_VERSION=$(bun --version)
```
**AI AGENTS**: Update progress after Bun installation:
```
CHECKPOINT 2: BUN INSTALLED DIRECTLY
Update Method A2 progress - Bun installation completed:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method A2 Selected]
B --> C[⚡ Install Bun Direct]
C --> D[⚙️ MCP Setup]
D --> E[🚀 Ready for WebSocket]
class A,B,C completed
class D current
class E pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
```
### Step A2.2: MCP Setup via Direct Method
**🎯 Project is already cloned and open in Cursor IDE**
1. **Verify project setup**:
```bash
# Verify current directory (should already be in cursor-talk-to-figma-mcp)
pwd | grep "cursor-talk-to-figma-mcp" && echo "✅ Correct directory" || echo "❌ ERROR: Wrong directory"
# Verify and setup
ls package.json src && echo "✅ Project structure valid" || echo "❌ ERROR: Invalid project structure"
bun install
bun run build
bun setup && echo "✅ Setup complete" || echo "❌ ERROR: Setup failed"
test -f .cursor/mcp.json && echo "✅ MCP config created" || echo "❌ ERROR: MCP config missing"
```
**AI AGENTS**: Update progress after Method A2 completion:
```
CHECKPOINT 3: METHOD A2 COMPLETE
Method A2 fully completed, ready for common steps:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method A2 Selected]
B --> C[⚡ Install Bun Direct]
C --> D[⚙️ MCP Setup]
D --> E[🚀 Ready for WebSocket]
class A,B,C,D,E completed
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
```
Progress: Method A2 100% Complete ✅ - Proceeding to Common Steps
```
**Continue to Common Steps below.**
---
## 📱 Method B: Cursor-Only Setup
### 📊 Progress Tracking for Method B
**AI AGENTS**: Start by creating Method B progress diagram:
```
CHECKPOINT 1: STARTING METHOD B - CURSOR-ONLY SETUP
Please create the Method B progress tracking diagram:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method B Selected]
B --> C[🖥️ Project Already Open]
C --> D[📖 Setup Dependencies]
D --> E[⚙️ MCP Setup]
E --> F[🚀 Ready for WebSocket]
class A completed
class B current
class C,D,E,F pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
```
### Prerequisites Check for Method B
```bash
# Verify Cursor-only setup conditions
[ "$CURSOR_AVAILABLE" = "YES" ] && echo "✅ Cursor IDE available" || echo "❌ ERROR: Install Cursor IDE first"
[ "$SUDO_AVAILABLE" = "NO" ] && echo "✅ Restricted environment confirmed" || echo "⚠️ Admin access available, consider Method A"
```
### Step B.1: Verify Project is Open in Cursor
**🎯 Project is already cloned and open in Cursor IDE**
1. **Verify project is properly loaded**:
- Confirm Cursor IDE has the project open
- Open terminal in Cursor: `Terminal > New Terminal` (or `Ctrl+Shift+`)
### Step B.2: Setup Dependencies in Cursor
```bash
# Verify current directory (should already be in cursor-talk-to-figma-mcp)
pwd | grep "cursor-talk-to-figma-mcp" && echo "✅ Correct directory" || echo "❌ ERROR: Wrong directory"
# Verify project structure
ls package.json src && echo "✅ Project structure valid" || echo "❌ ERROR: Invalid project structure"
```
**AI AGENTS**: Update progress after project cloning:
```
CHECKPOINT 2: PROJECT CLONED IN CURSOR
Update Method B progress - project cloned successfully:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method B Selected]
B --> C[🖥️ Project Already Open]
C --> D[📖 Setup Dependencies]
D --> E[⚙️ MCP Setup]
E --> F[🚀 Ready for WebSocket]
class A,B,C,D completed
class E current
class F pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
```
### Step B.3: Follow README Setup in Cursor
**📖 CRITICAL FOR AI AGENTS**: Ask the AI assistant in Cursor to read and execute the README:
```
Please read the @readme.md file and help me set up this project by following the installation instructions step by step.
IMPORTANT: For each step in the setup process, please:
1. Create a Mermaid flowchart showing the complete installation process
2. Highlight which step we're currently on
3. Show what steps are completed, current, and upcoming
4. Include brief descriptions of what each step does
5. Update the diagram as we progress through each step
Use this Mermaid template structure:
- Use different colors/styles to show: ✅ Completed, 🔄 Current, ⏳ Upcoming
- Include step numbers and brief descriptions
- Show the flow from Prerequisites → Installation → Configuration → Testing
- Make it visually clear where we are in the process
This will help track overall progress and determine next steps at each stage.
```
**AI AGENTS**: Update progress after Method B completion:
```
CHECKPOINT 3: METHOD B COMPLETE
Method B fully completed, ready for common steps:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method B Selected]
B --> C[🖥️ Project Already Open]
C --> D[📖 Setup Dependencies]
D --> E[⚙️ MCP Setup]
E --> F[🚀 Ready for WebSocket]
class A,B,C,D,E,F completed
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
```
Progress: Method B 100% Complete ✅ - Proceeding to Common Steps
```
**Continue to Common Steps below.**
---
## 🔗 Common Steps (All Methods)
### Step C.1: Verify MCP Configuration
**🚨 CRITICAL FOR AI AGENTS**: Project is already cloned and open in Cursor.
```bash
# Verify current directory (should already be in cursor-talk-to-figma-mcp)
pwd | grep "cursor-talk-to-figma-mcp" && echo "✅ Correct directory" || echo "❌ ERROR: Wrong directory"
# Verify project structure
ls package.json src && echo "✅ Project structure valid" || echo "❌ ERROR: Invalid project structure"
# Verify MCP config exists (created by bun setup)
if [ -f ".cursor/mcp.json" ]; then
echo "✅ MCP config found"
else
echo "⚠️ MCP config not found - running setup..."
bun setup
fi
echo "✅ Project verified - MCP should be configured"
```
**CHECKPOINT C.1**: Verify in Cursor:
1. Open Settings (`Cmd+,` on Mac, `Ctrl+,` on Windows/Linux)
2. Search "MCP"
3. Confirm "TalkToFigma" shows as "Connected"
**AI AGENTS**: Update overall progress after Cursor launch:
```
CHECKPOINT 3: MCP SETUP AND CONFIGURATION COMPLETE
Update overall progress - MCP setup and configured:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method Selection]
B --> C[⚡ Dependency Installation]
C --> D[⚙️ MCP setup and configuration]
D --> E[🌐 WebSocket Server]
E --> F[🔌 Figma Plugin]
F --> G[🧪 Integration Test]
G --> H[✅ Setup Complete]
class A,B,C,D completed
class E current
class F,G,H pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
Progress: 50% Complete - MCP Configured ✅ - Starting WebSocket Server
```
### Step C.2: Start WebSocket Server
To ensure stability and easy monitoring, we will run the WebSocket server in the foreground. This is the recommended method as it dedicates a terminal to the server, confirming it's always running, and saves all logs to a file for later review.
**How to Start and Monitor the Server:**
1. **Start the Server**: Open a new terminal in Cursor and run the following command. The terminal will become unresponsive, which means the server is running correctly.
```bash
# Runs the server in the foreground and saves all logs to websocket.log
bun socket > websocket.log 2>&1
```
2. **Monitor Logs**: To see server activity, open a *second* terminal and use this command for a live feed of the logs:
```bash
tail -f websocket.log
```
You can also simply open the `websocket.log` file to view its contents.
3. **Stop the Server**: To stop the server, go to its dedicated terminal window and press `Ctrl + C`.
**CHECKPOINT C.2**: The server terminal should be active (and unresponsive). You should see a "WebSocket server running on port 3055" message at the beginning of the `websocket.log` file. **Keep the server terminal open.**
### 🔍 Verify WebSocket Server Status
**🚨 CRITICAL FOR AI AGENTS**: Use Cursor's `@Terminals` to monitor WebSocket server status:
1. **Check Active Terminals**:
- In Cursor, type `@Terminals` in chat
- This will show all currently running terminal processes
- Verify you can see the WebSocket server terminal running
- Confirm the server shows "WebSocket server running on port 3055" message
2. **Verify Server is Active**:
```bash
# In a new terminal (don't close the WebSocket terminal!)
curl -I http://localhost:3055 2>/dev/null && echo "✅ WebSocket server responding" || echo "❌ Server not responding"
# Check port status
lsof -i :3055 && echo "✅ Port 3055 in use by WebSocket server" || echo "❌ Port 3055 not in use"
```
3. **Monitor Server Logs**:
- Keep the WebSocket terminal visible in Cursor
- Watch for connection messages when Figma plugin connects
- Server logs will show plugin connection status in real-time
**⚠️ IMPORTANT**: Do NOT close the WebSocket terminal - it must stay running throughout the entire Figma integration session.
**AI AGENTS**: Update progress after WebSocket server start:
```
CHECKPOINT 4: WEBSOCKET SERVER RUNNING
Update progress - WebSocket server successfully started:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method Selection]
B --> C[⚡ Dependency Installation]
C --> D[⚙️ MCP setup and configuration]
D --> E[🌐 WebSocket Server]
E --> F[🔌 Figma Plugin]
F --> G[🧪 Integration Test]
G --> H[✅ Setup Complete]
class A,B,C,D,E completed
class F current
class G,H pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
Progress: 63% Complete - WebSocket Running ✅ - Installing Figma Plugin
```
### Step C.3: Install and Configure Figma Plugin
#### 🔌 Install the Community Plugin
1. **Open the Plugin Page**:
- Navigate to: https://www.figma.com/community/plugin/1485687494525374295/cursor-talk-to-figma-mcp-plugin
- Click **"Install"** to add the plugin to your Figma account
2. **Open Figma and Run the Plugin**:
- Open any Figma file (or create a new one)
- Go to `Plugins` menu → `Cursor Talk to Figma MCP Plugin`
- The plugin panel will open
#### ⚙️ Configure Plugin to Connect to Local WebSocket
**🚨 CRITICAL**: The plugin needs to connect to your local WebSocket server:
1. **In the Plugin Panel**:
- Look for **"WebSocket URL"** or **"Server URL"** setting
- Change the URL from default to: `ws://localhost:3055`
- Click **"Connect"** or **"Save"** to apply the setting
2. **Verify Connection**:
- The plugin should show **"Connected"** status
- You should see green indicator or success message in the plugin
#### 📡 Monitor Connection Status Using @Terminals
**🔍 IMPORTANT FOR AI AGENTS**: Use Cursor's `@Terminals` to verify the plugin connection:
1. **Check WebSocket Server Logs**:
- In Cursor, type `@Terminals` in chat
- Look at the WebSocket server terminal
- When plugin connects successfully, you should see log messages like:
```
✅ New WebSocket connection from Figma plugin
✅ Plugin connected successfully
✅ Handshake completed
```
2. **Connection Troubleshooting**:
- If no connection messages appear in server logs, the plugin is not connecting properly
- Check that WebSocket URL in plugin is set to `ws://localhost:3055`
- Verify the WebSocket server is still running (check `@Terminals`)
- Try refreshing the Figma page and reconnecting the plugin
**AI AGENTS**: Update progress after Figma plugin installation:
```
CHECKPOINT 5: FIGMA PLUGIN INSTALLED
Update progress - Figma plugin successfully installed:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method Selection]
B --> C[⚡ Dependency Installation]
C --> D[⚙️ MCP setup and configuration]
D --> E[🌐 WebSocket Server]
E --> F[🔌 Figma Plugin]
F --> G[🧪 Integration Test]
G --> H[✅ Setup Complete]
class A,B,C,D,E,F completed
class G current
class H pending
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
classDef current fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff
classDef pending fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
```
Progress: 75% Complete - Plugin Installed ✅ - Running Integration Tests
```
### Step C.4: Test Integration
#### 🧪 Test MCP Commands in Cursor
**In Cursor (where MCP is connected):**
```bash
# Test 1: MCP Connection
join_channel
# Expected: "Successfully joined channel" message
# Test 2: Figma Communication
get_document_info
# Expected: JSON data from Figma document
```
#### 📋 Verify Complete Integration Using @Terminals
**🔍 FINAL VERIFICATION FOR AI AGENTS**:
1. **Check All Active Processes**:
- In Cursor, type `@Terminals` in chat
- Verify you can see:
- ✅ **WebSocket server terminal** still running with "WebSocket server running on port 3055"
- ✅ **Connection logs** showing Figma plugin is connected
- ✅ **MCP status** showing TalkToFigma as connected
2. **Test End-to-End Communication**:
```bash
# In Cursor chat, test these MCP commands:
get_document_info
get_selection
```
- Commands should return JSON data from your Figma document
- Check `@Terminals` - WebSocket logs should show command activity
- Figma plugin should show activity/response indicators
3. **Integration Status Checklist**:
- ✅ WebSocket server running (visible in `@Terminals`)
- ✅ Figma plugin connected (connection logs in server terminal)
- ✅ MCP commands working (returns Figma data)
- ✅ No error messages in any terminals
**CHECKPOINT C.4**: All tests must pass and `@Terminals` should show healthy connections for successful setup.
**AI AGENTS**: Update progress after successful integration test:
```
CHECKPOINT 6: SETUP COMPLETE - INTEGRATION SUCCESSFUL
🎉 FINAL STATUS - All components working perfectly:
```mermaid
graph TD
A[🔍 Environment Detection] --> B[📦 Method Selection]
B --> C[⚡ Dependency Installation]
C --> D[⚙️ MCP setup and configuration]
D --> E[🌐 WebSocket Server]
E --> F[🔌 Figma Plugin]
F --> G[🧪 Integration Test]
G --> H[✅ Setup Complete]
class A,B,C,D,E,F,G,H completed
classDef completed fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
```
🎯 **FINAL RESULT**: 100% Complete ✅
- ✅ Environment Detection Complete
- ✅ Method Successfully Executed
- ✅ Dependencies Installed
- ✅ Project Cloned & Configured
- ✅ MCP Connected
- ✅ WebSocket Server Running
- ✅ Figma Plugin Active
- ✅ Integration Tests Passed
- ✅ **READY TO USE!**
**🚀 AI Agent can now assist with Figma design tasks through Cursor!**
```
---
## 🔍 AI Agent Troubleshooting Decision Tree
### Issue: Prerequisites Failed
```bash
# Decision tree for prerequisite failures
if [ "$CURSOR_AVAILABLE" = "NO" ]; then
echo "❌ CRITICAL: Install Cursor IDE first - https://cursor.sh/"
exit 1
elif [ "$GIT_AVAILABLE" = "NO" ]; then
echo "❌ CRITICAL: Install Git first"
exit 1
else
echo "✅ Prerequisites satisfied, continue setup"
fi
```
### Issue: MCP Not Connected
```bash
# AI Agent debugging steps
echo "🔍 Debugging MCP connection..."
# Check if in correct project directory
if [ ! -f "package.json" ] || [ ! -d "src" ]; then
echo "❌ Not in project directory"
echo "💡 Please ensure you're in the cloned cursor-talk-to-figma-mcp directory"
echo "💡 Use Cursor's File > Open Folder to open the cloned project"
exit 1
fi
# Check if MCP config exists
if [ ! -f ".cursor/mcp.json" ]; then
echo "⚠️ MCP config missing - running setup..."
bun setup
fi
# Restart Cursor if needed
echo "💡 Restarting Cursor to reload MCP configuration..."
cursor .
sleep 5
```
### Issue: WebSocket Connection Failed
```bash
# AI Agent network debugging
echo "🔍 Debugging WebSocket connection..."
# Step 1: Use @Terminals to check current state
echo "💡 First, type '@Terminals' in Cursor chat to see all running processes"
echo "💡 Look for WebSocket server terminal and check its status"
# Check if port is in use
if lsof -i :3055 >/dev/null 2>&1; then
echo "⚠️ Port 3055 in use, killing existing process"
lsof -ti:3055 | xargs kill -9 2>/dev/null || true
sleep 2
fi
# Restart WebSocket server based on available runtime
if [ "$BUN_AVAILABLE" = "YES" ]; then
echo "🚀 Starting WebSocket server with Bun..."
bun socket
elif [ "$NODE_AVAILABLE" = "YES" ]; then
echo "🚀 Starting WebSocket server with Node..."
npm run socket || npx bun socket
else
echo "❌ No suitable runtime for WebSocket server"
exit 1
fi
echo "💡 After starting server, use '@Terminals' again to verify it's running"
echo "💡 Look for 'WebSocket server running on port 3055' message"
```
### Issue: Figma Plugin Not Connecting
```bash
# AI Agent plugin debugging
echo "🔍 Debugging Figma plugin connection..."
echo "💡 Use '@Terminals' in Cursor to check WebSocket server logs"
echo "💡 You should see connection attempts from Figma plugin"
# Common plugin connection issues:
echo "🔧 Plugin Connection Checklist:"
echo "1. Plugin WebSocket URL set to 'ws://localhost:3055'"
echo "2. WebSocket server running (check '@Terminals')"
echo "3. Figma plugin installed and activated"
echo "4. No firewall blocking localhost:3055"
echo "💡 In Figma plugin panel:"
echo "- Verify connection URL is 'ws://localhost:3055'"
echo "- Click disconnect/reconnect if needed"
echo "- Check for error messages in plugin"
echo "💡 Monitor '@Terminals' for real-time connection logs"
```
### Issue: Runtime Not Found
```bash
# AI Agent runtime fallback logic
echo "🔍 Attempting runtime fallback..."
if [ "$HOMEBREW_AVAILABLE" = "YES" ] && [ "$SUDO_AVAILABLE" = "YES" ]; then
echo "Installing missing runtime via Homebrew..."
brew install bun node
elif [ "$SUDO_AVAILABLE" = "YES" ]; then
echo "Installing Bun directly..."
curl -fsSL https://bun.sh/install | bash
source ~/.zshrc 2>/dev/null || source ~/.bashrc 2>/dev/null || true
else
echo "❌ Cannot install runtime in restricted environment"
echo "💡 Try Method B: Cursor-Only Setup"
exit 1
fi
```
---
## ✅ AI Agent Success Verification Matrix
**AI Agents should verify ALL conditions before marking setup as complete:**
### Environment Verification
```bash
echo "=== FINAL VERIFICATION MATRIX ==="
# System Environment
[ "$OS_TYPE" != "" ] && echo "✅ OS Detection: $OS_TYPE" || echo "❌ OS Detection Failed"
# Required Tools
[ "$CURSOR_AVAILABLE" = "YES" ] && echo "✅ Cursor IDE Available" || echo "❌ Cursor Missing"
[ "$GIT_AVAILABLE" = "YES" ] && echo "✅ Git Available" || echo "❌ Git Missing"
# Runtime Environment
if [ "$BUN_AVAILABLE" = "YES" ]; then
echo "✅ Bun Runtime: $BUN_VERSION"
elif [ "$NODE_AVAILABLE" = "YES" ]; then
echo "✅ Node.js Runtime: $NODE_VERSION"
else
echo "❌ No Suitable Runtime Found"
fi
# Project Setup
[ -f ".cursor/mcp.json" ] && echo "✅ MCP Config Present" || echo "❌ MCP Config Missing"
[ -f "package.json" ] && echo "✅ Project Structure Valid" || echo "❌ Invalid Project"
# Process Status
if lsof -i :3055 >/dev/null 2>&1; then
echo "✅ WebSocket Server Running (Port 3055)"
else
echo "❌ WebSocket Server Not Running"
fi
```
### Functional Verification
**Execute in Cursor with MCP connected:**
1. **MCP Connection Test**: `join_channel` → Should return success message
2. **Figma Communication Test**: `get_document_info` → Should return JSON data
3. **Plugin Status**: Figma plugin should show as connected
### 🎉 Success Criteria
**ALL of the following must be true:**
- ✅ Environment detection completed without errors
- ✅ Appropriate method selected and executed based on system capabilities
- ✅ Project successfully cloned and configured
- ✅ MCP configuration file present and valid
- ✅ Cursor IDE launched from project directory
- ✅ MCP shows "TalkToFigma" as "Connected" in settings
- ✅ WebSocket server running on port 3055 (verified via `@Terminals`)
- ✅ Figma plugin installed, configured with `ws://localhost:3055`, and connected
- ✅ Plugin connection visible in WebSocket server logs (check `@Terminals`)
- ✅ `join_channel` command works in Cursor
- ✅ `get_document_info` returns Figma document data
- ✅ All processes healthy and running (verified via `@Terminals`)
**If any criterion fails, AI agents should follow the troubleshooting decision tree above.**
---
## 🚀 AI Agent Quick Commands
### Recommended Setup (Use Cursor's Built-in Git Clone)
**AI AGENTS**: Instead of terminal commands, guide users to:
1. **Open Cursor IDE**
2. **Clone Repository**: Use `Cmd+Shift+P` → "Git: Clone"
3. **Enter URL**: `https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp.git`
4. **Select location and clone**
5. **Open cloned project in Cursor**
6. **Run setup**: `bun setup`
### Alternative One-Line Commands (For Advanced Users)
```bash
# Method A1 (Homebrew) - Clone and auto-open in Cursor
[ "$HOMEBREW_AVAILABLE" = "YES" ] && cd ~/Desktop && git clone https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp.git && cd cursor-talk-to-figma-mcp && brew install bun && bun setup && cursor .
# Method A2 (Direct) - Clone and auto-open in Cursor
[ "$SUDO_AVAILABLE" = "YES" ] && cd ~/Desktop && git clone https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp.git && cd cursor-talk-to-figma-mcp && curl -fsSL https://bun.sh/install | bash && source ~/.zshrc && bun setup && cursor .
# Method B (Cursor-only) - Clone and open manually
[ "$CURSOR_AVAILABLE" = "YES" ] && cd ~/Desktop && git clone https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp.git && echo "✅ Project cloned to ~/Desktop/cursor-talk-to-figma-mcp" && echo "💡 Open this folder in Cursor and run 'bun setup'"
```
### Service Management
```bash
# Start WebSocket Server (background)
nohup bun socket > websocket.log 2>&1 & echo $! > websocket.pid
# Stop WebSocket Server
[ -f websocket.pid ] && kill $(cat websocket.pid) && rm websocket.pid
# Check Service Status
ps aux | grep -E "(bun socket|node.*socket)" || echo "WebSocket server not running"
```
### 📊 Monitor Services Using @Terminals
**🔍 RECOMMENDED FOR AI AGENTS**: Use Cursor's `@Terminals` for real-time monitoring:
1. **Check Active Services**:
- Type `@Terminals` in Cursor chat anytime
- Instantly see all running terminal processes
- Verify WebSocket server status without additional commands
2. **Real-time Connection Monitoring**:
- Watch WebSocket server logs for Figma plugin connections
- See MCP command activity in real-time
- Monitor for errors or disconnections
3. **Quick Health Check**:
- `@Terminals` shows if WebSocket server is still running
- Displays connection status and recent activity
- No need for additional terminal commands
**Remember**: Always keep the WebSocket server running for the Figma plugin to communicate with Cursor! Use `@Terminals` to monitor its health.
```
--------------------------------------------------------------------------------
/src/talk_to_figma_mcp/server.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import WebSocket from "ws";
import { v4 as uuidv4 } from "uuid";
// Define TypeScript interfaces for Figma responses
interface FigmaResponse {
id: string;
result?: any;
error?: string;
}
// Define interface for command progress updates
interface CommandProgressUpdate {
type: 'command_progress';
commandId: string;
commandType: string;
status: 'started' | 'in_progress' | 'completed' | 'error';
progress: number;
totalItems: number;
processedItems: number;
currentChunk?: number;
totalChunks?: number;
chunkSize?: number;
message: string;
payload?: any;
timestamp: number;
}
// Update the getInstanceOverridesResult interface to match the plugin implementation
interface getInstanceOverridesResult {
success: boolean;
message: string;
sourceInstanceId: string;
mainComponentId: string;
overridesCount: number;
}
interface setInstanceOverridesResult {
success: boolean;
message: string;
totalCount?: number;
results?: Array<{
success: boolean;
instanceId: string;
instanceName: string;
appliedCount?: number;
message?: string;
}>;
}
// Custom logging functions that write to stderr instead of stdout to avoid being captured
const logger = {
info: (message: string) => process.stderr.write(`[INFO] ${message}\n`),
debug: (message: string) => process.stderr.write(`[DEBUG] ${message}\n`),
warn: (message: string) => process.stderr.write(`[WARN] ${message}\n`),
error: (message: string) => process.stderr.write(`[ERROR] ${message}\n`),
log: (message: string) => process.stderr.write(`[LOG] ${message}\n`)
};
// WebSocket connection and request tracking
let ws: WebSocket | null = null;
const pendingRequests = new Map<string, {
resolve: (value: unknown) => void;
reject: (reason: unknown) => void;
timeout: ReturnType<typeof setTimeout>;
lastActivity: number; // Add timestamp for last activity
}>();
// Track which channel each client is in
let currentChannel: string | null = null;
// Create MCP server
const server = new McpServer({
name: "TalkToFigmaMCP",
version: "1.0.0",
});
// Add command line argument parsing
const args = process.argv.slice(2);
const serverArg = args.find(arg => arg.startsWith('--server='));
const serverUrl = serverArg ? serverArg.split('=')[1] : 'localhost';
const WS_URL = serverUrl === 'localhost' ? `ws://${serverUrl}` : `wss://${serverUrl}`;
// Document Info Tool
server.tool(
"get_document_info",
"Get detailed information about the current Figma document",
{},
async () => {
try {
const result = await sendCommandToFigma("get_document_info");
return {
content: [
{
type: "text",
text: JSON.stringify(result)
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting document info: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Selection Tool
server.tool(
"get_selection",
"Get information about the current selection in Figma",
{},
async () => {
try {
const result = await sendCommandToFigma("get_selection");
return {
content: [
{
type: "text",
text: JSON.stringify(result)
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting selection: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Read My Design Tool
server.tool(
"read_my_design",
"Get detailed information about the current selection in Figma, including all node details",
{},
async () => {
try {
const result = await sendCommandToFigma("read_my_design", {});
return {
content: [
{
type: "text",
text: JSON.stringify(result)
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting node info: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Node Info Tool
server.tool(
"get_node_info",
"Get detailed information about a specific node in Figma",
{
nodeId: z.string().describe("The ID of the node to get information about"),
},
async ({ nodeId }: any) => {
try {
const result = await sendCommandToFigma("get_node_info", { nodeId });
return {
content: [
{
type: "text",
text: JSON.stringify(filterFigmaNode(result))
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting node info: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
function rgbaToHex(color: any): string {
// skip if color is already hex
if (color.startsWith('#')) {
return color;
}
const r = Math.round(color.r * 255);
const g = Math.round(color.g * 255);
const b = Math.round(color.b * 255);
const a = Math.round(color.a * 255);
return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}${a === 255 ? '' : a.toString(16).padStart(2, '0')}`;
}
function filterFigmaNode(node: any) {
// Skip VECTOR type nodes
if (node.type === "VECTOR") {
return null;
}
const filtered: any = {
id: node.id,
name: node.name,
type: node.type,
};
if (node.fills && node.fills.length > 0) {
filtered.fills = node.fills.map((fill: any) => {
const processedFill = { ...fill };
// Remove boundVariables and imageRef
delete processedFill.boundVariables;
delete processedFill.imageRef;
// Process gradientStops if present
if (processedFill.gradientStops) {
processedFill.gradientStops = processedFill.gradientStops.map((stop: any) => {
const processedStop = { ...stop };
// Convert color to hex if present
if (processedStop.color) {
processedStop.color = rgbaToHex(processedStop.color);
}
// Remove boundVariables
delete processedStop.boundVariables;
return processedStop;
});
}
// Convert solid fill colors to hex
if (processedFill.color) {
processedFill.color = rgbaToHex(processedFill.color);
}
return processedFill;
});
}
if (node.strokes && node.strokes.length > 0) {
filtered.strokes = node.strokes.map((stroke: any) => {
const processedStroke = { ...stroke };
// Remove boundVariables
delete processedStroke.boundVariables;
// Convert color to hex if present
if (processedStroke.color) {
processedStroke.color = rgbaToHex(processedStroke.color);
}
return processedStroke;
});
}
if (node.cornerRadius !== undefined) {
filtered.cornerRadius = node.cornerRadius;
}
if (node.absoluteBoundingBox) {
filtered.absoluteBoundingBox = node.absoluteBoundingBox;
}
if (node.characters) {
filtered.characters = node.characters;
}
if (node.style) {
filtered.style = {
fontFamily: node.style.fontFamily,
fontStyle: node.style.fontStyle,
fontWeight: node.style.fontWeight,
fontSize: node.style.fontSize,
textAlignHorizontal: node.style.textAlignHorizontal,
letterSpacing: node.style.letterSpacing,
lineHeightPx: node.style.lineHeightPx
};
}
if (node.children) {
filtered.children = node.children
.map((child: any) => filterFigmaNode(child))
.filter((child: any) => child !== null); // Remove null children (VECTOR nodes)
}
return filtered;
}
// Nodes Info Tool
server.tool(
"get_nodes_info",
"Get detailed information about multiple nodes in Figma",
{
nodeIds: z.array(z.string()).describe("Array of node IDs to get information about")
},
async ({ nodeIds }: any) => {
try {
const results = await Promise.all(
nodeIds.map(async (nodeId: any) => {
const result = await sendCommandToFigma('get_node_info', { nodeId });
return { nodeId, info: result };
})
);
return {
content: [
{
type: "text",
text: JSON.stringify(results.map((result) => filterFigmaNode(result.info)))
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting nodes info: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Create Rectangle Tool
server.tool(
"create_rectangle",
"Create a new rectangle in Figma",
{
x: z.number().describe("X position"),
y: z.number().describe("Y position"),
width: z.number().describe("Width of the rectangle"),
height: z.number().describe("Height of the rectangle"),
name: z.string().optional().describe("Optional name for the rectangle"),
parentId: z
.string()
.optional()
.describe("Optional parent node ID to append the rectangle to"),
},
async ({ x, y, width, height, name, parentId }: any) => {
try {
const result = await sendCommandToFigma("create_rectangle", {
x,
y,
width,
height,
name: name || "Rectangle",
parentId,
});
return {
content: [
{
type: "text",
text: `Created rectangle "${JSON.stringify(result)}"`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error creating rectangle: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Create Frame Tool
server.tool(
"create_frame",
"Create a new frame in Figma",
{
x: z.number().describe("X position"),
y: z.number().describe("Y position"),
width: z.number().describe("Width of the frame"),
height: z.number().describe("Height of the frame"),
name: z.string().optional().describe("Optional name for the frame"),
parentId: z
.string()
.optional()
.describe("Optional parent node ID to append the frame to"),
fillColor: z
.object({
r: z.number().min(0).max(1).describe("Red component (0-1)"),
g: z.number().min(0).max(1).describe("Green component (0-1)"),
b: z.number().min(0).max(1).describe("Blue component (0-1)"),
a: z
.number()
.min(0)
.max(1)
.optional()
.describe("Alpha component (0-1)"),
})
.optional()
.describe("Fill color in RGBA format"),
strokeColor: z
.object({
r: z.number().min(0).max(1).describe("Red component (0-1)"),
g: z.number().min(0).max(1).describe("Green component (0-1)"),
b: z.number().min(0).max(1).describe("Blue component (0-1)"),
a: z
.number()
.min(0)
.max(1)
.optional()
.describe("Alpha component (0-1)"),
})
.optional()
.describe("Stroke color in RGBA format"),
strokeWeight: z.number().positive().optional().describe("Stroke weight"),
layoutMode: z.enum(["NONE", "HORIZONTAL", "VERTICAL"]).optional().describe("Auto-layout mode for the frame"),
layoutWrap: z.enum(["NO_WRAP", "WRAP"]).optional().describe("Whether the auto-layout frame wraps its children"),
paddingTop: z.number().optional().describe("Top padding for auto-layout frame"),
paddingRight: z.number().optional().describe("Right padding for auto-layout frame"),
paddingBottom: z.number().optional().describe("Bottom padding for auto-layout frame"),
paddingLeft: z.number().optional().describe("Left padding for auto-layout frame"),
primaryAxisAlignItems: z
.enum(["MIN", "MAX", "CENTER", "SPACE_BETWEEN"])
.optional()
.describe("Primary axis alignment for auto-layout frame. Note: When set to SPACE_BETWEEN, itemSpacing will be ignored as children will be evenly spaced."),
counterAxisAlignItems: z.enum(["MIN", "MAX", "CENTER", "BASELINE"]).optional().describe("Counter axis alignment for auto-layout frame"),
layoutSizingHorizontal: z.enum(["FIXED", "HUG", "FILL"]).optional().describe("Horizontal sizing mode for auto-layout frame"),
layoutSizingVertical: z.enum(["FIXED", "HUG", "FILL"]).optional().describe("Vertical sizing mode for auto-layout frame"),
itemSpacing: z
.number()
.optional()
.describe("Distance between children in auto-layout frame. Note: This value will be ignored if primaryAxisAlignItems is set to SPACE_BETWEEN.")
},
async ({
x,
y,
width,
height,
name,
parentId,
fillColor,
strokeColor,
strokeWeight,
layoutMode,
layoutWrap,
paddingTop,
paddingRight,
paddingBottom,
paddingLeft,
primaryAxisAlignItems,
counterAxisAlignItems,
layoutSizingHorizontal,
layoutSizingVertical,
itemSpacing
}: any) => {
try {
const result = await sendCommandToFigma("create_frame", {
x,
y,
width,
height,
name: name || "Frame",
parentId,
fillColor: fillColor || { r: 1, g: 1, b: 1, a: 1 },
strokeColor: strokeColor,
strokeWeight: strokeWeight,
layoutMode,
layoutWrap,
paddingTop,
paddingRight,
paddingBottom,
paddingLeft,
primaryAxisAlignItems,
counterAxisAlignItems,
layoutSizingHorizontal,
layoutSizingVertical,
itemSpacing
});
const typedResult = result as { name: string; id: string };
return {
content: [
{
type: "text",
text: `Created frame "${typedResult.name}" with ID: ${typedResult.id}. Use the ID as the parentId to appendChild inside this frame.`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error creating frame: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Create Text Tool
server.tool(
"create_text",
"Create a new text element in Figma",
{
x: z.number().describe("X position"),
y: z.number().describe("Y position"),
text: z.string().describe("Text content"),
fontSize: z.number().optional().describe("Font size (default: 14)"),
fontWeight: z
.number()
.optional()
.describe("Font weight (e.g., 400 for Regular, 700 for Bold)"),
fontColor: z
.object({
r: z.number().min(0).max(1).describe("Red component (0-1)"),
g: z.number().min(0).max(1).describe("Green component (0-1)"),
b: z.number().min(0).max(1).describe("Blue component (0-1)"),
a: z
.number()
.min(0)
.max(1)
.optional()
.describe("Alpha component (0-1)"),
})
.optional()
.describe("Font color in RGBA format"),
name: z
.string()
.optional()
.describe("Semantic layer name for the text node"),
parentId: z
.string()
.optional()
.describe("Optional parent node ID to append the text to"),
},
async ({ x, y, text, fontSize, fontWeight, fontColor, name, parentId }: any) => {
try {
const result = await sendCommandToFigma("create_text", {
x,
y,
text,
fontSize: fontSize || 14,
fontWeight: fontWeight || 400,
fontColor: fontColor || { r: 0, g: 0, b: 0, a: 1 },
name: name || "Text",
parentId,
});
const typedResult = result as { name: string; id: string };
return {
content: [
{
type: "text",
text: `Created text "${typedResult.name}" with ID: ${typedResult.id}`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error creating text: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Set Fill Color Tool
server.tool(
"set_fill_color",
"Set the fill color of a node in Figma can be TextNode or FrameNode",
{
nodeId: z.string().describe("The ID of the node to modify"),
r: z.number().min(0).max(1).describe("Red component (0-1)"),
g: z.number().min(0).max(1).describe("Green component (0-1)"),
b: z.number().min(0).max(1).describe("Blue component (0-1)"),
a: z.number().min(0).max(1).optional().describe("Alpha component (0-1)"),
},
async ({ nodeId, r, g, b, a }: any) => {
try {
const result = await sendCommandToFigma("set_fill_color", {
nodeId,
color: { r, g, b, a: a || 1 },
});
const typedResult = result as { name: string };
return {
content: [
{
type: "text",
text: `Set fill color of node "${typedResult.name
}" to RGBA(${r}, ${g}, ${b}, ${a || 1})`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting fill color: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Set Stroke Color Tool
server.tool(
"set_stroke_color",
"Set the stroke color of a node in Figma",
{
nodeId: z.string().describe("The ID of the node to modify"),
r: z.number().min(0).max(1).describe("Red component (0-1)"),
g: z.number().min(0).max(1).describe("Green component (0-1)"),
b: z.number().min(0).max(1).describe("Blue component (0-1)"),
a: z.number().min(0).max(1).optional().describe("Alpha component (0-1)"),
weight: z.number().positive().optional().describe("Stroke weight"),
},
async ({ nodeId, r, g, b, a, weight }: any) => {
try {
const result = await sendCommandToFigma("set_stroke_color", {
nodeId,
color: { r, g, b, a: a || 1 },
weight: weight || 1,
});
const typedResult = result as { name: string };
return {
content: [
{
type: "text",
text: `Set stroke color of node "${typedResult.name
}" to RGBA(${r}, ${g}, ${b}, ${a || 1}) with weight ${weight || 1}`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting stroke color: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Move Node Tool
server.tool(
"move_node",
"Move a node to a new position in Figma",
{
nodeId: z.string().describe("The ID of the node to move"),
x: z.number().describe("New X position"),
y: z.number().describe("New Y position"),
},
async ({ nodeId, x, y }: any) => {
try {
const result = await sendCommandToFigma("move_node", { nodeId, x, y });
const typedResult = result as { name: string };
return {
content: [
{
type: "text",
text: `Moved node "${typedResult.name}" to position (${x}, ${y})`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error moving node: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Clone Node Tool
server.tool(
"clone_node",
"Clone an existing node in Figma",
{
nodeId: z.string().describe("The ID of the node to clone"),
x: z.number().optional().describe("New X position for the clone"),
y: z.number().optional().describe("New Y position for the clone")
},
async ({ nodeId, x, y }: any) => {
try {
const result = await sendCommandToFigma('clone_node', { nodeId, x, y });
const typedResult = result as { name: string, id: string };
return {
content: [
{
type: "text",
text: `Cloned node "${typedResult.name}" with new ID: ${typedResult.id}${x !== undefined && y !== undefined ? ` at position (${x}, ${y})` : ''}`
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error cloning node: ${error instanceof Error ? error.message : String(error)}`
}
]
};
}
}
);
// Resize Node Tool
server.tool(
"resize_node",
"Resize a node in Figma",
{
nodeId: z.string().describe("The ID of the node to resize"),
width: z.number().positive().describe("New width"),
height: z.number().positive().describe("New height"),
},
async ({ nodeId, width, height }: any) => {
try {
const result = await sendCommandToFigma("resize_node", {
nodeId,
width,
height,
});
const typedResult = result as { name: string };
return {
content: [
{
type: "text",
text: `Resized node "${typedResult.name}" to width ${width} and height ${height}`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error resizing node: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Delete Node Tool
server.tool(
"delete_node",
"Delete a node from Figma",
{
nodeId: z.string().describe("The ID of the node to delete"),
},
async ({ nodeId }: any) => {
try {
await sendCommandToFigma("delete_node", { nodeId });
return {
content: [
{
type: "text",
text: `Deleted node with ID: ${nodeId}`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error deleting node: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Delete Multiple Nodes Tool
server.tool(
"delete_multiple_nodes",
"Delete multiple nodes from Figma at once",
{
nodeIds: z.array(z.string()).describe("Array of node IDs to delete"),
},
async ({ nodeIds }: any) => {
try {
const result = await sendCommandToFigma("delete_multiple_nodes", { nodeIds });
return {
content: [
{
type: "text",
text: JSON.stringify(result)
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error deleting multiple nodes: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Export Node as Image Tool
server.tool(
"export_node_as_image",
"Export a node as an image from Figma",
{
nodeId: z.string().describe("The ID of the node to export"),
format: z
.enum(["PNG", "JPG", "SVG", "PDF"])
.optional()
.describe("Export format"),
scale: z.number().positive().optional().describe("Export scale"),
},
async ({ nodeId, format, scale }: any) => {
try {
const result = await sendCommandToFigma("export_node_as_image", {
nodeId,
format: format || "PNG",
scale: scale || 1,
});
const typedResult = result as { imageData: string; mimeType: string };
return {
content: [
{
type: "image",
data: typedResult.imageData,
mimeType: typedResult.mimeType || "image/png",
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error exporting node as image: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Set Text Content Tool
server.tool(
"set_text_content",
"Set the text content of an existing text node in Figma",
{
nodeId: z.string().describe("The ID of the text node to modify"),
text: z.string().describe("New text content"),
},
async ({ nodeId, text }: any) => {
try {
const result = await sendCommandToFigma("set_text_content", {
nodeId,
text,
});
const typedResult = result as { name: string };
return {
content: [
{
type: "text",
text: `Updated text content of node "${typedResult.name}" to "${text}"`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting text content: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Get Styles Tool
server.tool(
"get_styles",
"Get all styles from the current Figma document",
{},
async () => {
try {
const result = await sendCommandToFigma("get_styles");
return {
content: [
{
type: "text",
text: JSON.stringify(result)
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting styles: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Get Local Components Tool
server.tool(
"get_local_components",
"Get all local components from the Figma document",
{},
async () => {
try {
const result = await sendCommandToFigma("get_local_components");
return {
content: [
{
type: "text",
text: JSON.stringify(result)
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting local components: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Get Annotations Tool
server.tool(
"get_annotations",
"Get all annotations in the current document or specific node",
{
nodeId: z.string().describe("node ID to get annotations for specific node"),
includeCategories: z.boolean().optional().default(true).describe("Whether to include category information")
},
async ({ nodeId, includeCategories }: any) => {
try {
const result = await sendCommandToFigma("get_annotations", {
nodeId,
includeCategories
});
return {
content: [
{
type: "text",
text: JSON.stringify(result)
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting annotations: ${error instanceof Error ? error.message : String(error)}`
}
]
};
}
}
);
// Set Annotation Tool
server.tool(
"set_annotation",
"Create or update an annotation",
{
nodeId: z.string().describe("The ID of the node to annotate"),
annotationId: z.string().optional().describe("The ID of the annotation to update (if updating existing annotation)"),
labelMarkdown: z.string().describe("The annotation text in markdown format"),
categoryId: z.string().optional().describe("The ID of the annotation category"),
properties: z.array(z.object({
type: z.string()
})).optional().describe("Additional properties for the annotation")
},
async ({ nodeId, annotationId, labelMarkdown, categoryId, properties }: any) => {
try {
const result = await sendCommandToFigma("set_annotation", {
nodeId,
annotationId,
labelMarkdown,
categoryId,
properties
});
return {
content: [
{
type: "text",
text: JSON.stringify(result)
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting annotation: ${error instanceof Error ? error.message : String(error)}`
}
]
};
}
}
);
interface SetMultipleAnnotationsParams {
nodeId: string;
annotations: Array<{
nodeId: string;
labelMarkdown: string;
categoryId?: string;
annotationId?: string;
properties?: Array<{ type: string }>;
}>;
}
// Set Multiple Annotations Tool
server.tool(
"set_multiple_annotations",
"Set multiple annotations parallelly in a node",
{
nodeId: z
.string()
.describe("The ID of the node containing the elements to annotate"),
annotations: z
.array(
z.object({
nodeId: z.string().describe("The ID of the node to annotate"),
labelMarkdown: z.string().describe("The annotation text in markdown format"),
categoryId: z.string().optional().describe("The ID of the annotation category"),
annotationId: z.string().optional().describe("The ID of the annotation to update (if updating existing annotation)"),
properties: z.array(z.object({
type: z.string()
})).optional().describe("Additional properties for the annotation")
})
)
.describe("Array of annotations to apply"),
},
async ({ nodeId, annotations }: any) => {
try {
if (!annotations || annotations.length === 0) {
return {
content: [
{
type: "text",
text: "No annotations provided",
},
],
};
}
// Initial response to indicate we're starting the process
const initialStatus = {
type: "text" as const,
text: `Starting annotation process for ${annotations.length} nodes. This will be processed in batches of 5...`,
};
// Track overall progress
let totalProcessed = 0;
const totalToProcess = annotations.length;
// Use the plugin's set_multiple_annotations function with chunking
const result = await sendCommandToFigma("set_multiple_annotations", {
nodeId,
annotations,
});
// Cast the result to a specific type to work with it safely
interface AnnotationResult {
success: boolean;
nodeId: string;
annotationsApplied?: number;
annotationsFailed?: number;
totalAnnotations?: number;
completedInChunks?: number;
results?: Array<{
success: boolean;
nodeId: string;
error?: string;
annotationId?: string;
}>;
}
const typedResult = result as AnnotationResult;
// Format the results for display
const success = typedResult.annotationsApplied && typedResult.annotationsApplied > 0;
const progressText = `
Annotation process completed:
- ${typedResult.annotationsApplied || 0} of ${totalToProcess} successfully applied
- ${typedResult.annotationsFailed || 0} failed
- Processed in ${typedResult.completedInChunks || 1} batches
`;
// Detailed results
const detailedResults = typedResult.results || [];
const failedResults = detailedResults.filter(item => !item.success);
// Create the detailed part of the response
let detailedResponse = "";
if (failedResults.length > 0) {
detailedResponse = `\n\nNodes that failed:\n${failedResults.map(item =>
`- ${item.nodeId}: ${item.error || "Unknown error"}`
).join('\n')}`;
}
return {
content: [
initialStatus,
{
type: "text" as const,
text: progressText + detailedResponse,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting multiple annotations: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Create Component Instance Tool
server.tool(
"create_component_instance",
"Create an instance of a component in Figma",
{
componentKey: z.string().describe("Key of the component to instantiate"),
x: z.number().describe("X position"),
y: z.number().describe("Y position"),
},
async ({ componentKey, x, y }: any) => {
try {
const result = await sendCommandToFigma("create_component_instance", {
componentKey,
x,
y,
});
const typedResult = result as any;
return {
content: [
{
type: "text",
text: JSON.stringify(typedResult),
}
]
}
} catch (error) {
return {
content: [
{
type: "text",
text: `Error creating component instance: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Copy Instance Overrides Tool
server.tool(
"get_instance_overrides",
"Get all override properties from a selected component instance. These overrides can be applied to other instances, which will swap them to match the source component.",
{
nodeId: z.string().optional().describe("Optional ID of the component instance to get overrides from. If not provided, currently selected instance will be used."),
},
async ({ nodeId }: any) => {
try {
const result = await sendCommandToFigma("get_instance_overrides", {
instanceNodeId: nodeId || null
});
const typedResult = result as getInstanceOverridesResult;
return {
content: [
{
type: "text",
text: typedResult.success
? `Successfully got instance overrides: ${typedResult.message}`
: `Failed to get instance overrides: ${typedResult.message}`
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error copying instance overrides: ${error instanceof Error ? error.message : String(error)}`
}
]
};
}
}
);
// Set Instance Overrides Tool
server.tool(
"set_instance_overrides",
"Apply previously copied overrides to selected component instances. Target instances will be swapped to the source component and all copied override properties will be applied.",
{
sourceInstanceId: z.string().describe("ID of the source component instance"),
targetNodeIds: z.array(z.string()).describe("Array of target instance IDs. Currently selected instances will be used.")
},
async ({ sourceInstanceId, targetNodeIds }: any) => {
try {
const result = await sendCommandToFigma("set_instance_overrides", {
sourceInstanceId: sourceInstanceId,
targetNodeIds: targetNodeIds || []
});
const typedResult = result as setInstanceOverridesResult;
if (typedResult.success) {
const successCount = typedResult.results?.filter(r => r.success).length || 0;
return {
content: [
{
type: "text",
text: `Successfully applied ${typedResult.totalCount || 0} overrides to ${successCount} instances.`
}
]
};
} else {
return {
content: [
{
type: "text",
text: `Failed to set instance overrides: ${typedResult.message}`
}
]
};
}
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting instance overrides: ${error instanceof Error ? error.message : String(error)}`
}
]
};
}
}
);
// Set Corner Radius Tool
server.tool(
"set_corner_radius",
"Set the corner radius of a node in Figma",
{
nodeId: z.string().describe("The ID of the node to modify"),
radius: z.number().min(0).describe("Corner radius value"),
corners: z
.array(z.boolean())
.length(4)
.optional()
.describe(
"Optional array of 4 booleans to specify which corners to round [topLeft, topRight, bottomRight, bottomLeft]"
),
},
async ({ nodeId, radius, corners }: any) => {
try {
const result = await sendCommandToFigma("set_corner_radius", {
nodeId,
radius,
corners: corners || [true, true, true, true],
});
const typedResult = result as { name: string };
return {
content: [
{
type: "text",
text: `Set corner radius of node "${typedResult.name}" to ${radius}px`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting corner radius: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Define design strategy prompt
server.prompt(
"design_strategy",
"Best practices for working with Figma designs",
(extra) => {
return {
messages: [
{
role: "assistant",
content: {
type: "text",
text: `When working with Figma designs, follow these best practices:
1. Start with Document Structure:
- First use get_document_info() to understand the current document
- Plan your layout hierarchy before creating elements
- Create a main container frame for each screen/section
2. Naming Conventions:
- Use descriptive, semantic names for all elements
- Follow a consistent naming pattern (e.g., "Login Screen", "Logo Container", "Email Input")
- Group related elements with meaningful names
3. Layout Hierarchy:
- Create parent frames first, then add child elements
- For forms/login screens:
* Start with the main screen container frame
* Create a logo container at the top
* Group input fields in their own containers
* Place action buttons (login, submit) after inputs
* Add secondary elements (forgot password, signup links) last
4. Input Fields Structure:
- Create a container frame for each input field
- Include a label text above or inside the input
- Group related inputs (e.g., username/password) together
5. Element Creation:
- Use create_frame() for containers and input fields
- Use create_text() for labels, buttons text, and links
- Set appropriate colors and styles:
* Use fillColor for backgrounds
* Use strokeColor for borders
* Set proper fontWeight for different text elements
6. Mofifying existing elements:
- use set_text_content() to modify text content.
7. Visual Hierarchy:
- Position elements in logical reading order (top to bottom)
- Maintain consistent spacing between elements
- Use appropriate font sizes for different text types:
* Larger for headings/welcome text
* Medium for input labels
* Standard for button text
* Smaller for helper text/links
8. Best Practices:
- Verify each creation with get_node_info()
- Use parentId to maintain proper hierarchy
- Group related elements together in frames
- Keep consistent spacing and alignment
Example Login Screen Structure:
- Login Screen (main frame)
- Logo Container (frame)
- Logo (image/text)
- Welcome Text (text)
- Input Container (frame)
- Email Input (frame)
- Email Label (text)
- Email Field (frame)
- Password Input (frame)
- Password Label (text)
- Password Field (frame)
- Login Button (frame)
- Button Text (text)
- Helper Links (frame)
- Forgot Password (text)
- Don't have account (text)`,
},
},
],
description: "Best practices for working with Figma designs",
};
}
);
server.prompt(
"read_design_strategy",
"Best practices for reading Figma designs",
(extra) => {
return {
messages: [
{
role: "assistant",
content: {
type: "text",
text: `When reading Figma designs, follow these best practices:
1. Start with selection:
- First use read_my_design() to understand the current selection
- If no selection ask user to select single or multiple nodes
`,
},
},
],
description: "Best practices for reading Figma designs",
};
}
);
// Text Node Scanning Tool
server.tool(
"scan_text_nodes",
"Scan all text nodes in the selected Figma node",
{
nodeId: z.string().describe("ID of the node to scan"),
},
async ({ nodeId }: any) => {
try {
// Initial response to indicate we're starting the process
const initialStatus = {
type: "text" as const,
text: "Starting text node scanning. This may take a moment for large designs...",
};
// Use the plugin's scan_text_nodes function with chunking flag
const result = await sendCommandToFigma("scan_text_nodes", {
nodeId,
useChunking: true, // Enable chunking on the plugin side
chunkSize: 10 // Process 10 nodes at a time
});
// If the result indicates chunking was used, format the response accordingly
if (result && typeof result === 'object' && 'chunks' in result) {
const typedResult = result as {
success: boolean,
totalNodes: number,
processedNodes: number,
chunks: number,
textNodes: Array<any>
};
const summaryText = `
Scan completed:
- Found ${typedResult.totalNodes} text nodes
- Processed in ${typedResult.chunks} chunks
`;
return {
content: [
initialStatus,
{
type: "text" as const,
text: summaryText
},
{
type: "text" as const,
text: JSON.stringify(typedResult.textNodes, null, 2)
}
],
};
}
// If chunking wasn't used or wasn't reported in the result format, return the result as is
return {
content: [
initialStatus,
{
type: "text",
text: JSON.stringify(result, null, 2),
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error scanning text nodes: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Node Type Scanning Tool
server.tool(
"scan_nodes_by_types",
"Scan for child nodes with specific types in the selected Figma node",
{
nodeId: z.string().describe("ID of the node to scan"),
types: z.array(z.string()).describe("Array of node types to find in the child nodes (e.g. ['COMPONENT', 'FRAME'])")
},
async ({ nodeId, types }: any) => {
try {
// Initial response to indicate we're starting the process
const initialStatus = {
type: "text" as const,
text: `Starting node type scanning for types: ${types.join(', ')}...`,
};
// Use the plugin's scan_nodes_by_types function
const result = await sendCommandToFigma("scan_nodes_by_types", {
nodeId,
types
});
// Format the response
if (result && typeof result === 'object' && 'matchingNodes' in result) {
const typedResult = result as {
success: boolean,
count: number,
matchingNodes: Array<{
id: string,
name: string,
type: string,
bbox: {
x: number,
y: number,
width: number,
height: number
}
}>,
searchedTypes: Array<string>
};
const summaryText = `Scan completed: Found ${typedResult.count} nodes matching types: ${typedResult.searchedTypes.join(', ')}`;
return {
content: [
initialStatus,
{
type: "text" as const,
text: summaryText
},
{
type: "text" as const,
text: JSON.stringify(typedResult.matchingNodes, null, 2)
}
],
};
}
// If the result is in an unexpected format, return it as is
return {
content: [
initialStatus,
{
type: "text",
text: JSON.stringify(result, null, 2),
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error scanning nodes by types: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Text Replacement Strategy Prompt
server.prompt(
"text_replacement_strategy",
"Systematic approach for replacing text in Figma designs",
(extra) => {
return {
messages: [
{
role: "assistant",
content: {
type: "text",
text: `# Intelligent Text Replacement Strategy
## 1. Analyze Design & Identify Structure
- Scan text nodes to understand the overall structure of the design
- Use AI pattern recognition to identify logical groupings:
* Tables (rows, columns, headers, cells)
* Lists (items, headers, nested lists)
* Card groups (similar cards with recurring text fields)
* Forms (labels, input fields, validation text)
* Navigation (menu items, breadcrumbs)
\`\`\`
scan_text_nodes(nodeId: "node-id")
get_node_info(nodeId: "node-id") // optional
\`\`\`
## 2. Strategic Chunking for Complex Designs
- Divide replacement tasks into logical content chunks based on design structure
- Use one of these chunking strategies that best fits the design:
* **Structural Chunking**: Table rows/columns, list sections, card groups
* **Spatial Chunking**: Top-to-bottom, left-to-right in screen areas
* **Semantic Chunking**: Content related to the same topic or functionality
* **Component-Based Chunking**: Process similar component instances together
## 3. Progressive Replacement with Verification
- Create a safe copy of the node for text replacement
- Replace text chunk by chunk with continuous progress updates
- After each chunk is processed:
* Export that section as a small, manageable image
* Verify text fits properly and maintain design integrity
* Fix issues before proceeding to the next chunk
\`\`\`
// Clone the node to create a safe copy
clone_node(nodeId: "selected-node-id", x: [new-x], y: [new-y])
// Replace text chunk by chunk
set_multiple_text_contents(
nodeId: "parent-node-id",
text: [
{ nodeId: "node-id-1", text: "New text 1" },
// More nodes in this chunk...
]
)
// Verify chunk with small, targeted image exports
export_node_as_image(nodeId: "chunk-node-id", format: "PNG", scale: 0.5)
\`\`\`
## 4. Intelligent Handling for Table Data
- For tabular content:
* Process one row or column at a time
* Maintain alignment and spacing between cells
* Consider conditional formatting based on cell content
* Preserve header/data relationships
## 5. Smart Text Adaptation
- Adaptively handle text based on container constraints:
* Auto-detect space constraints and adjust text length
* Apply line breaks at appropriate linguistic points
* Maintain text hierarchy and emphasis
* Consider font scaling for critical content that must fit
## 6. Progressive Feedback Loop
- Establish a continuous feedback loop during replacement:
* Real-time progress updates (0-100%)
* Small image exports after each chunk for verification
* Issues identified early and resolved incrementally
* Quick adjustments applied to subsequent chunks
## 7. Final Verification & Context-Aware QA
- After all chunks are processed:
* Export the entire design at reduced scale for final verification
* Check for cross-chunk consistency issues
* Verify proper text flow between different sections
* Ensure design harmony across the full composition
## 8. Chunk-Specific Export Scale Guidelines
- Scale exports appropriately based on chunk size:
* Small chunks (1-5 elements): scale 1.0
* Medium chunks (6-20 elements): scale 0.7
* Large chunks (21-50 elements): scale 0.5
* Very large chunks (50+ elements): scale 0.3
* Full design verification: scale 0.2
## Sample Chunking Strategy for Common Design Types
### Tables
- Process by logical rows (5-10 rows per chunk)
- Alternative: Process by column for columnar analysis
- Tip: Always include header row in first chunk for reference
### Card Lists
- Group 3-5 similar cards per chunk
- Process entire cards to maintain internal consistency
- Verify text-to-image ratio within cards after each chunk
### Forms
- Group related fields (e.g., "Personal Information", "Payment Details")
- Process labels and input fields together
- Ensure validation messages and hints are updated with their fields
### Navigation & Menus
- Process hierarchical levels together (main menu, submenu)
- Respect information architecture relationships
- Verify menu fit and alignment after replacement
## Best Practices
- **Preserve Design Intent**: Always prioritize design integrity
- **Structural Consistency**: Maintain alignment, spacing, and hierarchy
- **Visual Feedback**: Verify each chunk visually before proceeding
- **Incremental Improvement**: Learn from each chunk to improve subsequent ones
- **Balance Automation & Control**: Let AI handle repetitive replacements but maintain oversight
- **Respect Content Relationships**: Keep related content consistent across chunks
Remember that text is never just text—it's a core design element that must work harmoniously with the overall composition. This chunk-based strategy allows you to methodically transform text while maintaining design integrity.`,
},
},
],
description: "Systematic approach for replacing text in Figma designs",
};
}
);
// Set Multiple Text Contents Tool
server.tool(
"set_multiple_text_contents",
"Set multiple text contents parallelly in a node",
{
nodeId: z
.string()
.describe("The ID of the node containing the text nodes to replace"),
text: z
.array(
z.object({
nodeId: z.string().describe("The ID of the text node"),
text: z.string().describe("The replacement text"),
})
)
.describe("Array of text node IDs and their replacement texts"),
},
async ({ nodeId, text }: any) => {
try {
if (!text || text.length === 0) {
return {
content: [
{
type: "text",
text: "No text provided",
},
],
};
}
// Initial response to indicate we're starting the process
const initialStatus = {
type: "text" as const,
text: `Starting text replacement for ${text.length} nodes. This will be processed in batches of 5...`,
};
// Track overall progress
let totalProcessed = 0;
const totalToProcess = text.length;
// Use the plugin's set_multiple_text_contents function with chunking
const result = await sendCommandToFigma("set_multiple_text_contents", {
nodeId,
text,
});
// Cast the result to a specific type to work with it safely
interface TextReplaceResult {
success: boolean;
nodeId: string;
replacementsApplied?: number;
replacementsFailed?: number;
totalReplacements?: number;
completedInChunks?: number;
results?: Array<{
success: boolean;
nodeId: string;
error?: string;
originalText?: string;
translatedText?: string;
}>;
}
const typedResult = result as TextReplaceResult;
// Format the results for display
const success = typedResult.replacementsApplied && typedResult.replacementsApplied > 0;
const progressText = `
Text replacement completed:
- ${typedResult.replacementsApplied || 0} of ${totalToProcess} successfully updated
- ${typedResult.replacementsFailed || 0} failed
- Processed in ${typedResult.completedInChunks || 1} batches
`;
// Detailed results
const detailedResults = typedResult.results || [];
const failedResults = detailedResults.filter(item => !item.success);
// Create the detailed part of the response
let detailedResponse = "";
if (failedResults.length > 0) {
detailedResponse = `\n\nNodes that failed:\n${failedResults.map(item =>
`- ${item.nodeId}: ${item.error || "Unknown error"}`
).join('\n')}`;
}
return {
content: [
initialStatus,
{
type: "text" as const,
text: progressText + detailedResponse,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting multiple text contents: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Annotation Conversion Strategy Prompt
server.prompt(
"annotation_conversion_strategy",
"Strategy for converting manual annotations to Figma's native annotations",
(extra) => {
return {
messages: [
{
role: "assistant",
content: {
type: "text",
text: `# Automatic Annotation Conversion
## Process Overview
The process of converting manual annotations (numbered/alphabetical indicators with connected descriptions) to Figma's native annotations:
1. Get selected frame/component information
2. Scan and collect all annotation text nodes
3. Scan target UI elements (components, instances, frames)
4. Match annotations to appropriate UI elements
5. Apply native Figma annotations
## Step 1: Get Selection and Initial Setup
First, get the selected frame or component that contains annotations:
\`\`\`typescript
// Get the selected frame/component
const selection = await get_selection();
const selectedNodeId = selection[0].id
// Get available annotation categories for later use
const annotationData = await get_annotations({
nodeId: selectedNodeId,
includeCategories: true
});
const categories = annotationData.categories;
\`\`\`
## Step 2: Scan Annotation Text Nodes
Scan all text nodes to identify annotations and their descriptions:
\`\`\`typescript
// Get all text nodes in the selection
const textNodes = await scan_text_nodes({
nodeId: selectedNodeId
});
// Filter and group annotation markers and descriptions
// Markers typically have these characteristics:
// - Short text content (usually single digit/letter)
// - Specific font styles (often bold)
// - Located in a container with "Marker" or "Dot" in the name
// - Have a clear naming pattern (e.g., "1", "2", "3" or "A", "B", "C")
// Identify description nodes
// Usually longer text nodes near markers or with matching numbers in path
\`\`\`
## Step 3: Scan Target UI Elements
Get all potential target elements that annotations might refer to:
\`\`\`typescript
// Scan for all UI elements that could be annotation targets
const targetNodes = await scan_nodes_by_types({
nodeId: selectedNodeId,
types: [
"COMPONENT",
"INSTANCE",
"FRAME"
]
});
\`\`\`
## Step 4: Match Annotations to Targets
Match each annotation to its target UI element using these strategies in order of priority:
1. **Path-Based Matching**:
- Look at the marker's parent container name in the Figma layer hierarchy
- Remove any "Marker:" or "Annotation:" prefixes from the parent name
- Find UI elements that share the same parent name or have it in their path
- This works well when markers are grouped with their target elements
2. **Name-Based Matching**:
- Extract key terms from the annotation description
- Look for UI elements whose names contain these key terms
- Consider both exact matches and semantic similarities
- Particularly effective for form fields, buttons, and labeled components
3. **Proximity-Based Matching** (fallback):
- Calculate the center point of the marker
- Find the closest UI element by measuring distances to element centers
- Consider the marker's position relative to nearby elements
- Use this method when other matching strategies fail
Additional Matching Considerations:
- Give higher priority to matches found through path-based matching
- Consider the type of UI element when evaluating matches
- Take into account the annotation's context and content
- Use a combination of strategies for more accurate matching
## Step 5: Apply Native Annotations
Convert matched annotations to Figma's native annotations using batch processing:
\`\`\`typescript
// Prepare annotations array for batch processing
const annotationsToApply = Object.values(annotations).map(({ marker, description }) => {
// Find target using multiple strategies
const target =
findTargetByPath(marker, targetNodes) ||
findTargetByName(description, targetNodes) ||
findTargetByProximity(marker, targetNodes);
if (target) {
// Determine appropriate category based on content
const category = determineCategory(description.characters, categories);
// Determine appropriate additional annotationProperty based on content
const annotationProperty = determineProperties(description.characters, target.type);
return {
nodeId: target.id,
labelMarkdown: description.characters,
categoryId: category.id,
properties: annotationProperty
};
}
return null;
}).filter(Boolean); // Remove null entries
// Apply annotations in batches using set_multiple_annotations
if (annotationsToApply.length > 0) {
await set_multiple_annotations({
nodeId: selectedNodeId,
annotations: annotationsToApply
});
}
\`\`\`
This strategy focuses on practical implementation based on real-world usage patterns, emphasizing the importance of handling various UI elements as annotation targets, not just text nodes.`
},
},
],
description: "Strategy for converting manual annotations to Figma's native annotations",
};
}
);
// Instance Slot Filling Strategy Prompt
server.prompt(
"swap_overrides_instances",
"Guide to swap instance overrides between instances",
(extra) => {
return {
messages: [
{
role: "assistant",
content: {
type: "text",
text: `# Swap Component Instance and Override Strategy
## Overview
This strategy enables transferring content and property overrides from a source instance to one or more target instances in Figma, maintaining design consistency while reducing manual work.
## Step-by-Step Process
### 1. Selection Analysis
- Use \`get_selection()\` to identify the parent component or selected instances
- For parent components, scan for instances with \`scan_nodes_by_types({ nodeId: "parent-id", types: ["INSTANCE"] })\`
- Identify custom slots by name patterns (e.g. "Custom Slot*" or "Instance Slot") or by examining text content
- Determine which is the source instance (with content to copy) and which are targets (where to apply content)
### 2. Extract Source Overrides
- Use \`get_instance_overrides()\` to extract customizations from the source instance
- This captures text content, property values, and style overrides
- Command syntax: \`get_instance_overrides({ nodeId: "source-instance-id" })\`
- Look for successful response like "Got component information from [instance name]"
### 3. Apply Overrides to Targets
- Apply captured overrides using \`set_instance_overrides()\`
- Command syntax:
\`\`\`
set_instance_overrides({
sourceInstanceId: "source-instance-id",
targetNodeIds: ["target-id-1", "target-id-2", ...]
})
\`\`\`
### 4. Verification
- Verify results with \`get_node_info()\` or \`read_my_design()\`
- Confirm text content and style overrides have transferred successfully
## Key Tips
- Always join the appropriate channel first with \`join_channel()\`
- When working with multiple targets, check the full selection with \`get_selection()\`
- Preserve component relationships by using instance overrides rather than direct text manipulation`,
},
},
],
description: "Strategy for transferring overrides between component instances in Figma",
};
}
);
// Set Layout Mode Tool
server.tool(
"set_layout_mode",
"Set the layout mode and wrap behavior of a frame in Figma",
{
nodeId: z.string().describe("The ID of the frame to modify"),
layoutMode: z.enum(["NONE", "HORIZONTAL", "VERTICAL"]).describe("Layout mode for the frame"),
layoutWrap: z.enum(["NO_WRAP", "WRAP"]).optional().describe("Whether the auto-layout frame wraps its children")
},
async ({ nodeId, layoutMode, layoutWrap }: any) => {
try {
const result = await sendCommandToFigma("set_layout_mode", {
nodeId,
layoutMode,
layoutWrap: layoutWrap || "NO_WRAP"
});
const typedResult = result as { name: string };
return {
content: [
{
type: "text",
text: `Set layout mode of frame "${typedResult.name}" to ${layoutMode}${layoutWrap ? ` with ${layoutWrap}` : ''}`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting layout mode: ${error instanceof Error ? error.message : String(error)}`,
},
],
};
}
}
);
// Set Padding Tool
server.tool(
"set_padding",
"Set padding values for an auto-layout frame in Figma",
{
nodeId: z.string().describe("The ID of the frame to modify"),
paddingTop: z.number().optional().describe("Top padding value"),
paddingRight: z.number().optional().describe("Right padding value"),
paddingBottom: z.number().optional().describe("Bottom padding value"),
paddingLeft: z.number().optional().describe("Left padding value"),
},
async ({ nodeId, paddingTop, paddingRight, paddingBottom, paddingLeft }: any) => {
try {
const result = await sendCommandToFigma("set_padding", {
nodeId,
paddingTop,
paddingRight,
paddingBottom,
paddingLeft,
});
const typedResult = result as { name: string };
// Create a message about which padding values were set
const paddingMessages = [];
if (paddingTop !== undefined) paddingMessages.push(`top: ${paddingTop}`);
if (paddingRight !== undefined) paddingMessages.push(`right: ${paddingRight}`);
if (paddingBottom !== undefined) paddingMessages.push(`bottom: ${paddingBottom}`);
if (paddingLeft !== undefined) paddingMessages.push(`left: ${paddingLeft}`);
const paddingText = paddingMessages.length > 0
? `padding (${paddingMessages.join(', ')})`
: "padding";
return {
content: [
{
type: "text",
text: `Set ${paddingText} for frame "${typedResult.name}"`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting padding: ${error instanceof Error ? error.message : String(error)}`,
},
],
};
}
}
);
// Set Axis Align Tool
server.tool(
"set_axis_align",
"Set primary and counter axis alignment for an auto-layout frame in Figma",
{
nodeId: z.string().describe("The ID of the frame to modify"),
primaryAxisAlignItems: z
.enum(["MIN", "MAX", "CENTER", "SPACE_BETWEEN"])
.optional()
.describe("Primary axis alignment (MIN/MAX = left/right in horizontal, top/bottom in vertical). Note: When set to SPACE_BETWEEN, itemSpacing will be ignored as children will be evenly spaced."),
counterAxisAlignItems: z
.enum(["MIN", "MAX", "CENTER", "BASELINE"])
.optional()
.describe("Counter axis alignment (MIN/MAX = top/bottom in horizontal, left/right in vertical)")
},
async ({ nodeId, primaryAxisAlignItems, counterAxisAlignItems }: any) => {
try {
const result = await sendCommandToFigma("set_axis_align", {
nodeId,
primaryAxisAlignItems,
counterAxisAlignItems
});
const typedResult = result as { name: string };
// Create a message about which alignments were set
const alignMessages = [];
if (primaryAxisAlignItems !== undefined) alignMessages.push(`primary: ${primaryAxisAlignItems}`);
if (counterAxisAlignItems !== undefined) alignMessages.push(`counter: ${counterAxisAlignItems}`);
const alignText = alignMessages.length > 0
? `axis alignment (${alignMessages.join(', ')})`
: "axis alignment";
return {
content: [
{
type: "text",
text: `Set ${alignText} for frame "${typedResult.name}"`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting axis alignment: ${error instanceof Error ? error.message : String(error)}`,
},
],
};
}
}
);
// Set Layout Sizing Tool
server.tool(
"set_layout_sizing",
"Set horizontal and vertical sizing modes for an auto-layout frame in Figma",
{
nodeId: z.string().describe("The ID of the frame to modify"),
layoutSizingHorizontal: z
.enum(["FIXED", "HUG", "FILL"])
.optional()
.describe("Horizontal sizing mode (HUG for frames/text only, FILL for auto-layout children only)"),
layoutSizingVertical: z
.enum(["FIXED", "HUG", "FILL"])
.optional()
.describe("Vertical sizing mode (HUG for frames/text only, FILL for auto-layout children only)")
},
async ({ nodeId, layoutSizingHorizontal, layoutSizingVertical }: any) => {
try {
const result = await sendCommandToFigma("set_layout_sizing", {
nodeId,
layoutSizingHorizontal,
layoutSizingVertical
});
const typedResult = result as { name: string };
// Create a message about which sizing modes were set
const sizingMessages = [];
if (layoutSizingHorizontal !== undefined) sizingMessages.push(`horizontal: ${layoutSizingHorizontal}`);
if (layoutSizingVertical !== undefined) sizingMessages.push(`vertical: ${layoutSizingVertical}`);
const sizingText = sizingMessages.length > 0
? `layout sizing (${sizingMessages.join(', ')})`
: "layout sizing";
return {
content: [
{
type: "text",
text: `Set ${sizingText} for frame "${typedResult.name}"`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting layout sizing: ${error instanceof Error ? error.message : String(error)}`,
},
],
};
}
}
);
// Set Item Spacing Tool
server.tool(
"set_item_spacing",
"Set distance between children in an auto-layout frame",
{
nodeId: z.string().describe("The ID of the frame to modify"),
itemSpacing: z.number().optional().describe("Distance between children. Note: This value will be ignored if primaryAxisAlignItems is set to SPACE_BETWEEN."),
counterAxisSpacing: z.number().optional().describe("Distance between wrapped rows/columns. Only works when layoutWrap is set to WRAP.")
},
async ({ nodeId, itemSpacing, counterAxisSpacing}: any) => {
try {
const params: any = { nodeId };
if (itemSpacing !== undefined) params.itemSpacing = itemSpacing;
if (counterAxisSpacing !== undefined) params.counterAxisSpacing = counterAxisSpacing;
const result = await sendCommandToFigma("set_item_spacing", params);
const typedResult = result as { name: string, itemSpacing?: number, counterAxisSpacing?: number };
let message = `Updated spacing for frame "${typedResult.name}":`;
if (itemSpacing !== undefined) message += ` itemSpacing=${itemSpacing}`;
if (counterAxisSpacing !== undefined) message += ` counterAxisSpacing=${counterAxisSpacing}`;
return {
content: [
{
type: "text",
text: message,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting spacing: ${error instanceof Error ? error.message : String(error)}`,
},
],
};
}
}
);
// A tool to get Figma Prototyping Reactions from multiple nodes
server.tool(
"get_reactions",
"Get Figma Prototyping Reactions from multiple nodes. CRITICAL: The output MUST be processed using the 'reaction_to_connector_strategy' prompt IMMEDIATELY to generate parameters for connector lines via the 'create_connections' tool.",
{
nodeIds: z.array(z.string()).describe("Array of node IDs to get reactions from"),
},
async ({ nodeIds }: any) => {
try {
const result = await sendCommandToFigma("get_reactions", { nodeIds });
return {
content: [
{
type: "text",
text: JSON.stringify(result)
},
{
type: "text",
text: "IMPORTANT: You MUST now use the reaction data above and follow the `reaction_to_connector_strategy` prompt to prepare the parameters for the `create_connections` tool call. This is a required next step."
}
],
followUp: {
type: "prompt",
prompt: "reaction_to_connector_strategy",
},
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error getting reactions: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Create Connectors Tool
server.tool(
"set_default_connector",
"Set a copied connector node as the default connector",
{
connectorId: z.string().optional().describe("The ID of the connector node to set as default")
},
async ({ connectorId }: any) => {
try {
const result = await sendCommandToFigma("set_default_connector", {
connectorId
});
return {
content: [
{
type: "text",
text: `Default connector set: ${JSON.stringify(result)}`
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting default connector: ${error instanceof Error ? error.message : String(error)}`
}
]
};
}
}
);
// Connect Nodes Tool
server.tool(
"create_connections",
"Create connections between nodes using the default connector style",
{
connections: z.array(z.object({
startNodeId: z.string().describe("ID of the starting node"),
endNodeId: z.string().describe("ID of the ending node"),
text: z.string().optional().describe("Optional text to display on the connector")
})).describe("Array of node connections to create")
},
async ({ connections }: any) => {
try {
if (!connections || connections.length === 0) {
return {
content: [
{
type: "text",
text: "No connections provided"
}
]
};
}
const result = await sendCommandToFigma("create_connections", {
connections
});
return {
content: [
{
type: "text",
text: `Created ${connections.length} connections: ${JSON.stringify(result)}`
}
]
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error creating connections: ${error instanceof Error ? error.message : String(error)}`
}
]
};
}
}
);
// Set Focus Tool
server.tool(
"set_focus",
"Set focus on a specific node in Figma by selecting it and scrolling viewport to it",
{
nodeId: z.string().describe("The ID of the node to focus on"),
},
async ({ nodeId }: any) => {
try {
const result = await sendCommandToFigma("set_focus", { nodeId });
const typedResult = result as { name: string; id: string };
return {
content: [
{
type: "text",
text: `Focused on node "${typedResult.name}" (ID: ${typedResult.id})`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting focus: ${error instanceof Error ? error.message : String(error)}`,
},
],
};
}
}
);
// Set Selections Tool
server.tool(
"set_selections",
"Set selection to multiple nodes in Figma and scroll viewport to show them",
{
nodeIds: z.array(z.string()).describe("Array of node IDs to select"),
},
async ({ nodeIds }: any) => {
try {
const result = await sendCommandToFigma("set_selections", { nodeIds });
const typedResult = result as { selectedNodes: Array<{ name: string; id: string }>; count: number };
return {
content: [
{
type: "text",
text: `Selected ${typedResult.count} nodes: ${typedResult.selectedNodes.map(node => `"${node.name}" (${node.id})`).join(', ')}`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error setting selections: ${error instanceof Error ? error.message : String(error)}`,
},
],
};
}
}
);
// Strategy for converting Figma prototype reactions to connector lines
server.prompt(
"reaction_to_connector_strategy",
"Strategy for converting Figma prototype reactions to connector lines using the output of 'get_reactions'",
(extra) => {
return {
messages: [
{
role: "assistant",
content: {
type: "text",
text: `# Strategy: Convert Figma Prototype Reactions to Connector Lines
## Goal
Process the JSON output from the \`get_reactions\` tool to generate an array of connection objects suitable for the \`create_connections\` tool. This visually represents prototype flows as connector lines on the Figma canvas.
## Input Data
You will receive JSON data from the \`get_reactions\` tool. This data contains an array of nodes, each with potential reactions. A typical reaction object looks like this:
\`\`\`json
{
"trigger": { "type": "ON_CLICK" },
"action": {
"type": "NAVIGATE",
"destinationId": "destination-node-id",
"navigationTransition": { ... },
"preserveScrollPosition": false
}
}
\`\`\`
## Step-by-Step Process
### 1. Preparation & Context Gathering
- **Action:** Call \`read_my_design\` on the relevant node(s) to get context about the nodes involved (names, types, etc.). This helps in generating meaningful connector labels later.
- **Action:** Call \`set_default_connector\` **without** the \`connectorId\` parameter.
- **Check Result:** Analyze the response from \`set_default_connector\`.
- If it confirms a default connector is already set (e.g., "Default connector is already set"), proceed to Step 2.
- If it indicates no default connector is set (e.g., "No default connector set..."), you **cannot** proceed with \`create_connections\` yet. Inform the user they need to manually copy a connector from FigJam, paste it onto the current page, select it, and then you can run \`set_default_connector({ connectorId: "SELECTED_NODE_ID" })\` before attempting \`create_connections\`. **Do not proceed to Step 2 until a default connector is confirmed.**
### 2. Filter and Transform Reactions from \`get_reactions\` Output
- **Iterate:** Go through the JSON array provided by \`get_reactions\`. For each node in the array:
- Iterate through its \`reactions\` array.
- **Filter:** Keep only reactions where the \`action\` meets these criteria:
- Has a \`type\` that implies a connection (e.g., \`NAVIGATE\`, \`OPEN_OVERLAY\`, \`SWAP_OVERLAY\`). **Ignore** types like \`CHANGE_TO\`, \`CLOSE_OVERLAY\`, etc.
- Has a valid \`destinationId\` property.
- **Extract:** For each valid reaction, extract the following information:
- \`sourceNodeId\`: The ID of the node the reaction belongs to (from the outer loop).
- \`destinationNodeId\`: The value of \`action.destinationId\`.
- \`actionType\`: The value of \`action.type\`.
- \`triggerType\`: The value of \`trigger.type\`.
### 3. Generate Connector Text Labels
- **For each extracted connection:** Create a concise, descriptive text label string.
- **Combine Information:** Use the \`actionType\`, \`triggerType\`, and potentially the names of the source/destination nodes (obtained from Step 1's \`read_my_design\` or by calling \`get_node_info\` if necessary) to generate the label.
- **Example Labels:**
- If \`triggerType\` is "ON\_CLICK" and \`actionType\` is "NAVIGATE": "On click, navigate to [Destination Node Name]"
- If \`triggerType\` is "ON\_DRAG" and \`actionType\` is "OPEN\_OVERLAY": "On drag, open [Destination Node Name] overlay"
- **Keep it brief and informative.** Let this generated string be \`generatedText\`.
### 4. Prepare the \`connections\` Array for \`create_connections\`
- **Structure:** Create a JSON array where each element is an object representing a connection.
- **Format:** Each object in the array must have the following structure:
\`\`\`json
{
"startNodeId": "sourceNodeId_from_step_2",
"endNodeId": "destinationNodeId_from_step_2",
"text": "generatedText_from_step_3"
}
\`\`\`
- **Result:** This final array is the value you will pass to the \`connections\` parameter when calling the \`create_connections\` tool.
### 5. Execute Connection Creation
- **Action:** Call the \`create_connections\` tool, passing the array generated in Step 4 as the \`connections\` argument.
- **Verify:** Check the response from \`create_connections\` to confirm success or failure.
This detailed process ensures you correctly interpret the reaction data, prepare the necessary information, and use the appropriate tools to create the connector lines.`
},
},
],
description: "Strategy for converting Figma prototype reactions to connector lines using the output of 'get_reactions'",
};
}
);
// Define command types and parameters
type FigmaCommand =
| "get_document_info"
| "get_selection"
| "get_node_info"
| "get_nodes_info"
| "read_my_design"
| "create_rectangle"
| "create_frame"
| "create_text"
| "set_fill_color"
| "set_stroke_color"
| "move_node"
| "resize_node"
| "delete_node"
| "delete_multiple_nodes"
| "get_styles"
| "get_local_components"
| "create_component_instance"
| "get_instance_overrides"
| "set_instance_overrides"
| "export_node_as_image"
| "join"
| "set_corner_radius"
| "clone_node"
| "set_text_content"
| "scan_text_nodes"
| "set_multiple_text_contents"
| "get_annotations"
| "set_annotation"
| "set_multiple_annotations"
| "scan_nodes_by_types"
| "set_layout_mode"
| "set_padding"
| "set_axis_align"
| "set_layout_sizing"
| "set_item_spacing"
| "get_reactions"
| "set_default_connector"
| "create_connections"
| "set_focus"
| "set_selections";
type CommandParams = {
get_document_info: Record<string, never>;
get_selection: Record<string, never>;
get_node_info: { nodeId: string };
get_nodes_info: { nodeIds: string[] };
create_rectangle: {
x: number;
y: number;
width: number;
height: number;
name?: string;
parentId?: string;
};
create_frame: {
x: number;
y: number;
width: number;
height: number;
name?: string;
parentId?: string;
fillColor?: { r: number; g: number; b: number; a?: number };
strokeColor?: { r: number; g: number; b: number; a?: number };
strokeWeight?: number;
};
create_text: {
x: number;
y: number;
text: string;
fontSize?: number;
fontWeight?: number;
fontColor?: { r: number; g: number; b: number; a?: number };
name?: string;
parentId?: string;
};
set_fill_color: {
nodeId: string;
r: number;
g: number;
b: number;
a?: number;
};
set_stroke_color: {
nodeId: string;
r: number;
g: number;
b: number;
a?: number;
weight?: number;
};
move_node: {
nodeId: string;
x: number;
y: number;
};
resize_node: {
nodeId: string;
width: number;
height: number;
};
delete_node: {
nodeId: string;
};
delete_multiple_nodes: {
nodeIds: string[];
};
get_styles: Record<string, never>;
get_local_components: Record<string, never>;
get_team_components: Record<string, never>;
create_component_instance: {
componentKey: string;
x: number;
y: number;
};
get_instance_overrides: {
instanceNodeId: string | null;
};
set_instance_overrides: {
targetNodeIds: string[];
sourceInstanceId: string;
};
export_node_as_image: {
nodeId: string;
format?: "PNG" | "JPG" | "SVG" | "PDF";
scale?: number;
};
execute_code: {
code: string;
};
join: {
channel: string;
};
set_corner_radius: {
nodeId: string;
radius: number;
corners?: boolean[];
};
clone_node: {
nodeId: string;
x?: number;
y?: number;
};
set_text_content: {
nodeId: string;
text: string;
};
scan_text_nodes: {
nodeId: string;
useChunking: boolean;
chunkSize: number;
};
set_multiple_text_contents: {
nodeId: string;
text: Array<{ nodeId: string; text: string }>;
};
get_annotations: {
nodeId?: string;
includeCategories?: boolean;
};
set_annotation: {
nodeId: string;
annotationId?: string;
labelMarkdown: string;
categoryId?: string;
properties?: Array<{ type: string }>;
};
set_multiple_annotations: SetMultipleAnnotationsParams;
scan_nodes_by_types: {
nodeId: string;
types: Array<string>;
};
get_reactions: { nodeIds: string[] };
set_default_connector: {
connectorId?: string | undefined;
};
create_connections: {
connections: Array<{
startNodeId: string;
endNodeId: string;
text?: string;
}>;
};
set_focus: {
nodeId: string;
};
set_selections: {
nodeIds: string[];
};
};
// Helper function to process Figma node responses
function processFigmaNodeResponse(result: unknown): any {
if (!result || typeof result !== "object") {
return result;
}
// Check if this looks like a node response
const resultObj = result as Record<string, unknown>;
if ("id" in resultObj && typeof resultObj.id === "string") {
// It appears to be a node response, log the details
console.info(
`Processed Figma node: ${resultObj.name || "Unknown"} (ID: ${resultObj.id
})`
);
if ("x" in resultObj && "y" in resultObj) {
console.debug(`Node position: (${resultObj.x}, ${resultObj.y})`);
}
if ("width" in resultObj && "height" in resultObj) {
console.debug(`Node dimensions: ${resultObj.width}×${resultObj.height}`);
}
}
return result;
}
// Update the connectToFigma function
function connectToFigma(port: number = 3055) {
// If already connected, do nothing
if (ws && ws.readyState === WebSocket.OPEN) {
logger.info('Already connected to Figma');
return;
}
const wsUrl = serverUrl === 'localhost' ? `${WS_URL}:${port}` : WS_URL;
logger.info(`Connecting to Figma socket server at ${wsUrl}...`);
ws = new WebSocket(wsUrl);
ws.on('open', () => {
logger.info('Connected to Figma socket server');
// Reset channel on new connection
currentChannel = null;
});
ws.on("message", (data: any) => {
try {
// Define a more specific type with an index signature to allow any property access
interface ProgressMessage {
message: FigmaResponse | any;
type?: string;
id?: string;
[key: string]: any; // Allow any other properties
}
const json = JSON.parse(data) as ProgressMessage;
// Handle progress updates
if (json.type === 'progress_update') {
const progressData = json.message.data as CommandProgressUpdate;
const requestId = json.id || '';
if (requestId && pendingRequests.has(requestId)) {
const request = pendingRequests.get(requestId)!;
// Update last activity timestamp
request.lastActivity = Date.now();
// Reset the timeout to prevent timeouts during long-running operations
clearTimeout(request.timeout);
// Create a new timeout
request.timeout = setTimeout(() => {
if (pendingRequests.has(requestId)) {
logger.error(`Request ${requestId} timed out after extended period of inactivity`);
pendingRequests.delete(requestId);
request.reject(new Error('Request to Figma timed out'));
}
}, 60000); // 60 second timeout for inactivity
// Log progress
logger.info(`Progress update for ${progressData.commandType}: ${progressData.progress}% - ${progressData.message}`);
// For completed updates, we could resolve the request early if desired
if (progressData.status === 'completed' && progressData.progress === 100) {
// Optionally resolve early with partial data
// request.resolve(progressData.payload);
// pendingRequests.delete(requestId);
// Instead, just log the completion, wait for final result from Figma
logger.info(`Operation ${progressData.commandType} completed, waiting for final result`);
}
}
return;
}
// Handle regular responses
const myResponse = json.message;
logger.debug(`Received message: ${JSON.stringify(myResponse)}`);
logger.log('myResponse' + JSON.stringify(myResponse));
// Handle response to a request
if (
myResponse.id &&
pendingRequests.has(myResponse.id) &&
myResponse.result
) {
const request = pendingRequests.get(myResponse.id)!;
clearTimeout(request.timeout);
if (myResponse.error) {
logger.error(`Error from Figma: ${myResponse.error}`);
request.reject(new Error(myResponse.error));
} else {
if (myResponse.result) {
request.resolve(myResponse.result);
}
}
pendingRequests.delete(myResponse.id);
} else {
// Handle broadcast messages or events
logger.info(`Received broadcast message: ${JSON.stringify(myResponse)}`);
}
} catch (error) {
logger.error(`Error parsing message: ${error instanceof Error ? error.message : String(error)}`);
}
});
ws.on('error', (error) => {
logger.error(`Socket error: ${error}`);
});
ws.on('close', () => {
logger.info('Disconnected from Figma socket server');
ws = null;
// Reject all pending requests
for (const [id, request] of pendingRequests.entries()) {
clearTimeout(request.timeout);
request.reject(new Error("Connection closed"));
pendingRequests.delete(id);
}
// Attempt to reconnect
logger.info('Attempting to reconnect in 2 seconds...');
setTimeout(() => connectToFigma(port), 2000);
});
}
// Function to join a channel
async function joinChannel(channelName: string): Promise<void> {
if (!ws || ws.readyState !== WebSocket.OPEN) {
throw new Error("Not connected to Figma");
}
try {
await sendCommandToFigma("join", { channel: channelName });
currentChannel = channelName;
logger.info(`Joined channel: ${channelName}`);
} catch (error) {
logger.error(`Failed to join channel: ${error instanceof Error ? error.message : String(error)}`);
throw error;
}
}
// Function to send commands to Figma
function sendCommandToFigma(
command: FigmaCommand,
params: unknown = {},
timeoutMs: number = 30000
): Promise<unknown> {
return new Promise((resolve, reject) => {
// If not connected, try to connect first
if (!ws || ws.readyState !== WebSocket.OPEN) {
connectToFigma();
reject(new Error("Not connected to Figma. Attempting to connect..."));
return;
}
// Check if we need a channel for this command
const requiresChannel = command !== "join";
if (requiresChannel && !currentChannel) {
reject(new Error("Must join a channel before sending commands"));
return;
}
const id = uuidv4();
const request = {
id,
type: command === "join" ? "join" : "message",
...(command === "join"
? { channel: (params as any).channel }
: { channel: currentChannel }),
message: {
id,
command,
params: {
...(params as any),
commandId: id, // Include the command ID in params
},
},
};
// Set timeout for request
const timeout = setTimeout(() => {
if (pendingRequests.has(id)) {
pendingRequests.delete(id);
logger.error(`Request ${id} to Figma timed out after ${timeoutMs / 1000} seconds`);
reject(new Error('Request to Figma timed out'));
}
}, timeoutMs);
// Store the promise callbacks to resolve/reject later
pendingRequests.set(id, {
resolve,
reject,
timeout,
lastActivity: Date.now()
});
// Send the request
logger.info(`Sending command to Figma: ${command}`);
logger.debug(`Request details: ${JSON.stringify(request)}`);
ws.send(JSON.stringify(request));
});
}
// Update the join_channel tool
server.tool(
"join_channel",
"Join a specific channel to communicate with Figma",
{
channel: z.string().describe("The name of the channel to join").default(""),
},
async ({ channel }: any) => {
try {
if (!channel) {
// If no channel provided, ask the user for input
return {
content: [
{
type: "text",
text: "Please provide a channel name to join:",
},
],
followUp: {
tool: "join_channel",
description: "Join the specified channel",
},
};
}
await joinChannel(channel);
return {
content: [
{
type: "text",
text: `Successfully joined channel: ${channel}`,
},
],
};
} catch (error) {
return {
content: [
{
type: "text",
text: `Error joining channel: ${error instanceof Error ? error.message : String(error)
}`,
},
],
};
}
}
);
// Start the server
async function main() {
try {
// Try to connect to Figma socket server
connectToFigma();
} catch (error) {
logger.warn(`Could not connect to Figma initially: ${error instanceof Error ? error.message : String(error)}`);
logger.warn('Will try to connect when the first command is sent');
}
// Start the MCP server with stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);
logger.info('FigmaMCP server running on stdio');
}
// Run the server
main().catch(error => {
logger.error(`Error starting FigmaMCP server: ${error instanceof Error ? error.message : String(error)}`);
process.exit(1);
});
```