OpenPencil

用于 .fig 设计文件的 CLI 和 MCP 服务器。两种操作模式：

• 应用模式 — 连接到正在运行的 OpenPencil 编辑器（省略文件参数）
• 无头模式 — 直接处理 .fig 文件（传递文件路径）

# 应用模式 — 操作编辑器中打开的文档
bun open-pencil tree

# 无头模式 — 操作 .fig 文件
bun open-pencil tree design.fig

应用运行时会在 http://127.0.0.1:7600 上暴露一个自动化桥接。当未提供文件路径时，CLI 会自动连接到它。

CLI 命令

检查

# 文档概览 — 页面、节点数量、字体
bun open-pencil info design.fig

# 节点树 — 显示带有类型和大小的层级结构
bun open-pencil tree design.fig
bun open-pencil tree --page "Components" --depth 3  # 应用模式，特定页面

# 列出页面
bun open-pencil pages design.fig

# 详细的节点属性 — 填充、描边、效果、布局、文本
bun open-pencil node design.fig --id 1:23
bun open-pencil node --id 1:23  # 应用模式

# 列出设计变量和集合
bun open-pencil variables design.fig
bun open-pencil variables --collection "Colors" --type COLOR

搜索

# 按名称查找（部分匹配，不区分大小写）
bun open-pencil find design.fig --name "Button"

# 按类型查找
bun open-pencil find --type FRAME                          # 应用模式
bun open-pencil find design.fig --type TEXT --page "Home"

# 组合筛选条件
bun open-pencil find design.fig --name "Card" --type COMPONENT --limit 50

XPath 查询

使用 XPath 选择器查找节点 — 按类型、属性和树结构筛选：

# 所有框架
bun open-pencil query design.fig "//FRAME"

# 宽度小于 300px 的框架
bun open-pencil query design.fig "//FRAME[@width < 300]"

# 名称中包含 "Button" 的文本
bun open-pencil query design.fig "//TEXT[contains(@name, 'Button')]"

# 具有自动布局的组件
bun open-pencil query design.fig "//COMPONENT[@stackMode]"

# 深层嵌套 — 组件内的框架内的文本
bun open-pencil query design.fig "//COMPONENT//FRAME//TEXT"

# 应用模式
bun open-pencil query "//FRAME[@width > 1000]"

节点类型：FRAME、TEXT、RECTANGLE、ELLIPSE、VECTOR、GROUP、COMPONENT、COMPONENT_SET、INSTANCE、SECTION、LINE、STAR、POLYGON、SLICE、BOOLEAN_OPERATION

导出

# PNG（默认）
bun open-pencil export design.fig -o hero.png
bun open-pencil export -o hero.png  # 应用模式 — 从运行中的编辑器导出

# 以 2 倍大小导出特定节点
bun open-pencil export design.fig --node 1:23 -s 2 -o button@2x.png

# JPG 并指定质量
bun open-pencil export design.fig -f jpg -q 85 -o preview.jpg

# SVG
bun open-pencil export design.fig -f svg --node 1:23 -o icon.svg

# JSX（OpenPencil 格式 — 可渲染回 .fig 文件）
bun open-pencil export design.fig -f jsx -o component.jsx

# JSX（Tailwind — 带 Tailwind 类的 React 组件）
bun open-pencil export design.fig -f jsx --style tailwind -o component.tsx

# 页面缩略图
bun open-pencil export design.fig --thumbnail --width 1920 --height 1080

# 特定页面
bun open-pencil export --page "Components" -o components.png

分析

# 调色板 — 使用频率、相似颜色
bun open-pencil analyze colors design.fig
bun open-pencil analyze colors --similar --threshold 10  # 应用模式

# 排版 — 字体族、字号、字重
bun open-pencil analyze typography design.fig --group-by size

# 间距 — 间隙和内边距值、网格合规性
bun open-pencil analyze spacing design.fig --grid 8

# 聚类 — 可成为组件的重复模式
bun open-pencil analyze clusters design.fig --min-count 3

Eval（Figma 插件 API）

使用完整的 Figma 插件 API 对文档执行 JavaScript：

# 只读 — 查询文档
bun open-pencil eval design.fig -c 'figma.currentPage.findAll(n => n.type === "TEXT").length'

# 应用模式 — 修改编辑器中的实时文档
bun open-pencil eval -c '
  const buttons = figma.currentPage.findAll(n => n.name === "Button");
  buttons.forEach(b => { b.cornerRadius = 8 });
  buttons.length + " buttons updated"
'

# 修改并保存到文件
bun open-pencil eval design.fig -w -c '
  const texts = figma.currentPage.findAll(n => n.type === "TEXT");
  texts.forEach(t => { t.fontSize = 16 });
'

# 保存到不同的文件
bun open-pencil eval design.fig -o modified.fig -c '...'

# 从标准输入读取代码
echo 'figma.currentPage.children.map(n => n.name)' | bun open-pencil eval design.fig --stdin

eval 环境提供了 figma 对象，支持 Figma 插件 API：figma.currentPage、figma.createFrame()、figma.createText()、figma.getNodeById() 等。

JSON 输出

每个命令都支持 --json 以实现机器可读的输出：

bun open-pencil info design.fig --json
bun open-pencil find --name "Button" --json  # 应用模式
bun open-pencil analyze colors design.fig --json

MCP 服务器

Stdio（Claude Desktop、Cursor）

添加到您的 MCP 配置中：

{
  "mcpServers": {
    "open-pencil": {
      "command": "npx",
      "args": ["openpencil-mcp"]
    }
  }
}

HTTP（多会话、远程）

export PORT=3100
export OPENPENCIL_MCP_AUTH_TOKEN=secret       # 可选的认证令牌
export OPENPENCIL_MCP_CORS_ORIGIN="*"         # 可选的 CORS 设置
export OPENPENCIL_MCP_ROOT=/path/to/files     # 限制文件访问

npx openpencil-mcp-http

MCP 工作流程

1. 打开文件 — open_file { path: "/path/to/design.fig" } 或 new_document {}
2. 查询 — get_page_tree、find_nodes、query_nodes、get_node、list_pages 等
3. 检查 — get_jsx（JSX 视图）、diff_jsx（结构差异）、describe（语义分析）、export_image（视觉截图）
4. 修改 — render（JSX）、set_fill、set_layout、create_shape 等
5. 保存 — save_file { path: "/path/to/output.fig" }

MCP 工具（共 94 个）

读取（14 个）： get_selection、get_page_tree、get_node、find_nodes、query_nodes、get_components、list_pages、switch_page、get_current_page、page_bounds、select_nodes、list_fonts、get_jsx、diff_jsx

创建（7 个）： create_shape、render、create_component、create_instance、create_page、create_vector、create_slice

修改（20 个）： set_fill、set_stroke、set_effects、update_node、set_layout、set_constraints、set_rotation、set_opacity、set_radius、set_min_max、set_text、set_font、set_font_range、set_text_resize、set_visible、set_blend、set_locked、set_stroke_align、set_text_properties、set_layout_child

结构（17 个）： delete_node、clone_node、rename_node、reparent_node、group_nodes、ungroup_node、flatten_nodes、node_to_component、node_bounds、node_move、node_resize、node_ancestors、node_children、node_tree、node_bindings、node_replace_with、arrange_nodes

变量（11 个）： list_variables、list_collections、get_variable、find_variables、create_variable、set_variable、delete_variable、bind_variable、get_collection、create_collection、delete_collection

矢量与导出（14 个）： boolean_union、boolean_subtract、boolean_intersect、boolean_exclude、path_get、path_set、path_scale、path_flip、path_move、viewport_get、viewport_set、viewport_zoom_to_fit、export_svg、export_image

分析与检查（8 个）： analyze_colors、analyze_typography、analyze_spacing、analyze_clusters、diff_create、diff_show、describe、eval

文件（3 个）： open_file、save_file、new_document

面向 AI 智能体的关键工具

• query_nodes — 使用 XPath 选择器查找特定节点，无需获取整个树。对于大型文件至关重要。
• get_jsx — 将任何节点视为 JSX（与 render 工具接受的格式相同）。在修改前了解结构很有用。
• diff_jsx — 两个节点之间的统一差异。比较前后变化，或查找相似组件之间的差异。
• describe — 语义分析：节点扮演的角色、其视觉样式、布局属性以及潜在的设计问题。
• export_image — 将节点渲染为 PNG 并返回。在修改后进行视觉验证。

JSX 渲染（通过 render 工具或 eval）

一次调用即可创建完整的组件树：

<Frame name="Card" w={320} h="hug" flex="col" gap={16} p={24} bg="#FFF" rounded={16}>
  <Text size={18} weight="bold">标题</Text>
  <Text size={14} color="#666">描述文本</Text>
  <Frame flex="row" gap={8}>
    <Frame w={80} h={36} bg="#3B82F6" rounded={8} justify="center" items="center">
      <Text size={14} color="#FFF" weight="600">操作</Text>
    </Frame>
  </Frame>
</Frame>

元素： Frame、Text、Rectangle、Ellipse、Line、Star、Polygon、Group、Section、Component

布局简写：

节点 ID

格式：session:local（例如 1:23）。从 find、tree、query 或 node 命令获取 ID。

提示

• 省略文件路径以操作在运行的 OpenPencil 编辑器中打开的文档
• 从 info 开始了解文档结构
• 使用 tree --depth 2 快速概览，避免输出过于冗长
• 使用 query "//COMPONENT" 通过 XPath 发现可复用组件
• 在大型文件中使用 query_nodes（MCP）精确找到所需节点 — 避免获取整个树
• 在修改前使用 get_jsx 查看节点结构
• 修改设计后，使用 export_image 进行视觉验证
• 使用 analyze colors --similar 查找需要合并的近似重复颜色
• 使用 --node 导出特定节点而不是整个页面，以获得更快的速度
• eval 命令为您提供了 CLI 未覆盖的完整 Figma 插件 API
• 当需要将输出传递给其他工具时，使用 --json
• 在应用模式下，eval 的修改会实时反映在编辑器中