Talk to Figma MCP

Instructions

Implementation Reference

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

  Registration and handler implementation of the MCP tool 'set_multiple_annotations'. The handler validates input using Zod schema, processes annotations in batches via the Figma plugin using sendCommandToFigma, and provides progress feedback.

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

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

  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-1200 (schema)

  Zod schema for input validation of the MCP tool 'set_multiple_annotations'.

    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 core handler function that executes the tool logic by forwarding the annotations to the Figma plugin via WebSocket (sendCommandToFigma), handles batch processing feedback, and formats the response with success metrics.

  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)
              }`,
          },
        ],
      };
    }
  }