mcpField
F
figma-blame-node

figma-blame-node

github.com/southleftデザイン・UI94120 回インストール10 週間前に更新
リポジトリ

figma-blame-node について

figma-blame-node は、二分探索で Figma のバージョン履歴を調べ、コンポーネントプロパティや子孫ノードが初めて現れたバージョンを特定するシェルベースのスキルです。バージョンと作者の情報に加え、帰属の確実性も返します。

主な機能

  1. 01二分探索によるバージョン履歴の検索
  2. 02コンポーネントプロパティまたは子ノードの追跡
  3. 03バージョンラベル・作者・日時の取得
  4. 04帰属の確実性とプローブ数の表示
  5. 05自動保存の包含・除外

活用シーン

  1. 01コンポーネントプロパティの追加時期の特定
  2. 02子ノードを導入したバージョンの特定
  3. 03帰属の確実性や検索範囲の確認
  4. 04自動保存を含めるか選んで履歴を検索

MCP 対応

MCP サーバーではなくスキルです。README では、個人アクセストークンを使ってシェルから Figma REST API を呼び出す方法を説明しています。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/southleft/figma-console-mcp-skills --skill figma-blame-node

インストール後、Claude Code で/figma-blame-nodeを入力して読み込まれたか確認します。

同梱ファイルscripts/blame-node.mjs

詳細

figma-blame-node — 変更を導入したバージョンを二分探索する

git blame の Figma 版です。ノードと対象（componentPropertyDefinitions のキー、または子孫ノード ID）を指定すると、対象を最初に導入したバージョンを特定し、そのバージョンのラベル、作成者のハンドル、タイムスタンプを返します。

セットアップ — ターミナルとトークンが必要です。 このスキルはシェルコマンドを実行するため、Claude Code（Claude Desktop 内の「Code」タブを含む）、Cursor、Codex、Gemini CLI で動作します。通常の Claude Desktop や claude.ai のチャットでは動作しません（シェルがありません）。Figma コネクターの OAuth ログインではこれらの REST API 呼び出しを認証できないため、ご自身の Figma パーソナルアクセストークンを用意する必要があります。Figma で Settings → Security → Personal access tokens を開き、File content: read（および File versions: read）のスコープを付与してトークンを生成し、シェルで設定してください：export FIGMA_TOKEN="figd_…"。スクリプトは実行時に環境変数から読み取ります。トークンをスキルファイルに記載しないでください。

二分探索を使う理由

単純な探索では、各バージョンのノードを取得するため、バージョン数が N なら API 呼び出しが N 回必要です。対象の存在は単調です（一度追加されると、HEAD までの新しいすべてのバージョンに存在します）。そのため、二分探索を行います。中間点を調べ、対象が存在するかを確認してから、古い側か新しい側に絞り込みます。呼び出しは約 log2(N) 回で済みます。たとえば、200 バージョンなら 200 回ではなく約 8 回のプローブで済みます。Figma REST API はトークンごとにレート制限があり、古いスナップショットは不変なので、プローブ回数が少ないほど確実に有利です。

セットアップとスキルの境界

  • すべてのリクエストは https://api.figma.com に対して X-Figma-Token: $FIGMA_TOKEN を使用します。

ファイルキーを特定する

FILE_KEY=$(echo "$FILE_URL" | sed -E 's#.*/(design|file)/([A-Za-z0-9]+).*#\2#')

ワークフロー

  1. ノードと対象を特定します。 node_id は通常 COMPONENT_SET です。対象は次のいずれか一つだけです。

    • --property '<key>' — Disabled#1:2 のような componentPropertyDefinitions のキー、または
    • --child '<node_id>' — node_id の配下に存在するはずの子孫ノード ID。

    検索範囲を絞り込む場合や ID を確認する場合は、先にバージョン一覧を取得してください。

    ../figma-version-history/scripts/list-versions.sh ABC123def456 --autosaves

  2. scripts/blame-node.mjs で blame 検索を実行します。

    # When was a component property first added?
node scripts/blame-node.mjs --file ABC123def456 --node 695:313 --property 'Disabled#1:2'

# When was a child node first added under a component set?
node scripts/blame-node.mjs --file ABC123def456 --node 695:313 --child 695:340

# Bound the lookback and start from a specific version instead of HEAD
node scripts/blame-node.mjs --file ABC123def456 --node 695:313 --property 'Size#9:0' \
  --start 4096800000 --max 100 --no-autosaves

    JSON が出力されます。対象を導入したバージョン（version_id、label、user_handle、created_at）、attribution_certainty、および呼び出し回数の少なさを確認できる probes_made が含まれます。

結果の読み方

attribution_certainty は、結果をどの程度信頼できるかを示します。

  • exact — 実在するバージョンが対象を導入し、作成者を特定できます。
  • system_attributed — 対象を導入したバージョンは、システムによる自動保存でした（user = "Figma"）。変更を含む最も近いラベル付きバージョンに合わせるには、--no-autosaves を指定して再実行してください。
  • exists_at_lookback_horizon — スキャンした最古のバージョンにも対象が存在するため、実際に導入されたのは検索範囲より前です。--max を増やしてください。
  • metadata_unavailable — 対象は --start 自体で導入されていますが、バージョン一覧をさかのぼっても作成者のメタデータが見つかりませんでした。対象の導入は確かですが、REST API からユーザーを特定することはできません。

注意事項と制限

  • 単調性の前提： 二分探索では、対象は一度追加されたら削除されないと仮定します。追加後に削除され、再度追加された場合、報告される導入ポイントは後の再追加時になる可能性があります。
  • --start には対象が存在している必要があります。 「これがいつ導入されたか」を調べるため、検索開始時のバージョン（デフォルトは HEAD／current）に対象が存在している必要があります。削除されたものを追跡するには、まだ存在していた時点の --start を選んでください。
  • より細かく特定できるよう、自動保存はデフォルトで含まれます（多くの自動保存には実際のユーザーが記録されています）。人がラベルを付けたバージョンだけを対象にするには、--no-autosaves を指定してください。
  • 検索中の 404 は通常、プローブした version_id が保存期間の制限により削除されたことを意味します。再実行してください。検索ではノードが見つからないバージョンを許容し、スキップします。

コメント

Markdown 対応