# VMFramework MCP

VMFramework MCP is an Editor-only Unity package that adds VMFramework-aware
project tools to [VM Unity MCP](https://github.com/VM233/VMUnityMCP). 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](https://github.com/VM233/unity-mcp-server#installation),
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](https://github.com/VM233/VMFramework#installation)
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:

```text
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`:

```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.

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

```json
{
  "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:

```json
{
  "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](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.