dcc-mcp-unity 0.2.0__tar.gz

dcc_mcp_unity-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage

dcc_mcp_unity-0.2.0/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.2.0"}

dcc_mcp_unity-0.2.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.2.0](https://github.com/dcc-mcp/dcc-mcp-unity/compare/v0.1.0...v0.2.0) (2026-07-21)
+
+
+### Features
+
+* add Unity Editor MCP adapter ([5595603](https://github.com/dcc-mcp/dcc-mcp-unity/commit/55956032b33643df8deaf229f131b9d2378891aa))
+
+## Changelog

dcc_mcp_unity-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loonghao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dcc_mcp_unity-0.2.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: dcc-mcp-unity
+Version: 0.2.0
+Summary: Unity Editor adapter and typed game-authoring skills for DCC-MCP
+Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-unity
+Project-URL: Repository, https://github.com/dcc-mcp/dcc-mcp-unity
+Project-URL: Issues, https://github.com/dcc-mcp/dcc-mcp-unity/issues
+Author-email: loonghao <hal.long@outlook.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,game-development,mcp,model-context-protocol,unity
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.9
+Requires-Dist: dcc-mcp-core<1.0.0,>=0.19.45
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dcc-mcp-unity
+
+![DCC-MCP Unity lockup](https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-unity/main/docs/assets/dcc-mcp-unity.svg)
+
+Unity Editor adapter for the DCC Model Context Protocol ecosystem. It ships a UPM Editor package,
+a loopback WebSocket bridge, and typed project and scene tools.
+
+The first-release boundary and comparison with `unity-cli` and two established Unity MCP projects
+are documented in the [architecture benchmark](https://github.com/dcc-mcp/dcc-mcp-unity/blob/main/docs/architecture-benchmark.md).
+
+## Install
+
+```bash
+pip install dcc-mcp-unity
+dcc-mcp-unity-install /path/to/UnityProject
+```
+
+Open or restart the Unity project so Package Manager compiles **DCC-MCP Unity**, then run:
+
+```bash
+dcc-mcp-unity
+```
+
+See the [installation guide](https://github.com/dcc-mcp/dcc-mcp-unity/blob/main/install.md) for
+upgrade, environment, and connection verification details.
+
+The MCP endpoint uses a free loopback port and is registered for gateway discovery. Set
+`DCC_MCP_UNITY_PORT=8765` before starting the server only when a fixed direct endpoint is needed.
+The Editor package reconnects to the loopback bridge at `ws://127.0.0.1:3852`; set
+`DCC_MCP_UNITY_BRIDGE_PORT` before the MCP server and `DCC_MCP_UNITY_BRIDGE_URL` before Unity starts
+to override it. `DCC_MCP_UNITY_BRIDGE_TIMEOUT` may increase the 60-second RPC timeout but cannot
+lower it; queued Editor work expires first so timed-out mutations are not executed later.
+
+The default bridge targets one Unity Editor. For concurrent Editors, run one adapter per Editor and
+assign each pair a unique bridge port and URL before starting either process.
+
+## Agent workflow
+
+1. Load `unity-project` and call `inspect_project` before assuming project or editor state. Stop if
+   the returned project is not the intended target or the Editor is compiling, updating, entering
+   Play Mode, or playing.
+2. Load `unity-scene` and call `inspect_scene` immediately before using an instance ID.
+3. Create GameObjects or change transforms through typed operations backed by Unity Undo.
+4. Verify the hierarchy, then explicitly call `save_scene`.
+5. Load `unity-diagnostics` and call `read_console` after failures or as a final verification step.
+
+Do not automatically retry a timed-out scene mutation. Inspect the project and scene first because
+the Editor may have completed the original request near the timeout boundary.
+
+No raw C# evaluation, shell command, or arbitrary filesystem write is exposed. The Editor bridge
+accepts only the methods implemented in `DccMcpCommands` and executes them on Unity's editor update
+loop. Mutations fail closed during compilation, asset updates, and Play Mode. Requests, queued work,
+scene snapshots, Console reads, and serialized responses have explicit size or lifetime budgets.
+
+## Validation boundary
+
+Public CI validates Python 3.9 and 3.12 on Windows, macOS, and Linux; validates the bundled skill
+contracts; performs static checks for the UPM package and main-thread/Undo contracts; and builds the
+PyPI artifacts. Automated live Unity Editor CI is intentionally not claimed because it requires a
+provisioned Unity CI license or activation. A real Editor smoke should be run before promoting the
+adapter from alpha.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run python -m pytest
+uv run ruff check src tests tools
+uv run ruff format --check src tests tools
+uv run python tools/lint_skills.py
+uv run python -m build
+uv run python -m twine check dist/*
+```
+
+Unity and the Unity cube logo are trademarks of Unity Technologies. This independent adapter is
+not affiliated with or endorsed by Unity Technologies.

dcc_mcp_unity-0.2.0/README.md

@@ -0,0 +1,76 @@
+# dcc-mcp-unity
+
+![DCC-MCP Unity lockup](https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-unity/main/docs/assets/dcc-mcp-unity.svg)
+
+Unity Editor adapter for the DCC Model Context Protocol ecosystem. It ships a UPM Editor package,
+a loopback WebSocket bridge, and typed project and scene tools.
+
+The first-release boundary and comparison with `unity-cli` and two established Unity MCP projects
+are documented in the [architecture benchmark](https://github.com/dcc-mcp/dcc-mcp-unity/blob/main/docs/architecture-benchmark.md).
+
+## Install
+
+```bash
+pip install dcc-mcp-unity
+dcc-mcp-unity-install /path/to/UnityProject
+```
+
+Open or restart the Unity project so Package Manager compiles **DCC-MCP Unity**, then run:
+
+```bash
+dcc-mcp-unity
+```
+
+See the [installation guide](https://github.com/dcc-mcp/dcc-mcp-unity/blob/main/install.md) for
+upgrade, environment, and connection verification details.
+
+The MCP endpoint uses a free loopback port and is registered for gateway discovery. Set
+`DCC_MCP_UNITY_PORT=8765` before starting the server only when a fixed direct endpoint is needed.
+The Editor package reconnects to the loopback bridge at `ws://127.0.0.1:3852`; set
+`DCC_MCP_UNITY_BRIDGE_PORT` before the MCP server and `DCC_MCP_UNITY_BRIDGE_URL` before Unity starts
+to override it. `DCC_MCP_UNITY_BRIDGE_TIMEOUT` may increase the 60-second RPC timeout but cannot
+lower it; queued Editor work expires first so timed-out mutations are not executed later.
+
+The default bridge targets one Unity Editor. For concurrent Editors, run one adapter per Editor and
+assign each pair a unique bridge port and URL before starting either process.
+
+## Agent workflow
+
+1. Load `unity-project` and call `inspect_project` before assuming project or editor state. Stop if
+   the returned project is not the intended target or the Editor is compiling, updating, entering
+   Play Mode, or playing.
+2. Load `unity-scene` and call `inspect_scene` immediately before using an instance ID.
+3. Create GameObjects or change transforms through typed operations backed by Unity Undo.
+4. Verify the hierarchy, then explicitly call `save_scene`.
+5. Load `unity-diagnostics` and call `read_console` after failures or as a final verification step.
+
+Do not automatically retry a timed-out scene mutation. Inspect the project and scene first because
+the Editor may have completed the original request near the timeout boundary.
+
+No raw C# evaluation, shell command, or arbitrary filesystem write is exposed. The Editor bridge
+accepts only the methods implemented in `DccMcpCommands` and executes them on Unity's editor update
+loop. Mutations fail closed during compilation, asset updates, and Play Mode. Requests, queued work,
+scene snapshots, Console reads, and serialized responses have explicit size or lifetime budgets.
+
+## Validation boundary
+
+Public CI validates Python 3.9 and 3.12 on Windows, macOS, and Linux; validates the bundled skill
+contracts; performs static checks for the UPM package and main-thread/Undo contracts; and builds the
+PyPI artifacts. Automated live Unity Editor CI is intentionally not claimed because it requires a
+provisioned Unity CI license or activation. A real Editor smoke should be run before promoting the
+adapter from alpha.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run python -m pytest
+uv run ruff check src tests tools
+uv run ruff format --check src tests tools
+uv run python tools/lint_skills.py
+uv run python -m build
+uv run python -m twine check dist/*
+```
+
+Unity and the Unity cube logo are trademarks of Unity Technologies. This independent adapter is
+not affiliated with or endorsed by Unity Technologies.

dcc_mcp_unity-0.2.0/docs/architecture-benchmark.md

@@ -0,0 +1,88 @@
+# Unity automation architecture benchmark
+
+This adapter was reviewed against pinned versions of three Unity automation projects before its first public
+release. The comparison is about architecture and contracts; no third-party source code is bundled
+or copied into this repository.
+
+## Source snapshots
+
+| Project | Snapshot | Primary role | License |
+| --- | --- | --- | --- |
+| [RageAgainstThePixel/unity-cli](https://github.com/RageAgainstThePixel/unity-cli/tree/c4f45b952c3e23beadfb442fc4c6d5920402c217) | `c4f45b9`, CLI 3.0.1 | Hub, Editor, license, project, batch, build, and UPM lifecycle automation | [MIT](https://github.com/RageAgainstThePixel/unity-cli/blob/c4f45b952c3e23beadfb442fc4c6d5920402c217/LICENSE) |
+| [CoplayDev/unity-mcp](https://github.com/CoplayDev/unity-mcp/tree/c14de1e6dc01ab42d2bb358730cff954bce0ce6b) | `c14de1e`, 10.1.0 | Python MCP server plus Unity Editor plugin and broad authoring tools | [MIT](https://github.com/CoplayDev/unity-mcp/blob/c14de1e6dc01ab42d2bb358730cff954bce0ce6b/LICENSE) |
+| [IvanMurzak/Unity-MCP](https://github.com/IvanMurzak/Unity-MCP/tree/73086e74924efc7ebf4430d3b4fa1ae44d49adaa) | `73086e7`, 0.86.0 | Editor/runtime plugin and CLI communicating with an external C# MCP server over SignalR | [Apache-2.0](https://github.com/IvanMurzak/Unity-MCP/blob/73086e74924efc7ebf4430d3b4fa1ae44d49adaa/LICENSE) |
+
+## Product boundary
+
+The projects solve two different automation planes. DCC-MCP Unity keeps them separate:
+
+```mermaid
+flowchart LR
+    A["Agent / DCC-MCP gateway"] --> B["Typed live Editor adapter"]
+    B --> C["Loopback WebSocket"]
+    C --> D["Unity Editor main thread"]
+    A -. "future approved jobs" .-> E["Optional Unity toolchain backend"]
+    E -. "fixed argv only" .-> F["unity-cli / Unity batch mode"]
+```
+
+- The live plane owns low-latency inspection and undoable Editor authoring.
+- A future toolchain plane may own project creation, compile, test, and build jobs.
+- Hub installation, license management, arbitrary Editor arguments, and credentials are not normal
+  MCP tools.
+
+## Decisions adopted for the first release
+
+1. **Explicit commands, not ambient code execution.** The Editor package accepts a fixed method
+   allowlist. It does not expose arbitrary C#, reflection calls, menu execution, shell commands, or
+   unconstrained file writes.
+2. **One main-thread boundary.** WebSocket I/O is asynchronous; commands enter through a bounded
+   queue and run from `EditorApplication.update`.
+3. **Fail-closed mutation lifecycle.** Each undoable GameObject mutation has its own Undo group and
+   rolls back on failure. Mutations are rejected during compile, asset update, and Play Mode.
+4. **Bounded transport and output.** Incoming messages, pending requests, queue lifetime, scene
+   snapshots, vector values, and captured Console output all have explicit limits.
+5. **Target evidence.** The bridge handshake includes product name, project path/hash, Unity version, process
+   ID, and a session ID stable across domain reloads. Agents inspect the project before mutation.
+6. **Diagnostic loop.** Project inspection reports Editor readiness, and `editor.read_console`
+   provides a bounded read-only view of messages captured after package load.
+7. **Version preflight.** The installer reads `ProjectSettings/ProjectVersion.txt` and rejects Unity
+   versions older than 2021.3 before changing the project.
+8. **No blind mutation retry.** A timeout is ambiguous: Unity may have completed work near the
+   boundary. The workflow requires project and scene inspection before deciding what to do next.
+
+## Deferred extensions
+
+- Add a separate optional backend for a pinned `unity-cli` version. It must use fixed argument
+  arrays, `shell=False`, bounded output and timeouts, credential redaction, and explicit approval for
+  project creation, compile, test, build, or GUI launch.
+- Add core-supported multi-instance routing keyed by project hash and session ID. Until then,
+  concurrent Editors use one adapter and a unique bridge port/URL pair per Editor.
+- Add `tests.run`, build, package, and other cross-domain-reload operations only with a persistent
+  job protocol (`request_id`, processing state, reconnect, completion, cancellation).
+- Add licensed Unity CI for the minimum supported 2021.3 release and a Unity 6 release. Static CI is
+  not presented as live Editor proof.
+- Expand authoring in bounded vertical slices: tests/build first, then carefully typed components,
+  prefabs, materials, and assets.
+
+## Capabilities intentionally rejected
+
+- Runtime compilation or execution of arbitrary C#.
+- Calling arbitrary public or private methods through reflection.
+- Generic object patching with an unconstrained type/property surface.
+- Arbitrary `unity-cli run`, Unity Hub, menu item, or package URL passthrough.
+- License and service-account credentials supplied as model arguments.
+- Automatic retry of non-idempotent scene mutations.
+- Cloud identity, telemetry, asset-generation providers, or third-party secret stores in the core
+  adapter.
+
+## Evidence consulted
+
+- `unity-cli` separates project/version detection and Editor execution, uses argument arrays with
+  `shell: false`, and maintains real Unity integration workflows: [project parser](https://github.com/RageAgainstThePixel/unity-cli/blob/c4f45b952c3e23beadfb442fc4c6d5920402c217/src/unity-project.ts#L61-L97), [process execution](https://github.com/RageAgainstThePixel/unity-cli/blob/c4f45b952c3e23beadfb442fc4c6d5920402c217/src/utilities.ts#L167-L293), [integration workflow](https://github.com/RageAgainstThePixel/unity-cli/blob/c4f45b952c3e23beadfb442fc4c6d5920402c217/.github/workflows/integration-tests.yml#L1-L74).
+- Coplay uses project hashes for instance routing, keeps the active instance per MCP session,
+  dispatches Editor work through a main-thread queue, and provides a large tool catalog; it also
+  exposes optional arbitrary C# that is explicitly not a sandbox: [instance middleware](https://github.com/CoplayDev/unity-mcp/blob/c14de1e6dc01ab42d2bb358730cff954bce0ce6b/Server/src/transport/unity_instance_middleware.py#L50-L95), [dispatcher](https://github.com/CoplayDev/unity-mcp/blob/c14de1e6dc01ab42d2bb358730cff954bce0ce6b/MCPForUnity/Editor/Services/Transport/TransportCommandDispatcher.cs#L70-L194), [execute-code warning](https://github.com/CoplayDev/unity-mcp/blob/c14de1e6dc01ab42d2bb358730cff954bce0ce6b/Server/src/services/tools/execute_code.py#L1-L9).
+- Ivan Murzak's implementation uses stable project/session identity and main-thread dispatch. Its
+  dynamic script execution and reflection-backed capabilities give it a broader operation surface
+  than this adapter's fixed allowlist:
+  [architecture](https://github.com/IvanMurzak/Unity-MCP/blob/73086e74924efc7ebf4430d3b4fa1ae44d49adaa/docs/claude/architecture.md#L3-L15), [instance identity](https://github.com/IvanMurzak/Unity-MCP/blob/73086e74924efc7ebf4430d3b4fa1ae44d49adaa/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/Services/ProjectInstanceService.cs#L53-L106), [dynamic script execution](https://github.com/IvanMurzak/Unity-MCP/blob/73086e74924efc7ebf4430d3b4fa1ae44d49adaa/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/API/Tool/Script.Execute.cs#L244-L310).

dcc_mcp_unity-0.2.0/docs/assets/SOURCES.md

@@ -0,0 +1,13 @@
+# Brand asset sources
+
+- Shared DCC-MCP master: approved DCC-MCP brand master.
+- Unity identity: exact approved Unity cube asset, checked against the
+  [Unity branding and trademarks guidance](https://unity.com/legal/branding-trademarks).
+- Family composition reference: the approved
+  [dcc-mcp-houdini](https://github.com/dcc-mcp/dcc-mcp-houdini) README lockup.
+- `dcc-mcp-unity-imagegen-source.png`: preserved ImageGen source used for the
+  Unity Scene-view composition.
+- `dcc-mcp-unity.png`: approved 1200×560 raster. The exact Unity identity asset
+  was composited over the generated identity region before approval.
+- `dcc-mcp-unity.svg`: self-contained SVG wrapper around the approved raster;
+  it is not a native vector redraw.