set_annotation
Create or update annotations in Figma designs programmatically, enabling precise collaboration and documentation between Cursor AI and Figma.
Instructions
Create or update an annotation
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
}
Implementation Reference
- src/cursor_mcp_plugin/code.js:2206-2302 (handler)Figma plugin handler for 'set_annotation' command. Validates parameters, retrieves node, creates annotation object with labelMarkdown, optional categoryId and properties, and sets node.annotations = [newAnnotation]. Returns success status and updated annotations.async function setAnnotation(params) { try { console.log("=== setAnnotation Debug Start ==="); console.log("Input params:", JSON.stringify(params, null, 2)); const { nodeId, annotationId, labelMarkdown, categoryId, properties } = params; // Validate required parameters if (!nodeId) { console.error("Validation failed: Missing nodeId"); return { success: false, error: "Missing nodeId" }; } if (!labelMarkdown) { console.error("Validation failed: Missing labelMarkdown"); return { success: false, error: "Missing labelMarkdown" }; } console.log("Attempting to get node:", nodeId); // Get and validate node const node = await figma.getNodeByIdAsync(nodeId); console.log("Node lookup result:", { id: nodeId, found: !!node, type: node ? node.type : undefined, name: node ? node.name : undefined, hasAnnotations: node ? "annotations" in node : false, }); if (!node) { console.error("Node lookup failed:", nodeId); return { success: false, error: `Node not found: ${nodeId}` }; } // Validate node supports annotations if (!("annotations" in node)) { console.error("Node annotation support check failed:", { nodeType: node.type, nodeId: node.id, }); return { success: false, error: `Node type ${node.type} does not support annotations`, }; } // Create the annotation object const newAnnotation = { labelMarkdown, }; // Validate and add categoryId if provided if (categoryId) { console.log("Adding categoryId to annotation:", categoryId); newAnnotation.categoryId = categoryId; } // Validate and add properties if provided if (properties && Array.isArray(properties) && properties.length > 0) { console.log( "Adding properties to annotation:", JSON.stringify(properties, null, 2) ); newAnnotation.properties = properties; } // Log current annotations before update console.log("Current node annotations:", node.annotations); // Overwrite annotations console.log( "Setting new annotation:", JSON.stringify(newAnnotation, null, 2) ); node.annotations = [newAnnotation]; // Verify the update console.log("Updated node annotations:", node.annotations); console.log("=== setAnnotation Debug End ==="); return { success: true, nodeId: node.id, name: node.name, annotations: node.annotations, }; } catch (error) { console.error("=== setAnnotation Error ==="); console.error("Error details:", { message: error.message, stack: error.stack, params: JSON.stringify(params, null, 2), }); return { success: false, error: error.message }; } }
- src/talk_to_figma_mcp/server.ts:1007-1047 (registration)MCP server tool registration for 'set_annotation'. Defines input schema using Zod and thin handler that forwards parameters to Figma plugin via sendCommandToFigma websocket command, returning the result or error message.server.tool( "set_annotation", "Create or update an annotation", { nodeId: z.string().describe("The ID of the node to annotate"), annotationId: z.string().optional().describe("The ID of the annotation to update (if updating existing annotation)"), labelMarkdown: z.string().describe("The annotation text in markdown format"), categoryId: z.string().optional().describe("The ID of the annotation category"), properties: z.array(z.object({ type: z.string() })).optional().describe("Additional properties for the annotation") }, async ({ nodeId, annotationId, labelMarkdown, categoryId, properties }) => { try { const result = await sendCommandToFigma("set_annotation", { nodeId, annotationId, labelMarkdown, categoryId, properties }); return { content: [ { type: "text", text: JSON.stringify(result) } ] }; } catch (error) { return { content: [ { type: "text", text: `Error setting annotation: ${error instanceof Error ? error.message : String(error)}` } ] }; } } );
- Input schema (Zod) for 'set_annotation' MCP tool defining parameters: nodeId (required), annotationId/categoryId/properties (optional).nodeId: z.string().describe("The ID of the node to annotate"), annotationId: z.string().optional().describe("The ID of the annotation to update (if updating existing annotation)"), labelMarkdown: z.string().describe("The annotation text in markdown format"), categoryId: z.string().optional().describe("The ID of the annotation category"), properties: z.array(z.object({ type: z.string() })).optional().describe("Additional properties for the annotation")
- src/cursor_mcp_plugin/code.js:163-164 (handler)Dispatch case in Figma plugin's handleCommand that routes 'set_annotation' command to setAnnotation handler function.case "set_annotation": return await setAnnotation(params);