mcpforunityserver 9.4.0b20260203025228__py3-none-any.whl

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}")

cli/utils/parsers.py

@@ -0,0 +1,112 @@
+"""JSON and value parsing utilities for CLI commands."""
+import json
+import sys
+from typing import Any
+
+from cli.utils.output import print_error, print_info
+
+
+def parse_value_safe(value: str) -> Any:
+    """Parse a value, trying JSON → float → string fallback.
+
+    This is used for property values that could be JSON objects/arrays,
+    numbers, or strings. Never raises an exception.
+
+    Args:
+        value: The string value to parse
+
+    Returns:
+        Parsed JSON object/array, float, or original string
+
+    Examples:
+        >>> parse_value_safe('{"x": 1}')
+        {'x': 1}
+        >>> parse_value_safe('3.14')
+        3.14
+        >>> parse_value_safe('hello')
+        'hello'
+    """
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        # Try to parse as number
+        try:
+            return float(value)
+        except ValueError:
+            # Keep as string
+            return value
+
+
+def parse_json_or_exit(value: str, context: str = "parameter") -> Any:
+    """Parse JSON string, trying to fix common issues, or exit with error.
+
+    Attempts to parse JSON with automatic fixes for:
+    - Single quotes instead of double quotes
+    - Python-style True/False instead of true/false
+
+    Args:
+        value: The JSON string to parse
+        context: Description of what's being parsed (for error messages)
+
+    Returns:
+        Parsed JSON object
+
+    Exits:
+        Calls sys.exit(1) if JSON is invalid after attempting fixes
+    """
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        # Try to fix common shell quoting issues (single quotes, Python bools)
+        try:
+            fixed = value.replace("'", '"').replace("True", "true").replace("False", "false")
+            return json.loads(fixed)
+        except json.JSONDecodeError as e:
+            print_error(f"Invalid JSON for {context}: {e}")
+            print_info("Example: --params '{\"key\":\"value\"}'")
+            print_info("Tip: wrap JSON in single quotes to avoid shell escaping issues.")
+            sys.exit(1)
+
+
+def parse_json_dict_or_exit(value: str, context: str = "parameter") -> dict[str, Any]:
+    """Parse JSON object (dict), or exit with error.
+
+    Like parse_json_or_exit, but ensures result is a dictionary.
+
+    Args:
+        value: The JSON string to parse
+        context: Description of what's being parsed (for error messages)
+
+    Returns:
+        Parsed JSON object as dictionary
+
+    Exits:
+        Calls sys.exit(1) if JSON is invalid or not an object
+    """
+    result = parse_json_or_exit(value, context)
+    if not isinstance(result, dict):
+        print_error(f"Invalid JSON for {context}: expected an object, got {type(result).__name__}")
+        sys.exit(1)
+    return result
+
+
+def parse_json_list_or_exit(value: str, context: str = "parameter") -> list[Any]:
+    """Parse JSON array (list), or exit with error.
+
+    Like parse_json_or_exit, but ensures result is a list.
+
+    Args:
+        value: The JSON string to parse
+        context: Description of what's being parsed (for error messages)
+
+    Returns:
+        Parsed JSON array as list
+
+    Exits:
+        Calls sys.exit(1) if JSON is invalid or not an array
+    """
+    result = parse_json_or_exit(value, context)
+    if not isinstance(result, list):
+        print_error(f"Invalid JSON for {context}: expected an array, got {type(result).__name__}")
+        sys.exit(1)
+    return result

cli/utils/suggestions.py

@@ -0,0 +1,34 @@
+"""Helpers for CLI suggestion messages."""
+
+from __future__ import annotations
+
+import difflib
+from typing import Iterable, List
+
+
+def suggest_matches(
+    value: str,
+    choices: Iterable[str],
+    *,
+    limit: int = 3,
+    cutoff: float = 0.6,
+) -> List[str]:
+    """Return close matches for a value from a list of choices."""
+    try:
+        normalized = [c for c in choices if isinstance(c, str)]
+    except Exception:
+        normalized = []
+    if not value or not normalized:
+        return []
+    return difflib.get_close_matches(value, normalized, n=limit, cutoff=cutoff)
+
+
+def format_suggestions(matches: Iterable[str]) -> str | None:
+    """Format matches into a CLI-friendly suggestion string."""
+    items = [m for m in matches if m]
+    if not items:
+        return None
+    if len(items) == 1:
+        return f"Did you mean: {items[0]}"
+    joined = ", ".join(items)
+    return f"Did you mean one of: {joined}"

core/config.py

@@ -0,0 +1,67 @@
+"""
+Configuration settings for the MCP for Unity Server.
+This file contains all configurable parameters for the server.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ServerConfig:
+    """Main configuration class for the MCP server."""
+
+    # Network settings
+    unity_host: str = "localhost"
+    unity_port: int = 6400
+    mcp_port: int = 6500
+
+    # Transport settings
+    transport_mode: str = "stdio"
+
+    # HTTP transport behaviour
+    http_remote_hosted: bool = False
+
+    # API key authentication (required when http_remote_hosted=True)
+    api_key_validation_url: str | None = None  # POST endpoint to validate keys
+    api_key_login_url: str | None = None       # URL for users to get/manage keys
+    # Cache TTL in seconds (5 min default)
+    api_key_cache_ttl: float = 300.0
+    # Optional service token for authenticating to the validation endpoint
+    api_key_service_token_header: str | None = None  # e.g. "X-Service-Token"
+    api_key_service_token: str | None = None         # The token value
+
+    # Connection settings
+    connection_timeout: float = 30.0
+    buffer_size: int = 16 * 1024 * 1024  # 16MB buffer
+
+    # STDIO framing behaviour
+    require_framing: bool = True
+    handshake_timeout: float = 1.0
+    framed_receive_timeout: float = 2.0
+    max_heartbeat_frames: int = 16
+    heartbeat_timeout: float = 2.0
+
+    # Logging settings
+    log_level: str = "INFO"
+    log_format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+    # Server settings
+    max_retries: int = 5
+    retry_delay: float = 0.25
+    # Backoff hint returned to clients when Unity is reloading (milliseconds)
+    reload_retry_ms: int = 250
+    # Number of polite retries when Unity reports reloading
+    # 40 × 250ms ≈ 10s default window
+    reload_max_retries: int = 40
+
+    # Port discovery cache
+    port_registry_ttl: float = 5.0
+
+    # Telemetry settings
+    telemetry_enabled: bool = True
+    # Align with telemetry.py default Cloud Run endpoint
+    telemetry_endpoint: str = "https://api-prod.coplay.dev/telemetry/events"
+
+
+# Create a global config instance
+config = ServerConfig()

core/constants.py

@@ -0,0 +1,4 @@
+"""Server-wide protocol constants."""
+
+# HTTP header name for API key authentication
+API_KEY_HEADER = "X-API-Key"

core/logging_decorator.py

@@ -0,0 +1,37 @@
+import functools
+import inspect
+import logging
+from typing import Callable, Any
+
+logger = logging.getLogger("mcp-for-unity-server")
+
+
+def log_execution(name: str, type_label: str):
+    """Decorator to log input arguments and return value of a function."""
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def _sync_wrapper(*args, **kwargs) -> Any:
+            logger.info(
+                f"{type_label} '{name}' called with args={args} kwargs={kwargs}")
+            try:
+                result = func(*args, **kwargs)
+                logger.info(f"{type_label} '{name}' returned: {result}")
+                return result
+            except Exception as e:
+                logger.info(f"{type_label} '{name}' failed: {e}")
+                raise
+
+        @functools.wraps(func)
+        async def _async_wrapper(*args, **kwargs) -> Any:
+            logger.info(
+                f"{type_label} '{name}' called with args={args} kwargs={kwargs}")
+            try:
+                result = await func(*args, **kwargs)
+                logger.info(f"{type_label} '{name}' returned: {result}")
+                return result
+            except Exception as e:
+                logger.info(f"{type_label} '{name}' failed: {e}")
+                raise
+
+        return _async_wrapper if inspect.iscoroutinefunction(func) else _sync_wrapper
+    return decorator