Cursor Talk to Figma MCP

Instructions

Implementation Reference

• src/talk_to_figma_mcp/server.ts:1112-1200 (handler)

  Handler function that validates input, sends batched set_multiple_annotations command to Figma plugin, processes results including chunked progress, and returns formatted success/failure summary with details on failed annotations.
  async ({ nodeId, annotations }, extra) => { try { if (!annotations || annotations.length === 0) { return { content: [ { type: "text", text: "No annotations provided", }, ], }; } // Initial response to indicate we're starting the process const initialStatus = { type: "text" as const, text: `Starting annotation process for ${annotations.length} nodes. This will be processed in batches of 5...`, }; // Track overall progress let totalProcessed = 0; const totalToProcess = annotations.length; // Use the plugin's set_multiple_annotations function with chunking const result = await sendCommandToFigma("set_multiple_annotations", { nodeId, annotations, }); // Cast the result to a specific type to work with it safely interface AnnotationResult { success: boolean; nodeId: string; annotationsApplied?: number; annotationsFailed?: number; totalAnnotations?: number; completedInChunks?: number; results?: Array<{ success: boolean; nodeId: string; error?: string; annotationId?: string; }>; } const typedResult = result as AnnotationResult; // Format the results for display const success = typedResult.annotationsApplied && typedResult.annotationsApplied > 0; const progressText = ` Annotation process completed: - ${typedResult.annotationsApplied || 0} of ${totalToProcess} successfully applied - ${typedResult.annotationsFailed || 0} failed - Processed in ${typedResult.completedInChunks || 1} batches `; // Detailed results const detailedResults = typedResult.results || []; const failedResults = detailedResults.filter(item => !item.success); // Create the detailed part of the response let detailedResponse = ""; if (failedResults.length > 0) { detailedResponse = `\n\nNodes that failed:\n${failedResults.map(item => `- ${item.nodeId}: ${item.error || "Unknown error"}` ).join('\n')}`; } return { content: [ initialStatus, { type: "text" as const, text: progressText + detailedResponse, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error setting multiple annotations: ${error instanceof Error ? error.message : String(error) }`, }, ], }; } }
• src/talk_to_figma_mcp/server.ts:1092-1201 (registration)

  MCP tool registration using server.tool(), including name, description, Zod input schema, and handler reference.
  "set_multiple_annotations", "Set multiple annotations parallelly in a node", { nodeId: z .string() .describe("The ID of the node containing the elements to annotate"), annotations: z .array( z.object({ nodeId: z.string().describe("The ID of the node to annotate"), labelMarkdown: z.string().describe("The annotation text in markdown format"), categoryId: z.string().optional().describe("The ID of the annotation category"), annotationId: z.string().optional().describe("The ID of the annotation to update (if updating existing annotation)"), properties: z.array(z.object({ type: z.string() })).optional().describe("Additional properties for the annotation") }) ) .describe("Array of annotations to apply"), }, async ({ nodeId, annotations }, extra) => { try { if (!annotations || annotations.length === 0) { return { content: [ { type: "text", text: "No annotations provided", }, ], }; } // Initial response to indicate we're starting the process const initialStatus = { type: "text" as const, text: `Starting annotation process for ${annotations.length} nodes. This will be processed in batches of 5...`, }; // Track overall progress let totalProcessed = 0; const totalToProcess = annotations.length; // Use the plugin's set_multiple_annotations function with chunking const result = await sendCommandToFigma("set_multiple_annotations", { nodeId, annotations, }); // Cast the result to a specific type to work with it safely interface AnnotationResult { success: boolean; nodeId: string; annotationsApplied?: number; annotationsFailed?: number; totalAnnotations?: number; completedInChunks?: number; results?: Array<{ success: boolean; nodeId: string; error?: string; annotationId?: string; }>; } const typedResult = result as AnnotationResult; // Format the results for display const success = typedResult.annotationsApplied && typedResult.annotationsApplied > 0; const progressText = ` Annotation process completed: - ${typedResult.annotationsApplied || 0} of ${totalToProcess} successfully applied - ${typedResult.annotationsFailed || 0} failed - Processed in ${typedResult.completedInChunks || 1} batches `; // Detailed results const detailedResults = typedResult.results || []; const failedResults = detailedResults.filter(item => !item.success); // Create the detailed part of the response let detailedResponse = ""; if (failedResults.length > 0) { detailedResponse = `\n\nNodes that failed:\n${failedResults.map(item => `- ${item.nodeId}: ${item.error || "Unknown error"}` ).join('\n')}`; } return { content: [ initialStatus, { type: "text" as const, text: progressText + detailedResponse, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error setting multiple annotations: ${error instanceof Error ? error.message : String(error) }`, }, ], }; } } );
• src/talk_to_figma_mcp/server.ts:1095-1111 (schema)

  Zod schema for tool inputs: nodeId (string) and annotations array with nodeId, labelMarkdown (required), and optional categoryId, annotationId, properties.
  nodeId: z .string() .describe("The ID of the node containing the elements to annotate"), annotations: z .array( z.object({ nodeId: z.string().describe("The ID of the node to annotate"), labelMarkdown: z.string().describe("The annotation text in markdown format"), categoryId: z.string().optional().describe("The ID of the annotation category"), annotationId: z.string().optional().describe("The ID of the annotation to update (if updating existing annotation)"), properties: z.array(z.object({ type: z.string() })).optional().describe("Additional properties for the annotation") }) ) .describe("Array of annotations to apply"), },
• src/talk_to_figma_mcp/server.ts:1079-1088 (schema)

  TypeScript interface defining the parameters for set_multiple_annotations command, matching the tool schema.
  interface SetMultipleAnnotationsParams { nodeId: string; annotations: Array<{ nodeId: string; labelMarkdown: string; categoryId?: string; annotationId?: string; properties?: Array<{ type: string }>; }>; }