使用说明

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客户端配置中（请参阅客户端设置在......下面

工具

`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"
  }
}

预设：

预设	代币减少	最适合
`compact`	~93–96%	LLM分析、比较
`standard`	约84%	当您需要GUID注释时
`minimal`	~95%	快速结构概述

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

{ "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.

技能	目的
`unity-asset-workflow`	通用工作流——初始化、浏览、列表、解析
`unity-diff-workflow`	比较不同版本的预制件、变体和场景
`unity-scene-workflow`	导航大 `.unity` 场景令牌高效

安装后可用的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 → 项目设置→ 编辑→ 资产序列化→ 模式=强制文本

输出示例

常规预制（紧凑模式）

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层以上深度的修改目标——如果不进行递归加载，它们的名称就无法解析。

代币成本参考

生产预制件的实际测量：

文件	原始YAML	解析压缩	缩减
Buck.prefab（变体，38KB）	~9600个令牌	~400个令牌	96%
Buck Base.prefab（完整，73KB）	~18000个令牌	~1200个令牌	93%

运营成本：

操作	大约令牌
`init_unity_project`	0（仅磁盘）
`browse_unity_project`	~200–500
`list_unity_assets` （50个文件）	~800
`parse_unity_file` 紧凑型	约150-1200
`parse_unity_file` 标准	~300-2000
原始Unity YAML（同一文件）	~5000–50000

配置参考

选项	类型	默认值	描述
`preset`	`"minimal"`	`"standard"`	`"compact"`
`resolveAssetNames`	布尔值	`true`	将GUID解析为资产名称
`showAssetTypes`	布尔值	`true`	将资产类型显示为注释
`arrayMaxElements`	编号	`20`	汇总前的最大数组元素数
`nestedObjectDepth`	编号	`4`	嵌套对象的最大深度
`includeTransform`	布尔值	`true`	包含转换组件
`includeDisabledObjects`	布尔值	`true`	包括禁用的游戏对象
`includeDefaultValues`	布尔值	`false`	包含具有默认值的属性
`includeNullReferences`	布尔值	`false`	包含空引用
`includeHierarchy`	布尔值	`true`	包含层次结构部分
`componentWhitelist`	string[]	`[]`	仅包括这些组件类型
`componentBlacklist`	string[]	`[]`	排除这些组件类型
`useBooleans`	布尔值	`false`	将0/1转换为真/假
`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`	显示 `# $`, `# +`, `# -` 标记

支持的组件

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

变换，矩形变换
刚体，刚体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)

许可证

麻省理工学院

Unity预制件解析服务

使用说明

Unity预制解析器MCP服务器

快速开始

推荐工作流程

首次参与项目

后续会议

示例提示

工具

`init_unity_project`

`browse_unity_project`

`list_unity_assets`

`parse_unity_file`

`parse_unity_prefab` （已弃用）

客户端设置

克劳德桌面版

开源代码

VS代码（GitHub Copilot/MCP扩展）

光标/风帆

Codex/Claude Code（CLI代理）

Unity序列化要求

输出示例

常规预制（紧凑模式）

预制变体（紧凑型）

代币成本参考

配置参考

支持的组件

项目结构

发展

许可证

使用说明

Unity预制解析器MCP服务器

快速开始

推荐工作流程

首次参与项目

后续会议

示例提示

工具

init_unity_project

browse_unity_project

list_unity_assets

parse_unity_file

parse_unity_prefab （已弃用）

客户端设置

克劳德桌面版

开源代码

VS代码（GitHub Copilot/MCP扩展）

光标/风帆

Codex/Claude Code（CLI代理）

Unity序列化要求

输出示例

常规预制（紧凑模式）

预制变体（紧凑型）

代币成本参考

配置参考

支持的组件

项目结构

发展

许可证

相关 MCP

网页搜索协议服务

LeetCode API服务

内存银行管理服务器

AI认知检查工具

arXiv论文搜索服务

Word文档实时编辑工具

`init_unity_project`

`browse_unity_project`

`list_unity_assets`

`parse_unity_file`

`parse_unity_prefab` （已弃用）