@akiojin/unity-mcp-server 2.43.3 → 2.44.0

package/package.json

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

@@ -1,183 +1,75 @@
 #!/usr/bin/env node
+/**
+ * Unity MCP Server - Main Server Module
+ *
+ * This module implements a deferred initialization pattern to ensure
+ * npx compatibility. The MCP transport connection is established FIRST,
+ * before loading handlers and other heavy dependencies, to avoid
+ * Claude Code's 30-second timeout.
+ *
+ * Initialization order:
+ * 1. MCP SDK imports (minimal, fast)
+ * 2. Transport connection (must complete before timeout)
+ * 3. Handler loading (deferred, after connection)
+ * 4. Unity connection (deferred, non-blocking)
+ */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import {
   ListToolsRequestSchema,
   CallToolRequestSchema,
   SetLevelRequestSchema
 } from '@modelcontextprotocol/sdk/types.js';
-// Note: filename is lowercase on disk; use exact casing for POSIX filesystems
-import { UnityConnection } from './unityConnection.js';
-import { createHandlers } from '../handlers/index.js';
-import { config, logger } from './config.js';
-import { IndexWatcher } from './indexWatcher.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-// Create Unity connection
-const unityConnection = new UnityConnection();
-
-// Create tool handlers
-const handlers = createHandlers(unityConnection);
-
-// Create MCP server
-const server = new Server(
-  {
-    name: config.server.name,
-    version: config.server.version
-  },
-  {
-    capabilities: {
-      // Explicitly advertise tool support; some MCP clients expect a non-empty object
-      // Setting listChanged enables future push updates if we emit notifications
-      tools: { listChanged: true },
-      // Enable MCP logging capability for sendLoggingMessage
-      logging: {}
-    }
-  }
-);
-
-// Register MCP protocol handlers
-// Note: Do not log here as it breaks MCP protocol initialization
-
-// Handle logging/setLevel request (REQ-6)
-server.setRequestHandler(SetLevelRequestSchema, async request => {
-  const { level } = request.params;
-  logger.setLevel(level);
-  logger.info(`Log level changed to: ${level}`);
-  return {};
-});
-
-// Handle tool listing
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  const tools = Array.from(handlers.values())
-    .map((handler, index) => {
-      try {
-        const definition = handler.getDefinition();
-        // Validate inputSchema
-        if (definition.inputSchema && definition.inputSchema.type !== 'object') {
-          logger.error(
-            `[MCP] Tool ${handler.name} (index ${index}) has invalid inputSchema type: ${definition.inputSchema.type}`
-          );
-        }
-        return definition;
-      } catch (error) {
-        logger.error(`[MCP] Failed to get definition for handler ${handler.name}:`, error);
-        return null;
-      }
-    })
-    .filter(tool => tool !== null);
-
-  logger.info(`[MCP] Returning ${tools.length} tool definitions`);
-  return { tools };
-});
-
-// Handle tool execution
-server.setRequestHandler(CallToolRequestSchema, async request => {
-  const { name, arguments: args } = request.params;
-  const requestTime = Date.now();
-
-  logger.info(
-    `[MCP] Received tool call request: ${name} at ${new Date(requestTime).toISOString()}`,
-    { args }
-  );
-
-  const handler = handlers.get(name);
-  if (!handler) {
-    logger.error(`[MCP] Tool not found: ${name}`);
-    throw new Error(`Tool not found: ${name}`);
-  }
-
-  try {
-    logger.info(`[MCP] Starting handler execution for: ${name} at ${new Date().toISOString()}`);
-    const startTime = Date.now();
-
-    // Handler returns response in our format
-    const result = await handler.handle(args);
-
-    const duration = Date.now() - startTime;
-    const totalDuration = Date.now() - requestTime;
-    logger.info(`[MCP] Handler completed at ${new Date().toISOString()}: ${name}`, {
-      handlerDuration: `${duration}ms`,
-      totalDuration: `${totalDuration}ms`,
-      status: result.status
-    });
-
-    // Convert to MCP format
-    if (result.status === 'error') {
-      logger.error(`[MCP] Handler returned error: ${name}`, {
-        error: result.error,
-        code: result.code
-      });
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Error: ${result.error}\nCode: ${result.code || 'UNKNOWN_ERROR'}${result.details ? '\nDetails: ' + JSON.stringify(result.details, null, 2) : ''}`
-          }
-        ]
-      };
-    }
-
-    // Success response
-    logger.info(`[MCP] Returning success response for: ${name} at ${new Date().toISOString()}`);
-
-    // Handle undefined or null results from handlers
-    let responseText;
-    if (result.result === undefined || result.result === null) {
-      responseText = JSON.stringify(
-        {
-          status: 'success',
-          message: 'Operation completed successfully but no details were returned',
-          tool: name
-        },
-        null,
-        2
-      );
-    } else {
-      responseText = JSON.stringify(result.result, null, 2);
-    }
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: responseText
-        }
-      ]
-    };
-  } catch (error) {
-    const errorTime = Date.now();
-    logger.error(`[MCP] Handler threw exception at ${new Date(errorTime).toISOString()}: ${name}`, {
-      error: error.message,
-      stack: error.stack,
-      duration: `${errorTime - requestTime}ms`
-    });
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error: ${error.message}`
-        }
-      ]
-    };
-  }
-});
-
-// Handle connection events
-unityConnection.on('connected', () => {
-  logger.info('Unity connection established');
-});
+// Deferred state - will be initialized after transport connection
+let unityConnection = null;
+let handlers = null;
+let config = null;
+let logger = null;
+
+/**
+ * Lazily load handlers and dependencies
+ * Called after MCP transport is connected
+ */
+async function ensureInitialized() {
+  if (handlers !== null) return;
+
+  // Load config first (needed for logging)
+  const configModule = await import('./config.js');
+  config = configModule.config;
+  logger = configModule.logger;
+
+  // Load UnityConnection
+  const { UnityConnection } = await import('./unityConnection.js');
+  unityConnection = new UnityConnection();
+
+  // Load and create handlers
+  const { createHandlers } = await import('../handlers/index.js');
+  handlers = createHandlers(unityConnection);
+
+  // Set up Unity connection event handlers
+  unityConnection.on('connected', () => {
+    logger.info('Unity connection established');
+  });
 
-unityConnection.on('disconnected', () => {
-  logger.info('Unity connection lost');
-});
+  unityConnection.on('disconnected', () => {
+    logger.info('Unity connection lost');
+  });
 
-unityConnection.on('error', error => {
-  logger.error('Unity connection error:', error.message);
-});
+  unityConnection.on('error', error => {
+    logger.error('Unity connection error:', error.message);
+  });
+}
 
 // Initialize server
 export async function startServer(options = {}) {
   try {
+    // Step 1: Load minimal config for server metadata
+    // We need server name/version before creating the Server instance
+    const { config: serverConfig, logger: serverLogger } = await import('./config.js');
+    config = serverConfig;
+    logger = serverLogger;
+
     const runtimeConfig = {
       ...config,
       http: { ...config.http, ...(options.http || {}) },
@@ -185,7 +77,24 @@ export async function startServer(options = {}) {
       stdioEnabled: options.stdioEnabled !== undefined ? options.stdioEnabled : true
     };
 
-    // Create transport - no logging before connection
+    // Step 2: Create MCP server with minimal configuration
+    const server = new Server(
+      {
+        name: config.server.name,
+        version: config.server.version
+      },
+      {
+        capabilities: {
+          // Explicitly advertise tool support; some MCP clients expect a non-empty object
+          // Setting listChanged enables future push updates if we emit notifications
+          tools: { listChanged: true },
+          // Enable MCP logging capability for sendLoggingMessage
+          logging: {}
+        }
+      }
+    );
+
+    // Step 3: Connect transport FIRST (critical for npx timeout avoidance)
     let transport;
     if (runtimeConfig.stdioEnabled !== false) {
       console.error(`[unity-mcp-server] MCP transport connecting...`);
@@ -197,9 +106,148 @@ export async function startServer(options = {}) {
       logger.setServer(server);
     }
 
+    // Step 4: Register request handlers (they will lazily load dependencies)
+    // Handle logging/setLevel request (REQ-6)
+    server.setRequestHandler(SetLevelRequestSchema, async request => {
+      await ensureInitialized();
+      const { level } = request.params;
+      logger.setLevel(level);
+      logger.info(`Log level changed to: ${level}`);
+      return {};
+    });
+
+    // Handle tool listing
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      await ensureInitialized();
+
+      const tools = Array.from(handlers.values())
+        .map((handler, index) => {
+          try {
+            const definition = handler.getDefinition();
+            // Validate inputSchema
+            if (definition.inputSchema && definition.inputSchema.type !== 'object') {
+              logger.error(
+                `[MCP] Tool ${handler.name} (index ${index}) has invalid inputSchema type: ${definition.inputSchema.type}`
+              );
+            }
+            return definition;
+          } catch (error) {
+            logger.error(`[MCP] Failed to get definition for handler ${handler.name}:`, error);
+            return null;
+          }
+        })
+        .filter(tool => tool !== null);
+
+      logger.info(`[MCP] Returning ${tools.length} tool definitions`);
+      return { tools };
+    });
+
+    // Handle tool execution
+    server.setRequestHandler(CallToolRequestSchema, async request => {
+      await ensureInitialized();
+
+      const { name, arguments: args } = request.params;
+      const requestTime = Date.now();
+
+      logger.info(
+        `[MCP] Received tool call request: ${name} at ${new Date(requestTime).toISOString()}`,
+        { args }
+      );
+
+      const handler = handlers.get(name);
+      if (!handler) {
+        logger.error(`[MCP] Tool not found: ${name}`);
+        throw new Error(`Tool not found: ${name}`);
+      }
+
+      try {
+        logger.info(`[MCP] Starting handler execution for: ${name} at ${new Date().toISOString()}`);
+        const startTime = Date.now();
+
+        // Handler returns response in our format
+        const result = await handler.handle(args);
+
+        const duration = Date.now() - startTime;
+        const totalDuration = Date.now() - requestTime;
+        logger.info(`[MCP] Handler completed at ${new Date().toISOString()}: ${name}`, {
+          handlerDuration: `${duration}ms`,
+          totalDuration: `${totalDuration}ms`,
+          status: result.status
+        });
+
+        // Convert to MCP format
+        if (result.status === 'error') {
+          logger.error(`[MCP] Handler returned error: ${name}`, {
+            error: result.error,
+            code: result.code
+          });
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Error: ${result.error}\nCode: ${result.code || 'UNKNOWN_ERROR'}${result.details ? '\nDetails: ' + JSON.stringify(result.details, null, 2) : ''}`
+              }
+            ]
+          };
+        }
+
+        // Success response
+        logger.info(`[MCP] Returning success response for: ${name} at ${new Date().toISOString()}`);
+
+        // Handle undefined or null results from handlers
+        let responseText;
+        if (result.result === undefined || result.result === null) {
+          responseText = JSON.stringify(
+            {
+              status: 'success',
+              message: 'Operation completed successfully but no details were returned',
+              tool: name
+            },
+            null,
+            2
+          );
+        } else {
+          responseText = JSON.stringify(result.result, null, 2);
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: responseText
+            }
+          ]
+        };
+      } catch (error) {
+        const errorTime = Date.now();
+        logger.error(
+          `[MCP] Handler threw exception at ${new Date(errorTime).toISOString()}: ${name}`,
+          {
+            error: error.message,
+            stack: error.stack,
+            duration: `${errorTime - requestTime}ms`
+          }
+        );
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error.message}`
+            }
+          ]
+        };
+      }
+    });
+
     // Now safe to log after connection established
     logger.info('MCP server started successfully');
 
+    // Step 5: Background initialization (non-blocking)
+    // Start loading handlers in background so first request is faster
+    ensureInitialized().catch(err => {
+      console.error(`[unity-mcp-server] Background initialization failed: ${err.message}`);
+    });
+
     // Optional HTTP transport
     let httpServerInstance;
     if (runtimeConfig.http?.enabled) {
@@ -219,16 +267,19 @@ export async function startServer(options = {}) {
       }
     }
 
-    // Attempt to connect to Unity
-    console.error(`[unity-mcp-server] Unity connection starting...`);
-    try {
-      await unityConnection.connect();
-      console.error(`[unity-mcp-server] Unity connection established`);
-    } catch (error) {
-      console.error(`[unity-mcp-server] Unity connection failed: ${error.message}`);
-      logger.error('Initial Unity connection failed:', error.message);
-      logger.info('Unity connection will retry automatically');
-    }
+    // Attempt to connect to Unity (deferred, non-blocking)
+    (async () => {
+      await ensureInitialized();
+      console.error(`[unity-mcp-server] Unity connection starting...`);
+      try {
+        await unityConnection.connect();
+        console.error(`[unity-mcp-server] Unity connection established`);
+      } catch (error) {
+        console.error(`[unity-mcp-server] Unity connection failed: ${error.message}`);
+        logger.error('Initial Unity connection failed:', error.message);
+        logger.info('Unity connection will retry automatically');
+      }
+    })();
 
     // Best-effort: prepare and start persistent C# LSP process (non-blocking)
     (async () => {
@@ -250,18 +301,23 @@ export async function startServer(options = {}) {
     })();
 
     // Start periodic index watcher (incremental)
-    const watcher = new IndexWatcher(unityConnection);
-    watcher.start();
-    const stopWatch = () => {
-      try {
-        watcher.stop();
-      } catch {}
-    };
-    process.on('SIGINT', stopWatch);
-    process.on('SIGTERM', stopWatch);
+    (async () => {
+      await ensureInitialized();
+      const { IndexWatcher } = await import('./indexWatcher.js');
+      const watcher = new IndexWatcher(unityConnection);
+      watcher.start();
+      const stopWatch = () => {
+        try {
+          watcher.stop();
+        } catch {}
+      };
+      process.on('SIGINT', stopWatch);
+      process.on('SIGTERM', stopWatch);
+    })();
 
     // Auto-initialize code index if DB doesn't exist
     (async () => {
+      await ensureInitialized();
       try {
         const { CodeIndex } = await import('./codeIndex.js');
         const index = new CodeIndex(unityConnection);
@@ -299,7 +355,7 @@ export async function startServer(options = {}) {
     // Handle shutdown
     process.on('SIGINT', async () => {
       logger.info('Shutting down...');
-      unityConnection.disconnect();
+      if (unityConnection) unityConnection.disconnect();
       if (transport) await server.close();
       if (httpServerInstance) await httpServerInstance.close();
       process.exit(0);
@@ -307,7 +363,7 @@ export async function startServer(options = {}) {
 
     process.on('SIGTERM', async () => {
       logger.info('Shutting down...');
-      unityConnection.disconnect();
+      if (unityConnection) unityConnection.disconnect();
       if (transport) await server.close();
       if (httpServerInstance) await httpServerInstance.close();
       process.exit(0);
@@ -323,14 +379,21 @@ export async function startServer(options = {}) {
 export const main = startServer;
 
 // Export for testing
-export async function createServer(customConfig = config) {
+export async function createServer(customConfig) {
+  // For testing, we need to load dependencies synchronously
+  const { config: defaultConfig } = await import('./config.js');
+  const actualConfig = customConfig || defaultConfig;
+
+  const { UnityConnection } = await import('./unityConnection.js');
+  const { createHandlers } = await import('../handlers/index.js');
+
   const testUnityConnection = new UnityConnection();
   const testHandlers = createHandlers(testUnityConnection);
 
   const testServer = new Server(
     {
-      name: customConfig.server.name,
-      version: customConfig.server.version
+      name: actualConfig.server.name,
+      version: actualConfig.server.version
     },
     {
       capabilities: {

package/src/lsp/CSharpLspUtils.js

@@ -90,9 +90,9 @@ export class CSharpLspUtils {
           fs.copyFileSync(legacyVersion, primaryVersion);
         } catch {}
       }
-      logger.info(`[csharp-lsp] migrated legacy binary to ${path.dirname(primary)}`);
+      logger.info(`[unity-mcp-server:lsp] migrated legacy binary to ${path.dirname(primary)}`);
     } catch (e) {
-      logger.warning(`[csharp-lsp] legacy migration failed: ${e.message}`);
+      logger.warning(`[unity-mcp-server:lsp] legacy migration failed: ${e.message}`);
     }
   }
 
@@ -135,7 +135,7 @@ export class CSharpLspUtils {
     // バージョン取得失敗時もバイナリが存在すれば使用
     if (!desired) {
       if (fs.existsSync(p)) {
-        logger.warning('[csharp-lsp] version not found, using existing binary');
+        logger.warning('[unity-mcp-server:lsp] version not found, using existing binary');
         return p;
       }
       throw new Error('mcp-server version not found; cannot resolve LSP tag');
@@ -152,7 +152,9 @@ export class CSharpLspUtils {
       return p;
     } catch (e) {
       if (fs.existsSync(p)) {
-        logger.warning(`[csharp-lsp] download failed, using existing binary: ${e.message}`);
+        logger.warning(
+          `[unity-mcp-server:lsp] download failed, using existing binary: ${e.message}`
+        );
         return p;
       }
       throw e;
@@ -212,7 +214,9 @@ export class CSharpLspUtils {
     try {
       if (process.platform !== 'win32') fs.chmodSync(dest, 0o755);
     } catch {}
-    logger.info(`[csharp-lsp] downloaded: ${path.basename(dest)} @ ${path.dirname(dest)}`);
+    logger.info(
+      `[unity-mcp-server:lsp] downloaded: ${path.basename(dest)} @ ${path.dirname(dest)}`
+    );
     // manifestから実際のバージョンを取得（信頼性の高いソースとして使用）
     const actualVersion = manifest.version || targetVersion;
     return actualVersion;

package/src/lsp/LspProcessManager.js

@@ -21,22 +21,22 @@ export class LspProcessManager {
         const rid = this.utils.detectRid();
         const bin = await this.utils.ensureLocal(rid);
         const proc = spawn(bin, { stdio: ['pipe', 'pipe', 'pipe'] });
-        proc.on('error', e => logger.error(`[csharp-lsp] process error: ${e.message}`));
+        proc.on('error', e => logger.error(`[unity-mcp-server:lsp] process error: ${e.message}`));
         proc.on('close', (code, sig) => {
-          logger.warning(`[csharp-lsp] exited code=${code} signal=${sig || ''}`);
+          logger.warning(`[unity-mcp-server:lsp] exited code=${code} signal=${sig || ''}`);
           if (this.state.proc === proc) {
             this.state.proc = null;
           }
         });
         proc.stderr.on('data', d => {
           const s = String(d || '').trim();
-          if (s) logger.debug(`[csharp-lsp] ${s}`);
+          if (s) logger.debug(`[unity-mcp-server:lsp] ${s}`);
         });
         this.state.proc = proc;
-        logger.info(`[csharp-lsp] started (pid=${proc.pid})`);
+        logger.info(`[unity-mcp-server:lsp] started (pid=${proc.pid})`);
         return proc;
       } catch (e) {
-        logger.error(`[csharp-lsp] failed to start: ${e.message}`);
+        logger.error(`[unity-mcp-server:lsp] failed to start: ${e.message}`);
         throw e;
       }
     })();

package/src/lsp/LspRpcClient.js

@@ -76,7 +76,7 @@ export class LspRpcClient {
     try {
       this.proc.stdin.write(payload, 'utf8');
     } catch (e) {
-      logger.error(`[csharp-lsp] writeMessage failed: ${e.message}`);
+      logger.error(`[unity-mcp-server:lsp] writeMessage failed: ${e.message}`);
       // Mark process as unavailable to prevent further writes
       this.proc = null;
       this.initialized = false;
@@ -161,7 +161,9 @@ export class LspRpcClient {
         this.proc = null;
         this.initialized = false;
         this.buf = Buffer.alloc(0);
-        logger.warning(`[csharp-lsp] recoverable error on ${method}: ${msg}. Retrying once...`);
+        logger.warning(
+          `[unity-mcp-server:lsp] recoverable error on ${method}: ${msg}. Retrying once...`
+        );
         return await this.#requestWithRetry(method, params, attempt + 1);
       }
       // Standardize error message