FigmaMind MCP Server

Verified
Overview InspectNew Schema Related Servers Reviews Score
FigmaMind
docs
# Technical Documentation - FigmaMind

This technical document consolidates detailed information about the internal workings of FigmaMind, combining information previously distributed across multiple files.

## System Architecture

The system consists of the following main components:

1. **Figma Data Extractor**: Responsible for fetching data from the Figma API
2. **Component Processor**: Analyzes and transforms the found components
3. **Transformers**: Set of specific rules for each component type
4. **REST API**: Interface for accessing transformation services
5. **Utilities**: Helper functions for data manipulation

```
┌─────────────────┐     ┌───────────────────┐     ┌────────────────┐
│                 │     │                   │     │                │
│  Figma API      │────▶│  Extractor        │────▶│  Processor     │
│                 │     │                   │     │                │
└─────────────────┘     └───────────────────┘     └────────┬───────┘
                                                           │
                                                           ▼
┌─────────────────┐     ┌───────────────────┐     ┌────────────────┐
│                 │     │                   │     │                │
│  Client         │◀────│  REST API         │◀────│ Transformers   │
│                 │     │                   │     │                │
└─────────────────┘     └───────────────────┘     └────────────────┘
```

## Data Processing Flow

### 1. Figma Data Extraction

The process begins with the extraction of data from Figma through its official API.

#### 1.1 Input Parameters
- **Figma URL**: URL of the Figma file or design (e.g., `https://www.figma.com/design/ID/Name?node-id=X`)
- **API Token**: Personal access token for the Figma API

#### 1.2 Extraction Process
1. **URL Analysis**: The system extracts the file key and node ID (if present) from the URL
2. **API Request**: Using Axios to make HTTP requests to the Figma API
3. **Response Processing**: Processing the API response and extracting relevant nodes

### 2. Component Processing

The processor analyzes the node tree returned by the Figma API, identifies components, and applies specific transformers.

#### 2.1 Component Identification

During tree traversal, the system identifies relevant components based on criteria such as:
- Node type (`INSTANCE`, `FRAME`, etc.)
- Component name (containing terms like "button", "header", etc.)
- Component-specific properties

#### 2.2 Position Normalization

To facilitate precise interface reconstruction, the system normalizes component positions:
- Converts absolute coordinates to screen-relative
- Calculates relative positions as percentages of screen width/height
- Determines horizontal alignment (left, center, right)
- Calculates margins relative to screen edges

#### 2.3 Organization into Logical Sections

The system groups components into logical sections based on:
- Vertical positioning
- Spacing between components
- Component type
- Hierarchical relationships

### 3. Application of Transformers

For each identified component, the system applies specific transformers based on the component type.

#### 3.1 Available Transformers
- **Button**: Extracts text, style, and button states
- **Header**: Processes title, navigation buttons, and other elements
- **Input**: Extracts placeholder, type, and field states
- **Keyboard**: Identifies keyboard type and special keys
- **List**: Processes list items and their properties
- **OnboardingInput**: Advanced version for input fields with labels and validation
- **RadioButton**: Extracts selection states and labels
- **OnboardCodeField**: For code input fields with special formatting

### 4. Output Formatting

The final result is a structured JSON with:
- Figma file metadata (name, version, etc.)
- Screen dimensions
- Components organized by type and section
- Specific properties for each component
- Normalized positioning information

## Implementation Details

### Main Processor (processor.js)

The main processor contains the following key functions:

1. **processData**: Main function that orchestrates all processing
2. **extractComponents**: Identifies components in the Figma tree
3. **processComponent**: Processes an individual component
4. **normalizeComponentPositions**: Normalizes component coordinates
5. **determineAlignment**: Calculates component alignment
6. **groupComponentsIntoSections**: Groups components into logical sections

### Transformer System

Transformers are implemented as functions that receive a component and return transformed properties:

```javascript
function transformButton(component) {
  // Extract relevant button properties
  const buttonText = extractTextFromComponent(component);
  const buttonStyle = determineButtonStyle(component);
  
  return {
    text: buttonText,
    style: buttonStyle,
    states: extractComponentStates(component)
  };
}
```

### Reusable Utilities

The system includes several utility functions for common tasks:
- **extractText**: Extracts text from text nodes
- **hasProperty**: Checks if a component has a certain property
- **getPropertyValue**: Gets the value of a property
- **formatObject**: Removes null/empty properties from objects

## REST API

The REST API exposes the following endpoints:

### GET /api
Returns information about the API, including version and available endpoints.

### POST /api/transform
Transforms Figma components from a URL.

#### Request Parameters:
```json
{
  "figmaUrl": "https://www.figma.com/design/ID/Name?node-id=X"
}
```

#### Success Response:
```json
{
  "success": true,
  "message": "Processed X components",
  "source": "Figma URL",
  "data": {
    // Processed data
  }
}
```

### GET /api/assets/:filename
Returns a specific asset.

## Asset Extraction

The system supports automatic extraction of images and icons from components.

### Asset Identification
During processing, the system identifies nodes that contain images or visual elements.

### Download and Storage
For each identified asset, the system:
1. Requests the export URL from the Figma API
2. Downloads the image and saves it in `examples/output/assets/`
3. Adds references to assets in the output JSON

### Asset Access
Assets can be accessed via the API through the `/api/assets/:filename` endpoint.

## Optimization Techniques

To improve system performance, several techniques are used:

1. **Selective Processing**: Using node-id to process only specific parts
2. **Efficient Traversal**: Ignoring hidden nodes (when appropriate)
3. **Request Caching**: Avoiding repeated requests to the Figma API
4. **Asynchronous Processing**: Using promises for parallel operations

## Security Considerations

- API tokens are stored in environment variables
- Input validation to prevent code injection
- File path sanitization to prevent directory traversal

## Extensibility

The system was designed to be easily extensible:

### Adding New Transformers
To add support for a new component type:

1. Create a transformer function in the transformer file
2. Add the function to the component type mapping
3. Update the type identification function to recognize the new component

### Support for New Output Formats
It's possible to extend the system to support formats other than JSON:

1. Create a new serializer in the utilities module
2. Add a format parameter to the API
3. Implement the logic to convert the processed object to the desired format

## Testing and Validation

To ensure the correct functioning of the system, tests were performed with various real Figma components.

The test results confirmed that the system:
- Correctly extracts components from Figma
- Processes all supported component types
- Generates valid and well-structured JSON
- Maintains the fidelity of the original components

## Best Practices for Use

To get the best results with the system:

1. Organize your components in Figma using descriptive names
2. Use consistent conventions for component types
3. Group related components in frames
4. Use node-id to process only specific parts
5. Check the resulting JSON to ensure all necessary properties have been extracted 