@akiojin/unity-mcp-server 4.2.1 → 5.1.0

package/README.md

@@ -72,6 +72,13 @@ More details:
 - Node.js 18.x / 20.x / 22.x LTS (23+ not supported)
 - MCP client (Claude Desktop, Cursor, etc.)
 
+## Native SQLite preload (optional)
+
+The server uses `fast-sql`, which can preload a native `better-sqlite3` binding when a prebuilt binary is packaged.
+
+- `UNITY_MCP_SKIP_NATIVE_BUILD=1` to skip native preload (forces sql.js fallback)
+- `UNITY_MCP_FORCE_NATIVE=1` to require the prebuilt binary (install fails if missing)
+
 ## Troubleshooting
 
 - Troubleshooting index: [`docs/troubleshooting/README.md`](https://github.com/akiojin/unity-mcp-server/blob/main/docs/troubleshooting/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "4.2.1",
+  "version": "5.1.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",
@@ -27,7 +27,7 @@
     "test:verbose": "VERBOSE_TEST=true node --test tests/**/*.test.js",
     "prepare": "cd .. && husky || true",
     "prepublishOnly": "npm run test:ci",
-    "postinstall": "chmod +x bin/unity-mcp-server.js || true",
+    "postinstall": "node scripts/ensure-better-sqlite3.mjs",
     "test:ci:unity": "timeout 60 node --test tests/unit/core/codeIndex.test.js tests/unit/core/config.test.js tests/unit/core/indexWatcher.test.js tests/unit/core/projectInfo.test.js tests/unit/core/server.test.js tests/unit/core/startupPerformance.test.js || exit 0",
     "test:unity": "node tests/run-unity-integration.mjs",
     "test:nounity": "npm run test:integration",
@@ -68,6 +68,8 @@
   "files": [
     "src/",
     "bin/",
+    "scripts/",
+    "prebuilt/",
     "README.md",
     "LICENSE"
   ],

package/scripts/ensure-better-sqlite3.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const ABI_BY_NODE_MAJOR = new Map([
+  [18, 115],
+  [20, 120],
+  [22, 131]
+]);
+
+export function parseEnvFlag(value) {
+  if (!value) return false;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+
+export function resolveNodeMajor(nodeVersion) {
+  if (!nodeVersion) return null;
+  const major = Number.parseInt(String(nodeVersion).split('.')[0], 10);
+  return Number.isFinite(major) ? major : null;
+}
+
+export function resolveNodeAbi({ nodeVersion, nodeAbi } = {}) {
+  const abi = Number.parseInt(nodeAbi, 10);
+  if (Number.isFinite(abi)) return abi;
+  const major = resolveNodeMajor(nodeVersion);
+  if (!major) return null;
+  return ABI_BY_NODE_MAJOR.get(major) ?? null;
+}
+
+export function resolveRuntimeInfo({
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  nodeVersion = process.versions?.node,
+  nodeAbi = process.versions?.modules
+} = {}) {
+  const resolvedPlatform = env.UNITY_MCP_PLATFORM || platform;
+  const resolvedArch = env.UNITY_MCP_ARCH || arch;
+  const envNodeMajor = env.UNITY_MCP_NODE_MAJOR
+    ? Number.parseInt(env.UNITY_MCP_NODE_MAJOR, 10)
+    : null;
+  const resolvedNodeMajor = Number.isFinite(envNodeMajor)
+    ? envNodeMajor
+    : resolveNodeMajor(nodeVersion);
+  const envNodeAbi = env.UNITY_MCP_NODE_ABI ? Number.parseInt(env.UNITY_MCP_NODE_ABI, 10) : null;
+  const resolvedNodeAbi = Number.isFinite(envNodeAbi)
+    ? envNodeAbi
+    : resolveNodeAbi({ nodeVersion, nodeAbi });
+
+  return {
+    platform: resolvedPlatform,
+    arch: resolvedArch,
+    nodeMajor: resolvedNodeMajor,
+    nodeAbi: resolvedNodeAbi
+  };
+}
+
+export function buildPlatformKey({ platform, arch, nodeMajor }) {
+  if (!platform || !arch || !nodeMajor) return null;
+  return `${platform}-${arch}-node${nodeMajor}`;
+}
+
+export function resolvePackageRoot(env = process.env) {
+  if (env.UNITY_MCP_PACKAGE_ROOT) {
+    return path.resolve(env.UNITY_MCP_PACKAGE_ROOT);
+  }
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(scriptDir, '..');
+}
+
+export function resolvePrebuiltRoot(packageRoot, env = process.env) {
+  if (env.UNITY_MCP_PREBUILT_DIR) {
+    return path.resolve(env.UNITY_MCP_PREBUILT_DIR);
+  }
+  return path.join(packageRoot, 'prebuilt', 'better-sqlite3');
+}
+
+export function resolveBetterSqlite3Root(packageRoot, env = process.env) {
+  if (env.UNITY_MCP_BETTER_SQLITE3_ROOT) {
+    return path.resolve(env.UNITY_MCP_BETTER_SQLITE3_ROOT);
+  }
+  try {
+    const req = createRequire(path.join(packageRoot, 'package.json'));
+    const pkgPath = req.resolve('better-sqlite3/package.json');
+    return path.dirname(pkgPath);
+  } catch {
+    return path.join(packageRoot, 'node_modules', 'better-sqlite3');
+  }
+}
+
+export function resolvePrebuiltBindingPath(prebuiltRoot, platformKey) {
+  if (!prebuiltRoot || !platformKey) return null;
+  return path.join(prebuiltRoot, platformKey, 'better_sqlite3.node');
+}
+
+export function resolveInstalledBindingPath(moduleRoot) {
+  return path.join(moduleRoot, 'build', 'Release', 'better_sqlite3.node');
+}
+
+export function ensureBinExecutable({ packageRoot, env = process.env, logger = console } = {}) {
+  if (parseEnvFlag(env.UNITY_MCP_SKIP_BIN_CHMOD)) return false;
+  const binPath = path.join(packageRoot, 'bin', 'unity-mcp-server.js');
+  try {
+    if (fs.existsSync(binPath)) {
+      fs.chmodSync(binPath, 0o755);
+      logger.info(`[ensure-better-sqlite3] chmod +x ${binPath}`);
+      return true;
+    }
+  } catch (err) {
+    logger.warn(
+      `[ensure-better-sqlite3] Failed to chmod ${binPath}: ${err?.message || String(err)}`
+    );
+  }
+  return false;
+}
+
+export function ensureBetterSqlite3({
+  env = process.env,
+  logger = console,
+  packageRoot,
+  prebuiltRoot,
+  moduleRoot,
+  platform,
+  arch,
+  nodeVersion,
+  nodeAbi
+} = {}) {
+  const skipNative = parseEnvFlag(env.UNITY_MCP_SKIP_NATIVE_BUILD);
+  const forceNative = parseEnvFlag(env.UNITY_MCP_FORCE_NATIVE);
+
+  const resolvedPackageRoot = packageRoot || resolvePackageRoot(env);
+  const resolvedPrebuiltRoot = prebuiltRoot || resolvePrebuiltRoot(resolvedPackageRoot, env);
+  const resolvedModuleRoot = moduleRoot || resolveBetterSqlite3Root(resolvedPackageRoot, env);
+
+  if (skipNative) {
+    logger.info('[ensure-better-sqlite3] Native preload skipped (UNITY_MCP_SKIP_NATIVE_BUILD).');
+    ensureBinExecutable({ packageRoot: resolvedPackageRoot, env, logger });
+    return { action: 'skip' };
+  }
+
+  if (!fs.existsSync(resolvedModuleRoot)) {
+    const message = `[ensure-better-sqlite3] better-sqlite3 module not found at ${resolvedModuleRoot}`;
+    if (forceNative) {
+      throw new Error(message);
+    }
+    logger.warn(message);
+    ensureBinExecutable({ packageRoot: resolvedPackageRoot, env, logger });
+    return { action: 'no-module' };
+  }
+
+  const runtimeInfo = resolveRuntimeInfo({
+    env,
+    platform,
+    arch,
+    nodeVersion,
+    nodeAbi
+  });
+
+  const platformKey = buildPlatformKey(runtimeInfo);
+  if (!platformKey) {
+    const message = '[ensure-better-sqlite3] Unable to resolve platform key';
+    if (forceNative) throw new Error(message);
+    logger.warn(message);
+    ensureBinExecutable({ packageRoot: resolvedPackageRoot, env, logger });
+    return { action: 'fallback' };
+  }
+
+  const prebuiltPath = resolvePrebuiltBindingPath(resolvedPrebuiltRoot, platformKey);
+  if (!prebuiltPath || !fs.existsSync(prebuiltPath)) {
+    const message = `[ensure-better-sqlite3] Prebuilt binary not found for ${platformKey}`;
+    if (forceNative) throw new Error(message);
+    logger.info(message);
+    ensureBinExecutable({ packageRoot: resolvedPackageRoot, env, logger });
+    return { action: 'fallback', platformKey, prebuiltPath };
+  }
+
+  const destPath = resolveInstalledBindingPath(resolvedModuleRoot);
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  fs.copyFileSync(prebuiltPath, destPath);
+  logger.info(`[ensure-better-sqlite3] Installed prebuilt ${platformKey} -> ${destPath}`);
+
+  ensureBinExecutable({ packageRoot: resolvedPackageRoot, env, logger });
+  return { action: 'copied', platformKey, prebuiltPath, destPath };
+}
+
+function isCliInvocation() {
+  if (!process.argv[1]) return false;
+  const invoked = path.resolve(process.argv[1]);
+  const current = path.resolve(fileURLToPath(import.meta.url));
+  return invoked === current;
+}
+
+if (isCliInvocation()) {
+  try {
+    ensureBetterSqlite3();
+  } catch (err) {
+    const message = err?.message || String(err);
+    console.error(`[ensure-better-sqlite3] ${message}`);
+    process.exit(1);
+  }
+}

package/scripts/run-non-unity-tests.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, '..');
+const integrationRoot = path.join(repoRoot, 'tests', 'integration');
+
+const curatedUnitTests = [
+  'tests/unit/core/codeIndex.test.js',
+  'tests/unit/core/config.test.js',
+  'tests/unit/core/indexWatcher.test.js',
+  'tests/unit/core/projectInfo.test.js',
+  'tests/unit/core/server.test.js',
+  'tests/unit/handlers/script/CodeIndexStatusToolHandler.test.js'
+];
+
+function collectIntegrationTests(dir) {
+  const entries = fs.existsSync(dir) ? fs.readdirSync(dir, { withFileTypes: true }) : [];
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectIntegrationTests(full));
+    } else if (entry.isFile() && entry.name.endsWith('.test.js')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+function detectUnityDependency(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return /UnityConnection|connect\(\)\s*=>\s*new UnityConnection/i.test(content);
+  } catch {
+    return false;
+  }
+}
+
+const allIntegrationTests = collectIntegrationTests(integrationRoot);
+const nonUnityTests = [];
+const unityTests = [];
+
+for (const absPath of allIntegrationTests) {
+  const relPath = path.relative(repoRoot, absPath);
+  if (detectUnityDependency(absPath)) {
+    unityTests.push(relPath);
+  } else {
+    nonUnityTests.push(relPath);
+  }
+}
+
+if (nonUnityTests.length === 0) {
+  console.warn('[tests] No non-Unity integration tests found.');
+}
+
+if (unityTests.length > 0) {
+  console.log('[tests] Skipping Unity-dependent integration suites in this run:');
+  for (const rel of unityTests) {
+    console.log(`  - ${rel}`);
+  }
+  console.log(
+    '[tests] These suites are executed via `npm run test:unity --workspace=mcp-server` when a Unity Editor is available.'
+  );
+}
+
+const testTargets = [...curatedUnitTests, ...nonUnityTests];
+
+const child = spawn(process.execPath, ['--test', ...testTargets], {
+  stdio: 'inherit',
+  cwd: repoRoot
+});
+
+child.on('exit', code => {
+  process.exit(code ?? 1);
+});

package/scripts/simulate-code-index-status.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { CodeIndexBuildToolHandler } from '../src/handlers/script/CodeIndexBuildToolHandler.js';
+import { CodeIndexStatusToolHandler } from '../src/handlers/script/CodeIndexStatusToolHandler.js';
+import { ProjectInfoProvider } from '../src/core/projectInfo.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const argv = process.argv.slice(2);
+const options = {
+  throttleMs: 50,
+  pollMs: 500,
+  reset: false,
+  delayStartMs: 0
+};
+
+for (const arg of argv) {
+  if (arg.startsWith('--throttle=')) {
+    options.throttleMs = Math.max(0, Number(arg.split('=')[1] || 0));
+  } else if (arg.startsWith('--poll=')) {
+    options.pollMs = Math.max(100, Number(arg.split('=')[1] || 500));
+  } else if (arg.startsWith('--delayStart=')) {
+    options.delayStartMs = Math.max(0, Number(arg.split('=')[1] || 0));
+  } else if (arg === '--reset' || arg === '--clean') {
+    options.reset = true;
+  } else if (arg === '--help' || arg === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+}
+
+function printHelp() {
+  console.log(`Usage: node scripts/simulate-code-index-status.mjs [--throttle=MS] [--poll=MS] [--reset]
+
+Options:
+  --throttle=MS  Delay (ms) after each file during build to keep job running (default: 50)
+  --poll=MS      Poll interval for code_index_status (default: 500)
+  --delayStart=MS  Delay (ms) before processing begins (default: 0)
+  --reset        Delete existing code index database before running
+`);
+}
+
+const mockUnityConnection = {
+  isConnected() {
+    return false;
+  },
+  sendCommand() {
+    throw new Error('Unity connection not available in simulation');
+  }
+};
+
+const buildHandler = new CodeIndexBuildToolHandler(mockUnityConnection);
+const statusHandler = new CodeIndexStatusToolHandler(mockUnityConnection);
+const projectInfo = new ProjectInfoProvider(mockUnityConnection);
+
+(async () => {
+  const info = await projectInfo.get();
+  const dbDir = path.resolve(info.codeIndexRoot);
+  if (options.reset) {
+    try {
+      for (const file of ['code-index.db', 'code-index.db-shm', 'code-index.db-wal']) {
+        const target = path.join(dbDir, file);
+        if (fs.existsSync(target)) fs.unlinkSync(target);
+      }
+      console.log('[simulate] Existing code index removed.');
+    } catch (err) {
+      console.error('[simulate] Failed to clean code index:', err.message);
+    }
+  }
+
+  console.log('[simulate] Starting code_index_build with throttleMs =', options.throttleMs);
+  const buildResult = await buildHandler.execute({
+    throttleMs: options.throttleMs,
+    delayStartMs: options.delayStartMs
+  });
+  console.log('[simulate] Job ID:', buildResult.jobId);
+
+  const interval = setInterval(async () => {
+    try {
+      const status = await statusHandler.execute({});
+      const job = status.index?.buildJob;
+      const line = {
+        time: new Date().toISOString(),
+        ready: status.index?.ready,
+        rows: status.index?.rows,
+        jobStatus: job?.status ?? null,
+        processed: job?.progress?.processed ?? null,
+        total: job?.progress?.total ?? null
+      };
+      console.log('[status]', JSON.stringify(line));
+
+      if (!job || job.status !== 'running') {
+        clearInterval(interval);
+        console.log('[simulate] Build finished.');
+        process.exit(0);
+      }
+    } catch (err) {
+      console.error('[status]', err.message);
+    }
+  }, options.pollMs);
+})();

package/scripts/sync-unity-package-version.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * Sync Unity Package version with mcp-server version
+ * Called by release-please via extra-files or manual invocation
+ *
+ * Usage: node sync-unity-package-version.js <version>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Get version from command line argument
+const version = process.argv[2];
+
+if (!version) {
+  console.error('Error: Version argument is required');
+  console.error('Usage: node sync-unity-package-version.js <version>');
+  process.exit(1);
+}
+
+// Resolve Unity Package path (mcp-server and UnityMCPServer are siblings)
+const unityPackageJsonPath = path.join(
+  __dirname,
+  '../../UnityMCPServer/Packages/unity-mcp-server/package.json'
+);
+
+try {
+  // Read Unity package.json
+  const packageJsonContent = fs.readFileSync(unityPackageJsonPath, 'utf8');
+  const packageJson = JSON.parse(packageJsonContent);
+
+  // Update version
+  packageJson.version = version;
+
+  // Write back with 2-space indentation and trailing newline
+  const updatedContent = JSON.stringify(packageJson, null, 2) + '\n';
+  fs.writeFileSync(unityPackageJsonPath, updatedContent, 'utf8');
+
+  console.log(`Unity Package version synced to ${version}`);
+  process.exit(0);
+} catch (error) {
+  console.error(`Error: Failed to sync Unity Package version`);
+  console.error(error.message);
+  process.exit(1);
+}

package/src/core/config.js

@@ -153,7 +153,7 @@ const baseConfig = {
 
   // LSP client defaults
   lsp: {
-    requestTimeoutMs: 60000
+    requestTimeoutMs: 120000
   },
 
   // Indexing (code index) settings

package/src/core/unityConnection.js

@@ -649,10 +649,9 @@ function wrapUnityConnectError(error, host, port) {
 }
 
 function buildUnityConnectionHint(_host, _port) {
-  const configPath = config.__configPath || '.unity/config.json';
   return (
     `Start Unity Editor and ensure the Unity MCP package is running (TCP listener). ` +
-    `Check ${configPath} (unity.mcpHost/unity.port). ` +
-    `If using WSL2/Docker → Windows Unity, set unity.mcpHost=host.docker.internal.`
+    `Check UNITY_MCP_MCP_HOST / UNITY_MCP_PORT and Unity Project Settings (Host/Port). ` +
+    `If using WSL2/Docker → Windows Unity, set UNITY_MCP_MCP_HOST=host.docker.internal.`
   );
 }

package/src/handlers/script/ScriptEditSnippetToolHandler.js

@@ -30,6 +30,11 @@ 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,
@@ -114,6 +119,7 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
     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;
@@ -142,7 +148,13 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
     }
 
     if (working === original) {
-      return this.#buildResponse({ preview, results, original, updated: working });
+      return this.#buildResponse({
+        preview,
+        results,
+        original,
+        updated: working,
+        validationSkipped: skipValidation
+      });
     }
 
     // Pre-syntax check on edited content before LSP validation
@@ -154,19 +166,30 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
       );
     }
 
-    const 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}`);
+    // LSP validation (skip if skipValidation=true for large files)
+    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}`);
+      }
     }
 
     if (!preview) {
       await fs.writeFile(absolute, working, 'utf8');
     }
 
-    return this.#buildResponse({ preview, results, original, updated: working, diagnostics });
+    return this.#buildResponse({
+      preview,
+      results,
+      original,
+      updated: working,
+      diagnostics,
+      validationSkipped: skipValidation
+    });
   }
 
   #resolvePaths(info, rawPath) {
@@ -279,12 +302,20 @@ export class ScriptEditSnippetToolHandler extends BaseToolHandler {
     return await this.lsp.validateText(relative, updatedText);
   }
 
-  #buildResponse({ preview, results, original, updated, diagnostics = [] }) {
+  #buildResponse({
+    preview,
+    results,
+    original,
+    updated,
+    diagnostics = [],
+    validationSkipped = false
+  }) {
     const out = {
       success: true,
       applied: !preview,
       results,
       diagnostics,
+      validationSkipped,
       beforeHash: this.#hash(original),
       afterHash: this.#hash(updated)
     };