mcpforunityserver 9.3.0b20260128055651__tar.gz → 9.3.0b20260129121506__tar.gz

{mcpforunityserver-9.3.0b20260128055651 → mcpforunityserver-9.3.0b20260129121506}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpforunityserver
-Version: 9.3.0b20260128055651
+Version: 9.3.0b20260129121506
 Summary: MCP for Unity Server: A Unity package for Unity Editor integration via the Model Context Protocol (MCP).
 Author-email: Marcus Sanatan <msanatan@gmail.com>, David Sarno <david.sarno@gmail.com>, Wu Shutong <martinwfire@gmail.com>
 License-Expression: MIT
@@ -163,6 +163,26 @@ The server connects to Unity Editor automatically when both are running. No addi
 
 ---
 
+## MCP Resources
+
+The server provides read-only MCP resources for querying Unity Editor state. Resources provide up-to-date information about your Unity project without modifying it.
+
+**Accessing Resources:**
+
+Resources are accessed by their URI (not their name). Always use `ListMcpResources` to get the correct URI format.
+
+**Example URIs:**
+- `mcpforunity://editor/state` - Editor readiness snapshot
+- `mcpforunity://project/tags` - All project tags
+- `mcpforunity://scene/gameobject/{instance_id}` - GameObject details by ID
+- `mcpforunity://prefab/{encoded_path}` - Prefab info by asset path
+
+**Important:** Resource names use underscores (e.g., `editor_state`) but URIs use slashes/hyphens (e.g., `mcpforunity://editor/state`). Always use the URI from `ListMcpResources()` when reading resources.
+
+**All resource descriptions now include their URI** for easy reference. List available resources to see the complete catalog with URIs.
+
+---
+
 ## Example Prompts
 
 Once connected, try these commands in your AI assistant:

{mcpforunityserver-9.3.0b20260128055651 → mcpforunityserver-9.3.0b20260129121506}/README.md

@@ -122,6 +122,26 @@ The server connects to Unity Editor automatically when both are running. No addi
 
 ---
 
+## MCP Resources
+
+The server provides read-only MCP resources for querying Unity Editor state. Resources provide up-to-date information about your Unity project without modifying it.
+
+**Accessing Resources:**
+
+Resources are accessed by their URI (not their name). Always use `ListMcpResources` to get the correct URI format.
+
+**Example URIs:**
+- `mcpforunity://editor/state` - Editor readiness snapshot
+- `mcpforunity://project/tags` - All project tags
+- `mcpforunity://scene/gameobject/{instance_id}` - GameObject details by ID
+- `mcpforunity://prefab/{encoded_path}` - Prefab info by asset path
+
+**Important:** Resource names use underscores (e.g., `editor_state`) but URIs use slashes/hyphens (e.g., `mcpforunity://editor/state`). Always use the URI from `ListMcpResources()` when reading resources.
+
+**All resource descriptions now include their URI** for easy reference. List available resources to see the complete catalog with URIs.
+
+---
+
 ## Example Prompts
 
 Once connected, try these commands in your AI assistant:

{mcpforunityserver-9.3.0b20260128055651 → mcpforunityserver-9.3.0b20260129121506}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcpforunityserver"
-version = "9.3.0b20260128055651"
+version = "9.3.0b20260129121506"
 description = "MCP for Unity Server: A Unity package for Unity Editor integration via the Model Context Protocol (MCP)."
 readme = "README.md"
 license = "MIT"

{mcpforunityserver-9.3.0b20260128055651 → mcpforunityserver-9.3.0b20260129121506}/src/cli/commands/animation.py

@@ -1,12 +1,12 @@
 """Animation CLI commands - placeholder for future implementation."""
 
-import sys
 import click
 from typing import Optional, Any
 
 from cli.utils.config import get_config
 from cli.utils.output import format_output, print_error, print_info
-from cli.utils.connection import run_command, UnityConnectionError
+from cli.utils.connection import run_command, handle_unity_errors
+from cli.utils.constants import SEARCH_METHOD_CHOICE_BASIC
 
 
 @click.group()
@@ -26,10 +26,11 @@ def animation():
 )
 @click.option(
     "--search-method",
-    type=click.Choice(["by_name", "by_path", "by_id"]),
+    type=SEARCH_METHOD_CHOICE_BASIC,
     default=None,
     help="How to find the target."
 )
+@handle_unity_errors
 def play(target: str, state_name: str, layer: int, search_method: Optional[str]):
     """Play an animation state on a target's Animator.
 
@@ -53,12 +54,8 @@ def play(target: str, state_name: str, layer: int, search_method: Optional[str])
     if search_method:
         params["searchMethod"] = search_method
 
-    try:
-        result = run_command("manage_components", params, config)
-        click.echo(format_output(result, config.format))
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_components", params, config)
+    click.echo(format_output(result, config.format))
 
 
 @animation.command("set-parameter")

{mcpforunityserver-9.3.0b20260128055651 → mcpforunityserver-9.3.0b20260129121506}/src/cli/commands/asset.py

@@ -7,7 +7,9 @@ from typing import Optional, Any
 
 from cli.utils.config import get_config
 from cli.utils.output import format_output, print_error, print_success
-from cli.utils.connection import run_command, UnityConnectionError
+from cli.utils.connection import run_command, handle_unity_errors
+from cli.utils.parsers import parse_json_dict_or_exit
+from cli.utils.confirmation import confirm_destructive_action
 
 
 @click.group()
@@ -41,6 +43,7 @@ def asset():
     type=int,
     help="Page number (1-based)."
 )
+@handle_unity_errors
 def search(pattern: str, path: str, filter_type: Optional[str], limit: int, page: int):
     """Search for assets.
 
@@ -64,12 +67,8 @@ def search(pattern: str, path: str, filter_type: Optional[str], limit: int, page
     if filter_type:
         params["filterType"] = filter_type
 
-    try:
-        result = run_command("manage_asset", params, config)
-        click.echo(format_output(result, config.format))
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_asset", params, config)
+    click.echo(format_output(result, config.format))
 
 
 @asset.command("info")
@@ -79,6 +78,7 @@ def search(pattern: str, path: str, filter_type: Optional[str], limit: int, page
     is_flag=True,
     help="Generate preview thumbnail (may be large)."
 )
+@handle_unity_errors
 def info(path: str, preview: bool):
     """Get detailed information about an asset.
 
@@ -95,12 +95,8 @@ def info(path: str, preview: bool):
         "generatePreview": preview,
     }
 
-    try:
-        result = run_command("manage_asset", params, config)
-        click.echo(format_output(result, config.format))
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_asset", params, config)
+    click.echo(format_output(result, config.format))
 
 
 @asset.command("create")
@@ -111,6 +107,7 @@ def info(path: str, preview: bool):
     default=None,
     help='Initial properties as JSON.'
 )
+@handle_unity_errors
 def create(path: str, asset_type: str, properties: Optional[str]):
     """Create a new asset.
 
@@ -129,20 +126,12 @@ def create(path: str, asset_type: str, properties: Optional[str]):
     }
 
     if properties:
-        try:
-            params["properties"] = json.loads(properties)
-        except json.JSONDecodeError as e:
-            print_error(f"Invalid JSON for properties: {e}")
-            sys.exit(1)
-
-    try:
-        result = run_command("manage_asset", params, config)
-        click.echo(format_output(result, config.format))
-        if result.get("success"):
-            print_success(f"Created {asset_type}: {path}")
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+        params["properties"] = parse_json_dict_or_exit(properties, "properties")
+
+    result = run_command("manage_asset", params, config)
+    click.echo(format_output(result, config.format))
+    if result.get("success"):
+        print_success(f"Created {asset_type}: {path}")
 
 
 @asset.command("delete")
@@ -152,6 +141,7 @@ def create(path: str, asset_type: str, properties: Optional[str]):
     is_flag=True,
     help="Skip confirmation prompt."
 )
+@handle_unity_errors
 def delete(path: str, force: bool):
     """Delete an asset.
 
@@ -162,23 +152,19 @@ def delete(path: str, force: bool):
     """
     config = get_config()
 
-    if not force:
-        click.confirm(f"Delete asset '{path}'?", abort=True)
+    confirm_destructive_action("Delete", "asset", path, force)
 
-    try:
-        result = run_command(
-            "manage_asset", {"action": "delete", "path": path}, config)
-        click.echo(format_output(result, config.format))
-        if result.get("success"):
-            print_success(f"Deleted: {path}")
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command(
+        "manage_asset", {"action": "delete", "path": path}, config)
+    click.echo(format_output(result, config.format))
+    if result.get("success"):
+        print_success(f"Deleted: {path}")
 
 
 @asset.command("duplicate")
 @click.argument("source")
 @click.argument("destination")
+@handle_unity_errors
 def duplicate(source: str, destination: str):
     """Duplicate an asset.
 
@@ -194,19 +180,16 @@ def duplicate(source: str, destination: str):
         "destination": destination,
     }
 
-    try:
-        result = run_command("manage_asset", params, config)
-        click.echo(format_output(result, config.format))
-        if result.get("success"):
-            print_success(f"Duplicated to: {destination}")
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_asset", params, config)
+    click.echo(format_output(result, config.format))
+    if result.get("success"):
+        print_success(f"Duplicated to: {destination}")
 
 
 @asset.command("move")
 @click.argument("source")
 @click.argument("destination")
+@handle_unity_errors
 def move(source: str, destination: str):
     """Move an asset to a new location.
 
@@ -222,19 +205,16 @@ def move(source: str, destination: str):
         "destination": destination,
     }
 
-    try:
-        result = run_command("manage_asset", params, config)
-        click.echo(format_output(result, config.format))
-        if result.get("success"):
-            print_success(f"Moved to: {destination}")
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_asset", params, config)
+    click.echo(format_output(result, config.format))
+    if result.get("success"):
+        print_success(f"Moved to: {destination}")
 
 
 @asset.command("rename")
 @click.argument("path")
 @click.argument("new_name")
+@handle_unity_errors
 def rename(path: str, new_name: str):
     """Rename an asset.
 
@@ -255,18 +235,15 @@ def rename(path: str, new_name: str):
         "destination": destination,
     }
 
-    try:
-        result = run_command("manage_asset", params, config)
-        click.echo(format_output(result, config.format))
-        if result.get("success"):
-            print_success(f"Renamed to: {new_name}")
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_asset", params, config)
+    click.echo(format_output(result, config.format))
+    if result.get("success"):
+        print_success(f"Renamed to: {new_name}")
 
 
 @asset.command("import")
 @click.argument("path")
+@handle_unity_errors
 def import_asset(path: str):
     """Import/reimport an asset.
 
@@ -276,19 +253,16 @@ def import_asset(path: str):
     """
     config = get_config()
 
-    try:
-        result = run_command(
-            "manage_asset", {"action": "import", "path": path}, config)
-        click.echo(format_output(result, config.format))
-        if result.get("success"):
-            print_success(f"Imported: {path}")
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command(
+        "manage_asset", {"action": "import", "path": path}, config)
+    click.echo(format_output(result, config.format))
+    if result.get("success"):
+        print_success(f"Imported: {path}")
 
 
 @asset.command("mkdir")
 @click.argument("path")
+@handle_unity_errors
 def mkdir(path: str):
     """Create a folder.
 
@@ -299,12 +273,8 @@ def mkdir(path: str):
     """
     config = get_config()
 
-    try:
-        result = run_command(
-            "manage_asset", {"action": "create_folder", "path": path}, config)
-        click.echo(format_output(result, config.format))
-        if result.get("success"):
-            print_success(f"Created folder: {path}")
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command(
+        "manage_asset", {"action": "create_folder", "path": path}, config)
+    click.echo(format_output(result, config.format))
+    if result.get("success"):
+        print_success(f"Created folder: {path}")

{mcpforunityserver-9.3.0b20260128055651 → mcpforunityserver-9.3.0b20260129121506}/src/cli/commands/audio.py

@@ -6,7 +6,8 @@ from typing import Optional, Any
 
 from cli.utils.config import get_config
 from cli.utils.output import format_output, print_error, print_info
-from cli.utils.connection import run_command, UnityConnectionError
+from cli.utils.connection import run_command, handle_unity_errors
+from cli.utils.constants import SEARCH_METHOD_CHOICE_BASIC
 
 
 @click.group()
@@ -24,10 +25,11 @@ def audio():
 )
 @click.option(
     "--search-method",
-    type=click.Choice(["by_name", "by_path", "by_id"]),
+    type=SEARCH_METHOD_CHOICE_BASIC,
     default=None,
     help="How to find the target."
 )
+@handle_unity_errors
 def play(target: str, clip: Optional[str], search_method: Optional[str]):
     """Play audio on a target's AudioSource.
 
@@ -52,22 +54,19 @@ def play(target: str, clip: Optional[str], search_method: Optional[str]):
     if search_method:
         params["searchMethod"] = search_method
 
-    try:
-        result = run_command("manage_components", params, config)
-        click.echo(format_output(result, config.format))
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_components", params, config)
+    click.echo(format_output(result, config.format))
 
 
 @audio.command("stop")
 @click.argument("target")
 @click.option(
     "--search-method",
-    type=click.Choice(["by_name", "by_path", "by_id"]),
+    type=SEARCH_METHOD_CHOICE_BASIC,
     default=None,
     help="How to find the target."
 )
+@handle_unity_errors
 def stop(target: str, search_method: Optional[str]):
     """Stop audio on a target's AudioSource.
 
@@ -88,12 +87,8 @@ def stop(target: str, search_method: Optional[str]):
     if search_method:
         params["searchMethod"] = search_method
 
-    try:
-        result = run_command("manage_components", params, config)
-        click.echo(format_output(result, config.format))
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_components", params, config)
+    click.echo(format_output(result, config.format))
 
 
 @audio.command("volume")
@@ -101,10 +96,11 @@ def stop(target: str, search_method: Optional[str]):
 @click.argument("level", type=float)
 @click.option(
     "--search-method",
-    type=click.Choice(["by_name", "by_path", "by_id"]),
+    type=SEARCH_METHOD_CHOICE_BASIC,
     default=None,
     help="How to find the target."
 )
+@handle_unity_errors
 def volume(target: str, level: float, search_method: Optional[str]):
     """Set audio volume on a target's AudioSource.
 
@@ -125,9 +121,5 @@ def volume(target: str, level: float, search_method: Optional[str]):
     if search_method:
         params["searchMethod"] = search_method
 
-    try:
-        result = run_command("manage_components", params, config)
-        click.echo(format_output(result, config.format))
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("manage_components", params, config)
+    click.echo(format_output(result, config.format))

{mcpforunityserver-9.3.0b20260128055651 → mcpforunityserver-9.3.0b20260129121506}/src/cli/commands/batch.py

@@ -7,7 +7,8 @@ from typing import Optional, Any
 
 from cli.utils.config import get_config
 from cli.utils.output import format_output, print_error, print_success, print_info
-from cli.utils.connection import run_command, UnityConnectionError
+from cli.utils.connection import run_command, handle_unity_errors
+from cli.utils.parsers import parse_json_list_or_exit
 
 
 @click.group()
@@ -20,6 +21,7 @@ def batch():
 @click.argument("file", type=click.Path(exists=True))
 @click.option("--parallel", is_flag=True, help="Execute read-only commands in parallel.")
 @click.option("--fail-fast", is_flag=True, help="Stop on first failure.")
+@handle_unity_errors
 def batch_run(file: str, parallel: bool, fail_fast: bool):
     """Execute commands from a JSON file.
 
@@ -67,29 +69,26 @@ def batch_run(file: str, parallel: bool, fail_fast: bool):
 
     click.echo(f"Executing {len(commands)} commands...")
 
-    try:
-        result = run_command("batch_execute", params, config)
-        click.echo(format_output(result, config.format))
-
-        if isinstance(result, dict):
-            results = result.get("data", {}).get("results", [])
-            succeeded = sum(1 for r in results if r.get("success"))
-            failed = len(results) - succeeded
-
-            if failed == 0:
-                print_success(
-                    f"All {succeeded} commands completed successfully")
-            else:
-                print_info(f"{succeeded} succeeded, {failed} failed")
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("batch_execute", params, config)
+    click.echo(format_output(result, config.format))
+
+    if isinstance(result, dict):
+        results = result.get("data", {}).get("results", [])
+        succeeded = sum(1 for r in results if r.get("success"))
+        failed = len(results) - succeeded
+
+        if failed == 0:
+            print_success(
+                f"All {succeeded} commands completed successfully")
+        else:
+            print_info(f"{succeeded} succeeded, {failed} failed")
 
 
 @batch.command("inline")
 @click.argument("commands_json")
 @click.option("--parallel", is_flag=True, help="Execute read-only commands in parallel.")
 @click.option("--fail-fast", is_flag=True, help="Stop on first failure.")
+@handle_unity_errors
 def batch_inline(commands_json: str, parallel: bool, fail_fast: bool):
     """Execute commands from inline JSON.
 
@@ -104,15 +103,7 @@ def batch_inline(commands_json: str, parallel: bool, fail_fast: bool):
     """
     config = get_config()
 
-    try:
-        commands = json.loads(commands_json)
-    except json.JSONDecodeError as e:
-        print_error(f"Invalid JSON: {e}")
-        sys.exit(1)
-
-    if not isinstance(commands, list):
-        print_error("Commands must be an array")
-        sys.exit(1)
+    commands = parse_json_list_or_exit(commands_json, "commands")
 
     if len(commands) > 25:
         print_error(f"Maximum 25 commands per batch, got {len(commands)}")
@@ -124,12 +115,8 @@ def batch_inline(commands_json: str, parallel: bool, fail_fast: bool):
     if fail_fast:
         params["failFast"] = True
 
-    try:
-        result = run_command("batch_execute", params, config)
-        click.echo(format_output(result, config.format))
-    except UnityConnectionError as e:
-        print_error(str(e))
-        sys.exit(1)
+    result = run_command("batch_execute", params, config)
+    click.echo(format_output(result, config.format))
 
 
 @batch.command("template")