Unity Prefab Parser MCP

Unity预制解析器MCP服务器

解析Unity的MCP（模型上下文协议）服务器 文本序列化 .prefab, .unity，以及 .asset 文件和输出仅以干净、分层的YAML格式显示检查器可见的数据，将令牌使用率降低了96%。

支持常规预制件， 预制变体 （显示按游戏对象和组件分组的覆盖值）和场景文件。

使用 任何兼容MCP的AI客户端：Claude Desktop、OpenCode、VS Code Copilot、Cursor、Windsurf、Codex等。

______________________________________________________________________

快速开始

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   — scan .meta files, build GUID cache (once per project)
2. browse_unity_project — navigate folder tree to find the right subfolder
3. list_unity_assets    — list assets in that folder (filter by type or name)
4. parse_unity_file     — parse with preset: "compact" for token-efficient output

后续会议

跳过 init_unity_project 如果 .unity-mcp-cache.json 存在且不到24小时。直走 browse_unity_project 或 list_unity_assets.

示例提示

Initialize my Unity project at /path/to/MyGame, then show me all enemy prefabs.

AI将呼叫 init_unity_project → browse_unity_project → list_unity_assets → parse_unity_file 自动。

______________________________________________________________________

工具

init_unity_project

扫描全部 .meta Unity项目中的文件并保存GUID→资产名称缓存到 .unity-mcp-cache.json。每个项目运行一次。后续的解析调用会自动从缓存加载——重新扫描成本为零。

{
  "projectPath": "/path/to/MyUnityProject",
  "force": false
}

• projectPath --Unity项目根目录的路径（包含 Assets/, ProjectSettings/)
• force --即使缓存是新的，也强制重新扫描（默认值： false)

返回：资产计数、所用时间、缓存文件位置。

______________________________________________________________________

browse_unity_project

在Unity项目文件夹树中导航每个文件夹的资产计数。在调用之前，使用此功能查找所需的子文件夹 list_unity_assets.

{
  "projectPath": "/path/to/MyUnityProject",
  "subPath": "Assets/Enemies",
  "depth": 2
}

输出示例：

Assets/
├── Enemies/          (12 prefabs)
├── UI/               (8 prefabs, 3 assets)
│   ├── HUD/          (4 prefabs)
│   └── Menus/        (4 prefabs)
├── Levels/           (5 scenes)
└── ScriptableObjects/ (23 assets)

______________________________________________________________________

list_unity_assets

列表 .prefab, .unity，以及 .asset 目录中的文件，其绝对路径已准备好粘贴到 parse_unity_file.

{
  "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文本序列化文件，并将Inspector可见组件数据提取为干净的YAML。

{
  "filePath": "/path/to/MyUnityProject/Assets/Enemies/BatPF.prefab",
  "config": {
    "preset": "compact"
  }
}

预设：

您可以将预设与替代混合使用：

{ "preset": "compact", "includeDefaultValues": true }

______________________________________________________________________

parse_unity_prefab *（已弃用）*

别名为 parse_unity_file。仍然适用于向后兼容性。

______________________________________________________________________

客户端设置

所有客户端都使用相同的MCP服务器二进制文件。替换 /path/to/unity-prefab-parser-mcp 使用您的实际克隆路径。

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "unity-prefab-parser": {
      "command": "node",
      "args": ["/path/to/unity-prefab-parser-mcp/dist/index.js"]
    }
  }
}

开源代码

添加到您的 opencode.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配置目录中：

# Copy all three Unity skills
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/

# Copy all Unity slash commands
cp /path/to/unity-prefab-parser-mcp/commands/*.md ~/.config/opencode/commands/

然后重新启动OpenCode。技能出现在 /skills，命令出现在 /commands.

安装后可用的Slash命令：

• /unity-init [path] --初始化项目缓存
• /unity-browse [path] --浏览项目树
• /unity-list [path] [type] [search] --列出资产
• /unity-parse [path] --使用紧凑的预设进行解析
• /unity-diff [pathA] [pathB] --比较两个序言或场景
• /unity-scene [path] --令牌高效场景概述

VS代码（GitHub Copilot/MCP扩展）

添加 .vscode/mcp.json 在您的工作区中，或访问VS Code用户设置：

{
  "mcpServers": {
    "unity-prefab-parser": {
      "command": "node",
      "args": ["/path/to/unity-prefab-parser-mcp/dist/index.js"]
    }
  }
}

这 .github/copilot-instructions.md 当仓库打开时，Copilot会自动读取此仓库中捆绑的内容——工作流指导不需要额外的配置。

光标/风帆

添加到MCP设置（设置→ MCP → 添加服务器）：

{
  "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→ 浏览→ list → 自动解析工作流。

______________________________________________________________________

Unity序列化要求

此服务器需要Unity的 文本序列化 格式。如果文件是二进制的，服务器将拒绝它并显示明确的错误。

启用文本序列化： Edit → 项目设置→ 编辑→ 资产序列化→ 模式=强制文本

• Unity编辑器管理器文档
• UnityYAML文档

______________________________________________________________________

输出示例

常规预制（紧凑模式）

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 并且只有来自基础预制件的修改，按游戏对象和实际组件/脚本类型分组：

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  # $

变体标记：

注： Unknown GameObjects是嵌套预制链中2层以上深度的修改目标——如果不进行递归加载，它们的名称就无法解析。

______________________________________________________________________

代币成本参考

生产预制件的实际测量：

运营成本：

______________________________________________________________________

配置参考

______________________________________________________________________

支持的组件

内置现场过滤器，适用于：

• 变换，矩形变换
• 刚体，刚体2D
• 所有碰撞器类型（长方体、球体、胶囊、圆形、多边形、网格）
• SpriteRenderer、网格渲染器、蒙皮网格渲染器和网格过滤器
• 动画师，动画
• 音频源、相机、灯光
• 画布，画布缩放器，图形光线投射器
• UI：图像、文本、TextMeshProUGUI、按钮
• ParticleSystem、粒子系统渲染器、轨迹渲染器、线渲染器
• MonoBehaviour（自定义脚本——显示所有序列化字段）

______________________________________________________________________

项目结构

unity-prefab-parser-mcp/
├── src/
│   ├── index.ts        # MCP server, all tool definitions
│   ├── parser.ts       # Unity YAML parsing
│   ├── resolver.ts     # Reference and value resolution
│   ├── components.ts   # Component field filters and renames
│   ├── hierarchy.ts    # GameObject tree builder
│   ├── formatter.ts    # YAML output formatter
│   ├── config.ts       # Configuration and presets
│   ├── cache.ts        # Meta file GUID cache
│   └── variant.ts      # Prefab variant detection
├── skills/
│   ├── unity-asset-workflow/
│   │   └── SKILL.md    # General workflow (init, browse, list, parse)
│   ├── unity-diff-workflow/
│   │   └── SKILL.md    # Compare prefabs, variants, scenes
│   └── unity-scene-workflow/
│       └── SKILL.md    # Navigate large scenes token-efficiently
├── 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  # Test suite (103 tests)
├── AGENTS.md           # Auto-read by Codex and Claude Code
├── .github/
│   └── copilot-instructions.md  # Auto-read by GitHub Copilot
├── package.json
└── tsconfig.json

______________________________________________________________________

发展

npm install       # install dependencies
npm run build     # compile TypeScript
npm test          # run test suite (103 tests)
npm run dev       # run with tsx (no build needed)

______________________________________________________________________

许可证

麻省理工学院