spex-mcp/docs/MODULES.md

MCP server for Figma SpeX plugin and Cursor AI integration

# Module Separation Summary

This document summarizes how the SpeX MCP Server functions have been divided into two distinct types: Figma SpeX Plugin functions and MCP Cursor AI tools.

## 🔄 Refactoring Overview

The monolithic `src/index.js` has been refactored into a modular architecture:

### Before (Monolithic)

```
src/index.js (212 lines)
├── Server setup
├── WebSocket handling  
├── MCP tool definitions
├── Tool handlers
├── Figma SpeX message handling
└── Connection management
```

### After (Modular)

```
src/
├── index.js (95 lines) - Main orchestration
├── figma-functions.js (120+ lines) - Figma SpeX plugin management
└── mcp-tools.js (70+ lines) - MCP tools for Cursor AI
```

## 📁 Module Breakdown

### 1. `src/figma-functions.js` - Figma SpeX Plugin Functions

**Purpose**: Handle all Figma SpeX plugin communication via WebSocket

**Key Features**:

- ✅ WebSocket server management (port 8080)
- ✅ Connection lifecycle management
- ✅ Message routing and handling
- ✅ SpeX plugin communication protocols
- ✅ Broadcasting to multiple SpeX plugins

**Functions**:

- `setupWebSocketServer()` - Initialize WebSocket server
- `handleFigmaMessage(ws, message)` - Route incoming messages
- `pullSpecsFromFigma()` - Request design specifications
- `broadcastToFigmaPlugins(message)` - Send to all SpeX plugins
- `shutdown()` - Graceful shutdown

**Message Types**:

- `hello-world` - Connectivity test
- `specs-data` - Design specifications

### 2. `src/mcp-tools.js` - MCP Cursor AI Tools

**Purpose**: Provide tools for Cursor AI via Model Context Protocol

**Key Features**:

- ✅ MCP tool definitions and schemas
- ✅ Tool execution handlers
- ✅ Error handling and responses

**Available Tools**:

- `hello-world` - Test connectivity
- `pull-specs` - Get design specifications

### 3. `src/index.js` - Main Orchestration

**Purpose**: Coordinate both Figma SpeX and MCP functionalities

**Key Features**:

- ✅ Initialize both managers
- ✅ Setup MCP request handlers
- ✅ Lifecycle management
- ✅ Graceful shutdown
- ✅ Error handling

## 🔗 Inter-module Communication

```
Cursor AI ↔ MCPToolsManager ↔ FigmaPluginManager ↔ Figma SpeX Plugins
```

- **MCPToolsManager** receives requests from Cursor AI
- **MCPToolsManager** calls **FigmaPluginManager** methods
- **FigmaPluginManager** communicates with Figma SpeX plugins via WebSocket
- Results flow back through the chain

## 📊 Benefits of Separation

### 1. **Maintainability**

- ✅ Clear separation of concerns
- ✅ Easier to debug specific functionality
- ✅ Independent testing of modules

### 2. **Extensibility**

- ✅ Add new Figma SpeX functions without touching MCP code
- ✅ Add new MCP tools without touching WebSocket code
- ✅ Simple and focused architecture

### 3. **Reusability**

- ✅ FigmaPluginManager can be used in other SpeX projects
- ✅ MCPToolsManager patterns can be reused
- ✅ Clean separation allows for easy integration

### 4. **Testing**

- ✅ Unit test each module independently
- ✅ Mock dependencies easily
- ✅ Focused integration tests

## 🚀 Usage Examples

### Adding a New Figma SpeX Function

```javascript
// In figma-functions.js
handleFigmaMessage(ws, message) {
    switch (message.name || message.type) {
        // ... existing cases
        case 'new-spex-function':
            this.handleNewSpeXFunction(message.data);
            break;
    }
}

handleNewSpeXFunction(data) {
    // Implementation
}
```

### Adding a New MCP Tool

```javascript
// In mcp-tools.js
getToolsList() {
    return [
        // ... existing tools
        {
            name: "new-mcp-tool",
            description: "Description of new tool",
            inputSchema: { /* schema */ }
        }
    ];
}

async handleToolCall(name, args) {
    switch (name) {
        // ... existing cases
        case "new-mcp-tool":
            return this.handleNewMCPTool(args);
    }
}
```

## 📈 Future Enhancements

With this simplified modular structure, we can easily add:

1. **Database Integration** - Store design specs persistently
2. **Authentication** - Secure WebSocket connections
3. **Plugin Marketplace** - Support multiple SpeX plugin types
4. **Real-time Sync** - Live updates between Figma SpeX and code
5. **Version Control** - Track design changes over time
6. **Team Collaboration** - Multi-user design workflows
7. **Enhanced Tools** - More sophisticated MCP tools
8. **Monitoring** - Health checks and metrics

## 🎯 Current Architecture Benefits

The simplified architecture provides:

1. **Focus** - Core functionality without unnecessary complexity
2. **Reliability** - Fewer moving parts, fewer potential issues
3. **Performance** - Lightweight and efficient
4. **Clarity** - Easy to understand and maintain
5. **Flexibility** - Room to grow in multiple directions

## 🔧 Next Steps

1. **Testing** - Add comprehensive unit tests for each module
2. **Documentation** - Expand API documentation with examples
3. **Examples** - Create more Figma SpeX plugin integration examples
4. **Performance** - Optimize WebSocket handling and message processing
5. **Security** - Add authentication and input validation
6. **Monitoring** - Add logging, metrics, and health checks