get_figma_image

Instructions

Implementation Reference

• src/index.ts:234-292 (handler)

  The primary handler function for executing the 'get_figma_image' tool. It extracts parameters from args, calls FigmaImageExtractor to get the image, and returns structured JSON response with success/error handling.

  private async handleGetImage(args: any) {
    const { url, format = 'png', scale = 1 } = args;
  
    try {
      console.error(`开始处理图片请求: ${url}`);
      
      const options: ImageExportOptions = { format, scale };
      const results = await this.imageExtractor.getImageFromUrl(url, options);
  
      if (results.length === 0) {
        throw new Error('未找到可导出的图片');
      }
  
      const result = results[0];
      console.error(`图片导出成功: ${result.nodeName} (${result.nodeId})`);
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: true,
              data: {
                imageUrl: result.url,
                nodeId: result.nodeId,
                nodeName: result.nodeName,
                format: result.format,
                scale: result.scale,
              },
            }, 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参数',
                  '确认Figma token是否有效',
                  '验证对该文件是否有访问权限',
                  '检查节点是否存在且可见'
                ],
                urlFormat: 'https://www.figma.com/design/{fileId}/{name}?node-id={nodeId}'
              }
            }, null, 2),
          },
        ],
      };
    }
  }

• src/index.ts:48-74 (registration)

  Registration of the 'get_figma_image' tool in the ListToolsRequestSchema handler, defining name, description, and input schema.

  {
    name: 'get_figma_image',
    description: '根据Figma URL获取节点的图片',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'Figma文件URL，必须包含node-id参数',
        },
        format: {
          type: 'string',
          enum: ['png', 'jpg', 'svg', 'pdf'],
          description: '图片格式，默认为png',
          default: 'png',
        },
        scale: {
          type: 'number',
          description: '图片缩放比例，默认为1',
          default: 1,
          minimum: 0.01,
          maximum: 4,
        },
      },
      required: ['url'],
    },
  },

• src/image-extractor.ts:23-64 (helper)

  Helper method in FigmaImageExtractor that parses the Figma URL, fetches node info, exports the image via FigmaService, and returns ImageResult.

  async getImageFromUrl(
    figmaUrl: string, 
    options: ImageExportOptions = {}
  ): Promise<ImageResult[]> {
    try {
      const urlInfo = this.figmaService.parseUrl(figmaUrl);
      const { fileId, nodeId } = urlInfo;
  
      if (!nodeId) {
        throw new Error('URL中缺少节点ID，无法导出图片。请确保URL包含node-id参数');
      }
  
      // 获取节点信息以获取名称
      const nodeInfo = await this.figmaService.getNode(fileId, nodeId);
      if (!nodeInfo) {
        throw new Error(`未找到节点: ${nodeId}`);
      }
  
      // 导出图片
      const images = await this.figmaService.exportImage(
        fileId, 
        [nodeId], 
        options
      );
  
      const imageUrl = images[nodeId];
      if (!imageUrl) {
        throw new Error(`无法生成节点 ${nodeId} 的图片URL`);
      }
  
      return [{
        url: imageUrl,
        nodeId,
        nodeName: nodeInfo.name,
        format: options.format || 'png',
        scale: options.scale || 1,
      }];
  
    } catch (error) {
      throw new Error(`获取图片失败: ${error instanceof Error ? error.message : '未知错误'}`);
    }
  }

• src/image-extractor.ts:3-7 (schema)

  Type definition for image export options used in the tool parameters and API calls.

  export interface ImageExportOptions {
    format?: 'jpg' | 'png' | 'svg' | 'pdf';
    scale?: number;
    version?: string;
  }

• src/figma-service.ts:238-263 (helper)

  Core helper in FigmaService that handles image export via Figma API, with batching for multiple nodes and error handling.

  async exportImage(fileId: string, nodeIds: string[], options: {
    format?: 'jpg' | 'png' | 'svg' | 'pdf';
    scale?: number;
    version?: string;
  } = {}): Promise<Record<string, string>> {
    try {
      // 分批处理，避免URL过长
      const batchSize = 90; // 保守分批
      const allImages: Record<string, string> = {};
  
      for (let i = 0; i < nodeIds.length; i += batchSize) {
        const batch = nodeIds.slice(i, i + batchSize);
        const batchImages = await this.exportImageBatch(fileId, batch, options);
        Object.assign(allImages, batchImages);
      }
  
      return allImages;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        const status = error.response?.status;
        const message = error.response?.data?.message || error.message;
        throw new Error(`导出图片失败 (${status}): ${message}`);
      }
      throw new Error(`导出图片失败: ${error instanceof Error ? error.message : '未知错误'}`);
    }
  }