内容
# 🧩 图标本地 MCP
🔍 **本地优先的 MCP 和 C# 工具包，用于 Figma `.fig` 文件。**
FigLocal MCP 直接在您的机器上打开导出的 `.fig` 文件，解码嵌入的 Kiwi 场景图，构建快速的节点树，并通过紧凑的本地 MCP 服务器公开它。它还包括一个 C# 库、CLI 和简单的调试 Web 浏览器。
> ⚠️ `.fig` 不是官方公开的 Figma 格式。该项目是尽力而为的本地只读逆向工程。
## ✨ 功能
- 📦 读取 `.fig` ZIP 容器：`canvas.fig`、`meta.json`、`thumbnail.png`、`images/*`
- 🥝 解码嵌入的 Kiwi 模式和数据块
- 🌳 从 `nodeChanges` 构建场景树
- ⚡ 将节点存储在 `id -> node` 索引中以实现 O(1) 查找
- 🧰 提供用于快速检查的 CLI
- 🖥️ 提供简单的 jsTree 调试 Web 浏览器
- 🤖 提供用于代理工作流的紧凑 MCP 服务器
- 🔒 按设计只读：无写入、无突变、无 Figma API 授权
## 🧱 仓库布局
```text
src/Figma.Fig 核心只读解析器库
src/Figma.Fig.Cli CLI 检查器
src/Figma.Fig.Web 简单的调试 Web 浏览器
src/Figma.Fig.Mcp Stdio 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 stdio 服务器
- `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}");
```
### CLI
检查文件摘要：
```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 服务器
运行_stdio 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: Dictionary<string, FigmaNode>
```
这意味着 `node(doc, "session:local")` 是 O(1) 字典查找。
## 🔒 只读合约
该项目**不**：
- 写入 `.fig` 文件
- 突变节点
- 调用 Figma API
- 需要 Figma 令牌
- 与实时 Figma 文档同步
## 🧪 构建检查
```bash
dotnet build
```
当前不包含测试项目。
## 📝 备注
Kiwi 模式嵌入在 `.fig` 文件中，因此解析器首先解码动态原始对象，然后在其上构建小型类型化模型。未知的 Figma 字段通过原始节点数据仍然可用。
