Figma MCP 服务器（支持分块处理）

这是一个与 Figma API 交互的 Model Context Protocol (MCP) 服务器，具有内存高效的分块和分页功能，可以处理大型 Figma 文件。

概述

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

主要功能

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

安装

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的 Figma MCP 服务器（支持分块处理）：

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

手动安装

# Clone the repository
git clone [repository-url]
cd figma-mcp-chunked

# Install dependencies
npm install

# Build the project
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,          // Optional: nodes per chunk
    "maxMemoryMB": 512,       // Optional: memory limit
    "nodeTypes": ["FRAME", "COMPONENT"],  // Optional: filter by type
    "cursor": "next-page-token",  // Optional: resume from last position
    "depth": 2                // Optional: traversal depth
  }
}

响应：

{
  "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,               // Optional: traversal depth
    "node_id": "specific-node-id"  // Optional: start from specific node
  }
}

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: 控制嵌套结构的遍历深度

调试日志

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

// Debug log examples
[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

错误处理

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

// Memory limit error
"Response size too large. Try using a smaller depth value or specifying a node_id."

// Invalid parameters
"Missing required parameters: fileKey and accessToken"

// API errors
"Figma API error: [detailed message]"

故障排除

常见问题

1. 内存错误

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

2. 性能问题

   • 监控内存使用情况
   • 调整块大小
   • 使用适当的节点类型过滤器
   • 对频繁访问的数据实现缓存

3. API 限制

   • 实现速率限制
   • 使用分页
   • 在可能的情况下缓存响应

调试模式

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

# Set debug environment variable
export DEBUG=true

贡献

欢迎贡献！请阅读我们的贡献指南并向我们的仓库提交拉取请求。

许可证

本项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。