FigClank: Docs

Capabilities

This MCP can:

Read nodes, styles, components, and tokens from design documents
Query nodes by type, name, component, size, and text style
Export nodes as SVG, PNG, HTML, or CSS
Inspect screens for layout, component usage, and text content
Mutate designs: create shapes/text, update nodes, align, distribute, group, wrap in auto layout, create components

Quick Start Strategy

1. documents_getSnapshot → Get document overview + pin version
2. tokens_get → Load design system tokens early
3. nodes_query → Find target screen/frame
4. nodes_getSubtree → Get screen node tree
5. components_get → Resolve INSTANCE references
6. export_svg / export_css → Export assets or generate styles
7. Generate code using gathered information

For mutations:
8. agent_getSelectionSnapshot → Get selection for planner
9. agent_updateNode, agent_createShape, etc. → Apply changes
10. User clicks Sync from MCP in app to pull updates

Recommended Patterns

Always Pin Version

const snapshot = await call('documents_getSnapshot', { documentId });
const version = snapshot.version;

// Use version in ALL subsequent calls for this document
await call('nodes_get', { documentId, version, nodeId });
await call('tokens_get', { documentId, version });

Use tokens_get Early

Design tokens inform all code generation. Load them first:

const { tokens } = await call('tokens_get', { documentId, version });
// tokens.colors, tokens.spacing, tokens.radii, tokens.typography, tokens.shadows

Prefer getSubtree Over Full Snapshots

Never try to load the entire document at once:

// GOOD: Get specific screen subtree
await call('nodes_getSubtree', {
  nodeId: screenId,
  documentId,
  version,
  depth: 6,
  maxNodes: 500,
  detailLevel: 'full',
});

// BAD: Don't try to load everything
// (No such tool exists intentionally)

Always Resolve INSTANCE via components_get

INSTANCE nodes reference components. Get the definition:

for (const instance of instances) {
  if (instance.componentRef?.componentId) {
    const component = await call('components_get', {
      componentId: instance.componentRef.componentId,
      documentId,
      version,
    });
  }
}

Export Only When Necessary

Prefer SVG for icons and vectors. Only export when needed:

// Export icons as SVG
if (node.type === 'VECTOR') {
  const { svg } = await call('export_svg', { nodeId: node.id, documentId, version });
}

Mapping Rules

Typography

FigClank Property	CSS/React Native
`fontName.family`	`fontFamily`
`fontSize`	`fontSize (px)`
`fontName.style`	`fontWeight, fontStyle`
`lineHeight.value (PIXELS)`	`lineHeight (px)`
`lineHeight.value (PERCENT)`	`lineHeight (em/ratio)`
`letterSpacing.value (PIXELS)`	`letterSpacing (px)`
`textAlignHorizontal`	`textAlign`

Spacing/Radius

FigClank Property	CSS Property
`layout.padding.top`	`paddingTop (px)`
`layout.itemSpacing`	`gap (px)`
`style.cornerRadius`	`borderRadius (px)`

Layout (Auto Layout)

FigClank Layout	CSS Flexbox
`mode: HORIZONTAL`	`flexDirection: row`
`mode: VERTICAL`	`flexDirection: column`
`primaryAxisAlign: MIN`	`justifyContent: flex-start`
`primaryAxisAlign: CENTER`	`justifyContent: center`
`primaryAxisAlign: MAX`	`justifyContent: flex-end`
`primaryAxisAlign: SPACE_BETWEEN`	`justifyContent: space-between`
`counterAxisAlign: MIN`	`alignItems: flex-start`
`counterAxisAlign: CENTER`	`alignItems: center`
`counterAxisAlign: STRETCH`	`alignItems: stretch`
`primaryAxisSizing: AUTO`	`No explicit width/height`
`primaryAxisSizing: FILL`	`flex: 1`

Colors

FigClank colors are 0-1 floats. Convert to hex:

function colorToHex(color: MCPColor): string {
  const r = Math.round(color.r * 255);
  const g = Math.round(color.g * 255);
  const b = Math.round(color.b * 255);
  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
}

Very complex vector shapes with multiple boolean operations may lose some fidelity in SVG export. For complex illustrations, consider exporting as PNG (if supported), simplifying in the design, or using external asset references.

Text Overflow Behavior

Text overflow and truncation may differ between platforms. FigClank uses Figma-style text rendering. Web/iOS/Android have different text engines. Test text-heavy components carefully.

Constraints vs Auto Layout

Designs can use either constraints (absolute positioning) or auto layout (flexbox). Check node.layout.mode - if not "NONE", it's auto layout. Check node.constraints for positioned elements. Some frames mix both approaches.

Agent Mutation Tools

Agents can mutate designs with these tools:

Tool	Description
agent_getSelectionSnapshot	Compact JSON of selection for planner context
agent_updateNode	Update fills, effects, width, height, cornerRadius, opacity
agent_createShape	Create rectangle, ellipse, frame, or triangle
agent_createText	Create a text node
agent_wrapInAutoLayout	Wrap selection in auto layout frame
agent_alignNodes	Align selection (left, center, right, top, middle, bottom)
agent_distributeNodes	Distribute with even spacing
agent_groupNodes	Group selection into GROUP
agent_ungroupNodes	Ungroup a GROUP
agent_createComponentFromSelection	Convert selection to reusable component

Rate Limits

Tool	Description
General API calls	100/min
export_svg	20/min
nodes_getSubtree	30/min
nodes_query	60/min

If rate limited, wait and retry with exponential backoff.

Error Handling

Common error codes:

Tool	Description
NOT_FOUND	Document/node doesn't exist – Check IDs
FORBIDDEN	No access to resource – Verify permissions
VALIDATION_ERROR	Invalid parameters – Check input format
RATE_LIMITED	Too many requests – Wait and retry

FigClank MCP Agent Guide