unity-mcp-cli 0.1.0__tar.gz

unity_mcp_cli-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Unity
+unity-project/Library/
+unity-project/Temp/
+unity-project/Logs/
+unity-project/UserSettings/
+unity-project/obj/
+unity-project/*.csproj
+unity-project/*.sln
+*.meta
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+*.egg
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Benchmark temp files
+*.log
+*.pid
+bench/reports/*.log
+bench/reports/*.pid
+
+# Session / conversation logs
+docs/conversation-*.md
+bench/reports/conversation-*.md

unity_mcp_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArtisanCodesmith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unity_mcp_cli-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: unity-mcp-cli
+Version: 0.1.0
+Summary: Token-efficient CLI for LLM agents to control Unity Editor
+Project-URL: Homepage, https://github.com/NaturaAurum/uni-cli
+Project-URL: Repository, https://github.com/NaturaAurum/uni-cli
+Project-URL: Issues, https://github.com/NaturaAurum/uni-cli/issues
+Author: ArtisanCodesmith
+License: MIT License
+        
+        Copyright (c) 2026 ArtisanCodesmith
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,cli,llm,mcp,unity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# uni-cli
+
+Token-efficient CLI for LLM agents to control Unity Editor via [MCP](https://modelcontextprotocol.io). Reduces token overhead by ~31x compared to raw MCP tool schemas.
+
+Part of the [uni-cli](https://github.com/NaturaAurum/uni-cli) project — extends [unity-mcp](https://github.com/CoplayDev/unity-mcp) with additional Unity subsystem tools.
+
+## Why
+
+LLM agents talking to Unity through MCP pay a heavy token tax — large tool schemas and verbose JSON responses eat context window budget. uni-cli solves this with a compact CLI layer:
+
+| Metric | Value |
+|--------|-------|
+| Per-response output reduction | **79–98%** (median 92.8%) |
+| Tool schema overhead | **MCP 14,877 → CLI 480 tokens** (31x reduction) |
+
+## Install
+
+```bash
+pip install unity-mcp-cli
+```
+
+**Prerequisites:**
+- Python 3.10+
+- [unity-mcp](https://github.com/CoplayDev/unity-mcp) running in your Unity project
+
+## Usage
+
+```bash
+# List scene hierarchy (compact output)
+uni-cli hierarchy ls --instance MyProject --fields id,name,parent --limit 50
+
+# Create a GameObject
+uni-cli object create --instance MyProject --name "Player" --preset Cube --pos 0,1,0
+
+# Search assets
+uni-cli asset search --instance MyProject --query "*.prefab" --limit 20
+
+# Get full JSON output
+uni-cli hierarchy ls --format json --limit 10
+
+# List available MCP tools
+uni-cli tools
+```
+
+### Output Format
+
+Compact row-based format designed for minimal token usage:
+
+```
+row id=12345 name="Main Camera" active=1 parent=-1
+row id=12346 name="Directional Light" active=1 parent=-1
+ok op=hierarchy.ls count=2 next="" truncated=0
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `hierarchy ls` | List scene hierarchy |
+| `object create/get/modify/delete` | GameObject operations |
+| `asset search/info/create/delete` | Asset operations |
+| `batch apply` | Execute batch commands from file |
+| `ui-toolkit <action>` | UI Toolkit (UXML, USS, VisualElement) |
+| `addressables <action>` | Addressable Asset System |
+| `dots <action>` | DOTS / ECS |
+| `shader-graph <action>` | Shader Graph |
+| `tools` | List available MCP tools |
+
+### Global Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--url` | `http://127.0.0.1:8080/mcp` | MCP server URL |
+| `--instance` | auto-detect | Unity instance selector |
+| `--format` | `compact` | Output format (`compact` or `json`) |
+| `--timeout` | `30` | Request timeout in seconds |
+
+## Zero Dependencies
+
+uni-cli uses only Python standard library — no external packages required.
+
+## License
+
+[MIT](https://github.com/NaturaAurum/uni-cli/blob/main/LICENSE)

unity_mcp_cli-0.1.0/README.md

@@ -0,0 +1,84 @@
+# uni-cli
+
+Token-efficient CLI for LLM agents to control Unity Editor via [MCP](https://modelcontextprotocol.io). Reduces token overhead by ~31x compared to raw MCP tool schemas.
+
+Part of the [uni-cli](https://github.com/NaturaAurum/uni-cli) project — extends [unity-mcp](https://github.com/CoplayDev/unity-mcp) with additional Unity subsystem tools.
+
+## Why
+
+LLM agents talking to Unity through MCP pay a heavy token tax — large tool schemas and verbose JSON responses eat context window budget. uni-cli solves this with a compact CLI layer:
+
+| Metric | Value |
+|--------|-------|
+| Per-response output reduction | **79–98%** (median 92.8%) |
+| Tool schema overhead | **MCP 14,877 → CLI 480 tokens** (31x reduction) |
+
+## Install
+
+```bash
+pip install unity-mcp-cli
+```
+
+**Prerequisites:**
+- Python 3.10+
+- [unity-mcp](https://github.com/CoplayDev/unity-mcp) running in your Unity project
+
+## Usage
+
+```bash
+# List scene hierarchy (compact output)
+uni-cli hierarchy ls --instance MyProject --fields id,name,parent --limit 50
+
+# Create a GameObject
+uni-cli object create --instance MyProject --name "Player" --preset Cube --pos 0,1,0
+
+# Search assets
+uni-cli asset search --instance MyProject --query "*.prefab" --limit 20
+
+# Get full JSON output
+uni-cli hierarchy ls --format json --limit 10
+
+# List available MCP tools
+uni-cli tools
+```
+
+### Output Format
+
+Compact row-based format designed for minimal token usage:
+
+```
+row id=12345 name="Main Camera" active=1 parent=-1
+row id=12346 name="Directional Light" active=1 parent=-1
+ok op=hierarchy.ls count=2 next="" truncated=0
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `hierarchy ls` | List scene hierarchy |
+| `object create/get/modify/delete` | GameObject operations |
+| `asset search/info/create/delete` | Asset operations |
+| `batch apply` | Execute batch commands from file |
+| `ui-toolkit <action>` | UI Toolkit (UXML, USS, VisualElement) |
+| `addressables <action>` | Addressable Asset System |
+| `dots <action>` | DOTS / ECS |
+| `shader-graph <action>` | Shader Graph |
+| `tools` | List available MCP tools |
+
+### Global Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--url` | `http://127.0.0.1:8080/mcp` | MCP server URL |
+| `--instance` | auto-detect | Unity instance selector |
+| `--format` | `compact` | Output format (`compact` or `json`) |
+| `--timeout` | `30` | Request timeout in seconds |
+
+## Zero Dependencies
+
+uni-cli uses only Python standard library — no external packages required.
+
+## License
+
+[MIT](https://github.com/NaturaAurum/uni-cli/blob/main/LICENSE)

unity_mcp_cli-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "unity-mcp-cli"
+version = "0.1.0"
+description = "Token-efficient CLI for LLM agents to control Unity Editor"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10"
+authors = [
+    { name = "ArtisanCodesmith" },
+]
+keywords = ["unity", "llm", "cli", "mcp", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/NaturaAurum/uni-cli"
+Repository = "https://github.com/NaturaAurum/uni-cli"
+Issues = "https://github.com/NaturaAurum/uni-cli/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.scripts]
+uni-cli = "uni_cli.main:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uni_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/uni_cli", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"LICENSE" = "uni_cli/LICENSE"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]

unity_mcp_cli-0.1.0/src/uni_cli/__init__.py

@@ -0,0 +1,8 @@
+"""uni-cli: Token-efficient CLI for LLM agents to control Unity Editor."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("uni-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

unity_mcp_cli-0.1.0/src/uni_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command implementations."""

unity_mcp_cli-0.1.0/src/uni_cli/commands/asset.py

@@ -0,0 +1,94 @@
+"""asset subcommand — Asset operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from uni_cli.transport.mcp_client import McpClient, extract_text, parse_result_json
+
+
+def run_search(
+    client: McpClient,
+    instance_id: str,
+    query: str,
+    filter_type: str | None,
+    fields: str,
+    limit: int,
+) -> dict[str, Any]:
+    """Search assets via manage_asset search."""
+    args: dict[str, Any] = {
+        "action": "search",
+        "path": "Assets",
+        "page_size": limit,
+        "page_number": 1,
+        "generate_preview": False,
+        "unity_instance": instance_id,
+    }
+    if query:
+        args["search_pattern"] = query
+    if filter_type:
+        args["filter_type"] = filter_type
+    result = client.call_tool("manage_asset", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}
+
+
+def run_info(
+    client: McpClient,
+    instance_id: str,
+    path: str,
+) -> dict[str, Any]:
+    """Get asset info via manage_asset get_info."""
+    args: dict[str, Any] = {
+        "action": "get_info",
+        "path": path,
+        "unity_instance": instance_id,
+    }
+    result = client.call_tool("manage_asset", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}
+
+
+def run_create(
+    client: McpClient,
+    instance_id: str,
+    path: str,
+    asset_type: str,
+    **properties: Any,
+) -> dict[str, Any]:
+    """Create an asset via manage_asset create."""
+    args: dict[str, Any] = {
+        "action": "create",
+        "path": path,
+        "asset_type": asset_type,
+        "unity_instance": instance_id,
+    }
+    if properties:
+        args["properties"] = properties
+    result = client.call_tool("manage_asset", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}
+
+
+def run_delete(
+    client: McpClient,
+    instance_id: str,
+    path: str,
+) -> dict[str, Any]:
+    """Delete an asset via manage_asset delete."""
+    args: dict[str, Any] = {
+        "action": "delete",
+        "path": path,
+        "unity_instance": instance_id,
+    }
+    result = client.call_tool("manage_asset", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}

unity_mcp_cli-0.1.0/src/uni_cli/commands/batch.py

@@ -0,0 +1,43 @@
+"""batch subcommand — Batch operations."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from uni_cli.transport.mcp_client import McpClient, extract_text, parse_result_json
+
+
+def run_apply(
+    client: McpClient,
+    instance_id: str,
+    file_path: str,
+) -> dict[str, Any]:
+    """Execute batch commands from a JSON file via batch_execute."""
+    with open(file_path) as f:
+        batch_data = json.load(f)
+
+    # Batch file format: {"commands": [{"tool": "...", "params": {...}}, ...]}
+    commands = batch_data.get("commands", [])
+    if not commands:
+        return {"success": False, "error": "No commands in batch file"}
+
+    # Inject unity_instance into each command's params
+    for cmd in commands:
+        params = cmd.get("params", {})
+        if "unity_instance" not in params:
+            params["unity_instance"] = instance_id
+        cmd["params"] = params
+
+    args: dict[str, Any] = {
+        "commands": commands,
+        "parallel": batch_data.get("parallel", False),
+        "fail_fast": batch_data.get("fail_fast", True),
+        "max_parallelism": batch_data.get("max_parallelism", 1),
+        "unity_instance": instance_id,
+    }
+    result = client.call_tool("batch_execute", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}

unity_mcp_cli-0.1.0/src/uni_cli/commands/hierarchy.py

@@ -0,0 +1,31 @@
+"""hierarchy subcommand — Scene hierarchy operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from uni_cli.transport.mcp_client import McpClient, extract_text, parse_result_json
+
+
+def run_ls(
+    client: McpClient,
+    instance_id: str,
+    fields: str,
+    limit: int,
+    cursor: str,
+) -> dict[str, Any]:
+    """List scene hierarchy via manage_scene get_hierarchy."""
+    args: dict[str, Any] = {
+        "action": "get_hierarchy",
+        "page_size": limit,
+        "cursor": int(cursor) if cursor.isdigit() else 0,
+        "include_transform": True,
+        "max_depth": 4,
+        "unity_instance": instance_id,
+    }
+    result = client.call_tool("manage_scene", args)
+    text = extract_text(result)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": text}

unity_mcp_cli-0.1.0/src/uni_cli/commands/object.py

@@ -0,0 +1,102 @@
+"""object subcommand — GameObject operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from uni_cli.transport.mcp_client import McpClient, extract_text, parse_result_json
+
+
+def run_create(
+    client: McpClient,
+    instance_id: str,
+    name: str,
+    preset: str,
+    pos: str,
+) -> dict[str, Any]:
+    """Create a GameObject via manage_gameobject create."""
+    position = [float(x) for x in pos.split(",")]
+    args: dict[str, Any] = {
+        "action": "create",
+        "name": name,
+        "unity_instance": instance_id,
+    }
+    if preset != "empty":
+        args["primitive_type"] = preset
+    if position != [0.0, 0.0, 0.0]:
+        args["position"] = position
+    result = client.call_tool("manage_gameobject", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}
+
+
+def run_get(
+    client: McpClient,
+    instance_id: str,
+    target: str,
+) -> dict[str, Any]:
+    """Get GameObject info via manage_gameobject get."""
+    args: dict[str, Any] = {
+        "action": "get",
+        "target": target,
+        "search_method": "by_name",
+        "unity_instance": instance_id,
+    }
+    result = client.call_tool("manage_gameobject", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}
+
+
+def run_modify(
+    client: McpClient,
+    instance_id: str,
+    target: str,
+    *,
+    pos: str | None = None,
+    parent: str | None = None,
+    name: str | None = None,
+    active: bool | None = None,
+) -> dict[str, Any]:
+    """Modify a GameObject via manage_gameobject modify."""
+    args: dict[str, Any] = {
+        "action": "modify",
+        "target": target,
+        "search_method": "by_name",
+        "unity_instance": instance_id,
+    }
+    if pos is not None:
+        args["position"] = [float(x) for x in pos.split(",")]
+    if parent is not None:
+        args["parent"] = parent
+    if name is not None:
+        args["name"] = name
+    if active is not None:
+        args["active"] = active
+    result = client.call_tool("manage_gameobject", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}
+
+
+def run_delete(
+    client: McpClient,
+    instance_id: str,
+    target: str,
+) -> dict[str, Any]:
+    """Delete a GameObject via manage_gameobject delete."""
+    args: dict[str, Any] = {
+        "action": "delete",
+        "target": target,
+        "search_method": "by_name",
+        "unity_instance": instance_id,
+    }
+    result = client.call_tool("manage_gameobject", args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}

unity_mcp_cli-0.1.0/src/uni_cli/commands/subsystem.py

@@ -0,0 +1,53 @@
+"""Subsystem commands — ui-toolkit, addressables, dots, shader-graph.
+
+These proxy to the uni-cli UPM package tools (manage_ui_toolkit, etc.)
+which are auto-registered via [McpForUnityTool] attribute.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from uni_cli.transport.mcp_client import McpClient, extract_text, parse_result_json
+
+# Tool name mapping: CLI command name -> MCP tool name
+_TOOL_MAP = {
+    "ui-toolkit": "manage_ui_toolkit",
+    "addressables": "manage_addressables",
+    "dots": "manage_dots",
+    "shader-graph": "manage_shader_graph",
+}
+
+
+def run_subsystem(
+    client: McpClient,
+    instance_id: str,
+    command: str,
+    action: str,
+    extra_args: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Generic dispatcher for subsystem tool commands.
+
+    Args:
+        client: MCP client
+        instance_id: Unity instance ID
+        command: CLI command name (e.g. "ui-toolkit")
+        action: Tool action (e.g. "list_documents")
+        extra_args: Additional parameters for the tool
+    """
+    tool_name = _TOOL_MAP.get(command)
+    if not tool_name:
+        return {"success": False, "error": f"Unknown subsystem: {command}"}
+
+    args: dict[str, Any] = {
+        "action": action,
+        "unity_instance": instance_id,
+    }
+    if extra_args:
+        args.update(extra_args)
+
+    result = client.call_tool(tool_name, args)
+    parsed = parse_result_json(result)
+    if parsed is not None:
+        return parsed
+    return {"raw_text": extract_text(result)}

unity_mcp_cli-0.1.0/src/uni_cli/formatter/__init__.py

@@ -0,0 +1 @@
+"""Compact output formatters for uni-cli."""