@akiojin/unity-mcp-server 2.43.2 → 2.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "2.43.2",
+  "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 { HybridStdioServerTransport } from './transports/HybridStdioServerTransport.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');
-});
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+// 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,11 +77,28 @@ 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...`);
-      transport = new HybridStdioServerTransport();
+      transport = new StdioServerTransport();
       await server.connect(transport);
       console.error(`[unity-mcp-server] MCP transport connected`);
 
@@ -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,57 +301,61 @@ 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
-    // DISABLED: Investigating Issue #168 - npx timeout with Claude Code
-    // (async () => {
-    //   try {
-    //     const { CodeIndex } = await import('./codeIndex.js');
-    //     const index = new CodeIndex(unityConnection);
-    //     const ready = await index.isReady();
-
-    //     if (!ready) {
-    //       if (index.disabled) {
-    //         logger.warning(
-    //           `[startup] Code index disabled: ${index.disableReason || 'SQLite native binding missing'}. Skipping auto-build.`
-    //         );
-    //         return;
-    //       }
-    //       logger.info('[startup] Code index DB not ready. Starting auto-build...');
-    //       const { CodeIndexBuildToolHandler } = await import(
-    //         '../handlers/script/CodeIndexBuildToolHandler.js'
-    //       );
-    //       const builder = new CodeIndexBuildToolHandler(unityConnection);
-    //       const result = await builder.execute({});
-
-    //       if (result.success) {
-    //         logger.info(
-    //           `[startup] Code index auto-build started: jobId=${result.jobId}. Use code_index_status to check progress.`
-    //         );
-    //       } else {
-    //         logger.warning(`[startup] Code index auto-build failed: ${result.message}`);
-    //       }
-    //     } else {
-    //       logger.info('[startup] Code index DB already exists. Skipping auto-build.');
-    //     }
-    //   } catch (e) {
-    //     logger.warning(`[startup] Code index auto-init failed: ${e.message}`);
-    //   }
-    // })();
+    (async () => {
+      await ensureInitialized();
+      try {
+        const { CodeIndex } = await import('./codeIndex.js');
+        const index = new CodeIndex(unityConnection);
+        const ready = await index.isReady();
+
+        if (!ready) {
+          if (index.disabled) {
+            logger.warning(
+              `[startup] Code index disabled: ${index.disableReason || 'SQLite native binding missing'}. Skipping auto-build.`
+            );
+            return;
+          }
+          logger.info('[startup] Code index DB not ready. Starting auto-build...');
+          const { CodeIndexBuildToolHandler } = await import(
+            '../handlers/script/CodeIndexBuildToolHandler.js'
+          );
+          const builder = new CodeIndexBuildToolHandler(unityConnection);
+          const result = await builder.execute({});
+
+          if (result.success) {
+            logger.info(
+              `[startup] Code index auto-build started: jobId=${result.jobId}. Use code_index_status to check progress.`
+            );
+          } else {
+            logger.warning(`[startup] Code index auto-build failed: ${result.message}`);
+          }
+        } else {
+          logger.info('[startup] Code index DB already exists. Skipping auto-build.');
+        }
+      } catch (e) {
+        logger.warning(`[startup] Code index auto-init failed: ${e.message}`);
+      }
+    })();
 
     // 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);
@@ -308,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);
@@ -324,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

package/src/core/transports/HybridStdioServerTransport.js

@@ -1,191 +0,0 @@
-import process from 'node:process';
-import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
-
-const HEADER_END = '\r\n\r\n';
-const HEADER_RE = /Content-Length:\s*(\d+)/i;
-const DEFAULT_BUFFER = Buffer.alloc(0);
-
-function encodeContentLength(message) {
-  const json = JSON.stringify(message);
-  const header = `Content-Length: ${Buffer.byteLength(json, 'utf8')}${HEADER_END}`;
-  return header + json;
-}
-
-function parseJson(text) {
-  return JSONRPCMessageSchema.parse(JSON.parse(text));
-}
-
-export class HybridStdioServerTransport {
-  constructor(stdin = process.stdin, stdout = process.stdout) {
-    this._stdin = stdin;
-    this._stdout = stdout;
-    this._buffer = DEFAULT_BUFFER;
-    this._started = false;
-    this._mode = null; // 'content-length' | 'ndjson'
-
-    this._onData = chunk => {
-      this._buffer = this._buffer.length
-        ? Buffer.concat([this._buffer, chunk])
-        : Buffer.from(chunk);
-      this._processBuffer();
-    };
-
-    this._onError = error => {
-      this.onerror?.(error);
-    };
-  }
-
-  get framingMode() {
-    return this._mode;
-  }
-
-  async start() {
-    if (this._started) {
-      throw new Error('HybridStdioServerTransport already started');
-    }
-    this._started = true;
-    this._stdin.on('data', this._onData);
-    this._stdin.on('error', this._onError);
-  }
-
-  async close() {
-    if (!this._started) return;
-    this._stdin.off('data', this._onData);
-    this._stdin.off('error', this._onError);
-    this._buffer = DEFAULT_BUFFER;
-    this._started = false;
-    this.onclose?.();
-  }
-
-  send(message) {
-    return new Promise(resolve => {
-      // Always use Content-Length framing for output (MCP protocol standard)
-      // Input remains hybrid (Content-Length or NDJSON) for client compatibility
-      const payload = encodeContentLength(message);
-      if (this._stdout.write(payload)) {
-        resolve();
-      } else {
-        this._stdout.once('drain', resolve);
-      }
-    });
-  }
-
-  _processBuffer() {
-    while (true) {
-      const message = this._readMessage();
-      if (message === null) {
-        break;
-      }
-      this.onmessage?.(message);
-    }
-  }
-
-  _readMessage() {
-    if (!this._buffer || this._buffer.length === 0) {
-      return null;
-    }
-
-    if (this._mode === 'content-length') {
-      return this._readContentLengthMessage();
-    }
-    if (this._mode === 'ndjson') {
-      return this._readNdjsonMessage();
-    }
-
-    const prefix = this._peekPrefix();
-    if (!prefix.length) {
-      return null;
-    }
-
-    if ('content-length:'.startsWith(prefix.toLowerCase())) {
-      return null; // Wait for full header keyword before deciding
-    }
-
-    if (prefix.toLowerCase().startsWith('content-length:')) {
-      this._mode = 'content-length';
-      return this._readContentLengthMessage();
-    }
-
-    const newlineIndex = this._buffer.indexOf(0x0a); // '\n'
-    if (newlineIndex === -1) {
-      return null;
-    }
-
-    this._mode = 'ndjson';
-    return this._readNdjsonMessage();
-  }
-
-  _peekPrefix() {
-    const length = Math.min(this._buffer.length, 32);
-    return this._buffer.toString('utf8', 0, length).trimStart();
-  }
-
-  _readContentLengthMessage() {
-    const { headerEndIndex, separatorLength } = (() => {
-      const crlfIndex = this._buffer.indexOf('\r\n\r\n');
-      const lfIndex = this._buffer.indexOf('\n\n');
-
-      if (crlfIndex === -1 && lfIndex === -1) return { headerEndIndex: -1, separatorLength: 0 };
-      if (crlfIndex === -1) return { headerEndIndex: lfIndex, separatorLength: 2 };
-      if (lfIndex === -1) return { headerEndIndex: crlfIndex, separatorLength: 4 };
-
-      return crlfIndex < lfIndex
-        ? { headerEndIndex: crlfIndex, separatorLength: 4 }
-        : { headerEndIndex: lfIndex, separatorLength: 2 };
-    })();
-
-    if (headerEndIndex === -1) {
-      return null;
-    }
-
-    const header = this._buffer.toString('utf8', 0, headerEndIndex);
-    const match = header.match(HEADER_RE);
-    if (!match) {
-      this._buffer = this._buffer.subarray(headerEndIndex + separatorLength);
-      this.onerror?.(new Error('Invalid Content-Length header'));
-      return null;
-    }
-
-    const length = Number(match[1]);
-    const totalMessageLength = headerEndIndex + separatorLength + length;
-    if (this._buffer.length < totalMessageLength) {
-      return null;
-    }
-
-    const json = this._buffer.toString(
-      'utf8',
-      headerEndIndex + separatorLength,
-      totalMessageLength
-    );
-    this._buffer = this._buffer.subarray(totalMessageLength);
-
-    try {
-      return parseJson(json);
-    } catch (error) {
-      this.onerror?.(error);
-      return null;
-    }
-  }
-
-  _readNdjsonMessage() {
-    while (true) {
-      const newlineIndex = this._buffer.indexOf(0x0a);
-      if (newlineIndex === -1) {
-        return null;
-      }
-
-      let line = this._buffer.toString('utf8', 0, newlineIndex);
-      this._buffer = this._buffer.subarray(newlineIndex + 1);
-      line = line.trim();
-      if (!line) {
-        continue;
-      }
-
-      try {
-        return parseJson(line);
-      } catch (error) {
-        this.onerror?.(error);
-      }
-    }
-  }
-}