@akiojin/unity-mcp-server 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "MCP server and Unity Editor bridge — enables AI assistants to control Unity for AI-assisted workflows",
   "type": "module",
   "main": "src/core/server.js",

package/src/core/projectInfo.js

@@ -46,6 +46,22 @@ export class ProjectInfoProvider {
 
   async get() {
     if (this.cached) return this.cached;
+    // Env-driven project root override (primarily for tests)
+    const envRootRaw = process.env.UNITY_PROJECT_ROOT;
+    if (typeof envRootRaw === 'string' && envRootRaw.trim().length > 0) {
+      const envRoot = envRootRaw.trim();
+      const projectRoot = normalize(path.resolve(envRoot));
+      const codeIndexRoot = normalize(resolveDefaultCodeIndexRoot(projectRoot));
+      this.cached = {
+        projectRoot,
+        assetsPath: normalize(path.join(projectRoot, 'Assets')),
+        packagesPath: normalize(path.join(projectRoot, 'Packages')),
+        packageCachePath: normalize(path.join(projectRoot, 'Library/PackageCache')),
+        codeIndexRoot
+      };
+      return this.cached;
+    }
+
     // Config-driven project root (no env fallback)
     const cfgRootRaw = config?.project?.root;
     if (typeof cfgRootRaw === 'string' && cfgRootRaw.trim().length > 0) {
@@ -61,6 +77,7 @@ export class ProjectInfoProvider {
         projectRoot,
         assetsPath: normalize(path.join(projectRoot, 'Assets')),
         packagesPath: normalize(path.join(projectRoot, 'Packages')),
+        packageCachePath: normalize(path.join(projectRoot, 'Library/PackageCache')),
         codeIndexRoot
       };
       return this.cached;
@@ -76,6 +93,9 @@ export class ProjectInfoProvider {
             projectRoot: info.projectRoot,
             assetsPath: info.assetsPath,
             packagesPath: normalize(info.packagesPath || path.join(info.projectRoot, 'Packages')),
+            packageCachePath: normalize(
+              info.packageCachePath || path.join(info.projectRoot, 'Library/PackageCache')
+            ),
             codeIndexRoot: normalize(
               info.codeIndexRoot || resolveDefaultCodeIndexRoot(info.projectRoot)
             )
@@ -96,6 +116,7 @@ export class ProjectInfoProvider {
         projectRoot,
         assetsPath: normalize(path.join(projectRoot, 'Assets')),
         packagesPath: normalize(path.join(projectRoot, 'Packages')),
+        packageCachePath: normalize(path.join(projectRoot, 'Library/PackageCache')),
         codeIndexRoot
       };
       return this.cached;

package/src/core/workers/indexBuildWorker.js

@@ -15,7 +15,7 @@
  */
 
 import { parentPort, workerData } from 'worker_threads';
-import { spawn } from 'child_process';
+import { spawn, execFile } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
@@ -107,6 +107,111 @@ function walkCs(root, files, seen) {
   }
 }
 
+/**
+ * Fast file enumeration using OS native commands (find on Unix, PowerShell on Windows)
+ * Falls back to walkCs on failure
+ * @param {string[]} roots - Array of root directories to scan
+ * @returns {Promise<string[]>} Array of absolute C# file paths
+ */
+async function fastWalkCs(roots) {
+  const isWindows = process.platform === 'win32';
+  const allFiles = [];
+  const seen = new Set();
+
+  for (const root of roots) {
+    if (!fs.existsSync(root)) {
+      log('info', `[worker] Skipping non-existent root: ${root}`);
+      continue;
+    }
+
+    log('info', `[worker] Scanning ${path.basename(root)}...`);
+    const startTime = Date.now();
+
+    try {
+      const files = await new Promise((resolve, reject) => {
+        if (isWindows) {
+          // Windows: Use PowerShell (secure - no shell interpretation)
+          execFile(
+            'powershell',
+            [
+              '-NoProfile',
+              '-Command',
+              `Get-ChildItem -Path '${root.replace(/'/g, "''")}' -Recurse -Include *.cs -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName`
+            ],
+            { maxBuffer: 50 * 1024 * 1024 }, // 50MB buffer for large projects
+            (error, stdout) => {
+              if (error) {
+                reject(error);
+                return;
+              }
+              const files = stdout
+                .split('\r\n')
+                .map(f => f.trim())
+                .filter(f => f && f.endsWith('.cs'));
+              resolve(files);
+            }
+          );
+        } else {
+          // Unix: Use find command (secure - no shell interpretation)
+          // Note: We intentionally don't exclude hidden directories (*/.*) because:
+          // - The search root may be inside .worktrees which contains a dot
+          // - -name '*.cs' already filters to only C# files (excluding .meta etc.)
+          execFile(
+            'find',
+            [
+              root,
+              '-name',
+              '*.cs',
+              '-type',
+              'f',
+              '-not',
+              '-path',
+              '*/obj/*',
+              '-not',
+              '-path',
+              '*/bin/*'
+            ],
+            { maxBuffer: 50 * 1024 * 1024 }, // 50MB buffer for large projects
+            (error, stdout) => {
+              if (error) {
+                reject(error);
+                return;
+              }
+              const files = stdout
+                .split('\n')
+                .map(f => f.trim())
+                .filter(f => f && f.endsWith('.cs'));
+              resolve(files);
+            }
+          );
+        }
+      });
+
+      const elapsed = Date.now() - startTime;
+      log('info', `[worker] Found ${files.length} files in ${path.basename(root)} (${elapsed}ms)`);
+
+      // Add unique files
+      for (const f of files) {
+        if (!seen.has(f)) {
+          seen.add(f);
+          allFiles.push(f);
+        }
+      }
+    } catch (e) {
+      // Fallback to walkCs on error
+      log(
+        'warn',
+        `[worker] Fast scan failed for ${path.basename(root)}: ${e.message}. Using fallback.`
+      );
+      const fallbackFiles = [];
+      walkCs(root, fallbackFiles, seen);
+      allFiles.push(...fallbackFiles);
+    }
+  }
+
+  return allFiles;
+}
+
 /**
  * Convert absolute path to relative path
  */
@@ -406,7 +511,9 @@ async function runBuild() {
     concurrency: _concurrency = 1, // Reserved for future parallel processing
     throttleMs = 0,
     retry = 2,
-    reportPercentage = 10
+    reportPercentage = 10,
+    excludePackageCache = false,
+    forceRebuild = false // Skip change detection and rebuild all files
   } = workerData;
   void _concurrency; // Explicitly mark as intentionally unused
 
@@ -473,36 +580,72 @@ async function runBuild() {
     runSQL(db, 'CREATE INDEX IF NOT EXISTS idx_symbols_path ON symbols(path)');
 
     // Scan for C# files
-    const roots = [
-      path.resolve(projectRoot, 'Assets'),
-      path.resolve(projectRoot, 'Packages'),
-      path.resolve(projectRoot, 'Library/PackageCache')
-    ];
-    const files = [];
-    const seen = new Set();
-    for (const r of roots) walkCs(r, files, seen);
+    // Build roots list based on excludePackageCache option
+    const roots = [path.resolve(projectRoot, 'Assets'), path.resolve(projectRoot, 'Packages')];
+    if (!excludePackageCache) {
+      roots.push(path.resolve(projectRoot, 'Library/PackageCache'));
+    }
+    log(
+      'info',
+      `[worker] Scanning roots: ${roots.map(r => path.basename(r)).join(', ')}${excludePackageCache ? ' (PackageCache excluded)' : ''}`
+    );
 
+    // Use fast find command when available, fallback to walkCs
+    const files = await fastWalkCs(roots);
     log('info', `[worker] Found ${files.length} C# files to process`);
 
-    // Get current indexed files
-    const currentResult = querySQL(db, 'SELECT path, sig FROM files');
-    const current = new Map();
-    if (currentResult.length > 0) {
-      for (const row of currentResult[0].values) {
-        current.set(row[0], row[1]);
+    let changed = [];
+    let removed = [];
+    const wanted = new Map();
+
+    if (forceRebuild) {
+      // Skip change detection - process all files
+      log('info', `[worker] forceRebuild=true, skipping change detection`);
+      // Clear all existing data
+      runSQL(db, 'DELETE FROM symbols');
+      runSQL(db, 'DELETE FROM files');
+      // Mark all files as changed
+      for (const abs of files) {
+        const rel = toRel(abs, projectRoot);
+        wanted.set(rel, '0-0'); // Dummy signature for forceRebuild
+        changed.push(rel);
+      }
+      log('info', `[worker] All ${changed.length} files marked for processing`);
+    } else {
+      // Normal change detection
+      // Get current indexed files
+      const currentResult = querySQL(db, 'SELECT path, sig FROM files');
+      const current = new Map();
+      if (currentResult.length > 0) {
+        for (const row of currentResult[0].values) {
+          current.set(row[0], row[1]);
+        }
       }
-    }
 
-    // Determine changes
-    const wanted = new Map(files.map(abs => [toRel(abs, projectRoot), makeSig(abs)]));
-    const changed = [];
-    const removed = [];
+      // Determine changes (this calls makeSig for each file)
+      log('info', `[worker] Computing file signatures (${files.length} files)...`);
+      const sigStartTime = Date.now();
+      let sigProcessed = 0;
+      for (const abs of files) {
+        const rel = toRel(abs, projectRoot);
+        const sig = makeSig(abs);
+        wanted.set(rel, sig);
+        sigProcessed++;
+        // Report progress every 10000 files
+        if (sigProcessed % 10000 === 0) {
+          const elapsed = ((Date.now() - sigStartTime) / 1000).toFixed(1);
+          log('info', `[worker] Signature progress: ${sigProcessed}/${files.length} (${elapsed}s)`);
+        }
+      }
+      const sigTime = ((Date.now() - sigStartTime) / 1000).toFixed(1);
+      log('info', `[worker] Signatures computed in ${sigTime}s`);
 
-    for (const [rel, sig] of wanted) {
-      if (current.get(rel) !== sig) changed.push(rel);
-    }
-    for (const [rel] of current) {
-      if (!wanted.has(rel)) removed.push(rel);
+      for (const [rel, sig] of wanted) {
+        if (current.get(rel) !== sig) changed.push(rel);
+      }
+      for (const [rel] of current) {
+        if (!wanted.has(rel)) removed.push(rel);
+      }
     }
 
     log('info', `[worker] Changes: ${changed.length} to update, ${removed.length} to remove`);

package/src/handlers/scene/SceneCreateToolHandler.js

@@ -64,17 +64,16 @@ export class SceneCreateToolHandler extends BaseToolHandler {
     // Send command to Unity
     const result = await this.unityConnection.sendCommand('create_scene', params);
 
-    // Check for Unity-side errors
-    if (result.status === 'error') {
+    // Unity returns errors as { error: "..." } payloads (still wrapped in a success response)
+    if (result && result.error) {
       const error = new Error(result.error);
       error.code = 'UNITY_ERROR';
       throw error;
     }
 
-    // Handle undefined or null results from Unity
-    if (result.result === undefined || result.result === null) {
+    // Handle undefined or null results from Unity (best-effort)
+    if (result === undefined || result === null) {
       return {
-        status: 'success',
         sceneName: params.sceneName,
         path: params.path || 'Assets/Scenes/',
         loadScene: params.loadScene !== false,
@@ -83,6 +82,6 @@ export class SceneCreateToolHandler extends BaseToolHandler {
       };
     }
 
-    return result.result;
+    return result;
   }
 }

package/src/handlers/scene/SceneLoadToolHandler.js

@@ -67,17 +67,16 @@ export class SceneLoadToolHandler extends BaseToolHandler {
     // Send command to Unity
     const result = await this.unityConnection.sendCommand('load_scene', params);
 
-    // Check for Unity-side errors
-    if (result.status === 'error') {
+    // Unity returns errors as { error: "..." } payloads (still wrapped in a success response)
+    if (result && result.error) {
       const error = new Error(result.error);
       error.code = 'UNITY_ERROR';
       throw error;
     }
 
-    // Handle undefined or null results from Unity
-    if (result.result === undefined || result.result === null) {
+    // Handle undefined or null results from Unity (best-effort)
+    if (result === undefined || result === null) {
       return {
-        status: 'success',
         sceneName: params.sceneName || 'Unknown',
         scenePath: params.scenePath || 'Unknown',
         loadMode: params.loadMode || 'Single',
@@ -85,6 +84,6 @@ export class SceneLoadToolHandler extends BaseToolHandler {
       };
     }
 
-    return result.result;
+    return result;
   }
 }

package/src/handlers/scene/SceneSaveToolHandler.js

@@ -51,23 +51,22 @@ export class SceneSaveToolHandler extends BaseToolHandler {
     // Send command to Unity
     const result = await this.unityConnection.sendCommand('save_scene', params);
 
-    // Check for Unity-side errors
-    if (result.status === 'error') {
+    // Unity returns errors as { error: "..." } payloads (still wrapped in a success response)
+    if (result && result.error) {
       const error = new Error(result.error);
       error.code = 'UNITY_ERROR';
       throw error;
     }
 
-    // Handle undefined or null results from Unity
-    if (result.result === undefined || result.result === null) {
+    // Handle undefined or null results from Unity (best-effort)
+    if (result === undefined || result === null) {
       return {
-        status: 'success',
         scenePath: params.scenePath || 'Current scene path',
         saveAs: params.saveAs === true,
         message: 'Scene save completed but Unity returned no details'
       };
     }
 
-    return result.result;
+    return result;
   }
 }

package/src/handlers/script/CodeIndexBuildToolHandler.js

@@ -23,6 +23,11 @@ export class CodeIndexBuildToolHandler extends BaseToolHandler {
             minimum: 0,
             maximum: 5,
             description: 'Number of retries for LSP requests (default: 2).'
+          },
+          excludePackageCache: {
+            type: 'boolean',
+            description:
+              'Exclude Library/PackageCache from indexing (default: false). Set to true for faster builds when package symbols are not needed.'
           }
         },
         required: []
@@ -54,7 +59,8 @@ export class CodeIndexBuildToolHandler extends BaseToolHandler {
       return {
         success: false,
         error: 'build_already_running',
-        message: 'Code index build is already running (Worker Thread). Use code_index_status to check progress.',
+        message:
+          'Code index build is already running (Worker Thread). Use code_index_status to check progress.',
         jobId: this.currentJobId
       };
     }
@@ -86,7 +92,8 @@ export class CodeIndexBuildToolHandler extends BaseToolHandler {
           concurrency: 1, // Worker Thread uses sequential processing for stability
           throttleMs: Math.max(0, Number(params?.throttleMs ?? 0)),
           retry: Math.max(0, Math.min(5, Number(params?.retry ?? 2))),
-          reportPercentage: 10
+          reportPercentage: 10,
+          excludePackageCache: Boolean(params?.excludePackageCache)
         });
 
         // Clear current job tracking on success

package/src/handlers/script/ScriptSearchToolHandler.js

@@ -8,7 +8,7 @@ export class ScriptSearchToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
       'script_search',
-      '[OFFLINE] No Unity connection required. Search C# by substring/regex/glob with pagination and snippet context. PRIORITY: Use to locate symbols/files; avoid full contents. Use returnMode="snippets" (or "metadata") with small snippetContext (1–2). Narrow aggressively via include globs under Assets/** or Packages/** and semantic filters (namespace/container/identifier). Do NOT prefix repository folders.',
+      '[OFFLINE] No Unity connection required. Search C# by substring/regex/glob with pagination and snippet context. PRIORITY: Use to locate symbols/files; avoid full contents. Use returnMode="snippets" (or "metadata") with small snippetContext (1–2). Narrow aggressively via include globs under Assets/**, Packages/**, or Library/PackageCache/** and semantic filters (namespace/container/identifier). Do NOT prefix repository folders.',
       {
         type: 'object',
         properties: {
@@ -29,9 +29,9 @@ export class ScriptSearchToolHandler extends BaseToolHandler {
           },
           scope: {
             type: 'string',
-            enum: ['assets', 'packages', 'embedded', 'all'],
+            enum: ['assets', 'packages', 'embedded', 'library', 'all'],
             description:
-              'Search scope: assets (Assets/, default), packages (Packages/), embedded, or all.'
+              'Search scope: assets (Assets/), packages (Packages/), embedded, library (Library/PackageCache/), or all. Default: all.'
           },
           include: {
             type: 'string',
@@ -151,6 +151,7 @@ export class ScriptSearchToolHandler extends BaseToolHandler {
       if (scope === 'assets' || scope === 'all') roots.push(info.assetsPath);
       if (scope === 'packages' || scope === 'embedded' || scope === 'all')
         roots.push(info.packagesPath);
+      if (scope === 'library' || scope === 'all') roots.push(info.packageCachePath);
 
       const includeRx = globToRegExp(include);
       const excludeRx = exclude ? globToRegExp(exclude) : null;

package/src/handlers/ui/UIFindElementsToolHandler.js

@@ -24,6 +24,10 @@ export class UIFindElementsToolHandler extends BaseToolHandler {
         canvasFilter: {
           type: 'string',
           description: 'Filter by parent Canvas name.'
+        },
+        uiSystem: {
+          type: 'string',
+          description: 'Filter by UI system: ugui|uitk|imgui|all (default: all).'
         }
       },
       required: []
@@ -32,7 +36,14 @@ export class UIFindElementsToolHandler extends BaseToolHandler {
   }
 
   async execute(params = {}) {
-    const { elementType, tagFilter, namePattern, includeInactive = false, canvasFilter } = params;
+    const {
+      elementType,
+      tagFilter,
+      namePattern,
+      includeInactive = false,
+      canvasFilter,
+      uiSystem
+    } = params;
 
     // Ensure connected
     if (!this.unityConnection.isConnected()) {
@@ -44,7 +55,8 @@ export class UIFindElementsToolHandler extends BaseToolHandler {
       tagFilter,
       namePattern,
       includeInactive,
-      canvasFilter
+      canvasFilter,
+      uiSystem
     });
 
     // Return the result for the BaseToolHandler to format

package/src/tools/scene/getSceneInfo.js

@@ -57,10 +57,10 @@ export async function getSceneInfoHandler(unityConnection, args) {
     }
 
     // Send command to Unity
-    const result = await unityConnection.sendCommand('scene_info_get', args);
+    const result = await unityConnection.sendCommand('get_scene_info', args);
 
-    // Handle Unity response
-    if (result.status === 'error') {
+    // Unity returns errors as { error: "..." } payloads (still wrapped in a success response)
+    if (result && result.error) {
       return {
         content: [
           {
@@ -77,7 +77,7 @@ export async function getSceneInfoHandler(unityConnection, args) {
       content: [
         {
           type: 'text',
-          text: result.result.summary || `Scene information retrieved`
+          text: result?.summary || `Scene information retrieved`
         }
       ],
       isError: false