@akiojin/unity-mcp-server 5.3.2 → 5.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "5.3.2",
+  "version": "5.5.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",
@@ -28,7 +28,7 @@
     "lru-cache": "^11.0.2"
   },
   "engines": {
-    "node": ">=18 <23"
+    "node": ">=18 <25"
   },
   "repository": {
     "type": "git",

package/scripts/ensure-better-sqlite3.mjs

@@ -7,7 +7,8 @@ import { createRequire } from 'node:module';
 const ABI_BY_NODE_MAJOR = new Map([
   [18, 115],
   [20, 120],
-  [22, 131]
+  [22, 131],
+  [24, 137]
 ]);
 
 export function parseEnvFlag(value) {

package/src/core/config.js

@@ -52,6 +52,15 @@ function parseIntEnv(value) {
   return Number.isFinite(n) ? n : undefined;
 }
 
+function parseCsvEnv(value) {
+  if (typeof value !== 'string') return undefined;
+  const items = value
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+  return items;
+}
+
 function envString(key) {
   const raw = process.env[key];
   if (typeof raw !== 'string') return undefined;
@@ -105,7 +114,8 @@ const baseConfig = {
   // Project settings (primarily for code index paths)
   project: {
     root: null,
-    codeIndexRoot: null
+    codeIndexRoot: null,
+    requireClientRoot: false
   },
 
   // Server settings
@@ -142,6 +152,12 @@ const baseConfig = {
     fields: []
   },
 
+  // Tool visibility filter
+  tools: {
+    includeCategories: [],
+    excludeCategories: []
+  },
+
   // Write queue removed: all edits go through structured Roslyn tools.
 
   // Search-related defaults and engine selection
@@ -154,7 +170,8 @@ const baseConfig = {
   // LSP client defaults
   lsp: {
     requestTimeoutMs: 120000,
-    slowRequestWarnMs: 2000
+    slowRequestWarnMs: 2000,
+    validationTimeoutMs: 5000
   },
 
   // Indexing (code index) settings
@@ -176,6 +193,7 @@ function loadEnvConfig() {
   const unityPort = parseIntEnv(process.env.UNITY_MCP_PORT);
 
   const projectRoot = envString('UNITY_PROJECT_ROOT');
+  const requireProjectRoot = parseBoolEnv(process.env.UNITY_MCP_REQUIRE_PROJECT_ROOT);
 
   const logLevel = envString('UNITY_MCP_LOG_LEVEL');
   const versionMismatch = envString('UNITY_MCP_VERSION_MISMATCH');
@@ -186,6 +204,9 @@ function loadEnvConfig() {
   const telemetryEnabled = parseBoolEnv(process.env.UNITY_MCP_TELEMETRY_ENABLED);
   const lspRequestTimeoutMs = parseIntEnv(process.env.UNITY_MCP_LSP_REQUEST_TIMEOUT_MS);
   const lspSlowRequestWarnMs = parseIntEnv(process.env.UNITY_MCP_LSP_SLOW_REQUEST_WARN_MS);
+  const lspValidationTimeoutMs = parseIntEnv(process.env.UNITY_MCP_LSP_VALIDATION_TIMEOUT_MS);
+  const includeCategories = parseCsvEnv(process.env.UNITY_MCP_TOOL_INCLUDE_CATEGORIES);
+  const excludeCategories = parseCsvEnv(process.env.UNITY_MCP_TOOL_EXCLUDE_CATEGORIES);
 
   const out = {};
 
@@ -201,6 +222,9 @@ function loadEnvConfig() {
     out.project = {};
     if (projectRoot) out.project.root = projectRoot;
   }
+  if (requireProjectRoot !== undefined) {
+    out.project = { ...(out.project || {}), requireClientRoot: requireProjectRoot };
+  }
 
   if (logLevel) {
     out.logging = { level: logLevel };
@@ -220,12 +244,21 @@ function loadEnvConfig() {
     out.telemetry = { enabled: telemetryEnabled };
   }
 
+  if (includeCategories !== undefined || excludeCategories !== undefined) {
+    out.tools = {};
+    if (includeCategories !== undefined) out.tools.includeCategories = includeCategories;
+    if (excludeCategories !== undefined) out.tools.excludeCategories = excludeCategories;
+  }
+
   if (lspRequestTimeoutMs !== undefined) {
     out.lsp = { requestTimeoutMs: lspRequestTimeoutMs };
   }
   if (lspSlowRequestWarnMs !== undefined) {
     out.lsp = { ...(out.lsp || {}), slowRequestWarnMs: lspSlowRequestWarnMs };
   }
+  if (lspValidationTimeoutMs !== undefined) {
+    out.lsp = { ...(out.lsp || {}), validationTimeoutMs: lspValidationTimeoutMs };
+  }
 
   return out;
 }
@@ -296,6 +329,25 @@ function validateAndNormalizeConfig(cfg) {
     cfg.project.codeIndexRoot = null;
   }
 
+  if (!cfg.tools || typeof cfg.tools !== 'object') {
+    cfg.tools = {};
+  }
+  if (!Array.isArray(cfg.tools.includeCategories)) {
+    cfg.tools.includeCategories = [];
+  }
+  if (!Array.isArray(cfg.tools.excludeCategories)) {
+    cfg.tools.excludeCategories = [];
+  }
+
+  cfg.tools.includeCategories = cfg.tools.includeCategories
+    .filter(v => typeof v === 'string')
+    .map(v => v.trim())
+    .filter(Boolean);
+  cfg.tools.excludeCategories = cfg.tools.excludeCategories
+    .filter(v => typeof v === 'string')
+    .map(v => v.trim())
+    .filter(Boolean);
+
   // lsp timeout sanity
   if (cfg.lsp?.requestTimeoutMs !== undefined) {
     const t = Number(cfg.lsp.requestTimeoutMs);
@@ -315,6 +367,15 @@ function validateAndNormalizeConfig(cfg) {
       cfg.lsp.slowRequestWarnMs = 2000;
     }
   }
+  if (cfg.lsp?.validationTimeoutMs !== undefined) {
+    const t = Number(cfg.lsp.validationTimeoutMs);
+    if (!Number.isFinite(t) || t < 0) {
+      logger.warning(
+        `[unity-mcp-server] WARN: Invalid UNITY_MCP_LSP_VALIDATION_TIMEOUT_MS (${cfg.lsp.validationTimeoutMs}); using default 5000`
+      );
+      cfg.lsp.validationTimeoutMs = 5000;
+    }
+  }
 }
 
 export const config = merge(baseConfig, loadEnvConfig());

package/src/core/httpServer.js

@@ -1,5 +1,6 @@
 import http from 'node:http';
 import { logger } from './config.js';
+import { createProjectRootGuard } from './projectRootGuard.js';
 
 function buildHealthResponse({ startedAt, mode, port, telemetryEnabled }) {
   return {
@@ -22,10 +23,12 @@ export function createHttpServer({
   port = 6401,
   telemetryEnabled = false,
   healthPath = '/healthz',
-  allowedHosts = ['localhost', '127.0.0.1']
+  allowedHosts = ['localhost', '127.0.0.1'],
+  requireClientRoot = false
 } = {}) {
   const startedAt = Date.now();
   let server;
+  const projectRootGuard = createProjectRootGuard({ requireClientRoot, logger });
 
   const listener = async (req, res) => {
     try {
@@ -76,6 +79,18 @@ export function createHttpServer({
         if (method === 'tools/call' || method === 'callTool') {
           const name = params?.name;
           const args = params?.arguments || {};
+          const guardError = await projectRootGuard(args);
+          if (guardError) {
+            res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(
+              JSON.stringify({
+                jsonrpc: '2.0',
+                id,
+                error: { code: -32010, message: guardError }
+              })
+            );
+            return;
+          }
           const handler = handlers.get(name);
           if (!handler) {
             res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });

package/src/core/indexProgress.js

@@ -0,0 +1,15 @@
+export function buildProgress({ phase, processed = 0, total = 0, rate = 0 } = {}) {
+  const safePhase = phase && String(phase).trim() ? String(phase) : 'index';
+  return {
+    phase: safePhase,
+    processed: Number.isFinite(processed) ? processed : 0,
+    total: Number.isFinite(total) ? total : 0,
+    rate: Number.isFinite(rate) ? rate : 0
+  };
+}
+
+export function getReportEvery(total, steps = 20) {
+  const safeTotal = Number.isFinite(total) && total > 0 ? total : 0;
+  const safeSteps = Number.isFinite(steps) && steps > 0 ? steps : 20;
+  return Math.max(1, Math.floor(safeTotal / safeSteps) || 1);
+}

package/src/core/projectRootGuard.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { ProjectInfoProvider } from './projectInfo.js';
+
+const normalizeRoot = root => {
+  if (!root) return '';
+  const resolved = path.resolve(String(root));
+  const normalized = resolved.replace(/\\/g, '/').replace(/\/+$/g, '');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+};
+
+export function createProjectRootGuard({
+  requireClientRoot = false,
+  projectInfoProvider = null,
+  logger = null
+} = {}) {
+  const provider = projectInfoProvider || new ProjectInfoProvider();
+  let cachedRoot = null;
+
+  const getServerRoot = async () => {
+    if (cachedRoot) return cachedRoot;
+    try {
+      const info = await provider.get();
+      cachedRoot = normalizeRoot(info?.projectRoot || '');
+    } catch (e) {
+      logger?.warning?.(`[unity-mcp-server] project root resolve failed: ${e.message}`);
+    }
+    return cachedRoot;
+  };
+
+  return async function guard(args = {}) {
+    const clientRootRaw = args?.projectRoot;
+    if (!requireClientRoot && !clientRootRaw) return null;
+
+    if (!clientRootRaw) {
+      return 'projectRoot is required. Call get_server_info and pass projectRoot with tool arguments.';
+    }
+
+    const clientRoot = normalizeRoot(clientRootRaw);
+    const serverRoot = await getServerRoot();
+    if (!serverRoot) {
+      return 'server projectRoot could not be resolved';
+    }
+    if (clientRoot !== serverRoot) {
+      return `projectRoot mismatch (client=${clientRootRaw}, server=${serverRoot})`;
+    }
+    return null;
+  };
+}

package/src/core/server.js

@@ -15,6 +15,8 @@
  */
 import fs from 'node:fs';
 import { StdioRpcServer } from './stdioRpcServer.js';
+import { createProjectRootGuard } from './projectRootGuard.js';
+import { createToolCategoryPolicy, filterToolsByCategory } from './toolCategoryFilter.js';
 
 // Deferred state - will be initialized after transport connection
 let unityConnection = null;
@@ -125,8 +127,50 @@ export async function startServer(options = {}) {
       ...config,
       http: { ...config.http, ...(options.http || {}) },
       telemetry: { ...config.telemetry, ...(options.telemetry || {}) },
+      tools: {
+        includeCategories: config.tools?.includeCategories || [],
+        excludeCategories: config.tools?.excludeCategories || []
+      },
       stdioEnabled: options.stdioEnabled !== undefined ? options.stdioEnabled : true
     };
+    const toolCategoryPolicy = createToolCategoryPolicy(runtimeConfig.tools, logger);
+    let publicToolNames = null;
+    let toolFilterLogged = false;
+
+    const applyCategoryFilter = tools => {
+      if (!toolCategoryPolicy.isActive) {
+        return tools;
+      }
+
+      const filtered = filterToolsByCategory(tools, toolCategoryPolicy);
+      publicToolNames = filtered.publicToolNames;
+
+      if (!toolFilterLogged) {
+        const include =
+          toolCategoryPolicy.includeList.length > 0
+            ? toolCategoryPolicy.includeList.join(', ')
+            : '(all)';
+        const exclude =
+          toolCategoryPolicy.excludeList.length > 0
+            ? toolCategoryPolicy.excludeList.join(', ')
+            : '(none)';
+        logger.info(
+          `[MCP] Tool category filter enabled. include=${include}, exclude=${exclude}`
+        );
+        toolFilterLogged = true;
+      }
+
+      return filtered.tools;
+    };
+
+    const projectInfoProvider =
+      deps.projectInfoProvider ||
+      (deps.ProjectInfoProvider ? new deps.ProjectInfoProvider() : null);
+    const projectRootGuard = createProjectRootGuard({
+      requireClientRoot: runtimeConfig.project?.requireClientRoot === true,
+      logger,
+      projectInfoProvider
+    });
 
     // Step 2: Create a lightweight stdio MCP server (no TS SDK import)
     const server =
@@ -180,7 +224,8 @@ export async function startServer(options = {}) {
             port: runtimeConfig.http.port,
             telemetryEnabled: runtimeConfig.telemetry.enabled,
             healthPath: runtimeConfig.http.healthPath,
-            allowedHosts: runtimeConfig.http.allowedHosts
+            allowedHosts: runtimeConfig.http.allowedHosts,
+            requireClientRoot: runtimeConfig.project?.requireClientRoot === true
           });
           try {
             await httpServerInstance.start();
@@ -320,14 +365,15 @@ export async function startServer(options = {}) {
     server?.setRequestHandler('tools/list', async () => {
       const manifestTools = readToolManifest();
       if (manifestTools) {
-        logger.info(`[MCP] Returning ${manifestTools.length} tool definitions`);
+        const visibleTools = applyCategoryFilter(manifestTools);
+        logger.info(`[MCP] Returning ${visibleTools.length} tool definitions`);
         requestPostInit();
-        return { tools: manifestTools };
+        return { tools: visibleTools };
       }
 
       await ensureInitialized(deps);
 
-      const tools = Array.from(handlers.values())
+      const allTools = Array.from(handlers.values())
         .map((handler, index) => {
           try {
             const definition = handler.getDefinition();
@@ -345,6 +391,7 @@ export async function startServer(options = {}) {
         })
         .filter(tool => tool !== null);
 
+      const tools = applyCategoryFilter(allTools);
       logger.info(`[MCP] Returning ${tools.length} tool definitions`);
       requestPostInit();
       return { tools };
@@ -362,6 +409,30 @@ export async function startServer(options = {}) {
         { args }
       );
 
+      if (toolCategoryPolicy.isActive) {
+        if (!publicToolNames) {
+          const handlerTools = Array.from(handlers.values()).map(handler => ({ name: handler.name }));
+          publicToolNames = filterToolsByCategory(handlerTools, toolCategoryPolicy).publicToolNames;
+        }
+        if (!publicToolNames.has(name)) {
+          logger.error(`[MCP] Tool not found (filtered): ${name}`);
+          throw new Error(`Tool not found: ${name}`);
+        }
+      }
+
+      const guardError = await projectRootGuard(args || {});
+      if (guardError) {
+        logger.error(`[MCP] projectRoot guard failed: ${guardError}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${guardError}\nCode: PROJECT_ROOT_MISMATCH`
+            }
+          ]
+        };
+      }
+
       const handler = handlers.get(name);
       if (!handler) {
         logger.error(`[MCP] Tool not found: ${name}`);

package/src/core/toolCategoryFilter.js

@@ -0,0 +1,309 @@
+/**
+ * Tool category filtering for tools/list and tools/call visibility control.
+ */
+
+const CATEGORY_NAMES = Object.freeze([
+  'system',
+  'gameobject',
+  'scene',
+  'analysis',
+  'playmode',
+  'ui',
+  'input',
+  'asset',
+  'prefab',
+  'material',
+  'addressables',
+  'menu',
+  'console',
+  'screenshot',
+  'video',
+  'component',
+  'compilation',
+  'test',
+  'editor',
+  'settings',
+  'package',
+  'script',
+  'profiler',
+  'general'
+]);
+
+function toCategoryKey(value) {
+  if (typeof value !== 'string') return '';
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_-]+/g, '');
+}
+
+const CATEGORY_KEY_TO_NAME = new Map(CATEGORY_NAMES.map(name => [toCategoryKey(name), name]));
+
+// User-friendly aliases
+CATEGORY_KEY_TO_NAME.set('addressable', 'addressables');
+CATEGORY_KEY_TO_NAME.set('gameobj', 'gameobject');
+CATEGORY_KEY_TO_NAME.set('play', 'playmode');
+CATEGORY_KEY_TO_NAME.set('playmode', 'playmode');
+CATEGORY_KEY_TO_NAME.set('uitoolkit', 'ui');
+CATEGORY_KEY_TO_NAME.set('ugui', 'ui');
+CATEGORY_KEY_TO_NAME.set('imgui', 'ui');
+
+const SYSTEM_TOOLS = new Set([
+  'ping',
+  'refresh_assets',
+  'get_command_stats',
+  'get_server_info',
+  'search_tools'
+]);
+
+const GAMEOBJECT_TOOLS = new Set([
+  'create_gameobject',
+  'find_gameobject',
+  'modify_gameobject',
+  'delete_gameobject',
+  'get_hierarchy'
+]);
+
+const SCENE_TOOLS = new Set(['create_scene', 'load_scene', 'save_scene', 'list_scenes', 'get_scene_info']);
+
+const ANALYSIS_TOOLS = new Set([
+  'get_gameobject_details',
+  'analyze_scene_contents',
+  'get_component_values',
+  'find_by_component',
+  'get_object_references',
+  'get_animator_state',
+  'get_animator_runtime_info',
+  'get_input_actions_state',
+  'analyze_input_actions_asset'
+]);
+
+const PLAYMODE_TOOLS = new Set(['play_game', 'pause_game', 'stop_game', 'playmode_wait_for_state']);
+
+const UI_TOOLS = new Set([
+  'find_ui_elements',
+  'click_ui_element',
+  'get_ui_element_state',
+  'set_ui_element_value',
+  'simulate_ui_input'
+]);
+
+const INPUT_TOOLS = new Set([
+  'input_system_control',
+  'input_keyboard',
+  'input_mouse',
+  'input_gamepad',
+  'input_touch',
+  'create_action_map',
+  'remove_action_map',
+  'add_input_action',
+  'remove_input_action',
+  'add_input_binding',
+  'remove_input_binding',
+  'remove_all_bindings',
+  'create_composite_binding',
+  'manage_control_schemes'
+]);
+
+const ASSET_TOOLS = new Set([
+  'manage_asset_database',
+  'manage_asset_import_settings',
+  'analyze_asset_dependencies'
+]);
+
+const PREFAB_TOOLS = new Set([
+  'create_prefab',
+  'modify_prefab',
+  'instantiate_prefab',
+  'open_prefab',
+  'exit_prefab_mode',
+  'save_prefab'
+]);
+
+const MATERIAL_TOOLS = new Set(['create_material', 'modify_material']);
+
+const MENU_TOOLS = new Set(['execute_menu_item']);
+const CONSOLE_TOOLS = new Set(['clear_console', 'read_console']);
+const SCREENSHOT_TOOLS = new Set(['capture_screenshot', 'analyze_screenshot']);
+const VIDEO_TOOLS = new Set([
+  'capture_video_start',
+  'capture_video_stop',
+  'capture_video_status',
+  'video_capture_for'
+]);
+const COMPONENT_TOOLS = new Set([
+  'add_component',
+  'remove_component',
+  'modify_component',
+  'list_components',
+  'get_component_types',
+  'set_component_field'
+]);
+const COMPILATION_TOOLS = new Set(['get_compilation_state']);
+const TEST_TOOLS = new Set(['run_tests', 'get_test_status']);
+const EDITOR_TOOLS = new Set([
+  'manage_tags',
+  'manage_layers',
+  'manage_selection',
+  'manage_windows',
+  'manage_tools',
+  'get_editor_state',
+  'quit_editor'
+]);
+const SETTINGS_TOOLS = new Set(['get_project_settings', 'update_project_settings']);
+const PACKAGE_TOOLS = new Set(['package_manager', 'registry_config', 'list_packages']);
+const SCRIPT_TOOLS = new Set([
+  'read',
+  'search',
+  'edit_structured',
+  'edit_snippet',
+  'get_symbols',
+  'find_symbol',
+  'find_refs',
+  'build_index',
+  'update_index',
+  'get_index_status',
+  'rename_symbol',
+  'create_class',
+  'remove_symbol'
+]);
+
+const TOOL_SETS = [
+  ['system', SYSTEM_TOOLS],
+  ['gameobject', GAMEOBJECT_TOOLS],
+  ['scene', SCENE_TOOLS],
+  ['analysis', ANALYSIS_TOOLS],
+  ['playmode', PLAYMODE_TOOLS],
+  ['ui', UI_TOOLS],
+  ['input', INPUT_TOOLS],
+  ['asset', ASSET_TOOLS],
+  ['prefab', PREFAB_TOOLS],
+  ['material', MATERIAL_TOOLS],
+  ['menu', MENU_TOOLS],
+  ['console', CONSOLE_TOOLS],
+  ['screenshot', SCREENSHOT_TOOLS],
+  ['video', VIDEO_TOOLS],
+  ['component', COMPONENT_TOOLS],
+  ['compilation', COMPILATION_TOOLS],
+  ['test', TEST_TOOLS],
+  ['editor', EDITOR_TOOLS],
+  ['settings', SETTINGS_TOOLS],
+  ['package', PACKAGE_TOOLS],
+  ['script', SCRIPT_TOOLS]
+];
+
+function logWarning(logger, message) {
+  if (!logger) return;
+  if (typeof logger.warning === 'function') {
+    logger.warning(message);
+    return;
+  }
+  if (typeof logger.warn === 'function') {
+    logger.warn(message);
+    return;
+  }
+  if (typeof logger.info === 'function') {
+    logger.info(message);
+  }
+}
+
+function normalizeCategoryList(rawValues = []) {
+  const values = Array.isArray(rawValues) ? rawValues : [];
+  const normalized = [];
+  const unknown = [];
+  const seen = new Set();
+
+  for (const value of values) {
+    const key = toCategoryKey(value);
+    if (!key) continue;
+    const category = CATEGORY_KEY_TO_NAME.get(key);
+    if (!category) {
+      unknown.push(String(value).trim());
+      continue;
+    }
+    if (seen.has(category)) continue;
+    seen.add(category);
+    normalized.push(category);
+  }
+
+  return { normalized, unknown };
+}
+
+export function getToolCategory(toolName) {
+  const name = typeof toolName === 'string' ? toolName : '';
+  if (!name) return 'general';
+  if (name.startsWith('addressables_')) return 'addressables';
+  if (name.startsWith('profiler_')) return 'profiler';
+
+  for (const [category, set] of TOOL_SETS) {
+    if (set.has(name)) return category;
+  }
+
+  return 'general';
+}
+
+export function createToolCategoryPolicy(config = {}, logger) {
+  const includeResult = normalizeCategoryList(config.includeCategories);
+  const excludeResult = normalizeCategoryList(config.excludeCategories);
+
+  if (includeResult.unknown.length > 0) {
+    logWarning(
+      logger,
+      `[tool-filter] Ignoring unknown include categories: ${includeResult.unknown.join(', ')}`
+    );
+  }
+  if (excludeResult.unknown.length > 0) {
+    logWarning(
+      logger,
+      `[tool-filter] Ignoring unknown exclude categories: ${excludeResult.unknown.join(', ')}`
+    );
+  }
+
+  return {
+    includeCategories: new Set(includeResult.normalized),
+    excludeCategories: new Set(excludeResult.normalized),
+    includeList: includeResult.normalized,
+    excludeList: excludeResult.normalized,
+    isActive: includeResult.normalized.length > 0 || excludeResult.normalized.length > 0
+  };
+}
+
+export function filterToolsByCategory(tools, policy) {
+  const list = Array.isArray(tools) ? tools : [];
+  const publicTools = [];
+  const hiddenToolNames = new Set();
+  const publicToolNames = new Set();
+  const includeCategories = policy?.includeCategories ?? new Set();
+  const excludeCategories = policy?.excludeCategories ?? new Set();
+  const includeEnabled = includeCategories.size > 0;
+  const excludeEnabled = excludeCategories.size > 0;
+
+  for (const tool of list) {
+    const name = tool?.name;
+    if (typeof name !== 'string' || name.length === 0) {
+      continue;
+    }
+
+    const category = getToolCategory(name);
+    const includeMatch = !includeEnabled || includeCategories.has(category);
+    const excludeMatch = excludeEnabled && excludeCategories.has(category);
+    const visible = includeMatch && !excludeMatch;
+
+    if (visible) {
+      publicTools.push(tool);
+      publicToolNames.add(name);
+    } else {
+      hiddenToolNames.add(name);
+    }
+  }
+
+  return {
+    tools: publicTools,
+    publicToolNames,
+    hiddenToolNames
+  };
+}
+
+export function getKnownToolCategories() {
+  return [...CATEGORY_NAMES];
+}

package/src/core/toolManifest.json

@@ -3602,6 +3602,14 @@
       "properties": {}
     }
   },
+  {
+    "name": "get_server_info",
+    "description": "Get MCP server identifying information (pid, project root, workspace)",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
+  },
   {
     "name": "ping",
     "description": "Test connection to Unity Editor",

package/src/core/workers/indexBuildWorker.js

@@ -20,6 +20,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
+import { buildProgress, getReportEvery } from '../indexProgress.js';
 
 // fast-sql helper: run SQL statement
 function runSQL(db, sql) {
@@ -71,8 +72,8 @@ function log(level, message) {
   sendMessage('log', { level, message });
 }
 
-function sendProgress(processed, total, rate) {
-  sendMessage('progress', { data: { processed, total, rate } });
+function sendProgress(phase, processed, total, rate) {
+  sendMessage('progress', { data: buildProgress({ phase, processed, total, rate }) });
 }
 
 function sendComplete(result) {
@@ -624,6 +625,8 @@ async function runBuild() {
 
       // Determine changes (this calls makeSig for each file)
       log('info', `[worker] Computing file signatures (${files.length} files)...`);
+      sendProgress('signature', 0, files.length, 0);
+      const signatureReportEvery = getReportEvery(files.length);
       const sigStartTime = Date.now();
       let sigProcessed = 0;
       for (const abs of files) {
@@ -632,13 +635,19 @@ async function runBuild() {
         wanted.set(rel, sig);
         sigProcessed++;
         // Report progress every 10000 files
-        if (sigProcessed % 10000 === 0) {
+        if (sigProcessed % signatureReportEvery === 0) {
           const elapsed = ((Date.now() - sigStartTime) / 1000).toFixed(1);
           log('info', `[worker] Signature progress: ${sigProcessed}/${files.length} (${elapsed}s)`);
+          const sigElapsed = Math.max(1, Date.now() - sigStartTime);
+          const sigRate = parseFloat(((sigProcessed * 1000) / sigElapsed).toFixed(1));
+          sendProgress('signature', sigProcessed, files.length, sigRate);
         }
       }
       const sigTime = ((Date.now() - sigStartTime) / 1000).toFixed(1);
       log('info', `[worker] Signatures computed in ${sigTime}s`);
+      const sigElapsed = Math.max(1, Date.now() - sigStartTime);
+      const sigRate = parseFloat(((sigProcessed * 1000) / sigElapsed).toFixed(1));
+      sendProgress('signature', sigProcessed, files.length, sigRate);
 
       for (const [rel, sig] of wanted) {
         if (current.get(rel) !== sig) changed.push(rel);
@@ -671,6 +680,7 @@ async function runBuild() {
 
     // Prepare for updates
     const absList = changed.map(rel => path.resolve(projectRoot, rel));
+    sendProgress('index', 0, absList.length, 0);
     const startAt = Date.now();
     let processed = 0;
     let updated = 0;
@@ -786,7 +796,7 @@ async function runBuild() {
         currentPercentage >= lastReportedPercentage + reportPercentage ||
         processed === absList.length
       ) {
-        sendProgress(processed, absList.length, rate);
+        sendProgress('index', processed, absList.length, rate);
         log(
           'info',
           `[worker] progress ${currentPercentage}% (${processed}/${absList.length}) rate:${rate} f/s`

package/src/handlers/index.js

@@ -10,6 +10,7 @@
 import { SystemPingToolHandler } from './system/SystemPingToolHandler.js';
 import { SystemRefreshAssetsToolHandler } from './system/SystemRefreshAssetsToolHandler.js';
 import { SystemGetCommandStatsToolHandler } from './system/SystemGetCommandStatsToolHandler.js';
+import { SystemGetServerInfoToolHandler } from './system/SystemGetServerInfoToolHandler.js';
 import { GameObjectCreateToolHandler } from './gameobject/GameObjectCreateToolHandler.js';
 import { GameObjectFindToolHandler } from './gameobject/GameObjectFindToolHandler.js';
 import { GameObjectModifyToolHandler } from './gameobject/GameObjectModifyToolHandler.js';
@@ -279,6 +280,7 @@ const HANDLER_CLASSES = [
   SystemPingToolHandler,
   SystemRefreshAssetsToolHandler,
   SystemGetCommandStatsToolHandler,
+  SystemGetServerInfoToolHandler,
 
   // GameObject handlers
   GameObjectCreateToolHandler,

package/src/handlers/script/CodeIndexStatusToolHandler.js

@@ -1,6 +1,7 @@
 import { BaseToolHandler } from '../base/BaseToolHandler.js';
 import { JobManager } from '../../core/jobManager.js';
 import { CodeIndex } from '../../core/codeIndex.js';
+import { getWorkerPool } from '../../core/indexBuildWorkerPool.js';
 
 export class CodeIndexStatusToolHandler extends BaseToolHandler {
   constructor(unityConnection) {
@@ -16,6 +17,7 @@ export class CodeIndexStatusToolHandler extends BaseToolHandler {
     this.unityConnection = unityConnection;
     this.jobManager = JobManager.getInstance();
     this.codeIndex = new CodeIndex(unityConnection);
+    this.workerPool = getWorkerPool();
   }
 
   async execute() {
@@ -53,7 +55,8 @@ export class CodeIndexStatusToolHandler extends BaseToolHandler {
         }
       };
     }
-    const buildInProgress = latestBuildJob?.status === 'running';
+    const workerBuildRunning = Boolean(this.workerPool?.isRunning?.());
+    const buildInProgress = latestBuildJob?.status === 'running' || workerBuildRunning;
     if (!ready && !buildInProgress) {
       if (latestBuildJob) {
         const indexInfo = {
@@ -93,6 +96,51 @@ export class CodeIndexStatusToolHandler extends BaseToolHandler {
         message: 'Code index is not built. Please run UnityMCP.build_index first.'
       };
     }
+    if (!ready && buildInProgress) {
+      const buildJob = latestBuildJob
+        ? {
+            id: latestBuildJob.id,
+            status: latestBuildJob.status,
+            startedAt: latestBuildJob.startedAt ?? null,
+            ...(latestBuildJob.progress
+              ? {
+                  progress: {
+                    phase: latestBuildJob.progress.phase || 'index',
+                    ...latestBuildJob.progress
+                  }
+                }
+              : {})
+          }
+        : {
+            id: null,
+            status: 'running',
+            startedAt: null,
+            source: 'worker'
+          };
+
+      if (latestBuildJob?.status === 'failed') {
+        buildJob.failedAt = latestBuildJob.failedAt ?? null;
+        buildJob.error = latestBuildJob.error ?? 'Unknown error';
+      }
+
+      return {
+        success: true,
+        status: latestBuildJob?.status === 'failed' ? 'failed' : 'pending',
+        ready: false,
+        totalFiles: 0,
+        indexedFiles: 0,
+        coverage: 0,
+        message: buildInProgress
+          ? 'Code index build is running. Check back with get_index_status.'
+          : 'Code index is not ready yet.',
+        index: {
+          ready: false,
+          rows: 0,
+          lastIndexedAt: null,
+          buildJob
+        }
+      };
+    }
 
     // Use DB stats directly for fast status check - avoid expensive filesystem traversal
     const stats = await this.codeIndex.getStats();
@@ -109,7 +157,9 @@ export class CodeIndexStatusToolHandler extends BaseToolHandler {
     };
 
     if (latestBuildJob) {
-      const progress = latestBuildJob.progress ? { ...latestBuildJob.progress } : undefined;
+      const progress = latestBuildJob.progress
+        ? { phase: latestBuildJob.progress.phase || 'index', ...latestBuildJob.progress }
+        : undefined;
       indexInfo.buildJob = {
         id: latestBuildJob.id,
         status: latestBuildJob.status,

package/src/handlers/script/ScriptEditSnippetToolHandler.js

@@ -5,6 +5,7 @@ import { BaseToolHandler } from '../base/BaseToolHandler.js';
 import { ProjectInfoProvider } from '../../core/projectInfo.js';
 import { LspRpcClientSingleton } from '../../lsp/LspRpcClientSingleton.js';
 import { preSyntaxCheck } from './csharpSyntaxCheck.js';
+import { logger } from '../../core/config.js';
 
 const MAX_INSTRUCTIONS = 10;
 const MAX_DIFF_CHARS = 80;
@@ -29,11 +30,6 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
             description:
               'If true, run validation and return preview text without writing to disk. Default=false.'
           },
-          skipValidation: {
-            type: 'boolean',
-            description:
-              'If true, skip LSP validation for faster execution. Lightweight syntax checks (brace balance) are still performed. Use for simple edits on large files. Default=false.'
-          },
           instructions: {
             type: 'array',
             minItems: 1,
@@ -84,7 +80,10 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
 
   validate(params) {
     super.validate(params);
-    const { path: filePath, instructions } = params;
+    const { path: filePath, instructions, skipValidation } = params;
+    if (skipValidation === true) {
+      throw new Error('skipValidation is not allowed; LSP validation is required');
+    }
     if (!filePath || String(filePath).trim() === '') {
       throw new Error('path cannot be empty');
     }
@@ -115,10 +114,17 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
   }
 
   async execute(params) {
+    logger.info(
+      `[Handler edit_snippet] pid=${process.pid} path=${params?.path || ''} preview=${
+        params?.preview === true
+      }`
+    );
+    if (params?.skipValidation === true) {
+      throw new Error('skipValidation is not allowed; LSP validation is required');
+    }
     const info = await this.projectInfo.get();
     const { relative, absolute } = this.#resolvePaths(info, params.path);
     const preview = params.preview === true;
-    const skipValidation = params.skipValidation === true;
     const instructions = params.instructions;
 
     let original;
@@ -152,7 +158,7 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
         results,
         original,
         updated: working,
-        validationSkipped: skipValidation
+        validationSkipped: false
       });
     }
 
@@ -165,16 +171,14 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
       );
     }
 
-    // LSP validation (skip if skipValidation=true for large files)
+    // LSP validation
     let diagnostics = [];
-    if (!skipValidation) {
-      diagnostics = await this.#validateWithLsp(info, relative, working);
-      const hasErrors = diagnostics.some(d => this.#severityIsError(d.severity));
-      if (hasErrors) {
-        const first = diagnostics.find(d => this.#severityIsError(d.severity));
-        const msg = first?.message || 'syntax error';
-        throw new Error(`syntax_error: ${msg}`);
-      }
+    diagnostics = await this.#validateWithLsp(info, relative, working);
+    const hasErrors = diagnostics.some(d => this.#severityIsError(d.severity));
+    if (hasErrors) {
+      const first = diagnostics.find(d => this.#severityIsError(d.severity));
+      const msg = first?.message || 'syntax error';
+      throw new Error(`syntax_error: ${msg}`);
     }
 
     if (!preview) {
@@ -187,7 +191,7 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
       original,
       updated: working,
       diagnostics,
-      validationSkipped: skipValidation
+      validationSkipped: false
     });
   }
 
@@ -298,7 +302,30 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
     if (!this.lsp) {
       this.lsp = await LspRpcClientSingleton.getValidationInstance(info.projectRoot);
     }
-    return await this.lsp.validateText(relative, updatedText);
+    const tempRelative = this.#buildTempValidationPath(relative);
+    const tempAbsolute = path.join(
+      info.projectRoot,
+      tempRelative.replace(/\//g, path.sep)
+    );
+    await fs.mkdir(path.dirname(tempAbsolute), { recursive: true });
+    await fs.writeFile(tempAbsolute, updatedText, 'utf8');
+    try {
+      return await this.lsp.validateText(tempRelative, '');
+    } finally {
+      try {
+        await fs.rm(tempAbsolute, { force: true });
+      } catch (e) {
+        logger.warning(`[Handler edit_snippet] failed to remove temp file: ${e.message}`);
+      }
+    }
+  }
+
+  #buildTempValidationPath(relative) {
+    const ext = path.extname(relative) || '.cs';
+    const base = path.basename(relative, ext).replace(/[^a-zA-Z0-9._-]/g, '_');
+    const stamp = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const hash = crypto.createHash('sha1').update(relative).digest('hex').slice(0, 8);
+    return `.unity/tmp/edit-snippet/${base}_${hash}_${stamp}${ext}`;
   }
 
   #buildResponse({
@@ -351,4 +378,5 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
     const s = String(severity).toLowerCase();
     return s === 'error' || s === '2';
   }
+
 }

package/src/handlers/system/SystemGetServerInfoToolHandler.js

@@ -0,0 +1,55 @@
+import { BaseToolHandler } from '../base/BaseToolHandler.js';
+import { CATEGORIES, SCOPES } from '../base/categories.js';
+import { ProjectInfoProvider } from '../../core/projectInfo.js';
+import { config, WORKSPACE_ROOT } from '../../core/config.js';
+
+/**
+ * Handler for the get_server_info tool
+ * Provides identifiers to distinguish multiple MCP servers
+ */
+export class SystemGetServerInfoToolHandler extends BaseToolHandler {
+  constructor(unityConnection) {
+    super(
+      'get_server_info',
+      'Get MCP server identifying information (pid, project root, workspace)',
+      {
+        type: 'object',
+        properties: {}
+      },
+      {
+        category: CATEGORIES.SYSTEM,
+        scope: SCOPES.READ,
+        keywords: ['server', 'info', 'pid', 'project', 'workspace', 'identify'],
+        tags: ['system', 'diagnostic']
+      }
+    );
+
+    this.unityConnection = unityConnection;
+    this.projectInfo = new ProjectInfoProvider();
+  }
+
+  async execute() {
+    const info = await this.projectInfo.get();
+    return {
+      success: true,
+      pid: process.pid,
+      projectRoot: info.projectRoot,
+      assetsPath: info.assetsPath,
+      packagesPath: info.packagesPath,
+      codeIndexRoot: info.codeIndexRoot,
+      workspaceRoot: WORKSPACE_ROOT,
+      server: {
+        name: config?.server?.name,
+        version: config?.server?.version
+      },
+      unity: {
+        host: config?.unity?.unityHost ?? config?.unity?.mcpHost,
+        port: config?.unity?.port
+      },
+      http: {
+        enabled: config?.http?.enabled,
+        port: config?.http?.port
+      }
+    };
+  }
+}

package/src/lsp/LspRpcClient.js

@@ -152,12 +152,19 @@ export class LspRpcClient {
     return resp;
   }
 
-  async request(method, params) {
-    return await this.#requestWithRetry(method, params, 1);
+  async request(method, params, options = {}) {
+    return await this.#requestWithRetry(method, params, 1, options);
   }
 
   async validateText(relative, newText) {
-    const resp = await this.request('mcp/validateTextEdits', { relative, newText });
+    const timeoutMs = Number.isFinite(config.lsp?.validationTimeoutMs)
+      ? config.lsp.validationTimeoutMs
+      : undefined;
+    const resp = await this.request(
+      'mcp/validateTextEdits',
+      { relative, newText },
+      { timeoutMs }
+    );
     if (!resp) return [];
     const payload = resp.result ?? resp;
     const diagnostics = Array.isArray(payload?.diagnostics) ? payload.diagnostics : [];
@@ -170,10 +177,14 @@ export class LspRpcClient {
     }));
   }
 
-  async #requestWithRetry(method, params, attempt) {
+  async #requestWithRetry(method, params, attempt, options) {
     let id = null;
     let timeoutHandle = null;
-    const timeoutMs = Math.max(1000, Math.min(300000, config.lsp?.requestTimeoutMs || 60000));
+    const configuredTimeout = config.lsp?.requestTimeoutMs || 60000;
+    const overrideTimeout = options?.timeoutMs;
+    const timeoutMs = Number.isFinite(overrideTimeout)
+      ? Math.max(1000, Math.min(300000, overrideTimeout))
+      : Math.max(1000, Math.min(300000, configuredTimeout));
     const startedAt = Date.now();
     try {
       await this.ensure();
@@ -227,7 +238,7 @@ export class LspRpcClient {
         logger.warning(
           `[unity-mcp-server:lsp] recoverable error on ${method}: ${msg}. Retrying once...`
         );
-        return await this.#requestWithRetry(method, params, attempt + 1);
+        return await this.#requestWithRetry(method, params, attempt + 1, options);
       }
       // Standardize error message with actionable recovery instructions
       let hint;