Imported from NaturaAurum/uni-cli (AGENTS.md). Install upstream with npx skills add NaturaAurum/uni-cli. Copyright stays with the author.

PROJECT KNOWLEDGE BASE

Generated: 2026-02-28T14:17:09Z | Commit: c537e24 | Branch: main

OVERVIEW

Token-efficient CLI + Unity Editor tools extending unity-mcp. Two deliverables: UPM package (C# subsystem tools auto-registered via MCP) and Python CLI (compact output, 31x schema reduction).

STRUCTURE

uni-cli/
├── package/          # UPM package — C# tools for UI Toolkit, Addressables, DOTS, Shader Graph
├── cli/              # Python CLI — compact MCP wrapper (pip install uni-cli)
├── bench/            # 3-tier benchmark framework (per-response, E2E, schema overhead)
├── docs/             # Design docs — CLI output contract, benchmark design
└── unity-project/    # Dev Unity project (2022.3) — local package ref + bench scenes

WHERE TO LOOK

CONVENTIONS

• MCP params: snake_case always (search_pattern not searchPattern)
• Commits: semantic English (feat:, fix:, chore:, docs:)
• C#: PascalCase. Editor-only. MCPForUnity.Editor.Helpers for responses
• Python: snake_case. from __future__ import annotations. Zero deps (stdlib only)

ANTI-PATTERNS (THIS PROJECT)

• NEVER add Python runtime dependencies — CLI is stdlib-only by design
• NEVER reference optional Unity packages directly in C# — use Type.GetType() reflection (see ManageAddressables.cs)
• NEVER suppress type errors — no as any, @ts-ignore, # type: ignore
• NEVER hardcode asset paths — normalize with Replace("\\", "/"), validate starts with Assets/ or Packages/
• NEVER return stack traces in MCP responses — use ErrorResponse("descriptive message") only

UNIQUE STYLES

C# Tool Pattern (all 4 tools follow this exactly)

[McpForUnityTool("manage_<subsystem>")]
public class Manage<Subsystem>
{
    public static object HandleCommand(JObject @params)
    {
        string action = @params["action"]?.ToString()?.ToLowerInvariant();
        try {
            switch (action) {
                case "<action>": return Handle<Action>(@params);
                default: return new ErrorResponse($"Unknown action: {action}");
            }
        } catch (Exception ex) {
            return new ErrorResponse($"Error in {action}: {ex.Message}");
        }
    }
}

Python Command Pattern

def run_<action>(client: McpClient, instance_id: str, **kwargs) -> dict:
    result = client.call_tool("manage_<tool>", {"action": "<action>", ...})
    return parse_result_json(result)

CLI Output Contract

Collections: row field1=val1 field2=val2 per item, ending with ok op=<op> count=<n> next=<cursor> truncated=<0|1>.

COMMANDS

PYTHONPATH=cli/src python3 -m uni_cli.main hierarchy ls --limit 10          # dev
uni-cli hierarchy ls --instance MyProject --limit 50                         # installed
python3 bench/scripts/run_real_benchmark.py \
  --url http://127.0.0.1:8080/mcp --unity-instance uni-cli \
  --iterations 10 --warmup 2 --repetitions 2 \
  --scene-profile all --out bench/reports/tier1-corrected.json               # bench
python3 bench/scripts/analyze_schema_overhead.py --url http://127.0.0.1:8080/mcp  # schema

NOTES

• MCP at http://127.0.0.1:8080/mcp (Streamable HTTP, not WebSocket)
• Instance ID: <project>@<hex> — CLI resolves by prefix/name match
• unity-project/ dev only — users install UPM via git URL
• Bench scenes auto-generated by BenchSceneBuilder.cs — don't hand-edit
• [McpForUnityTool] → auto-discovery via CommandRegistry.Initialize() reflection scan