Cursor Talk to Figma MCP

Instructions

Implementation Reference

• src/talk_to_figma_mcp/server.ts:1091-1201 (registration)

  Registration of the 'set_multiple_annotations' tool using server.tool(), including schema and handler function.

  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:1112-1200 (handler)

  The async handler function that executes the tool logic: validates input, sends batched command to Figma WebSocket server, processes results showing success/failure counts and details.

  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:1079-1088 (schema)

  TypeScript interface defining the parameters for set_multiple_annotations command sent to Figma.

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

• src/talk_to_figma_mcp/server.ts:1095-1111 (schema)

  Zod schema for input validation in the MCP tool definition.

    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"),
  },