@akiojin/unity-mcp-server 2.42.1 → 2.42.3

package/bin/unity-mcp-server

@@ -1,8 +1,92 @@
 #!/usr/bin/env node
 import { startServer } from '../src/core/server.js';
+import { listInstances } from '../src/cli/commands/listInstances.js';
+import { setActive } from '../src/cli/commands/setActive.js';
 
-startServer().catch(error => {
-  console.error('Fatal error:', error);
-  console.error('Stack trace:', error?.stack);
-  process.exit(1);
-});
+const args = process.argv.slice(2);
+const command = args[0] && !args[0].startsWith('--') ? args[0] : null;
+const rest = command ? args.slice(1) : args;
+let httpEnabled = false;
+let httpPort;
+let stdioEnabled = true;
+let telemetryEnabled;
+
+for (let i = 0; i < rest.length; i++) {
+  const arg = rest[i];
+  switch (arg) {
+    case '--http':
+      httpEnabled = true;
+      if (args[i + 1] && !args[i + 1].startsWith('--')) {
+        httpPort = parseInt(args[i + 1], 10);
+        i++;
+      }
+      break;
+    case '--no-http':
+      httpEnabled = false;
+      break;
+    case '--stdio':
+      stdioEnabled = true;
+      break;
+    case '--no-stdio':
+      stdioEnabled = false;
+      break;
+    case '--telemetry':
+      telemetryEnabled = true;
+      break;
+    case '--no-telemetry':
+      telemetryEnabled = false;
+      break;
+    default:
+      break;
+  }
+}
+
+async function main() {
+  if (command === 'list-instances') {
+    const portsArg = rest.find(a => a.startsWith('--ports='));
+    const ports = portsArg ? portsArg.replace('--ports=', '').split(',').map(p => Number(p)) : [];
+    const hostArg = rest.find(a => a.startsWith('--host='));
+    const host = hostArg ? hostArg.replace('--host=', '') : 'localhost';
+    const json = rest.includes('--json');
+    const list = await listInstances({ ports, host });
+    if (json) {
+      console.log(JSON.stringify(list, null, 2));
+    } else {
+      for (const e of list) {
+        console.log(`${e.active ? '*' : ' '} ${e.id} ${e.status}`);
+      }
+    }
+    return;
+  }
+
+  if (command === 'set-active') {
+    const id = rest[0];
+    if (!id) {
+      console.error('Usage: unity-mcp-server set-active <host:port>');
+      process.exit(1);
+    }
+    try {
+      const result = await setActive({ id });
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e) {
+      console.error(e.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  startServer({
+    http: {
+      enabled: httpEnabled,
+      port: httpPort
+    },
+    telemetry: telemetryEnabled === undefined ? undefined : { enabled: telemetryEnabled },
+    stdioEnabled
+  }).catch(error => {
+    console.error('Fatal error:', error);
+    console.error('Stack trace:', error?.stack);
+    process.exit(1);
+  });
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "2.42.1",
+  "version": "2.42.3",
   "description": "MCP server and Unity Editor bridge — enables AI assistants to control Unity for AI-assisted workflows",
   "type": "module",
   "main": "src/core/server.js",
@@ -50,7 +50,7 @@
   "author": "Akio Jinsenji <akio-jinsenji@cloud-creative-studios.com>",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.24.0",
+    "@modelcontextprotocol/sdk": "^1.24.3",
     "better-sqlite3": "^9.4.3",
     "find-up": "^6.3.0"
   },

package/src/cli/commands/listInstances.js

@@ -0,0 +1,10 @@
+import { InstanceRegistry } from '../../core/instanceRegistry.js';
+
+export async function listInstances({ ports, host = 'localhost', registry }) {
+  const reg = registry || new InstanceRegistry();
+  if (Array.isArray(ports)) {
+    ports.forEach(p => reg.add({ host, port: Number(p) }));
+  }
+  await reg.refreshStatus();
+  return reg.list();
+}

package/src/cli/commands/setActive.js

@@ -0,0 +1,6 @@
+import { InstanceRegistry } from '../../core/instanceRegistry.js';
+
+export async function setActive({ id, registry }) {
+  const reg = registry || new InstanceRegistry();
+  return reg.setActive(id, { timeoutMs: 1000 });
+}

package/src/core/config.js

@@ -1,267 +1,313 @@
-import fs from 'fs';
-import path from 'path';
-import { findUpSync } from 'find-up';
-
-/**
- * Shallow merge utility (simple objects only)
- */
-function merge(a, b) {
-  const out = { ...a };
-  for (const [k, v] of Object.entries(b || {})) {
-    if (v && typeof v === 'object' && !Array.isArray(v) && a[k] && typeof a[k] === 'object') {
-      out[k] = { ...a[k], ...v };
-    } else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-
-function resolvePackageVersion() {
-  const candidates = [];
-
-  // Resolve relative to this module (always inside mcp-server/src/core)
-  try {
-    const moduleDir = path.dirname(new URL(import.meta.url).pathname);
-    candidates.push(path.resolve(moduleDir, '../../package.json'));
-  } catch {}
-
-  // When executed from workspace root (monorepo) or inside mcp-server package
-  try {
-    const here = findUpSync('package.json', { cwd: process.cwd() });
-    if (here) candidates.push(here);
-  } catch {}
-
-  for (const candidate of candidates) {
-    try {
-      if (!candidate || !fs.existsSync(candidate)) continue;
-      const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8'));
-      if (pkg?.version) return pkg.version;
-    } catch {}
-  }
-
-  return '0.1.0';
-}
-
-/**
- * Base configuration for Unity MCP Server Server
- */
-const envUnityHost =
-  process.env.UNITY_BIND_HOST || process.env.UNITY_HOST || null;
-
-const envMcpHost =
-  process.env.UNITY_MCP_HOST || process.env.UNITY_CLIENT_HOST || process.env.UNITY_HOST || null;
-
-const envBindHost = process.env.UNITY_BIND_HOST || null;
-
-const baseConfig = {
-  // Unity connection settings
-  unity: {
-    unityHost: envUnityHost,
-    mcpHost: envMcpHost,
-    bindHost: envBindHost,
-    port: parseInt(process.env.UNITY_PORT || '', 10) || 6400,
-    reconnectDelay: 1000,
-    maxReconnectDelay: 30000,
-    reconnectBackoffMultiplier: 2,
-    commandTimeout: 30000
-  },
-
-  // Server settings
-  server: {
-    name: 'unity-mcp-server',
-    version: resolvePackageVersion(),
-    description: 'MCP server for Unity Editor integration'
-  },
-
-  // Logging settings
-  logging: {
-    level: process.env.LOG_LEVEL || 'info',
-    prefix: '[Unity MCP Server]'
-  },
-
-  // Write queue removed: all edits go through structured Roslyn tools.
-
-  // Search-related defaults and engine selection
-  search: {
-    // detail alias: 'compact' maps to returnMode 'snippets'
-    defaultDetail: (process.env.SEARCH_DEFAULT_DETAIL || 'compact').toLowerCase(), // compact|metadata|snippets|full
-    engine: (process.env.SEARCH_ENGINE || 'naive').toLowerCase() // naive|treesitter (future)
-  },
-
-  // LSP client defaults
-  lsp: {
-    requestTimeoutMs: Number(process.env.LSP_REQUEST_TIMEOUT_MS || 60000)
-  },
-
-  // Indexing (code index) settings
-  indexing: {
-    // Enable periodic incremental index updates (polling watcher)
-    watch: true,
-    // Polling interval (ms)
-    intervalMs: Number(process.env.INDEX_WATCH_INTERVAL_MS || 15000),
-    // Build options
-    concurrency: Number(process.env.INDEX_CONCURRENCY || 8),
-    retry: Number(process.env.INDEX_RETRY || 2),
-    reportEvery: Number(process.env.INDEX_REPORT_EVERY || 500)
-  }
-};
-
-/**
- * External config resolution (no legacy compatibility):
- * Priority:
- * 1) UNITY_MCP_CONFIG (explicit file path)
- * 2) ./.unity/config.json (project-local)
- * 3) ~/.unity/config.json (user-global)
- * If none found, create ./.unity/config.json with defaults.
- */
-function ensureDefaultProjectConfig(baseDir) {
-  const dir = path.resolve(baseDir, '.unity');
-  const file = path.join(dir, 'config.json');
-
-  try {
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-
-    if (!fs.existsSync(file)) {
-      const inferredRoot = fs.existsSync(path.join(baseDir, 'Assets')) ? baseDir : '';
-      const defaultConfig = {
-        unity: {
-          unityHost: 'localhost',
-          mcpHost: 'localhost',
-          port: 6400
-        },
-        project: {
-          root: inferredRoot ? inferredRoot.replace(/\\/g, '/') : ''
-        }
-      };
-      fs.writeFileSync(file, `${JSON.stringify(defaultConfig, null, 2)}\n`, 'utf8');
-    }
-    return file;
-  } catch (error) {
-    return null;
-  }
-}
-
-function loadExternalConfig() {
-  const explicitPath = process.env.UNITY_MCP_CONFIG;
-
-  const projectPath = findUpSync(
-    directory => {
-      const candidate = path.resolve(directory, '.unity', 'config.json');
-      return fs.existsSync(candidate) ? candidate : undefined;
-    },
-    { cwd: process.cwd() }
-  );
-  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-  const userPath = homeDir ? path.resolve(homeDir, '.unity', 'config.json') : null;
-
-  const candidates = [explicitPath, projectPath, userPath].filter(Boolean);
-  for (const p of candidates) {
-    try {
-      if (p && fs.existsSync(p)) {
-        const raw = fs.readFileSync(p, 'utf8');
-        const json = JSON.parse(raw);
-        const out = json && typeof json === 'object' ? json : {};
-        out.__configPath = p;
-        return out;
-      }
-    } catch (e) {
-      return { __configLoadError: `${p}: ${e.message}` };
-    }
-  }
-  const fallbackPath = ensureDefaultProjectConfig(process.cwd());
-  if (fallbackPath && fs.existsSync(fallbackPath)) {
-    try {
-      const raw = fs.readFileSync(fallbackPath, 'utf8');
-      const json = JSON.parse(raw);
-      const out = json && typeof json === 'object' ? json : {};
-      out.__configPath = fallbackPath;
-      out.__configGenerated = true;
-      return out;
-    } catch (e) {
-      return { __configLoadError: `${fallbackPath}: ${e.message}` };
-    }
-  }
-  return {};
-}
-
-const external = loadExternalConfig();
-export const config = merge(baseConfig, external);
-
-const normalizeUnityConfig = () => {
-  const unityConfig = config.unity || (config.unity = {});
-
-  // Legacy aliases coming from config files or env vars
-  const legacyHost = unityConfig.host;
-  const legacyClientHost = unityConfig.clientHost;
-  const legacyBindHost = unityConfig.bindHost;
-
-  if (!unityConfig.unityHost) {
-    unityConfig.unityHost = legacyBindHost || legacyHost || envUnityHost || 'localhost';
-  }
-
-  if (!unityConfig.mcpHost) {
-    unityConfig.mcpHost = legacyClientHost || envMcpHost || legacyHost || unityConfig.unityHost;
-  }
-
-  // Keep bindHost for backwards compatibility with legacy code paths
-  if (!unityConfig.bindHost) {
-    unityConfig.bindHost = legacyBindHost || envBindHost || unityConfig.unityHost;
-  }
-
-  // Maintain legacy properties so older handlers keep working
-  unityConfig.host = unityConfig.unityHost;
-  unityConfig.clientHost = unityConfig.mcpHost;
-};
-
-normalizeUnityConfig();
-
-// Workspace root detection: directory that contains .unity/config.json used
-const initialCwd = process.cwd();
-let workspaceRoot = initialCwd;
-try {
-  if (config.__configPath) {
-    const cfgDir = path.dirname(config.__configPath); // <workspace>/.unity
-    workspaceRoot = path.dirname(cfgDir); // <workspace>
-  }
-} catch {}
-export const WORKSPACE_ROOT = workspaceRoot;
-
-/**
- * Logger utility
- * IMPORTANT: In MCP servers, all stdout output must be JSON-RPC protocol messages.
- * Logging must go to stderr to avoid breaking the protocol.
- */
-export const logger = {
-  info: (message, ...args) => {
-    if (['info', 'debug'].includes(config.logging.level)) {
-      console.error(`${config.logging.prefix} ${message}`, ...args);
-    }
-  },
-
-  warn: (message, ...args) => {
-    if (['info', 'debug', 'warn'].includes(config.logging.level)) {
-      console.error(`${config.logging.prefix} WARN: ${message}`, ...args);
-    }
-  },
-
-  error: (message, ...args) => {
-    console.error(`${config.logging.prefix} ERROR: ${message}`, ...args);
-  },
-
-  debug: (message, ...args) => {
-    if (config.logging.level === 'debug') {
-      console.error(`${config.logging.prefix} DEBUG: ${message}`, ...args);
-    }
-  }
-};
-
-// Late log if external config failed to load
-if (config.__configLoadError) {
-  console.error(
-    `${baseConfig.logging.prefix} WARN: Failed to load external config: ${config.__configLoadError}`
-  );
-  delete config.__configLoadError;
-}
+import fs from 'fs';
+import path from 'path';
+import * as findUpPkg from 'find-up';
+function findUpSyncCompat(matcher, options = {}) {
+  if (typeof matcher === 'function') {
+    let dir = options.cwd || process.cwd();
+    const { root } = path.parse(dir);
+    // walk up until root
+    while (true) {
+      const found = matcher(dir);
+      if (found) return found;
+      if (dir === root) return undefined;
+      dir = path.dirname(dir);
+    }
+  }
+  if (typeof findUpPkg.sync === 'function') return findUpPkg.sync(matcher, options);
+  if (typeof findUpPkg === 'function') return findUpPkg(matcher, options);
+  return undefined;
+}
+
+/**
+ * Shallow merge utility (simple objects only)
+ */
+function merge(a, b) {
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b || {})) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && a[k] && typeof a[k] === 'object') {
+      out[k] = { ...a[k], ...v };
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function resolvePackageVersion() {
+  const candidates = [];
+
+  // Resolve relative to this module (always inside mcp-server/src/core)
+  try {
+    const moduleDir = path.dirname(new URL(import.meta.url).pathname);
+    candidates.push(path.resolve(moduleDir, '../../package.json'));
+  } catch {}
+
+  // When executed from workspace root (monorepo) or inside mcp-server package
+  try {
+    const here = findUpSyncCompat('package.json', { cwd: process.cwd() });
+    if (here) candidates.push(here);
+  } catch {}
+
+  for (const candidate of candidates) {
+    try {
+      if (!candidate || !fs.existsSync(candidate)) continue;
+      const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      if (pkg?.version) return pkg.version;
+    } catch {}
+  }
+
+  return '0.1.0';
+}
+
+/**
+ * Base configuration for Unity MCP Server Server
+ */
+const envUnityHost = process.env.UNITY_BIND_HOST || process.env.UNITY_HOST || null;
+
+const envMcpHost =
+  process.env.UNITY_MCP_HOST || process.env.UNITY_CLIENT_HOST || process.env.UNITY_HOST || null;
+
+const envBindHost = process.env.UNITY_BIND_HOST || null;
+
+const baseConfig = {
+  // Unity connection settings
+  unity: {
+    unityHost: envUnityHost,
+    mcpHost: envMcpHost,
+    bindHost: envBindHost,
+    port: parseInt(process.env.UNITY_PORT || '', 10) || 6400,
+    reconnectDelay: 1000,
+    maxReconnectDelay: 30000,
+    reconnectBackoffMultiplier: 2,
+    commandTimeout: 30000
+  },
+
+  // Server settings
+  server: {
+    name: 'unity-mcp-server',
+    version: resolvePackageVersion(),
+    description: 'MCP server for Unity Editor integration'
+  },
+
+  // Logging settings
+  logging: {
+    level: process.env.LOG_LEVEL || 'info',
+    prefix: '[unity-mcp-server]'
+  },
+
+  // HTTP transport (off by default)
+  http: {
+    enabled: (process.env.UNITY_MCP_HTTP_ENABLED || 'false').toLowerCase() === 'true',
+    host: process.env.UNITY_MCP_HTTP_HOST || '0.0.0.0',
+    port: parseInt(process.env.UNITY_MCP_HTTP_PORT || '', 10) || 6401,
+    healthPath: '/healthz',
+    allowedHosts: (process.env.UNITY_MCP_HTTP_ALLOWED_HOSTS || 'localhost,127.0.0.1')
+      .split(',')
+      .map(h => h.trim())
+      .filter(h => h.length > 0)
+  },
+
+  telemetry: {
+    enabled: (process.env.UNITY_MCP_TELEMETRY || 'off').toLowerCase() === 'on',
+    destinations: [],
+    fields: []
+  },
+
+  // Write queue removed: all edits go through structured Roslyn tools.
+
+  // Search-related defaults and engine selection
+  search: {
+    // detail alias: 'compact' maps to returnMode 'snippets'
+    defaultDetail: (process.env.SEARCH_DEFAULT_DETAIL || 'compact').toLowerCase(), // compact|metadata|snippets|full
+    engine: (process.env.SEARCH_ENGINE || 'naive').toLowerCase() // naive|treesitter (future)
+  },
+
+  // LSP client defaults
+  lsp: {
+    requestTimeoutMs: Number(process.env.LSP_REQUEST_TIMEOUT_MS || 60000)
+  },
+
+  // Indexing (code index) settings
+  indexing: {
+    // Enable periodic incremental index updates (polling watcher)
+    watch: true,
+    // Polling interval (ms)
+    intervalMs: Number(process.env.INDEX_WATCH_INTERVAL_MS || 15000),
+    // Build options
+    concurrency: Number(process.env.INDEX_CONCURRENCY || 8),
+    retry: Number(process.env.INDEX_RETRY || 2),
+    reportEvery: Number(process.env.INDEX_REPORT_EVERY || 500)
+  }
+};
+
+/**
+ * External config resolution (no legacy compatibility):
+ * Priority:
+ * 1) UNITY_MCP_CONFIG (explicit file path)
+ * 2) ./.unity/config.json (project-local)
+ * 3) ~/.unity/config.json (user-global)
+ * If none found, create ./.unity/config.json with defaults.
+ */
+function ensureDefaultProjectConfig(baseDir) {
+  const dir = path.resolve(baseDir, '.unity');
+  const file = path.join(dir, 'config.json');
+
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    if (!fs.existsSync(file)) {
+      const inferredRoot = fs.existsSync(path.join(baseDir, 'Assets')) ? baseDir : '';
+      const defaultConfig = {
+        unity: {
+          unityHost: 'localhost',
+          mcpHost: 'localhost',
+          port: 6400
+        },
+        project: {
+          root: inferredRoot ? inferredRoot.replace(/\\/g, '/') : ''
+        }
+      };
+      fs.writeFileSync(file, `${JSON.stringify(defaultConfig, null, 2)}\n`, 'utf8');
+    }
+    return file;
+  } catch (error) {
+    return null;
+  }
+}
+
+function loadExternalConfig() {
+  if (typeof findUpSyncCompat !== 'function') {
+    return {};
+  }
+  const explicitPath = process.env.UNITY_MCP_CONFIG;
+
+  const projectPath = findUpSyncCompat(
+    directory => {
+      const candidate = path.resolve(directory, '.unity', 'config.json');
+      return fs.existsSync(candidate) ? candidate : undefined;
+    },
+    { cwd: process.cwd() }
+  );
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  const userPath = homeDir ? path.resolve(homeDir, '.unity', 'config.json') : null;
+
+  const candidates = [explicitPath, projectPath, userPath].filter(Boolean);
+  for (const p of candidates) {
+    try {
+      if (p && fs.existsSync(p)) {
+        const raw = fs.readFileSync(p, 'utf8');
+        const json = JSON.parse(raw);
+        const out = json && typeof json === 'object' ? json : {};
+        out.__configPath = p;
+        return out;
+      }
+    } catch (e) {
+      return { __configLoadError: `${p}: ${e.message}` };
+    }
+  }
+  const fallbackPath = ensureDefaultProjectConfig(process.cwd());
+  if (fallbackPath && fs.existsSync(fallbackPath)) {
+    try {
+      const raw = fs.readFileSync(fallbackPath, 'utf8');
+      const json = JSON.parse(raw);
+      const out = json && typeof json === 'object' ? json : {};
+      out.__configPath = fallbackPath;
+      out.__configGenerated = true;
+      return out;
+    } catch (e) {
+      return { __configLoadError: `${fallbackPath}: ${e.message}` };
+    }
+  }
+  return {};
+}
+
+const external = loadExternalConfig();
+export const config = merge(baseConfig, external);
+
+const normalizeUnityConfig = () => {
+  const unityConfig = config.unity || (config.unity = {});
+
+  // Legacy aliases coming from config files or env vars
+  const legacyHost = unityConfig.host;
+  const legacyClientHost = unityConfig.clientHost;
+  const legacyBindHost = unityConfig.bindHost;
+
+  if (!unityConfig.unityHost) {
+    unityConfig.unityHost = legacyBindHost || legacyHost || envUnityHost || 'localhost';
+  }
+
+  if (!unityConfig.mcpHost) {
+    unityConfig.mcpHost = legacyClientHost || envMcpHost || legacyHost || unityConfig.unityHost;
+  }
+
+  // Keep bindHost for backwards compatibility with legacy code paths
+  if (!unityConfig.bindHost) {
+    unityConfig.bindHost = legacyBindHost || envBindHost || unityConfig.unityHost;
+  }
+
+  // Maintain legacy properties so older handlers keep working
+  unityConfig.host = unityConfig.unityHost;
+  unityConfig.clientHost = unityConfig.mcpHost;
+};
+
+normalizeUnityConfig();
+
+// Workspace root detection: directory that contains .unity/config.json used
+const initialCwd = process.cwd();
+let workspaceRoot = initialCwd;
+try {
+  if (config.__configPath) {
+    const cfgDir = path.dirname(config.__configPath); // <workspace>/.unity
+    workspaceRoot = path.dirname(cfgDir); // <workspace>
+  }
+} catch {}
+export const WORKSPACE_ROOT = workspaceRoot;
+
+/**
+ * Logger utility
+ * IMPORTANT: In MCP servers, all stdout output must be JSON-RPC protocol messages.
+ * Logging must go to stderr to avoid breaking the protocol.
+ */
+export const logger = {
+  info: (message, ...args) => {
+    if (['info', 'debug'].includes(config.logging.level)) {
+      console.error(`${config.logging.prefix} ${message}`, ...args);
+    }
+  },
+
+  warn: (message, ...args) => {
+    if (['info', 'debug', 'warn'].includes(config.logging.level)) {
+      console.error(`${config.logging.prefix} WARN: ${message}`, ...args);
+    }
+  },
+
+  error: (message, ...args) => {
+    console.error(`${config.logging.prefix} ERROR: ${message}`, ...args);
+  },
+
+  debug: (message, ...args) => {
+    if (config.logging.level === 'debug') {
+      console.error(`${config.logging.prefix} DEBUG: ${message}`, ...args);
+    }
+  }
+};
+
+// Late log if external config failed to load
+if (config.__configLoadError) {
+  console.error(
+    `${baseConfig.logging.prefix} WARN: Failed to load external config: ${config.__configLoadError}`
+  );
+  delete config.__configLoadError;
+}
+
+// Startup debug log: output config info to stderr for troubleshooting
+// This helps diagnose connection issues (especially in WSL2/Docker environments)
+console.error(`[unity-mcp-server] Startup config:`);
+console.error(`[unity-mcp-server]   Config file: ${config.__configPath || '(defaults)'}`);
+console.error(
+  `[unity-mcp-server]   Unity host: ${config.unity.mcpHost || config.unity.unityHost || 'localhost'}`
+);
+console.error(`[unity-mcp-server]   Unity port: ${config.unity.port}`);
+console.error(`[unity-mcp-server]   Workspace root: ${WORKSPACE_ROOT}`);

package/src/core/httpServer.js

@@ -0,0 +1,147 @@
+import http from 'node:http';
+import { logger } from './config.js';
+
+function buildHealthResponse({ startedAt, mode, port, telemetryEnabled }) {
+  return {
+    status: 'ok',
+    mode,
+    port,
+    telemetryEnabled,
+    uptimeMs: Date.now() - startedAt
+  };
+}
+
+function suggestPorts(port) {
+  if (!port || typeof port !== 'number') return [];
+  return [port + 1, port + 2, port + 11];
+}
+
+export function createHttpServer({
+  handlers,
+  host = '0.0.0.0',
+  port = 6401,
+  telemetryEnabled = false,
+  healthPath = '/healthz',
+  allowedHosts = ['localhost', '127.0.0.1']
+} = {}) {
+  const startedAt = Date.now();
+  let server;
+
+  const listener = async (req, res) => {
+    try {
+      const hostHeader = req.headers.host?.split(':')[0];
+      if (allowedHosts && allowedHosts.length && hostHeader && !allowedHosts.includes(hostHeader)) {
+        res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ error: 'forbidden host' }));
+        return;
+      }
+
+      const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+
+      if (req.method === 'GET' && url.pathname === healthPath) {
+        const body = buildHealthResponse({
+          startedAt,
+          mode: 'http',
+          port: server?.address()?.port,
+          telemetryEnabled
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify(body));
+        return;
+      }
+
+      if (req.method === 'POST' && url.pathname === '/rpc') {
+        const chunks = [];
+        for await (const chunk of req) chunks.push(chunk);
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let payload;
+        try {
+          payload = JSON.parse(raw || '{}');
+        } catch (e) {
+          res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+          res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32700, message: 'Invalid JSON' } }));
+          return;
+        }
+
+        const { method, params, id } = payload || {};
+        if (method === 'tools/list' || method === 'listTools') {
+          const tools = Array.from(handlers.values()).map(h => h.getDefinition());
+          res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+          res.end(JSON.stringify({ jsonrpc: '2.0', id, result: { tools } }));
+          return;
+        }
+
+        if (method === 'tools/call' || method === 'callTool') {
+          const name = params?.name;
+          const args = params?.arguments || {};
+          const handler = handlers.get(name);
+          if (!handler) {
+            res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32004, message: `Tool not found: ${name}` } }));
+            return;
+          }
+          try {
+            const result = await handler.handle(args);
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify({ jsonrpc: '2.0', id, result }));
+          } catch (e) {
+            logger.error(`[http] tool error ${name}: ${e.message}`);
+            res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32000, message: e.message } }));
+          }
+          return;
+        }
+
+        res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } }));
+        return;
+      }
+
+      res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+      res.end(JSON.stringify({ error: 'Not found' }));
+    } catch (e) {
+      logger.error(`[http] unexpected error: ${e.message}`);
+      try {
+        res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ error: 'internal error' }));
+      } catch {}
+    }
+  };
+
+  server = http.createServer(listener);
+
+  const start = () =>
+    new Promise((resolve, reject) => {
+      const onError = err => {
+        server.off('error', onError);
+        if (err.code === 'EADDRINUSE') {
+          const suggestions = suggestPorts(port);
+          const msg = `Port ${port} is already in use. Try: ${suggestions.join(', ')}`;
+          logger.error(msg);
+        }
+        reject(err);
+      };
+      server.once('error', onError);
+      server.listen(port, host, () => {
+        server.off('error', onError);
+        const address = server.address();
+        logger.info(`HTTP listening on http://${host}:${address.port}, telemetry: ${telemetryEnabled ? 'on' : 'off'}`);
+        resolve(address.port);
+      });
+    });
+
+  const close = () =>
+    new Promise((resolve, reject) => {
+      server.close(err => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+
+  return {
+    start,
+    close,
+    getPort: () => server.address()?.port,
+    health: () => buildHealthResponse({ startedAt, mode: 'http', port: server.address()?.port, telemetryEnabled })
+  };
+}

package/src/core/instanceRegistry.js

@@ -0,0 +1,73 @@
+import net from 'node:net';
+
+async function ping(host, port, timeoutMs = 1000) {
+  return new Promise(resolve => {
+    const socket = net.connect({ host, port });
+    const timer = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, timeoutMs);
+
+    socket.on('connect', () => {
+      clearTimeout(timer);
+      socket.end();
+      resolve(true);
+    });
+    socket.on('error', () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+  });
+}
+
+export class InstanceRegistry {
+  constructor(entries = []) {
+    this.entries = [];
+    this.activeId = null;
+    entries.forEach(e => this.add(e));
+  }
+
+  add(entry) {
+    const id = entry.id || `${entry.host}:${entry.port}`;
+    if (this.entries.find(e => e.id === id)) return;
+    this.entries.push({
+      id,
+      host: entry.host,
+      port: entry.port,
+      status: entry.status || 'unknown',
+      lastCheckedAt: entry.lastCheckedAt,
+      active: false
+    });
+  }
+
+  remove(id) {
+    this.entries = this.entries.filter(e => e.id !== id);
+  }
+
+  list() {
+    return this.entries.map(e => ({ ...e, active: e.id === this.activeId }));
+  }
+
+  async refreshStatus(timeoutMs = 1000) {
+    for (const entry of this.entries) {
+      const ok = await ping(entry.host, entry.port, timeoutMs);
+      entry.status = ok ? 'up' : 'down';
+      entry.lastCheckedAt = new Date().toISOString();
+    }
+    return this.list();
+  }
+
+  async setActive(id, { timeoutMs = 1000 } = {}) {
+    const entry = this.entries.find(e => e.id === id);
+    if (!entry) throw new Error(`Instance not found: ${id}`);
+
+    const ok = await ping(entry.host, entry.port, timeoutMs);
+    if (!ok) throw new Error(`Instance unreachable: ${id}`);
+
+    const previousId = this.activeId;
+    this.activeId = id;
+    entry.status = 'up';
+    entry.lastCheckedAt = new Date().toISOString();
+    return { activeId: id, previousId };
+  }
+}

package/src/core/server.js

@@ -162,21 +162,53 @@ unityConnection.on('error', error => {
 });
 
 // Initialize server
-export async function startServer() {
+export async function startServer(options = {}) {
   try {
-    // Create transport - no logging before connection
-    const transport = new HybridStdioServerTransport();
+    const runtimeConfig = {
+      ...config,
+      http: { ...config.http, ...(options.http || {}) },
+      telemetry: { ...config.telemetry, ...(options.telemetry || {}) },
+      stdioEnabled: options.stdioEnabled !== undefined ? options.stdioEnabled : true
+    };
 
-    // Connect to transport
-    await server.connect(transport);
+    // Create transport - no logging before connection
+    let transport;
+    if (runtimeConfig.stdioEnabled !== false) {
+      console.error(`[unity-mcp-server] MCP transport connecting...`);
+      transport = new HybridStdioServerTransport();
+      await server.connect(transport);
+      console.error(`[unity-mcp-server] MCP transport connected`);
+    }
 
     // Now safe to log after connection established
     logger.info('MCP server started successfully');
 
+    // Optional HTTP transport
+    let httpServerInstance;
+    if (runtimeConfig.http?.enabled) {
+      const { createHttpServer } = await import('./httpServer.js');
+      httpServerInstance = createHttpServer({
+        handlers,
+        host: runtimeConfig.http.host,
+        port: runtimeConfig.http.port,
+        telemetryEnabled: runtimeConfig.telemetry.enabled,
+        healthPath: runtimeConfig.http.healthPath
+      });
+      try {
+        await httpServerInstance.start();
+      } catch (err) {
+        logger.error(`HTTP server failed to start: ${err.message}`);
+        throw err;
+      }
+    }
+
     // 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');
     }
@@ -251,14 +283,16 @@ export async function startServer() {
     process.on('SIGINT', async () => {
       logger.info('Shutting down...');
       unityConnection.disconnect();
-      await server.close();
+      if (transport) await server.close();
+      if (httpServerInstance) await httpServerInstance.close();
       process.exit(0);
     });
 
     process.on('SIGTERM', async () => {
       logger.info('Shutting down...');
       unityConnection.disconnect();
-      await server.close();
+      if (transport) await server.close();
+      if (httpServerInstance) await httpServerInstance.close();
       process.exit(0);
     });
   } catch (error) {

package/src/core/unityConnection.js

@@ -21,6 +21,7 @@ export class UnityConnection extends EventEmitter {
     this.sendQueue = [];
     this.inFlight = 0;
     this.maxInFlight = 1; // process one command at a time by default
+    this.connectedAt = null; // Timestamp when connection was established
   }
 
   /**
@@ -48,6 +49,9 @@ export class UnityConnection extends EventEmitter {
       }
 
       const targetHost = config.unity.mcpHost || config.unity.unityHost;
+      console.error(
+        `[unity-mcp-server] Unity TCP connecting to ${targetHost}:${config.unity.port}...`
+      );
       logger.info(`Connecting to Unity at ${targetHost}:${config.unity.port}...`);
 
       this.socket = new net.Socket();
@@ -74,7 +78,11 @@ export class UnityConnection extends EventEmitter {
 
       // Set up event handlers
       this.socket.on('connect', () => {
-        logger.info('Connected to Unity Editor');
+        this.connectedAt = Date.now();
+        console.error(
+          `[unity-mcp-server] Unity TCP connected to ${targetHost}:${config.unity.port}`
+        );
+        logger.info(`Connected to Unity Editor at ${targetHost}:${config.unity.port}`);
         this.connected = true;
         this.reconnectAttempts = 0;
         this.connectPromise = null;
@@ -84,6 +92,12 @@ export class UnityConnection extends EventEmitter {
       });
 
       this.socket.on('end', () => {
+        // Unity closed the connection (FIN received)
+        const duration = this.connectedAt ? Date.now() - this.connectedAt : 0;
+        console.error(
+          `[unity-mcp-server] Unity TCP connection ended by remote (FIN received, duration: ${duration}ms)`
+        );
+        logger.info(`Unity closed connection (FIN received) after ${duration}ms`);
         // Treat end as close to trigger reconnection
         this.socket.destroy();
       });
@@ -93,6 +107,7 @@ export class UnityConnection extends EventEmitter {
       });
 
       this.socket.on('error', error => {
+        console.error(`[unity-mcp-server] Unity TCP error: ${error.message}`);
         logger.error('Socket error:', error.message);
         if (this.listenerCount('error') > 0) {
           this.emit('error', error);
@@ -121,11 +136,15 @@ export class UnityConnection extends EventEmitter {
 
         // Check if we're already handling disconnection
         if (this.isDisconnecting || !this.socket) {
+          console.error(`[unity-mcp-server] Unity TCP close event (already disconnecting)`);
           return;
         }
 
-        logger.info('Disconnected from Unity Editor');
+        const duration = this.connectedAt ? Date.now() - this.connectedAt : 0;
+        console.error(`[unity-mcp-server] Unity TCP disconnected (duration: ${duration}ms)`);
+        logger.info(`Disconnected from Unity Editor after ${duration}ms`);
         this.connected = false;
+        this.connectedAt = null;
         this.socket = null;
 
         // Clear message buffer
@@ -224,6 +243,9 @@ export class UnityConnection extends EventEmitter {
    * @param {Buffer} data
    */
   handleData(data) {
+    // Log received data size for debugging connection issues
+    console.error(`[unity-mcp-server] Received ${data.length} bytes from Unity`);
+
     // Fast-path: accept single unframed JSON message (NDJSON style) from tests/clients
     if (!this.messageBuffer.length) {
       const asString = data.toString('utf8').trim();
@@ -240,7 +262,7 @@ export class UnityConnection extends EventEmitter {
     // Check if this is an unframed Unity debug log
     if (data.length > 0 && !this.messageBuffer.length) {
       const dataStr = data.toString('utf8');
-      if (dataStr.startsWith('[Unity MCP Server]') || dataStr.startsWith('[Unity]')) {
+      if (dataStr.startsWith('[unity-mcp-server]') || dataStr.startsWith('[Unity]')) {
         logger.debug(`[Unity] Received unframed debug log: ${dataStr.trim()}`);
         // Don't process unframed logs as messages
         return;
@@ -315,7 +337,7 @@ export class UnityConnection extends EventEmitter {
 
           // Check if this looks like a Unity log message
           const messageStr = messageData.toString();
-          if (messageStr.includes('[Unity MCP Server]')) {
+          if (messageStr.includes('[unity-mcp-server]')) {
             logger.debug('[Unity] Received Unity log message instead of JSON response');
             // Don't treat this as a critical error
           }