JinDaGe - Figma Chunked MCP Details

article

README

🚀 Figma MCP 服务器带分块处理

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

🚀 快速开始

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

✨ 主要特性

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

📦 安装指南

方式一：通过 Smithery 平台安装

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

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

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

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

安装所有依赖项：

npm install

启动服务器：

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）

内存管理策略

分块处理的最佳实践

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

可配置选项

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 错误：[详细信息]"

故障排除

常见问题

内存错误
- 减少块大小
- 使用节点类型过滤
- 实施分页
- 指定较小的深度值
性能问题
- 监控内存使用情况
- 调整块大小
- 使用适当的节点类型筛选器
- 实现经常访问数据的缓存
API 限制
- 实现速率限制
- 使用分页
- 在可能的情况下缓存响应

调试模式

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

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

开发与贡献

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

📄 许可证

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

Figma Chunked