extract_node_elements

Instructions

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 : '未知错误'}`);
    }
  }