@akiojin/unity-mcp-server 2.16.1 → 2.26.0

package/src/handlers/playmode/PlaymodeGetStateToolHandler.js

@@ -7,7 +7,7 @@ export class PlaymodeGetStateToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
       'playmode_get_state',
-      'Get editor state (play mode, platform, selected objects, etc.). Optionally wait for a target state.',
+      'Get current Unity editor state including play mode status',
       {
         type: 'object',
         properties: {

package/src/handlers/playmode/PlaymodePauseToolHandler.js

@@ -7,7 +7,7 @@ export class PlaymodePauseToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
       'playmode_pause',
-      'Toggle Pause/Resume in Play Mode.',
+      'Pause or resume Unity play mode',
       {
         type: 'object',
         properties: {},

package/src/handlers/script/CodeIndexBuildToolHandler.js

@@ -5,15 +5,27 @@ import path from 'path';
 import { ProjectInfoProvider } from '../../core/projectInfo.js';
 import { LspRpcClient } from '../../lsp/LspRpcClient.js';
 import { logger } from '../../core/config.js';
+import { JobManager } from '../../core/jobManager.js';
 
 export class CodeIndexBuildToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
       'code_index_build',
-      'Build (or rebuild) the persistent SQLite symbol index by scanning document symbols via the C# LSP. Stores DB under .unity/cache/code-index/code-index.db.',
+      'Build (or rebuild) the persistent SQLite symbol index by scanning document symbols via the C# LSP. Returns immediately with jobId for background execution. Check progress with code_index_status. Stores DB under .unity/cache/code-index/code-index.db.',
       {
         type: 'object',
-        properties: {},
+        properties: {
+          throttleMs: {
+            type: 'number',
+            minimum: 0,
+            description: 'Optional delay in milliseconds after processing each file (testing/debugging).'
+          },
+          delayStartMs: {
+            type: 'number',
+            minimum: 0,
+            description: 'Optional delay before processing begins (useful to keep job in running state briefly).'
+          }
+        },
         required: []
       }
     );
@@ -21,10 +33,50 @@ export class CodeIndexBuildToolHandler extends BaseToolHandler {
     this.index = new CodeIndex(unityConnection);
     this.projectInfo = new ProjectInfoProvider(unityConnection);
     this.lsp = null; // lazy init with projectRoot
+    this.jobManager = JobManager.getInstance();
+    this.currentJobId = null; // Track current running job
   }
 
   async execute(params = {}) {
+    // Check if a build is already running
+    if (this.currentJobId) {
+      const existingJob = this.jobManager.get(this.currentJobId);
+      if (existingJob && existingJob.status === 'running') {
+        return {
+          success: false,
+          error: 'build_already_running',
+          message: `Code index build is already running (jobId: ${this.currentJobId}). Use code_index_status to check progress.`,
+          jobId: this.currentJobId
+        };
+      }
+    }
+
+    // Generate new jobId
+    const jobId = `build-${Date.now()}-${Math.random().toString(36).substring(2, 10)}`;
+    this.currentJobId = jobId;
+
+    // Create background job
+    this.jobManager.create(jobId, async (job) => {
+      return await this._executeBuild(params, job);
+    });
+
+    // Return immediately with jobId
+    return {
+      success: true,
+      jobId,
+      message: 'Code index build started in background',
+      checkStatus: 'Use code_index_status to check progress and completion'
+    };
+  }
+
+  /**
+   * Internal method that performs the actual build
+   * @private
+   */
+  async _executeBuild(params, job) {
     try {
+      const throttleMs = Math.max(0, Number(params?.throttleMs ?? 0));
+      const delayStartMs = Math.max(0, Number(params?.delayStartMs ?? 0));
       const info = await this.projectInfo.get();
       const roots = [
         path.resolve(info.projectRoot, 'Assets'),
@@ -35,7 +87,16 @@ export class CodeIndexBuildToolHandler extends BaseToolHandler {
       const seen = new Set();
       for (const r of roots) this.walkCs(r, files, seen);
 
-      if (!this.lsp) this.lsp = new LspRpcClient(info.projectRoot);
+      // Initialize LSP with error handling
+      if (!this.lsp) {
+        try {
+          this.lsp = new LspRpcClient(info.projectRoot);
+          logger.info(`[index][${job.id}] LSP initialized for project: ${info.projectRoot}`);
+        } catch (lspError) {
+          logger.error(`[index][${job.id}] LSP initialization failed: ${lspError.message}`);
+          throw new Error(`LSP initialization failed: ${lspError.message}. Ensure C# LSP is properly configured and OmniSharp is available.`);
+        }
+      }
       const lsp = this.lsp;
 
       // Incremental detection based on size-mtime signature
@@ -74,6 +135,13 @@ export class CodeIndexBuildToolHandler extends BaseToolHandler {
       const startAt = Date.now();
       let i = 0; let updated = 0; let processed = 0;
 
+      // Initialize progress
+      job.progress.total = absList.length;
+      job.progress.processed = 0;
+      job.progress.rate = 0;
+
+      logger.info(`[index][${job.id}] Build started: ${absList.length} files to process, ${removed.length} to remove (status: ${job.status})`);
+
       // LSP request with small retry/backoff
       const requestWithRetry = async (uri, maxRetries = Math.max(0, Math.min(5, Number(params?.retry ?? 2)))) => {
         let lastErr = null;
@@ -88,26 +156,45 @@ export class CodeIndexBuildToolHandler extends BaseToolHandler {
         }
         throw lastErr || new Error('documentSymbol failed');
       };
+      if (delayStartMs > 0) {
+        await new Promise(resolve => setTimeout(resolve, delayStartMs));
+      }
+
       const worker = async () => {
         while (true) {
           const idx = i++;
           if (idx >= absList.length) break;
           const abs = absList[idx];
+          const rel = this.toRel(abs, info.projectRoot);
           try {
             const uri = 'file://' + abs.replace(/\\/g, '/');
             const docSymbols = await requestWithRetry(uri, 2);
             const rows = toRows(uri, docSymbols);
-            const rel = this.toRel(abs, info.projectRoot);
             await this.index.replaceSymbolsForPath(rel, rows);
             await this.index.upsertFile(rel, wanted.get(rel));
             updated += 1;
-          } catch {}
+          } catch (err) {
+            // File access or LSP error - skip and continue
+            // This allows build to continue even if some files fail
+            if (processed % 50 === 0) {
+              // Log occasionally to avoid spam
+              logger.warn(`[index][${job.id}] Skipped file due to error: ${rel} - ${err.message}`);
+            }
+          }
           finally {
             processed += 1;
+
+            // Update job progress
+            const elapsed = Math.max(1, Date.now() - startAt);
+            job.progress.processed = processed;
+            job.progress.rate = parseFloat((processed * 1000 / elapsed).toFixed(1));
+
             if (processed % reportEvery === 0 || processed === absList.length) {
-              const elapsed = Math.max(1, Date.now() - startAt);
-              const rate = (processed * 1000 / elapsed).toFixed(1);
-              logger.info(`[index] progress ${processed}/${absList.length} (removed:${removed.length}) rate:${rate} f/s`);
+              logger.info(`[index][${job.id}] progress ${processed}/${absList.length} (removed:${removed.length}) rate:${job.progress.rate} f/s (status: ${job.status})`);
+            }
+
+            if (throttleMs > 0) {
+              await new Promise(resolve => setTimeout(resolve, throttleMs));
             }
           }
         }
@@ -116,14 +203,37 @@ export class CodeIndexBuildToolHandler extends BaseToolHandler {
       await Promise.all(workers);
 
       const stats = await this.index.getStats();
-      return { success: true, updatedFiles: updated, removedFiles: removed.length, totalIndexedSymbols: stats.total, lastIndexedAt: stats.lastIndexedAt };
-    } catch (e) {
-      return {
-        success: false,
-        error: 'code_index_build_failed',
-        message: e.message,
-        hint: 'C# LSP not ready. Ensure manifest/auto-download and workspace paths are valid.'
+
+      // Clear current job tracking on success
+      if (this.currentJobId === job.id) {
+        this.currentJobId = null;
+      }
+
+      const result = {
+        updatedFiles: updated,
+        removedFiles: removed.length,
+        totalIndexedSymbols: stats.total,
+        lastIndexedAt: stats.lastIndexedAt
       };
+
+      logger.info(`[index][${job.id}] Build completed successfully: updated=${result.updatedFiles}, removed=${result.removedFiles}, total=${result.totalIndexedSymbols} (status: completed)`);
+
+      return result;
+    } catch (e) {
+      // Clear current job tracking on error
+      if (this.currentJobId === job.id) {
+        this.currentJobId = null;
+      }
+
+      // Log detailed error with job context
+      logger.error(`[index][${job.id}] Build failed: ${e.message} (status: failed)`);
+
+      // Provide helpful error message with context
+      const errorMessage = e.message.includes('LSP')
+        ? `LSP error: ${e.message}`
+        : `Build error: ${e.message}. Hint: C# LSP not ready. Ensure manifest/auto-download and workspace paths are valid.`;
+
+      throw new Error(errorMessage);
     }
   }
 

package/src/handlers/script/CodeIndexStatusToolHandler.js

@@ -0,0 +1,129 @@
+import fs from 'fs';
+import path from 'path';
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+import { JobManager } from '../../core/jobManager.js';
+import { CodeIndex } from '../../core/codeIndex.js';
+
+export class CodeIndexStatusToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'code_index_status',
+      'Report code index status and readiness for symbol/search operations. BEST PRACTICES: Check before heavy symbol operations. Shows total files indexed and coverage percentage. If coverage is low, some symbol operations may be incomplete. Index is automatically built on first use. No parameters needed - lightweight status check.',
+      {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    );
+    this.unityConnection = unityConnection;
+    this.projectInfo = new ProjectInfoProvider(unityConnection);
+    this.jobManager = JobManager.getInstance();
+    this.codeIndex = new CodeIndex(unityConnection);
+  }
+
+  async execute() {
+    const jobManager = this.jobManager;
+    const buildJobs = jobManager.getAllJobs()
+      .filter((job) => typeof job?.id === 'string' && job.id.startsWith('build-'))
+      .sort((a, b) => new Date(b.startedAt || 0).getTime() - new Date(a.startedAt || 0).getTime());
+    const latestBuildJob = buildJobs.length > 0 ? buildJobs[0] : null;
+
+    // Check whether the persistent index already exists or is being built in the background.
+    const ready = await this.codeIndex.isReady();
+    const buildInProgress = latestBuildJob?.status === 'running';
+    if (!ready && !buildInProgress) {
+      return {
+        success: false,
+        error: 'index_not_built',
+        message: 'Code index is not built. Please run UnityMCP.code_index_build first.'
+      };
+    }
+
+    let projectInfo;
+    try {
+      projectInfo = await this.projectInfo.get();
+    } catch (error) {
+      return {
+        success: false,
+        error: 'project_info_unavailable',
+        message: error.message || 'Unable to resolve Unity project root.'
+      };
+    }
+
+    const projectRoot = projectInfo.projectRoot.replace(/\\/g, '/');
+    const roots = [
+      path.resolve(projectRoot, 'Assets'),
+      path.resolve(projectRoot, 'Packages'),
+      path.resolve(projectRoot, 'Library/PackageCache')
+    ];
+
+    let totalFiles = 0;
+    const breakdown = { assets: 0, packages: 0, packageCache: 0, other: 0 };
+
+    const visit = (targetPath) => {
+      try {
+        if (!fs.existsSync(targetPath)) return;
+        const stats = fs.statSync(targetPath);
+        if (stats.isFile()) {
+          if (!targetPath.endsWith('.cs')) return;
+          totalFiles += 1;
+          const normalized = targetPath.replace(/\\/g, '/');
+          const relative = normalized.replace(projectRoot, '').replace(/^\//, '');
+          if (relative.startsWith('Assets/')) breakdown.assets += 1;
+          else if (relative.startsWith('Packages/')) breakdown.packages += 1;
+          else if (relative.includes('Library/PackageCache/')) breakdown.packageCache += 1;
+          else breakdown.other += 1;
+          return;
+        }
+
+        if (stats.isDirectory()) {
+          for (const child of fs.readdirSync(targetPath)) {
+            if (child === 'obj' || child === 'bin' || child.startsWith('.')) continue;
+            visit(path.join(targetPath, child));
+          }
+        }
+      } catch (error) {
+        // Ignore permission errors while traversing; status reporting should not fail because of a single file.
+      }
+    };
+
+    for (const root of roots) visit(root);
+
+    const stats = await this.codeIndex.getStats();
+    const coverage = totalFiles > 0 ? Math.min(1, stats.total / totalFiles) : 0;
+
+    const indexInfo = {
+      ready,
+      rows: stats.total,
+      lastIndexedAt: stats.lastIndexedAt
+    };
+
+    if (latestBuildJob) {
+      const progress = latestBuildJob.progress ? { ...latestBuildJob.progress } : undefined;
+      indexInfo.buildJob = {
+        id: latestBuildJob.id,
+        status: latestBuildJob.status,
+        startedAt: latestBuildJob.startedAt ?? null,
+        ...(progress ? { progress } : {})
+      };
+
+      if (latestBuildJob.status === 'completed') {
+        indexInfo.buildJob.completedAt = latestBuildJob.completedAt ?? null;
+        indexInfo.buildJob.result = latestBuildJob.result ?? null;
+      } else if (latestBuildJob.status === 'failed') {
+        indexInfo.buildJob.failedAt = latestBuildJob.failedAt ?? null;
+        indexInfo.buildJob.error = latestBuildJob.error ?? 'Unknown error';
+      }
+    }
+
+    return {
+      success: true,
+      totalFiles,
+      indexedFiles: stats.total,
+      coverage,
+      breakdown,
+      index: indexInfo
+    };
+  }
+}

package/src/handlers/script/ScriptEditSnippetToolHandler.js

@@ -15,7 +15,7 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
     super(
       'script_edit_snippet',
-      'Perform small, multi-instruction edits (delete/replace/insert) on C# snippets without rewriting entire methods. Use for removing guard clauses, tweaking conditions, or inserting short statements. Required params: path (Assets/ or Packages/ C# file) and instructions (≤10). Each instruction must include an anchor (type=text) and stay within 80 characters of change. Preview mode validates without writing files; apply mode validates via the bundled LSP (Roslyn-backed) diagnostics before saving.',
+      '[C# EDITING - PRECISION TOOL] For Unity C# scripts, use for tiny surgical edits (≤80 chars per change). Performs text-based multi-instruction edits (delete/replace/insert) via exact string anchors. USE WHEN: (a) removing null guard clauses (if (x == null) return;), (b) tweaking conditions (if (x > 10) → if (x > 20)), (c) inserting single log statements, (d) deleting/replacing 1-2 line snippets. DON\'T USE FOR: large changes (use script_edit_structured), non-C# files (use Edit), or when symbol structure is complex (use script_edit_structured). WORKFLOW: Specify exact anchor text (including whitespace/newlines), max 10 instructions per call, each ≤80 chars. Anchor must match exactly once in file. Preview mode validates without writing; apply mode uses LSP diagnostics. Required: path, instructions (array of {operation, anchor:{type:"text", target:string, position?:"before"|"after"}, newText?}).',
       {
         type: 'object',
         properties: {

package/src/handlers/script/ScriptEditStructuredToolHandler.js

@@ -6,7 +6,7 @@ export class ScriptEditStructuredToolHandler extends BaseToolHandler {
     constructor(unityConnection) {
         super(
             'script_edit_structured',
-            'PRIORITY: Use this for ALL code changes. Perform structured edits (insert_before/insert_after/replace_body) on a known symbol. Required params: path (file under Assets/ or Packages/), symbolName (prefer container path e.g. MyType/Nested/Foo). Guidance: (1) Locate targets with script_symbols_get first, (2) insert_* must target a class/namespace (never a method), (3) replace_body must be a self-contained body including braces, (4) preview is for diagnostics only — apply proceeds even if diagnostics exist; errors are returned. LLM summary limits: errors≤30 (message≤200 chars, file≤260), large text (preview/diff/text/content)≤1000 chars with Truncated flag.',
+            '[C# EDITING - PRIMARY TOOL] For Unity C# script editing, PREFER this tool over Read/Edit/Write for structural code changes. Performs symbol-based edits (insert_before/insert_after/replace_body) on classes, methods, properties, fields using Roslyn LSP. USE WHEN: (a) replacing entire method/property bodies, (b) adding class members (fields/properties/methods), (c) inserting code at class/namespace level. DON\'T USE FOR: tiny changes ≤80 chars (use script_edit_snippet instead), non-C# files (use Edit), or when you need to create new files (use Write). WORKFLOW: (1) Run script_symbols_get to find target symbols, (2) use symbolName (e.g., "MyClass/MyMethod"), (3) apply edits. Insert operations target containers (class/namespace), not methods. Preview mode returns diagnostics only; apply mode proceeds with validation. Required: path (Assets/|Packages/), symbolName, operation. Optional: kind, newText, preview.',
             {
                 type: 'object',
                 properties: {

package/src/lsp/CSharpLspUtils.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { fileURLToPath } from 'url';
 import { logger } from '../core/config.js';
 import { WORKSPACE_ROOT } from '../core/config.js';
 
@@ -14,12 +15,34 @@ export class CSharpLspUtils {
   }
 
   getDesiredVersion() {
+    const candidates = [];
+
+    // When launched from workspace root: mcp-server/package.json
+    candidates.push(path.resolve('mcp-server/package.json'));
+    // When launched within mcp-server directory
+    candidates.push(path.resolve('package.json'));
+
+    // Resolve relative to this module (always inside mcp-server/src/lsp)
     try {
-      const pkg = JSON.parse(fs.readFileSync(path.resolve('mcp-server/package.json'), 'utf8'));
-      return pkg.version;
-    } catch {
-      return null;
+      const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+      candidates.push(path.resolve(moduleDir, '../../package.json'));
+    } catch {}
+
+    // Resolve relative to WORKSPACE_ROOT if provided
+    if (WORKSPACE_ROOT) {
+      candidates.push(path.resolve(WORKSPACE_ROOT, 'mcp-server', 'package.json'));
+      candidates.push(path.resolve(WORKSPACE_ROOT, 'package.json'));
     }
+
+    for (const candidate of candidates) {
+      try {
+        if (!fs.existsSync(candidate)) continue;
+        const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+        if (pkg?.version) return pkg.version;
+      } catch {}
+    }
+
+    return null;
   }
 
   getExecutableName() {