@akiojin/unity-mcp-server 2.44.1 → 2.45.0

package/README.md

@@ -315,18 +315,22 @@ Unity MCP Server uses the following components for code indexing and analysis:
 
 | Component | Purpose | Distribution | Notes |
 |-----------|---------|--------------|-------|
-| **sql.js** | Code index database | npm dependency | Pure JS/WASM, no native compilation |
+| **fast-sql** | Code index database | npm dependency | Hybrid backend: better-sqlite3 (native) or sql.js (WASM) |
 | **csharp-lsp** | C# symbol analysis | Downloaded on first use | ~80 MB per platform |
 
-#### Why sql.js?
+#### Why fast-sql?
 
-We use **sql.js** (pure JavaScript/WebAssembly SQLite) for the code index database:
+We use **fast-sql** (hybrid SQLite library) for the code index database:
 
-- **Zero native compilation**: Works immediately via `npx` without build tools
-- **Cross-platform**: Same code runs on all Node.js platforms
-- **No installation delays**: Avoids 30+ second native module compilation timeouts
+- **Optimal performance**: Uses better-sqlite3 (native) when available for ~34x faster queries
+- **npx compatible**: Falls back to sql.js (WASM) when native bindings unavailable
+- **Zero native compilation required**: Works immediately via `npx` without build tools
+- **Cross-platform**: Automatic backend selection based on environment
 
-**Trade-off**: sql.js is 1.5-5x slower than native SQLite (better-sqlite3), but this is acceptable for code index operations which are infrequent.
+**Performance comparison** (better-sqlite3 vs sql.js):
+- 50K inserts: 29ms vs 53ms (1.8x faster)
+- 1000 queries: 0.34μs vs 11.78μs (34x faster)
+- LIKE search: 2.5ms vs 7ms (2.8x faster)
 
 #### csharp-lsp Distribution
 
@@ -338,14 +342,14 @@ We use **sql.js** (pure JavaScript/WebAssembly SQLite) for the code index databa
 
 #### Supported Platforms
 
-| Platform | sql.js | csharp-lsp |
-|----------|--------|------------|
-| Linux x64 | ✅ Built-in | ✅ Downloaded (~79 MB) |
-| Linux arm64 | ✅ Built-in | ✅ Downloaded (~86 MB) |
-| macOS x64 | ✅ Built-in | ✅ Downloaded (~80 MB) |
-| macOS arm64 (Apple Silicon) | ✅ Built-in | ✅ Downloaded (~86 MB) |
-| Windows x64 | ✅ Built-in | ✅ Downloaded (~80 MB) |
-| Windows arm64 | ✅ Built-in | ✅ Downloaded (~85 MB) |
+| Platform | fast-sql | csharp-lsp |
+|----------|----------|------------|
+| Linux x64 | ✅ Native (better-sqlite3) | ✅ Downloaded (~79 MB) |
+| Linux arm64 | ✅ Native (better-sqlite3) | ✅ Downloaded (~86 MB) |
+| macOS x64 | ✅ Native (better-sqlite3) | ✅ Downloaded (~80 MB) |
+| macOS arm64 (Apple Silicon) | ✅ Native (better-sqlite3) | ✅ Downloaded (~86 MB) |
+| Windows x64 | ✅ Native (better-sqlite3) | ✅ Downloaded (~80 MB) |
+| Windows arm64 | ✅ WASM fallback (sql.js) | ✅ Downloaded (~85 MB) |
 
 #### Storage Locations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "2.44.1",
+  "version": "2.45.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",
@@ -50,7 +50,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.3",
     "find-up": "^6.3.0",
-    "sql.js": "^1.13.0"
+    "@akiojin/fast-sql": "file:../packages/fast-sql"
   },
   "engines": {
     "node": ">=18 <23"

package/src/core/codeIndex.js

@@ -3,10 +3,9 @@ import path from 'path';
 import { ProjectInfoProvider } from './projectInfo.js';
 import { logger } from './config.js';
 
-// sql.js helper: execute query and return results (wrapper to avoid hook false positive)
+// fast-sql helper: execute query and return results
 function querySQL(db, sql) {
-  const fn = db['ex' + 'ec'].bind(db);
-  return fn(sql);
+  return db.execSql(sql);
 }
 
 // Shared driver availability state across CodeIndex instances
@@ -43,9 +42,9 @@ export class CodeIndex {
     }
     if (this._SQL) return true;
     try {
-      // Dynamic import sql.js (pure JavaScript/WASM, no native bindings)
-      const initSqlJs = (await import('sql.js')).default;
-      this._SQL = await initSqlJs();
+      // Dynamic import fast-sql (hybrid backend: better-sqlite3 or sql.js fallback)
+      const initFastSql = (await import('@akiojin/fast-sql')).default;
+      this._SQL = await initFastSql();
       sharedConnections.SQL = this._SQL;
       driverStatus.available = true;
       driverStatus.error = null;
@@ -53,7 +52,7 @@ export class CodeIndex {
     } catch (e) {
       this.disabled = true;
       const errMsg = e && typeof e === 'object' && 'message' in e ? e.message : String(e);
-      this.disableReason = `sql.js unavailable: ${errMsg}. Code index features are disabled.`;
+      this.disableReason = `fast-sql unavailable: ${errMsg}. Code index features are disabled.`;
       driverStatus.available = false;
       driverStatus.error = this.disableReason;
       this._logDisable(this.disableReason);
@@ -102,12 +101,12 @@ export class CodeIndex {
 
   /**
    * Save in-memory database to file
-   * sql.js requires explicit save (unlike better-sqlite3 which auto-persists)
+   * fast-sql requires explicit save when using sql.js backend
    */
   _saveToFile() {
     if (!this.db || !this.dbPath) return;
     try {
-      const data = this.db.export();
+      const data = this.db.exportDb();
       const buffer = Buffer.from(data);
       fs.writeFileSync(this.dbPath, buffer);
     } catch (e) {
@@ -130,7 +129,7 @@ export class CodeIndex {
 
   _initSchema() {
     if (!this.db) return;
-    // sql.js doesn't support WAL mode (in-memory), skip PRAGMA journal_mode
+    // fast-sql applies optimal PRAGMAs automatically
     this.db.run(`
       CREATE TABLE IF NOT EXISTS meta (
         key TEXT PRIMARY KEY,
@@ -171,7 +170,7 @@ export class CodeIndex {
 
   async clearAndLoad(symbols) {
     const db = await this.open();
-    if (!db) throw new Error('CodeIndex is unavailable (sql.js not loaded)');
+    if (!db) throw new Error('CodeIndex is unavailable (fast-sql not loaded)');
 
     db.run('BEGIN TRANSACTION');
     try {

package/src/core/indexBuildWorkerPool.js

@@ -12,7 +12,7 @@ const __dirname = path.dirname(__filename);
  *
  * This class manages Worker Threads that execute index builds in a separate
  * thread, preventing the main Node.js event loop from being blocked by
- * sql.js database operations.
+ * fast-sql database operations (hybrid backend with better-sqlite3 or sql.js fallback).
  *
  * Requirements:
  * - FR-056: Execute index build in Worker Thread

package/src/core/workers/indexBuildWorker.js

@@ -3,7 +3,7 @@
  *
  * This script runs in a separate thread and performs the heavy lifting of
  * index builds: file scanning, LSP document symbol requests, and SQLite
- * database operations (using sql.js - pure JS/WASM, no native bindings).
+ * database operations (using fast-sql - hybrid backend with better-sqlite3 or sql.js fallback).
  * By running in a Worker Thread, these operations don't block the main event loop.
  *
  * Communication with main thread:
@@ -16,22 +16,20 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
-// sql.js helper: run SQL statement (wrapper to avoid hook false positive on "exec")
+// fast-sql helper: run SQL statement
 function runSQL(db, sql) {
   return db.run(sql);
 }
 
-// sql.js helper: execute query and return results
+// fast-sql helper: execute query and return results
 function querySQL(db, sql) {
-  // sql.js exec returns array of result sets
-  const fn = db['ex' + 'ec'].bind(db);
-  return fn(sql);
+  return db.execSql(sql);
 }
 
-// Save sql.js database to file
+// Save fast-sql database to file
 function saveDatabase(db, dbPath) {
   try {
-    const data = db.export();
+    const data = db.exportDb();
     const buffer = Buffer.from(data);
     fs.writeFileSync(dbPath, buffer);
   } catch (e) {
@@ -186,13 +184,13 @@ async function runBuild() {
   let db = null;
 
   try {
-    // Dynamic import sql.js in worker thread (pure JS/WASM, no native bindings)
+    // Dynamic import fast-sql in worker thread (hybrid: better-sqlite3 or sql.js fallback)
     let SQL;
     try {
-      const initSqlJs = (await import('sql.js')).default;
-      SQL = await initSqlJs();
+      const initFastSql = (await import('@akiojin/fast-sql')).default;
+      SQL = await initFastSql();
     } catch (e) {
-      throw new Error(`sql.js unavailable in worker: ${e.message}`);
+      throw new Error(`fast-sql unavailable in worker: ${e.message}`);
     }
 
     // Open or create database
@@ -203,7 +201,7 @@ async function runBuild() {
       db = new SQL.Database();
     }
 
-    // Initialize schema if needed (sql.js doesn't support WAL mode)
+    // Initialize schema if needed (fast-sql applies optimal PRAGMAs automatically)
     runSQL(
       db,
       `

package/src/handlers/script/CodeIndexStatusToolHandler.js

@@ -39,13 +39,13 @@ export class CodeIndexStatusToolHandler extends BaseToolHandler {
         coverage: 0,
         message:
           this.codeIndex.disableReason ||
-          'Code index is disabled because sql.js could not be loaded. The server will continue without the symbol index.',
+          'Code index is disabled because fast-sql could not be loaded. The server will continue without the symbol index.',
         remediation:
-          'Ensure sql.js is installed by running "npm install sql.js". After installing, restart unity-mcp-server.',
+          'Ensure fast-sql is properly installed. After reinstalling dependencies, restart unity-mcp-server.',
         index: {
           ready: false,
           disabled: true,
-          reason: this.codeIndex.disableReason || 'sql.js unavailable; code index is disabled'
+          reason: this.codeIndex.disableReason || 'fast-sql unavailable; code index is disabled'
         }
       };
     }

package/src/handlers/script/ScriptRefsFindToolHandler.js

@@ -94,7 +94,7 @@ export class ScriptRefsFindToolHandler extends BaseToolHandler {
           this.index.disableReason ||
           'Code index is disabled because the SQLite driver could not be loaded.',
         remediation:
-          'Ensure sql.js is installed by running "npm install sql.js". After installing, restart unity-mcp-server.'
+          'Ensure fast-sql is properly installed. After reinstalling dependencies, restart unity-mcp-server.'
       };
     }
 

package/src/handlers/script/ScriptSymbolFindToolHandler.js

@@ -61,7 +61,7 @@ export class ScriptSymbolFindToolHandler extends BaseToolHandler {
           this.index.disableReason ||
           'Code index is disabled because the SQLite driver could not be loaded.',
         remediation:
-          'Ensure sql.js is installed by running "npm install sql.js". After installing, restart unity-mcp-server.'
+          'Ensure fast-sql is properly installed. After reinstalling dependencies, restart unity-mcp-server.'
       };
     }