内容
# 🧩 Figma 本地 MCP
🔍 **基于本地的MCP和C#工具包，用于Figma `.fig` 文件。**
Figma本地MCP直接在您的机器上打开导出的 `.fig` 文件，解码嵌入的Kiwi场景图，构建快速的节点树，并通过紧凑的本地MCP服务器公开它。它还包括一个C#库、命令行界面和简单的调试Web查看器。
> ⚠️ `.fig` 不是Figma官方公开的文件格式。该项目是尽力而为的本地只读逆向工程。
## ✨ 功能
- 📦 读取 `.fig` ZIP容器：`canvas.fig`、`meta.json`、`thumbnail.png`、`images/*`
- 🥝 解码嵌入的Kiwi模式和数据块
- 🌳 从 `nodeChanges` 构建场景树
- ⚡ 将节点存储在 `id -> node` 索引中以实现O(1)查找
- 🧰 提供用于快速检查的命令行界面
- 🖥️ 提供简单的jsTree调试Web查看器
- 🤖 提供用于代理工作流的紧凑MCP服务器
- 🔒 按设计只读：无写入，无变异，无Figma API身份验证
## 🧱 仓库布局
```text
src/Figma.Fig 核心只读解析器库
src/Figma.Fig.Cli 命令行界面检查器
src/Figma.Fig.Web 简单的调试Web查看器
src/Figma.Fig.Mcp 标准输入输出MCP服务器
```
## 📋 要求
- .NET SDK 8+
- Linux/macOS/Windows 且 `dotnet` 在 `PATH` 中
- `libz` 在运行时可用于原始压缩块
在此Linux工作区中，`libz` 已作为 `libz.so` 提供。
## 📥 安装依赖项
恢复NuGet包：
```bash
dotnet restore
```
构建所有内容：
```bash
dotnet build
```
项目使用的主要NuGet依赖项：
- `ZstdSharp.Port` 用于Zstandard块解码
- `ModelContextProtocol` 用于MCP标准输入输出服务器
- `Microsoft.Extensions.Hosting` 用于MCP主机设置
## 🚀 快速入门
### C# 库
```csharp
using Figma.Fig;
var fig = await FigFileReader.ReadAsync("/path/to/design.fig");
Console.WriteLine(fig.Metadata.FileName);
Console.WriteLine(fig.Canvas.Version);
Console.WriteLine(fig.Document.Nodes.Count);
var node = fig.Document.GetNode("3:5123");
Console.WriteLine($"{node?.Type} {node?.Name}");
```
### 命令行界面
检查文件摘要：
```bash
dotnet run --project src/Figma.Fig.Cli -- inspect /path/to/design.fig
```
打印树：
```bash
dotnet run --project src/Figma.Fig.Cli -- tree /path/to/design.fig --max-depth 3 --max-children 20
```
### Web 调试查看器
```bash
dotnet run --project src/Figma.Fig.Web
```
打开打印的本地URL。查看器故意很简单：
- 上传 `.fig`
- 使用jsTree浏览树
- 搜索可见的加载树
- 点击节点检查JSON
## 🤖 MCP 服务器
运行标准输入输出MCP服务器：
```bash
dotnet run --project src/Figma.Fig.Mcp
```
### MCP 配置
示例 `.mcp.json`：
```json
{
"mcpServers": {
"figlocal": {
"command": "dotnet",
"args": [
"run",
"--project",
"/home/user/Projects/figma/src/Figma.Fig.Mcp"
]
}
}
}
```
本地MCP配置文件被故意忽略。在您自己的MCP客户端设置中添加上述配置。
### MCP 工作流
1. 启动支持MCP的客户端。
2. 加载文件：
```text
load(path: "/absolute/path/to/file.fig")
```
3. 检查结构：
```text
types(doc: "example")
tree(doc: "example", depth: 3, children: 50)
search(doc: "example", q: "Login", limit: 20)
node(doc: "example", id: "3:5123")
```
### MCP 工具
| 工具 | 用途 |
| --- | --- |
| `load(path)` | 加载本地 `.fig` 文件 |
| `docs()` | 列出已加载的文档 |
| `tree(doc, depth, children)` | 返回紧凑的树 |
| `node(doc, id, raw, includeChildren)` | 按ID返回节点，O(1) |
| `search(doc, q, type, limit)` | 按名称/类型搜索节点 |
| `types(doc)` | 计算节点类型 |
### 紧凑的 JSON 格式
MCP响应使用短键来减少令牌：
```json
{
"id": "3:5123",
"t": "FRAME",
"n": "Login Version 1",
"c": 3,
"ch": []
}
```
键映射：
- `id`：文档或节点ID
- `t`：节点类型
- `n`：节点名称
- `c`：子节点数
- `ch`：子节点
- `v`：可见
- `p`：父节点ID
- `raw`：解码的Kiwi字段，仅在请求时
## 🧠 数据模型
加载的文档存储为：
```text
LoadedDoc
Roots: 树根节点
Nodes: 字符串字典， FigmaNode
```
这意味着 `node(doc, "session:local")` 是O(1)字典查找。
## 🔒 只读合约
该项目**不**：
- 写入 `.fig` 文件
- 变异节点
- 调用Figma API
- 需要Figma令牌
- 与实时Figma文档同步
## 🧪 构建检查
```bash
dotnet build
```
目前不包含测试项目。
## 📝 备注
Kiwi模式嵌入在 `.fig` 文件中，因此解析器首先解码动态原始对象，然后在其上构建小型类型化模型。未知的Figma字段仍然可以通过原始节点数据获得。
