extract_node_elements

Extract all design elements (images, vectors, components) from Figma nodes to analyze or export assets from your designs.

Instructions

提取节点中的所有设计元素（图片、矢量、组件）

Input Schema

TableJSON Schema

Name	Required	Description	Default
`url`	Yes	Figma文件URL，必须包含node-id参数
`includeDetails`	No	是否包含详细信息，默认为false

Implementation Reference

src/index.ts:168-186 (schema)

Tool schema definition for 'extract_node_elements', including name, description, and input schema.

{
  name: 'extract_node_elements',
  description: '提取节点中的所有设计元素（图片、矢量、组件）',
  inputSchema: {
    type: 'object',
    properties: {
      url: {
        type: 'string',
        description: 'Figma文件URL，必须包含node-id参数',
      },
      includeDetails: {
        type: 'boolean',
        description: '是否包含详细信息，默认为false',
        default: false,
      },
    },
    required: ['url'],
  },
},

src/index.ts:215-216 (registration)
Tool dispatch/registration in the switch statement for CallToolRequest.
```
case 'extract_node_elements':
  return await this.handleExtractNodeElements(args);
```

src/index.ts:486-552 (handler)

Primary handler function for the 'extract_node_elements' tool, which delegates to FigmaElementExtractor and formats the response.

private async handleExtractNodeElements(args: any) {
  const { url, includeDetails = false } = args;

  try {
    console.error(`开始提取节点设计元素: ${url}`);
    
    const elements = await this.elementExtractor.getElementsFromUrl(url);
    
    console.error(`成功提取设计元素: ${elements.totalElements} 个`);
    
    const responseData: any = {
      success: true,
      data: {
        nodeId: elements.nodeId,
        nodeName: elements.nodeName,
        summary: {
          totalElements: elements.totalElements,
          images: elements.images.length,
          vectors: elements.vectors.length,
          components: elements.components.length,
        },
        elements: includeDetails ? {
          images: elements.images,
          vectors: elements.vectors,
          components: elements.components,
        } : undefined,
      },
    };

    // 如果不包含详细信息，提供可读的摘要
    if (!includeDetails) {
      responseData.data.textSummary = this.elementExtractor.generateElementsSummary(elements);
    }
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(responseData, null, 2),
        },
      ],
    };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : '未知错误';
    console.error(`提取设计元素失败: ${errorMessage}`);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: false,
            error: errorMessage,
            troubleshooting: {
              commonIssues: [
                '检查Figma URL是否包含node-id参数',
                '确认对该文件和节点有访问权限',
                '验证节点是否存在且包含设计元素',
              ],
              tip: '使用includeDetails=true获取详细的元素信息'
            }
          }, null, 2),
        },
      ],
    };
  }
}

src/element-extractor.ts:155-168 (handler)

Handler method in FigmaElementExtractor that parses the Figma URL and invokes the core element extraction logic.

async getElementsFromUrl(figmaUrl: string): Promise<NodeElements> {
  try {
    const urlInfo = this.figmaService.parseUrl(figmaUrl);
    const { fileId, nodeId } = urlInfo;

    if (!nodeId) {
      throw new Error('URL中缺少节点ID，无法提取设计元素。请确保URL包含node-id参数');
    }

    return await this.getAllNodeElements(fileId, nodeId);
  } catch (error) {
    throw new Error(`从URL获取设计元素失败: ${error instanceof Error ? error.message : '未知错误'}`);
  }
}

src/element-extractor.ts:114-150 (helper)

Core helper function that extracts images, vectors, and components from a Figma node using parallel calls and tree traversal.

async getAllNodeElements(fileId: string, nodeId: string): Promise<NodeElements> {
  try {
    const node = await this.figmaService.getNodeDetails(fileId, nodeId);
    if (!node) {
      throw new Error(`节点 ${nodeId} 不存在`);
    }

    const [images, vectors] = await Promise.all([
      this.getNodeImages(fileId, nodeId),
      this.extractVectorElements(fileId, nodeId)
    ]);

    // 收集组件节点
    const components: any[] = [];
    this.figmaService.traverseNodeTree(node, (currentNode) => {
      if (currentNode.type === 'COMPONENT' || currentNode.type === 'INSTANCE') {
        components.push({
          id: currentNode.id,
          name: currentNode.name,
          type: currentNode.type,
          componentId: currentNode.componentId || undefined
        });
      }
    });

    return {
      nodeId,
      nodeName: node.name || 'Unnamed Node',
      images,
      vectors,
      components,
      totalElements: images.length + vectors.length + components.length
    };
  } catch (error) {
    throw new Error(`获取节点元素失败: ${error instanceof Error ? error.message : '未知错误'}`);
  }
}

Figma MCP Tool