unity-mcp-cli 1.1.0 → 1.3.0

package/docs/README.es.md

@@ -97,6 +97,7 @@ npx unity-mcp-cli install-plugin /path/to/unity/project
   - [`install-unity`](#install-unity)
   - [`open`](#open)
   - [`run-tool`](#run-tool)
+  - [`exec`](#exec)
   - [`wait-for-ready`](#wait-for-ready)
   - [`setup-mcp`](#setup-mcp)
   - [`setup-skills`](#setup-skills)
@@ -250,6 +251,8 @@ unity-mcp-cli open ./MyGame
 | `--tools <names>` | `UNITY_MCP_TOOLS` | No | Lista de herramientas a activar, separadas por comas |
 | `--transport <method>` | `UNITY_MCP_TRANSPORT` | No | Metodo de transporte: `streamableHttp` o `stdio` |
 | `--start-server <value>` | `UNITY_MCP_START_SERVER` | No | Establece `true` o `false` para controlar el inicio automatico del servidor MCP |
+| `--headless` | — | No | Inicia el editor sin ventana (`-batchmode`; los gráficos siguen activos, así que las cámaras renderizan) y espera a que su servidor MCP responda. Implica `--keep-connected`. Reutiliza un editor ya abierto del proyecto; el que se inicia aquí pertenece a la CLI (`close --owned-only`), y las llamadas en paralelo inician solo uno. |
+| `--idle-timeout <seconds>` | `AIGD_SESSION_IDLE_SECONDS` (headless) / `UNITY_MCP_IDLE_TIMEOUT` (ventana) | No | Cierra el editor tras estos segundos sin llamadas a herramientas (antes guarda escenas y assets modificados) |
 
 El proceso del editor se lanza en modo desacoplado — la CLI regresa inmediatamente.
 
@@ -325,6 +328,36 @@ unity-mcp-cli run-tool assets-list ./MyGame --raw | jq '.results'
 
 ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true)
 
+## `exec`
+
+Ejecuta C# en Unity Editor y muestra el resultado. Si el proyecto ya está abierto (con ventana o headless), `exec` usa ese editor y nunca lo cierra. Si no, inicia un editor headless que se mantiene caliente para las siguientes llamadas y se cierra solo tras `--idle` segundos sin llamadas (guardando escenas y assets modificados). El editor que inicia queda registrado en el lease de sesión del proyecto (`.ai-game-dev/session.json`) y se inicia bajo un bloqueo de archivo, así que las llamadas `exec` en paralelo comparten un editor; `close --owned-only` lo cierra y `open` (con ventana) lo cierra antes de abrir la ventana. Estos archivos de sesión son locales de la máquina: `.ai-game-dev/.gitignore` los excluye de git. Si el proyecto está abierto en un editor que la CLI no inició y su plugin no responde en 60 s (desconectado o conectado a la nube de ai-game.dev), `exec` se detiene con una indicación en lugar de esperar: conecta el plugin, cambia su conexión a Custom (un servidor local) o pasa `--url`.
+
+```bash
+# La última expresión es el resultado
+unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
+
+# Desde un archivo o stdin, con namespaces extra y archivos auxiliares
+unity-mcp-cli exec -f ./snippet.cs --using MyGame.Gameplay --include Helpers/
+echo 'Application.unityVersion' | unity-mcp-cli exec
+```
+
+| Opción | Requerido | Descripción |
+|---|---|---|
+| `[code]` | No | Fragmento C#: instrucciones simples, la última expresión es el resultado. También `-f` o stdin. |
+| `--path <path>` | No | Ruta del proyecto Unity (por defecto: directorio actual) |
+| `-f, --file <file>` | No | Lee el código de un archivo (`-` para stdin) |
+| `--using <namespace>` | No | Namespace adicional, repetible |
+| `--include <path>` | No | Archivo `.cs` o carpeta auxiliar (recursiva), relativa a `<Project>/.ai-game-dev/snippets`, repetible |
+| `--window` | No | Inicia el editor con ventana en lugar de headless (solo si aún no está abierto) |
+| `--idle <seconds>` | No | Cierra el editor iniciado por `exec` tras estos segundos de inactividad (por defecto: 300) |
+| `--ready-timeout <ms>` | No | Tiempo máximo de espera hasta que el editor esté listo (por defecto: 300000) |
+| `--timeout <ms>` | No | Tiempo límite de la llamada (por defecto: 310000) |
+| `--raw` | No | Muestra el JSON de respuesta sin formato |
+| `--url <url>` | No | URL del servidor; una URL local hace que el editor nuevo inicie ese servidor |
+| `--token <token>` | No | Token Bearer |
+
+`exec` llama a la herramienta `script-execute`, así que los fragmentos, `usings` e `include` requieren una versión del plugin con Code-Exec. Un error de compilación termina con código 1 y señala tus propias líneas.
+
 ## `wait-for-ready`
 
 Espera hasta que Unity Editor y el servidor MCP esten conectados y listos para aceptar llamadas de herramientas. Sondea el servidor a un intervalo configurable hasta que responda correctamente o se alcance el tiempo limite. Util para scripts de automatizacion y orquestacion de agentes de IA donde `open` inicia Unity pero el agente necesita saber cuando puede empezar a llamar herramientas.

package/docs/README.ja.md

@@ -97,6 +97,7 @@ npx unity-mcp-cli install-plugin /path/to/unity/project
   - [`install-unity`](#install-unity)
   - [`open`](#open)
   - [`run-tool`](#run-tool)
+  - [`exec`](#exec)
   - [`wait-for-ready`](#wait-for-ready)
   - [`setup-mcp`](#setup-mcp)
   - [`setup-skills`](#setup-skills)
@@ -250,6 +251,8 @@ unity-mcp-cli open ./MyGame
 | `--tools <names>` | `UNITY_MCP_TOOLS` | いいえ | 有効にするツールのカンマ区切りリスト |
 | `--transport <method>` | `UNITY_MCP_TRANSPORT` | いいえ | トランスポート方式：`streamableHttp`または`stdio` |
 | `--start-server <value>` | `UNITY_MCP_START_SERVER` | いいえ | MCPサーバーの自動起動を制御（`true`または`false`） |
+| `--headless` | — | いいえ | ウィンドウなしでエディタを起動（`-batchmode`。グラフィックスは有効なのでカメラは描画されます）し、MCP サーバーが応答するまで待ちます。`--keep-connected` を含みます。プロジェクトのエディタが既に起動していればそれを使い、ここで起動したエディタは CLI のものになります（`close --owned-only`）。並列呼び出しでも起動は 1 つだけです。 |
+| `--idle-timeout <seconds>` | `AIGD_SESSION_IDLE_SECONDS`（headless）/ `UNITY_MCP_IDLE_TIMEOUT`（ウィンドウ） | いいえ | ツール呼び出しがこの秒数ないとエディタを終了（変更されたシーンとアセットを先に保存） |
 
 エディタープロセスはデタッチモードで起動されます — CLIは即座に制御を返します。
 
@@ -325,6 +328,36 @@ unity-mcp-cli run-tool assets-list ./MyGame --raw | jq '.results'
 
 ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true)
 
+## `exec`
+
+Unity Editor で C# を実行し、結果を表示します。プロジェクトが既に開いている場合（ウィンドウ付きでも headless でも）、`exec` はそのエディタを使い、閉じることはありません。開いていない場合は headless エディタを起動し、次の呼び出しのために起動したまま保ち、`--idle` 秒間ツール呼び出しがなければ自動で終了します（変更されたシーンとアセットを保存）。起動したエディタはプロジェクトのセッションリース（`.ai-game-dev/session.json`）に記録され、ファイルロックの下で起動されるため、並列の `exec` 呼び出しは 1 つのエディタを共有します。`close --owned-only` で閉じることができ、`open`（ウィンドウ付き）はウィンドウを開く前にそれを閉じます。これらのセッションファイルはマシン固有のもので、`.ai-game-dev/.gitignore` によって git から除外されます。CLI が起動していないエディタでプロジェクトが開かれていて、そのプラグインが 60 秒以内に応答しない場合（未接続、または ai-game.dev クラウドに接続中）、`exec` は待ち続けずにヒントを表示して終了します。プラグインを接続するか、接続を Custom（ローカルサーバー）に切り替えるか、`--url` を指定してください。
+
+```bash
+# 最後の式が結果になります
+unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
+
+# ファイルまたは stdin から、追加の名前空間とヘルパーファイル付きで
+unity-mcp-cli exec -f ./snippet.cs --using MyGame.Gameplay --include Helpers/
+echo 'Application.unityVersion' | unity-mcp-cli exec
+```
+
+| オプション | 必須 | 説明 |
+|---|---|---|
+| `[code]` | いいえ | C# スニペット：通常の文で、最後の式が結果。`-f` または stdin も可。 |
+| `--path <path>` | いいえ | Unity プロジェクトのパス（デフォルト：カレントディレクトリ） |
+| `-f, --file <file>` | いいえ | ファイルからコードを読み込む（`-` で stdin） |
+| `--using <namespace>` | いいえ | 追加の名前空間（複数指定可） |
+| `--include <path>` | いいえ | ヘルパーの `.cs` ファイルまたはフォルダ（再帰）、`<Project>/.ai-game-dev/snippets` からの相対パス（複数指定可） |
+| `--window` | いいえ | headless ではなくウィンドウ付きでエディタを起動（まだ起動していない場合のみ） |
+| `--idle <seconds>` | いいえ | `exec` が起動したエディタをこの秒数アイドルで終了（デフォルト：300） |
+| `--ready-timeout <ms>` | いいえ | エディタの準備完了を待つ最大時間（デフォルト：300000） |
+| `--timeout <ms>` | いいえ | ツール呼び出しのタイムアウト（デフォルト：310000） |
+| `--raw` | いいえ | ツール応答の生の JSON を出力 |
+| `--url <url>` | いいえ | サーバー URL の上書き。ローカル URL の場合、新しく起動したエディタがそのサーバーを起動します |
+| `--token <token>` | いいえ | Bearer トークンの上書き |
+
+`exec` は `script-execute` ツールを呼び出すため、スニペット、`usings`、`include` には Code-Exec 対応のプラグインが必要です。コンパイルエラーは終了コード 1 で、あなたのコードの行を指します。
+
 ## `wait-for-ready`
 
 Unity EditorとMCPサーバーが接続され、ツール呼び出しを受け付ける準備ができるまで待機します。設定可能な間隔でサーバーをポーリングし、正常に応答するかタイムアウトに達するまで待ちます。`open`でUnityを起動した後、エージェントがツールの呼び出しを開始できるタイミングを知る必要がある自動化スクリプトやAIエージェントのオーケストレーションに便利です。

package/docs/README.zh-CN.md

@@ -97,6 +97,7 @@ npx unity-mcp-cli install-plugin /path/to/unity/project
   - [`install-unity`](#install-unity)
   - [`open`](#open)
   - [`run-tool`](#run-tool)
+  - [`exec`](#exec)
   - [`wait-for-ready`](#wait-for-ready)
   - [`setup-mcp`](#setup-mcp)
   - [`setup-skills`](#setup-skills)
@@ -250,6 +251,8 @@ unity-mcp-cli open ./MyGame
 | `--tools <names>` | `UNITY_MCP_TOOLS` | 否 | 要启用的工具列表（逗号分隔） |
 | `--transport <method>` | `UNITY_MCP_TRANSPORT` | 否 | 传输方式：`streamableHttp` 或 `stdio` |
 | `--start-server <value>` | `UNITY_MCP_START_SERVER` | 否 | 设置为 `true` 或 `false` 以控制 MCP 服务器自动启动 |
+| `--headless` | — | 否 | 无窗口启动编辑器（`-batchmode`；图形保持开启，相机仍可渲染），并等待其 MCP 服务器响应。隐含 `--keep-connected`。复用项目已运行的编辑器；在此启动的编辑器归 CLI 所有（`close --owned-only`），并行调用只启动一个。 |
+| `--idle-timeout <seconds>` | `AIGD_SESSION_IDLE_SECONDS`（headless）/ `UNITY_MCP_IDLE_TIMEOUT`（窗口） | 否 | 在这么多秒内没有工具调用时退出编辑器（先保存已修改的场景和资源） |
 
 编辑器进程以分离模式启动 — CLI 将立即返回。
 
@@ -325,6 +328,36 @@ unity-mcp-cli run-tool assets-list ./MyGame --raw | jq '.results'
 
 ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true)
 
+## `exec`
+
+在 Unity Editor 中运行 C# 并输出结果。如果项目已打开（有窗口或 headless），`exec` 会使用该编辑器且绝不关闭它。否则它会启动一个 headless 编辑器，为后续调用保持预热，并在 `--idle` 秒内没有工具调用时自动退出（会保存已修改的场景和资源）。它启动的编辑器记录在项目的会话租约（`.ai-game-dev/session.json`）中，并在文件锁下启动，因此并行的 `exec` 调用共享一个编辑器；`close --owned-only` 会关闭它，`open`（带窗口）会在打开窗口前先关闭它。这些会话文件仅属于本机：`.ai-game-dev/.gitignore` 会将它们排除在 git 之外。如果项目在一个并非由 CLI 启动的编辑器中打开，且其插件在 60 秒内没有响应（未连接，或连接到 ai-game.dev 云端），`exec` 会给出提示并停止，而不是一直等待：请连接插件、将其连接切换为 Custom（本地服务器），或传入 `--url`。
+
+```bash
+# 最后一个表达式即为结果
+unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
+
+# 从文件或 stdin 读取，附加命名空间和辅助文件
+unity-mcp-cli exec -f ./snippet.cs --using MyGame.Gameplay --include Helpers/
+echo 'Application.unityVersion' | unity-mcp-cli exec
+```
+
+| 选项 | 必需 | 描述 |
+|---|---|---|
+| `[code]` | 否 | C# 片段：普通语句，最后一个表达式即为结果。也可用 `-f` 或 stdin。 |
+| `--path <path>` | 否 | Unity 项目路径（默认：当前目录） |
+| `-f, --file <file>` | 否 | 从文件读取代码（`-` 表示 stdin） |
+| `--using <namespace>` | 否 | 额外的命名空间，可重复 |
+| `--include <path>` | 否 | 辅助 `.cs` 文件或文件夹（递归），相对于 `<Project>/.ai-game-dev/snippets`，可重复 |
+| `--window` | 否 | 以窗口方式而非 headless 启动编辑器（仅在尚未运行时） |
+| `--idle <seconds>` | 否 | 由 `exec` 启动的编辑器空闲这么多秒后退出（默认：300） |
+| `--ready-timeout <ms>` | 否 | 等待编辑器就绪的最长时间（默认：300000） |
+| `--timeout <ms>` | 否 | 工具调用超时（默认：310000） |
+| `--raw` | 否 | 输出原始工具响应 JSON |
+| `--url <url>` | 否 | 服务器 URL 覆盖；本地 URL 会让新启动的编辑器启动该服务器 |
+| `--token <token>` | 否 | Bearer 令牌覆盖 |
+
+`exec` 调用 `script-execute` 工具，因此片段、`usings` 和 `include` 需要支持 Code-Exec 的插件版本。编译错误会以退出码 1 结束，并指向你自己的代码行。
+
 ## `wait-for-ready`
 
 等待 Unity 编辑器和 MCP 服务器连接就绪并可接受工具调用。以可配置的间隔轮询服务器，直到成功响应或达到超时时间。适用于自动化脚本和 AI 代理编排场景，其中 `open` 启动 Unity 后代理需要知道何时可以开始调用工具。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unity-mcp-cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Cross-platform CLI tool for AI Game Developer (Skills & MCP). Full AI develop and test loop. Efficient token usage, advanced tools. Creates Unity project, installs plugins, configures tools, and manages HTTP connection with Unity Editor and a game made with Unity. Works with Claude Code, Gemini, Copilot, Cursor and any other absolutely for free.",
   "type": "module",
   "main": "dist/lib.js",
@@ -62,7 +62,7 @@
     "node": "^20.19.0 || >=22.12.0"
   },
   "dependencies": {
-    "@baizor/gamedev-cli-core": "^0.6.0",
+    "@baizor/gamedev-cli-core": "^0.7.1",
     "chalk": "^5.6.2",
     "commander": "^13.1.0",
     "yocto-spinner": "^1.1.0"