VMFramework MCP

VMFramework MCP 是一个仅编辑器（Editor-only）的 Unity 包，它为 VM Unity MCP 添加了支持 VMFramework 的项目工具。它使用 VMFramework 的公共概念——GamePrefabs、GeneralSettings、GameTags、UI 面板、容器和属性——而不是要求调用方编辑内部序列化字段。

这些工具加入 VM Unity MCP 的绑定项目规范目录。一个配套服务器连接不可变地绑定到一个项目，并在首次成功列出工具时发布完整的类型化目录。搜索和精确契约检查基于该已公布的表面运行，因此项目特定工具绝不会跨连接泄漏。

安装

VMFramework MCP 是已使用 VMFramework 的项目的可选扩展。首先完成基础 VM Unity MCP 和 MCP 主机设置，包括其健康检查。此包复用同一个服务器连接，不需要再添加 Codex、Claude Desktop 或其他 MCP 主机条目。

要求

• Unity 6000.4 或更新版本。

• com.vm233.unity-mcp 10.x。包契约要求该主版本线中 10.0.0 或更新版本；当前匹配版本为 10.0.13。

• package.json 声明的 VMFramework、VMCore、VM Odin Extensions 和 Unity Localization 依赖。

项目必须已经从自己的 Packages/manifest.json 或配置的注册表中解析 VMFramework 依赖栈。基础框架请遵循 VMFramework 安装指南；此扩展不会重复那些 Git 固定版本。

添加包

在 Unity 中，打开 Window > Package Manager，选择 Add package from git URL...，然后输入：

https://github.com/VM233/VMFramework-MCP.git#v5.1.0

对于不可变项目固定版本，请在 Packages/manifest.json 中使用该版本发布的完整提交 SHA：

"com.vm233.vmframework-mcp": "https://github.com/VM233/VMFramework-MCP.git#3463cab5f5018ecfd7b9bc5414293c03f2b4c1dd"

让 Package Manager 更新 Packages/packages-lock.json；不要编辑 Library/PackageCache 或嵌入该包。

验证扩展

Unity 完成包的解析和编译后，如果 MCP 主机已经发布了项目的工具列表，请重新连接。使用 moduleId: vmframework 调用 unity_tools_search，用 unity_tools_get 检查一个精确结果，并直接调用该已公布的带类型工具。当这些工具与基础 Unity 工具出现在同一个项目绑定目录中时，扩展即安装正确。

Related MCP server: Registry Browser MCP

项目工具

使用配套服务器的 unity_tools_search（使用意图或 moduleId: vmframework），然后用 unity_tools_get 检查一个精确结果。按照已发布的 schema 直接调用已公布的带类型工具。该包目前发布以下能力系列：

• 有效配置和 GeneralSettings 发现；

• GamePrefab 类型发现、搜索、配置查询、检查、创建和原子更新；

• UI 面板、绑定对象、容器面板和 VisualElementPath 检查；

• PropertyManager 读取、运行时写入和有界追踪；

• GameTag 列出、本地化 upsert 和验证。

• 以 owner 为作用域的运行时 GameItem 会话，包括放置、属性、可选的项目域阵营设置、Panel 绑定和令牌清理；

• 运行时 Panel 生命周期、绑定、实际可见性以及 OnOpen/OnPostClose 等待；

• Procedure 状态等待和 Logic Tick 查询/控制；

• 一次性运行时 GameItem 检查；

• 通用的 wrapper/GamePrefab/Prefab/component/GameTag/localization/dependency 以及反向引用追踪。

目录能力标志是 tags 中仅表示存在性的字符串；缺少标签表示 false。确切的资源/运行时效果保留在 sideEffects 中，而动态工具结果（如实际可见性、失败的等待匹配或未推进的 tick）保持显式布尔值，因为 false 是有意义的运行时数据。

运行时 GameItem 域适配器是 VMFramework 不拥有的项目事实的唯一扩展点。项目实现必须读取和修改权威的游戏玩法组件；名称、标签、Prefab 路径、层级和 UI 状态不能作为阵营、能力或生命周期的有效代理。

长时间等待和反向引用扫描使用 runAsJob=true。使用 jobs/get 轮询返回的 Job，通过 jobs/cancel 取消它，并且仅在 Job 报告可用的清理令牌时调用 jobs/cleanup。会话创建还接受 sessionKey；仅当每个创建参数都匹配时，重用它才是有效的。

单面板 UI 工具要求恰好一个 panelID 或 prefabPath。vmframework/validate-visual-element-paths 还接受 allPanels: true 来审计每个已注册的面板和独立的 UIPanel prefab。聚合结果进行全局分页，并分别报告缺失的 prefab、缺失的 VisualTreeAssets、无效的面板和无效的路径。由可解析的 Odin ShowIf 或 HideIf 条件禁用的路径会被排除，因为它们不属于组件的活动配置。

所有 schema 都拒绝未知的业务参数。选择器、路径、ID、事务操作、dryRun、覆盖选择和注册选择在每次请求中保持显式。

GamePrefab 创作现在有一个可直接组合的数据产物：vmframework.game-prefab-ref。vmframework/add-game-prefab 和 vmframework/find-game-prefab 生成该引用；vmframework/inspect-game-prefab 和 vmframework/update-game-prefab 需要它；update 返回经过验证的当前引用。在配套服务器中使用 fromTool 或 toTool 搜索，以获取精确的结果到输入的 JSON 指针绑定，然后直接在两个普通工具之间传递引用对象。该包不提供通用链式执行器，也不接受转发的 JSON 字符串。当匹配的 wrapper 未注册到恰好一个类型兼容的 GamePrefabGeneralSetting 时，发现会安全失败（fail closed）；使用者在读取或修改之前会重新验证同一注册。

vmframework/query-game-prefab-configs 将选择和投影分开。id、filter 和 gamePrefabType 选择身份和一个可赋值的框架类型；gameTagsAll、gameTagsAny、gameTagsNone、hasName 和 hasDescription 组合内容过滤器。fields 显式选择 gameTags、name 或 description，而 locales 缩小本地化值的范围。每一行仍然携带 vmframework.game-prefab-ref，因此调用方可以将一个匹配项传递给 inspect-game-prefab 以获取完整的受限序列化对象。省略 fields 会生成仅包含身份的最小页面；批量查询不会重复完整对象检查器。

消费项目提供自己的类型名称和 GameTag id。例如，项目可以请求任意类型/标签组合的某一种语言环境的名称，而无需该包定义该类型或标签的含义：

{
  "gamePrefabType": "<full GamePrefab type>",
  "gameTagsAll": ["<tag-id>"],
  "hasName": true,
  "fields": ["name"],
  "locales": ["en-US"]
}

vmframework/update-game-prefab 通过根级 id 设置操作支持语义 ID 迁移。操作种类是类型化值 set、append、insert、remove 和 clear。事务会验证并读回新身份，在 gamePrefab 中返回它，并在身份更改时包含 previousId。

更新在变更前对 wrapper 和 meta 字节做快照。成功提交返回 terminalState="committed" 及 SHA-256 提交证据。失败时，同目录原子替换会恢复基线，Unity 同步导入它，并且字节读取和语义读取都必须通过，工具才会返回 terminalState="rolled_back"。恢复失败会报告为 rollback_failed，原始错误和回滚错误分开保留。

配置

有效默认值按以下顺序使用：

1. 显式工具参数；

2. Project Settings > VMFramework MCP；

3. Preferences > VMFramework MCP 或共享的 Preferences > Unity MCP 结果预算；

4. 包默认值。

ProjectSettings/VMFrameworkMCPSettings.json 属于团队所有，仅包含 GameTag 验证覆盖契约：

{
  "schemaVersion": 1,
  "gameTagValidation": {
    "includeMissingTranslations": true,
    "includeGamePrefabReferences": true
  }
}

Preferences > VMFramework MCP 包含操作员响应选项：GamePrefab 检查深度、每个集合的条目预算、可选的更新快照，以及保留的属性追踪容量。

单一主集合工具复用 Preferences > Unity MCP > Tool Responses 下的可选结果数量限制覆盖。VMFramework MCP 不会复制该偏好设置。

大型或不确定的细节由请求方控制，默认关闭：

• includeGamePrefabDetails；

• includeRuntime；

• includeValid；

• includeLocalizations；

• includeSnapshots；

• includeValidation（作用于 upsert-game-tag）。

GamePrefab 配置查询投影也通过 fields 由请求方控制；除非 locales 缩小范围，否则本地化投影会包含每个表语言环境。

请参阅 Documentation~/configuration.md 了解每个工具的所有权审计和响应规则。

开发

通过已公布的 unity_testing_run_package_tests 工具运行包的 EditMode 测试，或使用 VMFrameworkMCP.FullRegression 筛选 Unity Test Runner。回归套件验证精确的 VMFramework 目录、直接路由、操作元数据、严格 schema、设置往返，以及 GamePrefab/GameTag 转换行为。

此包不包含运行时程序集。