内容
align="center">
# Figwright
**开源、双向的 Figma 代理，适用于 MCP 客户端。**
免费替代 Figma 的 Dev Mode MCP — 您的 AI 代理以高保真度读取设计 _并且_写入画布。不需要付费 Figma 座位。
[](https://www.npmjs.com/package/@figwright/mcp)
[](https://github.com/awdr74100/figwright/actions/workflows/ci.yml)
[](./LICENSE)
[](https://nodejs.org)
</div>
<!-- TODO(demo): drop a short GIF / screenshot of a real codegen → canvas round-trip here. -->
## 什么是 Figwright？
Figwright 通过本地 WebSocket 代理连接 **MCP 服务器** 和 **Figma 插件**，使 AI 代理（如 Claude Code、Cursor 或其他 MCP 客户端）能够与 Figma 交互，而不仅仅是查看它。
它支持双向操作：
- **读取** — 将 Figma 选择转换为框架感知代码，基于忠实的、去重的设计上下文（布局、排版、变量、组件）。
- **写入** — 直接在画布上创作和编辑：框架、文本、自动布局、样式、变量、组件、整个屏幕。
所有操作都在您的机器上运行，并通过插件与 Figma 通信，因此不需要 **Figma Dev Mode 座位** 和 **付费层级**。
## 为什么选择 Figwright
- **免费** — 无需 Figma Dev Mode 或付费座位。官方 Dev Mode MCP 是付费的；而 Figwright 是免费的。
- **双向** — 不仅限于读取。**88 种工具** 支持读取 _和_ 写入画布，使代理可以实现设计并构建它们。
- **提供者优先的代码生成** — Figwright 检测您的实际堆栈（框架 + 样式系统）并重用现有的组件、令牌和图标，而不是生成需要重写的通用标记。
- **任何 MCP 客户端** — Claude Code、Cursor 和其他支持 MCP 的代理都以相同的方式工作。
- **开放且可扩展** — 读取/写入工作流作为可安装的 [技能](#技能) 提供，您可以采用或分叉。
## 工作原理
```mermaid
flowchart LR
subgraph machine["您的机器"]
A["MCP 客户端<br/>(Claude Code, Cursor, …)"]
B["@figwright/mcp<br/>服务器 · 代理 · 选举"]
end
subgraph figma["Figma 应用"]
C["Figwright 插件<br/>Vue 3 UI + 沙盒"]
D[("画布")]
end
A -->|"MCP (stdio)"| B
B <-->|"本地 WebSocket · msgpack"| C
C -->|"Figma 插件 API"| D
```
**服务器**（`@figwright/mcp`）是您的 MCP 客户端启动的进程。它负责 WebSocket **代理**、领导者/跟随者 **选举**（多个 MCP 服务器可以共享一个插件）和请求 **幂等性**。**插件** 运行在 Figma 中 — 一个 Vue 3 UI 加上一个执行实际 Figma API 调用的沙盒 — 并连接到本地服务器。
按照设计，Figwright 是 **提供者优先** 的：它不使用固定的编译器管道，而是提供诚实的设计上下文，并让模型生成与您的代码库相匹配的代码。[`figma-codegen`](#技能) 技能编码了这种方法。
## 快速入门
### 1. 将服务器添加到您的 MCP 客户端
对于 Claude Code，请在您的 `.mcp.json` 中添加以下内容（其他客户端使用相同的格式）：
```json
{
"mcpServers": {
"figwright": {
"command": "npx",
"args": ["-y", "@figwright/mcp@latest"]
}
}
}
```
`npx` 会获取并运行已发布的服务器 — 无需全局安装。
### 2. 安装 Figma 插件
插件尚未在 Figma 社区市场上线，因此请从最新版本中安装：
1. 从 [**最新 GitHub 版本**](https://github.com/awdr74100/figwright/releases/latest) 下载插件 zip 文件并解压。
2. 在 Figma **桌面应用** 中：**菜单 → 插件 → 开发 → 从清单导入插件…** 并选择解压后的 `manifest.json`。
### 3. 连接
在 Figma 中打开 Figwright 插件（**插件 → 开发 → Figwright**）。它会自动连接到本地服务器并显示 **已连接**。请您的代理运行 `ping` 以确认链接。
### 4. （可选）安装技能
[技能](#技能) 使代理在正确的时间调用 Figwright 并遵循有根据的工作流：
```bash
npx skills add awdr74100/figwright/skills
```
### 5. 试用
在 Figma 中选择一个框架，然后提示您的代理：
> _将此 Figma 选择编码为 React 组件。_
或在另一个方向：
> _根据此规范在 Figma 中构建一个定价部分。_
## 技能
代理技能协调 Figwright 的工具。它们由模型调用 — 您的代理会在任务与描述匹配时自动加载一个技能。
| 技能 | 描述 |
| :--------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| [`figma-codegen`](./skills/figma-codegen/SKILL.md) | 将 Figma 选择转换为框架感知代码，基于您的堆栈和现有组件。 |
| [`figma-build`](./skills/figma-build/SKILL.md) | 从代码或描述中构建 Figma 设计，重用文件中的现有组件和样式。 |
使用 [`skills`](https://www.skills.sh) CLI 在任何支持的代理上安装：
```bash
npx skills add awdr74100/figwright/skills # 全部
npx skills add https://github.com/awdr74100/figwright/tree/main/skills/figma-codegen # 单个
```
> 技能需要连接到 `@figwright/mcp` 服务器 — 它们本身没有驱动工具。
## 工具
Figwright 提供了 **88 种 MCP 工具**，分为三组：
- **读取** — 选择、文档和节点检查、样式、变量、组件、字体、反应、截图和 PDF 导出。
- **写入** — 创建和编辑框架、文本、形状、自动布局、效果、样式、变量、组件、页面和反应；另外还有一个 `batch` 工具，可以一次应用多个编辑。
- **基础** — `get_design_context` 提供忠实的、去重的设计上下文，以及 `component_map` / `token_map` / `icon_map`，它们将 Figma 数据连接到您的代码库，以便代码生成重用您已经拥有的内容。
您的 MCP 客户端会在连接时列出每个工具 — 这始终是权威的、最新的目录。
## 要求
- **MCP 客户端**（Claude Code、Cursor、…）。
- **Node.js 24 LTS 或更新版本** — 服务器通过 `npx` 运行。
- **Figma** — 免费层足够；桌面应用需要导入开发中的插件。
## 常见问题
<details>
<summary><strong>我的 MCP 客户端无法启动服务器 — <code>npx</code> 或 <code>node</code> "命令未找到"。</strong></summary>
这通常意味着您的 MCP 客户端无法在 `PATH` 上找到 `node` / `npx` — 它特定于 Figwright，并影响任何 `npx` 启动的 MCP 服务器。在使用版本管理器（**fnm, nvm, asdf, volta, mise**）管理 Node 时尤其常见：这些管理器从 shell 钩子设置 `PATH`，而这些钩子仅在交互式终端中运行，因此直接生成命令的 GUI 应用或 MCP 客户端永远不会继承它们。
修复方法，从最简单的开始：
- **使用绝对路径。** 在普通终端中运行 `which npx`（或 `which node`），并使用该完整路径作为 `command`：
```json
{
"mcpServers": {
"figwright": {
"command": "/Users/you/.local/share/fnm/node-versions/v24.x.x/installation/bin/npx",
"args": ["-y", "@figwright/mcp@latest"]
}
}
}
```
- **安装它并指向二进制文件。** 安装包（全局使用 `npm i -g @figwright/mcp`，或作为本地依赖项），然后将 `command` 设置为 `which figwright-mcp` 的绝对路径。这样做的好处是跳过了 `npx … @latest` 每次启动时执行的网络解析。
- **通过 `env` 传递 `PATH`。** 如果您的客户端支持每个服务器的 `env`，请将版本管理器的 `bin` 目录添加到 `env.PATH`。
</details>
<details>
<summary><strong>插件保持在“等待”状态，永远不会连接。</strong></summary>
服务器由您的 MCP 客户端启动，因此它只在运行。请检查：
- 您的 MCP 客户端正在运行并已配置 Figwright（尝试 `ping- 插件在同一台机器上的同一个 Figma打开（代理仅限`127.0.1`）。
- 没有阻止本地环回连接（某些防火墙/安全工具会这样做）。
</details>
<details>
<summary><strong>我需要付费 Figma 计划或 Dev Mode 吗？</strong></summary>
不需要。Figwright 通过插件与 Figma 通信，因此免费层就足够了 — 不需要 Dev Mode 座位或付费层级。
</details>
<details>
<summary><strong>是否允许多个代理同时使用同一个插件？</strong></summary>
是的。多个 MCP 服务器可以通过领导者/跟随者 **选举** 共享一个插件 — 一个领导，其他跟随，如果领导离开，则会平稳交接。
</details>
## 贡献与开发
欢迎贡献 — 请参阅 **[CONTRIBUTING.md](./CONTRIBUTING.md)** 以获取工作流程，并参阅 **[AGENTS.md](./AGENTS.md)** 以获取架构、布局。
```
packages/
shared/ # 类型、Zod 模式、msgpack 编码器、插件↔服务器协议（打包到 mcp）
mcp/ # MCP 服务器 — @figwright/mcp（Node，ESM）：代理、选举、工具、连接
plugin/ # Figma 插件 — Vue 3 + Vite + Tailwind（UI）盒（F）
skills/ 代理技能，协调工具 — 可通过 ` skills add` 安装
```
从仓库根目录运行规范检查（与 CI 强制执行的内容相同）：
```bash
pnpm install
typecheck && pnpm lint && pnpm format:check && pnpm knip && pnpm build && pnpm test
```
## 名称由来
`figwright` 遵循 **_-wright_** 传统 — 一个古老的英语单词，表示制造者或工匠：**playwright** 编写戏剧，**shipwright** 建造船舶，**wheelwright** 制造轮子。这个名字是对 [**Playwright**](https://playwright.dev) 的致敬，它自动化了浏览器。Playwright 驱动浏览器，而 **Figwright** 驱动 Figma — 一个设计制作者，既可以读取画布，又可以将作品写入画布。
## 许可证
[MIT](./LICENSE) Roya 版权所有
