Update for CLI (#636)

(1) Custom Tool fix
(2) Include more tips and helps with CLI, including a CLI_EXAMPLE.md with @JohanHoltby's feedback!

Author: Scriptwonder

Server/src/cli/CLI_USAGE_GUIDE.md

@@ -533,6 +533,18 @@ unity-mcp editor tests
 unity-mcp editor tests --mode PlayMode
 ```
 
+### Custom Tools
+
+```bash
+# List custom tools / default tools for the active Unity project
+unity-mcp tool list
+unity-mcp custom_tool list
+
+# Execute a custom tool by name
+unity-mcp editor custom-tool "MyBuildTool"
+unity-mcp editor custom-tool "Deploy" --params '{"target": "Android"}'
+```
+
 ### Prefab Commands
 
 ```bash

Server/src/cli/commands/editor.py

@@ -6,7 +6,8 @@
 
 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, run_list_custom_tools, UnityConnectionError
+from cli.utils.suggestions import suggest_matches, format_suggestions
 
 
 @click.group()
@@ -472,6 +473,8 @@ def custom_tool(tool_name: str, params: str):
         params_dict = json.loads(params)
     except json.JSONDecodeError as e:
         print_error(f"Invalid JSON for params: {e}")
+        print_info("Example: --params '{\"key\":\"value\"}'")
+        print_info("Tip: wrap JSON in single quotes to avoid shell escaping issues.")
         sys.exit(1)
 
     try:
@@ -482,6 +485,26 @@ def custom_tool(tool_name: str, params: str):
         click.echo(format_output(result, config.format))
         if result.get("success"):
             print_success(f"Executed custom tool: {tool_name}")
+        else:
+            message = (result.get("message") or result.get("error") or "").lower()
+            if "not found" in message and "tool" in message:
+                try:
+                    tools_result = run_list_custom_tools(config)
+                    tools = tools_result.get("tools")
+                    if tools is None:
+                        data = tools_result.get("data", {})
+                        tools = data.get("tools") if isinstance(data, dict) else None
+                    names = [
+                        t.get("name") for t in tools if isinstance(t, dict) and t.get("name")
+                    ] if isinstance(tools, list) else []
+                    matches = suggest_matches(tool_name, names)
+                    suggestion = format_suggestions(matches)
+                    if suggestion:
+                        print_info(suggestion)
+                        print_info(
+                            f'Example: unity-mcp editor custom-tool "{matches[0]}"')
+                except UnityConnectionError:
+                    pass
     except UnityConnectionError as e:
         print_error(str(e))
         sys.exit(1)

Server/src/cli/commands/tool.py

@@ -0,0 +1,61 @@
+"""Tool CLI commands for listing custom tools."""
+
+import sys
+import click
+
+from cli.utils.config import get_config
+from cli.utils.output import format_output, print_error
+from cli.utils.connection import run_list_custom_tools, UnityConnectionError
+
+
+def _list_custom_tools() -> None:
+    config = get_config()
+    try:
+        result = run_list_custom_tools(config)
+        if config.format != "text":
+            click.echo(format_output(result, config.format))
+            return
+
+        if not isinstance(result, dict) or not result.get("success", True):
+            click.echo(format_output(result, config.format))
+            return
+
+        tools = result.get("tools")
+        if tools is None:
+            data = result.get("data", {})
+            tools = data.get("tools") if isinstance(data, dict) else None
+        if not isinstance(tools, list):
+            click.echo(format_output(result, config.format))
+            return
+
+        click.echo(f"Custom tools ({len(tools)}):")
+        for i, tool in enumerate(tools):
+            name = tool.get("name") if isinstance(tool, dict) else str(tool)
+            click.echo(f"  [{i}] {name}")
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@click.group("tool")
+def tool():
+    """Tool management - list custom tools for the active Unity project."""
+    pass
+
+
+@tool.command("list")
+def list_tools():
+    """List custom tools registered for the active Unity project."""
+    _list_custom_tools()
+
+
+@click.group("custom_tool")
+def custom_tool():
+    """Alias for tool management (custom tools)."""
+    pass
+
+
+@custom_tool.command("list")
+def list_custom_tools():
+    """List custom tools registered for the active Unity project."""
+    _list_custom_tools()

Server/src/cli/main.py

@@ -8,6 +8,7 @@
 
 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,
@@ -28,6 +29,35 @@ def __init__(self):
 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(
@@ -212,6 +242,8 @@ def register_optional_command(module_name: str, command_name: str) -> None:
         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"),

Server/src/cli/utils/connection.py

@@ -189,3 +189,40 @@ async def list_unity_instances(config: Optional[CLIConfig] = None) -> Dict[str,
 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))

Server/src/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}"