Skip to content

Instantly share code, notes, and snippets.

@dusskapark

dusskapark/CURSOR_FIGMA_MCP_SETUP_GUIDE.md

Last active June 28, 2025 06:39
Show Gist options
  • Save dusskapark/c50b2942ee08944d310940f618c20c7f to your computer and use it in GitHub Desktop.
Save dusskapark/c50b2942ee08944d310940f618c20c7f to your computer and use it in GitHub Desktop.
Download ZIP
Cursor Talk to Figma MCP Setup Guide for AI Agents.
Raw
CURSOR_FIGMA_MCP_SETUP_GUIDE.md

Cursor Talk to Figma MCP Setup Guide for AI Agents

🤖 AI Agent Decision Flow

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
Loading

🎯 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.

# 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:

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
Loading

🎨 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):

graph LR
    A1[🍺 Homebrew Check] --> A2[📦 Install Dependencies]
    A2 --> A3[⚙️ MCP Setup]  
    A3 --> A4[✅ Ready for WebSocket]
Loading

For Method B (Cursor-Only):

graph LR
    B1[🖥️ Project Already Open] --> B2[📖 Setup Dependencies]
    B2 --> B3[⚙️ MCP Setup] 
    B3 --> B4[✅ Ready for WebSocket]
Loading

📍 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:

# 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

# 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:

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
Loading 

### 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

# 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:

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
Loading 

### 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

# 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:

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
Loading

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"
  1. 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:

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
Loading

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:

    # 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

# 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

# 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

# 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

# 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

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)

# 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

# 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment