Figma MCP Server with Chunking

Instructions

Implementation Reference

• src/client.ts:384-731 (handler)

  Core handler implementation for fetching specific Figma file nodes. Handles API calls, single/multiple node logic, child pagination (cursor/pageSize for single nodes), depth traversal, node type filtering, property exclusion, and summarization to manage response size.

  async getFileNodes(fileKey: string, ids: string[], options: {
    pageSize?: number;
    maxResponseSize?: number;
    cursor?: string;
    depth?: number;
    nodeTypes?: string[];
    excludeProps?: string[];
    summarizeNodes?: boolean;
  } = {}) {
    try {
      // Input validation
      if (!fileKey || typeof fileKey !== 'string' || fileKey.trim() === '') {
        throw new Error('fileKey must be a non-empty string');
      }
      if (!ids || !Array.isArray(ids) || ids.length === 0) {
        throw new Error('ids must be a non-empty array');
      }
      
      // Basic ID validation - Figma API will handle the rest
      for (const id of ids) {
        if (!id || typeof id !== 'string') {
          throw new Error('All node IDs must be non-empty strings');
        }
      }
      
      if (process.env.MCP_DEBUG) {
        console.debug('[MCP Debug] Getting nodes for file:', fileKey, 'Options:', options);
      }
      
      const {
        pageSize = 50,
        maxResponseSize = 50,
        cursor,
        depth = 2,
        nodeTypes,
        excludeProps,
        summarizeNodes = false
      } = options;
      
      // Validate options
      if (pageSize !== undefined) {
        if (typeof pageSize !== 'number' || pageSize < 1 || pageSize > 1000) {
          throw new Error('pageSize must be between 1 and 1000');
        }
      }
      
      if (depth !== undefined) {
        if (typeof depth !== 'number' || depth < 0 || depth > 10) {
          throw new Error('depth must be between 0 and 10');
        }
      }
      
      if (maxResponseSize !== undefined) {
        if (typeof maxResponseSize !== 'number' || maxResponseSize < 1 || maxResponseSize > 100) {
          throw new Error('maxResponseSize must be between 1 and 100 MB');
        }
      }
      
      if (excludeProps && excludeProps.length > 0) {
        const criticalProps = ['id', 'type', 'name'];
        for (const prop of excludeProps) {
          if (criticalProps.includes(prop)) {
            throw new Error(`Cannot exclude critical property: ${prop}`);
          }
        }
      }
      
  
      // For single node requests, implement child pagination
      if (ids.length === 1) {
        const nodeId = ids[0];
        
        // Step 1: Fetch the parent node with depth=1 to get immediate children list
        // We always fetch parent with depth=1 first for pagination to work
        let shallowResponse;
        try {
          shallowResponse = await this.client.get(`/files/${fileKey}/nodes`, {
            params: { 
              ids: nodeId,
              depth: 1 // Shallow fetch to get list of immediate children IDs
            }
          });
        } catch (error: any) {
          if (error.response?.status === 413 || error.response?.status === 504) {
            throw new Error(
              `Node is too large to fetch all at once. ` +
              `Try these parameters to paginate through its children:\n` +
              `- pageSize: 10 (fetch 10 children at a time)\n` +
              `- cursor: "0" (start from first child)\n` +
              `- depth: 1 (immediate children only)\n` +
              `- summarizeNodes: true (minimal data)\n` +
              `- excludeProps: ["fills", "effects", "strokes"] (remove heavy properties)`
            );
          }
          throw error;
        }
        
        if (!shallowResponse.data || !shallowResponse.data.nodes) {
          throw new Error('Invalid response from Figma API');
        }
        
        let mainNode = shallowResponse.data.nodes[nodeId];
        if (!mainNode) {
          throw new Error('Requested node not found');
        }
        
        // Handle Figma's document wrapper - sometimes nodes come wrapped in a 'document' object
        // Clone to avoid mutations
        const actualNode = { ...(mainNode.document || mainNode) };
        
        // Step 2: Extract children IDs (safely)
        const allChildIds: string[] = [];
        if (actualNode.children) {
          if (!Array.isArray(actualNode.children)) {
            console.warn('[MCP Warning] Node children property is not an array');
          } else {
            for (const child of actualNode.children) {
              if (child && typeof child === 'object' && child.id && typeof child.id === 'string') {
                allChildIds.push(child.id);
              }
            }
          }
        }
        
        if (process.env.MCP_DEBUG) {
          console.debug(`[MCP Debug] Found ${allChildIds.length} children`);
        }
        
        // Step 3: Paginate through children
        const startIndex = cursor ? parseInt(cursor, 10) : 0;
        if (isNaN(startIndex) || startIndex < 0) {
          throw new Error(`Invalid cursor value: ${cursor}. Must be a non-negative number.`);
        }
        if (startIndex >= allChildIds.length) {
          // Cursor is beyond the last child - return empty result with hasMore=false
          return {
            nodes: { [nodeId]: actualNode },
            pagination: {
              totalChildren: allChildIds.length,
              fetchedChildren: 0,
              nextCursor: undefined,
              hasMore: false,
              message: allChildIds.length === 0 
                ? 'Node has no children' 
                : `Cursor beyond range (max: ${allChildIds.length - 1})`
            }
          };
        }
        const safePageSize = pageSize; // Already validated above
        const endIndex = Math.min(startIndex + safePageSize, allChildIds.length);
        const childIdsToFetch = allChildIds.slice(startIndex, endIndex);
        
        let childrenData: any = {};
        
        // Step 4: Fetch the selected page of children (if any)
        if (childIdsToFetch.length > 0) {
          const childParams: any = { 
            ids: childIdsToFetch.join(',')
          };
          // Apply depth to children fetch (depth applies to how deep we fetch each child)
          // depth=1 means fetch children with their immediate children
          // depth=2 means fetch children with 2 levels of descendants, etc.
          if (typeof depth === 'number' && depth >= 0) {
            childParams.depth = depth;
          }
          
          let childResponse;
          try {
            childResponse = await this.client.get(`/files/${fileKey}/nodes`, {
              params: childParams,
              timeout: 30000 // 30 second timeout
            });
          } catch (childError: any) {
            console.error('[MCP Error] Failed to fetch children:', childError.message);
            // Return partial result with parent only
            return {
              nodes: { [nodeId]: actualNode },
              pagination: {
                totalChildren: allChildIds.length,
                fetchedChildren: 0,
                nextCursor: startIndex.toString(),
                hasMore: true,
                error: 'Failed to fetch children, returning parent only'
              }
            };
          }
          
          if (!childResponse.data || !childResponse.data.nodes) {
            console.warn('[MCP Warning] Invalid response for child nodes, using empty object');
            childrenData = {};
          } else {
            childrenData = childResponse.data.nodes;
          }
          
          // Handle document wrapper for children too
          for (const [childId, childNode] of Object.entries(childrenData)) {
            if ((childNode as any).document) {
              childrenData[childId] = (childNode as any).document;
            }
          }
        }
        
        // Step 5: Combine parent and children nodes
        // Note: We don't modify the parent's children array - it shows all children IDs
        // The fetched children are separate entries in the nodes object
        let processedData: any = {
          [nodeId]: actualNode, // Parent node (already has full children array from depth=1 fetch)
          ...childrenData       // Fetched children (based on pagination)
        };
        
        // Filter by node types if specified
        // Note: Parent node is always kept regardless of its type (for context)
        if (nodeTypes && nodeTypes.length > 0) {
          const filteredData: any = {
            [nodeId]: processedData[nodeId] // Always keep parent for context
          };
          for (const [id, node] of Object.entries(processedData)) {
            if (id !== nodeId) {
              const nodeType = (node as any).type;
              if (nodeType && nodeTypes.includes(nodeType)) {
                filteredData[id] = node;
              }
            }
          }
          processedData = filteredData;
        }
        
        // Exclude properties if specified
        if (excludeProps && excludeProps.length > 0) {
          const cleanedData: any = {};
          for (const [id, node] of Object.entries(processedData)) {
            cleanedData[id] = this.nodeProcessor.filterNodeProperties(node as SceneNode, excludeProps);
          }
          processedData = cleanedData;
        }
        
        // Apply summarization if requested
        if (summarizeNodes) {
          const summarizedData: any = {};
          for (const [id, node] of Object.entries(processedData)) {
            summarizedData[id] = this.nodeProcessor.summarizeNode(node as SceneNode);
          }
          processedData = summarizedData;
        }
        
        // Check response size (with safety for large objects)
        let responseSize = 0;
        try {
          responseSize = JSON.stringify(processedData).length / (1024 * 1024); // in MB
          if (responseSize > maxResponseSize) {
            console.warn(`[MCP Warning] Response size ${responseSize.toFixed(2)}MB exceeds max ${maxResponseSize}MB`);
          }
        } catch (e) {
          console.warn('[MCP Warning] Response too large to calculate size');
        }
        
        return {
          nodes: processedData,
          pagination: {
            totalChildren: allChildIds.length,
            fetchedChildren: childIdsToFetch.length,
            nextCursor: endIndex < allChildIds.length ? endIndex.toString() : undefined,
            hasMore: endIndex < allChildIds.length
          }
        };
      }
      
      // For multiple nodes, fetch them all at once (no child pagination)
      
      // Warn if pagination parameters are provided with multiple nodes
      if (cursor || (pageSize && pageSize !== 50)) {
        console.warn(
          '[MCP Warning] Pagination parameters (pageSize, cursor) are ignored when fetching multiple nodes. ' +
          'Pagination only works when fetching a single node (to paginate through its children).'
        );
      }
      
      const params: any = { ids: ids.join(',') };
      if (typeof depth === 'number') params.depth = depth;
      
      const response = await this.client.get(`/files/${fileKey}/nodes`, {
        params,
        timeout: 30000 // 30 second timeout
      });
      
      if (!response.data || !response.data.nodes) {
        throw new Error('Invalid response from Figma API');
      }
      
      let nodeData = response.data.nodes;
      
      // Handle document wrapper for multiple nodes
      for (const [id, node] of Object.entries(nodeData)) {
        if ((node as any).document) {
          nodeData[id] = (node as any).document;
        }
      }
      
      // Apply filters and transformations
      if (nodeTypes && nodeTypes.length > 0) {
        const filteredNodes: any = {};
        for (const [id, node] of Object.entries(nodeData)) {
          const nodeType = (node as any).type;
          if (nodeType && nodeTypes.includes(nodeType)) {
            filteredNodes[id] = node;
          }
        }
        nodeData = filteredNodes;
      }
      
      if (excludeProps && excludeProps.length > 0) {
        const processedNodes: any = {};
        for (const [id, node] of Object.entries(nodeData)) {
          processedNodes[id] = this.nodeProcessor.filterNodeProperties(node as SceneNode, excludeProps);
        }
        nodeData = processedNodes;
      }
      
      if (summarizeNodes) {
        const summarizedNodes: any = {};
        for (const [id, node] of Object.entries(nodeData)) {
          summarizedNodes[id] = this.nodeProcessor.summarizeNode(node as SceneNode);
        }
        nodeData = summarizedNodes;
      }
      
      // Return with clear indication that pagination doesn't apply
      const result: any = {
        nodes: nodeData
      };
      
      // Only include pagination info if user tried to use pagination params
      if (cursor || (pageSize && pageSize !== 50)) {
        result.pagination = {
          warning: 'Pagination parameters were ignored. Pagination only works when fetching a single node.',
          explanation: 'To paginate: fetch one node at a time, use pageSize and cursor to navigate through its children.'
        };
      }
      
      return result;
    } catch (error: any) {
      // Sanitize error messages
      const message = error.message || 'Unknown error';
      const sanitized = message.substring(0, 500); // Limit error message length
      console.error('[MCP Error] Failed to get file nodes:', sanitized);
      throw new Error(`Failed to get nodes: ${sanitized}`);
    }
  }

• src/index.ts:220-290 (registration)

  Tool registration in ListToolsRequestSchema handler, including name, description, and detailed inputSchema defining parameters like file_key, ids, pageSize, cursor, depth, etc.

  {
    name: 'get_file_nodes',
    description: 'Get specific nodes from a Figma file. IMPORTANT: Pagination (pageSize/cursor) ONLY works when fetching a SINGLE node - it paginates through that node\'s children. When fetching multiple nodes, pagination parameters are ignored. For large nodes use: pageSize: 10-25, summarizeNodes: true, depth: 1.',
    inputSchema: {
      type: 'object',
      properties: {
        file_key: {
          type: 'string',
          description: 'Figma file key'
        },
        ids: {
          type: 'array',
          items: {
            type: 'string'
          },
          description: 'Array of node IDs to retrieve'
        },
        pageSize: {
          type: 'number',
          description: '[SINGLE NODE ONLY] Number of child nodes to fetch per page. Ignored when fetching multiple nodes.',
          minimum: 1,
          maximum: 1000
        },
        maxResponseSize: {
          type: 'number',
          description: 'Maximum response size in MB (defaults to 50)',
          minimum: 1,
          maximum: 100
        },
        cursor: {
          type: 'string',
          description: '[SINGLE NODE ONLY] Pagination cursor - child index to start from (e.g., "0", "50", "100"). Ignored when fetching multiple nodes.'
        },
        depth: {
          type: 'number',
          description: 'Maximum depth to traverse in the node tree',
          minimum: 1
        },
        nodeTypes: {
          type: 'array',
          items: {
            type: 'string',
            enum: [
              'FRAME',
              'GROUP',
              'VECTOR',
              'BOOLEAN_OPERATION',
              'STAR',
              'LINE',
              'TEXT',
              'COMPONENT',
              'INSTANCE'
            ]
          },
          description: 'Filter nodes by type. For single nodes: filters children only (parent always kept). For multiple nodes: filters all requested nodes.'
        },
        excludeProps: {
          type: 'array',
          items: {
            type: 'string'
          },
          description: 'Properties to exclude from node data'
        },
        summarizeNodes: {
          type: 'boolean',
          description: 'Return only essential node properties to reduce response size'
        }
      },
      required: ['file_key', 'ids']
    }
  }

• src/index.ts:412-488 (handler)

  MCP CallToolRequestSchema handler case for 'get_file_nodes'. Validates arguments, calls figmaClient.getFileNodes, checks response size with helpful error if too large, and formats response.

  case 'get_file_nodes': {
    const args = request.params.arguments as unknown as FileNodesArgs & { 
      pageSize?: number;
      maxResponseSize?: number;
      cursor?: string;
      depth?: number;
      nodeTypes?: string[];
      excludeProps?: string[];
      summarizeNodes?: boolean;
    };
    if (!args.file_key) {
      throw new McpError(ErrorCode.InvalidParams, 'file_key is required');
    }
    if (!args.ids || !Array.isArray(args.ids) || args.ids.length === 0) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'ids array is required and must not be empty'
      );
    }
    console.debug('[MCP Debug] Fetching file nodes', args);
    const data = await this.figmaClient.getFileNodes(
      args.file_key, 
      args.ids, 
      {
        pageSize: args.pageSize,
        maxResponseSize: args.maxResponseSize,
        cursor: args.cursor,
        depth: args.depth,
        nodeTypes: args.nodeTypes,
        excludeProps: args.excludeProps,
        summarizeNodes: args.summarizeNodes
      }
    );
    
    // Check response size and provide helpful error if too large
    const jsonString = JSON.stringify(data, null, 2);
    const sizeInBytes = new TextEncoder().encode(jsonString).length;
    const estimatedTokens = Math.ceil(sizeInBytes / 4); // ~4 bytes per token
    
    if (estimatedTokens > 25000) {
      const helpfulError = {
        error: 'Response too large',
        estimatedTokens,
        maxTokens: 25000,
        currentParams: {
          pageSize: args.pageSize || 50,
          depth: args.depth || 'full',
          summarizeNodes: args.summarizeNodes || false
        },
        solutions: [
          '1. Use summarizeNodes: true to strip nodes to essentials',
          '2. Reduce pageSize to 10-25 (fetches fewer children per request)',
          '3. Set depth: 1 to fetch only immediate children',
          '4. Add excludeProps: ["fills", "effects", "strokes", "exportSettings"]',
          '5. Use cursor to paginate through children (cursor: "0" for first batch, "10" for second, etc.)'
        ],
        exampleCall: {
          file_key: args.file_key,
          ids: args.ids,
          pageSize: 10,
          depth: 1,
          summarizeNodes: true,
          excludeProps: ["fills", "effects", "strokes"],
          cursor: "0"
        },
        nodeInfo: data.pagination || { note: 'Multiple nodes requested - try fetching one at a time' }
      };
      
      return {
        content: [{ type: 'text', text: JSON.stringify(helpfulError, null, 2) }],
      };
    }
    
    return {
      content: [{ type: 'text', text: jsonString }],
    };
  }

• src/index.ts:223-289 (schema)

  Input schema/JSON Schema for the get_file_nodes tool, defining all parameters, types, descriptions, constraints, and required fields.

  inputSchema: {
    type: 'object',
    properties: {
      file_key: {
        type: 'string',
        description: 'Figma file key'
      },
      ids: {
        type: 'array',
        items: {
          type: 'string'
        },
        description: 'Array of node IDs to retrieve'
      },
      pageSize: {
        type: 'number',
        description: '[SINGLE NODE ONLY] Number of child nodes to fetch per page. Ignored when fetching multiple nodes.',
        minimum: 1,
        maximum: 1000
      },
      maxResponseSize: {
        type: 'number',
        description: 'Maximum response size in MB (defaults to 50)',
        minimum: 1,
        maximum: 100
      },
      cursor: {
        type: 'string',
        description: '[SINGLE NODE ONLY] Pagination cursor - child index to start from (e.g., "0", "50", "100"). Ignored when fetching multiple nodes.'
      },
      depth: {
        type: 'number',
        description: 'Maximum depth to traverse in the node tree',
        minimum: 1
      },
      nodeTypes: {
        type: 'array',
        items: {
          type: 'string',
          enum: [
            'FRAME',
            'GROUP',
            'VECTOR',
            'BOOLEAN_OPERATION',
            'STAR',
            'LINE',
            'TEXT',
            'COMPONENT',
            'INSTANCE'
          ]
        },
        description: 'Filter nodes by type. For single nodes: filters children only (parent always kept). For multiple nodes: filters all requested nodes.'
      },
      excludeProps: {
        type: 'array',
        items: {
          type: 'string'
        },
        description: 'Properties to exclude from node data'
      },
      summarizeNodes: {
        type: 'boolean',
        description: 'Return only essential node properties to reduce response size'
      }
    },
    required: ['file_key', 'ids']
  }