mcpforunityserver 8.5.0__py3-none-any.whl → 9.1.0__py3-none-any.whl

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/connection.py

@@ -0,0 +1,191 @@
+"""Connection utilities for CLI to communicate with Unity via MCP server."""
+
+import asyncio
+import json
+import sys
+from typing import Any, Dict, Optional
+
+import httpx
+
+from cli.utils.config import get_config, CLIConfig
+
+
+class UnityConnectionError(Exception):
+    """Raised when connection to Unity fails."""
+    pass
+
+
+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))

cli/utils/output.py

@@ -0,0 +1,195 @@
+"""Output formatting utilities for CLI."""
+
+import json
+from typing import Any
+
+import click
+
+
+def format_output(data: Any, format_type: str = "text") -> str:
+    """Format output based on requested format type.
+
+    Args:
+        data: Data to format
+        format_type: One of 'text', 'json', 'table'
+
+    Returns:
+        Formatted string
+    """
+    if format_type == "json":
+        return format_as_json(data)
+    elif format_type == "table":
+        return format_as_table(data)
+    else:
+        return format_as_text(data)
+
+
+def format_as_json(data: Any) -> str:
+    """Format data as pretty-printed JSON."""
+    try:
+        return json.dumps(data, indent=2, default=str)
+    except (TypeError, ValueError) as e:
+        return json.dumps({"error": f"JSON serialization failed: {e}", "raw": str(data)})
+
+
+def format_as_text(data: Any, indent: int = 0) -> str:
+    """Format data as human-readable text."""
+    prefix = "  " * indent
+
+    if data is None:
+        return f"{prefix}(none)"
+
+    if isinstance(data, dict):
+        # Check for error response
+        if "success" in data and not data.get("success"):
+            error = data.get("error") or data.get("message") or "Unknown error"
+            return f"{prefix}❌ Error: {error}"
+
+        # Check for success response with data
+        if "success" in data and data.get("success"):
+            result = data.get("data") or data.get("result") or data
+            if result != data:
+                return format_as_text(result, indent)
+
+        lines = []
+        for key, value in data.items():
+            if key in ("success", "error", "message") and "success" in data:
+                continue  # Skip meta fields
+            if isinstance(value, dict):
+                lines.append(f"{prefix}{key}:")
+                lines.append(format_as_text(value, indent + 1))
+            elif isinstance(value, list):
+                lines.append(f"{prefix}{key}: [{len(value)} items]")
+                if len(value) <= 10:
+                    for i, item in enumerate(value):
+                        lines.append(
+                            f"{prefix}  [{i}] {_format_list_item(item)}")
+                else:
+                    for i, item in enumerate(value[:5]):
+                        lines.append(
+                            f"{prefix}  [{i}] {_format_list_item(item)}")
+                    lines.append(f"{prefix}  ... ({len(value) - 10} more)")
+                    for i, item in enumerate(value[-5:], len(value) - 5):
+                        lines.append(
+                            f"{prefix}  [{i}] {_format_list_item(item)}")
+            else:
+                lines.append(f"{prefix}{key}: {value}")
+        return "\n".join(lines)
+
+    if isinstance(data, list):
+        if not data:
+            return f"{prefix}(empty list)"
+        lines = [f"{prefix}[{len(data)} items]"]
+        for i, item in enumerate(data[:20]):
+            lines.append(f"{prefix}  [{i}] {_format_list_item(item)}")
+        if len(data) > 20:
+            lines.append(f"{prefix}  ... ({len(data) - 20} more)")
+        return "\n".join(lines)
+
+    return f"{prefix}{data}"
+
+
+def _format_list_item(item: Any) -> str:
+    """Format a single list item."""
+    if isinstance(item, dict):
+        # Try to find a name/id field for display
+        name = item.get("name") or item.get(
+            "Name") or item.get("id") or item.get("Id")
+        if name:
+            extra = ""
+            if "instanceID" in item:
+                extra = f" (ID: {item['instanceID']})"
+            elif "path" in item:
+                extra = f" ({item['path']})"
+            return f"{name}{extra}"
+        # Fallback to compact representation
+        return json.dumps(item, default=str)[:80]
+    return str(item)[:80]
+
+
+def format_as_table(data: Any) -> str:
+    """Format data as an ASCII table."""
+    if isinstance(data, dict):
+        # Check for success response with data
+        if "success" in data and data.get("success"):
+            result = data.get("data") or data.get(
+                "result") or data.get("items")
+            if isinstance(result, list):
+                return _build_table(result)
+
+        # Single dict as key-value table
+        rows = [[str(k), str(v)[:60]] for k, v in data.items()]
+        return _build_table(rows, headers=["Key", "Value"])
+
+    if isinstance(data, list):
+        return _build_table(data)
+
+    return str(data)
+
+
+def _build_table(data: list[Any], headers: list[str] | None = None) -> str:
+    """Build an ASCII table from list data."""
+    if not data:
+        return "(no data)"
+
+    # Convert list of dicts to rows
+    if isinstance(data[0], dict):
+        if headers is None:
+            headers = list(data[0].keys())
+        rows = [[str(item.get(h, ""))[:40] for h in headers] for item in data]
+    elif isinstance(data[0], (list, tuple)):
+        rows = [[str(cell)[:40] for cell in row] for row in data]
+        if headers is None:
+            headers = [f"Col{i}" for i in range(len(data[0]))]
+    else:
+        rows = [[str(item)[:60]] for item in data]
+        headers = headers or ["Value"]
+
+    # Calculate column widths
+    col_widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            if i < len(col_widths):
+                col_widths[i] = max(col_widths[i], len(cell))
+
+    # Build table
+    lines = []
+
+    # Header
+    header_line = " | ".join(
+        h.ljust(col_widths[i]) for i, h in enumerate(headers))
+    lines.append(header_line)
+    lines.append("-+-".join("-" * w for w in col_widths))
+
+    # Rows
+    for row in rows[:50]:  # Limit rows
+        row_line = " | ".join(
+            (row[i] if i < len(row) else "").ljust(col_widths[i])
+            for i in range(len(headers))
+        )
+        lines.append(row_line)
+
+    if len(rows) > 50:
+        lines.append(f"... ({len(rows) - 50} more rows)")
+
+    return "\n".join(lines)
+
+
+def print_success(message: str) -> None:
+    """Print a success message."""
+    click.echo(f"✅ {message}")
+
+
+def print_error(message: str) -> None:
+    """Print an error message to stderr."""
+    click.echo(f"❌ {message}", err=True)
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message."""
+    click.echo(f"⚠️  {message}")
+
+
+def print_info(message: str) -> None:
+    """Print an info message."""
+    click.echo(f"ℹ️  {message}")