Cursor Talk to Figma MCP

Instructions

Implementation Reference

• src/talk_to_figma_mcp/server.ts:1061-1171 (registration)

  MCP tool registration, input schema, and handler implementation for 'set_multiple_annotations'. The handler proxies to Figma plugin command, handles progress, and formats results.

  server.tool(
    "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:1049-1058 (schema)

  TypeScript interface defining parameters for set_multiple_annotations, matching the Zod schema.

  interface SetMultipleAnnotationsParams {
    nodeId: string;
    annotations: Array<{
      nodeId: string;
      labelMarkdown: string;
      categoryId?: string;
      annotationId?: string;
      properties?: Array<{ type: string }>;
    }>;
  }