内容
# 处理 Figma MCP
该项目实现了 AI IDE（如 Cursor、Antigravity、Windsurf 等）与 Figma 之间的模型上下文协议（MCP）集成。它允许您的 AI 助手与 Figma 通信，以读取设计并以编程方式修改它们。
https://github.com/user-attachments/assets/129a14d2-ed73-470f-9a4c-2240b2a4885c
## 项目结构
- `src/talk_to_figma_mcp/` - 用于 Figma 集成的 TypeScript MCP 服务器
- `src/cursor_mcp_plugin/` - 用于与您的 AI IDE 通信的 Figma 插件
- `src/socket.ts` - （旧版）独立 WebSocket 服务器（现已嵌入 MCP 服务器）
## 快速开始（推荐）
使用此 MCP 服务器的最简单方法是直接通过 `npx` 使用。这样可以确保您始终拥有最新版本，而无需下载或本地管理文件。
1. **添加到您的 AI IDE 的 MCP 配置**
进入您的 IDE 的 MCP 设置（例如，Cursor 设置 > MCP），并添加一个新服务器，配置如下：
```json
{
"mcpServers": {
"TalkToFigma": {
"command": "npx",
"args": ["-y", "handle-figma-mcp@latest"]
}
}
}
```
*（注意：嵌入式 WebSocket 服务器将在您的 IDE 运行此命令时自动启动！）*
**故障排除：Mac Homebrew PATH 问题**
如果您的 AI IDE（例如 Cursor）无法找到 `npx`，您可能需要提供绝对路径并注入 PATH 环境变量。*（注意：以下路径是 Apple Silicon Mac 的示例。Intel Mac 通常使用 `/usr/local/bin/npx`。如果不同，请替换为实际路径。）*
```json
{
"mcpServers": {
"TalkToFigma": {
"command": "/opt/homebrew/bin/npx",
"args": ["-y", "handle-figma-mcp@latest"],
"env": {
"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
}
}
}
}
```
2. **安装 Figma 插件**
从 [GitHub](https://github.com/GEON1999/cursor-talk-to-figma-mcp-local/tree/main/src/cursor_mcp_plugin) 下载整个 `cursor_mcp_plugin` 文件夹。然后，在 Figma 中，进入 **插件 > 开发 > 从清单导入插件...** 并选择您下载的文件夹中的 `manifest.json` 文件。
## 快速视频教程
[视频链接](https://www.linkedin.com/posts/sonnylazuardi_just-wanted-to-share-my-latest-experiment-activity-7307821553654657024-yrh8)
## 设计自动化示例
**批量文本内容替换**
感谢 [@dusskapark](https://github.com/dusskapark) 为批量文本替换功能做出的贡献。以下是[演示视频](https://www.youtube.com/watch?v=j05gGT3xfCs)。
**实例覆盖传播**
[@dusskapark](https://github.com/dusskapark) 的另一个贡献。从源实例传播组件实例覆盖到多个目标实例，单次命令即可完成。此功能大大减少了处理需要类似自定义的组件实例时的重复设计工作。请查看我们的[演示视频](https://youtu.be/uvuT8LByroI)。
## 本地开发（适用于贡献者）
如果您想修改代码或为项目做出贡献：
1. 安装 Bun（如果尚未安装）：
```bash
curl -fsSL https://bun.sh/install | bash
```
2. 运行设置：
```bash
bun setup
```
3. 更新您的 AI IDE 的 MCP 配置以运行本地入口点：
```json
{
"mcpServers": {
"TalkToFigma": {
"command": "node",
"args": ["/absolute/path/to/cursor-talk-to-figma-mcp/dist/server.js"]
}
}
}
```
4. 在 Figma 中加载本地插件：
进入插件 > 开发 > 新插件 > “链接现有插件”，然后选择 `src/cursor_mcp_plugin/manifest.json`。
## MCP 工具
MCP 服务器提供以下工具用于与 Figma 交互：
### 文档和选择
- `get_document_info` - 获取当前 Figma 文档的信息
- `get_selection` - 获取当前选择的信息
- `read_my_design` - 获取当前选择的详细节点信息，无需参数
- `get_node_info` - 获取特定节点信息的详细信息
- `get_nodes_info` - 通过提供节点 ID 数组获取多个节点的详细信息
- `set_focus` - 通过选择节点并滚动视口到它来设置特定节点的焦点
- `set_selections` - 将选择设置为多个节点并滚动视口以显示它们
### 注释
- `get_annotations` - 获取当前文档或特定节点的所有注释
- `set_annotation` - 使用 Markdown 支持创建或更新注释
- `set_multiple_annotations` - 批量创建/更新多个注释
- `scan_nodes_by_types` - 扫描具有特定类型的节点（适用于查找注释目标）
### 原型和连接
- `get_reactions` - 从具有视觉高亮动画的节点获取所有原型反应
- `set_default_connector` - 将复制的 FigJam 连接器设置为创建连接的默认连接器样式（必须在创建连接之前设置）
- `create_connections` - 根据原型流程或自定义映射在节点之间创建 FigJam 连接器线
### 创建元素
- `create_rectangle` - 创建具有位置、大小和可选名称的新矩形
- `create_frame` - 创建具有位置、大小和可选名称的新框架
- `create_text` - 创建具有可自定义字体属性的新文本节点
- `create_polygon` - 创建具有位置、大小、点数和样式的新多边形（正多边形）
### 修改文本内容
- `scan_text_nodes` - 扫描具有智能分块的大型设计中的文本节点
- `set_text_content` - 设置单个文本节点的内容
- `set_multiple_text_contents` - 批量更新多个文本节点
### 自动布局和间距
- `set_layout_mode` - 设置框架的布局模式和包装行为（NONE，HORIZONTAL，VERTICAL）
- `set_padding` - 为自动布局框架设置填充值（上、右、下、左）
- `set_axis_align` - 为自动布局框架设置主轴和副轴对齐方式
- `set_layout_sizing` - 为自动布局框架设置水平和垂直尺寸模式（FIXED，HUG，FILL）
- `set_item_spacing` - 在自动布局框架中设置子项之间的距离
### 样式
- `set_fill_color` - 设置节点的填充颜色（RGBA）
- `set_stroke_color` - 设置节点的描边颜色和权重
- `set_corner_radius` - 设置节点的圆角半径，可选每角控制
- `create_paint_style` - 在 Figma 中创建新的颜色样式（油漆样式）。使用文件夹表示法进行分组
- `create_multiple_paint_styles` - 一次创建 Figma 中的多个颜色样式（油漆样式）
- `apply_paint_style` - 将现有的颜色样式（油漆样式）应用于节点的填充
- `rename_paint_style` - 重命名现有的油漆样式
- `swap_style` - 查找特定油漆样式的所有用法并用另一种样式替换
- `create_color_variable` - 创建或更新单个 Figma 颜色变量
- `create_multiple_color_variables` - 一次创建或更新多个 Figma 颜色变量
### 布局和组织
- `move_node` - 将节点移动到新位置
- `resize_node` - 使用新尺寸调整节点大小
- `rename_node` - 在 Figma 中重命名节点
- `delete_node` - 删除节点
- `delete_multiple_nodes` - 一次高效删除多个节点
- `clone_node` - 创建现有节点的副本，可选位置偏移
### 组件和样式
- `get_styles` - 获取本地样式的信息
- `get_local_components` - 获取本地组件的信息
- `create_component_instance` - 创建组件实例
- `get_instance_overrides` - 从选定的组件实例中提取覆盖属性
- `set_instance_overrides` - 将提取的覆盖应用于目标实例
### 导出和高级
- `export_node_as_image` - 将节点导出为图像（PNG，JPG，SVG 或 PDF）- 目前对图像的支持有限，返回 base64 作为文本
### 连接管理
- `join_channel` - 加入特定频道与 Figma 通信
### MCP 提示
MCP 服务器包含几个帮助器提示，引导您完成复杂的 设计任务：
- `design_strategy` - 使用 Figma 设计的最佳实践
- `read_design_strategy` - 读取 Figma 设计的最佳实践
- `text_replacement_strategy` - 在 Figma 设计中替换文本的系统方法
- `annotation_conversion_strategy` - 将手动注释转换为 Figma 原生注释的策略
- `swap_overrides_instances` - 在 Figma 中在组件实例之间传输覆盖的策略
- `reaction_to_connector_strategy` - 使用“get_reactions”的输出将 Figma 原型反应转换为连接器线的策略，并在序列中使用“create_connections”
## 开发
### 构建 Figma 插件
1. 导航到 Figma 插件目录：
```bash
cd src/cursor_mcp_plugin
```
2. 编辑 code.js 和 ui.html
## 最佳实践
使用 Figma MCP 时：
1. 始终在发送命令之前加入频道
2. 首先使用 `get_document_info` 获取文档概述
3. 在修改之前使用 `get_selection` 检查当前选择
4. 根据需要使用适当的创建工具：
- `create_frame` 用于容器
- `create_rectangle` 用于基本形状
- `create_text` 用于文本元素
- `create_polygon` 用于多边形形状
5. 使用 `get_node_info` 验证更改
6. 在可能的情况下使用组件实例以保持一致性
7. 适当地处理错误，因为所有命令都可能抛出异常
8. 对于大型设计：
- 在 `scan_text_nodes` 中使用分块参数
- 通过 WebSocket 更新监控进度
- 实现适当的错误处理
9. 对于文本操作：
- 在可能的情况下使用批量操作
- 考虑结构关系
- 通过有针对性的导出验证更改
10. 对于转换旧版注释：
- 扫描文本节点以识别编号标记和描述
- 使用 `scan_nodes_by_types` 查找注释所指的 UI 元素
- 使用路径、名称或接近度匹配标记与其目标元素
- 使用 `get_annotations` 对注释进行适当分类
- 批量创建原生注释，使用 `set_multiple_annotations`
- 验证所有注释是否正确链接到其目标
- 在成功转换后删除旧版注释节点
11. 将原型线路可视化为 FigJam 连接器：
- 使用 `get_reactions` 提取原型流程，
- 使用 `set_default_connector` 设置默认连接器，
- 使用 `create_connections` 生成连接器线以进行清晰的视觉流程映射。
## License
MIT
