@akiojin/unity-mcp-server 2.16.1 → 2.26.0

package/src/core/indexWatcher.js

@@ -1,10 +1,13 @@
 import { logger, config } from './config.js';
+import { JobManager } from './jobManager.js';
 
 export class IndexWatcher {
   constructor(unityConnection) {
     this.unityConnection = unityConnection;
     this.timer = null;
     this.running = false;
+    this.jobManager = JobManager.getInstance();
+    this.currentWatcherJobId = null;
   }
 
   start() {
@@ -13,6 +16,9 @@ export class IndexWatcher {
     const interval = Math.max(2000, Number(config.indexing.intervalMs || 15000));
     logger.info(`[index] watcher enabled (interval=${interval}ms)`);
     this.timer = setInterval(() => this.tick(), interval);
+    if (typeof this.timer.unref === 'function') {
+      this.timer.unref();
+    }
     // Initial kick
     this.tick();
   }
@@ -28,24 +34,88 @@ export class IndexWatcher {
     if (this.running) return;
     this.running = true;
     try {
+      // Check if manual build is already running (jobs starting with 'build-')
+      const allJobs = this.jobManager.getAllJobs();
+      const manualBuildRunning = allJobs.some(job =>
+        job.id.startsWith('build-') && job.status === 'running'
+      );
+
+      if (manualBuildRunning) {
+        logger.info('[index] watcher: skipping auto-build (manual build in progress)');
+        return;
+      }
+
+      // Check if our watcher job is still running
+      if (this.currentWatcherJobId) {
+        const watcherJob = this.jobManager.get(this.currentWatcherJobId);
+        if (watcherJob && watcherJob.status === 'running') {
+          logger.info('[index] watcher: previous auto-build still running, skipping');
+          return;
+        }
+        // Previous watcher job completed or cleaned up
+        this.currentWatcherJobId = null;
+      }
+
+      // Start new watcher build job
+      const jobId = `watcher-${Date.now()}`;
+      this.currentWatcherJobId = jobId;
+
       const { CodeIndexBuildToolHandler } = await import('../handlers/script/CodeIndexBuildToolHandler.js');
       const handler = new CodeIndexBuildToolHandler(this.unityConnection);
-      const params = {
-        concurrency: config.indexing.concurrency || 8,
-        retry: config.indexing.retry || 2,
-        reportEvery: config.indexing.reportEvery || 500,
-      };
-      const res = await handler.handle(params);
-      const ok = res?.result?.success;
-      if (ok) {
-        logger.info(`[index] updated=${res.result.updatedFiles || 0} removed=${res.result.removedFiles || 0} total=${res.result.totalIndexedSymbols || 0}`);
-      } else if (res?.result?.error) {
-        logger.warn(`[index] update failed: ${res.result.error}`);
-      }
+
+      // Create the build job through JobManager
+      this.jobManager.create(jobId, async (job) => {
+        const params = {
+          concurrency: config.indexing.concurrency || 8,
+          retry: config.indexing.retry || 2,
+          reportEvery: config.indexing.reportEvery || 500,
+        };
+        return await handler._executeBuild(params, job);
+      });
+
+      logger.info(`[index] watcher: started auto-build job ${jobId}`);
+
+      // Monitor job completion in background
+      // (Job result will be logged when it completes/fails)
+      this._monitorJob(jobId);
+
     } catch (e) {
-      logger.warn(`[index] update exception: ${e.message}`);
+      logger.warn(`[index] watcher exception: ${e.message}`);
     } finally {
       this.running = false;
     }
   }
+
+  /**
+   * Monitor job completion for logging
+   * @private
+   */
+  async _monitorJob(jobId) {
+    // Check job status periodically
+    const checkInterval = setInterval(() => {
+      const job = this.jobManager.get(jobId);
+      if (!job) {
+        // Job cleaned up
+        clearInterval(checkInterval);
+        return;
+      }
+
+      if (job.status === 'completed') {
+        logger.info(`[index] watcher: auto-build completed - updated=${job.result?.updatedFiles || 0} removed=${job.result?.removedFiles || 0} total=${job.result?.totalIndexedSymbols || 0}`);
+        clearInterval(checkInterval);
+      } else if (job.status === 'failed') {
+        logger.warn(`[index] watcher: auto-build failed - ${job.error}`);
+        clearInterval(checkInterval);
+      }
+    }, 1000);
+    if (typeof checkInterval.unref === 'function') {
+      checkInterval.unref();
+    }
+
+    // Cleanup interval after 10 minutes (longer than job cleanup)
+    const cleanupTimeout = setTimeout(() => clearInterval(checkInterval), 600000);
+    if (typeof cleanupTimeout.unref === 'function') {
+      cleanupTimeout.unref();
+    }
+  }
 }

package/src/core/jobManager.js

@@ -0,0 +1,178 @@
+/**
+ * JobManager - Manages background job execution and tracking
+ *
+ * SPEC-yt3ikddd: Background job execution for code index build
+ * - Memory-based job tracking (no persistence)
+ * - Single concurrent job execution
+ * - Auto-cleanup after 5 minutes (configurable)
+ */
+
+/**
+ * BuildJob structure
+ * @typedef {Object} BuildJob
+ * @property {string} id - Unique job identifier
+ * @property {'running'|'completed'|'failed'} status - Current job status
+ * @property {Object} progress - Progress information
+ * @property {number} progress.processed - Number of processed items
+ * @property {number} progress.total - Total items to process
+ * @property {number} progress.rate - Processing rate (items/sec)
+ * @property {Object|null} result - Result object (only for completed jobs)
+ * @property {number} result.updatedFiles - Number of updated files
+ * @property {number} result.removedFiles - Number of removed files
+ * @property {number} result.totalIndexedSymbols - Total indexed symbols
+ * @property {string} result.lastIndexedAt - ISO8601 timestamp of last index
+ * @property {string|null} error - Error message (only for failed jobs)
+ * @property {string} startedAt - ISO8601 timestamp when job started
+ * @property {string|null} completedAt - ISO8601 timestamp when job completed
+ * @property {string|null} failedAt - ISO8601 timestamp when job failed
+ */
+
+export class JobManager {
+  constructor() {
+    /**
+     * Map of jobId -> BuildJob
+     * @type {Map<string, BuildJob>}
+     */
+    this.jobs = new Map();
+
+    /**
+     * Map of jobId -> cleanup timeout handle
+     * @type {Map<string, NodeJS.Timeout>}
+     */
+    this.cleanupTimers = new Map();
+  }
+
+  /**
+   * Get the singleton instance
+   * @returns {JobManager}
+   */
+  static getInstance() {
+    if (!JobManager._instance) {
+      JobManager._instance = new JobManager();
+    }
+    return JobManager._instance;
+  }
+
+  /**
+   * Create a new job and execute it in background
+   *
+   * @param {string} jobId - Unique job identifier
+   * @param {Function} jobFn - Async function to execute: async (job) => result
+   * @returns {string} jobId - Returns immediately
+   */
+  create(jobId, jobFn) {
+    // Create initial job object
+    const job = {
+      id: jobId,
+      status: 'running',
+      progress: {
+        processed: 0,
+        total: 0,
+        rate: 0
+      },
+      result: null,
+      error: null,
+      startedAt: new Date().toISOString(),
+      completedAt: null,
+      failedAt: null
+    };
+
+    // Store job
+    this.jobs.set(jobId, job);
+
+    // Execute in background (don't await)
+    this._executeJob(jobId, jobFn, job);
+
+    // Return jobId immediately
+    return jobId;
+  }
+
+  /**
+   * Get job by ID
+   *
+   * @param {string} jobId - Job identifier
+   * @returns {BuildJob|undefined} Job object or undefined if not found
+   */
+  get(jobId) {
+    return this.jobs.get(jobId);
+  }
+
+  /**
+   * Schedule job cleanup after retention period
+   *
+   * @param {string} jobId - Job identifier
+   * @param {number} retentionMs - Retention period in milliseconds (default: 5 minutes)
+   */
+  cleanup(jobId, retentionMs = 300000) {
+    // Clear any existing cleanup timer
+    if (this.cleanupTimers.has(jobId)) {
+      clearTimeout(this.cleanupTimers.get(jobId));
+    }
+
+    // Schedule new cleanup
+    const timer = setTimeout(() => {
+      this.jobs.delete(jobId);
+      this.cleanupTimers.delete(jobId);
+    }, retentionMs);
+    if (typeof timer.unref === 'function') {
+      timer.unref();
+    }
+
+    this.cleanupTimers.set(jobId, timer);
+  }
+
+  /**
+   * Execute job function in background
+   *
+   * @private
+   * @param {string} jobId - Job identifier
+   * @param {Function} jobFn - Async job function
+   * @param {BuildJob} job - Job object (passed by reference for progress updates)
+   */
+  async _executeJob(jobId, jobFn, job) {
+    try {
+      // Execute job function
+      // jobFn can update job.progress directly
+      const result = await jobFn(job);
+
+      // Update job on success
+      job.status = 'completed';
+      job.result = result;
+      job.completedAt = new Date().toISOString();
+
+      // Schedule cleanup after 5 minutes
+      this.cleanup(jobId, 300000);
+    } catch (error) {
+      // Update job on failure
+      job.status = 'failed';
+      job.error = error.message || String(error);
+      job.failedAt = new Date().toISOString();
+
+      // Schedule cleanup after 5 minutes
+      this.cleanup(jobId, 300000);
+    }
+  }
+
+  /**
+   * Get all jobs (for debugging/testing)
+   *
+   * @returns {BuildJob[]} Array of all jobs
+   */
+  getAllJobs() {
+    return Array.from(this.jobs.values());
+  }
+
+  /**
+   * Clear all jobs (for testing)
+   */
+  clearAll() {
+    // Clear all cleanup timers
+    for (const timer of this.cleanupTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.cleanupTimers.clear();
+
+    // Clear all jobs
+    this.jobs.clear();
+  }
+}

package/src/core/projectInfo.js

@@ -1,118 +1,65 @@
-import fs from 'fs';
-import path from 'path';
-import { logger, config, WORKSPACE_ROOT } from './config.js';
-
-const normalize = (p) => p.replace(/\\/g, '/');
-
-const resolveDefaultCodeIndexRoot = (projectRoot) => {
-  const base = WORKSPACE_ROOT || projectRoot || process.cwd();
-  return normalize(path.join(base, '.unity', 'cache', 'code-index'));
-};
-
-// Lazy project info resolver. Prefers Unity via get_editor_info, otherwise infers by walking up for Assets/Packages.
-export class ProjectInfoProvider {
-  constructor(unityConnection) {
-    this.unityConnection = unityConnection;
-    this.cached = null;
-    this.lastTried = 0;
-  }
-
-  async get() {
-    if (this.cached) return this.cached;
-    // Config-driven project root (no env fallback)
-    const cfgRoot = config?.project?.root;
-    if (cfgRoot) {
-      // Resolve relative paths against WORKSPACE_ROOT
-      const projectRoot = normalize(path.isAbsolute(cfgRoot) ? cfgRoot : path.resolve(WORKSPACE_ROOT, cfgRoot));
-      const codeIndexRoot = normalize(config?.project?.codeIndexRoot || resolveDefaultCodeIndexRoot(projectRoot));
-      this.cached = {
-        projectRoot,
-        assetsPath: normalize(path.join(projectRoot, 'Assets')),
-        packagesPath: normalize(path.join(projectRoot, 'Packages')),
-        codeIndexRoot,
-      };
-      return this.cached;
-    }
-    // Try Unity if connected (rate-limit attempts)
-    const now = Date.now();
-    if (this.unityConnection && this.unityConnection.isConnected() && (now - this.lastTried > 1000)) {
-      this.lastTried = now;
-      try {
-        const info = await this.unityConnection.sendCommand('get_editor_info', {});
-        if (info && info.projectRoot && info.assetsPath) {
-          this.cached = {
-            projectRoot: info.projectRoot,
-            assetsPath: info.assetsPath,
-            packagesPath: normalize(info.packagesPath || path.join(info.projectRoot, 'Packages')),
-            codeIndexRoot: normalize(info.codeIndexRoot || resolveDefaultCodeIndexRoot(info.projectRoot)),
-          };
-          return this.cached;
-        }
-      } catch (e) {
-        logger.warn(`get_editor_info failed: ${e.message}`);
-      }
-    }
-    // Fallback: infer by walking up from CWD to find Assets/
-    const inferred = this.inferFromCwd();
-    if (inferred) {
-      this.cached = inferred;
-      return this.cached;
-    }
-    throw new Error('Unable to resolve Unity project root (no connection and no Assets/ found)');
-  }
-
-  inferFromCwd() {
-    // First, check for Docker environment default path
-    const dockerDefaultPath = '/unity-mcp-server/UnityMCPServer';
-    const dockerAssets = path.join(dockerDefaultPath, 'Assets');
-    if (fs.existsSync(dockerAssets)) {
-      const projectRoot = normalize(dockerDefaultPath);
-      logger.info(`Found Unity project at Docker default path: ${projectRoot}`);
-      return {
-        projectRoot,
-        assetsPath: normalize(dockerAssets),
-        packagesPath: normalize(path.join(dockerDefaultPath, 'Packages')),
-        codeIndexRoot: resolveDefaultCodeIndexRoot(projectRoot),
-      };
-    }
-
-    let dir = process.cwd();
-    // Walk up max 5 levels (look for Assets directly under a directory)
-    for (let i = 0; i < 5; i++) {
-      const assets = path.join(dir, 'Assets');
-      if (fs.existsSync(assets)) {
-        const projectRoot = normalize(dir);
-        return {
-          projectRoot,
-          assetsPath: normalize(assets),
-          packagesPath: normalize(path.join(dir, 'Packages')),
-          codeIndexRoot: resolveDefaultCodeIndexRoot(projectRoot),
-        };
-      }
-      dir = path.dirname(dir);
-    }
-
-    // Fallback: search shallow subdirectories for Unity projects (depth 2)
-    const rootsToCheck = [process.cwd(), path.dirname(process.cwd())];
-    for (const root of rootsToCheck) {
-      try {
-        const entries = fs.readdirSync(root, { withFileTypes: true });
-        for (const e of entries) {
-          if (!e.isDirectory()) continue;
-          const candidate = path.join(root, e.name);
-          const assets = path.join(candidate, 'Assets');
-          if (fs.existsSync(assets)) {
-            const projectRoot = normalize(candidate);
-            return {
-              projectRoot,
-              assetsPath: normalize(assets),
-              packagesPath: normalize(path.join(candidate, 'Packages')),
-              codeIndexRoot: resolveDefaultCodeIndexRoot(projectRoot),
-            };
-          }
-        }
-      } catch {}
-    }
-    return null;
-  }
-}
+import fs from 'fs';
+import path from 'path';
+import { logger, config, WORKSPACE_ROOT } from './config.js';
+
+const normalize = (p) => p.replace(/\\/g, '/');
+
+const resolveDefaultCodeIndexRoot = (projectRoot) => {
+  const base = WORKSPACE_ROOT || projectRoot || process.cwd();
+  return normalize(path.join(base, '.unity', 'cache', 'code-index'));
+};
+
+// Lazy project info resolver. Prefers Unity via get_editor_info, otherwise infers by walking up for Assets/Packages.
+export class ProjectInfoProvider {
+  constructor(unityConnection) {
+    this.unityConnection = unityConnection;
+    this.cached = null;
+    this.lastTried = 0;
+  }
+
+  async get() {
+    if (this.cached) return this.cached;
+    // Config-driven project root (no env fallback)
+    const cfgRootRaw = config?.project?.root;
+    if (typeof cfgRootRaw === 'string' && cfgRootRaw.trim().length > 0) {
+      const cfgRoot = cfgRootRaw.trim();
+      // Resolve relative paths against WORKSPACE_ROOT
+      const projectRoot = normalize(path.isAbsolute(cfgRoot) ? cfgRoot : path.resolve(WORKSPACE_ROOT, cfgRoot));
+      const codeIndexRoot = normalize(config?.project?.codeIndexRoot || resolveDefaultCodeIndexRoot(projectRoot));
+      this.cached = {
+        projectRoot,
+        assetsPath: normalize(path.join(projectRoot, 'Assets')),
+        packagesPath: normalize(path.join(projectRoot, 'Packages')),
+        codeIndexRoot,
+      };
+      return this.cached;
+    }
+    // Try Unity if connected (rate-limit attempts)
+    const now = Date.now();
+    if (this.unityConnection && this.unityConnection.isConnected() && (now - this.lastTried > 1000)) {
+      this.lastTried = now;
+      try {
+        const info = await this.unityConnection.sendCommand('get_editor_info', {});
+        if (info && info.projectRoot && info.assetsPath) {
+          this.cached = {
+            projectRoot: info.projectRoot,
+            assetsPath: info.assetsPath,
+            packagesPath: normalize(info.packagesPath || path.join(info.projectRoot, 'Packages')),
+            codeIndexRoot: normalize(info.codeIndexRoot || resolveDefaultCodeIndexRoot(info.projectRoot)),
+          };
+          return this.cached;
+        }
+      } catch (e) {
+        logger.warn(`get_editor_info failed: ${e.message}`);
+      }
+    }
+    if (typeof cfgRootRaw === 'string') {
+      throw new Error('project.root is configured but empty. Set a valid path in .unity/config.json or UNITY_MCP_CONFIG.');
+    }
+    throw new Error('Unable to resolve Unity project root. Configure project.root in .unity/config.json or provide UNITY_MCP_CONFIG.');
+  }
+
+  inferFromCwd() {
+    return null;
+  }
+}

package/src/core/server.js

@@ -169,7 +169,7 @@ unityConnection.on('error', (error) => {
 });
 
 // Initialize server
-async function main() {
+export async function startServer() {
   try {
     // Create transport - no logging before connection
     const transport = new StdioServerTransport();
@@ -232,6 +232,9 @@ async function main() {
   }
 }
 
+// Maintain backwards compatibility for older callers that expect main()
+const main = startServer;
+
 // Export for testing
 export async function createServer(customConfig = config) {
   const testUnityConnection = new UnityConnection();
@@ -287,7 +290,17 @@ export async function createServer(customConfig = config) {
 }
 
 // Start the server
-main().catch((error) => {
+const isDirectExecution = (() => {
+  if (process.env.NODE_ENV === 'test') return false;
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === new URL('file://' + process.argv[1]).href;
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirectExecution) startServer().catch((error) => {
   console.error('Fatal error:', error);
   console.error('Stack trace:', error.stack);
   process.exit(1);