mcpforunityserver 9.3.0b20260129104751__py3-none-any.whl

cli/main.py

@@ -0,0 +1,281 @@
+"""Unity MCP Command Line Interface - Main Entry Point."""
+
+import sys
+from importlib import import_module
+
+import click
+from typing import Optional
+
+from cli import __version__
+from cli.utils.config import CLIConfig, set_config, get_config
+from cli.utils.suggestions import suggest_matches, format_suggestions
+from cli.utils.output import format_output, print_error, print_success, print_info
+from cli.utils.connection import (
+    run_command,
+    run_check_connection,
+    run_list_instances,
+    UnityConnectionError,
+    warn_if_remote_host,
+)
+
+
+# Context object to pass configuration between commands
+class Context:
+    def __init__(self):
+        self.config: Optional[CLIConfig] = None
+        self.verbose: bool = False
+
+
+pass_context = click.make_pass_decorator(Context, ensure=True)
+
+
+_ORIGINAL_RESOLVE_COMMAND = click.Group.resolve_command
+
+
+def _resolve_command_with_suggestions(self: click.Group, ctx: click.Context, args: list[str]):
+    try:
+        return _ORIGINAL_RESOLVE_COMMAND(self, ctx, args)
+    except click.exceptions.NoSuchCommand as e:
+        if not args or args[0].startswith("-"):
+            raise
+        matches = suggest_matches(args[0], self.list_commands(ctx))
+        suggestion = format_suggestions(matches)
+        if suggestion:
+            message = f"{e}\n{suggestion}"
+            raise click.exceptions.UsageError(message, ctx=ctx)
+        raise
+    except click.exceptions.UsageError as e:
+        if args and not args[0].startswith("-") and "No such command" in str(e):
+            matches = suggest_matches(args[0], self.list_commands(ctx))
+            suggestion = format_suggestions(matches)
+            if suggestion:
+                message = f"{e}\n{suggestion}"
+                raise click.exceptions.UsageError(message, ctx=ctx)
+        raise
+
+
+# Install suggestion handling for all CLI command groups.
+click.Group.resolve_command = _resolve_command_with_suggestions  # type: ignore[assignment]
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="unity-mcp")
+@click.option(
+    "--host", "-h",
+    default="127.0.0.1",
+    envvar="UNITY_MCP_HOST",
+    help="MCP server host address."
+)
+@click.option(
+    "--port", "-p",
+    default=8080,
+    type=int,
+    envvar="UNITY_MCP_HTTP_PORT",
+    help="MCP server port."
+)
+@click.option(
+    "--timeout", "-t",
+    default=30,
+    type=int,
+    envvar="UNITY_MCP_TIMEOUT",
+    help="Command timeout in seconds."
+)
+@click.option(
+    "--format", "-f",
+    type=click.Choice(["text", "json", "table"]),
+    default="text",
+    envvar="UNITY_MCP_FORMAT",
+    help="Output format."
+)
+@click.option(
+    "--instance", "-i",
+    default=None,
+    envvar="UNITY_MCP_INSTANCE",
+    help="Target Unity instance (hash or Name@hash)."
+)
+@click.option(
+    "--verbose", "-v",
+    is_flag=True,
+    help="Enable verbose output."
+)
+@pass_context
+def cli(ctx: Context, host: str, port: int, timeout: int, format: str, instance: Optional[str], verbose: bool):
+    """Unity MCP Command Line Interface.
+
+    Control Unity Editor directly from the command line using the Model Context Protocol.
+
+    \b
+    Examples:
+        unity-mcp status
+        unity-mcp gameobject find "Player"
+        unity-mcp scene hierarchy --format json
+        unity-mcp editor play
+
+    \b
+    Environment Variables:
+        UNITY_MCP_HOST      Server host (default: 127.0.0.1)
+        UNITY_MCP_HTTP_PORT Server port (default: 8080)
+        UNITY_MCP_TIMEOUT   Timeout in seconds (default: 30)
+        UNITY_MCP_FORMAT    Output format (default: text)
+        UNITY_MCP_INSTANCE  Target Unity instance
+    """
+    config = CLIConfig(
+        host=host,
+        port=port,
+        timeout=timeout,
+        format=format,
+        unity_instance=instance,
+    )
+
+    # Security warning for non-localhost connections
+    warn_if_remote_host(config)
+
+    set_config(config)
+    ctx.config = config
+    ctx.verbose = verbose
+
+
+@cli.command("status")
+@pass_context
+def status(ctx: Context):
+    """Check connection status to Unity MCP server."""
+    config = ctx.config or get_config()
+
+    click.echo(f"Checking connection to {config.host}:{config.port}...")
+
+    if run_check_connection(config):
+        print_success(
+            f"Connected to Unity MCP server at {config.host}:{config.port}")
+
+        # Try to get Unity instances
+        try:
+            result = run_list_instances(config)
+            instances = result.get("instances", []) if isinstance(
+                result, dict) else []
+            if instances:
+                click.echo("\nConnected Unity instances:")
+                for inst in instances:
+                    project = inst.get("project", "Unknown")
+                    version = inst.get("unity_version", "Unknown")
+                    hash_id = inst.get("hash", "")[:8]
+                    click.echo(f"  • {project} (Unity {version}) [{hash_id}]")
+            else:
+                print_info("No Unity instances currently connected")
+        except UnityConnectionError as e:
+            print_info(f"Could not retrieve Unity instances: {e}")
+    else:
+        print_error(
+            f"Cannot connect to Unity MCP server at {config.host}:{config.port}")
+        sys.exit(1)
+
+
+@cli.command("instances")
+@pass_context
+def list_instances(ctx: Context):
+    """List available Unity instances."""
+    config = ctx.config or get_config()
+
+    try:
+        instances = run_list_instances(config)
+        click.echo(format_output(instances, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@cli.command("raw")
+@click.argument("command_type")
+@click.argument("params", required=False, default="{}")
+@pass_context
+def raw_command(ctx: Context, command_type: str, params: str):
+    """Send a raw command to Unity.
+
+    \b
+    Examples:
+        unity-mcp raw manage_scene '{"action": "get_hierarchy"}'
+        unity-mcp raw read_console '{"count": 10}'
+    """
+    import json
+    config = ctx.config or get_config()
+
+    try:
+        params_dict = json.loads(params)
+    except json.JSONDecodeError as e:
+        print_error(f"Invalid JSON params: {e}")
+        sys.exit(1)
+
+    try:
+        result = run_command(command_type, params_dict, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+# Import and register command groups
+# These will be implemented in subsequent TODOs
+def register_commands():
+    """Register all command groups."""
+    def register_optional_command(module_name: str, command_name: str) -> None:
+        try:
+            module = import_module(module_name)
+        except ModuleNotFoundError as e:
+            if e.name == module_name:
+                return
+            print_error(
+                f"Failed to load command module '{module_name}': {e}"
+            )
+            return
+        except Exception as e:
+            print_error(
+                f"Failed to load command module '{module_name}': {e}"
+            )
+            return
+
+        command = getattr(module, command_name, None)
+        if command is None:
+            print_error(
+                f"Command '{command_name}' not found in '{module_name}'"
+            )
+            return
+
+        cli.add_command(command)
+
+    optional_commands = [
+        ("cli.commands.tool", "tool"),
+        ("cli.commands.tool", "custom_tool"),
+        ("cli.commands.gameobject", "gameobject"),
+        ("cli.commands.component", "component"),
+        ("cli.commands.scene", "scene"),
+        ("cli.commands.asset", "asset"),
+        ("cli.commands.script", "script"),
+        ("cli.commands.code", "code"),
+        ("cli.commands.editor", "editor"),
+        ("cli.commands.prefab", "prefab"),
+        ("cli.commands.material", "material"),
+        ("cli.commands.lighting", "lighting"),
+        ("cli.commands.animation", "animation"),
+        ("cli.commands.audio", "audio"),
+        ("cli.commands.ui", "ui"),
+        ("cli.commands.instance", "instance"),
+        ("cli.commands.shader", "shader"),
+        ("cli.commands.vfx", "vfx"),
+        ("cli.commands.batch", "batch"),
+        ("cli.commands.texture", "texture"),
+    ]
+
+    for module_name, command_name in optional_commands:
+        register_optional_command(module_name, command_name)
+
+
+# Register commands on import
+register_commands()
+
+
+def main():
+    """Main entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

cli/utils/__init__.py

@@ -0,0 +1,31 @@
+"""CLI utility modules."""
+
+from cli.utils.config import CLIConfig, get_config, set_config
+from cli.utils.connection import (
+    run_command,
+    run_check_connection,
+    run_list_instances,
+    UnityConnectionError,
+)
+from cli.utils.output import (
+    format_output,
+    print_success,
+    print_error,
+    print_warning,
+    print_info,
+)
+
+__all__ = [
+    "CLIConfig",
+    "UnityConnectionError",
+    "format_output",
+    "get_config",
+    "print_error",
+    "print_info",
+    "print_success",
+    "print_warning",
+    "run_check_connection",
+    "run_command",
+    "run_list_instances",
+    "set_config",
+]

cli/utils/config.py

@@ -0,0 +1,58 @@
+"""CLI Configuration utilities."""
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class CLIConfig:
+    """Configuration for CLI connection to Unity."""
+
+    host: str = "127.0.0.1"
+    port: int = 8080
+    timeout: int = 30
+    format: str = "text"  # text, json, table
+    unity_instance: Optional[str] = None
+
+    @classmethod
+    def from_env(cls) -> "CLIConfig":
+        port_raw = os.environ.get("UNITY_MCP_HTTP_PORT", "8080")
+        try:
+            port = int(port_raw)
+        except (ValueError, TypeError):
+            raise ValueError(
+                f"Invalid UNITY_MCP_HTTP_PORT value: {port_raw!r}")
+
+        timeout_raw = os.environ.get("UNITY_MCP_TIMEOUT", "30")
+        try:
+            timeout = int(timeout_raw)
+        except (ValueError, TypeError):
+            raise ValueError(
+                f"Invalid UNITY_MCP_TIMEOUT value: {timeout_raw!r}")
+
+        return cls(
+            host=os.environ.get("UNITY_MCP_HOST", "127.0.0.1"),
+            port=port,
+            timeout=timeout,
+            format=os.environ.get("UNITY_MCP_FORMAT", "text"),
+            unity_instance=os.environ.get("UNITY_MCP_INSTANCE"),
+        )
+
+
+# Global config instance
+_config: Optional[CLIConfig] = None
+
+
+def get_config() -> CLIConfig:
+    """Get the current CLI configuration."""
+    global _config
+    if _config is None:
+        _config = CLIConfig.from_env()
+    return _config
+
+
+def set_config(config: CLIConfig) -> None:
+    """Set the CLI configuration."""
+    global _config
+    _config = config

cli/utils/confirmation.py

@@ -0,0 +1,37 @@
+"""Confirmation dialog utilities for CLI commands."""
+
+import click
+
+
+def confirm_destructive_action(
+    action: str,
+    item_type: str,
+    item_name: str,
+    force: bool,
+    extra_context: str = ""
+) -> None:
+    """Prompt user to confirm destructive action unless --force flag is set.
+
+    Args:
+        action: The action being performed (e.g., "Delete", "Remove")
+        item_type: The type of item (e.g., "script", "GameObject", "asset")
+        item_name: The name/path of the item
+        force: If True, skip confirmation prompt
+        extra_context: Optional additional context (e.g., "from 'Player'")
+
+    Raises:
+        click.Abort: If user declines confirmation
+
+    Examples:
+        confirm_destructive_action("Delete", "script", "MyScript.cs", force=False)
+        # Prompts: "Delete script 'MyScript.cs'?"
+
+        confirm_destructive_action("Remove", "Rigidbody", "Player", force=False, extra_context="from")
+        # Prompts: "Remove Rigidbody from 'Player'?"
+    """
+    if not force:
+        if extra_context:
+            message = f"{action} {item_type} {extra_context} '{item_name}'?"
+        else:
+            message = f"{action} {item_type} '{item_name}'?"
+        click.confirm(message, abort=True)

cli/utils/connection.py

@@ -0,0 +1,258 @@
+"""Connection utilities for CLI to communicate with Unity via MCP server."""
+
+import asyncio
+import functools
+import sys
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+import httpx
+
+from cli.utils.config import get_config, CLIConfig
+
+
+class UnityConnectionError(Exception):
+    """Raised when connection to Unity fails."""
+    pass
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def handle_unity_errors(func: F) -> F:
+    """Decorator that handles UnityConnectionError consistently.
+
+    Wraps a CLI command function and catches UnityConnectionError,
+    printing a formatted error message and exiting with code 1.
+
+    Usage:
+        @scene.command("active")
+        @handle_unity_errors
+        def active():
+            config = get_config()
+            result = run_command("manage_scene", {"action": "get_active"}, config)
+            click.echo(format_output(result, config.format))
+    """
+    from cli.utils.output import print_error
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return func(*args, **kwargs)
+        except UnityConnectionError as e:
+            print_error(str(e))
+            sys.exit(1)
+
+    return wrapper  # type: ignore[return-value]
+
+
+def warn_if_remote_host(config: CLIConfig) -> None:
+    """Warn user if connecting to a non-localhost server.
+
+    This is a security measure to alert users that connecting to remote
+    servers exposes Unity control to potential network attacks.
+
+    Args:
+        config: CLI configuration with host setting
+    """
+    import click
+
+    local_hosts = ("127.0.0.1", "localhost", "::1", "0.0.0.0")
+    if config.host.lower() not in local_hosts:
+        click.echo(
+            "⚠️  Security Warning: Connecting to non-localhost server.\n"
+            "   The MCP CLI has no authentication. Anyone on the network could\n"
+            "   intercept commands or send unauthorized commands to Unity.\n"
+            "   Only proceed if you trust this network.\n",
+            err=True
+        )
+
+
+async def send_command(
+    command_type: str,
+    params: Dict[str, Any],
+    config: Optional[CLIConfig] = None,
+    timeout: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Send a command to Unity via the MCP HTTP server.
+
+    Args:
+        command_type: The command type (e.g., 'manage_gameobject', 'manage_scene')
+        params: Command parameters
+        config: Optional CLI configuration
+        timeout: Optional timeout override
+
+    Returns:
+        Response dict from Unity
+
+    Raises:
+        UnityConnectionError: If connection fails
+    """
+    cfg = config or get_config()
+    url = f"http://{cfg.host}:{cfg.port}/api/command"
+
+    payload = {
+        "type": command_type,
+        "params": params,
+    }
+
+    if cfg.unity_instance:
+        payload["unity_instance"] = cfg.unity_instance
+
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url,
+                json=payload,
+                timeout=timeout or cfg.timeout,
+            )
+            response.raise_for_status()
+            return response.json()
+    except httpx.ConnectError as e:
+        raise UnityConnectionError(
+            f"Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. "
+            f"Make sure the server is running and Unity is connected.\n"
+            f"Error: {e}"
+        )
+    except httpx.TimeoutException:
+        raise UnityConnectionError(
+            f"Connection to Unity timed out after {timeout or cfg.timeout}s. "
+            f"Unity may be busy or unresponsive."
+        )
+    except httpx.HTTPStatusError as e:
+        raise UnityConnectionError(
+            f"HTTP error from server: {e.response.status_code} - {e.response.text}"
+        )
+    except Exception as e:
+        raise UnityConnectionError(f"Unexpected error: {e}")
+
+
+def run_command(
+    command_type: str,
+    params: Dict[str, Any],
+    config: Optional[CLIConfig] = None,
+    timeout: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Synchronous wrapper for send_command.
+
+    Args:
+        command_type: The command type
+        params: Command parameters
+        config: Optional CLI configuration
+        timeout: Optional timeout override
+
+    Returns:
+        Response dict from Unity
+    """
+    return asyncio.run(send_command(command_type, params, config, timeout))
+
+
+async def check_connection(config: Optional[CLIConfig] = None) -> bool:
+    """Check if we can connect to the Unity MCP server.
+
+    Args:
+        config: Optional CLI configuration
+
+    Returns:
+        True if connection successful, False otherwise
+    """
+    cfg = config or get_config()
+    url = f"http://{cfg.host}:{cfg.port}/health"
+
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, timeout=5)
+            return response.status_code == 200
+    except Exception:
+        return False
+
+
+def run_check_connection(config: Optional[CLIConfig] = None) -> bool:
+    """Synchronous wrapper for check_connection."""
+    return asyncio.run(check_connection(config))
+
+
+async def list_unity_instances(config: Optional[CLIConfig] = None) -> Dict[str, Any]:
+    """List available Unity instances.
+
+    Args:
+        config: Optional CLI configuration
+
+    Returns:
+        Dict with list of Unity instances
+    """
+    cfg = config or get_config()
+
+    # Try the new /api/instances endpoint first, fall back to /plugin/sessions
+    urls_to_try = [
+        f"http://{cfg.host}:{cfg.port}/api/instances",
+        f"http://{cfg.host}:{cfg.port}/plugin/sessions",
+    ]
+
+    async with httpx.AsyncClient() as client:
+        for url in urls_to_try:
+            try:
+                response = await client.get(url, timeout=10)
+                if response.status_code == 200:
+                    data = response.json()
+                    # Normalize response format
+                    if "instances" in data:
+                        return data
+                    elif "sessions" in data:
+                        # Convert sessions format to instances format
+                        instances = []
+                        for session_id, details in data["sessions"].items():
+                            instances.append({
+                                "session_id": session_id,
+                                "project": details.get("project", "Unknown"),
+                                "hash": details.get("hash", ""),
+                                "unity_version": details.get("unity_version", "Unknown"),
+                                "connected_at": details.get("connected_at", ""),
+                            })
+                        return {"success": True, "instances": instances}
+            except Exception:
+                continue
+
+    raise UnityConnectionError(
+        "Failed to list Unity instances: No working endpoint found")
+
+
+def run_list_instances(config: Optional[CLIConfig] = None) -> Dict[str, Any]:
+    """Synchronous wrapper for list_unity_instances."""
+    return asyncio.run(list_unity_instances(config))
+
+
+async def list_custom_tools(config: Optional[CLIConfig] = None) -> Dict[str, Any]:
+    """List custom tools registered for the active Unity project."""
+    cfg = config or get_config()
+    url = f"http://{cfg.host}:{cfg.port}/api/custom-tools"
+    params: Dict[str, Any] = {}
+    if cfg.unity_instance:
+        params["instance"] = cfg.unity_instance
+
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, params=params, timeout=cfg.timeout)
+            response.raise_for_status()
+            return response.json()
+    except httpx.ConnectError as e:
+        raise UnityConnectionError(
+            f"Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. "
+            f"Make sure the server is running and Unity is connected.\n"
+            f"Error: {e}"
+        )
+    except httpx.TimeoutException:
+        raise UnityConnectionError(
+            f"Connection to Unity timed out after {cfg.timeout}s. "
+            f"Unity may be busy or unresponsive."
+        )
+    except httpx.HTTPStatusError as e:
+        raise UnityConnectionError(
+            f"HTTP error from server: {e.response.status_code} - {e.response.text}"
+        )
+    except Exception as e:
+        raise UnityConnectionError(f"Unexpected error: {e}")
+
+
+def run_list_custom_tools(config: Optional[CLIConfig] = None) -> Dict[str, Any]:
+    """Synchronous wrapper for list_custom_tools."""
+    return asyncio.run(list_custom_tools(config))

cli/utils/constants.py

@@ -0,0 +1,23 @@
+"""Common constants for CLI commands."""
+import click
+
+# Search method constants used across various CLI commands
+# These define how GameObjects and other Unity objects can be located
+
+# Full set of search methods (used by gameobject commands)
+SEARCH_METHODS_FULL = ["by_name", "by_path", "by_id", "by_tag", "by_layer", "by_component"]
+
+# Basic search methods (used by component, animation, audio commands)
+SEARCH_METHODS_BASIC = ["by_id", "by_name", "by_path"]
+
+# Extended search methods for renderer-based commands (material commands)
+SEARCH_METHODS_RENDERER = ["by_id", "by_name", "by_path", "by_tag", "by_layer", "by_component"]
+
+# Tagged search methods (used by VFX commands)
+SEARCH_METHODS_TAGGED = ["by_name", "by_path", "by_id", "by_tag"]
+
+# Click choice options for each set
+SEARCH_METHOD_CHOICE_FULL = click.Choice(SEARCH_METHODS_FULL)
+SEARCH_METHOD_CHOICE_BASIC = click.Choice(SEARCH_METHODS_BASIC)
+SEARCH_METHOD_CHOICE_RENDERER = click.Choice(SEARCH_METHODS_RENDERER)
+SEARCH_METHOD_CHOICE_TAGGED = click.Choice(SEARCH_METHODS_TAGGED)