spex-mcp/docs/GENERATE_COMPOSE_UI_TOOL.md

MCP server for Figma SpeX plugin and Cursor AI integration

# Generate Compose UI Tool

This document describes the `generate-compose-ui` MCP tool, which provides a structured prompt template for generating Jetpack Compose UI code from Figma design specifications.

## Overview

The `generate-compose-ui` tool implements a comprehensive 6-step workflow that guides developers through the process of converting Figma design specs into production-ready Jetpack Compose UI code.

## Usage

### Tool Parameters

- **`source_code_file`** (required): The target file path where the generated Compose UI code should be written
  - Example: `'app/src/main/java/com/example/ui/screens/HomeScreen.kt'`

### Example Usage

```javascript
// Call the MCP tool
await mcpToolsManager.handleToolCall('generate-compose-ui', {
    source_code_file: 'app/src/main/java/com/example/ui/screens/LoginScreen.kt'
});
```

### From Cursor AI

When using the tool in Cursor AI, simply call:

```
generate-compose-ui with source_code_file: "path/to/your/screen.kt"
```

## Workflow Steps

The tool generates a structured prompt that guides through these steps:

### ✅ Step 1: Understand the Design Context & Structure
1. **Call `get-page-thumbnail`** - Visual understanding of the design
2. **Call `get-spec-files-manifest`** - Get list of available specification files
3. **Call `get-specs-readme`** - Understand file structure and conventions

### ✅ Step 2: Parse the Screen Specification
- Retrieve and analyze the main screen specification file
- Construct UI hierarchy diagram (non-mermaid format)
- Identify all component instances and references

### ✅ Step 3: Identify Code Component Definitions
- Check for existing components with `codeFilePath` fields
- Examine `@Preview` functions for component patterns
- Identify new components that need to be generated
- Create component mapping table

### ✅ Step 4: Generate Compose UI Code
- Generate main screen composable function
- Create new component implementations
- Add `@Preview` functions for testing

### ✅ Step 5: Adjustments with Design Screenshot
- Compare generated UI with design screenshot
- Make alignment and accuracy adjustments
- Validate code with Android Studio MCP tools

### ✅ Step 6: Summary
- Generate comprehensive component usage report
- Categorize components as used/unused
- Provide explanations for unused components

## Key Features

### 🎯 **Structured Workflow**
- Methodical approach ensures no steps are missed
- Clear dependencies between steps
- Consistent results across different designs

### 📋 **Comprehensive Analysis**
- Thorough examination of design specifications
- Cross-referencing with existing code components
- Detailed component mapping and hierarchy

### 🔧 **Production-Ready Code**
- Generates complete Compose implementations
- Includes proper `@Preview` functions
- Follows Android development best practices

### 🎨 **Visual Validation**
- Uses design screenshots for accuracy
- Compares generated UI with intended design
- Ensures visual fidelity

## Integration with SpeX MCP

The tool leverages the full SpeX MCP ecosystem:

- **Design Specs**: Retrieved via `get-a-spec-file`
- **Visual Context**: Obtained through `get-page-thumbnail`
- **File Structure**: Understood via `get-specs-readme` and `get-spec-files-manifest`
- **Real-time Updates**: Connected to live Figma design data

## Example Output

When called with a source file, the tool generates a comprehensive prompt like:

```
🎯 Task: Generate Jetpack Compose UI code into `app/src/main/java/com/example/ui/screens/HomeScreen.kt` from Figma design specs served via `spex-mcp`.

I will provide:
- Access to the `spex-mcp` server (current design context is already selected).
- A screenshot showing the expected visual output of the screen.

✅ **Step 1: Understand the Design Context & Structure**
1. Call `get-page-thumbnail`
   - This retrieves the thumbnail image of the design screen...
   
[... detailed step-by-step instructions ...]

**Now please begin with Step 1: Call `get-page-thumbnail` to understand the design context.**
```

## Benefits

### For Developers
- **Reduced Manual Work**: Automated prompt generation
- **Consistent Process**: Same workflow for every design
- **Quality Assurance**: Built-in validation steps

### For Teams
- **Standardized Approach**: Everyone follows the same process
- **Knowledge Sharing**: Embedded best practices
- **Faster Onboarding**: Clear step-by-step guidance

### For Projects
- **Higher Code Quality**: Systematic approach reduces errors
- **Better Design Fidelity**: Visual validation ensures accuracy
- **Maintainable Code**: Structured generation process

## Technical Implementation

The tool is implemented as part of the `MCPToolsManager` class in `src/local/mcp-tools.js`:

- **Tool Registration**: Added to the tools list with proper schema
- **Handler Implementation**: `handleGenerateComposeUI()` method
- **Error Handling**: Validates required parameters
- **Template Generation**: Creates dynamic prompt based on target file

## Testing

The implementation includes comprehensive tests in `test/test-generate-compose-ui.js`:

- Parameter validation
- Tool registration verification
- Template generation testing
- Error handling validation

Run tests with:
```bash
cd spex-mcp
node test/test-generate-compose-ui.js
```