@akiojin/unity-mcp-server 2.44.0 → 2.45.0

package/README.md

@@ -309,64 +309,50 @@ Add to your `claude_desktop_config.json`:
 
 ## Architecture
 
-### Native Dependencies
+### Dependencies
 
-Unity MCP Server uses platform-specific native binaries for performance-critical operations:
+Unity MCP Server uses the following components for code indexing and analysis:
 
-| Component | Purpose | Distribution | Size per platform |
-|-----------|---------|--------------|-------------------|
-| **better-sqlite3** | Code index database | Bundled in npm package | ~3-5 MB |
-| **csharp-lsp** | C# symbol analysis | Downloaded on first use | ~80 MB |
+| Component | Purpose | Distribution | Notes |
+|-----------|---------|--------------|-------|
+| **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 better-sqlite3 over JavaScript-based SQLite?
+#### Why fast-sql?
 
-We chose **better-sqlite3** (native C binding) instead of JavaScript-based alternatives like **sql.js** for the following reasons:
+We use **fast-sql** (hybrid SQLite library) for the code index database:
 
-| Aspect | better-sqlite3 (native) | sql.js (WASM/JS) |
-|--------|------------------------|------------------|
-| **Performance** | 10-100x faster for bulk operations | Slower due to WASM overhead |
-| **Memory** | Efficient native memory management | Higher memory usage, GC pressure |
-| **Synchronous API** | Native sync operations, ideal for MCP | Async-only, adds complexity |
-| **Startup time** | Instant module load | ~100-500ms WASM initialization |
-| **Database size** | Handles large indexes efficiently | Performance degrades with size |
+- **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
 
-The code index database may contain tens of thousands of symbols from Unity projects. Native SQLite provides the performance characteristics needed for responsive symbol searches and incremental updates.
+**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)
 
-**Trade-off**: Requires platform-specific binaries (bundled for all supported platforms), while sql.js would work everywhere but with unacceptable performance for our use case.
+#### csharp-lsp Distribution
 
-#### Why Different Distribution Methods?
-
-**better-sqlite3 (bundled)**:
-
-- Small size (~3-5 MB per platform)
-- Prevents MCP server initialization timeout during `npm install` compilation
-- Code index features disabled with clear error message if native binding fails
-
-**csharp-lsp (downloaded)**:
+**csharp-lsp (downloaded on first use)**:
 
 - Large size (~80 MB per platform, ~480 MB for all 6 platforms)
-- Too large to bundle in npm package (would increase package size 100x)
+- Too large to bundle in npm package
 - Downloaded from GitHub Release on first use of script editing tools
 
 #### Supported Platforms
 
-| Platform | better-sqlite3 | csharp-lsp |
-|----------|---------------|------------|
-| Linux x64 | ✅ Bundled | ✅ Downloaded (~79 MB) |
-| Linux arm64 | ✅ Bundled | ✅ Downloaded (~86 MB) |
-| macOS x64 | ✅ Bundled | ✅ Downloaded (~80 MB) |
-| macOS arm64 (Apple Silicon) | ✅ Bundled | ✅ Downloaded (~86 MB) |
-| Windows x64 | ✅ Bundled | ✅ Downloaded (~80 MB) |
-| Windows arm64 | ✅ Bundled | ✅ Downloaded (~85 MB) |
-
-#### Fallback Behavior
-
-- **better-sqlite3**: No fallback; code index features disabled with clear error if native binding unavailable
-- **csharp-lsp**: No fallback; script editing features require the native binary
+| 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
 
-- **better-sqlite3**: `<package>/prebuilt/better-sqlite3/<platform>/`
 - **csharp-lsp**: `~/.unity/tools/csharp-lsp/<rid>/`
 - **Code index database**: `<workspace>/.unity/cache/code-index/code-index.db`
 
@@ -422,23 +408,6 @@ npm uninstall -g @akiojin/unity-mcp-server
 npm install -g @akiojin/unity-mcp-server
 ```
 
-### Native Module (better-sqlite3) Issues
-
-If you encounter errors related to `better-sqlite3` during installation or startup:
-
-**Symptom**: Installation fails with `node-gyp` errors, or startup shows "Could not locate the bindings file."
-
-**Cause**: The package includes prebuilt native binaries for supported platforms (Linux/macOS/Windows × x64/arm64 × Node 18/20/22). If your platform isn't supported or the prebuilt fails to load, code index features will be disabled.
-
-**Solution - Force native rebuild**:
-
-```bash
-# Force rebuild from source (requires build tools)
-UNITY_MCP_FORCE_NATIVE=1 npm install @akiojin/unity-mcp-server
-```
-
-**Note**: If native binding is unavailable, code index features (`code_index_build`, `code_index_status`, `script_symbol_find`, etc.) will return clear error messages indicating the feature is disabled. Other MCP server features continue to work normally.
-
 ### MCP Client Shows "Capabilities: none"
 
 If your MCP client (Claude Code, Cursor, etc.) shows "Capabilities: none" despite successful connection:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akiojin/unity-mcp-server",
-  "version": "2.44.0",
+  "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",
@@ -20,16 +20,14 @@
     "test:watch": "node --watch --test tests/unit/**/*.test.js",
     "test:watch:all": "node --watch --test tests/**/*.test.js",
     "test:performance": "node --test tests/performance/*.test.js",
-    "test:ci": "CI=true NODE_ENV=test 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/handlers/script/CodeIndexStatusToolHandler.test.js tests/unit/scripts/ensure-better-sqlite3.test.js",
+    "test:ci": "CI=true NODE_ENV=test 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/handlers/script/CodeIndexStatusToolHandler.test.js",
     "test:ci:coverage": "c8 --reporter=lcov --reporter=text 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/handlers/script/CodeIndexStatusToolHandler.test.js",
     "test:ci:all": "c8 --reporter=lcov node --test tests/unit/**/*.test.js",
     "simulate:code-index": "node scripts/simulate-code-index-status.mjs",
     "test:verbose": "VERBOSE_TEST=true node --test tests/**/*.test.js",
     "prepare": "cd .. && husky || true",
-    "prebuild:better-sqlite3": "node scripts/prebuild-better-sqlite3.mjs",
-    "prebuilt:manifest": "node scripts/generate-prebuilt-manifest.mjs",
-    "prepublishOnly": "npm run test:ci && npm run prebuilt:manifest",
-    "postinstall": "node scripts/ensure-better-sqlite3.mjs && chmod +x bin/unity-mcp-server.js || true",
+    "prepublishOnly": "npm run test:ci",
+    "postinstall": "chmod +x bin/unity-mcp-server.js || true",
     "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 || exit 0",
     "test:unity": "node tests/run-unity-integration.mjs",
     "test:nounity": "npm run test:integration",
@@ -51,8 +49,8 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.3",
-    "better-sqlite3": "^9.4.3",
-    "find-up": "^6.3.0"
+    "find-up": "^6.3.0",
+    "@akiojin/fast-sql": "file:../packages/fast-sql"
   },
   "engines": {
     "node": ">=18 <23"
@@ -69,8 +67,6 @@
   "files": [
     "src/",
     "bin/",
-    "scripts/ensure-better-sqlite3.mjs",
-    "prebuilt/",
     "README.md",
     "LICENSE"
   ],

package/src/core/codeIndex.js

@@ -3,6 +3,11 @@ import path from 'path';
 import { ProjectInfoProvider } from './projectInfo.js';
 import { logger } from './config.js';
 
+// fast-sql helper: execute query and return results
+function querySQL(db, sql) {
+  return db.execSql(sql);
+}
+
 // Shared driver availability state across CodeIndex instances
 const driverStatus = {
   available: null,
@@ -12,21 +17,21 @@ const driverStatus = {
 
 // Shared DB connections (singleton pattern for concurrent access)
 const sharedConnections = {
-  writeDb: null,
-  readDb: null,
+  db: null,
   dbPath: null,
-  schemaInitialized: false
+  schemaInitialized: false,
+  SQL: null // sql.js factory
 };
 
 export class CodeIndex {
   constructor(unityConnection) {
     this.unityConnection = unityConnection;
     this.projectInfo = new ProjectInfoProvider(unityConnection);
-    this.db = null; // legacy reference, points to writeDb
+    this.db = null;
     this.dbPath = null;
-    this.disabled = false; // set true if better-sqlite3 is unavailable
+    this.disabled = false;
     this.disableReason = null;
-    this._Database = null;
+    this._SQL = null;
   }
 
   async _ensureDriver() {
@@ -35,18 +40,19 @@ export class CodeIndex {
       this.disableReason = this.disableReason || driverStatus.error;
       return false;
     }
-    if (this._Database) return true;
+    if (this._SQL) return true;
     try {
-      // Dynamic import to avoid hard failure when native binding is missing
-      const mod = await import('better-sqlite3');
-      this._Database = mod.default || mod;
+      // 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;
       return true;
     } catch (e) {
-      // No fallback - fail fast with clear error
       this.disabled = true;
-      this.disableReason = `better-sqlite3 native binding unavailable: ${e?.message || e}. Code index features are disabled.`;
+      const errMsg = e && typeof e === 'object' && 'message' in e ? e.message : String(e);
+      this.disableReason = `fast-sql unavailable: ${errMsg}. Code index features are disabled.`;
       driverStatus.available = false;
       driverStatus.error = this.disableReason;
       this._logDisable(this.disableReason);
@@ -57,35 +63,33 @@ export class CodeIndex {
   async open() {
     if (this.db) return this.db;
     const ok = await this._ensureDriver();
-    if (!ok) return null; // index disabled
+    if (!ok) return null;
     const info = await this.projectInfo.get();
     const dir = info.codeIndexRoot;
     fs.mkdirSync(dir, { recursive: true });
     const dbPath = path.join(dir, 'code-index.db');
     this.dbPath = dbPath;
 
-    // Use shared connections for all CodeIndex instances
-    if (sharedConnections.writeDb && sharedConnections.dbPath === dbPath) {
-      this.db = sharedConnections.writeDb;
+    // Use shared connection for all CodeIndex instances
+    if (sharedConnections.db && sharedConnections.dbPath === dbPath) {
+      this.db = sharedConnections.db;
       return this.db;
     }
 
     try {
-      if (this._Database) {
-        // Create write connection (default)
-        sharedConnections.writeDb = new this._Database(dbPath);
-        sharedConnections.dbPath = dbPath;
-        this.db = sharedConnections.writeDb;
-
-        // Create separate read-only connection for concurrent reads
-        // readonly: true allows reads even while write transaction is active
-        sharedConnections.readDb = new this._Database(dbPath, { readonly: true });
+      // Load existing database file if exists, otherwise create new
+      if (fs.existsSync(dbPath)) {
+        const buffer = fs.readFileSync(dbPath);
+        this.db = new this._SQL.Database(buffer);
       } else {
-        throw new Error('No database driver available');
+        this.db = new this._SQL.Database();
       }
+      sharedConnections.db = this.db;
+      sharedConnections.dbPath = dbPath;
     } catch (e) {
       this.disabled = true;
-      this.disableReason = e?.message || 'Failed to open code index database';
+      const errMsg = e && typeof e === 'object' && 'message' in e ? e.message : String(e);
+      this.disableReason = errMsg || 'Failed to open code index database';
       driverStatus.available = false;
       driverStatus.error = this.disableReason;
       this._logDisable(this.disableReason);
@@ -96,36 +100,50 @@ export class CodeIndex {
   }
 
   /**
-   * Get read-only DB connection for queries (non-blocking during writes)
-   * Falls back to write connection if read connection unavailable
+   * Save in-memory database to file
+   * fast-sql requires explicit save when using sql.js backend
    */
-  _getReadDb() {
-    return sharedConnections.readDb || this.db;
+  _saveToFile() {
+    if (!this.db || !this.dbPath) return;
+    try {
+      const data = this.db.exportDb();
+      const buffer = Buffer.from(data);
+      fs.writeFileSync(this.dbPath, buffer);
+    } catch (e) {
+      const errMsg = e && typeof e === 'object' && 'message' in e ? e.message : String(e);
+      logger.warn(`[index] Failed to save database: ${errMsg}`);
+    }
   }
 
   _logDisable(reason) {
     if (driverStatus.logged) return;
     driverStatus.logged = true;
     try {
-      logger?.warn?.(`[index] code index disabled: ${reason}`);
-    } catch {}
+      if (logger && typeof logger.warn === 'function') {
+        logger.warn(`[index] code index disabled: ${reason}`);
+      }
+    } catch {
+      // Ignore logging errors
+    }
   }
 
   _initSchema() {
     if (!this.db) return;
-    const db = this.db;
-    db.exec(`
-      PRAGMA journal_mode=WAL;
-      PRAGMA busy_timeout=5000;
+    // fast-sql applies optimal PRAGMAs automatically
+    this.db.run(`
       CREATE TABLE IF NOT EXISTS meta (
         key TEXT PRIMARY KEY,
         value TEXT
-      );
+      )
+    `);
+    this.db.run(`
       CREATE TABLE IF NOT EXISTS files (
         path TEXT PRIMARY KEY,
         sig TEXT,
         updatedAt TEXT
-      );
+      )
+    `);
+    this.db.run(`
       CREATE TABLE IF NOT EXISTS symbols (
         path TEXT NOT NULL,
         name TEXT NOT NULL,
@@ -134,33 +152,36 @@ export class CodeIndex {
         namespace TEXT,
         line INTEGER,
         column INTEGER
-      );
-      CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
-      CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);
-      CREATE INDEX IF NOT EXISTS idx_symbols_path ON symbols(path);
+      )
     `);
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name)');
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind)');
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_symbols_path ON symbols(path)');
+    this._saveToFile();
   }
 
   async isReady() {
     const db = await this.open();
     if (!db) return false;
-    // Use read-only connection for non-blocking check
-    const readDb = this._getReadDb();
-    const row = readDb.prepare('SELECT COUNT(*) AS c FROM symbols').get();
-    return (row?.c || 0) > 0;
+    const result = querySQL(db, 'SELECT COUNT(*) AS c FROM symbols');
+    const count = result.length > 0 && result[0].values.length > 0 ? result[0].values[0][0] : 0;
+    return count > 0;
   }
 
   async clearAndLoad(symbols) {
     const db = await this.open();
-    if (!db) throw new Error('CodeIndex is unavailable (better-sqlite3 not installed)');
-    const insert = db.prepare(
-      'INSERT INTO symbols(path,name,kind,container,namespace,line,column) VALUES (?,?,?,?,?,?,?)'
-    );
-    const tx = db.transaction(rows => {
-      db.exec('DELETE FROM symbols');
-      db.exec('DELETE FROM files');
-      for (const r of rows) {
-        insert.run(
+    if (!db) throw new Error('CodeIndex is unavailable (fast-sql not loaded)');
+
+    db.run('BEGIN TRANSACTION');
+    try {
+      db.run('DELETE FROM symbols');
+      db.run('DELETE FROM files');
+
+      const stmt = db.prepare(
+        'INSERT INTO symbols(path,name,kind,container,namespace,line,column) VALUES (?,?,?,?,?,?,?)'
+      );
+      for (const r of symbols || []) {
+        stmt.run([
           r.path,
           r.name,
           r.kind,
@@ -168,14 +189,20 @@ export class CodeIndex {
           r.ns || r.namespace || null,
           r.line || null,
           r.column || null
-        );
+        ]);
       }
-      db.prepare('REPLACE INTO meta(key,value) VALUES (?,?)').run(
-        'lastIndexedAt',
-        new Date().toISOString()
-      );
-    });
-    tx(symbols || []);
+      stmt.free();
+
+      const metaStmt = db.prepare('REPLACE INTO meta(key,value) VALUES (?,?)');
+      metaStmt.run(['lastIndexedAt', new Date().toISOString()]);
+      metaStmt.free();
+
+      db.run('COMMIT');
+      this._saveToFile();
+    } catch (e) {
+      db.run('ROLLBACK');
+      throw e;
+    }
     return { total: symbols?.length || 0 };
   }
 
@@ -183,90 +210,127 @@ export class CodeIndex {
   async getFiles() {
     const db = await this.open();
     if (!db) return new Map();
-    // Use read-only connection for non-blocking read
-    const readDb = this._getReadDb();
-    const rows = readDb.prepare('SELECT path, sig FROM files').all();
+    const result = querySQL(db, 'SELECT path, sig FROM files');
     const map = new Map();
-    for (const r of rows) map.set(String(r.path), String(r.sig || ''));
+    if (result.length > 0) {
+      for (const row of result[0].values) {
+        map.set(String(row[0]), String(row[1] || ''));
+      }
+    }
     return map;
   }
 
   async upsertFile(pathStr, sig) {
     const db = await this.open();
     if (!db) return;
-    db.prepare('REPLACE INTO files(path,sig,updatedAt) VALUES (?,?,?)').run(
-      pathStr,
-      sig || '',
-      new Date().toISOString()
-    );
+    const stmt = db.prepare('REPLACE INTO files(path,sig,updatedAt) VALUES (?,?,?)');
+    stmt.run([pathStr, sig || '', new Date().toISOString()]);
+    stmt.free();
+    this._saveToFile();
   }
 
   async removeFile(pathStr) {
     const db = await this.open();
     if (!db) return;
-    const tx = db.transaction(p => {
-      db.prepare('DELETE FROM symbols WHERE path = ?').run(p);
-      db.prepare('DELETE FROM files WHERE path = ?').run(p);
-    });
-    tx(pathStr);
+    db.run('BEGIN TRANSACTION');
+    try {
+      const stmt1 = db.prepare('DELETE FROM symbols WHERE path = ?');
+      stmt1.run([pathStr]);
+      stmt1.free();
+
+      const stmt2 = db.prepare('DELETE FROM files WHERE path = ?');
+      stmt2.run([pathStr]);
+      stmt2.free();
+
+      db.run('COMMIT');
+      this._saveToFile();
+    } catch (e) {
+      db.run('ROLLBACK');
+      throw e;
+    }
   }
 
   async replaceSymbolsForPath(pathStr, rows) {
     const db = await this.open();
     if (!db) return;
-    const tx = db.transaction((p, list) => {
-      db.prepare('DELETE FROM symbols WHERE path = ?').run(p);
-      const insert = db.prepare(
+
+    db.run('BEGIN TRANSACTION');
+    try {
+      const delStmt = db.prepare('DELETE FROM symbols WHERE path = ?');
+      delStmt.run([pathStr]);
+      delStmt.free();
+
+      const insertStmt = db.prepare(
         'INSERT INTO symbols(path,name,kind,container,namespace,line,column) VALUES (?,?,?,?,?,?,?)'
       );
-      for (const r of list)
-        insert.run(
-          p,
+      for (const r of rows || []) {
+        insertStmt.run([
+          pathStr,
           r.name,
           r.kind,
           r.container || null,
           r.ns || r.namespace || null,
           r.line || null,
           r.column || null
-        );
-      db.prepare('REPLACE INTO meta(key,value) VALUES (?,?)').run(
-        'lastIndexedAt',
-        new Date().toISOString()
-      );
-    });
-    tx(pathStr, rows || []);
+        ]);
+      }
+      insertStmt.free();
+
+      const metaStmt = db.prepare('REPLACE INTO meta(key,value) VALUES (?,?)');
+      metaStmt.run(['lastIndexedAt', new Date().toISOString()]);
+      metaStmt.free();
+
+      db.run('COMMIT');
+      this._saveToFile();
+    } catch (e) {
+      db.run('ROLLBACK');
+      throw e;
+    }
   }
 
   async querySymbols({ name, kind, scope = 'all', exact = false }) {
     const db = await this.open();
     if (!db) return [];
-    // Use read-only connection for non-blocking query
-    const readDb = this._getReadDb();
+
     let sql = 'SELECT path,name,kind,container,namespace,line,column FROM symbols WHERE 1=1';
-    const params = {};
+    const params = [];
+
     if (name) {
       if (exact) {
-        sql += ' AND name = @name';
-        params.name = name;
+        sql += ' AND name = ?';
+        params.push(name);
       } else {
-        sql += ' AND name LIKE @name';
-        params.name = `%${name}%`;
+        sql += ' AND name LIKE ?';
+        params.push(`%${name}%`);
       }
     }
     if (kind) {
-      sql += ' AND kind = @kind';
-      params.kind = kind;
+      sql += ' AND kind = ?';
+      params.push(kind);
+    }
+
+    const stmt = db.prepare(sql);
+    if (params.length > 0) {
+      stmt.bind(params);
+    }
+
+    const rows = [];
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      rows.push(row);
     }
-    const rows = readDb.prepare(sql).all(params);
-    // Apply path-based scope filter in JS (simpler than CASE in SQL)
+    stmt.free();
+
+    // Apply path-based scope filter in JS
     const filtered = rows.filter(r => {
-      const p = String(r.path || '').replace(/\\\\/g, '/');
+      const p = String(r.path || '').replace(/\\/g, '/');
       if (scope === 'assets') return p.startsWith('Assets/');
       if (scope === 'packages')
         return p.startsWith('Packages/') || p.includes('Library/PackageCache/');
       if (scope === 'embedded') return p.startsWith('Packages/');
       return true;
     });
+
     return filtered.map(r => ({
       path: r.path,
       name: r.name,
@@ -281,13 +345,32 @@ export class CodeIndex {
   async getStats() {
     const db = await this.open();
     if (!db) return { total: 0, lastIndexedAt: null };
-    // Use read-only connection for non-blocking stats
-    const readDb = this._getReadDb();
-    const total = readDb.prepare('SELECT COUNT(*) AS c FROM symbols').get().c || 0;
+
+    const countResult = querySQL(db, 'SELECT COUNT(*) AS c FROM symbols');
+    const total =
+      countResult.length > 0 && countResult[0].values.length > 0 ? countResult[0].values[0][0] : 0;
+
+    const metaResult = querySQL(db, "SELECT value FROM meta WHERE key = 'lastIndexedAt'");
     const last =
-      readDb.prepare("SELECT value AS v FROM meta WHERE key = 'lastIndexedAt'").get()?.v || null;
+      metaResult.length > 0 && metaResult[0].values.length > 0 ? metaResult[0].values[0][0] : null;
+
     return { total, lastIndexedAt: last };
   }
+
+  /**
+   * Close the database connection
+   */
+  close() {
+    if (this.db) {
+      this._saveToFile();
+      this.db.close();
+      this.db = null;
+    }
+    if (sharedConnections.db === this.db) {
+      sharedConnections.db = null;
+      sharedConnections.dbPath = null;
+    }
+  }
 }
 
 // Test-only helper to reset cached driver status between runs
@@ -296,18 +379,15 @@ export function __resetCodeIndexDriverStatusForTest() {
   driverStatus.error = null;
   driverStatus.logged = false;
   // Also reset shared connections
-  if (sharedConnections.writeDb) {
+  if (sharedConnections.db) {
     try {
-      sharedConnections.writeDb.close();
-    } catch {}
-  }
-  if (sharedConnections.readDb) {
-    try {
-      sharedConnections.readDb.close();
-    } catch {}
+      sharedConnections.db.close();
+    } catch {
+      // Ignore close errors
+    }
   }
-  sharedConnections.writeDb = null;
-  sharedConnections.readDb = null;
+  sharedConnections.db = null;
   sharedConnections.dbPath = null;
   sharedConnections.schemaInitialized = false;
+  sharedConnections.SQL = null;
 }

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
- * better-sqlite3's synchronous 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,8 +3,8 @@
  *
  * 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. By running in a Worker Thread, these synchronous
- * operations don't block the main event loop.
+ * 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:
  * - Receives: workerData with build options
@@ -16,6 +16,27 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
+// fast-sql helper: run SQL statement
+function runSQL(db, sql) {
+  return db.run(sql);
+}
+
+// fast-sql helper: execute query and return results
+function querySQL(db, sql) {
+  return db.execSql(sql);
+}
+
+// Save fast-sql database to file
+function saveDatabase(db, dbPath) {
+  try {
+    const data = db.exportDb();
+    const buffer = Buffer.from(data);
+    fs.writeFileSync(dbPath, buffer);
+  } catch (e) {
+    log('warn', `[worker] Failed to save database: ${e.message}`);
+  }
+}
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -160,31 +181,49 @@ async function runBuild() {
 
   log('info', `[worker] Starting build: projectRoot=${projectRoot}, dbPath=${dbPath}`);
 
+  let db = null;
+
   try {
-    // Dynamic import better-sqlite3 in worker thread
-    let Database;
+    // Dynamic import fast-sql in worker thread (hybrid: better-sqlite3 or sql.js fallback)
+    let SQL;
     try {
-      const mod = await import('better-sqlite3');
-      Database = mod.default || mod;
+      const initFastSql = (await import('@akiojin/fast-sql')).default;
+      SQL = await initFastSql();
     } catch (e) {
-      throw new Error(`better-sqlite3 unavailable in worker: ${e.message}`);
+      throw new Error(`fast-sql unavailable in worker: ${e.message}`);
     }
 
-    // Open database
-    const db = new Database(dbPath);
-    db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;');
+    // Open or create database
+    if (fs.existsSync(dbPath)) {
+      const buffer = fs.readFileSync(dbPath);
+      db = new SQL.Database(buffer);
+    } else {
+      db = new SQL.Database();
+    }
 
-    // Initialize schema if needed
-    db.exec(`
+    // Initialize schema if needed (fast-sql applies optimal PRAGMAs automatically)
+    runSQL(
+      db,
+      `
       CREATE TABLE IF NOT EXISTS meta (
         key TEXT PRIMARY KEY,
         value TEXT
-      );
+      )
+    `
+    );
+    runSQL(
+      db,
+      `
       CREATE TABLE IF NOT EXISTS files (
         path TEXT PRIMARY KEY,
         sig TEXT,
         updatedAt TEXT
-      );
+      )
+    `
+    );
+    runSQL(
+      db,
+      `
       CREATE TABLE IF NOT EXISTS symbols (
         path TEXT NOT NULL,
         name TEXT NOT NULL,
@@ -193,11 +232,12 @@ async function runBuild() {
         namespace TEXT,
         line INTEGER,
         column INTEGER
-      );
-      CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
-      CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);
-      CREATE INDEX IF NOT EXISTS idx_symbols_path ON symbols(path);
-    `);
+      )
+    `
+    );
+    runSQL(db, 'CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name)');
+    runSQL(db, 'CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind)');
+    runSQL(db, 'CREATE INDEX IF NOT EXISTS idx_symbols_path ON symbols(path)');
 
     // Scan for C# files
     const roots = [
@@ -212,8 +252,13 @@ async function runBuild() {
     log('info', `[worker] Found ${files.length} C# files to process`);
 
     // Get current indexed files
-    const currentRows = db.prepare('SELECT path, sig FROM files').all();
-    const current = new Map(currentRows.map(r => [r.path, r.sig]));
+    const currentResult = querySQL(db, 'SELECT path, sig FROM files');
+    const current = new Map();
+    if (currentResult.length > 0) {
+      for (const row of currentResult[0].values) {
+        current.set(row[0], row[1]);
+      }
+    }
 
     // Determine changes
     const wanted = new Map(files.map(abs => [toRel(abs, projectRoot), makeSig(abs)]));
@@ -230,11 +275,14 @@ async function runBuild() {
     log('info', `[worker] Changes: ${changed.length} to update, ${removed.length} to remove`);
 
     // Remove vanished files
-    const deleteSymbols = db.prepare('DELETE FROM symbols WHERE path = ?');
-    const deleteFile = db.prepare('DELETE FROM files WHERE path = ?');
     for (const rel of removed) {
-      deleteSymbols.run(rel);
-      deleteFile.run(rel);
+      const stmt1 = db.prepare('DELETE FROM symbols WHERE path = ?');
+      stmt1.run([rel]);
+      stmt1.free();
+
+      const stmt2 = db.prepare('DELETE FROM files WHERE path = ?');
+      stmt2.run([rel]);
+      stmt2.free();
     }
 
     // Prepare for updates
@@ -271,14 +319,6 @@ async function runBuild() {
       throw lastErr || new Error('documentSymbol failed');
     };
 
-    // Prepared statements for updates
-    const insertSymbol = db.prepare(
-      'INSERT INTO symbols(path,name,kind,container,namespace,line,column) VALUES (?,?,?,?,?,?,?)'
-    );
-    const deleteSymbolsForPath = db.prepare('DELETE FROM symbols WHERE path = ?');
-    const upsertFile = db.prepare('REPLACE INTO files(path,sig,updatedAt) VALUES (?,?,?)');
-    const updateMeta = db.prepare("REPLACE INTO meta(key,value) VALUES ('lastIndexedAt',?)");
-
     // Process files sequentially (concurrency=1 for non-blocking)
     for (let i = 0; i < absList.length; i++) {
       const abs = absList[i];
@@ -290,14 +330,33 @@ async function runBuild() {
         const rows = toRows(uri, docSymbols, projectRoot);
 
         // Update database in transaction
-        db.transaction(() => {
-          deleteSymbolsForPath.run(rel);
+        runSQL(db, 'BEGIN TRANSACTION');
+        try {
+          const delStmt = db.prepare('DELETE FROM symbols WHERE path = ?');
+          delStmt.run([rel]);
+          delStmt.free();
+
+          const insertStmt = db.prepare(
+            'INSERT INTO symbols(path,name,kind,container,namespace,line,column) VALUES (?,?,?,?,?,?,?)'
+          );
           for (const r of rows) {
-            insertSymbol.run(r.path, r.name, r.kind, r.container, r.ns, r.line, r.column);
+            insertStmt.run([r.path, r.name, r.kind, r.container, r.ns, r.line, r.column]);
           }
-          upsertFile.run(rel, wanted.get(rel), new Date().toISOString());
-          updateMeta.run(new Date().toISOString());
-        })();
+          insertStmt.free();
+
+          const fileStmt = db.prepare('REPLACE INTO files(path,sig,updatedAt) VALUES (?,?,?)');
+          fileStmt.run([rel, wanted.get(rel), new Date().toISOString()]);
+          fileStmt.free();
+
+          const metaStmt = db.prepare("REPLACE INTO meta(key,value) VALUES ('lastIndexedAt',?)");
+          metaStmt.run([new Date().toISOString()]);
+          metaStmt.free();
+
+          runSQL(db, 'COMMIT');
+        } catch (txErr) {
+          runSQL(db, 'ROLLBACK');
+          throw txErr;
+        }
 
         updated++;
       } catch (err) {
@@ -332,12 +391,20 @@ async function runBuild() {
       }
     }
 
+    // Save database to file
+    saveDatabase(db, dbPath);
+
     // Get final stats
-    const total = db.prepare('SELECT COUNT(*) AS c FROM symbols').get().c || 0;
+    const countResult = querySQL(db, 'SELECT COUNT(*) AS c FROM symbols');
+    const total =
+      countResult.length > 0 && countResult[0].values.length > 0 ? countResult[0].values[0][0] : 0;
+
+    const metaResult = querySQL(db, "SELECT value FROM meta WHERE key = 'lastIndexedAt'");
     const lastIndexedAt =
-      db.prepare("SELECT value AS v FROM meta WHERE key = 'lastIndexedAt'").get()?.v || null;
+      metaResult.length > 0 && metaResult[0].values.length > 0 ? metaResult[0].values[0][0] : null;
 
     db.close();
+    db = null;
 
     const result = {
       updatedFiles: updated,
@@ -354,6 +421,13 @@ async function runBuild() {
     sendComplete(result);
   } catch (error) {
     log('error', `[worker] Build failed: ${error.message}`);
+    if (db) {
+      try {
+        db.close();
+      } catch {
+        // Ignore close errors
+      }
+    }
     sendError(error);
   }
 }

package/src/handlers/script/CodeIndexStatusToolHandler.js

@@ -39,15 +39,13 @@ export class CodeIndexStatusToolHandler extends BaseToolHandler {
         coverage: 0,
         message:
           this.codeIndex.disableReason ||
-          'Code index is disabled because the SQLite driver 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:
-          'Install native build tools (python3, make, g++) and run "npm rebuild better-sqlite3 --build-from-source", or set UNITY_MCP_SKIP_NATIVE_BUILD=0 to allow native rebuild. 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 ||
-            'better-sqlite3 native binding 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:
-          'Install native build tools and run "npm rebuild better-sqlite3 --build-from-source", then restart the 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:
-          'Install native build tools and run "npm rebuild better-sqlite3 --build-from-source", then restart the server.'
+          'Ensure fast-sql is properly installed. After reinstalling dependencies, restart unity-mcp-server.'
       };
     }
 

package/prebuilt/better-sqlite3/manifest.json

@@ -1,11 +0,0 @@
-{
-  "artifacts": [
-    {
-      "platformKey": "linux-x64-node22",
-      "checksum": null,
-      "node": null,
-      "generatedAt": null,
-      "size": 2066648
-    }
-  ]
-}

package/scripts/ensure-better-sqlite3.mjs

@@ -1,119 +0,0 @@
-#!/usr/bin/env node
-// Ensure better-sqlite3 native binding exists. Prefers bundled prebuilt binaries, otherwise
-// optionally attempts a native rebuild (opt-in to avoid first-time npx timeouts).
-import fs from 'fs';
-import path from 'path';
-import { spawnSync } from 'child_process';
-import { fileURLToPath } from 'url';
-
-const SCRIPT_PATH = fileURLToPath(import.meta.url);
-const PKG_ROOT = path.resolve(path.dirname(SCRIPT_PATH), '..');
-
-const DEFAULT_BINDING_PATH = process.env.UNITY_MCP_BINDING_PATH
-  ? path.resolve(process.env.UNITY_MCP_BINDING_PATH)
-  : path.join(
-      PKG_ROOT,
-      'node_modules',
-      'better-sqlite3',
-      'build',
-      'Release',
-      'better_sqlite3.node'
-    );
-
-const DEFAULT_PREBUILT_ROOT = process.env.UNITY_MCP_PREBUILT_DIR
-  ? path.resolve(process.env.UNITY_MCP_PREBUILT_DIR)
-  : path.join(PKG_ROOT, 'prebuilt', 'better-sqlite3');
-
-export function resolvePlatformKey(
-  nodeVersion = process.versions.node,
-  platform = process.platform,
-  arch = process.arch
-) {
-  const major = String(nodeVersion).split('.')[0];
-  return `${platform}-${arch}-node${major}`;
-}
-
-function copyPrebuiltBinding(prebuiltDir, bindingTarget, log) {
-  const platformKey = resolvePlatformKey();
-  const source = path.join(prebuiltDir, platformKey, 'better_sqlite3.node');
-  if (!fs.existsSync(source)) return false;
-  fs.mkdirSync(path.dirname(bindingTarget), { recursive: true });
-  fs.copyFileSync(source, bindingTarget);
-  if (log) log(`[postinstall] Installed better-sqlite3 prebuilt for ${platformKey}`);
-  return true;
-}
-
-function rebuildNative(bindingTarget, pkgRoot, log) {
-  log(
-    '[postinstall] No prebuilt available. Attempting native rebuild (npm rebuild better-sqlite3 --build-from-source)'
-  );
-  const result = spawnSync('npm', ['rebuild', 'better-sqlite3', '--build-from-source'], {
-    stdio: 'inherit',
-    shell: false,
-    cwd: pkgRoot
-  });
-  if (result.status !== 0) {
-    throw new Error(`better-sqlite3 rebuild failed with code ${result.status ?? 'null'}`);
-  }
-  if (!fs.existsSync(bindingTarget)) {
-    throw new Error('better-sqlite3 rebuild completed but binding was still not found');
-  }
-  return true;
-}
-
-export function ensureBetterSqlite3(options = {}) {
-  const {
-    bindingPath = DEFAULT_BINDING_PATH,
-    prebuiltRoot = DEFAULT_PREBUILT_ROOT,
-    pkgRoot = PKG_ROOT,
-    skipNative = process.env.UNITY_MCP_SKIP_NATIVE_BUILD === '1',
-    forceNative = process.env.UNITY_MCP_FORCE_NATIVE === '1',
-    skipLegacyFlag = Boolean(process.env.SKIP_SQLITE_REBUILD),
-    log = console.log,
-    warn = console.warn
-  } = options;
-
-  if (skipLegacyFlag && !forceNative) {
-    warn('[postinstall] SKIP_SQLITE_REBUILD set, skipping better-sqlite3 check');
-    return { status: 'skipped' };
-  }
-
-  if (!forceNative && copyPrebuiltBinding(prebuiltRoot, bindingPath, log)) {
-    return { status: 'copied' };
-  }
-
-  if (skipNative && !forceNative) {
-    warn(
-      '[postinstall] UNITY_MCP_SKIP_NATIVE_BUILD=1 -> skipping native rebuild; sql.js fallback will be used'
-    );
-    return { status: 'skipped' };
-  }
-
-  if (forceNative) {
-    log('[postinstall] UNITY_MCP_FORCE_NATIVE=1 -> forcing better-sqlite3 rebuild');
-  } else if (fs.existsSync(bindingPath)) {
-    // Binding already exists and native rebuild not forced.
-    return { status: 'existing' };
-  }
-
-  rebuildNative(bindingPath, pkgRoot, log);
-  return { status: 'rebuilt' };
-}
-
-function isCliExecution() {
-  const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : '';
-  return invokedPath === SCRIPT_PATH;
-}
-
-async function main() {
-  try {
-    await ensureBetterSqlite3();
-  } catch (err) {
-    console.warn(`[postinstall] Warning: ${err.message}`);
-    // Do not hard fail install; runtime may still use sql.js fallback in codeIndex
-  }
-}
-
-if (isCliExecution()) {
-  main();
-}