spex-mcp/src/remote/README.md

MCP server for Figma SpeX plugin and Cursor AI integration

# SpeX MCP Remote Mode

This directory contains the **Remote Mode** implementation for SpeX MCP server, designed for cloud deployment and remote plugin connections.

## 🌐 Remote Mode

**Best for**: Cloud deployment, remote access, production environments, team collaboration

### Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Remote Mode Architecture                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    stdio     ┌─────────────┐   WebSocket   │
│  │ Cursor AI   │◄────────────►│ MCP Client  │◄──────────┐   │
│  │             │              │ (Local)     │           │   │
│  └─────────────┘              └─────────────┘           │   │
│                                       │                 │   │
│                                       │ WSS/HTTPS       │   │
│                                       ▼                 │   │
│                               ┌─────────────┐           │   │
│                               │ Remote      │───────────┘   │
│                               │ WebSocket   │               │
│                               │ Server      │               │
│                               │ (Cloud)     │               │
│                               └─────────────┘               │
│                                       │                     │
│                                       │ WebSocket           │
│                                       ▼                     │
│                               ┌─────────────┐               │
│                               │ SpeX Plugin │               │
│                               │ (Figma)     │               │
│                               └─────────────┘               │
└─────────────────────────────────────────────────────────────┘
```

### Files Structure

- **`index.js`** - Main server entry point with remote session management
- **`figma-functions.js`** - Advanced WebSocket server with session-based routing
- **`mcp-tools.js`** - MCP tools handler with WebSocket communication
- **`README.md`** - This documentation file

### Key Features

#### Session Management
- **Session-based routing** prevents cross-client data leakage
- **Secure session IDs** for client identification
- **Connection type validation** (plugin vs mcp-client)
- **Health check endpoints** for monitoring

#### Remote WebSocket Server
- **HTTP + WebSocket server** for health checks and connections
- **Cloud deployment ready** with PORT environment variable support
- **Session query parameters** for connection routing
- **Automatic cleanup** of disconnected sessions

#### Enhanced Security
- **Session isolation** ensures data goes to correct clients
- **Connection validation** prevents unauthorized access
- **Graceful error handling** with proper error responses
- **Resource cleanup** on connection failures

### Usage

#### Deploy Remote Server
```bash
# Deploy to cloud (Render.com example)
node src/remote/index.js

# Custom port for local testing
node src/remote/index.js --port 3000

# Force kill existing processes
node src/remote/index.js --force
```

#### Connect MCP Client
```bash
# Connect to remote server
node src/remote/index.js --client-type mcp-client --session-id <SESSION_ID> --server-url wss://your-server.com

# Connect to local server for testing
node src/remote/index.js --client-type mcp-client --session-id TestSession123 --server-url ws://localhost:8080
```

### Data Flow

`Cursor AI ↔ Local MCP Client ↔ Remote WebSocket Server ↔ Figma Plugin`

### Available MCP Tools

1. **`hello-world`** - Returns a simple hello world message
2. **`get-specs-readme`** - Fetches README.md from SpeX plugin
3. **`get-spec-files-manifest`** - Fetches manifest.yaml file
4. **`get-a-spec-file`** - Fetches specific spec file by filename
5. **`get-page-thumbnail`** - Fetches page thumbnail image

### WebSocket Connection URLs

#### For Figma Plugins
```
ws://your-server.com?session-id=<SESSION_ID>&type=plugin
```

#### For MCP Clients
```
ws://your-server.com?session-id=<SESSION_ID>&type=mcp-client
```

### Health Check

The remote server provides a health check endpoint:

```
GET http://your-server.com/health
```

Response:
```json
{
  "status": "healthy",
  "timestamp": "2025-01-20T10:30:00.000Z",
  "version": "1.5.1",
  "uptime": 3600,
  "environment": "production",
  "connections": 4,
  "sessions": 2
}
```

### Environment Variables

- **`PORT`** - Server port (default: 8080)
- **`NODE_ENV`** - Environment mode (development/production)

### Command Line Options

```bash
Options:
  --port <number>         WebSocket server port (default: 8080, or $PORT env var)
  --session-id <string>   Session ID for MCP client connections
  --client-type <type>    Client type: 'plugin' or 'mcp-client'
  --server-url <url>      Remote server URL for MCP client connections
  --force                 Force kill any process using the port before starting
  --version, -v           Show version number
  --help, -h              Show this help message
```

### Deployment

This remote mode is designed for cloud deployment platforms like:

- **Render.com** (recommended)
- **Railway**
- **Heroku**
- **DigitalOcean App Platform**
- **AWS/GCP/Azure**

The server automatically binds to `0.0.0.0` and uses the `PORT` environment variable for cloud compatibility.

### Security Considerations

- Sessions are isolated to prevent data cross-contamination
- WebSocket connections require valid session IDs
- Health checks don't expose sensitive information
- Graceful error handling prevents information leakage
- Automatic resource cleanup prevents memory leaks