coplaydev--unity-mcp/docs/wiki/V10.md

# MCP for Unity v10 Release Notes

These notes cover v10: the full major-version change from
v9.0.0, the new AI asset generation/import surface, secure provider-key storage,
Blender/local-file handoff, and the README/docs/brand refresh.

For this comparison, **v9 means `v9.0.0`**, not the last v9 patch. The `v9.7.3`
tag is still useful for the release-to-release changelog, but it already
contains much of the v9 tool expansion.

## What changed since v9.0.0

At `v9.0.0`, MCP for Unity exposed 29 MCP tool entrypoints around the core Unity
Editor loop: scenes, GameObjects, components, scripts, prefabs, assets,
materials, shaders, VFX, console reads, editor refresh, async tests, custom
tools, and batch execution.

The v10 release exposes 47 MCP tool entrypoints across 10 groups:
`core`, `animation`, `asset_gen`, `docs`, `probuilder`, `profiling`,
`scripting_ext`, `testing`, `ui`, and `vfx`.

| Area | `v9.0.0` baseline | v10 release |
| --- | --- | --- |
| Tool catalog | 29 MCP tool entrypoints, with most tools registered directly into one visible surface. | 47 MCP tool entrypoints across grouped domains. |
| Tool visibility | No decorator-level group metadata and no `manage_tools` workflow for user-controlled visibility. | Tool registry has named groups; `core` is enabled by default and non-core groups are opt-in. |
| Editor automation domains | Core scene/object/component/script/asset/prefab/material/shader/VFX/test/editor operations. | Adds build orchestration, camera/Cinemachine control, render pipeline and graphics operations, package management, physics, animation, UI Toolkit, profiling, ProBuilder, and procedural texture generation. |
| Asset creation/import | Existing asset management and VFX/shader/script tools could create or modify project content, but external generation providers were not part of the product surface. | Adds the `asset_gen` group for Tripo/Meshy model generation, fal.ai/OpenRouter image generation, Sketchfab import, and local FBX/OBJ/glTF handoff from tools such as Blender. |
| API lookup and docs | API discovery depended on external docs or local project inspection. | Adds `unity_docs` and `unity_reflect`, plus generated tool/resource reference docs. |
| Safety model | Core tool execution, custom tools, async test polling, and instance routing were present. | Adds group-gated high-power tools, secure provider-key storage in Unity, project-scoped import hardening, archive/path validation, and more test coverage around transport, tool registry, provider adapters, and Unity compatibility. |
| Editor UI and docs | The window focused on connection/client setup and the docs grew around accumulated features. | Adds tool/resource visibility flows, Asset Gen setup, glTFast dependency guidance, refreshed README/docs navigation, icons/social assets, and consistent "MCP for Unity" product naming. |

Added MCP tool entrypoints since `v9.0.0`: `execute_code`,
`generate_image`, `generate_model`, `import_model`, `import_model_file`,
`manage_animation`, `manage_build`, `manage_camera`, `manage_graphics`,
`manage_packages`, `manage_physics`, `manage_probuilder`, `manage_profiler`,
`manage_texture`, `manage_tools`, `manage_ui`, `unity_docs`, and
`unity_reflect`.

## What v10 is about

1. **A larger grouped tool surface** - the catalog grows from 29 to 47 MCP tool
   entrypoints, with high-power domains split into opt-in groups.
2. **Asset generation and import** - first-class MCP tools for generating 3D
   models, generating 2D images, importing marketplace models, and handing off
   local files from tools like Blender.
3. **Safer agent operations** - provider keys stay in the Unity Editor, tools
   are opt-in by group, long-running jobs are explicit and pollable, and file
   writes are constrained to project assets.
4. **Clearer product surface** - refreshed README, docs site, branding, and
   distribution metadata.
5. **Release confidence** - Python tests, Unity compile checks, docs builds, and
   compatibility shims for the wide Unity support window.

## AI Asset Generation

The headline v10 feature is the new `asset_gen` tool group. It is disabled by
default like other non-core tool groups, and can be enabled with `manage_tools`.

| Tool | Purpose |
| --- | --- |
| `generate_model` | Generate 3D models from text or image prompts through providers such as Tripo and Meshy. |
| `generate_image` | Generate 2D images through providers such as fal.ai and OpenRouter. |
| `import_model` | Search and import downloadable Sketchfab models. |
| `import_model_file` | Import a local model file already on disk, such as an FBX/OBJ/glTF exported from Blender. |

Generation and import jobs are asynchronous. A request returns a `job_id`, and
the client polls `action="status"` until the job completes or fails.

### Providers

- 3D generation: Tripo (default) and Meshy.
- 3D import: Sketchfab.
- 2D image generation: fal.ai (default) and OpenRouter.

### Setup

1. Open **Window > MCP for Unity > Asset Gen** and enter provider API keys.
2. Enable the tools with `manage_tools`; the `asset_gen` group is off by
   default.
3. Install **glTFast** from the Dependencies tab for GLB output/import. FBX
   import does not require glTFast.

Provider keys are stored in the OS secure store and are not written to project
assets or `EditorPrefs`.

### Usage examples

Generation runs through MCP tools or the `asset-gen` CLI, not from the Unity
GUI. Long-running jobs return a `job_id`; call `action="status"` with that
`job_id` until the job completes.

```text
generate_model action=generate provider=tripo mode=text prompt="a low-poly oak tree" format=fbx
generate_model action=generate provider=meshy mode=image image_path=Assets/refs/chair.png
generate_image action=generate provider=fal mode=text prompt="a pixel-art coin"
import_model action=search query="wooden chair"
import_model action=import uid=<uid from search>
```

### Provider caveats

- `image_url` points at a hosted image.
- `image_path` points at a local file, commonly under `Assets/`.
- Meshy image-to-3D and fal/OpenRouter image-to-image support local
  `image_path` inputs by sending the image inline as a base64 data URI.
- Tripo image-to-3D currently needs a hosted `image_url`.
- `transparent` sets the Unity texture import flag only; fal/FLUX does not
  provide transparent-background generation.
- `width` and `height` are forwarded to fal; OpenRouter's chat API has no size
  control.

## Provider keys

Asset providers are bring-your-own-key. Keys are entered in the Unity Editor's
Asset Gen tab and stored in the operating system secure store:

- macOS: Keychain
- Windows: Credential Manager
- Linux: libsecret / Secret Service compatible tooling

Keys are not written to project assets, `EditorPrefs`, generated docs, or MCP
tool parameters. The MCP client can request a generation job, but it does not
receive provider credentials.

## Local image inputs

v10 distinguishes hosted image inputs from local project images:

- `image_url` points at an externally hosted image.
- `image_path` points at a local file, commonly under `Assets/`.

Meshy image-to-3D and fal/OpenRouter image-to-image can accept local image files
by sending the image data inline as a base64 data URI. Tripo image-to-3D still
requires a hosted `image_url` until an upload flow is wired.

## Blender handoff

The `import_model_file` tool creates a clean boundary between DCC generation and
Unity import:

1. The modeling tool creates or exports the asset.
2. MCP for Unity imports the file with `import_model_file`.
3. The Unity agent uses existing scene, material, prefab, and build tools to wire
   the asset into the project.

With BlenderMCP connected, a modeling workflow can export the current Blender
model and import it through `import_model_file` (FBX by default). BlenderMCP
handles modeling or generation; MCP for Unity handles import and scene
placement. The Asset Gen tab shows a best-effort "Blender app detected" status,
but BlenderMCP itself is configured in the AI client and is not detectable from
Unity.

This is a handoff, not MCP for Unity controlling Blender directly.

## Safety model

### Opt-in tool group

`asset_gen` is not part of the default core tool set. Users must explicitly
enable it with `manage_tools`.

### Project-scoped imports

Generated and imported assets resolve into the Unity project's `Assets/` folder,
with traversal and unsafe paths rejected. Archives are extracted through
allowlisted import paths and extensions rather than blindly writing every file
a provider returns.

### No hidden spend

Generation calls go to third-party providers using the user's own API keys.

- MCP for Unity does not bundle provider credits.
- Provider pricing, rate limits, and content policies are controlled by the
  provider.
- Enable the tool group only when you intend to call generation or import
  providers.

## Docs and brand refresh

v10 also updates the project front door:

- README trimmed into a clearer front door.
- Docs site reorganized around Getting Started, Guides, Reference,
  Architecture, Contributing, Migrations, and Releases.
- Tool reference pages are generated from the tool registry.
- Distribution and analytics docs are explicit about what is measured and what
  is not.
- Branding now consistently uses **MCP for Unity** in user-facing UI and docs.

## Compatibility posture

v10 continues the existing compatibility promise:

- Unity 2021.3 LTS remains the package floor.
- Unity 6.x stays in the supported matrix.
- Known Unity API changes route through compatibility helpers under
  `MCPForUnity/Runtime/Helpers/`.
- Contributors touching shims or version-gated APIs run
  `tools/check-unity-versions.sh` against installed Unity Hub editors.

## Upgrade notes from v9

1. Update the Unity package to v10. Use the `main` branch for the latest stable
   release, or pin `v10.0.0` when you need this exact release. Use `beta` only
   for post-v10 preview builds.
2. Reconfigure MCP clients if the package prompts you to.
3. Install optional dependencies only when needed. GLB import uses glTFast; FBX
   import does not require that package.
4. Enable `asset_gen` explicitly with `manage_tools` before calling asset
   generation tools.
5. Add provider keys in Unity, not in MCP client config files.
6. Keep generated assets under review before committing them.

## What is intentionally not in v10

- No hosted MCP for Unity asset-generation credits.
- No guarantee that every provider supports every input mode.
- No automatic BlenderMCP configuration from Unity.
- No promise that provider-generated assets are production-ready without artist
  review.
- No change to the rule that non-core tool groups start disabled.

## Final comparison

**Major-version comparison**: https://github.com/CoplayDev/unity-mcp/compare/v9.0.0...v10.0.0

**v9.7.3 patch comparison**: https://github.com/CoplayDev/unity-mcp/compare/v9.7.3...v10.0.0

## Troubleshooting

### `asset_gen` tools do not appear

The `asset_gen` group is disabled by default. Enable it with `manage_tools`:

```text
manage_tools action=activate group=asset_gen
```

If the tools still do not appear, refresh/reconnect the MCP server in the client.
Some clients cache tool lists until the server is restarted or refreshed.

### Provider key missing

Generation providers are bring-your-own-key. Add keys in Unity's **Asset Gen**
tab. Do not place provider keys in MCP client config files, prompts, project
assets, or generated docs.

### GLB import fails or has missing geometry/materials

GLB/glTF import depends on **glTFast**. Install it from the Dependencies tab or
via Package Manager before importing GLB assets. FBX imports do not require
glTFast.

### Tripo image-to-3D rejects `image_path`

Tripo image-to-3D currently needs a hosted `image_url`. Local `image_path` inputs
are supported by Meshy image-to-3D and fal/OpenRouter image-to-image, where the
image can be sent inline as a base64 data URI.

### Generated or imported files are larger than expected

Provider output can include large binary assets. Review generated files before
committing them, keep generated output under `Assets/Generated/` when possible,
and avoid committing experimental provider output that is not needed by the
project.

### Archive import is rejected

Archive extraction is intentionally constrained. Provider archives may be
rejected when they contain unsupported extensions, traversal paths, scripts, or
files outside the import allowlist. Import the model again with a supported
format or inspect the archive before bringing it into the Unity project.

## Related docs

- Tool groups: https://coplaydev.github.io/unity-mcp/guides/tool-groups
- Asset generation tools: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/
- generate_model: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/generate_model
- generate_image: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/generate_image
- import_model: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/import_model
- import_model_file: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/import_model_file
- Tool reference: https://coplaydev.github.io/unity-mcp/reference/tools/
- Unity compatibility shims: https://coplaydev.github.io/unity-mcp/architecture/unity-compat
- Project roadmap: https://coplaydev.github.io/unity-mcp/architecture/project-roadmap