@akiojin/unity-mcp-server 2.16.0 → 2.25.0

package/README.md

@@ -74,105 +74,158 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-## Available Tools (70 Tools)
-
-### System & Core Tools (2 tools)
-- `ping` - Test connection to Unity Editor and verify server status
-- `refresh_assets` - Refresh Unity assets and trigger recompilation
-
-### GameObject Management (5 tools)
-- `create_gameobject` - Create GameObjects with primitives, transforms, tags, and layers
-- `find_gameobject` - Find GameObjects by name, tag, layer with pattern matching
-- `modify_gameobject` - Modify GameObject properties (transform, name, active state, parent)
-- `delete_gameobject` - Delete single or multiple GameObjects with child handling
-- `get_hierarchy` - Get scene hierarchy with components and depth control
-
-### Component System (5 tools)
-- `add_component` - Add Unity components to GameObjects with initial properties
-- `remove_component` - Remove components from GameObjects with safety checks
-- `modify_component` - Modify component properties with nested property support
-- `list_components` - List all components on a GameObject with type information
-- `get_component_types` - Discover available component types with filtering
-
-### Scene Management (5 tools)
-- `create_scene` - Create new scenes with build settings integration
-- `load_scene` - Load scenes in Single or Additive mode
-- `save_scene` - Save current scene with Save As functionality
-- `list_scenes` - List all scenes in project with filtering options
-- `get_scene_info` - Get detailed scene information including GameObject counts
-
-### Scene Analysis (7 tools)
-- `get_gameobject_details` - Deep inspection of GameObjects with component details
-- `analyze_scene_contents` - Comprehensive scene statistics and performance metrics
-- `get_component_values` - Get all properties and values of specific components
-- `find_by_component` - Find GameObjects by component type with scope filtering
-- `get_object_references` - Analyze references between objects and assets
-- `get_animator_state` - Get current Animator state, parameters, and transitions
-- `get_animator_runtime_info` - Get runtime Animator info (Play mode only)
-
-### Asset Management (11 tools)
-- `create_prefab` - Create prefabs from GameObjects or templates
-- `modify_prefab` - Modify existing prefabs with property changes
-- `instantiate_prefab` - Instantiate prefabs in scenes with transform options
-- `open_prefab` - Open prefabs in Unity's prefab mode for editing
-- `exit_prefab_mode` - Exit prefab mode with save/discard options
-- `save_prefab` - Save prefab changes or apply instance overrides
-- `create_material` - Create new materials with shader and properties
-- `modify_material` - Modify material properties and shaders
-- `manage_asset_import_settings` - Manage asset import settings and presets
-- `manage_asset_database` - Asset database operations (find, move, copy, delete)
-- `analyze_asset_dependencies` - Analyze asset dependencies and find unused assets
-
-### Script Management (6 tools)
-- `create_script` - Create new C# scripts with templates (MonoBehaviour, ScriptableObject, etc.)
-- `read_script` - Read script file contents with syntax highlighting
-- `update_script` - Modify existing scripts with validation
-- `delete_script` - Delete script files with dependency checking
-- `list_scripts` - List all scripts in project with filtering and metadata
-- `validate_script` - Validate script syntax and Unity compatibility
-
-### Play Mode Controls (4 tools)
-- `play_game` - Start Unity play mode for testing
-- `pause_game` - Pause or resume Unity play mode
-- `stop_game` - Stop Unity play mode and return to edit mode
-- `get_editor_state` - Get current editor state and compilation status
-
-### UI Automation (5 tools)
-- `find_ui_elements` - Locate UI elements by type, tag, or name
-- `click_ui_element` - Simulate clicking on UI elements (buttons, toggles)
-- `get_ui_element_state` - Get UI element properties and interaction state
-- `set_ui_element_value` - Set values for input fields, sliders, dropdowns
-- `simulate_ui_input` - Execute complex UI interaction sequences
-
-### Input System Simulation (5 tools)
-- `simulate_keyboard` - Simulate keyboard input with key combos and text typing
-- `simulate_mouse` - Simulate mouse movement, clicks, drags, and scrolling
-- `simulate_gamepad` - Simulate gamepad buttons, sticks, triggers, and d-pad
-- `simulate_touch` - Simulate touch gestures (tap, swipe, pinch, multi-touch)
-- `get_current_input_state` - Get current state of all input devices
-
-### Editor Operations (5 tools)
-- `execute_menu_item` - Execute Unity menu items programmatically
-- `clear_console` - Clear Unity console logs with filtering options
-- `read_console` - Read console logs with advanced filtering and search
-- `capture_screenshot` - Take screenshots of Game View or Scene View
-- `analyze_screenshot` - Analyze screenshot content with image analysis
-
-### Editor Control & Automation (6 tools)
-- `manage_tags` - Manage Unity project tags (add, remove, list)
-- `manage_layers` - Manage Unity project layers with index conversion
-- `manage_selection` - Manage Editor selection (get, set, clear)
-- `manage_windows` - Manage Editor windows (list, focus, get state)
-- `manage_tools` - Manage Editor tools and plugins
-- `get_compilation_state` - Get current compilation state and errors
-
-### Project Settings Management (2 tools)
-- `get_project_settings` - Read Unity project settings with granular control
-  - Player, Graphics, Quality, Physics, Audio, Time settings
-  - Build settings, Tags and layers configuration
-- `update_project_settings` - Safely update project settings
-  - Requires explicit confirmation for safety
-  - Supports partial updates to specific categories
+## Code Index Workflow
+
+コードの自動編集を安定させるには、以下の 3 ステップでコードインデックスを運用してください。重いフルテストを回す必要はありません。
+
+1. **初回または大幅変更後に `code_index_build`**  
+   プロジェクト内の `Assets/` と `Packages/` の C# をすべてスキャンし、`.unity/cache/code-index/code-index.db` にシンボルを格納します。
+2. **ファイル更新後は `code_index_update`**  
+   編集したファイルだけを配列で渡すと、LSP から最新シンボルを再取得してインデックスを差分更新します。長時間待ちになる `code_index_build` の再実行を避けられます。
+3. **シンボル取得時は `script_symbol_find`**  
+   インデックスが利用可能なら高速に、未構築でも LSP にフォールバックして定義位置を取得できます。`script_edit_*` ツールに渡す `symbolName` 構築に活用してください。
+
+> **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
+- `system_ping` — Test connection to Unity Editor and verify server status
+- `system_refresh_assets` — Refresh Unity assets and trigger recompilation
+- `system_get_command_stats` — Retrieve recent MCP command usage metrics
+
+### GameObject Management
+- `gameobject_create` — Create GameObjects with primitives, transforms, tags, and layers
+- `gameobject_find` — Find GameObjects by name, tag, or layer with pattern matching
+- `gameobject_modify` — Modify GameObject properties (transform, name, active state, parent)
+- `gameobject_delete` — Delete single or multiple GameObjects with child handling
+- `gameobject_get_hierarchy` — Inspect scene hierarchy with component details
+
+### Component System
+- `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
+
+### Scene Management
+- `scene_create` — Create new scenes with build-settings integration
+- `scene_load` — Load scenes in Single or Additive mode
+- `scene_save` — Save the active scene (supports Save As)
+- `scene_list` — List scenes in the project with filtering options
+- `scene_info_get` — Retrieve detailed scene information including GameObject counts
+
+### Analysis & Diagnostics
+- `analysis_scene_contents_analyze` — Gather scene statistics and performance metrics
+- `analysis_component_find` — Locate GameObjects by component type with scope filtering
+- `analysis_component_values_get` — Inspect component properties and values
+- `analysis_gameobject_details_get` — Deep inspection of GameObjects and components
+- `analysis_object_references_get` — Trace references between objects and assets
+- `analysis_animator_state_get` — Inspect Animator layers, parameters, and transitions
+- `analysis_animator_runtime_info_get` — Retrieve runtime Animator diagnostics (Play Mode)
+
+### Asset Management
+- `asset_prefab_create` — Create prefabs from GameObjects or blank templates
+- `asset_prefab_instantiate` — Instantiate prefabs with custom transforms
+- `asset_prefab_modify` — Apply property overrides to existing prefabs
+- `asset_prefab_open` — Open prefabs in Prefab Mode for editing
+- `asset_prefab_exit_mode` — Exit Prefab Mode with save/discard handling
+- `asset_prefab_save` — Save prefab changes or apply instance overrides
+- `asset_material_create` — Create materials with shader and property setup
+- `asset_material_modify` — Update material properties and shaders
+- `asset_import_settings_manage` — Inspect or modify asset-import settings and presets
+- `asset_database_manage` — Perform asset database operations (find, move, copy, delete)
+- `asset_dependency_analyze` — Audit asset dependencies and identify unused assets
+
+### Script & Code Tools
+- `script_read` — Read script file contents with syntax-aware formatting
+- `script_search` — Search C# sources by substring/regex/glob filters
+- `script_symbols_get` — Enumerate symbols within a specific C# file
+- `script_symbol_find` — Locate symbol definitions across the project
+- `script_refs_find` — List references/usages for a symbol via C# LSP
+- `script_edit_snippet` — Apply small text edits within C# files
+- `script_edit_structured` — Perform structured symbol edits via C# LSP extensions
+- `script_create_class` — Generate a new C# class file from parameters
+- `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
+- `code_index_status` — Report status of the persistent code index
+
+### Code Index Utilities
+- `code_index_build` — フルスキャンでシンボルインデックスを再構築（開発時は `delayStartMs` や `throttleMs` で進捗観測用に速度調整可能）
+- `code_index_update` — 変更した C# ファイルのみ差分再インデックス
+
+### Play Mode Controls
+- `playmode_play` — Enter Play Mode
+- `playmode_pause` — Pause or resume Play Mode
+- `playmode_stop` — Exit Play Mode back to Edit Mode
+- `playmode_get_state` — Inspect current play/edit/compilation state
+- `playmode_wait_for_state` — Await a target play/edit state
+
+### UI Automation
+- `ui_find_elements` — Locate UI elements by type, tag, or name
+- `ui_click_element` — Simulate clicking UI buttons, toggles, etc.
+- `ui_get_element_state` — Inspect UI element properties and interactability
+- `ui_set_element_value` — Modify UI input values (sliders, fields, dropdowns)
+- `ui_simulate_input` — Execute complex multi-step UI interaction sequences
+
+### Input System Utilities
+- `input_system_control` — Dispatch keyboard/mouse/gamepad/touch operations
+- `input_keyboard_simulate` — Simulate keyboard input with combos or text
+- `input_mouse_simulate` — Simulate mouse movement, clicks, drags, and scrolling
+- `input_gamepad_simulate` — Simulate gamepad buttons, sticks, and triggers
+- `input_touch_simulate` — Simulate touch gestures (tap, swipe, pinch)
+- `input_action_add` — Add actions to an Input Action map
+- `input_action_remove` — Remove actions from an Input Action map
+- `input_action_map_create` — Create new Input Action maps
+- `input_action_map_remove` — Delete existing Input Action maps
+- `input_binding_add` — Add bindings to an action (including composites)
+- `input_binding_remove` — Remove a specific binding from an action
+- `input_binding_remove_all` — Clear all bindings from an action
+- `input_binding_composite_create` — Create composite bindings (e.g., 2D vectors)
+- `input_control_schemes_manage` — Manage control schemes and device lists
+- `input_actions_state_get` — Inspect current Input Actions asset configuration
+- `input_actions_asset_analyze` — Produce structured summaries of Input Actions assets
+
+### Editor & Console Utilities
+- `menu_item_execute` — Trigger Unity Editor menu items programmatically
+- `console_clear` — Clear Unity console logs with filtering options
+- `console_read` — Stream Unity console output with advanced filters
+- `editor_tags_manage` — Manage project tags (add/remove/list)
+- `editor_layers_manage` — Manage project layers with index conversion
+- `editor_selection_manage` — Inspect or mutate the current editor selection
+- `editor_windows_manage` — Enumerate or focus Unity editor windows
+- `editor_tools_manage` — Manage editor tools and plugins
+- `compilation_get_state` — Inspect current compilation state and errors
+
+### Project Settings & Packages
+- `settings_get` — Read Unity project settings with granular control
+- `settings_update` — Safely update project settings (requires confirmation)
+- `package_manage` — List or manage Unity packages via Package Manager
+- `package_registry_config` — Configure package registries/scopes
+
+### Asset Visualization & Capture
+- `screenshot_capture` — Capture Game/Scene view screenshots
+- `screenshot_analyze` — Run image analysis on captured screenshots
+- `video_capture_start` — Begin recording the Game view to video
+- `video_capture_stop` — Stop the current video recording
+- `video_capture_status` — Inspect capture status / metadata
+- `video_capture_for` — Record for a fixed duration before auto-stop
+
+### Testing & Diagnostics
+- `test_run` — Run Unity tests (EditMode/PlayMode)
+- `test_get_status` — Query test runner progress/results
 
 ## Requirements
 
@@ -199,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.0",
+  "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",
@@ -42,10 +48,11 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^0.6.1",
-    "better-sqlite3": "^9.4.3"
+    "better-sqlite3": "^9.4.3",
+    "find-up": "^6.3.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18 <21"
   },
   "repository": {
     "type": "git",
@@ -67,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

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { findUpSync } from 'find-up';
 
 /**
  * Shallow merge utility (simple objects only)
@@ -92,25 +93,44 @@ 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 loadExternalConfig() {
-  const explicitPath = process.env.UNITY_MCP_CONFIG;
+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 });
+    }
 
-  // Find nearest <workspace>/.unity/config.json by walking up from process.cwd()
-  const findProjectConfigUp = () => {
-    let dir = process.cwd();
-    let prev = '';
-    for (let i = 0; i < 3 && dir && dir !== prev; i++) {
-      const p = path.resolve(dir, '.unity', 'config.json');
-      if (fs.existsSync(p)) return p;
-      prev = dir;
-      dir = path.dirname(dir);
+    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;
-  };
+  }
+}
 
-  const projectPath = findProjectConfigUp();
+function loadExternalConfig() {
+  const explicitPath = process.env.UNITY_MCP_CONFIG;
+
+  const projectPath = findUpSync((directory) => {
+    const candidate = path.resolve(directory, '.unity', 'config.json');
+    return fs.existsSync(candidate) ? candidate : undefined;
+  }, { cwd: process.cwd() });
   const homeDir = process.env.HOME || process.env.USERPROFILE || '';
   const userPath = homeDir ? path.resolve(homeDir, '.unity', 'config.json') : null;
 
@@ -128,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,25 +34,88 @@ export class IndexWatcher {
     if (this.running) return;
     this.running = true;
     try {
-      const { BuildCodeIndexToolHandler } = await import('../handlers/script/BuildCodeIndexToolHandler.js');
-      const handler = new BuildCodeIndexToolHandler(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}`);
+      // 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);
+
+      // 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();
+    }
+  }
+}