OpenPencil

.fig デザインファイル用の CLI および MCP サーバー。2つの動作モード:

• アプリモード — 実行中の 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 Plugin API)

Figma Plugin 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 '...'

# stdin からコードを読み込み
echo 'figma.currentPage.children.map(n => n.name)' | bun open-pencil eval design.fig --stdin

eval 環境は Figma Plugin API で figma を提供: 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 — 2つのノード間の統合 diff。修正前後の比較や、類似コンポーネント間の差異発見に。
• describe — セマンティック分析: ノードの役割、ビジュアルスタイル、レイアウトプロパティ、潜在的デザイン問題。
• export_image — ノードを PNG にレンダリングして返却。修正後の視覚的検証に。

JSX レンダリング (render ツールまたは eval を経由)

1 回の呼び出しで完全なコンポーネントツリーを作成:

<Frame name="Card" w={320} h="hug" flex="col" gap={16} p={24} bg="#FFF" rounded={16}>
  <Text size={18} weight="bold">Title</Text>
  <Text size={14} color="#666">Description text</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">Action</Text>
    </Frame>
  </Frame>
</Frame>

要素: Frame, Text, Rectangle, Ellipse, Line, Star, Polygon, Group, Section, Component

レイアウト省略記号:

プロパティ	意味
w, h	幅、高さ (数値または "hug" / "fill")
flex	"row" または "col"
grid, columns, rows	CSS Grid — 例: columns="1fr 200px 1fr"
gap, rowGap, columnGap	アイテム間隔
p, px, py, pt, pr, pb, pl	パディング
justify	"start", "center", "end", "between"
items	"start", "center", "end", "stretch"
grow	Flex grow 係数
bg	フィル色 (16進)
rounded, roundedTL/TR/BL/BR	コーナー半径
stroke, strokeWidth	ストローク色と太さ
opacity	0–1
rotate	度数
overflow	"hidden" で子をクリップ
shadow	"offsetX offsetY blur #color"
blur	レイヤーぼかし
size, weight, font, color, textAlign	テキストプロパティ
colStart, rowStart, colSpan, rowSpan	グリッド子要素の位置

ノード ID

形式: session:local (例: 1:23)。ID は find, tree, query, node コマンドから取得。

ヒント

• ファイルパスを省略すると、実行中の OpenPencil エディタで開いているドキュメントで作業できます
• info で始めてドキュメント構造を把握
• tree --depth 2 で出力に圧倒されない概要確認
• query "//COMPONENT" で XPath を使い再利用可能コンポーネントを発見
• query_nodes (MCP) で大規模ファイル内の必要なノードのみを検索 — 全ツリー取得を回避
• get_jsx で修正前のノード構造を確認
• デザイン修正後は export_image で視覚的検証
• analyze colors --similar で近似色を見つけてマージ
• --node で特定ノードをエクスポートするとページ全体より高速
• eval コマンドで CLI にない機能は Figma Plugin API 全体を活用可能
• 出力を他ツールにパイプするときは --json を使用
• アプリモードでの eval 修正はエディタのリアルタイム反映