Npm command for Unity operations

[IvanMurzak]

We need to have npm (or npx, what is better?) command line app for making basic Unity operations. Make the folder "GameDev-cli" for the project at the root of the repository. The app must be operational on Linux, Mac and Windows.

Commands:

• Open Unity Project in Unity Editor
• Install Unity MCP as a dependency into the Unity project with an option to install latest version or a specified.
• Set list of enabled MCP Tools
• Set list of enabled MCP Prompts
• Set list of enabled MCP Resources
• Open Unity and Enforce Unity MCP connection to specified URL to MCP server by calling a new C# method which you will need to develop specifically for this command. The method must be in Unity-MCP-Plugin project under Editor folder because it is only for Unity Editor.

To set list of MCP features you will need to modify json file or to create it if it doesn't exist yet. That is AI-Game-Developer-Config.json file. Which is generated usually by Unity-MCP-Plugin as only Unity Editor is opened with Unity MCP package installed.

[IvanMurzak]

@claude it is your time!
Analyze the task, find the efficient and easy to maintain the future strategy. Implement it.

[claude]

Claude finished @IvanMurzak's task in 10m 6s —— View job • claude/issue-493-20260224-0833 • Create PR ➔

---

Implementation Complete

Tasks

• Gather context and analyze the codebase
• Design GameDev-cli architecture and file structure
• Create all GameDev-cli files (package.json, bin, commands, utils)
• Create C# CommandLineArgs.cs in Unity-MCP-Plugin/Assets/root/Editor/Scripts/
• Commit and push all changes

---

What was implemented

GameDev-cli/ — pure Node.js ESM CLI, no build step, works on Linux / macOS / Windows.

Usage

# Without global install
npx gamedev-cli <command> [options]

# After global install: npm install -g gamedev-cli
gamedev <command> [options]

Commands

Command	Description
open <project-path>	Open a Unity project in Unity Editor (auto-detects Unity Hub or installed editors)
install-mcp <project-path>	Add com.ivanmurzak.unity.mcp to Packages/manifest.json via OpenUPM (latest or --version <v>)
set-tools <project-path> [names...]	Set which MCP Tools are enabled in AI-Game-Developer-Config.json
set-prompts <project-path> [names...]	Set which MCP Prompts are enabled
set-resources <project-path> [names...]	Set which MCP Resources are enabled
connect <project-path> --url <url>	Update config host URL and open Unity with -mcpServerUrl arg

set-* flag options

• --all — clear the list (Unity enables everything by default)
• --disable name1,name2 — disable specific items, preserve the rest
• Positional names — set exactly these as enabled

Unity-MCP-Plugin addition: CommandLineArgs.cs

• [InitializeOnLoad] reads -mcpServerUrl <url> from Unity's command-line args at Editor startup
• Calls EnforceConnect(url) which: updates UnityMcpPlugin.Host, saves AI-Game-Developer-Config.json, then calls UnityMcpPlugin.Connect()
• EnforceConnect(string url) is also a public static method usable from other Editor scripts

File structure

GameDev-cli/
├── package.json          (name: gamedev-cli, bin: gamedev)
├── bin/gamedev.js        (entry point, shebang, commander setup)
└── src/
    ├── commands/
    │   ├── open.js
    │   ├── install-mcp.js
    │   ├── set-features.js   (registers set-tools, set-prompts, set-resources)
    │   └── connect.js
    └── utils/
        ├── config.js         (read/write AI-Game-Developer-Config.json)
        ├── unity.js          (Unity Hub / direct exe detection + spawn)
        └── manifest.js       (Packages/manifest.json + OpenUPM scoped registry)

Unity-MCP-Plugin/Assets/root/Editor/Scripts/CommandLineArgs.cs

|

[IvanMurzak]

@claude need to cover heavily with tests the GameDev-cli project. And also, need to cover with tests in Unity-MCP-Plugin project the CommandLineArgs.cs.

Can we make this method public static void EnforceConnect(string url) to return an error when it is called from command line? If so, lets do it, because we will need to see when something get wrong. And provide detailed error information.

[claude]

Claude finished @IvanMurzak's task in 15m 49s —— View job • claude/issue-493-20260224-0912 • Create PR ➔

---

Tasks

• Gather context and read existing implementation from previous branch
• Analyze Unity test patterns and project structure
• Copy GameDev-cli source files and set up Vitest testing framework
• Modify EnforceConnect → returns ConnectResult + writes result file for CLI feedback
• Update CLI connect command with --wait option to poll result file and report errors
• Write comprehensive Vitest tests for all GameDev-cli modules — 93 tests, all passing
• Write Unity EditMode tests for CommandLineArgs.cs — 21 tests
• Commit and push all changes

---

What was implemented

EnforceConnect now returns ConnectResult

// Before
public static void EnforceConnect(string url)

// After
public static ConnectResult EnforceConnect(string url)

ConnectResult is a new readonly struct in CommandLineArgs.cs:

Field	Type	Description
Success	bool	Whether the connection was established
ErrorMessage	string?	Human-readable error (exception message or validation error)
ErrorType	string?	Full exception type name (e.g. System.InvalidOperationException)
StackTrace	string?	Exception stack trace

When triggered via -mcpServerUrl from CLI:

• Writes Library/mcp-connect-result.json with the full result (success/errorType/errorMessage/stackTrace/timestamp)
• On failure: calls EditorApplication.Exit(1) so the calling process gets a non-zero exit code

connect command updated with --wait flag

# Open Unity and wait up to 60s for result, reporting any errors:
gamedev connect ./MyGame --url http://localhost:8080 --wait

# Custom timeout:
gamedev connect ./MyGame --url http://localhost:8080 --wait --wait-timeout 120

When --wait is used, the CLI polls Library/mcp-connect-result.json and exits with code 1 + detailed error output on failure.

GameDev-cli Tests (Vitest, 93 tests)

File	Coverage
tests/utils/config.test.js	readConfig, writeConfig, getConfigPath — parsing, defaults, missing file, invalid JSON, directory creation
tests/utils/manifest.test.js	installUnityMcp — scoped registry, scopes, version update, missing/invalid manifest; fetchLatestVersion — dist-tags, fallback on error
tests/utils/unity.test.js	findUnityHub, findUnityExecutable, openUnityProject (detach/no-detach, extraArgs, error), pollForFile, getConnectResultPath
tests/commands/open.test.js	registerOpenCommand — path resolution, option forwarding, error handling
tests/commands/install-mcp.test.js	registerInstallMcpCommand — auto-fetch vs explicit version, error handling
tests/commands/set-features.test.js	buildFeatureList (all modes), parseCommaSeparated, CLI integration (set-tools/set-prompts/set-resources, --all, --disable, error case)
tests/commands/connect.test.js	registerConnectCommand — config update, stale file cleanup, --wait polling, success/error reporting, --unity-path, --wait-timeout

Unity EditMode Tests (21 tests)

Unity-MCP-Plugin/Assets/root/Tests/Editor/CommandLineArgs/CommandLineArgsTests.cs

• ConnectResult.Ok() — Success=true, all error fields null
• ConnectResult.Fail(string) — Success=false, message preserved, exception fields null
• ConnectResult.Fail(Exception) — captures message, full type name, stack trace
• ConnectResult.ToString() — [Success] / [Error] markers, message included
• Value semantics — two Ok results are equal, Ok ≠ Fail
• EnforceConnect(""), null, " " → all return ConnectResult.Fail (no UnityMcpPlugin needed)
• ConnectResultRelativePath — non-empty, starts with "Library", ends with ".json"

• claude/issue-493-20260224-0912