Skip to main content
Glama
Figma Local Bridge

Figma Local Bridge

by Miart

figma_checkpoint

Save a Figma subtree as inspectable JSON, compare it with the live document, and restore its children in one verified transaction—a manual undo-stack alternative for Plugin API work.

Instructions

Save a subtree as data, compare it against the live document, and rebuild it — the alternative to an undo stack the Plugin API does not offer. action "save" writes an inspectable JSON file; "show" diffs the live subtree against it; "restore" replaces the target's children from it in ONE transaction, dry run first, and verifies itself by dumping the subtree again. Refuses what it cannot promise: node types it cannot rebuild, truncated dumps, a group or instance target, and any restore not asked for out loud. STAR and POLYGON are rebuilt natively with their point count (and STAR's inner radius); BOOLEAN_OPERATION trees are rebuilt from their children with the recorded operation; SLICE nodes come back with their geometry and exportSettings; COMPONENT_SETs are rebuilt from their variant components, with non-variant properties added back by type and default value, their supported metadata and default-value variable bindings restored, and layer references remapped, while other unsupported node types are still refused by name. A save says what a checkpoint-v1 rebuild does not carry (an INSTANCE's interior structure beyond its direct overrides, and component and component-set identity/instances); direct per-layer overrides are captured and replayed by path after the main component is re-instantiated, including per-run text styling inside an overridden text layer, where a link or binding the override removed is cleared before the run snapshot is replayed, and style ids and node-level and run-level variable bindings are re-linked when still present. Every missing link or stale override path is reported.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "figma_checkpoint"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoCheckpoint id; an unambiguous prefix is enough, and "latest" (the default) is the newest for this file
dirNoWhere checkpoints live; defaults to ~/.local/share/opencode/figma-bridge-checkpoints
nameNosave: a label for the id (defaults to the node name)
forceNorestore: rebuild even when the subtree already matches the checkpoint
actionYessave | show (compare live, read-only) | list | drop (a local file) | restore (dry run unless dryRun: false)
dryRunNorestore: default TRUE. false performs the rebuild (also needs allowDestructive and a bridge started with destructive writes)
nodeIdNoThe subtree root. save: defaults to the selection; show/restore: defaults to the checkpoint's own root
compareNoshow: compare against the live subtree (default true). false reads the file only
fileKeyNoWhich connected Figma file to use: its fileKey (figma_whoami) or, when omitted, the only connected file. Required once more than one file is connected; figma_ping lists them.
maxNodesNosave: node cap; a truncated checkpoint cannot be restored
allowPartialNorestore: rebuild what can be rebuilt and list the rest as skipped, instead of refusing
allowDestructiveNorestore: required for a real rebuild — it deletes the target's current children

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.36.0

TDQS

A3.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses one-transaction restore, dry-run-first behavior, self-verification, refusal of truncated dumps and group/instance targets, exact node types that are unsupported, override replay semantics, and reporting of missing links or stale paths. This is unusually rich behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is front-loaded and clear, but the body becomes a dense, semicolon-heavy run-on paragraph. The COMPONENT_SET and override-replay details are relevant, but they are hard to parse and could be better structured as bullets or a shorter summary. It is informative but not concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, multi-action, destructive checkpoint tool with no output schema, the description is largely complete: it covers transactionality, refusals, supported node types, save limitations, and override replay. It omits prose coverage of the list and drop actions and does not specify exact return shapes, which prevents a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the baseline is 3. The description adds action-level context but does not add meaning beyond the schema for parameters such as fileKey, maxNodes, allowPartial, or dryRun. Most parameter semantics remain in the structured schema, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and set of verbs: saving a subtree as data, comparing it against the live document, and rebuilding it. It also explains the save/show/restore actions distinctly. It does not differentiate itself from sibling tools and does not mention the list/drop actions, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The action descriptions imply when to use save, show, and restore, and restore is explicitly framed as needing dry run and destructive-write authorization. However, there is no explicit guidance on when to choose this tool over siblings such as figma_compare or figma_journal. The refusal conditions are behavioral constraints, not clear usage routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.