react-native-sqlite-mcp 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# 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.
+
+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.
+
+## Requirements
+* NodeJS
+* iOS: `xcrun simctl` (available with Xcode)
+* Android: `adb` (available with Android Studio / Android SDK)
+
+## Quick Start (Recommended)
+
+The easiest way to use this MCP server is via `npx`. This doesn't require cloning the repository.
+
+Add this to your `claude_desktop_config.json` (or Cursor/other MCP client settings):
+
+```json
+{
+  "mcpServers": {
+    "rn-sqlite-bridge": {
+      "command": "npx",
+      "args": ["-y", "react-native-sqlite-mcp"],
+      "env": {
+        "DB_NAME": "my_database.db",
+        "ANDROID_BUNDLE_ID": "com.mycompany.myapp"
+      }
+    }
+  }
+}
+```
+
+## Manual Installation (From Source)
+
+If you want to run it locally from source:
+
+```bash
+git clone <your-repo> react-native-sqlite-mcp
+cd react-native-sqlite-mcp
+npm install
+npm run build
+```
+
+Then configure your MCP client to point to the local file:
+
+```json
+{
+  "mcpServers": {
+    "rn-sqlite-bridge": {
+      "command": "node",
+      "args": ["/absolute/path/to/react-native-sqlite-mcp/dist/index.js"],
+      "env": {
+        "DB_NAME": "my_database.db",
+        "ANDROID_BUNDLE_ID": "com.mycompany.myapp"
+      }
+    }
+  }
+}
+```
+*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.
+
+## Features
+
+This MCP provides four core 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.
+
+## How it Works
+
+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`. 
+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.

package/dist/db.js

@@ -0,0 +1,74 @@
+import sqlite3 from "sqlite3";
+export class Database {
+    db;
+    constructor(filename) {
+        this.db = new sqlite3.Database(filename);
+    }
+    all(sql, params = []) {
+        return new Promise((resolve, reject) => {
+            this.db.all(sql, params, (err, rows) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(rows);
+            });
+        });
+    }
+    get(sql, params = []) {
+        return new Promise((resolve, reject) => {
+            this.db.get(sql, params, (err, row) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(row);
+            });
+        });
+    }
+    close() {
+        return new Promise((resolve, reject) => {
+            this.db.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+}
+/**
+ * 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);
+    }
+    finally {
+        await db.close();
+    }
+}
+/**
+ * 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();
+    }
+}

package/dist/index.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { listDatabases, syncDatabase } from "./locator.js";
+import { inspectSchema, queryDb } from "./db.js";
+let activeDatabases = [];
+const server = new Server({
+    name: "react-native-sqlite-bridge",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "sync_database",
+                description: "Re-runs the adb pull or file-find logic to ensure the AI is looking at the latest data from the emulator/simulator.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        dbName: {
+                            type: "string",
+                            description: "The name of the database file or a glob pattern (e.g., 'my_app.db' or '*.db'). Optional. If omitted, it will select the first discovered database."
+                        },
+                        bundleId: {
+                            type: "string",
+                            description: "(Android only) The application bundle ID (e.g., 'com.example.app'). Not required for iOS."
+                        },
+                        platform: {
+                            type: "string",
+                            description: "Optional. Explicitly target 'ios' or 'android'."
+                        }
+                    }
+                }
+            },
+            {
+                name: "list_databases",
+                description: "Lists all available SQLite databases found on the iOS Simulator or Android Emulator.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        bundleId: {
+                            type: "string",
+                            description: "(Android only) The application bundle ID (e.g., 'com.example.app'). Not required for iOS."
+                        },
+                        platform: {
+                            type: "string",
+                            description: "Optional. Explicitly target 'ios' or 'android'."
+                        }
+                    }
+                }
+            },
+            {
+                name: "inspect_schema",
+                description: "Returns a list of all tables and their column definitions. This gives the AI the 'map' of the database.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        dbName: {
+                            type: "string",
+                            description: "Optional. Target a specific database name. If omitted, uses the active DB or auto-selects."
+                        },
+                        platform: {
+                            type: "string",
+                            description: "Optional. Explicitly target 'ios' or 'android'. If omitted, uses the active DB or auto-selects."
+                        }
+                    },
+                    required: []
+                }
+            },
+            {
+                name: "read_table_contents",
+                description: "Returns rows from a specific table. Equivalent to SELECT * FROM table_name.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        tableName: {
+                            type: "string",
+                            description: "The name of the table to read."
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Optional limit to the number of rows returned. Defaults to 100."
+                        },
+                        dbName: {
+                            type: "string",
+                            description: "Optional. Target a specific database name. If omitted, uses the active DB or auto-selects."
+                        },
+                        platform: {
+                            type: "string",
+                            description: "Optional. Explicitly target 'ios' or 'android'. If omitted, uses the active DB or auto-selects."
+                        }
+                    },
+                    required: ["tableName"]
+                }
+            },
+            {
+                name: "query_db",
+                description: "Accepts a raw SQL SELECT string and returns the JSON result set.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        sql: {
+                            type: "string",
+                            description: "The raw SQL SELECT string to execute."
+                        },
+                        params: {
+                            type: "array",
+                            description: "Optional arguments to bind to the SQL query. Use this to safely substitute ? placeholders in your SQL string (e.g. ['value', 42]).",
+                            items: {
+                                type: ["string", "number", "boolean", "null"],
+                                description: "A single bound parameter value."
+                            }
+                        },
+                        dbName: {
+                            type: "string",
+                            description: "Optional. Target a specific database name. If omitted, uses the active DB or auto-selects."
+                        },
+                        platform: {
+                            type: "string",
+                            description: "Optional. Explicitly target 'ios' or 'android'. If omitted, uses the active DB or auto-selects."
+                        }
+                    },
+                    required: ["sql"]
+                }
+            }
+        ]
+    };
+});
+// Helper to sanitize platform input if any
+function cleanPlatform(raw) {
+    if (!raw)
+        return undefined;
+    const cleaned = raw.replace(/['"]/g, '').trim().toLowerCase();
+    if (cleaned === 'ios' || cleaned === 'android')
+        return cleaned;
+    return undefined; // If they pass garbage, just let locator try both
+}
+// Helper to ensure database is synced based on provided args
+async function ensureDbState(args) {
+    const reqDbName = args?.dbName;
+    const reqPlatform = cleanPlatform(args?.platform);
+    // If nothing is synced, sync defaults
+    if (activeDatabases.length === 0) {
+        const envDb = reqDbName || process.env.DB_NAME;
+        const envBundle = process.env.ANDROID_BUNDLE_ID;
+        activeDatabases = await syncDatabase(envDb, envBundle, reqPlatform);
+    }
+    // Filter based on explicit requirements
+    let candidates = activeDatabases;
+    if (reqPlatform)
+        candidates = candidates.filter(db => db.platform === reqPlatform);
+    if (reqDbName)
+        candidates = candidates.filter(db => db.dbName === reqDbName);
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    if (candidates.length === 0) {
+        throw new Error(`No synced databases match the criteria (platform: ${reqPlatform || 'any'}, dbName: ${reqDbName || 'any'}). Try calling sync_database first.`);
+    }
+    const matches = candidates.map(c => `[${c.platform}] ${c.dbName}`).join(", ");
+    throw new Error(`Multiple databases match the criteria. Please specify 'platform' or 'dbName'. Matches: ${matches}`);
+}
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        if (name === "list_databases") {
+            const bundleId = args?.bundleId;
+            const platform = cleanPlatform(args?.platform);
+            const results = await listDatabases(bundleId, platform);
+            return {
+                content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+            };
+        }
+        if (name === "sync_database") {
+            const dbName = args?.dbName;
+            const bundleId = args?.bundleId;
+            const platform = cleanPlatform(args?.platform);
+            const results = await syncDatabase(dbName, bundleId, platform);
+            activeDatabases = results; // Replace the active list
+            let msg = "Successfully synced databases:\n";
+            for (const res of results) {
+                msg += `- Platform: ${res.platform} | DB: ${res.dbName}\n  Path: ${res.localPath}\n`;
+            }
+            return {
+                content: [{ type: "text", text: msg }]
+            };
+        }
+        if (name === "inspect_schema") {
+            const activeDb = await ensureDbState(args);
+            const schema = await inspectSchema(activeDb.localPath);
+            return {
+                content: [{ type: "text", text: `[Active Platform: ${activeDb.platform} | DB: ${activeDb.dbName}]\n` + JSON.stringify(schema, null, 2) }]
+            };
+        }
+        if (name === "read_table_contents") {
+            const activeDb = await ensureDbState(args);
+            const tableName = args?.tableName;
+            const limit = args?.limit || 100;
+            if (!tableName) {
+                throw new Error("Missing required argument: tableName");
+            }
+            const sql = `SELECT * FROM "${tableName}" LIMIT ?`;
+            const results = await queryDb(activeDb.localPath, sql, [limit]);
+            return {
+                content: [{ type: "text", text: `[Active Platform: ${activeDb.platform} | DB: ${activeDb.dbName} | Table: ${tableName} | Limit: ${limit}]\n` + JSON.stringify(results, null, 2) }]
+            };
+        }
+        if (name === "query_db") {
+            const activeDb = await ensureDbState(args);
+            const sql = args?.sql;
+            const params = args?.params || [];
+            if (!sql) {
+                throw new Error("Missing required argument: sql");
+            }
+            const results = await queryDb(activeDb.localPath, sql, params);
+            return {
+                content: [{ type: "text", text: `[Active Platform: ${activeDb.platform} | DB: ${activeDb.dbName}]\n` + JSON.stringify(results, null, 2) }]
+            };
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${error.message}`
+                }
+            ],
+            isError: true
+        };
+    }
+});
+async function run() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Universal React Native SQLite MCP Server running on stdio");
+}
+run().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/dist/locator.js

@@ -0,0 +1,229 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import os from "os";
+export async function listDatabases(bundleId, targetPlatform) {
+    const results = [];
+    if (!targetPlatform || targetPlatform === 'ios') {
+        try {
+            const udidStr = execSync("xcrun simctl list devices booted | awk -F '[()]' '/Booted/{print $2; exit}'", { stdio: ['pipe', 'pipe', 'ignore'], timeout: 3000 }).toString().trim();
+            if (udidStr) {
+                const appDataDir = `${process.env.HOME}/Library/Developer/CoreSimulator/Devices/${udidStr}/data/Containers/Data/Application`;
+                if (fs.existsSync(appDataDir)) {
+                    try {
+                        const findCmd = `find "${appDataDir}" -type f \\( -name "*.db" -o -name "*.sqlite" -o -name "*.sqlite3" \\) -maxdepth 7 -print`;
+                        const found = execSync(findCmd, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 10000 }).toString().trim();
+                        if (found) {
+                            results.push({
+                                platform: 'ios',
+                                appDir: appDataDir,
+                                databases: found.split('\n').map(p => path.basename(p.trim())).filter(Boolean)
+                            });
+                        }
+                    }
+                    catch (e) {
+                        console.error("iOS find failed", e);
+                    }
+                }
+            }
+            else if (targetPlatform === 'ios') {
+                throw new Error("No booted iOS Simulator found (simctl returned empty).");
+            }
+        }
+        catch (e) {
+            if (targetPlatform === 'ios' && !e.message?.includes("find failed")) {
+                throw new Error("No booted iOS Simulator found or xcrun failed.");
+            }
+        }
+    }
+    if (!targetPlatform || targetPlatform === 'android') {
+        try {
+            execSync("adb get-state", { stdio: ['pipe', 'pipe', 'ignore'], timeout: 3000 });
+        }
+        catch (e) {
+            if (targetPlatform === 'android') {
+                throw new Error("No booted Android Emulator found or adb is unresponsive.");
+            }
+            if (results.length === 0) {
+                throw new Error("No booted iOS Simulator or Android Emulator device found.");
+            }
+            return results;
+        }
+        // if we have a specific bundleId-use it otherwise hunt
+        let packagesToScan = [];
+        if (bundleId) {
+            packagesToScan = [bundleId];
+        }
+        else {
+            try {
+                const packagesStr = execSync("adb shell pm list packages -3", { stdio: ['pipe', 'pipe', 'ignore'], timeout: 5000 }).toString().trim();
+                packagesToScan = packagesStr.split('\n')
+                    .map(line => line.replace('package:', '').trim())
+                    .filter(Boolean);
+            }
+            catch (e) {
+                if (results.length === 0) {
+                    throw new Error("Could not list packages on Android Emulator to discover databases. Is it fully booted?");
+                }
+                return results;
+            }
+        }
+        const allAndroidDatabases = [];
+        let lastSuccessfulAppDir;
+        for (const pkg of packagesToScan) {
+            const baseDirs = [`/data/user/0/${pkg}`, `/data/data/${pkg}`];
+            for (const baseDir of baseDirs) {
+                try {
+                    execSync(`adb shell run-as ${pkg} ls -d ${baseDir}`, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 2000 });
+                    let foundFiles = [];
+                    try {
+                        const findCmd = `adb shell "run-as ${pkg} find ${baseDir} -type f \\( -name \\"*.db\\" -o -name \\"*.sqlite\\" -o -name \\"*.sqlite3\\" \\)"`;
+                        const findOut = execSync(findCmd, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 5000 }).toString().trim();
+                        if (findOut) {
+                            foundFiles.push(...findOut.split('\n').map(l => l.trim().replace(/\r/g, '')).filter(Boolean));
+                        }
+                    }
+                    catch (e) { }
+                    try {
+                        const lsOut = execSync(`adb shell run-as ${pkg} ls -1p ${baseDir}/databases`, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 2000 }).toString().trim();
+                        const lsFiles = lsOut.split('\n')
+                            .map(l => l.trim().replace(/\r/g, ''))
+                            .filter(Boolean)
+                            .filter(f => !f.endsWith('/'))
+                            .filter(f => !f.endsWith('-journal') && !f.endsWith('-wal') && !f.endsWith('-shm'))
+                            .filter(f => !f.includes('.'))
+                            .map(f => `${baseDir}/databases/${f}`);
+                        foundFiles.push(...lsFiles);
+                    }
+                    catch (e) { }
+                    // Deduplicate
+                    foundFiles = [...new Set(foundFiles)];
+                    if (foundFiles.length > 0) {
+                        const displayFiles = foundFiles.map(f => f.replace(`${baseDir}/`, ''));
+                        allAndroidDatabases.push(...displayFiles);
+                        lastSuccessfulAppDir = `${baseDir}::${pkg}`;
+                        break;
+                    }
+                }
+                catch (e) {
+                    console.error(`Failed to list databases for app: ${pkg}`);
+                }
+            }
+        }
+        if (allAndroidDatabases.length > 0) {
+            results.push({
+                platform: 'android',
+                appDir: lastSuccessfulAppDir,
+                databases: allAndroidDatabases
+            });
+        }
+        else if (targetPlatform === 'android') {
+            throw new Error(`Android Emulator is booted, but no SQLite databases were found in any debuggable third-party packages.`);
+        }
+    }
+    return results;
+}
+/**
+ * Finds the DB file based on platform and a provided/detected filename.
+ * If dbNameGlob is empty/undefined, it will auto-select the first discovered database.
+ * Prioritizes iOS (simctl), falls back to Android (adb).
+ * Returns the local file path (either the iOS original or a pulled Android copy).
+ */
+export async function syncDatabase(dbNameGlob, bundleId, targetPlatform) {
+    // First, discover available databases
+    const locations = await listDatabases(bundleId, targetPlatform);
+    if (locations.length === 0) {
+        if (targetPlatform) {
+            throw new Error(`No SQLite databases found for platform '${targetPlatform}'.`);
+        }
+        throw new Error(`No SQLite databases found on any platform.`);
+    }
+    const synced = [];
+    for (const loc of locations) {
+        if (targetPlatform && loc.platform !== targetPlatform)
+            continue;
+        let targetDbNames = [];
+        if (!dbNameGlob) {
+            // Auto-select: find the first .db or .sqlite file in this location
+            const preferred = loc.databases.find(d => d.endsWith('.db') || d.endsWith('.sqlite'));
+            if (preferred) {
+                targetDbNames.push(preferred);
+            }
+            else if (loc.databases.length > 0) {
+                targetDbNames.push(loc.databases[0]); // fallback to first file
+            }
+        }
+        else {
+            const globRegex = new RegExp('^' + dbNameGlob.replace(/\*/g, '.*') + '$');
+            targetDbNames = loc.databases.filter(name => globRegex.test(name));
+        }
+        for (const targetDbName of targetDbNames) {
+            const { platform, appDir } = loc;
+            // --- iOS Logic ---
+            if (platform === 'ios') {
+                if (!appDir)
+                    continue;
+                // Find the exact path of the targetDbName
+                const findCmd = `find "${appDir}" -type f -name "${targetDbName}" -maxdepth 7 -print | head -n 1`;
+                try {
+                    const found = execSync(findCmd, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 5000 }).toString().trim();
+                    if (found && fs.existsSync(found)) {
+                        console.error(`Located iOS DB at: ${found}`);
+                        synced.push({ localPath: found, dbName: targetDbName, platform: 'ios' });
+                    }
+                }
+                catch (e) {
+                    console.error(`Failed to locate full path for iOS DB: ${targetDbName}`);
+                }
+                continue;
+            }
+            // --- Android Logic ---
+            if (!appDir || !appDir.includes("::")) {
+                console.error(`Invalid Android appDir format: ${appDir}`);
+                continue;
+            }
+            const [targetDbDir, targetPkg] = appDir.split("::");
+            try {
+                execSync(`adb shell am force-stop ${targetPkg}`, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 3000 });
+            }
+            catch (e) {
+                console.error(`Failed to force-stop app: ${targetPkg}`);
+            }
+            const tmpdir = fs.mkdtempSync(path.join(os.tmpdir(), "rn-sqlite-mcp-"));
+            const safeLocalName = targetDbName.replace(/\//g, '_');
+            const localDb = path.join(tmpdir, safeLocalName);
+            const localWal = `${localDb}-wal`;
+            const localShm = `${localDb}-shm`;
+            const remoteMain = `${targetDbDir}/${targetDbName}`;
+            const remoteWal = `${remoteMain}-wal`;
+            const remoteShm = `${remoteMain}-shm`;
+            const pullOne = (remote, local) => {
+                try {
+                    const remoteBase = path.basename(remote);
+                    const tmpRemote = `/data/local/tmp/${targetPkg}_${remoteBase}_${Date.now()}`;
+                    execSync(`adb shell "run-as '${targetPkg}' cat '${remote}' > '${tmpRemote}'"`, { stdio: 'ignore', timeout: 5000 });
+                    execSync(`adb pull '${tmpRemote}' '${local}'`, { stdio: 'ignore', timeout: 5000 });
+                    execSync(`adb shell rm '${tmpRemote}'`, { stdio: 'ignore', timeout: 3000 });
+                    return fs.existsSync(local) && fs.statSync(local).size > 0;
+                }
+                catch (e) {
+                    if (fs.existsSync(local))
+                        fs.unlinkSync(local);
+                    return false;
+                }
+            };
+            if (!pullOne(remoteMain, localDb)) {
+                console.error(`Failed to pull main DB file from Android: ${remoteMain}`);
+                continue;
+            }
+            pullOne(remoteWal, localWal);
+            pullOne(remoteShm, localShm);
+            console.error(`Pulled Android DB to local temp: ${localDb}`);
+            synced.push({ localPath: localDb, dbName: targetDbName, platform: 'android' });
+        }
+    }
+    if (synced.length === 0) {
+        throw new Error(`Failed to sync any databases matching '${dbNameGlob || 'auto-select'}'.`);
+    }
+    return synced;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "react-native-sqlite-mcp",
+  "version": "1.0.0",
+  "description": "Universal React Native SQLite MCP Server",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "react-native-sqlite-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "react-native",
+    "sqlite",
+    "claude",
+    "cursor"
+  ],
+  "author": "Brian Murillo",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "sqlite3": "^5.1.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "@types/sqlite3": "^3.1.11",
+    "typescript": "^5.7.3"
+  }
+}

package/src/db.ts

@@ -0,0 +1,85 @@
+import sqlite3 from "sqlite3";
+
+export class Database {
+  private db: sqlite3.Database;
+
+  constructor(filename: string) {
+    this.db = new sqlite3.Database(filename);
+  }
+
+  public all<T>(sql: string, params: any[] = []): Promise<T[]> {
+    return new Promise((resolve, reject) => {
+      this.db.all(sql, params, (err, rows) => {
+        if (err) reject(err);
+        else resolve(rows as Array<T>);
+      });
+    });
+  }
+
+  public get<T>(sql: string, params: any[] = []): Promise<T | undefined> {
+    return new Promise((resolve, reject) => {
+      this.db.get(sql, params, (err, row) => {
+        if (err) reject(err);
+        else resolve(row as T | undefined);
+      });
+    });
+  }
+
+  public close(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.db.close((err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+}
+
+/**
+ * Executes a simple query on the database.
+ */
+export async function queryDb(dbPath: string, sql: string, params: any[] = []): Promise<any[]> {
+  const db = new Database(dbPath);
+  try {
+    return await db.all(sql, params);
+  } finally {
+    await db.close();
+  }
+}
+
+/**
+ * Returns a detailed schema of all tables in the database.
+ */
+export async function inspectSchema(dbPath: string): Promise<any> {
+  const db = new Database(dbPath);
+  try {
+    // Get all table names
+    const tables = await db.all<{ name: string }>(
+      "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;"
+    );
+
+    const schemaInfo: Record<string, any> = {};
+
+    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<{ sql: string }>(
+        `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();
+  }
+}

package/src/index.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { listDatabases, syncDatabase } from "./locator.js";
+import { inspectSchema, queryDb } from "./db.js";
+
+// Keep track of the currently active databases
+interface SyncedDB {
+  localPath: string;
+  dbName: string;
+  platform: 'ios' | 'android';
+}
+
+let activeDatabases: SyncedDB[] = [];
+
+const server = new Server(
+  {
+    name: "react-native-sqlite-bridge",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "sync_database",
+        description: "Re-runs the adb pull or file-find logic to ensure the AI is looking at the latest data from the emulator/simulator.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            dbName: {
+              type: "string",
+              description: "The name of the database file or a glob pattern (e.g., 'my_app.db' or '*.db'). Optional. If omitted, it will select the first discovered database."
+            },
+            bundleId: {
+              type: "string",
+              description: "(Android only) The application bundle ID (e.g., 'com.example.app'). Not required for iOS."
+            },
+            platform: {
+              type: "string",
+              description: "Optional. Explicitly target 'ios' or 'android'."
+            }
+          }
+        }
+      },
+      {
+        name: "list_databases",
+        description: "Lists all available SQLite databases found on the iOS Simulator or Android Emulator.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            bundleId: {
+              type: "string",
+              description: "(Android only) The application bundle ID (e.g., 'com.example.app'). Not required for iOS."
+            },
+            platform: {
+              type: "string",
+              description: "Optional. Explicitly target 'ios' or 'android'."
+            }
+          }
+        }
+      },
+      {
+        name: "inspect_schema",
+        description: "Returns a list of all tables and their column definitions. This gives the AI the 'map' of the database.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            dbName: {
+              type: "string",
+              description: "Optional. Target a specific database name. If omitted, uses the active DB or auto-selects."
+            },
+            platform: {
+              type: "string",
+              description: "Optional. Explicitly target 'ios' or 'android'. If omitted, uses the active DB or auto-selects."
+            }
+          },
+          required: []
+        }
+      },
+      {
+        name: "read_table_contents",
+        description: "Returns rows from a specific table. Equivalent to SELECT * FROM table_name.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            tableName: {
+              type: "string",
+              description: "The name of the table to read."
+            },
+            limit: {
+              type: "number",
+              description: "Optional limit to the number of rows returned. Defaults to 100."
+            },
+            dbName: {
+              type: "string",
+              description: "Optional. Target a specific database name. If omitted, uses the active DB or auto-selects."
+            },
+            platform: {
+              type: "string",
+              description: "Optional. Explicitly target 'ios' or 'android'. If omitted, uses the active DB or auto-selects."
+            }
+          },
+          required: ["tableName"]
+        }
+      },
+      {
+        name: "query_db",
+        description: "Accepts a raw SQL SELECT string and returns the JSON result set.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            sql: {
+              type: "string",
+              description: "The raw SQL SELECT string to execute."
+            },
+            params: {
+              type: "array",
+              description: "Optional arguments to bind to the SQL query. Use this to safely substitute ? placeholders in your SQL string (e.g. ['value', 42]).",
+              items: {
+                type: ["string", "number", "boolean", "null"],
+                description: "A single bound parameter value."
+              }
+            },
+            dbName: {
+              type: "string",
+              description: "Optional. Target a specific database name. If omitted, uses the active DB or auto-selects."
+            },
+            platform: {
+              type: "string",
+              description: "Optional. Explicitly target 'ios' or 'android'. If omitted, uses the active DB or auto-selects."
+            }
+          },
+          required: ["sql"]
+        }
+      }
+    ]
+  };
+});
+
+// Helper to sanitize platform input if any
+function cleanPlatform(raw?: string): 'ios' | 'android' | undefined {
+  if (!raw) return undefined;
+  const cleaned = raw.replace(/['"]/g, '').trim().toLowerCase();
+  if (cleaned === 'ios' || cleaned === 'android') return cleaned;
+  return undefined; // If they pass garbage, just let locator try both
+}
+
+// Helper to ensure database is synced based on provided args
+async function ensureDbState(args: any): Promise<SyncedDB> {
+  const reqDbName = args?.dbName as string | undefined;
+  const reqPlatform = cleanPlatform(args?.platform as string | undefined);
+  
+  // If nothing is synced, sync defaults
+  if (activeDatabases.length === 0) {
+    const envDb = reqDbName || process.env.DB_NAME;
+    const envBundle = process.env.ANDROID_BUNDLE_ID;
+    activeDatabases = await syncDatabase(envDb, envBundle, reqPlatform);
+  }
+
+  // Filter based on explicit requirements
+  let candidates = activeDatabases;
+  if (reqPlatform) candidates = candidates.filter(db => db.platform === reqPlatform);
+  if (reqDbName) candidates = candidates.filter(db => db.dbName === reqDbName);
+
+  if (candidates.length === 1) {
+    return candidates[0];
+  }
+
+  if (candidates.length === 0) {
+    throw new Error(`No synced databases match the criteria (platform: ${reqPlatform || 'any'}, dbName: ${reqDbName || 'any'}). Try calling sync_database first.`);
+  }
+
+  const matches = candidates.map(c => `[${c.platform}] ${c.dbName}`).join(", ");
+  throw new Error(`Multiple databases match the criteria. Please specify 'platform' or 'dbName'. Matches: ${matches}`);
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (name === "list_databases") {
+      const bundleId = args?.bundleId as string | undefined;
+      const platform = cleanPlatform(args?.platform as string | undefined);
+      const results = await listDatabases(bundleId, platform);
+      return {
+        content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
+      };
+    }
+
+    if (name === "sync_database") {
+      const dbName = args?.dbName as string | undefined;
+      const bundleId = args?.bundleId as string | undefined;
+      const platform = cleanPlatform(args?.platform as string | undefined);
+
+      const results = await syncDatabase(dbName, bundleId, platform);
+      
+      activeDatabases = results; // Replace the active list
+
+      let msg = "Successfully synced databases:\n";
+      for (const res of results) {
+        msg += `- Platform: ${res.platform} | DB: ${res.dbName}\n  Path: ${res.localPath}\n`;
+      }
+
+      return {
+        content: [{ type: "text", text: msg }]
+      };
+    }
+
+    if (name === "inspect_schema") {
+      const activeDb = await ensureDbState(args);
+      const schema = await inspectSchema(activeDb.localPath);
+      return {
+        content: [{ type: "text", text: `[Active Platform: ${activeDb.platform} | DB: ${activeDb.dbName}]\n` + JSON.stringify(schema, null, 2) }]
+      };
+    }
+
+    if (name === "read_table_contents") {
+      const activeDb = await ensureDbState(args);
+      
+      const tableName = args?.tableName as string;
+      const limit = args?.limit as number || 100;
+      
+      if (!tableName) {
+        throw new Error("Missing required argument: tableName");
+      }
+
+      const sql = `SELECT * FROM "${tableName}" LIMIT ?`;
+      const results = await queryDb(activeDb.localPath, sql, [limit]);
+      return {
+        content: [{ type: "text", text: `[Active Platform: ${activeDb.platform} | DB: ${activeDb.dbName} | Table: ${tableName} | Limit: ${limit}]\n` + JSON.stringify(results, null, 2) }]
+      };
+    }
+
+    if (name === "query_db") {
+      const activeDb = await ensureDbState(args);
+      
+      const sql = args?.sql as string;
+      const params = (args?.params as any[]) || [];
+      
+      if (!sql) {
+        throw new Error("Missing required argument: sql");
+      }
+
+      const results = await queryDb(activeDb.localPath, sql, params);
+      return {
+        content: [{ type: "text", text: `[Active Platform: ${activeDb.platform} | DB: ${activeDb.dbName}]\n` + JSON.stringify(results, null, 2) }]
+      };
+    }
+
+    throw new Error(`Unknown tool: ${name}`);
+  } catch (error: any) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${error.message}`
+        }
+      ],
+      isError: true
+    };
+  }
+});
+
+async function run() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Universal React Native SQLite MCP Server running on stdio");
+}
+
+run().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/src/locator.ts

@@ -0,0 +1,255 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+export interface DatabaseLocation {
+  platform: 'ios' | 'android';
+  databases: string[];
+  appDir?: string;
+}
+
+export async function listDatabases(bundleId?: string, targetPlatform?: 'ios' | 'android'): Promise<DatabaseLocation[]> {
+  const results: DatabaseLocation[] = [];
+
+  if (!targetPlatform || targetPlatform === 'ios') {
+    try {
+      const udidStr = execSync("xcrun simctl list devices booted | awk -F '[()]' '/Booted/{print $2; exit}'", { stdio: ['pipe', 'pipe', 'ignore'], timeout: 3000 }).toString().trim();
+      if (udidStr) {
+        const appDataDir = `${process.env.HOME}/Library/Developer/CoreSimulator/Devices/${udidStr}/data/Containers/Data/Application`;
+        if (fs.existsSync(appDataDir)) {
+          try {
+            const findCmd = `find "${appDataDir}" -type f \\( -name "*.db" -o -name "*.sqlite" -o -name "*.sqlite3" \\) -maxdepth 7 -print`;
+            const found = execSync(findCmd, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 10000 }).toString().trim();
+            if (found) {
+              results.push({
+                platform: 'ios',
+                appDir: appDataDir,
+                databases: found.split('\n').map(p => path.basename(p.trim())).filter(Boolean)
+              });
+            }
+          } catch (e) {
+            console.error("iOS find failed", e);
+          }
+        }
+      } else if (targetPlatform === 'ios') {
+        throw new Error("No booted iOS Simulator found (simctl returned empty).");
+      }
+    } catch (e: any) {
+      if (targetPlatform === 'ios' && !e.message?.includes("find failed")) {
+        throw new Error("No booted iOS Simulator found or xcrun failed.");
+      }
+    }
+  }
+
+  if (!targetPlatform || targetPlatform === 'android') {
+    try {
+      execSync("adb get-state", { stdio: ['pipe', 'pipe', 'ignore'], timeout: 3000 });
+    } catch (e) {
+      if (targetPlatform === 'android') {
+        throw new Error("No booted Android Emulator found or adb is unresponsive.");
+      }
+      if (results.length === 0) {
+        throw new Error("No booted iOS Simulator or Android Emulator device found.");
+      }
+      return results; 
+    }
+
+    // if we have a specific bundleId-use it otherwise hunt
+    let packagesToScan: string[] = [];
+    if (bundleId) {
+      packagesToScan = [bundleId];
+    } else {
+      try {
+        const packagesStr = execSync("adb shell pm list packages -3", { stdio: ['pipe', 'pipe', 'ignore'], timeout: 5000 }).toString().trim();
+        packagesToScan = packagesStr.split('\n')
+          .map(line => line.replace('package:', '').trim())
+          .filter(Boolean);
+      } catch (e) {
+        if (results.length === 0) {
+          throw new Error("Could not list packages on Android Emulator to discover databases. Is it fully booted?");
+        }
+        return results;
+      }
+    }
+
+    const allAndroidDatabases: string[] = [];
+    let lastSuccessfulAppDir: string | undefined;
+
+    for (const pkg of packagesToScan) {
+      const baseDirs = [`/data/user/0/${pkg}`, `/data/data/${pkg}`];
+      
+      for (const baseDir of baseDirs) {
+        try {
+          execSync(`adb shell run-as ${pkg} ls -d ${baseDir}`, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 2000 });
+          
+          let foundFiles: string[] = [];
+          
+          try {
+            const findCmd = `adb shell "run-as ${pkg} find ${baseDir} -type f \\( -name \\"*.db\\" -o -name \\"*.sqlite\\" -o -name \\"*.sqlite3\\" \\)"`;
+            const findOut = execSync(findCmd, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 5000 }).toString().trim();
+            if (findOut) {
+               foundFiles.push(...findOut.split('\n').map(l => l.trim().replace(/\r/g, '')).filter(Boolean));
+            }
+          } catch (e) {}
+          
+           try {
+            const lsOut = execSync(`adb shell run-as ${pkg} ls -1p ${baseDir}/databases`, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 2000 }).toString().trim();
+            const lsFiles = lsOut.split('\n')
+              .map(l => l.trim().replace(/\r/g, ''))
+              .filter(Boolean)
+              .filter(f => !f.endsWith('/'))
+              .filter(f => !f.endsWith('-journal') && !f.endsWith('-wal') && !f.endsWith('-shm'))
+              .filter(f => !f.includes('.')) 
+              .map(f => `${baseDir}/databases/${f}`);
+             foundFiles.push(...lsFiles);
+           } catch (e) {}
+
+          // Deduplicate
+          foundFiles = [...new Set(foundFiles)];
+
+          if (foundFiles.length > 0) {
+             const displayFiles = foundFiles.map(f => f.replace(`${baseDir}/`, ''));
+             
+             allAndroidDatabases.push(...displayFiles);
+             lastSuccessfulAppDir = `${baseDir}::${pkg}`;
+             break;
+          }
+        } catch (e) {
+          console.error(`Failed to list databases for app: ${pkg}`);
+        }
+      }
+    }
+
+    if (allAndroidDatabases.length > 0) {
+       results.push({
+        platform: 'android',
+        appDir: lastSuccessfulAppDir,
+        databases: allAndroidDatabases
+      });
+    } else if (targetPlatform === 'android') {
+       throw new Error(`Android Emulator is booted, but no SQLite databases were found in any debuggable third-party packages.`);
+    }
+  }
+  
+  return results;
+}
+
+/**
+ * Finds the DB file based on platform and a provided/detected filename.
+ * If dbNameGlob is empty/undefined, it will auto-select the first discovered database.
+ * Prioritizes iOS (simctl), falls back to Android (adb).
+ * Returns the local file path (either the iOS original or a pulled Android copy).
+ */
+export async function syncDatabase(dbNameGlob?: string, bundleId?: string, targetPlatform?: 'ios' | 'android'): Promise<{ localPath: string, dbName: string, platform: 'ios' | 'android' }[]> {
+  // First, discover available databases
+  const locations = await listDatabases(bundleId, targetPlatform);
+
+  if (locations.length === 0) {
+    if (targetPlatform) {
+       throw new Error(`No SQLite databases found for platform '${targetPlatform}'.`);
+    }
+    throw new Error(`No SQLite databases found on any platform.`);
+  }
+
+  const synced: { localPath: string, dbName: string, platform: 'ios' | 'android' }[] = [];
+
+  for (const loc of locations) {
+    if (targetPlatform && loc.platform !== targetPlatform) continue;
+    
+    let targetDbNames: string[] = [];
+
+    if (!dbNameGlob) {
+      // Auto-select: find the first .db or .sqlite file in this location
+      const preferred = loc.databases.find(d => d.endsWith('.db') || d.endsWith('.sqlite'));
+      if (preferred) {
+        targetDbNames.push(preferred);
+      } else if (loc.databases.length > 0) {
+        targetDbNames.push(loc.databases[0]); // fallback to first file
+      }
+    } else {
+      const globRegex = new RegExp('^' + dbNameGlob.replace(/\*/g, '.*') + '$');
+      targetDbNames = loc.databases.filter(name => globRegex.test(name));
+    }
+
+    for (const targetDbName of targetDbNames) {
+      const { platform, appDir } = loc;
+
+      // --- iOS Logic ---
+      if (platform === 'ios') {
+        if (!appDir) continue;
+        
+        // Find the exact path of the targetDbName
+        const findCmd = `find "${appDir}" -type f -name "${targetDbName}" -maxdepth 7 -print | head -n 1`;
+        try {
+          const found = execSync(findCmd, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 5000 }).toString().trim();
+          if (found && fs.existsSync(found)) {
+            console.error(`Located iOS DB at: ${found}`);
+            synced.push({ localPath: found, dbName: targetDbName, platform: 'ios' });
+          }
+        } catch (e) {
+           console.error(`Failed to locate full path for iOS DB: ${targetDbName}`);
+        }
+        continue;
+      }
+
+      // --- Android Logic ---
+      if (!appDir || !appDir.includes("::")) {
+        console.error(`Invalid Android appDir format: ${appDir}`);
+        continue;
+      }
+      
+      const [targetDbDir, targetPkg] = appDir.split("::");
+      
+      try {
+        execSync(`adb shell am force-stop ${targetPkg}`, { stdio: ['pipe', 'pipe', 'ignore'], timeout: 3000 });
+      } catch (e) {
+        console.error(`Failed to force-stop app: ${targetPkg}`);
+      }
+
+      const tmpdir = fs.mkdtempSync(path.join(os.tmpdir(), "rn-sqlite-mcp-"));
+      const safeLocalName = targetDbName.replace(/\//g, '_');
+      const localDb = path.join(tmpdir, safeLocalName);
+      const localWal = `${localDb}-wal`;
+      const localShm = `${localDb}-shm`;
+
+      const remoteMain = `${targetDbDir}/${targetDbName}`;
+      const remoteWal = `${remoteMain}-wal`;
+      const remoteShm = `${remoteMain}-shm`;
+
+   
+      const pullOne = (remote: string, local: string) => {
+        try {
+          const remoteBase = path.basename(remote);
+          const tmpRemote = `/data/local/tmp/${targetPkg}_${remoteBase}_${Date.now()}`;
+          
+          execSync(`adb shell "run-as '${targetPkg}' cat '${remote}' > '${tmpRemote}'"`, { stdio: 'ignore', timeout: 5000 });
+          execSync(`adb pull '${tmpRemote}' '${local}'`, { stdio: 'ignore', timeout: 5000 });
+          execSync(`adb shell rm '${tmpRemote}'`, { stdio: 'ignore', timeout: 3000 });
+          
+          return fs.existsSync(local) && fs.statSync(local).size > 0;
+        } catch (e) {
+          if (fs.existsSync(local)) fs.unlinkSync(local);
+          return false;
+        }
+      };
+
+      if (!pullOne(remoteMain, localDb)) {
+        console.error(`Failed to pull main DB file from Android: ${remoteMain}`);
+        continue;
+      }
+
+      pullOne(remoteWal, localWal);
+      pullOne(remoteShm, localShm);
+
+      console.error(`Pulled Android DB to local temp: ${localDb}`);
+      synced.push({ localPath: localDb, dbName: targetDbName, platform: 'android' });
+    }
+  }
+
+  if (synced.length === 0) {
+    throw new Error(`Failed to sync any databases matching '${dbNameGlob || 'auto-select'}'.`);
+  }
+
+  return synced;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}