react-native-sqlite-mcp 1.0.0 → 1.0.2

package/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Welcome to the Contributing Guide
+
+First off, thank you for considering contributing to the **Universal React Native SQLite MCP**! 
+
+Whether you're fixing a typo, optimizing an ADB command, or pointing out a glaring architecture flaw, your help is what makes open source awesome. I built this tool to fill a massive gap in the current MCP ecosystem around mobile development. There are plenty of SQLite tools out there, but none that seamlessly hook into your local emulators and simulators. And all the MCP's around mobile development are primarily UI focused. So hopefully this fills a niche. Let's make mobile dev less painful together!
+
+## The Vibe
+
+- **Keep it chill, but keep it working**: Have fun with the code and the docs, but let's make sure the core functionality is rock solid.
+- **Assume good intent**: We're all here to build cool stuff and learn. Be kind in your PRs and specific in your code reviews.
+- **Developer Experience (DX) is king**: This tool exists to make life easier. If a feature makes the tool harder to use or setup, we probably need to rethink it.
+
+## 🛠️ How to get started
+
+1. **Fork the repo** and clone it locally.
+2. **Install dependencies**: `npm install`
+3. **Make your changes**: Branch off `main` and do your thing.
+4. **Test it out locally**: Build it with `npm run build` and point your local MCP client to it to verify it actually works against an emulator/simulator.
+5. **Open a PR**: Give it a descriptive title and tell me what you fixed or added.
+
+## Found a Bug?
+
+Please open an issue! Tell me:
+- What you were trying to do.
+- What actually happened.
+- Are you on iOS, Android, or both? 
+- Any logs you have from your AI client.
+
+## Got a Feature Idea?
+
+Open an issue and let's chat about it before you spend hours coding it up. I'm totally open to new ideas (especially if they involve making the auto-discovery even smarter).
+
+---
+
+Let's build something epic together.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Murillo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,23 @@
-# Universal React Native SQLite MCP
+# 🚀 Universal React Native SQLite MCP
 
-A Model Context Protocol (MCP) server that connects LLMs (Claude, Cursor, etc.) to your local React Native SQLite databases running on an iOS Simulator or Android Emulator.
+**TL;DR:** A Model Context Protocol (MCP) server that gives your favorite LLM (Claude, Cursor, Antigravity, etc.) X-ray vision into your local React Native SQLite databases. 
 
-This essentially acts as a "Database Inspector" for AI agents, allowing them to automatically view your DB schema and execute queries against the live app database without you having to manually export or describe tables.
+No more flying blind. No more manually exporting `.db` files from emulators to figure out why your app is broken. Just ask your AI: *"Hey, what does the `users` table look like on my Android emulator?"* and watch the magic happen. ✨
 
-## Requirements
-* NodeJS
-* iOS: `xcrun simctl` (available with Xcode)
-* Android: `adb` (available with Android Studio / Android SDK)
+---
 
-## Quick Start (Recommended)
+## 🤔 Why did I build this?
 
-The easiest way to use this MCP server is via `npx`. This doesn't require cloning the repository.
+Honestly? I was tired of jumping through hoops to inspect local databases while building React Native apps. Extracting SQLite files from an iOS Simulator or bypassing root permissions on an Android Emulator just to run a `SELECT *` was ruining my flow state. 
 
-Add this to your `claude_desktop_config.json` (or Cursor/other MCP client settings):
+I wanted my AI assistant to just *know* what my database looked like and query it in real-time. So I built this bridge. It's mobile development less painful.
+
+
+## 📦 Quick Start (The Magic Way)
+
+You don't even need to clone this repo. The easiest way to get rolling is via `npx`.
+
+Toss this bad boy into your `mcp.json` (or your Claude/Cursor/agent settings):
 
 ```json
 {
@@ -30,18 +34,20 @@ Add this to your `claude_desktop_config.json` (or Cursor/other MCP client settin
 }
 ```
 
-## Manual Installation (From Source)
+Boom. You're connected. 🤝
 
-If you want to run it locally from source:
+## 🛠️ Manual Installation (For the brave)
+
+Prefer to tinker with the source code yourself? I respect it. 
 
 ```bash
-git clone <your-repo> react-native-sqlite-mcp
+git clone https://github.com/your-username/react-native-sqlite-mcp.git
 cd react-native-sqlite-mcp
 npm install
 npm run build
 ```
 
-Then configure your MCP client to point to the local file:
+Then point your MCP client to your local build:
 
 ```json
 {
@@ -57,27 +63,42 @@ Then configure your MCP client to point to the local file:
   }
 }
 ```
-*Note: Replace `/absolute/path/to/react-native-sqlite-mcp` with the absolute path to where you cloned this repository.*
 
-### Environment Variables
-- `DB_NAME`: The filename of your database (e.g., `my_app.db`) or a glob pattern (`*.db`).
-- `ANDROID_BUNDLE_ID`: Only required for Android. The application ID/package name of your app (e.g., `com.mycompany.app`). Optional: If omitted, the MCP will scan all third-party apps on the emulator for SQLite databases.
+## 🎛️ Environment Variables (The Knobs)
+
+- `DB_NAME`: The filename of your database (e.g., `my_app.db`). You can also use a glob pattern (`*.db`) if you're feeling adventurous.
+- `ANDROID_BUNDLE_ID`: *(Android Only)* The application ID/package name of your app (e.g., `com.mycompany.app`). 
+  - **Pro-Tip:** If you leave this out, the MCP will go rogue and scan *all* third-party apps on your emulator for SQLite databases. Use with caution/glee.
 
-## Features
+## 🦸‍♂️ Features (What this bad boy can do)
 
-This MCP provides four core tools:
+This MCP arms your AI with four super-powered tools:
 
-- **`list_databases`**: Discovers and returns a list of all SQLite databases currently available. You can optionally pass `platform` ('ios' or 'android') to explicitly target one environment.
-- **`sync_database`**: Pulls a local copy of a database from the active device so the AI can inspect it, and sets it as the active database. `dbName`, `bundleId`, and `platform` are all optional; if omitted, it will automatically select the first discovered default database across all running emulators.
-- **`inspect_schema`**: Returns the `CREATE TABLE` and column information for the currently active synced database. Gives the AI the map of your database. Optionally accepts `tableName`, `dbName`, and `platform` to skip explicit syncing.
-- **`read_table_contents`**: Returns all rows from a specified table. Equivalent to `SELECT * FROM table_name`, limited to 100 rows by default.
-- **`query_db`**: Accepts a raw SQL query and returns the results for the currently active database. Optionally accepts `dbName` and `platform` to skip explicit syncing.
+- 🕵️‍♂️ **`list_databases`**: Scours the device and returns a list of all available SQLite databases. Toss in `platform` ('ios' or 'android') to narrow the search.
+- 🔄 **`sync_database`**: Yanks a copy of a database from your active device into the MCP's working directory so the AI can inspect it to its heart's content. Leave the arguments blank, and it'll just grab the first default database it finds.
+- 🗺️ **`inspect_schema`**: The holy grail. Returns the `CREATE TABLE` and column info for your synced database. It literally gives the AI the map to your data.
+- 📖 **`read_table_contents`**: Dumps all rows from a specific table (capped at 100 rows so we don't blow up the context window). 
+- 🤖 **`query_db`**: Lets the AI fire raw SQL queries right at the database and get the results back. 
 
-## How it Works
+## ⚙️ How it Actually Works (Under the hood)
 
-1. **Auto-Detect Platform**: By default, the tool will scan **both** iOS and Android environments. It locates booted iOS Simulators using `simctl` and active Android Emulators using `adb`. 
+1. **Auto-Detect Platform**: It scans **both** iOS and Android environments simultaneously. It hunts down booted iOS Simulators using `simctl` and active Android Emulators using `adb`. 
 2. **Auto-Locate Database**: 
-  - For iOS, the simulator's app sandbox files are directly accessed without needing root.
-  - For Android, it uses `adb exec-out run-as com.pkg.name cat ...` to copy the database file, along with `-wal` and `-shm` temp files, bypassing strict root permission boundaries on debug profiles.
-3. **Platform Switching**: The MCP server maintains a single active database connection. If you want to switch between iOS and Android, the AI simply calls `sync_database` targeting the desired platform.
-4. **Execution**: Wraps arbitrary requests allowing the LLM to learn the schema and query live data.
+  - **iOS:** We dive straight into the simulator's app sandbox. No root needed.
+  - **Android:** We do a sneaky `adb exec-out run-as com.pkg.name cat ...` to copy the database file, along with its `-wal` and `-shm` sidekicks, completely bypassing the strict root permission boundaries on debug profiles.
+3. **Platform Switching**: The server keeps one active database connection open. Want to switch from iOS to Android? The AI just calls `sync_database` for the other platform. Simple.
+4. **Execution**: It wraps all this up nicely so the LLM can learn your schema and query live data without bothering you.
+
+## 🤝 Contributing (Yes, please!)
+
+Got an idea to make this objectively cooler? Found a bug where it accidentally queried your smart fridge? 
+
+I am **all in** on community contributions. Whether you're fixing a typo, optimizing the ADB scripts, or adding support for Windows Phone (please don't), I want your PRs.
+
+Check out the [CONTRIBUTING.md](./CONTRIBUTING.md) guide to see how we party.
+
+## 📜 License
+
+This project is licensed under the **MIT License**.
+
+See the [LICENSE](./LICENSE) file for the legal jargon.

package/dist/db.js

@@ -1,74 +1,89 @@
-import sqlite3 from "sqlite3";
-export class Database {
-    db;
-    constructor(filename) {
-        this.db = new sqlite3.Database(filename);
+import initSqlJs from "sql.js";
+import fs from "fs";
+import { logger } from "./logger.js";
+let SQL = null;
+async function getSqlJs() {
+    if (!SQL) {
+        SQL = await initSqlJs();
+        logger.debug("sql.js WASM engine initialized");
     }
-    all(sql, params = []) {
-        return new Promise((resolve, reject) => {
-            this.db.all(sql, params, (err, rows) => {
-                if (err)
-                    reject(err);
-                else
-                    resolve(rows);
-            });
-        });
+    return SQL;
+}
+const CACHE_TTL_MS = 60_000;
+const connectionCache = new Map();
+async function getCachedDb(dbPath) {
+    const existing = connectionCache.get(dbPath);
+    if (existing) {
+        clearTimeout(existing.timer);
+        existing.lastUsed = Date.now();
+        existing.timer = setTimeout(() => evictConnection(dbPath), CACHE_TTL_MS);
+        return existing.db;
     }
-    get(sql, params = []) {
-        return new Promise((resolve, reject) => {
-            this.db.get(sql, params, (err, row) => {
-                if (err)
-                    reject(err);
-                else
-                    resolve(row);
-            });
-        });
+    const sqlJs = await getSqlJs();
+    const buffer = fs.readFileSync(dbPath);
+    const db = new sqlJs.Database(buffer);
+    const timer = setTimeout(() => evictConnection(dbPath), CACHE_TTL_MS);
+    connectionCache.set(dbPath, { db, dbPath, lastUsed: Date.now(), timer });
+    logger.debug(`Opened DB connection: ${dbPath}`);
+    return db;
+}
+function evictConnection(dbPath) {
+    const entry = connectionCache.get(dbPath);
+    if (!entry)
+        return;
+    connectionCache.delete(dbPath);
+    try {
+        entry.db.close();
+        logger.debug(`Closed idle DB connection: ${dbPath}`);
     }
-    close() {
-        return new Promise((resolve, reject) => {
-            this.db.close((err) => {
-                if (err)
-                    reject(err);
-                else
-                    resolve();
-            });
-        });
+    catch (e) {
+        logger.warn(`Error closing DB: ${dbPath}`, { error: String(e) });
     }
 }
-/**
- * Executes a simple query on the database.
- */
-export async function queryDb(dbPath, sql, params = []) {
-    const db = new Database(dbPath);
-    try {
-        return await db.all(sql, params);
+export async function closeAllConnections() {
+    const paths = [...connectionCache.keys()];
+    for (const p of paths) {
+        evictConnection(p);
     }
-    finally {
-        await db.close();
+    logger.info(`Closed ${paths.length} cached DB connection(s)`);
+}
+const QUERY_TIMEOUT_MS = 30_000;
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Query timed out after ${ms}ms: ${label}`));
+        }, ms);
+        promise
+            .then((result) => { clearTimeout(timer); resolve(result); })
+            .catch((err) => { clearTimeout(timer); reject(err); });
+    });
+}
+function runQuery(db, sql, params = []) {
+    const stmt = db.prepare(sql);
+    if (params.length > 0)
+        stmt.bind(params);
+    const results = [];
+    while (stmt.step()) {
+        results.push(stmt.getAsObject());
     }
+    stmt.free();
+    return results;
+}
+export async function queryDb(dbPath, sql, params = []) {
+    const db = await getCachedDb(dbPath);
+    return withTimeout(Promise.resolve(runQuery(db, sql, params)), QUERY_TIMEOUT_MS, sql.slice(0, 80));
 }
-/**
- * Returns a detailed schema of all tables in the database.
- */
 export async function inspectSchema(dbPath) {
-    const db = new Database(dbPath);
-    try {
-        // Get all table names
-        const tables = await db.all("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;");
-        const schemaInfo = {};
-        for (const table of tables) {
-            // For each table, get column definitions
-            const columns = await db.all(`PRAGMA table_info("${table.name}");`);
-            // Get table creation SQL
-            const createSql = await db.get(`SELECT sql FROM sqlite_master WHERE type='table' AND name=?`, [table.name]);
-            schemaInfo[table.name] = {
-                columns,
-                createSql: createSql?.sql
-            };
-        }
-        return schemaInfo;
-    }
-    finally {
-        await db.close();
+    const db = await getCachedDb(dbPath);
+    const tables = runQuery(db, "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;");
+    const schemaInfo = {};
+    for (const table of tables) {
+        const columns = runQuery(db, `PRAGMA table_info("${table.name}");`);
+        const createSqlRows = runQuery(db, `SELECT sql FROM sqlite_master WHERE type='table' AND name=?`, [table.name]);
+        schemaInfo[table.name] = {
+            columns,
+            createSql: createSqlRows[0]?.sql
+        };
     }
+    return schemaInfo;
 }