spex-mcp/README.md

MCP server for Figma SpeX plugin and Cursor AI integration

# SpeX MCP Local Mode

This directory contains the **Local Development Mode** implementation for SpeX MCP server, restored from stable version **1.5.0** (commit `d1536d965cb4b02262b8a659611375dfb4a4acc7`).

## 📍 Local Development Mode

**Best for**: Individual development, local testing, direct plugin connections

### Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Local Development Mode                   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    stdio     ┌─────────────┐   WebSocket   │
│  │ Cursor AI   │◄────────────►│ MCP Server  │◄──────────┐   │
│  │             │              │ (Local)     │           │   │
│  └─────────────┘              └─────────────┘           │   │
│                                       │                 │   │
│                                       │ localhost:8080  │   │
│                                       ▼                 │   │
│                               ┌─────────────┐           │   │
│                               │ WebSocket   │───────────┘   │
│                               │ Server      │               │
│                               │ (Stateless) │               │
│                               └─────────────┘               │
│                                       │                     │
│                                       │ passthrough         │
│                                       ▼                     │
│                               ┌─────────────┐               │
│                               │ SpeX Plugin │               │
│                               │ (Figma)     │               │
│                               └─────────────┘               │
└─────────────────────────────────────────────────────────────┘
```

### Files Structure

- **`index.js`** - Main server entry point with MCP and WebSocket server setup
- **`figma-functions.js`** - WebSocket server and Figma plugin communication manager
- **`mcp-tools.js`** - MCP tools handler for Cursor AI integration

### Usage

```json
"spex-npm-local": {
    "command": "npx",
    "args": [
    "-y",
    "spex-mcp",
    "--mode",
    "local",
    "--port",
    "8080",
    "--force"
    ]
}
```
Note:
- port: specify custom port of websocket server that plugin connect to
- force: force using port
```


### Data Flow

`Cursor AI ↔ MCP Server ↔ Local WebSocket Server ↔ SpeX 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
6. **`generate-compose-ui`** - 🎯 **Prompt Template Tool** - Generates a structured 6-step workflow prompt for creating Jetpack Compose UI code from Figma design specs. Takes a `source_code_file` parameter and provides step-by-step guidance for the design-to-code process. See [Generate Compose UI Tool Documentation](docs/GENERATE_COMPOSE_UI_TOOL.md) for details.

### Key Features

- **Direct Plugin Connection**: WebSocket server runs locally on port 8080 (default)
- **MCP Protocol**: Full support for Cursor AI integration via stdio transport
- **File Upload Support**: Binary file transfer handling with progress tracking
- **Image Support**: Base64 image injection for Cursor AI
- **Port Management**: Automatic port conflict resolution with `--force` option
- **Graceful Shutdown**: Proper cleanup of connections and resources

### Restoration Notes

This implementation was restored from commit `d1536d965cb4b02262b8a659611375dfb4a4acc7` which represents the stable **version 1.5.0** of the SpeX MCP server. The code has been placed in the `@/local` folder as requested.

The local mode provides the most direct and reliable connection between Cursor AI and the Figma SpeX plugin, making it ideal for development and testing scenarios.