@akiojin/unity-mcp-server 2.46.0 → 3.0.0

package/README.md

@@ -1,78 +1,12 @@
-# Unity MCP Server
+# Unity MCP Server (npm package)
 
-MCP (Model Context Protocol) server for Unity Editor integration. Enables AI assistants like Claude and Cursor to interact directly with Unity Editor for automated game development.
+MCP (Model Context Protocol) server for Unity Editor integration.
+Enables AI assistants like Claude and Cursor to interact directly with Unity Editor for automated workflows.
 
-## Features
+This README documents the **npm package**.
+For the Unity package, OpenUPM setup, and the full repository documentation, see:
 
-- **106 comprehensive tools** across 16+ categories for Unity Editor automation
-- **Tool discovery** - Efficient `search_tools` meta-tool for discovering relevant tools (96.2% token reduction)
-- **GameObject management** - Create, find, modify, delete GameObjects with full hierarchy control
-- **Component system** - Add, remove, modify components with property control
-- **Scene management** - Create, load, save, list scenes with build settings integration
-- **Scene analysis** - Deep inspection, component analysis, and performance metrics
-- **Asset management** - Create and modify prefabs, materials, scripts with full control
-- **UI automation** - Find, click, and interact with UI elements programmatically
-- **Input simulation** - Simulate keyboard, mouse, gamepad, and touch input
-- **Play mode controls** - Start, pause, stop Unity play mode for testing
-- **Performance profiling** - Record profiling sessions, collect metrics, save .data files for analysis
-- **Project settings** - Read and update Unity project settings safely
-- **Editor operations** - Console logs, screenshots, video capture, compilation monitoring
-- **Editor control** - Manage tags, layers, selection, windows, and tools
-
-## Tool Discovery
-
-Unity MCP Server provides a **`search_tools`** meta-tool for efficient tool discovery, helping you find relevant tools quickly.
-
-### Usage Examples
-
-```javascript
-// Find tools for GameObject manipulation
-{
-  "tool": "search_tools",
-  "params": {
-    "query": "gameobject",
-    "limit": 10
-  }
-}
-// Returns: gameobject_create, gameobject_find, gameobject_modify, ...
-
-// Filter by category
-{
-  "tool": "search_tools",
-  "params": {
-    "category": "scene",
-    "limit": 10
-  }
-}
-// Returns: scene_create, scene_load, scene_save, scene_list, scene_info_get
-
-// Filter by tags
-{
-  "tool": "search_tools",
-  "params": {
-    "tags": ["create", "asset"],
-    "limit": 5
-  }
-}
-// Returns tools that create assets
-
-// Include full input schemas (when needed)
-{
-  "tool": "search_tools",
-  "params": {
-    "query": "screenshot",
-    "includeSchemas": true
-  }
-}
-// Returns full tool definitions with inputSchema
-```
-
-### Benefits
-
-- **Smart filtering** - Search by keywords, categories, tags, or scope (read/write/execute)
-- **Relevance scoring** - Results sorted by relevance to your query
-- **On-demand schemas** - Full inputSchema only when explicitly requested
-- **Easy discovery** - Find the right tool without browsing all 103 tools manually
+- [github.com/akiojin/unity-mcp-server](https://github.com/akiojin/unity-mcp-server)
 
 ## Quick Start
 
@@ -82,25 +16,19 @@ Unity MCP Server provides a **`search_tools`** meta-tool for efficient tool disc
 npx @akiojin/unity-mcp-server@latest
 ```
 
-### Global Installation
+### HTTP Mode (for HTTP-only networks)
 
 ```bash
-npm install -g @akiojin/unity-mcp-server
-unity-mcp-server
-```
-
-### Local Installation
-
-```bash
-npm install @akiojin/unity-mcp-server
-npx unity-mcp-server
+npx @akiojin/unity-mcp-server@latest --http 6401 --no-telemetry
+curl http://localhost:6401/healthz
 ```
 
 ## Unity Setup
 
-1. Install the Unity package from: `https://github.com/akiojin/unity-mcp-server.git?path=UnityMCPServer/Packages/unity-mcp-server`
+1. Install the Unity package from:
+   - [`https://github.com/akiojin/unity-mcp-server.git?path=UnityMCPServer/Packages/unity-mcp-server`](https://github.com/akiojin/unity-mcp-server.git?path=UnityMCPServer/Packages/unity-mcp-server)
 2. Open Unity Package Manager → Add package from git URL
-3. The package will automatically start a TCP server on port 6400
+3. The package starts a TCP server (default port `6400`)
 
 ## MCP Client Configuration
 
@@ -119,328 +47,35 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-### Alternative (if globally installed)
+## Tools & Discovery
+
+Unity MCP Server ships **100+ tools**.
+Use the `search_tools` meta-tool to find the right tool quickly.
 
 ```json
 {
-  "mcpServers": {
-    "unity-mcp-server": {
-      "command": "unity-mcp-server"
-    }
+  "tool": "search_tools",
+  "params": {
+    "query": "create gameobject",
+    "limit": 10
   }
 }
 ```
 
-## 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` — Keyboard input with batching, combos, typing, and auto-hold durations
-- `input_mouse` — Mouse movement, clicks, drags, per-button press/hold, and batching
-- `input_gamepad` — Gamepad buttons, sticks, triggers, d-pad with batching and timed holds
-- `input_touch` — Touch gestures (tap/swipe/pinch/multi) with batched steps
-
-#### 同時押下とホールドの扱い
-
-- **単一アクションで同時押下**: キーボードは `action:"combo"`、タッチは `action:"multi"`、ゲームパッドのスティックは `action:"stick"` で X/Y を同時指定できます。
-- **`actions[]` バッチ**: 異なるボタンやデバイスを同一フレームで実行したい場合は `actions:[{...},{...}]` に並べて送信します（順番を保持）。
-- **ホールド時間**: `holdSeconds` を press/button/trigger などに付与すると、その秒数後に自動で release/state reset がスケジュールされます。省略すると押下状態が維持されるので、手動で release アクションを送ってください。
-- `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 Unity Test Runner progress/results. Parameters:
-  - `includeTestResults` (bool, default `false`): attaches the latest exported `.unity/test-results/*.json` summary to the response when a test run has completed.
-  - `includeFileContent` (bool, default `false`): when combined with `includeTestResults`, also returns the JSON file contents as a string so agents can parse the detailed per-test data without reading the file directly.
-
-## Architecture
-
-### Dependencies
-
-Unity MCP Server uses the following components for code indexing and analysis:
-
-| Component | Purpose | Distribution | Notes |
-|-----------|---------|--------------|-------|
-| **fast-sql** | Code index database | npm dependency | Hybrid backend: better-sqlite3 (native) or sql.js (WASM) |
-| **csharp-lsp** | C# symbol analysis | Downloaded on first use | ~80 MB per platform |
-
-#### Why fast-sql?
-
-We use **fast-sql** (hybrid SQLite library) for the code index database:
-
-- **Optimal performance**: Uses better-sqlite3 (native) when available for ~34x faster queries
-- **npx compatible**: Falls back to sql.js (WASM) when native bindings unavailable
-- **Zero native compilation required**: Works immediately via `npx` without build tools
-- **Cross-platform**: Automatic backend selection based on environment
-
-**Performance comparison** (better-sqlite3 vs sql.js):
-- 50K inserts: 29ms vs 53ms (1.8x faster)
-- 1000 queries: 0.34μs vs 11.78μs (34x faster)
-- LIKE search: 2.5ms vs 7ms (2.8x faster)
-
-#### csharp-lsp Distribution
-
-**csharp-lsp (downloaded on first use)**:
-
-- Large size (~80 MB per platform, ~480 MB for all 6 platforms)
-- Too large to bundle in npm package
-- Downloaded from GitHub Release on first use of script editing tools
-
-#### Supported Platforms
-
-| Platform | fast-sql | csharp-lsp |
-|----------|----------|------------|
-| Linux x64 | ✅ Native (better-sqlite3) | ✅ Downloaded (~79 MB) |
-| Linux arm64 | ✅ Native (better-sqlite3) | ✅ Downloaded (~86 MB) |
-| macOS x64 | ✅ Native (better-sqlite3) | ✅ Downloaded (~80 MB) |
-| macOS arm64 (Apple Silicon) | ✅ Native (better-sqlite3) | ✅ Downloaded (~86 MB) |
-| Windows x64 | ✅ Native (better-sqlite3) | ✅ Downloaded (~80 MB) |
-| Windows arm64 | ✅ WASM fallback (sql.js) | ✅ Downloaded (~85 MB) |
-
-#### Storage Locations
-
-- **csharp-lsp**: `~/.unity/tools/csharp-lsp/<rid>/`
-- **Code index database**: `<workspace>/.unity/cache/code-index/code-index.db`
+More details:
+- Tools & Code Index workflow: [`docs/tools.md`](https://github.com/akiojin/unity-mcp-server/blob/main/docs/tools.md)
+- Configuration reference: [`docs/configuration.md`](https://github.com/akiojin/unity-mcp-server/blob/main/docs/configuration.md)
 
 ## Requirements
 
-- **Unity**: 2020.3 LTS or newer (Unity 6 supported)
-- **Node.js**: 18.0.0 or newer
-- **MCP Client**: Claude Desktop, Cursor, or compatible client
-
-## Performance Benchmark
-
-Response time comparison between Code Index tools and standard Claude Code tools (with DB index built, `watch: true` enabled):
-
-| Operation | unity-mcp-server | Time | Standard Tool | Time | Result |
-|-----------|------------------|------|---------------|------|--------|
-| File Read | `script_read` | **instant** | `Read` | **instant** | EQUAL |
-| Symbol List | `script_symbols_get` | **instant** | N/A | N/A | PASS |
-| Symbol Find | `script_symbol_find` | **instant** | `Grep` | **instant** | EQUAL |
-| Text Search | `script_search` | **instant** | `Grep` | **instant** | EQUAL |
-| Reference Find | `script_refs_find` | **instant** | `Grep` | **instant** | EQUAL |
-| Index Status | `code_index_status` | **instant** | N/A | N/A | PASS |
-
-**Note**: Performance above requires DB index to be built. Run `code_index_build` before first use.
-
-### Worker Thread Implementation
-
-Since v2.41.x, background index builds run in Worker Threads, so MCP tools are never blocked even with `watch: true`:
-
-| Scenario | Before Worker Thread | After Worker Thread |
-|----------|---------------------|---------------------|
-| `system_ping` | **60+ seconds block** | **instant** |
-| `code_index_status` | **60+ seconds block** | **instant** |
-| Any MCP tool | timeout during build | **instant** |
-
-See [`docs/benchmark.md`](../docs/benchmark.md) for detailed benchmark results.
+- Unity 2020.3 LTS or newer
+- Node.js 18.x / 20.x / 22.x LTS (23+ not supported)
+- MCP client (Claude Desktop, Cursor, etc.)
 
 ## Troubleshooting
 
-### Connection Issues
-
-1. Ensure Unity Editor is running with the Unity package installed
-2. Check Unity console for connection messages
-3. Verify port 6400 is not blocked by firewall
-
-### Installation Issues
-
-```bash
-# Clear npm cache
-npm cache clean --force
-
-# Reinstall
-npm uninstall -g @akiojin/unity-mcp-server
-npm install -g @akiojin/unity-mcp-server
-```
-
-### MCP Client Shows "Capabilities: none"
-
-If your MCP client (Claude Code, Cursor, etc.) shows "Capabilities: none" despite successful connection:
-
-**Symptom**: Server connects successfully, but no tools are visible to the client.
-
-**Root Cause**: Empty capability objects (`resources: {}`, `prompts: {}`) in MCP SDK v0.6.1 cause capability validation to fail silently.
-
-**Solution**: Update to latest version with the fix:
-
-```bash
-# Update to latest version (2.41.0+)
-npm update -g @akiojin/unity-mcp-server
-
-# Or reinstall
-npm uninstall -g @akiojin/unity-mcp-server
-npm install -g @akiojin/unity-mcp-server
-```
-
-**Verification**: After restart, your MCP client should display 107 available tools.
-
-## Repository
-
-Full source code and documentation: <https://github.com/akiojin/unity-mcp-server>
-
-## Release Automation
-
-- Releases are generated by release-please on `main`.
-  - If changes are in develop, run `scripts/prepare-release-pr.sh` (creates/auto-merges develop→main PR).
-  - release-please runs on main and publishes via tags; no automatic back-merge to develop.
-- Required checks: Markdown, ESLint & Formatting / Commit Message Lint / Test & Coverage / Package.
-- Tags trigger `publish.yml` to push npm, OpenUPM (via tag), and csharp-lsp artifacts; Unity package version is kept in sync via release-please extra-files.
-- If OpenUPM lags, create a new release so the tag and Unity package version match.
+- Troubleshooting index: [`docs/troubleshooting/README.md`](https://github.com/akiojin/unity-mcp-server/blob/main/docs/troubleshooting/README.md)
+- “Capabilities: none” fix: [`docs/troubleshooting/capabilities-none.md`](https://github.com/akiojin/unity-mcp-server/blob/main/docs/troubleshooting/capabilities-none.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "2.46.0",
+  "version": "3.0.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/config.js

@@ -1,4 +1,5 @@
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import * as findUpPkg from 'find-up';
 import { MCPLogger } from './mcpLogger.js';
@@ -67,20 +68,13 @@ function resolvePackageVersion() {
 /**
  * Base configuration for Unity MCP Server Server
  */
-const envUnityHost = process.env.UNITY_BIND_HOST || process.env.UNITY_HOST || null;
-
-const envMcpHost =
-  process.env.UNITY_MCP_HOST || process.env.UNITY_CLIENT_HOST || process.env.UNITY_HOST || null;
-
-const envBindHost = process.env.UNITY_BIND_HOST || null;
-
 const baseConfig = {
   // Unity connection settings
   unity: {
-    unityHost: envUnityHost,
-    mcpHost: envMcpHost,
-    bindHost: envBindHost,
-    port: parseInt(process.env.UNITY_PORT || '', 10) || 6400,
+    unityHost: null,
+    mcpHost: null,
+    bindHost: null,
+    port: 6400,
     reconnectDelay: 1000,
     maxReconnectDelay: 30000,
     reconnectBackoffMultiplier: 2,
@@ -96,24 +90,21 @@ const baseConfig = {
 
   // Logging settings
   logging: {
-    level: process.env.LOG_LEVEL || 'info',
+    level: 'info',
     prefix: '[unity-mcp-server]'
   },
 
   // HTTP transport (off by default)
   http: {
-    enabled: (process.env.UNITY_MCP_HTTP_ENABLED || 'false').toLowerCase() === 'true',
-    host: process.env.UNITY_MCP_HTTP_HOST || '0.0.0.0',
-    port: parseInt(process.env.UNITY_MCP_HTTP_PORT || '', 10) || 6401,
+    enabled: false,
+    host: '0.0.0.0',
+    port: 6401,
     healthPath: '/healthz',
-    allowedHosts: (process.env.UNITY_MCP_HTTP_ALLOWED_HOSTS || 'localhost,127.0.0.1')
-      .split(',')
-      .map(h => h.trim())
-      .filter(h => h.length > 0)
+    allowedHosts: ['localhost', '127.0.0.1']
   },
 
   telemetry: {
-    enabled: (process.env.UNITY_MCP_TELEMETRY || 'off').toLowerCase() === 'on',
+    enabled: false,
     destinations: [],
     fields: []
   },
@@ -123,13 +114,13 @@ const baseConfig = {
   // Search-related defaults and engine selection
   search: {
     // detail alias: 'compact' maps to returnMode 'snippets'
-    defaultDetail: (process.env.SEARCH_DEFAULT_DETAIL || 'compact').toLowerCase(), // compact|metadata|snippets|full
-    engine: (process.env.SEARCH_ENGINE || 'naive').toLowerCase() // naive|treesitter (future)
+    defaultDetail: 'compact', // compact|metadata|snippets|full
+    engine: 'naive' // naive|treesitter (future)
   },
 
   // LSP client defaults
   lsp: {
-    requestTimeoutMs: Number(process.env.LSP_REQUEST_TIMEOUT_MS || 60000)
+    requestTimeoutMs: 60000
   },
 
   // Indexing (code index) settings
@@ -137,95 +128,48 @@ const baseConfig = {
     // Enable periodic incremental index updates (polling watcher)
     watch: true,
     // Polling interval (ms)
-    intervalMs: Number(process.env.INDEX_WATCH_INTERVAL_MS || 15000),
+    intervalMs: 15000,
     // Build options
-    concurrency: Number(process.env.INDEX_CONCURRENCY || 8),
-    retry: Number(process.env.INDEX_RETRY || 2),
-    reportEvery: Number(process.env.INDEX_REPORT_EVERY || 500)
+    concurrency: 8,
+    retry: 2,
+    reportEvery: 500
   }
 };
 
 /**
- * External config resolution (no legacy compatibility):
- * Priority:
- * 1) UNITY_MCP_CONFIG (explicit file path)
- * 2) ./.unity/config.json (project-local)
- * 3) ~/.unity/config.json (user-global)
- * If none found, create ./.unity/config.json with defaults.
+ * External config resolution:
+ * - Uses the nearest `.unity/config.json` found by walking up from the current working directory.
+ * - Intentionally ignores `~/.unity/config.json` (user-global).
  */
-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() {
   if (typeof findUpSyncCompat !== 'function') {
     return {};
   }
-  const explicitPath = process.env.UNITY_MCP_CONFIG;
+  let userGlobalPath = null;
+  try {
+    const homeDir = os.homedir();
+    userGlobalPath = homeDir ? path.resolve(homeDir, '.unity', 'config.json') : null;
+  } catch {}
 
   const projectPath = findUpSyncCompat(
     directory => {
       const candidate = path.resolve(directory, '.unity', 'config.json');
+      if (userGlobalPath && path.resolve(candidate) === userGlobalPath) return undefined;
       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;
 
-  const candidates = [explicitPath, projectPath, userPath].filter(Boolean);
-  for (const p of candidates) {
-    try {
-      if (p && fs.existsSync(p)) {
-        const raw = fs.readFileSync(p, 'utf8');
-        const json = JSON.parse(raw);
-        const out = json && typeof json === 'object' ? json : {};
-        out.__configPath = p;
-        return out;
-      }
-    } catch (e) {
-      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}` };
-    }
+  if (!projectPath) return {};
+  try {
+    const raw = fs.readFileSync(projectPath, 'utf8');
+    const json = JSON.parse(raw);
+    const out = json && typeof json === 'object' ? json : {};
+    out.__configPath = projectPath;
+    return out;
+  } catch (e) {
+    return { __configLoadError: `${projectPath}: ${e.message}` };
   }
-  return {};
 }
 
 const external = loadExternalConfig();
@@ -234,22 +178,22 @@ export const config = merge(baseConfig, external);
 const normalizeUnityConfig = () => {
   const unityConfig = config.unity || (config.unity = {});
 
-  // Legacy aliases coming from config files or env vars
+  // Legacy aliases coming from config files
   const legacyHost = unityConfig.host;
   const legacyClientHost = unityConfig.clientHost;
   const legacyBindHost = unityConfig.bindHost;
 
   if (!unityConfig.unityHost) {
-    unityConfig.unityHost = legacyBindHost || legacyHost || envUnityHost || 'localhost';
+    unityConfig.unityHost = legacyBindHost || legacyHost || 'localhost';
   }
 
   if (!unityConfig.mcpHost) {
-    unityConfig.mcpHost = legacyClientHost || envMcpHost || legacyHost || unityConfig.unityHost;
+    unityConfig.mcpHost = legacyClientHost || legacyHost || unityConfig.unityHost;
   }
 
   // Keep bindHost for backwards compatibility with legacy code paths
   if (!unityConfig.bindHost) {
-    unityConfig.bindHost = legacyBindHost || envBindHost || unityConfig.unityHost;
+    unityConfig.bindHost = legacyBindHost || unityConfig.unityHost;
   }
 
   // Maintain legacy properties so older handlers keep working
@@ -291,7 +235,7 @@ if (config.__configLoadError) {
 // Startup debug log: output config info to stderr for troubleshooting
 // This helps diagnose connection issues (especially in WSL2/Docker environments)
 console.error(`[unity-mcp-server] Startup config:`);
-console.error(`[unity-mcp-server]   Config file: ${config.__configPath || '(defaults)'}`);
+console.error(`[unity-mcp-server]   Config file: ${config.__configPath || '(not found)'}`);
 console.error(
   `[unity-mcp-server]   Unity host: ${config.unity.mcpHost || config.unity.unityHost || 'localhost'}`
 );

package/src/core/projectInfo.js

@@ -1,8 +1,36 @@
+import fs from 'fs';
 import path from 'path';
 import { logger, config, WORKSPACE_ROOT } from './config.js';
 
 const normalize = p => p.replace(/\\/g, '/');
 
+const looksLikeUnityProjectRoot = dir => {
+  try {
+    return (
+      fs.existsSync(path.join(dir, 'Assets')) &&
+      fs.existsSync(path.join(dir, 'Packages')) &&
+      fs.statSync(path.join(dir, 'Assets')).isDirectory() &&
+      fs.statSync(path.join(dir, 'Packages')).isDirectory()
+    );
+  } catch {
+    return false;
+  }
+};
+
+const inferUnityProjectRootFromDir = startDir => {
+  try {
+    let dir = startDir;
+    const { root } = path.parse(dir);
+    while (true) {
+      if (looksLikeUnityProjectRoot(dir)) return dir;
+      if (dir === root) return null;
+      dir = path.dirname(dir);
+    }
+  } catch {
+    return null;
+  }
+};
+
 const resolveDefaultCodeIndexRoot = projectRoot => {
   const base = WORKSPACE_ROOT || projectRoot || process.cwd();
   return normalize(path.join(base, '.unity', 'cache', 'code-index'));
@@ -18,21 +46,6 @@ 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')),
-        codeIndexRoot
-      };
-      return this.cached;
-    }
-
     // Config-driven project root (no env fallback)
     const cfgRootRaw = config?.project?.root;
     if (typeof cfgRootRaw === 'string' && cfgRootRaw.trim().length > 0) {
@@ -73,13 +86,28 @@ export class ProjectInfoProvider {
         logger.warning(`get_editor_info failed: ${e.message}`);
       }
     }
+
+    // Best-effort local inference (when Unity isn't connected)
+    const inferredRoot = inferUnityProjectRootFromDir(process.cwd());
+    if (inferredRoot) {
+      const projectRoot = normalize(inferredRoot);
+      const codeIndexRoot = normalize(resolveDefaultCodeIndexRoot(projectRoot));
+      this.cached = {
+        projectRoot,
+        assetsPath: normalize(path.join(projectRoot, 'Assets')),
+        packagesPath: normalize(path.join(projectRoot, 'Packages')),
+        codeIndexRoot
+      };
+      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.'
+        'project.root is configured but empty. Set a valid path in .unity/config.json.'
       );
     }
     throw new Error(
-      'Unable to resolve Unity project root. Configure project.root in .unity/config.json or provide UNITY_MCP_CONFIG.'
+      'Unable to resolve Unity project root. Start the server inside a Unity project (directory containing Assets/ and Packages/) or configure project.root in .unity/config.json.'
     );
   }