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

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