内容
# Unity Prefab 解析 MCP 服务器
MCP（模型上下文协议）服务器，用于解析 Unity **文本序列化**的 `.prefab`、`.unity` 和 `.asset` 文件，并以干净的、分层结构的 YAML 格式输出仅限检查器可见的数据 — 可减少高达 96% 的令牌使用量。
支持常规预制件、**预制件变体**（显示按 GameObject 和组件分组的覆盖值）和场景文件。
与**任何 MCP 兼容的 AI 客户端**配合使用：Claude Desktop、OpenCode、VS Code Copilot、Cursor、Windsurf、Codex 等。
---
## 快速入门
```bash
git clone https://github.com/luckynee/unity-prefab-parser-mcp.git
cd unity-prefab-parser-mcp
npm install && npm run build
```
然后添加到您的 AI 客户端配置中（参见下面的[客户端设置](#客户端设置)）。
---
## 推荐的工作流程
### 首次使用项目
```
1. init_unity_project — 扫描 .meta 文件，构建 GUID 缓存（每个项目一次）
2. browse_unity_project — 导航文件夹树以找到正确的子文件夹
3. list_unity_assets — 列出该文件夹中的资产（按类型或名称筛选）
4. parse_unity_file — 使用预设解析： "compact" 以实现高效的令牌输出
```
### 后续会话
跳过 `init_unity_project` 如果 `.unity-mcp-cache.json` 存在且小于 24 小时。直接进入 `browse_unity_project` 或 `list_unity_assets`。
### 示例提示
```
初始化我的 Unity 项目，路径为 /path/to/MyGame，然后显示所有敌人预制件。
```
AI 将自动调用 `init_unity_project` → `browse_unity_project` → `list_unity_assets` → `parse_unity_file`。
---
## 工具
### `init_unity_project`
扫描 Unity 项目中的所有 `.meta` 文件，并将 GUID→资产名称缓存保存到 `.unity-mcp-cache.json`。每个项目运行一次。后续解析调用将自动从缓存加载 — 零重新扫描成本。
```json
{
"projectPath": "/path/to/MyUnityProject",
"force": false
}
```
- `projectPath` — Unity 项目根目录的路径（包含 `Assets/`、`ProjectSettings/` 的文件夹）
- `force` — 强制重新扫描，即使缓存新鲜（默认：`false`）
返回：资产数量、耗时、缓存文件位置。
---
### `browse_unity_project`
导航 Unity 项目文件夹树，显示每个文件夹的资产数量。使用此功能在调用 `list_unity_assets` 之前找到要查找的子文件夹。
```json
{
"projectPath": "/path/to/MyUnityProject",
"subPath": "Assets/Enemies",
"depth": 2
}
```
示例输出：
```
Assets/
├── Enemies/ (12 个预制件)
├── UI/ (8 个预制件，3 个资产)
│ ├── HUD/ (4 个预制件)
│ └── Menus/ (4 个预制件)
├── Levels/ (5 个场景)
└── ScriptableObjects/ (23 个资产)
```
---
### `list_unity_assets`
列出目录中的 `.prefab`、`.unity` 和 `.asset` 文件，路径绝对，可直接粘贴到 `parse_unity_file` 中。
```json
{
"directory": "/path/to/MyUnityProject/Assets/Enemies",
"type": "prefab",
"search": "bat",
"recursive": true,
"limit": 50
}
```
- `type` — `"prefab"`、`"unity"`、`"asset"` 或 `"all"`（默认：`"all"`）
- `search` — 不区分大小写的名称筛选器（例如 `"enemy"` 返回 `EnemyBat.prefab`、`EnemyWolf.prefab`）
- `recursive` — 搜索子文件夹（默认：`true`）
- `limit` — 最大结果数（默认：`50`）
---
### `parse_unity_file`
解析 Unity 文本序列化文件，提取检查器可见的组件数据为干净的 YAML。
```json
{
"filePath": "/path/to/MyUnityProject/Assets/Enemies/BatPF.prefab",
"config": {
"preset": "compact"
}
}
```
**预设：**
| 预设 | 令牌减少 | 最适合 |
|--------|----------------|----------|
| `compact` | ~93–96% | LLM 分析、比较 |
| `standard` | ~84% | 需要 GUID 注释时 |
| `minimal` | ~95% | 快速结构概览 |
可以混合预设和覆盖项：
```json
{ "preset": "compact", "includeDefaultValues": true }
```
---
### `parse_unity_prefab` *(已弃用)*
`parse_unity_file` 的别名。仍为向后兼容而工作。
---
## 客户端设置
所有客户端都使用相同的 MCP 服务器二进制文件。将 `/path/to/unity-prefab-parser-mcp` 替换为实际的克隆路径。
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"unity-prefab-parser": {
"command": "node",
"args": ["/path/to/unity-prefab-parser-mcp/dist/index.js"]
}
}
}
```
### OpenCode
添加到您的 `opencode.json` 中：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"unity-parser": {
"type": "local",
"command": ["node", "/path/to/unity-prefab-parser-mcp/dist/index.js"],
"enabled": true
}
}
}
```
**OpenCode 用户：** 将捆绑的技能和命令复制到您的 OpenCode 配置目录：
```bash
# 复制所有三个 Unity 技能
cp -r /path/to/unity-prefab-parser-mcp/skills/unity-asset-workflow ~/.config/opencode/skills/
cp -r /path/to/unity-prefab-parser-mcp/skills/unity-diff-workflow ~/.config/opencode/skills/
cp -r /path/to/unity-prefab-parser-mcp/skills/unity-scene-workflow ~/.config/opencode/skills/
# 复制所有 Unity 斜杠命令
cp /path/to/unity-prefab-parser-mcp/commands/*.md ~/.config/opencode/commands/
```
然后重启 OpenCode。技能出现在 `/skills` 中，命令出现在 `/commands` 中。
| 技能 | 目的 |
|---|---|
| `unity-asset-workflow` | 一般工作流程 — 初始化、浏览、列出、解析 |
| `unity-diff-workflow` | 比较预制件、变体、场景的版本 |
| `unity-scene-workflow` | 高效浏览大型 `.unity` 场景 |
安装后可用的斜杠命令：
- `/unity-init [path]` — 初始化项目缓存
- `/unity-browse [path]` — 浏览项目树
- `/unity-list [path] [type] [search]` — 列出资产
- `/unity-parse [path]` — 使用紧凑预设解析
- `/unity-diff [pathA] [pathB]` — 比较两个预制件或场景
- `/unity-scene [path]` — 高效场景概览
### VS Code（GitHub Copilot / MCP 扩展）
添加到您工作区的 `.vscode/mcp.json` 或 VS Code 用户设置中：
```json
{
"mcpServers": {
"unity-prefab-parser": {
"command": "node",
"args": ["/path/to/unity-prefab-parser-mcp/dist/index.js"]
}
}
}
```
此存储库中捆绑的 `.github/copilot-instructions.md` 文件被 Copilot 自动读取 — 无需额外配置即可实现工作流程指导。
### Cursor / Windsurf
添加到您的 MCP 设置（设置 → MCP → 添加服务器）：
```json
{
"unity-prefab-parser": {
"command": "node",
"args": ["/path/to/unity-prefab-parser-mcp/dist/index.js"]
}
}
```
### Codex / Claude Code（CLI 代理）
此存储库中捆绑的 `AGENTS.md` 文件被 Codex 和 Claude Code 自动读取 — 无需额外配置。他们将自动遵循 init → browse → list → parse 工作流程。
---
## Unity 序列化要求
此服务器需要 Unity 的**文本序列化**格式。如果文件是二进制的，服务器将拒绝并显示明确的错误。
启用文本序列化：**编辑 → 项目设置 → 编辑器 → 资产序列化 → 模式 = 强制文本**
- [Unity 编辑器管理器文档](https://docs.unity3d.com/Manual/class-EditorManager.html)
- [UnityYAML 文档](https://docs.unity3d.com/Manual/UnityYAML.html)
---
## 示例输出
### 常规预制件（紧凑模式）
```yaml
prefab_name: BatPF
hierarchy: |
BatPF (t: Player, l: Layer28)
├── Geometry
└── Data
components:
BatPF:
Transform:
lPos: (27.13, -6.38, 0)
Rigidbody2D:
mass: 3
linearDrag: 5
angularDrag: 6
gravity: 0
bodyType: 0
sleepingMode: 1
CircleCollider2D: {trigger: true, radius: 0.5}
Data:
EntityData:
_entityName: Bat
_walkSpeed: 1.5
_attack: 10
_defense: 2
_isAlive: true
```
### 预制件变体（紧凑模式）
变体显示 `variant_of` 和仅从基础预制件修改的内容，按 GameObject 和实际组件/脚本类型分组：
```yaml
prefab_name: Buck
variant_of: Buck Base
hierarchy: |
Buck Base # $
├── AI # $
├── Hitable Geometry # $
└── Unknown # $
components:
Buck Base:
Transform: # $
lPos: (-42.633396, -215.17801, 0) # $
GameObject: # $
name: Buck # $
Seeker: # $
tagPenalties.array.data: 10000 # $
AI:
AIBrain: # $
states.array.size: 7 # $
states.array.data.stateName: Exit Scene # $
states.array.data.transitions.array.array.data.trueState: Flee # $
Hitable Geometry:
GameObject: # $
layer: 20 # $
Unknown:
AggressiveAnimalData: # $
_defense: 3 # $
Animator: # $
ctrl: Buck Anim Controller # $
```
**变体标记：**
| 标记 | 含义 |
|--------|---------|
| `# $` | 从基础修改 |
| `# +` | 添加（新组件或 GameObject） |
| `# -` | 从基础删除 |
> **注意：** `Unknown` GameObjects 是修改目标，它们存在于嵌套预制件链中 2+ 级深 — 它们的名字无法在不递归加载的情况下解析。
---
## 令牌成本参考
生产预制件的实际测量：
| 文件 | 原始 YAML | 解析紧凑 | 减少 |
|------|----------|----------------|-----------|
| Buck.prefab（变体，38KB） | ~9,600 个令牌 | ~400 个令牌 | **96%** |
| Buck Base.prefab（完整，73KB） | ~18,000 个令牌 | ~1,200 个令牌 | **93%** |
操作成本：
| 操作 | 近似令牌 |
|---|---|
| `init_unity_project` | 0（仅磁盘） |
| `browse_unity_project` | ~200–500 |
| `list_unity_assets`（50 个文件） | ~800 |
| `parse_unity_file` 紧凑 | ~150–1,200 |
| `parse_unity_file` 标准 | ~300–2,000 |
| 原始 Unity YAML（相同文件） | ~5,000–50,000 |
---
## 配置参考
| 选项 | 类型 | 默认值 | 描述 |
|--------|------|---------|-------------|
| `preset` | `"minimal"` \| `"standard"` \| `"compact"` | — | 使用预设 |
| `resolveAssetNames` | 布尔值 | `true` | 解析 GUID 为资产名称 |
| `showAssetTypes` | 布尔值 | `true` | 显示资产类型为注释 |
| `arrayMaxElements` | 数字 | `20` | 最大数组元素个数，超过时汇总 |
| `nestedObjectDepth` | 数字 | `4` | 嵌套对象最大深度 |
| `includeTransform` | 布尔值 | `true` | 包括 Transform 组件 |
| `includeDisabledObjects` | 布尔值 | `true` | 包括禁用的 GameObjects |
| `includeDefaultValues` | 布尔值 | `false` | 包括具有默认值的属性 |
| `includeNullReferences` | 布尔值 | `false` | 包括空/空引用 |
| `includeHierarchy` | 布尔值 | `true` | 包括层次结构部分 |
| `componentWhitelist` | 字符串数组 | `[]` | 仅包括这些组件类型 |
| `componentBlacklist` | 字符串数组 | `[]` | 排除这些组件类型 |
| `useBooleans` | 布尔值 | `false` | 将 0/1 转换为 true/false |
| `convertBitmasks` | 布尔值 | `false` | 将 LayerMask 转换为层数组 |
| `useTreeHierarchy` | 布尔值 | `false` | 对层次结构使用树格式 |
| `abbreviateFieldNames` | 布尔值 | `false` | 缩短字段名称（`lPos`、`lRot`） |
| `omitDefaultTransforms` | 布尔值 | `false` | 省略默认位置/旋转/缩放 |
| `useShortRefs` | 布尔值 | `false` | 使用 `@Name` 代替 `<Type:Name>` |
| `useParenVectors` | 布尔值 | `false` | 使用 `(x, y, z)` 代替 `{x, y, z}` |
| `inlineSimpleComponents` | 布尔值 | `false` | 内联具有 1-2 个字段的组件 |
| `showVariantMarkers` | 布尔值 | `true` | 显示 `# $`、`# +`、`# -` 标记 |
---
## 支持的组件
内置字段过滤器：
- Transform, RectTransform
- Rigidbody, Rigidbody2D
- 所有碰撞器类型（Box, Sphere, Capsule, Circle, Polygon, Mesh）
- SpriteRenderer, MeshRenderer, SkinnedMeshRenderer, MeshFilter
- Animator, Animation
- AudioSource, Camera, Light
- Canvas, CanvasScaler, GraphicRaycaster
- UI: Image, Text, TextMeshProUGUI, Button
- ParticleSystem, ParticleSystemRenderer, TrailRenderer, LineRenderer
- MonoBehaviour（自定义脚本 — 显示所有序列化字段）
---
## 项目结构
```
unity-prefab-parser-mcp/
├── src/
│ ├── index.ts # MCP 服务器，所有工具定义
│ ├── parser.ts # Unity YAML 解析
│ ├── resolver.ts # 引用和值解析
│ ├── components.ts # 组件字段过滤器和重命名
│ ├── hierarchy.ts # GameObject 树构建
│ ├── formatter.ts # YAML 输出格式化
│ ├── config.ts # 配置和预设
│ ├── cache.ts # Meta 文件 GUID 缓存
│ └── variant.ts # 预制件变体检测
├── skills/
│ ├── unity-asset-workflow/
│ │ └── SKILL.md # 一般工作流程（init, browse, list, parse）
│ ├── unity-diff-workflow/
│ │ └── SKILL.md # 比较预制件、变体、场景的版本
│ └── unity-scene-workflow/
│ └── SKILL.md # 高效浏览大型 `.unity` 场景
├── commands/
│ ├── unity-init.md # /unity-init [path]
│ ├── unity-browse.md # /unity-browse [path]
│ ├── unity-list.md # /unity-list [path] [type] [search]
│ ├── unity-parse.md # /unity-parse [path]
│ ├── unity-diff.md # /unity-diff [pathA] [pathB]
│ └── unity-scene.md # /unity-scene [path]
├── test/
│ └── parser.test.ts # 测试套件（103 个测试）
├── AGENTS.md # Codex 和 Claude Code 自动读取
├── .github/
│ └── copilot-instructions.md # GitHub Copilot 自动读取
├── package.json
└── tsconfig.json
```
---
## 开发
```bash
npm install # 安装依赖
npm run build # 编译 TypeScript
npm test # 运行测试套件（103 个测试）
npm run dev # 使用 tsx 运行（无需构建）
```
---
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器