anchor-d2c-mcp

v1.1.0

Published

3 months ago

MCP server for converting a single Figma node into frontend code through the Figma REST API.

0High
0Medium
0Low

agjyxzz

d2c figma figma to code anchor mcp

Anchor D2C MCP

anchor-d2c-mcp 是一个基于 Figma REST API 的 MCP 服务，用于把单个 Figma 节点转换为 HTML、Tailwind、Flutter、SwiftUI、Compose 代码。

项目中的代码生成能力参考 bernaferrari/FigmaToCode，并在当前仓库中补齐了面向 MCP 服务的输入解析与诊断输出。

当前服务通过 Figma API 获取数据，同时添加了下载资源文件的能力。与原始插件版的数据来源和运行环境不同，因此生成代码与原始插件版可能存在差异。当前版本的生成质量不代表原始插件版本的生成质量。

已知问题

file_variables:read 相关能力受 Figma 企业版权限限制影响，当前版本暂时没有完成实际功能验证。
当 figma 中 svg 通过 effets 设置阴影时，导出的 svg 宽高可能和原始不匹配
不支持 figma 多层设计，代码会生成到一个层里
vector mask 不支持，直接按照普通 Rectangle mask 处理
修改后只对Tailwind，jsx 类型进行了测试，其他输出格式未验证。

安装与启动

前置条件

运行时要求 Node.js >=20.18.0。

配置figma access token 环境变量，把以下内容添加到 ~/.zshrc 中

export FIGMA_ACCESS_TOKEN=figd_xxxx

通过 npx 直接运行，无需全局安装：

对应的 MCP 配置：

{
  "mcpServers": {
    "anchor-d2c-mcp": {
      "command": "npx",
      "args": ["-y", "anchor-d2c-mcp@latest", "stdio"],
      "timeout": 600000
    }
  }
}

通过 pnpm 包全局安装，使用统一命令 anchor-d2c-mcp：

pnpm install -g anchor-d2c-mcp

可用子命令：

anchor-d2c-mcp convert "<figma-url>"
anchor-d2c-mcp screenshot "<figma-url>"
anchor-d2c-mcp init codex
anchor-d2c-mcp init claude
anchor-d2c-mcp init opencode
anchor-d2c-mcp stdio
anchor-d2c-mcp help
anchor-d2c-mcp --version

init 会优先使用当前环境中的 FIGMA_ACCESS_TOKEN；未设置时使用不回显的终端输入。如果直接回车，会把空字符串写入配置。配置通过同目录临时文件原子替换；在 POSIX 系统上，配置目录和文件权限分别强制为 0700、0600。

初始化配置

使用 init 命令配置到不同的 cli

Codex：

anchor-d2c-mcp init codex

Claude：

anchor-d2c-mcp init claude

初始化程序会安全地合并 ~/.claude.json 中的用户级 mcpServers 配置，不会把 Figma token 放入子进程命令行参数。

OpenCode：

anchor-d2c-mcp init opencode

ROUND_TAILWIND_VALUES 和 ROUND_TAILWIND_COLORS 默认关闭，Tailwind 输出使用精确像素值。如需启用近似映射（按 THRESHOLD_PERCENT 阈值匹配最接近的 Tailwind 预设值），可在环境变量中设为 true。通过 Figma REST API 拉取数据可能受网络影响和频率限制，推荐适当增大工具超时时间。

转码方法

最简 CLI 调用会在当前目录生成 Tailwind JSX 代码，并以 JSON 返回代码文件路径：

anchor-d2c-mcp convert "https://www.figma.com/design/ANONFILEKEY1234567890AB/anonymized-case?node-id=1-1427"

指定工作区、框架和生成模式：

anchor-d2c-mcp convert "<figma-url>" --workspace-root . --framework Flutter --generation-mode stateless

也可以在 MCP 客户端中使用提示词：

https://www.figma.com/design/ANONFILEKEY1234567890AB/anonymized-case?node-id=1-1427
将这个 figma 设计转换为 Tailwind jsx 风格的代码

截图方法

最简 CLI 调用会下载 2 倍节点截图，并以 JSON 返回截图文件路径：

anchor-d2c-mcp screenshot "https://www.figma.com/design/ANONFILEKEY1234567890AB/anonymized-case?node-id=1-1427"

指定工作区、倍率和缓存策略：

anchor-d2c-mcp screenshot "<figma-url>" --workspace-root . --scale 3 --use-cache

工作区结构

当前仓库采用 pnpm + turbo + TypeScript，包含 3 个工作区：

apps/figma-rest-mcp-server 负责 MCP 服务、Figma REST 访问、缓存、能力探测与响应组装
packages/codegen-kernel 负责转换核心与多端代码生成
packages/codegen-types 提供共享类型定义

核心能力

服务主链路包含以下步骤：

解析 figmaUrl 中的 fileKey 和 node-id
拉取目标节点对应的 Figma REST snapshot
构建稳定的 SourceSnapshot
归一化为内部 NormalizedTree
调用目标 framework generator 生成代码
返回生成代码路径与 warnings，并按环境变量决定是否返回 diagnostics

当前对外提供两个 MCP 工具：

figma_to_code_convert
figma_to_code_fetch_screenshot

`figma_to_code_convert`

入参表：

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | figmaUrl | string | 是 | 无 | 单节点 Figma URL，必须包含 node-id | | workspaceRoot | string | 是 | 无 | 工作区根目录，用于保存缓存、中间产物与生成结果 | | useCache | boolean | 否 | true | 是否复用 TTL 内的 REST 缓存和资产中间产物 | | framework | "HTML" \| "Tailwind" \| "Flutter" \| "SwiftUI" \| "Compose" | 否 | "Tailwind" | 目标代码框架，不填时默认为 Tailwind | | generationMode | string | 否 | 无 | 对应框架的生成模式，取值受 framework 限制。使用 Tailwind 时若不填则默认为 jsx |

generationMode 可选值：

| framework | 合法 generationMode | 默认值 | |---|---|---| | HTML | html, jsx, styled-components, svelte | 无 | | Tailwind | html, jsx, twig | jsx | | Flutter | fullApp, stateless, snippet | 无 | | SwiftUI | preview, struct, snippet | 无 | | Compose | snippet, composable, screen | 无 |

说明：

图片和向量默认使用 local 模式，资源写入 <workspaceRoot>/.figma-to-code/cache/assets/；remote 模式只获取 Figma 签名地址并由生成代码直接引用，不下载资源内容
useCache=true 时按资产项复用有效的本地文件；图片或 SVG 单项失败后，下次转换只重试失败项，其余成功项继续使用缓存
资产模式由服务端环境变量 IMAGE_ASSET_MODE / VECTOR_ASSET_MODE 控制，仅接受 local 或 remote，不在公开 MCP 请求中暴露；inline 实现保留但固定关闭
preview 相关内部模块与响应 schema 仍然保留，但当前公开工具固定不生成 preview
structuredContent 成功时返回转换结果，失败时返回标准错误对象；公开 outputSchema 同时兼容两种结果，避免客户端用成功 schema 二次覆盖原始错误

`figma_to_code_fetch_screenshot`

入参表：

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | figmaUrl | string | 是 | 无 | 单节点 Figma URL，必须包含 node-id | | workspaceRoot | string | 是 | 无 | 工作区根目录，用于保存截图缓存 | | useCache | boolean | 否 | false | 是否优先复用当前工作区下已缓存的节点截图 | | scale | number | 否 | 2 | 截图缩放倍率，合法范围为 0.01–4 |

返回字段：

| 字段 | 类型 | 说明 | |---|---|---| | screenshotPath | string | 相对 workspaceRoot 的截图缓存路径 | | fileKey | string | 从 figmaUrl 解析出的 file key | | nodeId | string | 归一化后的节点 id |

说明：

这是独立的 Figma 节点截图工具，与现有 HTML preview 能力无关
1 倍截图写入 <workspaceRoot>/.figma-to-code/cache/screenshot/<fileKey>/<nodeId>/preview.png
其他倍率写入同目录下的倍率文件，例如 3 倍图为 preview_3x.png，1.5 倍图为 preview_1_5x.png
useCache=true 时只复用相同倍率的截图文件，不会用其他倍率的缓存代替

缓存默认写入：

<workspaceRoot>/.figma-to-code/cache/rest/
<workspaceRoot>/.figma-to-code/cache/generated/
<workspaceRoot>/.figma-to-code/cache/assets/

环境变量

核心配置位于 apps/figma-rest-mcp-server/src/infrastructure/config.ts。

环境变量表：

| 变量名 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | FIGMA_ACCESS_TOKEN | string | 是 | 无 | Figma API token，调用 Figma API 必备参数 | | FIGMA_API_BASE_URL | string | 否 | https://api.figma.com | Figma API 基地址 | | HTTP_TIMEOUT_MS | number | 否 | 60000 | HTTP 请求超时毫秒数 | | HTTP_RETRY_MAX | number | 否 | 2 | HTTP 最大重试次数 | | HTTP_MAX_CONCURRENCY | number | 否 | 6 | HTTP 并发上限 | | CACHE_TTL_MS | number | 否 | 300000 | 通用缓存 TTL | | IMAGE_CACHE_TTL_MS | number | 否 | 无 | 图片缓存 TTL，未设置时沿用 CACHE_TTL_MS | | VECTOR_CACHE_TTL_MS | number | 否 | 无 | 向量缓存 TTL，未设置时沿用 CACHE_TTL_MS | | VARIABLE_CACHE_TTL_MS | number | 否 | 无 | 变量缓存 TTL，未设置时沿用 CACHE_TTL_MS | | AUTH_CACHE_TTL_MS | number | 否 | 无 | 认证缓存 TTL，未设置时沿用 CACHE_TTL_MS | | CACHE_MAX_ENTRIES | number | 否 | 500 | 进程内缓存最大条目数 | | WORKSPACE_ALLOWED_ROOTS | JSON string[] | 否 | ["."] | 允许写入的 workspace 根目录列表；请求路径必须是其中一个现存目录或其现存子目录 | | ENABLE_VARIABLES | boolean | 否 | false | 是否启用变量能力，同时也是颜色变量输出的默认来源 | | INCLUDE_DIAGNOSTICS | boolean | 否 | false | 是否默认在响应中返回 diagnostics | | ENABLE_METRICS_LOGGING | boolean | 否 | false | 是否输出 metrics 日志 | | MCP_TEXT_FALLBACK | boolean | 否 | false | 是否把关键 structuredContent 数据同步写入 MCP 文本响应，适用于不展示 structuredContent 的客户端 | | SHOW_LAYER_NAMES | boolean | 否 | false | 是否在输出中显示 layer 名称 | | ROUND_TAILWIND_VALUES | boolean | 否 | false | Tailwind 数值是否按阈值近似映射 | | ROUND_TAILWIND_COLORS | boolean | 否 | false | Tailwind 颜色是否按阈值近似映射 | | USE_TAILWIND4 | boolean | 否 | false | 是否启用 Tailwind 4 相关生成逻辑 | | CUSTOM_TAILWIND_PREFIX | string | 否 | "" | Tailwind 类名前缀 | | BASE_FONT_SIZE | number | 否 | 16 | 基础字体大小，用于部分 Tailwind/排版换算 | | THRESHOLD_PERCENT | number | 否 | 15 | Tailwind 数值近似匹配阈值百分比 | | BASE_FONT_FAMILY | string | 否 | "" | 默认字体族 | | FONT_FAMILY_CUSTOM_CONFIG | JSON string | 否 | {} | 自定义字体映射，环境变量中需传 JSON 字符串 | | IMAGE_ASSET_MODE | "local" \| "remote" | 否 | "local" | 图片写入本地或直接引用远程签名 URL | | VECTOR_ASSET_MODE | "local" \| "remote" | 否 | "local" | SVG 写入本地或直接引用远程签名 URL |

示例：

export FIGMA_ACCESS_TOKEN=xxxxx
export WORKSPACE_ALLOWED_ROOTS='["/absolute/path/to/workspace"]'

workspaceRoot 会在任何 Figma 请求前经过 realpath 校验。不存在的目录、越出允许根目录的 .. 路径，以及指向允许范围外的符号链接都会被拒绝。默认的 "." 指服务进程启动目录。

`MCP_TEXT_FALLBACK`

默认情况下，工具会把完整结构化结果放在 MCP 的 structuredContent 字段里，content[0].text 只返回一段简短摘要。部分 MCP 客户端（例如某些 Trae 配置）不会把 structuredContent 暴露给模型或用户，这时会出现 help 只看到摘要、convert 只看到生成路径、详细字段丢失的情况。

遇到这类客户端兼容问题时，可以设置：

export MCP_TEXT_FALLBACK=true

开启后，工具仍会保留原始 structuredContent，同时把关键结构化结果追加到 content[0].text。支持 true / false 或 1 / 0。默认值为 false，避免在支持 structuredContent 的客户端里产生过长文本。

开发者运行

pnpm install
pnpm --filter anchor-d2c-mcp dev

根目录 README.md 和 LICENSE 是发布内容的唯一来源。npm 打包时， prepack 会通过 sync:package-files 临时复制到 apps/figma-rest-mcp-server/，随后执行 tarball dry-run，验证 LICENSE、README、bin、exports、JavaScript 和 DTS 均存在；不要直接编辑生成文件。

构建：

pnpm --filter anchor-d2c-mcp build

Inspector 调试

pnpm --filter anchor-d2c-mcp build
FIGMA_ACCESS_TOKEN=xxxxx npx @modelcontextprotocol/inspector anchor-d2c-mcp stdio

测试

当前测试覆盖：

unit：基础设施、resolver、gateway、normalizer、preview、use case
contract：MCP handler 合同测试与 framework golden
e2e：基于真实结构 fixture 的 mocked pipeline 回归

运行：

pnpm type-check
pnpm test
pnpm build

如需验证真实 Figma 链路，可以运行：

FIGMA_ACCESS_TOKEN=xxxxx \
FIGMA_FILE_URL='https://www.figma.com/design/ANONFILEKEY1234567890AB/anonymized-case?node-id=1-1427' \
pnpm --filter anchor-d2c-mcp verify:real

常见错误

missing_figma_access_token：调用接口时未配置 FIGMA_ACCESS_TOKEN，在 MCP server env 配置中添加后重试
figma_http_401：检查 token 是否有效、是否过期或被撤销
figma_http_403：确认 token 所属账号能访问目标 Figma 文件
figma_http_404：检查 figmaUrl 中的文件和 node-id 是否正确
figma_http_429：降低并发或稍后重试
missing_source_node_id：figmaUrl 必须携带正确 node-id

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme