@akiojin/unity-mcp-server 5.3.2 → 5.4.0

package/package.json

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

@@ -105,7 +105,8 @@ const baseConfig = {
   // Project settings (primarily for code index paths)
   project: {
     root: null,
-    codeIndexRoot: null
+    codeIndexRoot: null,
+    requireClientRoot: false
   },
 
   // Server settings
@@ -154,7 +155,8 @@ const baseConfig = {
   // LSP client defaults
   lsp: {
     requestTimeoutMs: 120000,
-    slowRequestWarnMs: 2000
+    slowRequestWarnMs: 2000,
+    validationTimeoutMs: 5000
   },
 
   // Indexing (code index) settings
@@ -176,6 +178,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 +189,7 @@ 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 out = {};
 
@@ -201,6 +205,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 };
@@ -226,6 +233,9 @@ function loadEnvConfig() {
   if (lspSlowRequestWarnMs !== undefined) {
     out.lsp = { ...(out.lsp || {}), slowRequestWarnMs: lspSlowRequestWarnMs };
   }
+  if (lspValidationTimeoutMs !== undefined) {
+    out.lsp = { ...(out.lsp || {}), validationTimeoutMs: lspValidationTimeoutMs };
+  }
 
   return out;
 }
@@ -315,6 +325,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,7 @@
  */
 import fs from 'node:fs';
 import { StdioRpcServer } from './stdioRpcServer.js';
+import { createProjectRootGuard } from './projectRootGuard.js';
 
 // Deferred state - will be initialized after transport connection
 let unityConnection = null;
@@ -128,6 +129,15 @@ export async function startServer(options = {}) {
       stdioEnabled: options.stdioEnabled !== undefined ? options.stdioEnabled : true
     };
 
+    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 =
       runtimeConfig.stdioEnabled === false
@@ -180,7 +190,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();
@@ -362,6 +373,19 @@ export async function startServer(options = {}) {
         { args }
       );
 
+      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/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;