@akiojin/unity-mcp-server 2.16.1 → 2.25.0

package/README.md

@@ -87,6 +87,16 @@ Add to your `claude_desktop_config.json`:
 
 > **Tip:** `code_index_update` は JSON パラメータ `paths` に絶対パス／相対パスの配列を渡すだけで完了します。内部で存在チェックと LSP リトライを行うため、Unity を起動したままでも短時間で終わります。
 
+### インデックス状態を検証したいとき
+
+ビルド中・未構築・完了後といったステータスを再現したい場合は、`code_index_build` に `delayStartMs` や `throttleMs` を付けて進捗を意図的に保ちます。さらに、`npm run simulate:code-index` を実行すると以下が自動化されます。
+
+- 既存インデックスのリセット（`--reset`）
+- `code_index_build` のバックグラウンド実行（任意の `--delayStart=MS` / `--throttle=MS`）
+- 指定間隔での `code_index_status` ポーリング（`--poll=MS`）
+
+出力される JSON を追うことで、`ready: false` → `true` へ遷移する様子や `buildJob.status` の変化を簡単に確認できます。
+
 ## Available Tools (Standardized Names)
 
 ### System & Core Tools
@@ -105,6 +115,7 @@ Add to your `claude_desktop_config.json`:
 - `component_add` — Add Unity components to GameObjects with initial properties
 - `component_remove` — Remove components from GameObjects with safety checks
 - `component_modify` — Modify component properties with nested support
+- `component_field_set` — Update serialized fields (including private `[SerializeField]` values, arrays, and nested structs)
 - `component_list` — List all components on a GameObject with type information
 - `component_get_types` — Discover available component types with filtering
 
@@ -149,10 +160,10 @@ Add to your `claude_desktop_config.json`:
 - `script_remove_symbol` — Delete symbols (types/members) with reference checks
 - `script_refactor_rename` — Rename symbols project-wide via LSP
 - `script_packages_list` — List installed packages relevant to scripting
-- `script_index_status` — Report status of the persistent code index
+- `code_index_status` — Report status of the persistent code index
 
 ### Code Index Utilities
-- `code_index_build` — フルスキャンでシンボルインデックスを再構築
+- `code_index_build` — フルスキャンでシンボルインデックスを再構築（開発時は `delayStartMs` や `throttleMs` で進捗観測用に速度調整可能）
 - `code_index_update` — 変更した C# ファイルのみ差分再インデックス
 
 ### Play Mode Controls
@@ -216,7 +227,6 @@ Add to your `claude_desktop_config.json`:
 - `test_run` — Run Unity tests (EditMode/PlayMode)
 - `test_get_status` — Query test runner progress/results
 
-
 ## Requirements
 
 - **Unity**: 2020.3 LTS or newer (Unity 6 supported)
@@ -242,7 +252,7 @@ npm install -g @akiojin/unity-mcp-server
 
 ## Repository
 
-Full source code and documentation: https://github.com/akiojin/unity-mcp-server
+Full source code and documentation: <https://github.com/akiojin/unity-mcp-server>
 
 ## License
 

package/bin/unity-mcp-server

@@ -1,2 +1,8 @@
 #!/usr/bin/env node
-import '../src/core/server.js';
+import { startServer } from '../src/core/server.js';
+
+startServer().catch((error) => {
+  console.error('Fatal error:', error);
+  console.error('Stack trace:', error?.stack);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "2.16.1",
+  "version": "2.25.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",
@@ -13,18 +13,24 @@
     "build:index": "node src/tools/buildCodeIndex.js",
     "test": "node --test tests/unit/**/*.test.js tests/integration/*.test.js",
     "test:unit": "NODE_ENV=test node --test tests/unit/**/*.test.js",
-    "test:integration": "NODE_ENV=test node --test tests/integration/*.test.js",
+    "test:integration": "NODE_ENV=test node scripts/run-non-unity-tests.mjs",
     "test:e2e": "NODE_ENV=test node --test tests/e2e/*.test.js",
     "test:coverage": "c8 --reporter=lcov --reporter=text --reporter=html node --test tests/unit/**/*.test.js tests/integration/*.test.js",
     "test:coverage:full": "c8 --reporter=lcov --reporter=text --reporter=html node --test tests/**/*.test.js",
     "test:watch": "node --watch --test tests/unit/**/*.test.js",
     "test:watch:all": "node --watch --test tests/**/*.test.js",
     "test:performance": "node --test tests/performance/*.test.js",
-    "test:ci": "c8 --reporter=lcov --check-coverage=false node --test tests/unit/core/config.test.js tests/unit/handlers/PingToolHandler.test.js tests/unit/handlers/CreateGameObjectToolHandler.test.js",
+    "test:ci": "CI=true NODE_ENV=test node --test tests/unit/core/codeIndex.test.js tests/unit/core/codeIndexDb.test.js tests/unit/core/config.test.js tests/unit/core/indexWatcher.test.js tests/unit/core/projectInfo.test.js tests/unit/core/server.test.js tests/unit/handlers/script/CodeIndexStatusToolHandler.test.js",
     "test:ci:all": "c8 --reporter=lcov node --test tests/unit/**/*.test.js",
+    "simulate:code-index": "node scripts/simulate-code-index-status.mjs",
     "test:verbose": "VERBOSE_TEST=true node --test tests/**/*.test.js",
+    "prepare": "cd .. && husky || true",
     "prepublishOnly": "npm run test:ci",
-    "postinstall": "chmod +x bin/unity-mcp-server || true"
+    "postinstall": "chmod +x bin/unity-mcp-server || true",
+    "test:ci:unity": "timeout 60 node --test tests/unit/core/codeIndex.test.js tests/unit/core/codeIndexDb.test.js tests/unit/core/config.test.js tests/unit/core/indexWatcher.test.js tests/unit/core/projectInfo.test.js tests/unit/core/server.test.js || exit 0",
+    "test:unity": "node tests/run-unity-integration.mjs",
+    "test:nounity": "npm run test:integration",
+    "test:ci:integration": "CI=true NODE_ENV=test node --test tests/integration/code-index-background.test.js"
   },
   "keywords": [
     "mcp",
@@ -68,7 +74,23 @@
     "access": "public"
   },
   "devDependencies": {
+    "@commitlint/cli": "^18.6.1",
+    "@commitlint/config-conventional": "^18.6.3",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/exec": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/release-notes-generator": "^12.1.0",
     "c8": "^10.1.3",
-    "nodemon": "^3.1.7"
+    "eslint": "^8.57.1",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-promise": "^6.6.0",
+    "husky": "^9.1.7",
+    "markdownlint-cli": "^0.43.0",
+    "nodemon": "^3.1.7",
+    "prettier": "^3.4.2",
+    "semantic-release": "^22.0.12"
   }
 }

package/src/core/config.js

@@ -93,8 +93,37 @@ const baseConfig = {
  * 1) UNITY_MCP_CONFIG (explicit file path)
  * 2) ./.unity/config.json (project-local)
  * 3) ~/.unity/config.json (user-global)
- * If none found, return {} and rely on env/defaults.
+ * If none found, create ./.unity/config.json with defaults.
  */
+function ensureDefaultProjectConfig(baseDir) {
+  const dir = path.resolve(baseDir, '.unity');
+  const file = path.join(dir, 'config.json');
+
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    if (!fs.existsSync(file)) {
+      const inferredRoot = fs.existsSync(path.join(baseDir, 'Assets')) ? baseDir : '';
+      const defaultConfig = {
+        unity: {
+          unityHost: 'localhost',
+          mcpHost: 'localhost',
+          port: 6400,
+        },
+        project: {
+          root: inferredRoot ? inferredRoot.replace(/\\/g, '/') : '',
+        },
+      };
+      fs.writeFileSync(file, `${JSON.stringify(defaultConfig, null, 2)}\n`, 'utf8');
+    }
+    return file;
+  } catch (error) {
+    return null;
+  }
+}
+
 function loadExternalConfig() {
   const explicitPath = process.env.UNITY_MCP_CONFIG;
 
@@ -119,6 +148,19 @@ function loadExternalConfig() {
       return { __configLoadError: `${p}: ${e.message}` };
     }
   }
+  const fallbackPath = ensureDefaultProjectConfig(process.cwd());
+  if (fallbackPath && fs.existsSync(fallbackPath)) {
+    try {
+      const raw = fs.readFileSync(fallbackPath, 'utf8');
+      const json = JSON.parse(raw);
+      const out = json && typeof json === 'object' ? json : {};
+      out.__configPath = fallbackPath;
+      out.__configGenerated = true;
+      return out;
+    } catch (e) {
+      return { __configLoadError: `${fallbackPath}: ${e.message}` };
+    }
+  }
   return {};
 }
 

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

@@ -20,8 +20,9 @@ export class ProjectInfoProvider {
   async get() {
     if (this.cached) return this.cached;
     // Config-driven project root (no env fallback)
-    const cfgRoot = config?.project?.root;
-    if (cfgRoot) {
+    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));
@@ -52,67 +53,13 @@ export class ProjectInfoProvider {
         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;
+    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 (no connection and no Assets/ found)');
+    throw new Error('Unable to resolve Unity project root. Configure project.root in .unity/config.json or provide UNITY_MCP_CONFIG.');
   }
 
   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;
   }
 }

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);