Figma-Context-MCP

Fetches raw Figma file and node data via the Figma REST API, then applies a multi-stage extraction and transformation pipeline that filters metadata, converts Figma auto-layout concepts to CSS flexbox properties, translates effect objects to box-shadow CSS, and generates CSS-compatible color values. The extraction system (src/extractors) isolates layout and styling information while the transformer layer (src/transformers) performs semantic translation from Figma's design model to web-implementable CSS, outputting simplified JSON or YAML optimized for LLM consumption.

Implements the Model Context Protocol (MCP) server specification using @modelcontextprotocol/sdk v1.10.2, exposing Figma capabilities as standardized MCP tools (get_figma_data, download_figma_images) that AI agents like Cursor can discover and invoke via a schema-based function registry. The MCP layer (src/mcp.ts) handles protocol serialization, request routing, and response formatting, allowing any MCP-compatible client to call Figma operations without custom integration code.

Provides batch operations for downloading multiple assets from a Figma file in a single request, with optional image optimization (compression, format conversion). The batch retrieval system (src/index.ts image processing) collects asset node IDs, fetches them in parallel from Figma's CDN, and optionally applies optimization (e.g., SVG minification, PNG compression) before delivery. This reduces latency and network overhead compared to fetching assets individually.

Implements optional polling-based change detection that periodically fetches Figma file metadata and compares against cached state to identify design updates. The monitoring system (if implemented in src/services/figma.ts) tracks file modification timestamps and node-level changes, allowing the MCP server to notify clients when designs have been updated. This enables AI agents to work with fresh design data without manual refresh.

Implements the download_figma_images MCP tool that retrieves SVG and PNG assets directly from Figma designs, handling format conversion and optimization. The image processing pipeline (src/index.ts image processing section) manages asset fetching from Figma's CDN, format selection based on design node type, and optional image optimization before delivery to the AI agent. Supports both vector (SVG) and raster (PNG) formats with automatic selection based on node properties.

Provides three transport layer implementations (src/server.ts) for deploying the MCP server: StdioServerTransport for local CLI integration, SSEServerTransport for HTTP long-polling, and StreamableHTTPServerTransport for REST-based MCP communication. The transport abstraction allows the same MCP server logic to run in different deployment contexts (local CLI, HTTP server on port 3333, or embedded in Node.js applications) without code changes. Server orchestration (src/server.ts) selects transport based on environment or CLI arguments.

Implements a configuration system (src/config.ts) that reads Figma API credentials and server settings from multiple sources with a priority hierarchy: CLI arguments override environment variables, which override defaults. Supports both Personal Access Token and OAuth Bearer Token authentication methods, allowing flexible credential management across local development, CI/CD, and production deployments. Configuration is validated at startup to fail fast if required credentials are missing.

Implements a Figma API client (src/services/figma.ts) that wraps the Figma REST API with authentication, request construction, and error handling. The client manages API calls to fetch file data, node information, and asset URLs, handling Figma's pagination for large files and implementing exponential backoff for rate-limit recovery. Abstracts Figma API specifics (authentication headers, endpoint construction, response parsing) from the extraction and transformation layers, providing a clean interface for design data retrieval.

Implements an extraction system (src/extractors) that parses Figma's verbose API responses and filters out non-essential metadata, retaining only layout, styling, and hierarchy information relevant for code generation. The extraction pipeline walks the Figma node tree, identifies design-relevant properties (constraints, fills, strokes, typography, spacing), and discards internal Figma metadata (IDs, plugin data, version history). This reduces token count and improves LLM focus by removing noise from design data.

Implements a transformer layer (src/transformers) that converts Figma design concepts into CSS-compatible properties and values. The transformation pipeline maps Figma's auto-layout system to CSS flexbox (direction, alignment, gap), translates effect objects (shadows, blurs) to CSS box-shadow and filter properties, converts Figma color objects to CSS hex/rgba values, and normalizes typography properties to CSS font specifications. This semantic translation enables AI models to generate immediately-usable CSS without interpretation overhead.

Formats extracted and transformed design data into YAML or JSON output optimized for AI model consumption. The formatting layer (src/index.ts output formatting) structures design hierarchy, properties, and assets into human-readable YAML or machine-parseable JSON, with consistent key naming and property organization. This allows AI agents to easily parse design context and reference specific components, properties, and assets in generated code.

Extracts Figma's component structure, including component definitions, instances, overrides, and property hierarchies, mapping them to a simplified component model suitable for code generation. The extraction system identifies component boundaries, tracks instance relationships, and preserves property inheritance chains, allowing AI models to understand which properties are inherited vs. overridden. This enables generation of component-based code that mirrors Figma's design system structure.