3. Figma MCP tools

This section lists every Figma MCP tool and what ud does with it. Parameters are Figma’s. Where ud adds an optional parameter it is marked ud. The schemas served by ud schema <tool> and by ud mcp are the compatibility contract tested by SRS CMD-8: each is Figma’s schema for the tool, and the test accepts only these differences (review decision D8):

• extra parameters, all optional, marked ud below;
• the pattern of fileKey and nodeId, and of every other property that carries a node id, array items included (nodeIds[], mappings[].nodeId, currentPageId, …), so that native ids (section 2.3) pass;
• the pattern of planKey, so that ud::local passes (Figma’s is ^(team|organization)::\d+$);
• fileKey dropped from required when ud mcp --file is set (section 8). Without --file it stays required, as in Figma.

Everything else — tool names, descriptions, parameter names, types and the required lists — is Figma’s.

3.1 use_figma#

Runs a script against the document with the figma global (section 4).

¹ Required by the schema, as in Figma. On the command line it can be left out when section 2.2 resolves it; under ud mcp --file it becomes optional in the schema too. The same applies to fileKey in every tool below.

The call is atomic (SRS CMD-12): if the script throws or hits a limit, nothing is applied. The result is one text content item with a JSON object:

{
  "result": { "frameId": "nd-3f9a0c1e7b2d" },
  "createdNodeIds": ["nd-3f9a0c1e7b2d", "nd-91c0d4e2aa17"],
  "changedNodeIds": [],
  "removedNodeIds": [],
  "logs": ["Built login frame"],
  "events": { "from": 412, "to": 431 },
  "durationMs": 38
}

result is the script’s return value, serialised as JSON. Nodes become { "id", "name", "type" }, and figma.mixed becomes "<mixed>". On error the content has isError: true and the text is

Error at line 14, column 9: UnsupportedApiError: figma.createSlice is not supported by UI Designer yet
(planned for 0.2). No changes were applied.

Shell example:

ud use_figma designs/app.design --description "Add a card" --code '
  const card = figma.createFrame();
  card.name = "Card";
  card.layoutMode = "VERTICAL";
  card.itemSpacing = 12;
  card.paddingTop = card.paddingBottom = card.paddingLeft = card.paddingRight = 24;
  card.fills = [{ type: "SOLID", color: { r: 1, g: 1, b: 1 } }];
  figma.currentPage.appendChild(card);
  return { id: card.id };
'

3.2 get_metadata#

Returns the same sparse XML as Figma: element per node, named by type, with id, name, x, y, width, height, and hidden="true" when invisible. When the live editor has a selection, the response starts with a Currently selected nodes: block, as Figma’s does.

<frame id="nd-3f9a0c1e7b2d" name="Login" x="0" y="0" width="390" height="844">
  <text id="nd-91c0d4e2aa17" name="Title" x="24" y="96" width="342" height="36" />
  <instance id="nd-c2e8a1f0937b" name="Button" x="24" y="720" width="342" height="48" />
</frame>

Without nodeId: [{ "id": "pg-0b44e1d2a9c3", "name": "Screens" }, …]. An unknown nodeId returns an error that includes this list. The native form with more detail is ud tree (section 5.3).

3.3 create_new_file#

¹ Required by the schema, as in Figma; any value is accepted.

Result: { "fileKey": "designs/login.design", "url": "ud://designs/login.design", "documentId": "doc-…" }. The file is opened in VS Code when a window is reachable through the bridge, unless --no-open.

3.4 whoami#

No parameters. Result:

{
  "handle": "Claude",
  "email": null,
  "plans": [{ "key": "ud::local", "name": "UI Designer Pro", "seat": "edit" }],
  "actor": "Claude",
  "licence": { "plan": "pro", "state": "active", "offlineGraceUntil": "2026-10-13T09:00:00.000Z" }
}

seat is edit with a paid plan or the trial, otherwise view.

3.5 get_screenshot#

The result has a JSON item { width, height, original_width, original_height, path, url }, and curl instructions like Figma’s. url is a single-use loopback URL (SRS CMD-5) when a server is running to answer it: the extension host when the call goes through the bridge, or ud mcp while it runs (section 3.16). A one-shot headless ud get_screenshot exits before anyone could fetch the URL, so it returns url: null and the file at path; on the command line it prints the path. The native form with more options is ud render (section 5.4).

3.6 upload_assets#

As in Figma, the result lists single-use upload URLs: http://127.0.0.1:<port>/u/<token>. A POST of the raw bytes with the right Content-Type stores the image in <name>.design.assets/ and places it. PNG, JPEG, GIF and WebP become image fills (on the target, or on a new frame of the image’s size). SVG becomes editable vectors. The limit is 10 MB per asset. On the command line, ud upload_assets --paths hero.png logo.svg does it in one step.

The URL protocol needs a server that stays up to receive the POST (section 3.16): the extension host when bridged, or ud mcp while it runs. A one-shot headless ud upload_assets has nobody to serve the URLs, so there --paths is required; without it the command exits 2 (usage) with that hint. Under ud mcp --proposal the entries of paths must be local files; URLs are refused (section 8).

3.7 download_assets#

Result, as in Figma: export (render of the node), rawImages (original source images of fills in the subtree, with format, at most 20) and svgAssets (vector layers best shipped as SVG, at most 20). Each entry has a local path and a loopback url; as for get_screenshot, url is null from a one-shot headless command and set only while a server runs (section 3.16).

3.8 get_variable_defs#

Returns the variables and styles used by the node and its subtree, resolved for the node’s mode (or mode), as Figma’s flat map: { "color/surface": "#FFFFFF", "space/4": "16", "Heading/H1": "Font(family: Inter, style: Bold, size: 32, lineHeight: 40)" }. With --json and --detail ud, each entry also has the variable id, collection, all mode values and the code syntax.

3.9 search_design_system#

Searches the file’s own components, variables and styles and those of every library the file can use (SRS VAR-7). Matches are ranked by name, description, aliases and usage count. Results come in the same order as queries. Each match has key (usable with figma.importComponentByKeyAsync and figma.variables.importVariableByKeyAsync), name, description, libraryKey, libraryName, variant properties for component sets, the resolved value for variables, and the code-map entry when there is one.

3.10 get_libraries#

The result keeps Figma’s shape. libraries_added_to_file: libraries the file uses. libraries_available_to_add: other .design files of the workspace that publish a library (SRS VAR-7), plus libraries listed in the ud.libraries setting, 50 per page. When more remain, libraries_available_to_add_next_offset is the offset for the next call. Each library has name, libraryKey (the library document id), description, sourceType (workspace or setting) and path.

3.11 get_motion_context#

Returns smart-animate transitions and prototype animations of the node (SRS PRO-4) as keyframe tracks with easing, CSS @keyframes and motion.dev snippets, and the coordination hints described in Figma’s documentation.

3.12 get_design_context#

Returns reference code for the node, written by the generators of SRS DEV-2. The default is React with Tailwind, as in Figma. Instances that have a code-map entry (SRS DEV-4) are emitted as the mapped component with its props. Variables appear as their code syntax. The result also has a screenshot and the assets the code refers to, each with a local path and a loopback url that is set only while a server runs (section 3.16). When the code would exceed 40 000 characters and forceCode is not set, the result is the get_metadata outline with a note to call the tool on child nodes, as Figma does.

3.13 Code Connect tools#

They read and write the code map of SRS DEV-4. The code map is stored in the file (codeMap of components) and can be overridden by the ud.codeMap setting.

label takes Figma’s values (React, Web Components, Vue, SwiftUI, Compose, …). template is stored and used by get_design_context when it renders a mapped instance.

3.14 generate_figma_design#

Captures a web page into frames, as Figma’s code-to-canvas does, using the HTML import of SRS EXP-6. The parameters are Figma’s. The capture runs locally through the Browser DevTools extension or a local headless Chromium. Figma’s clipboard output mode is not supported: the target is always a file.

3.15 Unsupported tools#

get_figjam, generate_diagram, generate_image, export_video, list_shaders, get_shader, create_shader, update_shader, list_file_shaders, list_generative_plugins, get_generative_plugin, create_generative_plugin, update_generative_plugin, html_to_figma (use generate_figma_design or ud import html) and the weave_* tools are not served by ud mcp. Called through ud, they exit 6 with a hint, for example: generate_diagram is a FigJam tool. UI Designer designs interfaces; for diagrams use Software Board (uml).

3.16 Loopback URLs#

get_screenshot, download_assets, the assets of get_design_context and the upload URLs of upload_assets keep Figma’s URL protocol so that Figma’s skills work unchanged (review decision D7). The URLs are served by a small HTTP server that exists only while something is running to own it:

Every result that carries a url also carries a local path, and the local path is what a headless script should use. upload_assets headless needs --paths (section 3.6).

Hardening, specified in ARC-001 §9.6 and SRS NFR-4: the server binds 127.0.0.1 only; the Host header must match the address it was given out with, otherwise the request is dropped; requests that carry an Origin header are rejected, so a browser page cannot reach it; bodies are capped at 10 MB; each URL holds a random 128-bit token that is valid for one request and for 10 minutes, after which it answers 404.