zhongwei/gh-alekspetrov-navigator

Fork 0

Files

Zhongwei Li 38e80921c8 Initial commit

2025-11-29 17:51:59 +08:00

7.7 KiB

Raw Blame History

Navigator Product Design Skill - Installation Guide

Quick setup guide for the product-design skill with Figma MCP integration.

Prerequisites

Required

Python 3.10+

python3 --version  # Should be 3.10 or higher

Figma Desktop App
- Download: https://www.figma.com/downloads/
- Must be running during design reviews
Figma Account
- Free or paid account
- Logged into Figma Desktop

Optional (Enhanced Features)

Figma Enterprise - For Code Connect mappings (automatic component detection)
Tailwind CSS - For design token integration
Storybook - For visual regression testing

Installation Methods

Method 1: Automatic Setup (Recommended)

Run the automated setup script:

cd skills/product-design
./setup.sh

This will:

✅ Check Python version (3.10+ required)
✅ Create virtual environment
✅ Install dependencies (mcp>=1.2.1)
✅ Verify Figma Desktop is running
✅ Test MCP connection

Expected output:

==========================================
Navigator Product Design Skill - Setup
==========================================

[1/5] Checking Python version...
✅ Python 3.13.7

[2/5] Setting up Python environment...
✅ Virtual environment created

[3/5] Installing Python dependencies...
✅ Dependencies installed (mcp>=1.2.1)

[4/5] Checking Figma Desktop status...
✅ Figma MCP server detected (port 3845)

[5/5] Testing Figma MCP connection...
✅ Successfully connected to Figma MCP server
   Found 6 tools:
     - get_design_context
     - get_variable_defs
     - get_code_connect_map
     - get_screenshot
     - get_metadata
     - create_design_system_rules

==========================================
✅ Setup Complete!
==========================================

Method 2: Manual Installation

If the automatic script fails or you prefer manual setup:

Step 1: Install Python Dependencies

cd skills/product-design

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Step 2: Enable Figma MCP Server

Open Figma Desktop app
Go to Figma → Preferences (macOS) or File → Settings (Windows/Linux)
Find "Enable local MCP Server" option
Toggle ON
You should see confirmation: "MCP server running at http://127.0.0.1:3845/mcp"

Step 3: Verify Connection

cd functions
python3 test_mcp_connection.py

Expected output:

✅ Successfully connected to Figma MCP server
   Found 6 tools:
     - get_design_context
     - get_variable_defs
     - ...

Troubleshooting

"Figma Desktop not running or MCP not enabled"

Symptoms:

❌ Figma Desktop not running or MCP not enabled
   Could not connect to Figma Desktop MCP server.

Solutions:

Check Figma is running:

# macOS
ps aux | grep Figma

# Should show Figma processes

Enable MCP server:
- Figma → Preferences → Enable local MCP Server
- Look for confirmation message

Verify port is open:

curl http://127.0.0.1:3845/mcp

# Should return JSON response (even if error)
# Example: {"jsonrpc":"2.0","error":{"code":-32001,"message":"Invalid sessionId"},"id":null}

Check Figma version:
- MCP requires Figma Desktop v116.0.0+
- Update if necessary: Figma → Help → Check for Updates

"MCP SDK not installed"

Symptoms:

ImportError: MCP SDK not installed. Install with: pip install mcp

Solutions:

Activate virtual environment (if using):

source skills/product-design/venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```

Verify installation:

python3 -c "import mcp; print(mcp.__version__)"
# Should print: 1.2.1 or higher

"Python 3.10+ required"

Symptoms:

❌ Python 3.10+ required (found 3.9.6)

Solutions:

Install Python 3.10+:

# macOS (Homebrew)
brew install python@3.13

# Ubuntu/Debian
sudo apt install python3.13

# Windows
# Download from python.org

Use specific Python version:

python3.13 -m venv venv
source venv/bin/activate

"Port 3845 already in use"

Symptoms:

Figma MCP server won't start
Connection errors

Solutions:

Check what's using port 3845:
```
lsof -i :3845
```

Kill conflicting process:

# If another process is using the port
kill -9 <PID>

Restart Figma Desktop:
- Quit Figma completely
- Restart app
- Re-enable MCP server

Verifying Installation

Quick Test

cd skills/product-design/functions
python3 -c "
import asyncio
from figma_mcp_client import get_figma_variables

async def test():
    try:
        # This will use currently selected node in Figma
        vars = await get_figma_variables()
        print(f'✅ Connected! Found {len(vars)} variables')
    except Exception as e:
        print(f'❌ Error: {e}')

asyncio.run(test())
"

Full Test

cd skills/product-design
./setup.sh

What Gets Installed

Python Packages

mcp>=1.2.1          # Official MCP SDK for Figma integration
anyio>=4.0.0        # Async I/O (transitive dependency)
httpx>=0.25.0       # HTTP client (transitive dependency)
pydantic>=2.0.0     # Data validation (transitive dependency)

File Structure After Installation

skills/product-design/
├── venv/                           # Virtual environment (created)
│   ├── bin/
│   ├── lib/
│   └── ...
├── functions/
│   ├── figma_mcp_client.py        # MCP client wrapper ✨ NEW
│   ├── test_mcp_connection.py     # Connection test ✨ NEW
│   ├── design_analyzer.py         # Existing functions (to be refactored)
│   └── ...
├── requirements.txt                # Dependencies ✨ NEW
├── setup.sh                        # Setup script ✨ NEW
├── INSTALL.md                      # This file ✨ NEW
└── SKILL.md                        # Skill documentation

Next Steps

After successful installation:

Try the skill:

User: "Review this Figma design: https://figma.com/file/..."

Read documentation:
- SKILL.md - Complete skill guide
- functions/figma_mcp_client.py - API documentation

Set up design system (optional):

mkdir -p .agent/design-system/reviews
touch .agent/design-system/design-tokens.json
touch .agent/design-system/ui-kit-inventory.json

Uninstalling

To remove the skill:

cd skills/product-design

# Remove virtual environment
rm -rf venv

# Disable MCP server in Figma
# Figma → Preferences → Disable local MCP Server

Support

Documentation

Skill Guide: SKILL.md
MCP Client API: functions/figma_mcp_client.py
Figma MCP Docs: https://help.figma.com/hc/en-us/articles/32132100833559

Common Issues

Connection errors: Ensure Figma Desktop running and MCP enabled
Import errors: Activate virtual environment: source venv/bin/activate
Version errors: Upgrade Python to 3.10+

Reporting Issues

Open issue at: https://github.com/navigator-plugin/navigator/issues

Include:

Python version: python3 --version
Figma version: Figma → Help → About Figma
Error message and full stack trace
Output from: python3 functions/test_mcp_connection.py

Last Updated: 2025-10-22 Navigator Version: 3.3.1 Skill Version: 1.0.0 MCP SDK Version: 1.2.1+

7.7 KiB Raw Blame History

Navigator Product Design Skill - Installation Guide

Prerequisites

Required

Optional (Enhanced Features)

Installation Methods

Method 1: Automatic Setup (Recommended)

Method 2: Manual Installation

Step 1: Install Python Dependencies

Step 2: Enable Figma MCP Server

Step 3: Verify Connection

Troubleshooting

"Figma Desktop not running or MCP not enabled"

"MCP SDK not installed"

"Python 3.10+ required"

"Port 3845 already in use"

Verifying Installation

Quick Test

Full Test

What Gets Installed

Python Packages

File Structure After Installation

Next Steps

Uninstalling

Support

Documentation

Common Issues

Reporting Issues

7.7 KiB

Raw Blame History