Figma MCP Tool

Instructions

Implementation Reference

• src/index.ts:377-427 (handler)

  MCP tool handler for 'get_node_images': parses input URL, delegates to elementExtractor.getNodeImages, handles response and errors.

  private async handleGetNodeImages(args: any) {
    const { url } = args;
  
    try {
      console.error(`开始获取节点图片资源: ${url}`);
      
      const images = await this.elementExtractor.getNodeImages(
        this.figmaService.parseUrl(url).fileId,
        this.figmaService.parseUrl(url).nodeId!
      );
  
      console.error(`成功获取 ${images.length} 个图片资源`);
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: true,
              data: {
                images,
                totalCount: images.length,
              },
            }, 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参数',
                  '确认节点中是否包含图片资源',
                  '验证对该文件是否有访问权限',
                ],
                urlFormat: 'https://www.figma.com/design/{fileId}/{name}?node-id={nodeId}'
              }
            }, null, 2),
          },
        ],
      };
    }

• src/element-extractor.ts:9-61 (helper)

  Core logic for extracting image resources from a Figma node: traverses node tree, collects IMAGE fills, fetches URLs, deduplicates.

  async getNodeImages(fileId: string, nodeId: string): Promise<ImageResource[]> {
    try {
      const node = await this.figmaService.getNodeDetails(fileId, nodeId);
      if (!node) {
        throw new Error(`节点 ${nodeId} 不存在`);
      }
  
      const images: ImageResource[] = [];
      
      // 递归收集所有包含图片的节点
      this.figmaService.traverseNodeTree(node, (currentNode) => {
        // 检查填充中的图片
        if (currentNode.fills) {
          for (const fill of currentNode.fills) {
            if (fill.type === 'IMAGE' && fill.imageRef) {
              images.push({
                id: fill.imageRef,
                name: currentNode.name || `Image in ${currentNode.id}`,
                type: 'EMBEDDED',
                size: currentNode.absoluteBoundingBox ? {
                  width: currentNode.absoluteBoundingBox.width,
                  height: currentNode.absoluteBoundingBox.height
                } : undefined
              });
            }
          }
        }
  
        // 检查节点类型是否为图片
        if (currentNode.type === 'RECTANGLE' && currentNode.fills?.some(f => f.type === 'IMAGE')) {
          // 已在上面处理
        }
      });
  
      // 获取图片的实际URL
      if (images.length > 0) {
        try {
          const imageRefs = await this.figmaService.getFileImageReferences(fileId);
          for (const image of images) {
            if (imageRefs[image.id]) {
              image.url = imageRefs[image.id];
            }
          }
        } catch (error) {
          console.error('获取图片URL失败:', error);
        }
      }
  
      return this.deduplicateImages(images);
    } catch (error) {
      throw new Error(`获取节点图片失败: ${error instanceof Error ? error.message : '未知错误'}`);
    }
  }

• src/index.ts:140-153 (registration)

  Tool registration in ListToolsResponse: name, description, and input schema.

  {
    name: 'get_node_images',
    description: '获取节点中的所有图片资源',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'Figma文件URL，必须包含node-id参数',
        },
      },
      required: ['url'],
    },
  },

• src/index.ts:209-210 (handler)

  Switch case routing tool calls to the specific handler.

  case 'get_node_images':
    return await this.handleGetNodeImages(args);