chore: bump version to 10.3.0

.claude/skills/unity-mcp-skill/SKILL.md

@@ -27,6 +27,11 @@ Before applying a template:
 5. Verify results         → read_console, manage_camera(action="screenshot"), resources
 ```
 
+**If a tool you need is not in your tool list, it is not necessarily missing.** Check these before troubleshooting the connection:
+
+- **Project custom tools** (C# `[McpForUnityTool]`): with project-scoped tools enabled on the server, they are *not* callable by name. List them via `mcpforunity://custom-tools` and run them with `execute_custom_tool(tool_name="...", parameters={...})`. With it disabled, they are registered as ordinary tools and appear in your list.
+- **Disabled tool groups**: over HTTP, a session starts with only the `core` group enabled. Over stdio, all groups start enabled and are then synced to the tool toggles in the Unity editor, so a tool can still be hidden. `manage_tools(action="list_groups")` shows the groups, `manage_tools(action="activate", group="...")` enables one.
+
 ## Critical Best Practices
 
 ### 1. After Writing/Editing Scripts: Wait for Compilation and Check Console

.gitattributes

@@ -1,3 +1,8 @@
 # Shell scripts must keep LF: tools/compile-check.sh runs inside a Linux container,
 # where CRLF would fail with "bad interpreter".
 *.sh text eol=lf
+
+# compile-check.sh reads these line by line; a CR from a core.autocrlf checkout would
+# become part of every -define: symbol and reference name.
+tools/compile-defines.txt text eol=lf
+tools/compile-refs/*.txt text eol=lf

.github/workflows/e2e-bridge.yml

@@ -15,6 +15,8 @@ on:
       - "Server/src/**"
       - "Server/tests/e2e/**"
       - "tools/local_harness.py"
+      - "tools/ci_unity_license.py"
+      - "tools/tests/test_ci_unity_license.py"
       - ".github/workflows/e2e-bridge.yml"
 
 permissions:
@@ -50,7 +52,9 @@ jobs:
           UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
         run: |
           set -e
-          if [ -n "$UNITY_LICENSE" ] || { [ -n "$UNITY_EMAIL" ] && [ -n "$UNITY_PASSWORD" ] && [ -n "$UNITY_SERIAL" ]; }; then
+          # Only absent secrets skip a fork run. Partial configuration must fail
+          # explicitly in prepare, rather than silently look like missing access.
+          if [ -n "$UNITY_LICENSE$UNITY_EMAIL$UNITY_PASSWORD$UNITY_SERIAL" ]; then
             echo "unity_ok=true" >> "$GITHUB_OUTPUT"
           else
             echo "unity_ok=false" >> "$GITHUB_OUTPUT"
@@ -90,87 +94,39 @@ jobs:
           echo "$GITHUB_WORKSPACE/.venv/bin" >> "$GITHUB_PATH"
           uv pip install -e Server
 
-      # --- License staging (mirrors claude-nl-suite.yml) ---
-      - name: Decide license sources
-        id: lic
-        shell: bash
+      # Activate with the same pinned GameCI implementation that runs our tests.
+      # Personal account credentials do not require a professional serial key.
+      - name: Prepare Unity license and activation helpers
+        id: prepare_license
         env:
           UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
           UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
           UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
-          UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
-        run: |
-          set -eu
-          use_ulf=false; use_ebl=false
-          [[ -n "${UNITY_LICENSE:-}" ]] && use_ulf=true
-          [[ -n "${UNITY_EMAIL:-}" && -n "${UNITY_PASSWORD:-}" && -n "${UNITY_SERIAL:-}" ]] && use_ebl=true
-          echo "use_ulf=$use_ulf" >> "$GITHUB_OUTPUT"
-          echo "use_ebl=$use_ebl" >> "$GITHUB_OUTPUT"
-
-      - name: Stage Unity .ulf license (from secret)
-        if: steps.lic.outputs.use_ulf == 'true'
-        id: ulf
-        env:
-          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
-        shell: bash
-        run: |
-          set -eu
-          mkdir -p "$RUNNER_TEMP/unity-license-ulf" "$RUNNER_TEMP/unity-local/Unity"
-          f="$RUNNER_TEMP/unity-license-ulf/Unity_lic.ulf"
-          if printf "%s" "$UNITY_LICENSE" | base64 -d - >/dev/null 2>&1; then
-            printf "%s" "$UNITY_LICENSE" | base64 -d - > "$f"
-          else
-            printf "%s" "$UNITY_LICENSE" > "$f"
-          fi
-          chmod 600 "$f" || true
-          if grep -qi '<Signature>' "$f"; then
-            cp -f "$f" "$RUNNER_TEMP/unity-local/Unity/Unity_lic.ulf"
-            echo "ok=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "ok=false" >> "$GITHUB_OUTPUT"
-          fi
+        run: python3 tools/ci_unity_license.py prepare
 
-      - name: Activate Unity (EBL via container)
-        if: steps.lic.outputs.use_ebl == 'true'
-        shell: bash
+      - name: Activate Unity license
         env:
-          UNITY_IMAGE: ${{ env.UNITY_IMAGE }}
           UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
           UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
           UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
-        run: |
-          set -euo pipefail
-          mkdir -p "$RUNNER_TEMP/unity-config" "$RUNNER_TEMP/unity-local"
-          docker run --rm --network host \
-            -e HOME=/root -e UNITY_EMAIL -e UNITY_PASSWORD -e UNITY_SERIAL \
-            -v "$RUNNER_TEMP/unity-config:/root/.config/unity3d" \
-            -v "$RUNNER_TEMP/unity-local:/root/.local/share/unity3d" \
-            "$UNITY_IMAGE" bash -lc '
-              set -euxo pipefail
-              /opt/unity/Editor/Unity -batchmode -nographics -logFile - \
-                -username "$UNITY_EMAIL" -password "$UNITY_PASSWORD" -serial "$UNITY_SERIAL" -quit || true
-            '
+        run: python3 tools/ci_unity_license.py activate
 
       - name: Warm up project (import Library once)
         shell: bash
         env:
           UNITY_IMAGE: ${{ env.UNITY_IMAGE }}
-          ULF_OK: ${{ steps.ulf.outputs.ok }}
         run: |
           set -euxo pipefail
-          manual_args=()
-          if [[ "${ULF_OK:-false}" == "true" ]]; then
-            manual_args=(-manualLicenseFile "/root/.local/share/unity3d/Unity/Unity_lic.ulf")
-          fi
           docker run --rm --network host \
             -e HOME=/root \
+            -v "$RUNNER_TEMP/unity-machine-id:/etc/machine-id:ro" \
             -v "${{ github.workspace }}:${{ github.workspace }}" -w "${{ github.workspace }}" \
             -v "$RUNNER_TEMP/unity-config:/root/.config/unity3d" \
             -v "$RUNNER_TEMP/unity-local:/root/.local/share/unity3d" \
             -v "$RUNNER_TEMP/unity-cache:/root/.cache/unity3d" \
             "$UNITY_IMAGE" /opt/unity/Editor/Unity -batchmode -nographics -logFile - \
               -projectPath "${{ github.workspace }}/TestProjects/UnityMCPTests" \
-              "${manual_args[@]}" -quit
+              -quit
 
       - name: Clean old MCP status
         run: |
@@ -182,32 +138,32 @@ jobs:
         shell: bash
         env:
           UNITY_IMAGE: ${{ env.UNITY_IMAGE }}
-          ULF_OK: ${{ steps.ulf.outputs.ok }}
         run: |
           set -euxo pipefail
           # In --ci mode the harness drives the DockerLauncher: it runs the same
           # docker container (repo .unity-mcp status dir, docker liveness/teardown,
           # log redaction), waits on the status file, derives the instance, then
           # runs the smoke + EditMode + PlayMode legs over the bridge.
-          license_args=()
-          if [[ "${ULF_OK:-false}" == "true" ]]; then
-            license_args=(--editor-arg -manualLicenseFile \
-              --editor-arg "/root/.local/share/unity3d/Unity/Unity_lic.ulf")
-          fi
           python3 tools/local_harness.py --ci \
             --legs smoke,editmode,playmode \
             --project-path TestProjects/UnityMCPTests \
-            --reports reports \
-            "${license_args[@]}"
+            --reports reports
 
-      - name: Unity logs on failure
-        if: failure()
-        run: docker logs unity-mcp --tail 200 | sed -E 's/((email|serial|license|password|token)[^[:space:]]*)/[REDACTED]/Ig' || true
+      - name: Return Unity license seat
+        if: always() && steps.prepare_license.outcome == 'success'
+        env:
+          UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
+          UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
+          UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
+        run: python3 tools/ci_unity_license.py return
 
       - name: Upload E2E report
         if: always()
         uses: actions/upload-artifact@v4
         with:
           name: e2e-bridge-report
-          path: reports/junit-*.xml
+          # The harness snapshots redacted Editor logs before removing its container.
+          path: |
+            reports/junit-*.xml
+            reports/unity-editor-*.log
           if-no-files-found: ignore

.github/workflows/python-tests.yml

@@ -47,8 +47,11 @@ jobs:
       - name: Install dependencies
         run: |
           cd Server
-          uv sync
-          uv pip install -e ".[dev]"
+          # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
+          # re-resolving, so a dependency or version bump that forgot `uv lock` shows up here.
+          # The dev extra is resolved in the lock too, so pytest runs against pinned versions
+          # instead of whatever `uv pip install` would fetch today.
+          uv sync --locked --extra dev
 
       - name: Run tests with coverage
         run: |

CLAUDE.md

@@ -70,7 +70,7 @@ from services.registry import mcp_for_unity_tool
 
 @mcp_for_unity_tool(
     description="Does something in Unity.",
-    group="core",  # core (default), vfx, animation, ui, scripting_ext, testing, probuilder, profiling, docs
+    group="core",  # core (default), vfx, animation, ui, scripting_ext, testing, probuilder, profiling, docs, asset_gen
 )
 async def manage_something(
     ctx: Context,
@@ -165,6 +165,12 @@ cd Server && uv run pytest tests/ -k "test_create_material" -v
 # Local multi-version compile check (parity with CI matrix, see tools/unity-versions.json)
 tools/check-unity-versions.sh           # compile-only across installed Unity Hub editors
 tools/check-unity-versions.sh --full    # full EditMode test run
+
+# License-free Roslyn compile of MCPForUnity, the same gate compile-check.yml runs on every PR.
+# No Editor launch, ~1 min per version. EXTRA_REFS must hold Newtonsoft.Json.dll and
+# nunit.framework.dll (copy them from TestProjects/UnityMCPTests/Library/PackageCache);
+# the script header has the full recipe, including the Windows/Git Bash form.
+UNITY_DATA=/path/to/Editor/Data UNITY_VERSION=2021.3.45f2 EXTRA_REFS=/path/to/refs tools/compile-check.sh
 ```
 
 #### Local headless test harness

MCPForUnity/Editor/Clients/Configurators/PiConfigurator.cs

@@ -0,0 +1,98 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using MCPForUnity.Editor.Models;
+
+namespace MCPForUnity.Editor.Clients.Configurators
+{
+    /// <summary>
+    /// Pi (pi.dev) configurator.
+    ///
+    /// Two things make Pi different from every other JSON client in this folder, and both are
+    /// load-bearing rather than cosmetic:
+    ///
+    /// 1. <b>Pi has no built-in MCP client.</b> As of pi 0.84.x there is no <c>mcp</c> subcommand,
+    ///    no <c>--mcp-config</c> equivalent, and no <c>mcp.json</c> reader anywhere in the
+    ///    distributed package; its own README states "No MCP. Build CLI tools with READMEs, or
+    ///    build an extension that adds MCP support." Reaching this server from Pi therefore
+    ///    requires an MCP extension, and the <c>unityMCP</c> entry written below is what that
+    ///    extension reads. <see cref="GetInstallationSteps"/> names the extension explicitly,
+    ///    because on Pi a config file alone is a silent no-op — the exact "configured, enabled, and
+    ///    silently providing nothing" shape this window exists to prevent.
+    ///
+    /// 2. <b>The file is shared, so presence cannot be inferred from it.</b> Pi MCP extensions read
+    ///    the tool-agnostic <c>~/.config/mcp/mcp.json</c>, not a Pi-owned path. That makes the
+    ///    inherited <c>IsInstalled</c> ("does the config path's parent directory exist") wrong in
+    ///    both directions — see <see cref="IsInstalled"/>.
+    /// </summary>
+    public class PiConfigurator : JsonFileMcpConfigurator
+    {
+        public PiConfigurator() : base(new McpClient
+        {
+            name = "Pi",
+            windowsConfigPath = GetSharedMcpConfigPath(),
+            macConfigPath = GetSharedMcpConfigPath(),
+            linuxConfigPath = GetSharedMcpConfigPath()
+        })
+        { }
+
+        /// <summary>
+        /// Pi-exclusive presence check, deliberately NOT the inherited
+        /// <c>ParentDirectoryExists(GetConfigPath())</c>.
+        ///
+        /// <para>
+        /// The config path here is a SHARED, tool-agnostic file. Its parent directory therefore says
+        /// nothing about whether Pi exists: a Cursor or Claude Code user has a
+        /// <c>~/.config/mcp</c> tree without ever installing Pi, and a Pi user who has not yet
+        /// configured any MCP server has no <c>~/.config/mcp</c> at all. Keying detection on that
+        /// path would make "Configure All Detected Clients" offer Pi on machines that do not have
+        /// it while skipping the exact machines this configurator exists to fix.
+        /// </para>
+        ///
+        /// <para>
+        /// Pi's own agent directory is the correct marker: pi creates it on first run for settings,
+        /// sessions and auth, nothing else writes there, and <c>PI_CODING_AGENT_DIR</c> relocates
+        /// it — so an explicitly relocated install is detected too rather than hardcoding
+        /// <c>~/.pi</c>.
+        /// </para>
+        /// </summary>
+        public override bool IsInstalled
+        {
+            get
+            {
+                string agentDir = GetPiAgentDirectory();
+                return !string.IsNullOrEmpty(agentDir) && Directory.Exists(agentDir);
+            }
+        }
+
+        public override IList<string> GetInstallationSteps() => new List<string>
+        {
+            "Install an MCP extension for Pi — Pi ships no MCP client of its own:\npi install npm:pi-mcp-adapter",
+            "Restart Pi so the extension loads (extensions are read at startup)",
+            "Paste the configuration JSON into the file at the path above, or use Configure",
+            "Start Pi and ask it to search MCP — e.g. \"search MCP for manage_gameobject\""
+        };
+
+        /// <summary>The tool-agnostic shared MCP config Pi MCP extensions read, in the user's home.</summary>
+        private static string GetSharedMcpConfigPath()
+        {
+            string home = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+            return Path.Combine(home, ".config", "mcp", "mcp.json");
+        }
+
+        /// <summary>
+        /// Pi's agent directory: <c>$PI_CODING_AGENT_DIR</c> when set (Pi's own documented
+        /// relocation override), else <c>~/.pi/agent</c>. Null when the home directory cannot be
+        /// resolved, which callers must treat as "not installed" rather than as a match.
+        /// </summary>
+        private static string GetPiAgentDirectory()
+        {
+            string overrideDir = Environment.GetEnvironmentVariable("PI_CODING_AGENT_DIR");
+            if (!string.IsNullOrWhiteSpace(overrideDir))
+                return overrideDir.Trim();
+
+            string home = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+            return string.IsNullOrEmpty(home) ? null : Path.Combine(home, ".pi", "agent");
+        }
+    }
+}

MCPForUnity/Editor/Clients/Configurators/TraeCnConfigurator.cs

@@ -0,0 +1,30 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using MCPForUnity.Editor.Models;
+
+namespace MCPForUnity.Editor.Clients.Configurators
+{
+    public class TraeCnConfigurator : JsonFileMcpConfigurator
+    {
+        public TraeCnConfigurator() : base(new McpClient
+        {
+            name = "Trae CN",
+            windowsConfigPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), "Trae CN", "User", "mcp.json"),
+            macConfigPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), "Library", "Application Support", "Trae CN", "User", "mcp.json"),
+            linuxConfigPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), ".config", "Trae CN", "User", "mcp.json"),
+        })
+        { }
+
+        public override IList<string> GetInstallationSteps() => new List<string>
+        {
+            "Open Trae CN and go to Settings > MCP",
+            "Select Add Server > Add Manually",
+            "Paste the JSON or point to the mcp.json file\n"+
+                "Windows: %AppData%\\Trae CN\\User\\mcp.json\n" +
+                "macOS: ~/Library/Application Support/Trae CN/User/mcp.json\n" +
+                "Linux: ~/.config/Trae CN/User/mcp.json\n",
+            "Save and restart Trae CN"
+        };
+    }
+}