Figma MCP 服务器与分块

一个用于与 Figma API 交互的模型上下文协议 (MCP) 服务器，具有内存高效的分块和分页功能，用于处理大型 Figma 文件。

概述

此 MCP 服务器提供了一个强大的 Figma API 接口，具有内置的内存管理功能。它旨在通过将操作分解为可管理的分块并在必要时实施分页来高效处理大型 Figma 文件。

主要特性

• 具有可配置限制的内存感知处理
• 用于大型文件的分块数据检索
• 对所有列表操作的分页支持
• 节点类型过滤
• 进度跟踪
• 可配置的分块大小
• 中断操作的恢复能力
• 调试日志
• 配置文件支持

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装带有分块的 Figma MCP 服务器：

npx -y @smithery/cli install @ArchimedesCrypto/figma-mcp-chunked --client claude

手动安装

# 克隆仓库
git clone [repository-url]
cd figma-mcp-chunked

# 安装依赖
npm install

# 构建项目
npm run build

配置

环境变量

• FIGMA_ACCESS_TOKEN: 您的 Figma API 访问令牌

配置文件

您可以使用 --config 标志通过 JSON 文件提供配置：

{
  "mcpServers": {
    "figma": {
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

用法:

node build/index.js --config=path/to/config.json

工具

get_file_data (新增)

检索具有内存高效分块和分页的 Figma 文件数据。

{
  "name": "get_file_data",
  "arguments": {
    "fileKey": "your-file-key",
    "accessToken": "your-access-token",
    "pageSize": 100,          // 可选：每个分块的节点数
    "maxMemoryMB": 512,       // 可选：内存限制
    "nodeTypes": ["FRAME", "COMPONENT"],  // 可选：按类型过滤
    "cursor": "next-page-token",  // 可选：从上次位置恢复
    "depth": 2                // 可选：遍历深度
  }
}

响应:

{
  "nodes": [...],
  "memoryUsage": 256.5,
  "nextCursor": "next-page-token",
  "hasMore": true
}

list_files

列出具有分页支持的文件。

{
  "name": "list_files",
  "arguments": {
    "project_id": "optional-project-id",
    "team_id": "optional-team-id"
  }
}

get_file_versions

以分块形式检索版本历史记录。

{
  "name": "get_file_versions",
  "arguments": {
    "file_key": "your-file-key"
  }
}

get_file_comments

检索带有分页的评论。

{
  "name": "get_file_comments",
  "arguments": {
    "file_key": "your-file-key"
  }
}

get_file_info

检索具有分块节点遍历的文件信息。

{
  "name": "get_file_info",
  "arguments": {
    "file_key": "your-file-key",
    "depth": 2,               // 可选：遍历深度
    "node_id": "specific-node-id"  // 可选：从特定节点开始
  }
}

get_components

检索具有分块支持的组件。

{
  "name": "get_components",
  "arguments": {
    "file_key": "your-file-key"
  }
}

get_styles

检索具有分块支持的样式。

{
  "name": "get_styles",
  "arguments": {
    "file_key": "your-file-key"
  }
}

get_file_nodes

检索具有分块支持的特定节点。

{
  "name": "get_file_nodes",
  "arguments": {
    "file_key": "your-file-key",
    "ids": ["node-id-1", "node-id-2"]
  }
}

内存管理

服务器实施了多种策略来有效地管理内存：

分块策略

• 通过 pageSize 可配置的分块大小
• 内存使用监控
• 基于内存压力的自动分块大小调整
• 每个分块的进度跟踪
• 使用游标的恢复能力

最佳实践

1. 从较小的分块大小（50-100 个节点）开始，并根据性能进行调整
2. 通过响应元数据监控内存使用情况
3. 尽可能使用节点类型过滤来减少数据负载
4. 为大型数据集实施分页
5. 对非常大的文件使用恢复能力

配置选项

• pageSize: 每个分块的节点数（默认值：100）
• maxMemoryMB: 最大内存使用量，以 MB 为单位（默认值：512）
• nodeTypes: 过滤特定节点类型
• depth: 控制嵌套结构的遍历深度

调试日志

服务器包含全面的调试日志：

// 调试日志示例
[MCP Debug] Loading config from config.json
[MCP Debug] Access token found xxxxxxxx...
[MCP Debug] Request { tool: 'get_file_data', arguments: {...} }
[MCP Debug] Response size 2.5 MB

错误处理

服务器提供详细的错误消息和建议：

// 内存限制错误
"Response size too large. Try using a smaller depth value or specifying a node_id."

// 无效参数
"Missing required parameters: fileKey and accessToken"

// API 错误
"Figma API error: [detailed message]"

故障排除

常见问题

1. 内存错误

   • 减少分块大小
   • 使用节点类型过滤
   • 实施分页
   • 指定较小的深度值

2. 性能问题

   • 监控内存使用情况
   • 调整分块大小
   • 使用适当的节点类型过滤器
   • 为经常访问的数据实施缓存

3. API 限制

   • 实施速率限制
   • 使用分页
   • 尽可能缓存响应

调试模式

启用调试日志以获取详细信息：

# 设置调试环境变量
export DEBUG=true

贡献

欢迎贡献！请阅读我们的贡献指南并将拉取请求提交到我们的存储库。

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。