spex-mcp/docs/MCP_INTEGRATION.md

MCP server for Figma SpeX plugin and Cursor AI integration

# MCP Integration Guide

This guide covers how to configure Cursor AI with SpeX MCP server in both local and remote modes.

## 🏠 Local Mode Configuration

For individual development and testing:

### ~/.cursor/mcp.json
```json
{
  "mcpServers": {
    "spex-local-dev": {
      "command": "node",
      "args": [
        "/path/to/spex-mcp/src/local/index.js",
        "--port",
        "8080",
        "--force"
      ]
    }
  }
}
```

### Alternative using npm package
```json
{
  "mcpServers": {
    "spex-mcp-npm": {
      "command": "npx",
      "args": [
        "-y",
        "spex-mcp-local",
        "--port",
        "8082",
        "--force"
      ]
    }
  }
}
```

## 🌐 Remote Mode Configuration

For production and team collaboration:

### ~/.cursor/mcp.json
```json
{
  "mcpServers": {
    "spex-mcp-remote": {
      "command": "node",
      "args": [
        "/path/to/spex-mcp/src/remote/index.js",
        "--session-id",
        "TestSession123",
        "--client-type",
        "mcp-client",
        "--server-url",
        "wss://spex-figma-mcp.onrender.com"
      ]
    }
  }
}
```

### Development with local remote server
```json
{
  "mcpServers": {
    "spex-mcp-dev": {
      "command": "node",
      "args": [
        "/path/to/spex-mcp/src/remote/index.js",
        "--client-type",
        "mcp-client",
        "--session-id",
        "TestSession123",
        "--port",
        "8080",
        "--force"
      ]
    }
  }
}
```

## 🔧 Complete Configuration Example

Here's a complete `~/.cursor/mcp.json` with all modes:

```json
{
  "mcpServers": {
    "spex-mcp-remote": {
      "command": "node",
      "args": [
        "/home/henry/Code/spex/spex-mcp/src/remote/index.js",
        "--session-id",
        "TestSession123",
        "--client-type",
        "mcp-client",
        "--server-url",
        "wss://spex-figma-mcp.onrender.com"
      ]
    },
    "spex-mcp-dev": {
      "command": "node",
      "args": [
        "/home/henry/Code/spex/spex-mcp/src/remote/index.js",
        "--client-type",
        "mcp-client",
        "--session-id",
        "TestSession123",
        "--port",
        "8080",
        "--force"
      ]
    },
    "spex-local-dev": {
      "command": "node",
      "args": [
        "/home/henry/Code/spex/spex-mcp/src/local/index.js",
        "--port",
        "8080",
        "--force"
      ]
    },
    "spex-mcp-npm": {
      "command": "npx",
      "args": [
        "-y",
        "spex-mcp",
        "--port",
        "8082",
        "--force"
      ]
    }
  }
}
```

## 🚀 Quick Start

### 1. For Local Development
```bash
# Start local MCP server
node src/local/index.js --port 8080 --force

# Or use npm script
npm run start:local
```

### 2. For Remote Development
```bash
# Start remote MCP client connecting to cloud server
node src/remote/index.js --client-type mcp-client --session-id your-session-id --server-url wss://your-server.com

# Or use npm script (configure server URL first)
npm run start:remote
```

### 3. For Cloud Deployment
```bash
# Deploy the remote server to cloud
npm start  # This now points to src/remote/index.js
```

## 🔍 Troubleshooting

### Port Conflicts
```bash
# Local mode: Use --force to kill existing processes
node src/local/index.js --port 8080 --force
```

### Session Issues
```bash
# Remote mode: Ensure unique session IDs
node src/remote/index.js --session-id "session_$(date +%s)" --client-type mcp-client
```

### WebSocket Connection Issues
```bash
# Check server status
curl https://your-server.com/health

# Test WebSocket connection
npx wscat -c "wss://your-server.com?session-id=test&type=mcp-client"
```

## 📊 Architecture Comparison

| Aspect | Local Mode | Remote Mode |
|--------|------------|-------------|
| **Entry Point** | `src/local/index.js` | `src/remote/index.js` |
| **Session Management** | None | Required for security |
| **WebSocket URL** | `ws://localhost:8080` | `wss://your-server.com` |
| **Health Check** | Not available | `GET /health` |
| **Deployment** | Local only | Cloud compatible |
| **Client Types** | Single | `plugin` or `mcp-client` |

## 🔐 Security Best Practices

### Remote Mode
- Always use unique session IDs for each user
- Use WSS (secure WebSocket) in production
- Monitor health check endpoint
- Implement proper session cleanup

### Local Mode
- Use `--force` to handle port conflicts
- Consider firewall rules for localhost access
- Monitor resource usage for long-running sessions

## 🎯 Usage Recommendations

**Use Local Mode when:**
- Individual development
- Testing and debugging
- Working offline
- Simple setup required

**Use Remote Mode when:**
- Team collaboration
- Production deployment
- Multi-user environments
- Cloud infrastructure available