dcc-mcp-unity 0.2.0__py3-none-any.whl

dcc_mcp_unity/__init__.py

@@ -0,0 +1,6 @@
+"""Unity Editor adapter for DCC-MCP."""
+
+from .__version__ import __version__
+from .server import UnityMcpServer
+
+__all__ = ["UnityMcpServer", "__version__"]

dcc_mcp_unity/__version__.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.2.0"  # x-release-please-version

dcc_mcp_unity/bridge.py

@@ -0,0 +1,64 @@
+"""Loopback WebSocket bridge shared by the MCP server and Unity package."""
+
+from __future__ import annotations
+
+import math
+import os
+import threading
+import time
+from typing import Any
+
+from dcc_mcp_core.bridge import DccBridge
+
+_bridge: DccBridge | None = None
+_lock = threading.Lock()
+_HOST_REQUEST_LIFETIME_SECONDS = 55
+
+
+def _bridge_timeout() -> float:
+    value = float(os.environ.get("DCC_MCP_UNITY_BRIDGE_TIMEOUT", "60"))
+    if not math.isfinite(value) or value < 60:
+        raise ValueError(
+            "DCC_MCP_UNITY_BRIDGE_TIMEOUT must be a finite value of at least 60 seconds"
+        )
+    return value
+
+
+def get_bridge() -> DccBridge:
+    """Return the process-wide bridge, creating it without starting it."""
+    global _bridge
+    with _lock:
+        if _bridge is None:
+            port = int(os.environ.get("DCC_MCP_UNITY_BRIDGE_PORT", "3852"))
+            _bridge = DccBridge(
+                host="127.0.0.1",
+                port=port,
+                timeout=_bridge_timeout(),
+                server_name="dcc-mcp-unity",
+            )
+            os.environ.setdefault("DCC_MCP_UNITY_BRIDGE_URL", f"ws://127.0.0.1:{port}")
+        return _bridge
+
+
+def start_bridge() -> DccBridge:
+    bridge = get_bridge()
+    bridge.connect(wait_for_dcc=False)
+    return bridge
+
+
+def stop_bridge() -> None:
+    global _bridge
+    with _lock:
+        bridge, _bridge = _bridge, None
+    if bridge is not None:
+        bridge.disconnect()
+
+
+def call_host(method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Invoke one typed command in the connected Unity Editor."""
+    request_params = dict(params or {})
+    request_params["_dcc_mcp_deadline_unix_ms"] = int(
+        (time.time() + _HOST_REQUEST_LIFETIME_SECONDS) * 1000
+    )
+    result = get_bridge().call(method, **request_params)
+    return result if isinstance(result, dict) else {"value": result}

dcc_mcp_unity/dispatcher.py

@@ -0,0 +1,21 @@
+"""In-process skill dispatcher for the external Unity Editor bridge."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class UnityBridgeDispatcher:
+    """Run Python wrappers inline; Unity performs host work on its editor update loop."""
+
+    def dispatch_callable(self, func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        for key in (
+            "affinity",
+            "context",
+            "action_name",
+            "skill_name",
+            "execution",
+            "timeout_hint_secs",
+        ):
+            kwargs.pop(key, None)
+        return func(*args, **kwargs)

dcc_mcp_unity/install.py

@@ -0,0 +1,67 @@
+"""Install the bundled UPM package into a Unity project."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+from pathlib import Path
+
+PACKAGE_NAME = "com.dcc-mcp.unity"
+MIN_UNITY_VERSION = (2021, 3)
+_EDITOR_VERSION_PATTERN = re.compile(r"^m_EditorVersion:\s*(\S+)\s*$", re.MULTILINE)
+
+
+def read_unity_version(project: Path) -> str:
+    """Return the exact Editor version recorded by a Unity project."""
+    version_file = project / "ProjectSettings" / "ProjectVersion.txt"
+    try:
+        contents = version_file.read_text(encoding="utf-8-sig")
+    except OSError as exc:
+        raise ValueError(f"Unity project version file is unavailable: {version_file}") from exc
+
+    match = _EDITOR_VERSION_PATTERN.search(contents)
+    if match is None:
+        raise ValueError(f"Unity project version is missing from: {version_file}")
+    return match.group(1)
+
+
+def _require_supported_unity_version(version: str) -> None:
+    match = re.match(r"^(\d+)\.(\d+)", version)
+    if match is None:
+        raise ValueError(f"unsupported Unity version format: {version}")
+    parsed = (int(match.group(1)), int(match.group(2)))
+    if parsed < MIN_UNITY_VERSION:
+        raise ValueError(
+            f"Unity {version} is unsupported; DCC-MCP Unity requires Unity 2021.3 or newer"
+        )
+
+
+def install_package(project: Path, *, overwrite: bool = False) -> Path:
+    """Copy the bundled package below the target project's Packages directory."""
+    project = project.resolve()
+    if not (project / "Assets").is_dir() or not (project / "ProjectSettings").is_dir():
+        raise ValueError(f"not a Unity project: {project}")
+    _require_supported_unity_version(read_unity_version(project))
+
+    source = Path(__file__).resolve().parent / "unity_package"
+    target = project / "Packages" / PACKAGE_NAME
+    if target.exists():
+        if not overwrite:
+            raise FileExistsError(f"package already exists: {target}")
+        shutil.rmtree(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(source, target)
+    return target
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Install DCC-MCP Unity into a Unity project.")
+    parser.add_argument("project", type=Path)
+    parser.add_argument("--overwrite", action="store_true")
+    args = parser.parse_args()
+    print(install_package(args.project, overwrite=args.overwrite))
+
+
+if __name__ == "__main__":
+    main()

dcc_mcp_unity/server.py

@@ -0,0 +1,101 @@
+"""Unity MCP server composition and lifecycle."""
+
+from __future__ import annotations
+
+import os
+import signal
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+from dcc_mcp_core import DccServerOptions, HostExecutionBridge
+from dcc_mcp_core.host import QueueDispatcher, StandaloneHost
+from dcc_mcp_core.server_base import DccServerBase
+
+from .__version__ import __version__
+from .bridge import start_bridge, stop_bridge
+from .dispatcher import UnityBridgeDispatcher
+
+_server: Optional["UnityMcpServer"] = None
+
+
+class UnityMcpServer(DccServerBase):
+    """DCC-MCP server backed by the bundled Unity Editor package."""
+
+    def __init__(self, port: Optional[int] = None) -> None:
+        self._host_dispatcher = QueueDispatcher()
+        self._host_driver = StandaloneHost(
+            self._host_dispatcher,
+            thread_name="dcc-mcp-unity-host",
+        )
+        execution_bridge = HostExecutionBridge(
+            dispatcher=UnityBridgeDispatcher(),
+            host_dispatcher=self._host_dispatcher,
+            default_thread_affinity="main",
+            default_execution="sync",
+            default_timeout_hint_secs=60,
+        )
+        options = DccServerOptions.from_env(
+            "unity",
+            Path(__file__).resolve().parent / "skills",
+            port=port,
+            server_name="dcc-mcp-unity",
+            server_version=__version__,
+            execution_bridge=execution_bridge,
+        )
+        super().__init__(options=options)
+
+    def start(self, **kwargs: Any) -> Any:
+        start_bridge()
+        try:
+            self._host_driver.start()
+            return super().start(**kwargs)
+        except Exception:
+            self._host_driver.stop()
+            stop_bridge()
+            raise
+
+    def stop(self) -> None:
+        try:
+            super().stop()
+        finally:
+            try:
+                self._host_driver.stop()
+            finally:
+                stop_bridge()
+
+    def _version_string(self) -> str:
+        return os.environ.get("DCC_MCP_UNITY_VERSION", "unknown")
+
+
+def start_server(port: Optional[int] = None) -> UnityMcpServer:
+    global _server
+    if _server is None or not _server.is_running:
+        _server = UnityMcpServer(port)
+        _server.register_builtin_actions()
+        _server.start()
+    return _server
+
+
+def stop_server() -> None:
+    global _server
+    if _server is not None:
+        _server.stop()
+        _server = None
+
+
+def main() -> None:
+    """Run the standalone adapter until interrupted."""
+    stopped = threading.Event()
+    signal.signal(signal.SIGINT, lambda *_: stopped.set())
+    if hasattr(signal, "SIGTERM"):
+        signal.signal(signal.SIGTERM, lambda *_: stopped.set())
+    start_server()
+    try:
+        stopped.wait()
+    finally:
+        stop_server()
+
+
+if __name__ == "__main__":
+    main()

dcc_mcp_unity/skills/unity-diagnostics/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: unity-diagnostics
+description: >-
+  Domain skill — Read a bounded snapshot of Unity Console messages captured
+  after the Editor bridge loads. Use to verify operations and diagnose compile,
+  import, or runtime errors. Not for clearing logs or arbitrary Editor access.
+license: MIT
+compatibility: "Unity 2021.3+; dcc-mcp-core 0.19.45+"
+allowed-tools: "python"
+metadata:
+  dcc-mcp:
+    dcc: unity
+    layer: domain
+    version: "0.2.0"  # x-release-please-version
+    search-hint: "Unity Console logs errors warnings stack trace diagnostics"
+    tags: "unity,console,logs,diagnostics,game-development"
+    tools: tools.yaml
+    depends: "dcc-diagnostics"
+---
+
+# Unity Diagnostics
+
+Read the captured Unity Console after an operation or when the Editor reports a failure. Results
+are bounded and may be truncated; increase `limit` up to 200 or narrow by severity when needed.

dcc_mcp_unity/skills/unity-diagnostics/metadata/depends.md

@@ -0,0 +1,3 @@
+# Dependencies
+
+- dcc-diagnostics

dcc_mcp_unity/skills/unity-diagnostics/scripts/read_console.py

@@ -0,0 +1,16 @@
+from dcc_mcp_core.skill import skill_entry, skill_success
+
+from dcc_mcp_unity.bridge import call_host
+
+
+@skill_entry
+def main(limit: int = 100, severity: str = "all", **_kwargs):
+    result = call_host("editor.read_console", {"limit": limit, "severity": severity})
+    count = len(result.get("entries", []))
+    return skill_success(f"Read {count} captured Unity Console entries.", **result)
+
+
+if __name__ == "__main__":
+    from dcc_mcp_core.skill import run_main
+
+    run_main(main)

dcc_mcp_unity/skills/unity-diagnostics/tools.yaml

@@ -0,0 +1,21 @@
+tools:
+  - name: read_console
+    description: Return a bounded, chronological snapshot of Unity Console messages captured since the Editor package loaded. Filter by severity and use after operations or failures. Not for historical logs from before package initialization.
+    input_schema:
+      type: object
+      properties:
+        limit: {type: integer, minimum: 1, maximum: 200, default: 100}
+        severity: {type: string, enum: [all, error, warning, log], default: all}
+      additionalProperties: false
+    output_schema: {type: object}
+    read_only: true
+    destructive: false
+    idempotent: true
+    execution: sync
+    affinity: main
+    enforce_thread_affinity: true
+    timeout_hint_secs: 60
+    source_file: scripts/read_console.py
+    next-tools:
+      on-success: [unity_project__inspect_project, unity_scene__inspect_scene]
+      on-failure: [dcc_diagnostics__screenshot, dcc_diagnostics__audit_log]

dcc_mcp_unity/skills/unity-project/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: unity-project
+description: >-
+  Domain skill — Inspect the open Unity project and refresh its Asset Database.
+  Use for project identity, Unity version, Editor state, active scene, build
+  scenes, and asset import refresh. Not for GameObject edits — use unity-scene.
+license: MIT
+compatibility: "Unity 2021.3+; dcc-mcp-core 0.19.45+"
+allowed-tools: "python"
+metadata:
+  dcc-mcp:
+    dcc: unity
+    layer: domain
+    version: "0.2.0"  # x-release-please-version
+    search-hint: "Unity project version build scenes Asset Database refresh"
+    tags: "unity,project,assets,game-development"
+    tools: tools.yaml
+    depends: "dcc-diagnostics"
+---
+
+# Unity Project
+
+Inspect before assuming the active project, scene, Unity version, or Play/compile state. Asset
+refresh is an explicit mutation because it may import changed files and update generated metadata.
+
+Stop if the returned project path is not the intended target. Do not automatically retry a timed-out
+refresh; inspect the project again first.

dcc_mcp_unity/skills/unity-project/metadata/depends.md

@@ -0,0 +1,3 @@
+# Dependencies
+
+- dcc-diagnostics

dcc_mcp_unity/skills/unity-project/scripts/inspect_project.py

@@ -0,0 +1,14 @@
+from dcc_mcp_core.skill import skill_entry, skill_success
+
+from dcc_mcp_unity.bridge import call_host
+
+
+@skill_entry
+def main(**_kwargs):
+    return skill_success("Unity project inspected.", **call_host("project.inspect"))
+
+
+if __name__ == "__main__":
+    from dcc_mcp_core.skill import run_main
+
+    run_main(main)

dcc_mcp_unity/skills/unity-project/scripts/refresh_assets.py

@@ -0,0 +1,14 @@
+from dcc_mcp_core.skill import skill_entry, skill_success
+
+from dcc_mcp_unity.bridge import call_host
+
+
+@skill_entry
+def main(**_kwargs):
+    return skill_success("Unity assets refreshed.", **call_host("assets.refresh"))
+
+
+if __name__ == "__main__":
+    from dcc_mcp_core.skill import run_main
+
+    run_main(main)

dcc_mcp_unity/skills/unity-project/tools.yaml

@@ -0,0 +1,31 @@
+tools:
+  - name: inspect_project
+    description: Return Unity project identity, editor version and readiness state, active scene, and enabled build scenes. Use before project-sensitive work and stop mutations while Unity reports compiling, updating, or playing. Not for hierarchy inspection; use inspect_scene.
+    input_schema: {type: object, properties: {}, additionalProperties: false}
+    output_schema: {type: object}
+    read_only: true
+    destructive: false
+    idempotent: true
+    execution: sync
+    affinity: main
+    enforce_thread_affinity: true
+    timeout_hint_secs: 60
+    source_file: scripts/inspect_project.py
+    next-tools:
+      on-success: [unity_scene__inspect_scene, unity_project__refresh_assets]
+      on-failure: [dcc_diagnostics__screenshot, dcc_diagnostics__audit_log]
+  - name: refresh_assets
+    description: Ask Unity AssetDatabase to discover and import changed project assets. Use after external file changes. Not for saving scene edits; use save_scene.
+    input_schema: {type: object, properties: {}, additionalProperties: false}
+    output_schema: {type: object}
+    read_only: false
+    destructive: false
+    idempotent: true
+    execution: sync
+    affinity: main
+    enforce_thread_affinity: true
+    timeout_hint_secs: 60
+    source_file: scripts/refresh_assets.py
+    next-tools:
+      on-success: [unity_project__inspect_project]
+      on-failure: [dcc_diagnostics__screenshot, dcc_diagnostics__audit_log]

dcc_mcp_unity/skills/unity-scene/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: unity-scene
+description: >-
+  Domain skill — Inspect and edit the active Unity scene with typed, undoable
+  GameObject operations. Use for hierarchy, object creation, transforms, and
+  scene saves. Not for asset imports — use unity-project.
+license: MIT
+compatibility: "Unity 2021.3+; dcc-mcp-core 0.19.45+"
+allowed-tools: "python"
+metadata:
+  dcc-mcp:
+    dcc: unity
+    layer: domain
+    version: "0.2.0"  # x-release-please-version
+    search-hint: "Unity scene hierarchy GameObject transform save Undo"
+    tags: "unity,scene,gameobject,transform,game-development"
+    tools: tools.yaml
+    depends: "dcc-diagnostics"
+---
+
+# Unity Scene
+
+Inspect the hierarchy immediately before using instance IDs; Unity instance IDs are scoped to the
+current Editor session. Object creation and transform edits register with Unity Undo.
+
+Do not automatically retry a timed-out mutation. Inspect the project and scene first because the
+Editor may have completed the original request near the timeout boundary.

dcc_mcp_unity/skills/unity-scene/metadata/depends.md

@@ -0,0 +1,3 @@
+# Dependencies
+
+- dcc-diagnostics

dcc_mcp_unity/skills/unity-scene/scripts/create_game_object.py

@@ -0,0 +1,18 @@
+from dcc_mcp_core.skill import skill_entry, skill_success
+
+from dcc_mcp_unity.bridge import call_host
+
+
+@skill_entry
+def main(name: str, parent_instance_id: int = 0, **_kwargs):
+    result = call_host(
+        "scene.create_game_object",
+        {"name": name, "parent_instance_id": parent_instance_id},
+    )
+    return skill_success(f"Created Unity GameObject {name}.", **result)
+
+
+if __name__ == "__main__":
+    from dcc_mcp_core.skill import run_main
+
+    run_main(main)

dcc_mcp_unity/skills/unity-scene/scripts/inspect_scene.py

@@ -0,0 +1,15 @@
+from dcc_mcp_core.skill import skill_entry, skill_success
+
+from dcc_mcp_unity.bridge import call_host
+
+
+@skill_entry
+def main(max_nodes: int = 1000, **_kwargs):
+    result = call_host("scene.inspect", {"max_nodes": max_nodes})
+    return skill_success("Unity scene inspected.", **result)
+
+
+if __name__ == "__main__":
+    from dcc_mcp_core.skill import run_main
+
+    run_main(main)

dcc_mcp_unity/skills/unity-scene/scripts/save_scene.py

@@ -0,0 +1,14 @@
+from dcc_mcp_core.skill import skill_entry, skill_success
+
+from dcc_mcp_unity.bridge import call_host
+
+
+@skill_entry
+def main(**_kwargs):
+    return skill_success("Unity scenes saved.", **call_host("scene.save"))
+
+
+if __name__ == "__main__":
+    from dcc_mcp_core.skill import run_main
+
+    run_main(main)

dcc_mcp_unity/skills/unity-scene/scripts/set_transform.py

@@ -0,0 +1,31 @@
+from typing import List, Optional
+
+from dcc_mcp_core.skill import skill_entry, skill_success
+
+from dcc_mcp_unity.bridge import call_host
+
+
+@skill_entry
+def main(
+    instance_id: int,
+    position: Optional[List[float]] = None,
+    rotation_euler: Optional[List[float]] = None,
+    scale: Optional[List[float]] = None,
+    **_kwargs,
+):
+    params = {"instance_id": instance_id}
+    for name, value in (
+        ("position", position),
+        ("rotation_euler", rotation_euler),
+        ("scale", scale),
+    ):
+        if value is not None:
+            params[name] = value
+    result = call_host("scene.set_transform", params)
+    return skill_success(f"Updated Unity transform {instance_id}.", **result)
+
+
+if __name__ == "__main__":
+    from dcc_mcp_core.skill import run_main
+
+    run_main(main)

dcc_mcp_unity/skills/unity-scene/tools.yaml

@@ -0,0 +1,95 @@
+tools:
+  - name: inspect_scene
+    description: Return a bounded active Unity scene hierarchy up to eight levels deep with session-scoped GameObject instance IDs. Use immediately before choosing targets and lower max_nodes for smaller responses. Not for project metadata; use inspect_project.
+    input_schema:
+      type: object
+      properties:
+        max_nodes: {type: integer, minimum: 1, maximum: 5000, default: 1000}
+      additionalProperties: false
+    output_schema: {type: object}
+    read_only: true
+    destructive: false
+    idempotent: true
+    execution: sync
+    affinity: main
+    enforce_thread_affinity: true
+    timeout_hint_secs: 60
+    source_file: scripts/inspect_scene.py
+    next-tools:
+      on-success: [unity_scene__create_game_object, unity_scene__set_transform]
+      on-failure: [dcc_diagnostics__screenshot, dcc_diagnostics__audit_log]
+  - name: create_game_object
+    description: Create one undoable GameObject in the active Unity scene. Use a parent instance ID from a fresh inspect_scene result, or omit it for a scene root. Not for prefab or asset creation.
+    input_schema:
+      type: object
+      required: [name]
+      properties:
+        name: {type: string, minLength: 1, maxLength: 120}
+        parent_instance_id: {type: integer, default: 0}
+      additionalProperties: false
+    output_schema: {type: object}
+    read_only: false
+    destructive: false
+    idempotent: false
+    execution: sync
+    affinity: main
+    enforce_thread_affinity: true
+    timeout_hint_secs: 60
+    source_file: scripts/create_game_object.py
+    next-tools:
+      on-success: [unity_scene__set_transform, unity_scene__save_scene]
+      on-failure: [unity_scene__inspect_scene, dcc_diagnostics__audit_log]
+  - name: set_transform
+    description: Set selected world position, world Euler rotation, or local scale on a Unity GameObject through Undo. Use a session-scoped instance ID from a fresh inspect_scene. Not for RectTransform layout properties.
+    input_schema:
+      type: object
+      required: [instance_id]
+      properties:
+        instance_id: {type: integer}
+        position:
+          type: array
+          items: {type: number}
+          minItems: 3
+          maxItems: 3
+        rotation_euler:
+          type: array
+          items: {type: number}
+          minItems: 3
+          maxItems: 3
+        scale:
+          type: array
+          items: {type: number}
+          minItems: 3
+          maxItems: 3
+      anyOf:
+        - required: [position]
+        - required: [rotation_euler]
+        - required: [scale]
+      additionalProperties: false
+    output_schema: {type: object}
+    read_only: false
+    destructive: true
+    idempotent: true
+    execution: sync
+    affinity: main
+    enforce_thread_affinity: true
+    timeout_hint_secs: 60
+    source_file: scripts/set_transform.py
+    next-tools:
+      on-success: [unity_scene__save_scene, unity_scene__inspect_scene]
+      on-failure: [unity_scene__inspect_scene, dcc_diagnostics__audit_log]
+  - name: save_scene
+    description: Save all currently open Unity scenes. Use after verified scene mutations. Not for importing assets; use refresh_assets.
+    input_schema: {type: object, properties: {}, additionalProperties: false}
+    output_schema: {type: object}
+    read_only: false
+    destructive: true
+    idempotent: true
+    execution: sync
+    affinity: main
+    enforce_thread_affinity: true
+    timeout_hint_secs: 60
+    source_file: scripts/save_scene.py
+    next-tools:
+      on-success: [unity_scene__inspect_scene]
+      on-failure: [dcc_diagnostics__screenshot, dcc_diagnostics__audit_log]

dcc_mcp_unity/unity_package/Editor/DccMcp.Unity.Editor.asmdef

@@ -0,0 +1,9 @@
+{
+  "name": "DccMcp.Unity.Editor",
+  "rootNamespace": "DccMcp.Unity",
+  "references": [],
+  "includePlatforms": [
+    "Editor"
+  ],
+  "autoReferenced": true
+}