# glips/figma-context-mcp architecture

> Architecture diagram of the GitHub repository glips/figma-context-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/glips/figma-context-mcp
- Repository: https://github.com/glips/figma-context-mcp

## Overview

##### Project Type and Purpose
- It’s a focused, backend server designed to integrate Figma design data with Cursor via the Model Context Protocol (MCP).
- Its main purpose is to fetch, simplify, and translate Figma API responses so that Cursor can more effectively convert designs into code.

##### Analyzing the File Structure
- Top-level files (like .env.example, package.json, tsconfig.json) and configuration files indicate a standard Node/TypeScript setup.
- The “src” directory houses the core application modules. Notice separate entry files like cli.ts (which handles command-line operations), server.ts (which likely sets up the HTTP or SSE server), and index.ts (which may be the main entry point).
- A “config.ts” file suggests a dedicated module for environment configuration and parsing command-line arguments.
- Subdirectories under “src” include:
– services: Contains integrations with external APIs; for example, figma.ts likely interacts with the Figma API and simplify-node-response.ts processes the API response data.
– transformers: Contains logic for transforming the complex Figma API response into a simpler layout, as in layout.ts.
– types: Contains TypeScript interfaces and types for Figma-related data.
– utils: Likely includes helper functions such as identity.ts which may be used across the application.

##### Key Components and Their Roles
a. Entry Point and CLI Interface:
- The CLI (src/cli.ts) accepts command-line arguments (such as the Figma API key and port). This enables quick startup via npm/yarn.
b. Configuration Module:
- src/config.ts manages environment variables and command-line arguments. This module controls runtime settings like API keys and ports.
c. Server Module:
- src/server.ts sets up the HTTP/SSE endpoints and REST-like routes to serve requests from Cursor. It handles endpoints like /sse and /messages.
d. Service Layer:
- src/services/figma.ts is responsible for communicating with the Figma API to fetch design data.
- src/services/simplify-node-response.ts processes the fetched data to retain only the necessary layout and styling details.
e. Transformers:
- src/transformers/layout.ts further processes and transforms the data so that it’s optimized for consumption by Cursor.
f. Types and Utilities:
- The src/types and src/utils directories ensure proper type-safety and provide common helper functions.

##### Relationships and Data Flow
- The entry point/CLI module initializes the server based on configuration settings.
- The server component accepts incoming requests and routes them to the appropriate service.
- When a request (like get_file or get_node) is received, the server will:
– Use the Figma Service to make API calls to Figma.
– Process and simplify the API response using the transformer modules.
– Return the simplified data back via HTTP response or SSE streams.
- Optionally, show an inspection tool (“inspect”) that can launch a web UI for debugging MCP responses.

##### Architectural Patterns and Design Principles
- Separation of concerns: Different modules (CLI, configuration, server, services, transformers) handle their own responsibilities.
- Modular design: Easy to extend individual pieces, such as adding more tools or integrating additional services.
- Environment-based configuration: Settings are loaded from environment variables and overridden by command-line arguments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    cursorClient["Cursor Client"]:::external
    figmaAPI["Figma API"]:::external
    inspectTool["Inspect Tool<br/>(Debug UI)"]:::external

    %% Startup Subgraph
    subgraph "Startup"
        cli["CLI Module"]:::cli
        config["Configuration Module"]:::config
    end

    %% Core Server Subgraph
    subgraph "Core Server"
        server["Server"]:::server
    end

    %% Processing Pipeline Subgraph
    subgraph "Processing Pipeline"
        figmaService["Figma Service"]:::service
        simplifyService["Simplification Service"]:::service
        layoutTransformer["Layout Transformer"]:::transformer
    end

    %% Helpers Subgraph
    subgraph "Helpers"
        figmaTypes["Figma Data Types"]:::helper
        utils["Utility Functions"]:::helper
    end

    %% Data Flow Connections
    cursorClient -->|"request"| server
    cli -->|"init"| config
    config -->|"configure"| server
    server -->|"fetch-design-data"| figmaService
    figmaService -->|"call"| figmaAPI
    figmaAPI -->|"response"| figmaService
    figmaService -->|"simplify-data"| simplifyService
    simplifyService -->|"transform-data"| layoutTransformer
    layoutTransformer -->|"formatted-response"| server
    server -->|"send-response"| cursorClient
    server -->|"debug-stream"| inspectTool

    %% Helpers Usage Connections
    figmaService -->|"uses"| figmaTypes
    simplifyService -->|"uses"| utils

    %% Click Events
    click cli "https://github.com/glips/figma-context-mcp/blob/main/src/cli.ts"
    click config "https://github.com/glips/figma-context-mcp/blob/main/src/config.ts"
    click server "https://github.com/glips/figma-context-mcp/blob/main/src/server.ts"
    click figmaService "https://github.com/glips/figma-context-mcp/blob/main/src/services/figma.ts"
    click simplifyService "https://github.com/glips/figma-context-mcp/blob/main/src/services/simplify-node-response.ts"
    click layoutTransformer "https://github.com/glips/figma-context-mcp/blob/main/src/transformers/layout.ts"
    click figmaTypes "https://github.com/glips/figma-context-mcp/blob/main/src/types/figma.ts"
    click utils "https://github.com/glips/figma-context-mcp/blob/main/src/utils/identity.ts"

    %% Styles
    classDef cli fill:#FFDAB9,stroke:#D2691E,stroke-width:2px;
    classDef config fill:#FFE4B5,stroke:#CD853F,stroke-width:2px;
    classDef server fill:#B0E0E6,stroke:#4682B4,stroke-width:2px;
    classDef service fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef transformer fill:#FFFFE0,stroke:#DAA520,stroke-width:2px;
    classDef external fill:#D5E8D4,stroke:#82B366,stroke-width:2px;
    classDef helper fill:#FFF2CC,stroke:#C9B037,stroke-width:2px;
```
