FigClank: Docs

Overview

Mode: Read and write. Supports read operations and write operations via agent_* mutation tools.
Auth: OAuth 2.1. All document-scoped tools require user authentication.
Units: All dimensions are in pixels (px) unless otherwise noted.
IDs: All identifiers (nodeId, documentId, componentId, styleId) are strings.

Node Types

type NodeType =
  | "PAGE"
  | "FRAME"
  | "RECTANGLE"
  | "TEXT"
  | "COMPONENT"
  | "INSTANCE"
  | "GROUP"
  | "VECTOR"
  | "ELLIPSE"
  | "LINE"
  | "POLYGON"
  | "STAR"
  | "BOOLEAN_OPERATION";

Core Schemas

MCPNode

The canonical node schema exposed by the MCP. All fields use consistent types and units.

interface MCPNode {
  // Identity
  id: string;
  name: string;
  type: NodeType;
  parentId: string | null;

  // Transform (all in px)
  x: number;
  y: number;
  width: number;
  height: number;
  rotation?: number; // degrees

  // Visibility
  visible?: boolean;
  locked?: boolean;
  opacity?: number; // 0-1

  // Layout (Auto Layout)
  layout?: {
    mode: "NONE" | "HORIZONTAL" | "VERTICAL";
    primaryAxisAlign: "MIN" | "CENTER" | "MAX" | "SPACE_BETWEEN";
    counterAxisAlign: "MIN" | "CENTER" | "MAX" | "STRETCH";
    primaryAxisSizing: "FIXED" | "AUTO" | "FILL";
    counterAxisSizing: "FIXED" | "AUTO" | "FILL";
    padding: { top: number; right: number; bottom: number; left: number; };
    itemSpacing: number | "AUTO";
    wrap?: boolean;
  };

  // Style
  style?: {
    fills?: MCPFill[];
    strokes?: MCPStroke[];
    effects?: MCPEffect[];
    cornerRadius?: number;
    clipsContent?: boolean;
    blendMode?: string;
  };

  // Text (for TEXT nodes)
  text?: {
    characters: string;
    fontSize: number;
    fontFamily: string;
    fontStyle: string;
    textAlignHorizontal: "LEFT" | "CENTER" | "RIGHT" | "JUSTIFIED";
    textAlignVertical: "TOP" | "CENTER" | "BOTTOM";
    autoResize: "WIDTH_AND_HEIGHT" | "HEIGHT" | "NONE";
  };

  // Component reference (for INSTANCE nodes)
  componentRef?: {
    componentId: string;
    componentKey?: string;
  };
}

MCPFill

interface MCPFill {
  type: "SOLID" | "GRADIENT_LINEAR" | "GRADIENT_RADIAL" | "GRADIENT_ANGULAR" | "GRADIENT_DIAMOND" | "IMAGE";
  visible?: boolean;
  opacity?: number; // 0-1
  blendMode?: string;

  // For SOLID
  color?: MCPColor;

  // For gradients
  gradientStops?: Array<{ position: number; color: MCPColor; }>;

  // For IMAGE
  imageRef?: string;
  scaleMode?: "FILL" | "FIT" | "CROP" | "TILE";
}

MCPColor

interface MCPColor {
  r: number; // 0-1
  g: number; // 0-1
  b: number; // 0-1
  a: number; // 0-1
}

MCPEffect

interface MCPEffect {
  type: "DROP_SHADOW" | "INNER_SHADOW" | "LAYER_BLUR" | "BACKGROUND_BLUR";
  visible?: boolean;
  radius?: number; // px
  color?: MCPColor;
  offset?: { x: number; y: number }; // px
  spread?: number; // px
}

Tool Categories

Discovery

Tool	Description
auth_whoami	Get authenticated user info
workspace_listProjects	List user's projects/designs
documents_list	List documents with pagination
documents_get	Get document metadata

Snapshots & History

Tool	Description
documents_getSnapshot	Get lightweight snapshot summary (pin version)
history_listVersions	List document versions

Node Inspection

Tool	Description
nodes_get	Get single node
nodes_listChildren	List children of a node
nodes_getSubtree	Get subtree with depth limit
nodes_query	Query nodes by criteria

Design System

Tool	Description
components_list	List components
components_get	Get component definition
styles_list	List styles
tokens_get	Get design tokens

Export / Render

Tool	Description
render_thumbnail	Get node thumbnail
export_svg	Export node as SVG
export_png	Export node as PNG
export_html	Export frame as HTML
export_css	Generate CSS, Tailwind, or React Native styles
resolve_asset_url	Resolve image reference to public URL

Agent Mutation

Tool	Description
agent_getSelectionSnapshot	Get selection for planner
agent_updateNode	Update node properties
agent_createShape	Create rectangle, ellipse, frame, triangle
agent_createText	Create text node
agent_wrapInAutoLayout	Wrap selection in auto layout
agent_alignNodes	Align selection
agent_distributeNodes	Distribute nodes
agent_groupNodes	Group selection
agent_ungroupNodes	Ungroup GROUP
agent_createComponentFromSelection	Convert selection to component

Error Codes

Tool	Description
NOT_FOUND	Resource does not exist (404)
FORBIDDEN	User lacks permission (403)
VALIDATION_ERROR	Invalid input parameters (400)
RATE_LIMITED	Too many requests (429)
INTERNAL_ERROR	Server error (500)

Version Pinning

All document-scoped tools accept an optional version parameter:

// Load a specific version (deterministic)
call('nodes_get', { nodeId, documentId, version: 42 })

// Load latest (may change between calls)
call('nodes_get', { nodeId, documentId })

Agents should pass version for reproducible codegen workflows.