🚀 Figma MCP 服务器带分块处理

一个用于与 Figma API 交互的模型上下文协议（MCP）服务器，内置内存高效的分块处理和分页功能，适用于处理大型 Figma 文件，能有效解决大型文件处理时的内存和性能问题。

🚀 快速开始

此 MCP 服务器提供了一个强大的接口来与 Figma API 交互，并带有内置的内存管理功能。它专为处理大型 Figma 文件而设计，通过将操作分解为可管理的块并实施分页（如果需要）来实现高效处理。

✨ 主要特性

• 内存感知处理，带可配置限制
• 大文件数据检索的分块处理
• 所有列表操作的分页支持
• 节点类型过滤
• 进度跟踪
• 可配置的块大小
• 使用游标恢复功能
• 详细的调试日志
• 详细的错误处理

📦 安装指南

方式一：通过 Smithery 平台安装

1. 访问 Smithery。
2. 搜索并选择“Figma MCP 服务器带分块处理”工具包。
3. 根据提示完成安装流程。

方式二：手动安装（适用于高级用户）

1. 克隆此仓库到本地开发环境：

git clone https://github.com/your-username/figma-mcp-chunked.git

2. 安装所有依赖项：

npm install

3. 启动服务器：

node index.js

📚 详细文档

配置说明

使用环境变量配置

通过设置以下环境变量来调整服务器行为：

• MCP_SERVER_PORT：指定服务器运行的端口（默认值为 3000）
• MCP_API_KEY：指定用于与 Figma API 交互的密钥
• MCP_DEBUG_MODE：启用调试模式（可选值为 true 或 false）

使用配置文件

创建一个 config.json 文件，并在其中指定以下参数：

{
  "port": 3000,
  "apiKey": "your-api-key",
  "debugMode": true
}

工具使用指南

MCP 工具集

以下是可用的 MCP 工具及其说明：

基础用法

• get_file_data：获取文件数据
  • 参数要求：
    • fileKey：必须，指定要检索的文件密钥
    • accessToken：必须，用于身份验证的访问令牌
  • 使用示例：

curl -X POST http://localhost:3000/mcp/tool/get_file_data \
  -H "Content-Type: application/json" \
  -d '{"fileKey":"your-file-key","accessToken":"your-access-token"}'

高级用法

• process_blocks：处理数据块
  • 参数要求：
    • blockSize：可选，指定每个块的大小（默认为 100）
    • maxMemoryMB：可选，指定最大内存使用限制（以 MB 为单位，默认为 512）

内存管理策略

分块处理的最佳实践

1. 起始较小的块大小：从每个块处理 50 到 100 个节点开始，并根据性能调整。
2. 监控内存使用情况：通过响应元数据跟踪内存使用情况。
3. 使用节点类型过滤：尽可能减少数据负载。
4. 实施分页：对于大数据集使用分页。
5. 指定较小的深度值：在处理嵌套结构时。

可配置选项

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

调试日志

服务器包含详细的调试日志：

// 调试日志示例
[MCP 调试] 从 config.json 加载配置
[MCP 调试] 找到访问令牌 xxxxxxxx...
[MCP 调试] 请求 { tool: 'get_file_data', arguments: {...} }
[MCP 调试] 响应大小为 2.5 MB

错误处理

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

// 内存限制错误
"响应太大。尝试使用较小的深度值或指定 node_id。"

// 参数错误
"缺少必需参数：fileKey 和 accessToken"

// API 错误
"Figma API 错误：[详细信息]"

故障排除

常见问题

1. 内存错误

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

2. 性能问题

   • 监控内存使用情况
   • 调整块大小
   • 使用适当的节点类型筛选器
   • 实现经常访问数据的缓存

3. API 限制

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

调试模式

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

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

开发与贡献

• 问题报告：在 GitHub Issues 上提交任何遇到的问题或功能请求。
• 代码贡献：欢迎 fork 仓库并提出拉取请求，帮助改进工具。

📄 许可证

项目遵循 MIT License，详细信息请参阅许可证文件。