VMFramework MCP

VMFramework MCP is an Editor-only Unity package that adds VMFramework-aware project tools to VM Unity MCP. It works with VMFramework's public concepts—GamePrefabs, GeneralSettings, GameTags, UI panels, containers, and properties—instead of asking callers to edit internal serialized fields.

The tools join VM Unity MCP's project-bound canonical catalog. One companion server connection binds immutably to one project and publishes the complete typed catalog on its first successful tool list. Search and exact contract inspection operate on that already-advertised surface, so project-specific tools never leak across connections.

Installation

VMFramework MCP is an optional extension for projects that already use VMFramework. First complete the base VM Unity MCP and MCP host setup, including its health check. This package reuses that same server connection and does not require another Codex, Claude Desktop, or other MCP host entry.

Requirements

• Unity 6000.4 or newer.

• com.vm233.unity-mcp 10.x. The package contract requires 10.0.0 or newer in that major line; the current matching release is 10.0.13.

• The VMFramework, VMCore, VM Odin Extensions, and Unity Localization dependencies declared by package.json.

The project must already resolve the VMFramework dependency stack from its own Packages/manifest.json or configured registry. Follow the VMFramework installation guide for the base framework; this extension does not duplicate those Git pins.

Add the package

In Unity, open Window > Package Manager, choose Add package from git URL..., and enter:

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

For an immutable project pin, use the release's full commit SHA in Packages/manifest.json:

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

Let Package Manager update Packages/packages-lock.json; do not edit Library/PackageCache or embed the package.

Verify the extension

After Unity finishes resolving and compiling packages, reconnect the MCP host if it had already published the project's tool list. Call unity_tools_search with moduleId: vmframework, inspect one exact result with unity_tools_get, and call that advertised typed tool directly. The extension is installed correctly when its tools appear in the same project-bound catalog as the base Unity tools.

Related MCP server: Registry Browser MCP

Project tools

Use the companion server's unity_tools_search with intent or moduleId: vmframework, then unity_tools_get to inspect one exact result. Call the advertised typed tool directly with its published schema. The package currently publishes these capability families:

• effective configuration and GeneralSettings discovery;

• GamePrefab type discovery, search, config querying, inspection, creation, and atomic update;

• UI panel, bind-object, container-panel, and VisualElementPath inspection;

• PropertyManager reads, runtime writes, and bounded traces;

• GameTag listing, localized upsert, and validation.

• owner-scoped runtime GameItem sessions with placement, properties, optional project-domain faction setup, Panel binding, and token cleanup;

• runtime Panel lifecycle, binding, actual visibility, and OnOpen/OnPostClose waits;

• Procedure state waits and Logic Tick query/control;

• one-shot runtime GameItem inspection;

• generic wrapper/GamePrefab/Prefab/component/GameTag/localization/dependency and reverse-reference tracing.

Catalog capability flags are presence-only strings in tags; missing tags mean false. Exact asset/runtime effects remain in sideEffects, while dynamic tool results such as actual visibility, a failed wait match, or a tick that was not advanced remain explicit booleans because false is meaningful runtime data.

The runtime GameItem domain adapter is the only extension point for project facts that VMFramework does not own. Project implementations must read and mutate authoritative gameplay components; names, tags, Prefab paths, hierarchy, and UI state are not valid proxies for faction, abilities, or lifecycle.

Long waits and reverse-reference scans use runAsJob=true. Poll the returned Job with jobs/get, cancel it through jobs/cancel, and call jobs/cleanup only when the Job reports an available cleanup token. Session creation also accepts a sessionKey; reusing it is valid only when every create argument matches.

Single-panel UI tools require exactly one panelID or prefabPath. vmframework/validate-visual-element-paths additionally accepts allPanels: true to audit every registered panel and standalone UIPanel prefab. Aggregate results are globally paginated and report missing prefabs, missing VisualTreeAssets, invalid panels, and invalid paths separately. Paths disabled by a resolvable Odin ShowIf or HideIf condition are excluded because they are not part of the component's active configuration.

All schemas reject unknown business arguments. Selectors, paths, IDs, transaction operations, dryRun, overwrite choices, and registration choices remain explicit per request.

GamePrefab authoring now has one directly composable data product: vmframework.game-prefab-ref. vmframework/add-game-prefab and vmframework/find-game-prefab produce that reference; vmframework/inspect-game-prefab and vmframework/update-game-prefab require it; update returns the verified current reference. Search with fromTool or toTool in the companion server to obtain the exact result-to-input JSON pointer binding, then pass the reference object between the two ordinary tools directly. The package does not expose a generic chain executor or accept a forwarded JSON string. Discovery fails closed when a matching wrapper is not registered to exactly one type-compatible GamePrefabGeneralSetting; consumers revalidate the same registration before reading or mutating it.

vmframework/query-game-prefab-configs keeps selection and projection separate. id, filter, and gamePrefabType select identity and an assignable framework type; gameTagsAll, gameTagsAny, gameTagsNone, hasName, and hasDescription compose content filters. fields explicitly selects gameTags, name, or description, while locales narrows localized values. Every row still carries vmframework.game-prefab-ref, so callers can pass one match to inspect-game-prefab for the complete bounded serialized object. Omitting fields produces the minimal identity-only page; the bulk query does not duplicate the full-object inspector.

Consumer projects supply their own type names and GameTag ids. For example, a project can request one locale of names for any type/tag combination without the package defining what that type or tag means:

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

vmframework/update-game-prefab supports semantic ID migration through a root id set operation. Operation kinds are the typed values set, append, insert, remove, and clear. The transaction validates and reads back the new identity, returns it in gamePrefab, and includes previousId when the identity changed.

The update snapshots wrapper and meta bytes before mutation. A successful commit returns terminalState="committed" with SHA-256 commit evidence. On failure, same-directory atomic replacement restores the baseline, Unity imports it synchronously, and byte plus semantic readback must both pass before the tool returns terminalState="rolled_back". Restoration failure is reported as rollback_failed with the original and rollback errors kept separately.

Configuration

Effective defaults use this order:

1. explicit tool argument;

2. Project Settings > VMFramework MCP;

3. Preferences > VMFramework MCP or the shared Preferences > Unity MCP result budget;

4. package default.

ProjectSettings/VMFrameworkMCPSettings.json is team-owned and contains only the GameTag validation coverage contract:

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

Preferences > VMFramework MCP contains operator response choices: GamePrefab inspection depth, per-collection item budget, optional update snapshots, and the retained property-trace capacity.

Single-primary-collection tools reuse the optional result-limit override under Preferences > Unity MCP > Tool Responses. VMFramework MCP does not duplicate that preference.

Large or nondeterministic details stay request-owned and default off:

• includeGamePrefabDetails;

• includeRuntime;

• includeValid;

• includeLocalizations;

• includeSnapshots;

• includeValidation on upsert-game-tag.

GamePrefab config-query projections are also request-owned through fields; localized projections include every table locale unless locales narrows them.

See Documentation~/configuration.md for the per-tool ownership audit and response rules.

Development

Run the package's EditMode tests through the advertised unity_testing_run_package_tests tool or filter Unity Test Runner by VMFrameworkMCP.FullRegression. The regression suite verifies the exact VMFramework catalog, direct routes, operation metadata, strict schemas, settings round-tripping, and GamePrefab/GameTag conversion behavior.

This package contains no runtime assembly.