# Figma MCP

Figma MCP is a local FastMCP 3 server that converts a selected Figma Design
Frame, Component, or Instance into an inspectable packet and a static Unity
UGUI Direct YAML Prefab.

The project is intentionally small and independent. It uses the Figma REST API,
stores rendered PNGs locally, and does not require a Figma plugin, OAuth flow,
or Unity Editor extension.

中文文档：[README.zh-CN.md](README.zh-CN.md)

## Requirements

- Python 3.10+
- `uv` (recommended) or another Python environment manager
- A Figma personal access token with `file_content:read`
- Unity 2022.3 LTS or Unity 6 LTS for generated output

## Install

```bash
uv sync --extra dev
cp .env.example .env
```

Set the token only in your local `.env`:

```dotenv
FIGMA_TOKEN=figd_your_token_here
```

The token is used only in `X-Figma-Token` headers sent to
`https://api.figma.com`. Render downloads use a separate unauthenticated HTTP
client. The token is not stored in packets, generated assets, source maps, or
error details.

## Run

Loopback HTTP (default):

```bash
uv run figma-mcp
```

The endpoint is `http://127.0.0.1:8127/mcp`. Non-loopback HTTP binding is
rejected.

stdio:

```bash
./run-stdio.sh
```

or:

```bash
MCP_TRANSPORT=stdio uv run figma-mcp
```

## Tools

| Tool | Purpose |
| --- | --- |
| `figma_list_frames` | List selectable Frames, Components, Instances, and Component Set variants, including those nested under Sections. |
| `figma_prepare_design` | Fetch one root, normalize it, batch-render PNG assets, and persist an active or diagnostic Packet. |
| `figma_inspect_design` | Inspect `summary`, `full`, `tree`, `nodes`, `assets`, `slices`, `unity_profile`, or `unity_plan`. |
| `figma_generate_unity_prefab` | Transactionally write and statically pre-verify a UGUI Direct YAML Prefab. |
| `figma_verify_unity_prefab` | Independently verify YAML, Sprite meta files, source map, ownership, fileIDs, and Unity version. |

Example flow:

1. Call `figma_list_frames` with a Figma Design URL or file key.
2. Call `figma_prepare_design` with a node id, exact/unique partial name, or
   1-based list index. A URL `node-id` takes precedence.
3. Inspect `view="unity_plan"` and review warnings.
4. Call `figma_generate_unity_prefab` with an absolute Unity project path.
5. Call `figma_verify_unity_prefab`, then open the project in Unity for actual
   import, compile, and visual validation.

## Cache behavior

Successful active Packets use a stable key derived from the Figma file key,
node id, image scale, semantic ruleset, and an explicit `version-id` when one is
requested. Frame listings and Packets for different explicit versions are kept
in separate cache namespaces. They persist across server restarts.
`force_refresh=true` is the only normal way to bypass a complete cache.

Refreshes download into a temporary staging directory. A complete refresh writes
an immutable asset version and atomically replaces the active Packet pointer. If
any render is missing or fails, the previous active Packet is preserved and a
separate diagnostic Packet is saved with `generation_ready=false`.

Figma render URLs are never treated as cache entries. Every rendered PNG is
downloaded immediately and stored with its SHA-256 hash.

## Figma-to-Unity rules

- Figma child order is preserved. Increasing `z_index` is bottom-to-top and
  Unity creates same-parent nodes in ascending order.
- Coordinates are rebased to the selected root and use a top-left origin.
- Standard constraints map to `RectTransform` anchors.
- horizontal/vertical Auto Layout maps to LayoutGroup and LayoutElement hints.
  Wrap/grid combinations retain snapshot coordinates and emit warnings.
- Editable text becomes `UnityEngine.UI.Text`; unmatched fonts fall back to
  built-in Arial with a warning.
- Hidden Figma nodes become inactive GameObjects. Group opacity uses one
  `CanvasGroup`; leaf opacity is applied once to its generated Graphic.
- Simple solid rectangles become UGUI Images. Vector, image fill, gradient,
  rounded, stroked, or effect-heavy visual leaves become PNG sprites.
- Rotated visual leaves and containers use rendered PNGs so rotation is baked
  accurately. A rotated container keeps its descendant hierarchy and source
  mapping, while descendant source visuals are suppressed to avoid duplication.
- Complex containers remain hierarchical. Rectangular `clipsContent` maps to
  `RectMask2D` where safe; unsupported container visuals emit fidelity warnings.

Interactive generation defaults to `conservative`: confidence must be at least
0.8, review must not be required, and all references must be complete.
`structure_only` suppresses inferred Button/Toggle/Input/Dropdown/Slider/
ScrollRect components while retaining presentation hierarchy and safe layout or
mask components.

Explicit name tags include `@button`, `@toggle`, `@input`, `@dropdown`,
`@slider`, `@scroll`, `@scrollbar`, `@tab`, `@radio`, `@mask`, and `@ignore`.
They never create business scripts, UnityEvent bindings, navigation, or data
bindings.

## Unity ownership policy

The default output root is `Assets/FigmaMCP`. Generation uses staging, static
pre-verification, deterministic GUIDs, a source map, and an ownership manifest.

`overwrite=false` is the default. With `overwrite=true`, only unchanged files
already owned by the same Packet manifest can be replaced; every existing file
is checked against its previous SHA-256. If an owned file was edited manually,
generation returns `owned_asset_modified`. Set
`force_overwrite_modified=true` together with `overwrite=true` only when those
edits may be discarded. Direct YAML regeneration replaces complete owned files;
field-level preservation hints describe a future editor-side importer, not the
current writer. Historical orphaned files are reported but not deleted. A failed
commit rolls back files changed during that transaction.

## Contracts

All responses use `api_version: "0.1"` and a `success`/`error` envelope. Public
schemas are version 1:

- `figma-mcp.packet`
- `figma-mcp.unity-plan`
- `figma-mcp.prefab-source-map`
- `figma-mcp.ownership-manifest`

Generated JSON Schemas are in [`schemas/`](schemas/).

## Development

```bash
uv run pytest
uv run pytest --cov=figma_mcp --cov-report=term-missing
uv run ruff check src tests
uv run mypy src
uv build
```

The test suite is offline: it mocks Figma REST and creates temporary Unity
project structures. Passing tests prove the contracts, generated files, and
static checks; they do not prove compatibility with every real Figma document,
Unity Editor import/compilation, or visual parity.

## Scope exclusions

Version 0.1.0 does not implement OAuth, Figma variables, FigJam/Slides, plugin
templates, real Unity Prefab Instances/Variants, C# importers, visual diff, or a
publishing pipeline.

## License

MIT