agentleFS
dabowmandabowman/Figmagent/skills/add-mcp-tool/SKILL.md

add-mcp-tool

Skill0 starsChanged 2 months agoMITView on GitHub

Add a new tool or wire command to the Figmagent MCP server. Use when extending Figmagent itself — adding an MCP tool in src/figmagent_mcp/tools/, a plugin command handler, a registry entry, or a remote-transport domain mapping. Not for using Figma via the existing tools.

12 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 11 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when adding new tools or commands that let AI agents control Figma through the MCP server.

    line 8
  2. Very specific:

    Run bun run build:plugin (regenerates code.js), bun test, bun run check.

    line 35
  3. Very specific:

    Errors state fixes: use fail(message, fix) from helpers.js — no user-facing error without a stated fix.

    line 85

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill: Adding a New MCP Tool to Figmagent

Use this skill when adding new tools or commands that let AI agents control Figma through the MCP server.

Architecture Overview

One command implementation serves two transports. The relay and plugin UI are generic routers — adding a new tool never touches them:

plugin:  MCP Server (tools/*.ts) ←WS→ Relay (socket.ts) ←WS→ Plugin UI (ui.html) ←postMessage→ code.js (registry dispatch)
remote:  MCP Server (tools/*.ts) → remote/executor.ts → per-domain bundle of the same command modules → Figma's use_figma VM

MCP tool names (first arg of server.tool) are decoupled from wire command names — e.g. the edit tool sends the apply wire command. Pick an agent-facing tool name freely; the wire command name is permanent protocol (it never changes after shipping — renames happen at the MCP layer only).

Before adding a tool, check it's needed: write/edit already cover most node creation/mutation, grep/read cover search/reads, and run_script is the escape hatch for one-offs. New first-class tools should come from recurring needs (recurring run_script scripts in session logs are the roadmap).

Files to edit for a new wire command (the checklist that tests enforce)

  1. src/figma_plugin/src/commands/<domain>.js — the handler function. Takes a single params object, returns a JSON-serializable result. Runs in BOTH Figma VMs (see constraints below).
  2. src/figma_plugin/src/registry/<domain>.js — registry entry:
    my_command: { lock: "read", handler: (params) => myCommand(params) },
    lock is the concurrency class: "read" (runs freely), "global" (serialized via global mutex — tree mutations, batch writes), "node" (locks by params.nodeId — single-node writes). The registry is the single source of truth; main.js dispatches from it and the remote entry shim (src/figma_plugin/src/remote_entries/<domain>.js) picks the new command up automatically — do not edit the shim.
  3. src/figmagent_mcp/remote/domains.ts — add the command to COMMAND_DOMAINS (command → bundle domain). If it's a pure read, also add it to REMOTE_READ_COMMANDS (controls the atomic-retry suffix on remote errors).
  4. src/figmagent_mcp/types.ts — add the wire name to the FigmaCommand union.
  5. tests/registry.test.ts — add the wire name to EXPECTED_COMMANDS, and to EXPECTED_READ or EXPECTED_GLOBAL if its lock is read/global (anything not in those lists must be node). This test also asserts COMMAND_DOMAINS mirrors the registry — steps 2/3/5 fail loudly if they drift.
  6. src/figmagent_mcp/tools/<domain>.ts — the MCP tool registration (or extend an existing tool's schema — folding an op into edit/write is often better than a new tool).
  7. Run bun run build:plugin (regenerates code.js), bun test, bun run check.

Files you do NOT edit: src/socket.ts (relay), src/figma_plugin/ui.html (forwarder), src/figma_plugin/src/remote_entries/<domain>.js (auto-derived from the registry), src/figma_plugin/code.js (build artifact — never hand-edit).

New domain instead of new command? Also create src/figma_plugin/src/registry/<newdomain>.js + src/figma_plugin/src/remote_entries/<newdomain>.js (copy an existing shim, swap the import), register the domain in src/figma_plugin/src/registry.js (DOMAINS), and keep the bundle under 40KB (asserted in tests).

Request/Response Lifecycle

Plugin transport:

  1. tools/<domain>.ts handler calls sendCommandToFigma(wireCommand, params) (from ../connection.js)
  2. A UUID is generated, stored in pendingRequests with resolve/reject callbacks and a 30s timeout (extended when progress updates arrive)
  3. Message → relay → plugin UI → code.js, which looks the command up in the registry, acquires the lock, runs the handler
  4. Result (sanitized of figma.mixed symbols) flows back and resolves the promise by UUID

Remote transport: the same sendCommandToFigma call routes through remote/executor.ts, which prepends the domain's bundled IIFE, injects params as JSON, awaits globalThis.__figmagent.<command>(params) inside one use_figma script, and returns the JSON result. Scripts are atomic (a thrown error rolls back everything) and queue FIFO per fileKey. sendProgressUpdate is a no-op remotely.

Critical: the wire command string must match EXACTLY across sendCommandToFigma("my_command"), the registry key, COMMAND_DOMAINS, and FigmaCommand. Parameter shapes must agree between the Zod schema and the handler's destructuring — there is no shared schema, just convention (and tests).

MCP tool registration template

server.tool(
  "my_new_tool",                               // agent-facing name
  "Description — this is the source of truth the agent reads. State capabilities, call shapes, and constraints here, not in CLAUDE.md.",
  {
    nodeId: z.string().describe("The ID of the node to modify"),
    someValue: z.number().describe("A numeric value"),
  },
  async ({ nodeId, someValue }: any) => {
    try {
      const result = await sendCommandToFigma("my_new_tool", { nodeId, someValue });
      return { content: [{ type: "text", text: JSON.stringify(result) }] };
    } catch (error) {
      return {
        content: [
          { type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` },
        ],
      };
    }
  }
);

For write tools, append formatWarningsBlock(result.warnings) (from ../utils.js) to surface post-write assertion warnings, and consider running runPostWriteAssertions/miniLint in the handler (see commands/create.js / commands/apply.js for the pattern).

Handler constraints (both Figma VMs)

  • Async-first: await figma.getNodeByIdAsync(nodeId), never the sync version; await page.loadAsync() before touching another page's children.
  • No ?., no ??, no object spread ({ ...obj }) in src/figma_plugin/src/ — the VMs reject them and Bun does not transpile them down. Use Object.assign({}, obj). Array spread is fine. Biome enforces part of this.
  • Strict property guard: the remote VM throws on reading properties that don't exist on a node type. Use prop(node, "name") (from helpers.js) for any duck-typed read at serializer/read boundaries.
  • Errors state fixes: use fail(message, fix) from helpers.js — no user-facing error without a stated fix.
  • Font loading before text mutation: await figma.loadFontAsync(node.fontName) before setting .characters; for mixed fonts use the existing setCharacters() from setcharacters.js.
  • Immutable property arrays: clone-modify-reassign .fills/.strokes/.effects (JSON.parse(JSON.stringify(...))); never mutate in place.
  • Colors are 0–1 floats, opacity separate.
  • Type-check before type-specific access: if (!("fills" in node)) fail(...) or if (node.type !== "TEXT") fail(...).
  • Return JSON-serializable values only (no Figma objects; run results through sanitizeSymbols if they may contain figma.mixed — the registry shim and routeCommand do this for you on the standard paths).

Batch/chunked pattern (10+ nodes)

Chunk with CHUNK_SIZE = 5: chunks sequential, items within a chunk parallel (Promise.all). Call sendProgressUpdate(commandId, type, status, progress, total, processed, message) per chunk — on the plugin path it resets the server-side inactivity timeout (30s → extended); remotely it's a harmless no-op. params.commandId is injected by sendCommandToFigma. Return { success, totalCount, successCount, failureCount, results } with per-item success/error entries — batches continue past per-op failures.

See setMultipleTextContents in commands/text.js for the canonical implementation.

Helpers available in src/figma_plugin/src/

Helper (module)Purpose
prop(node, name) (helpers)Strict-guard property read — required for duck-typed reads on the remote VM
fail(message, fix) (helpers)Throw an error that states its fix
sendProgressUpdate(...) (helpers)Progress through the chain — required for batch ops on the plugin path
loadFontWithFallback(family, weightOrStyle) (helpers)Font resolution with fallback chain (weight→style name→Inter Regular)
setCharacters(node, text, options) (setcharacters)Font-safe text replacement (mixed fonts)
sanitizeSymbols(obj) (helpers)Replace figma.mixed symbols with the string "mixed"
toNumber(value, fallback), rgbaToHex(color), delay(ms), generateCommandId(), findNodeByIdInTree(nodeId), customBase64Encode(bytes) (helpers)Utilities
runPostWriteAssertions(ctx), checkNodes(nodeIds) (assertions)Post-write structural warnings (balloon, width collapse, FILL-not-applied, font fallback, overlaps)
matchVariable(...), miniLint(rawSets) (commands/lint)Write-time exact-match variable suggestions

Checklist

  • Wire command string identical in tools/<domain>.ts, registry/<domain>.js, remote/domains.ts, types.ts
  • Registry entry has the right lock (read/global/node)
  • tests/registry.test.ts EXPECTED lists updated (EXPECTED_COMMANDS always; EXPECTED_READ/EXPECTED_GLOBAL per lock)
  • REMOTE_READ_COMMANDS updated if the command is a pure read
  • Handler takes a single params object; param names match the Zod schema
  • No ?./??/object-spread; prop() for duck-typed reads; fail(message, fix) for errors
  • Font loaded before text mutation (if applicable); node type/capability checked
  • Batch operations chunked with sendProgressUpdate()
  • Tool description carries the full agent-facing knowledge (descriptions are the source of truth, not CLAUDE.md)
  • bun run build:plugin + bun test + bun run check all green

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.