@airabbit/sqlite-mcp-server 0.1.3

package/README.md

@@ -0,0 +1,91 @@
+## Generic SQLite MCP Server
+
+This folder contains a **self-contained, generic Model Context Protocol (MCP) server** for SQLite.
+It is completely independent from the rest of the repo and can be reused with any SQLite database.
+
+### Capabilities
+
+The server exposes these tools:
+
+- **`sqlite_list_tables`**: list tables in the database (optionally filtered by a LIKE pattern).
+- **`sqlite_get_table_info`**: describe a table (columns, types, PK info, row count, optional sample rows).
+- **`sqlite_run_query`**: run a **read-only `SELECT`** query with positional parameters.
+- **`sqlite_get_db_info`**: basic info about the DB file (path, size, timestamps).
+
+All results are returned as JSON text in the MCP response.
+
+### Database configuration
+
+The server locates the SQLite file using:
+
+1. `SQLITE_DB_PATH` environment variable (preferred).
+2. `MCP_DB_PATH` environment variable (fallback).
+3. `./database.sqlite` in the current working directory (development default).
+
+The database is opened in **read-only** mode.
+
+### Install & build
+
+From the `sqlite-mcp-server` directory:
+
+```bash
+npm install
+npm run build
+```
+
+### Run
+
+Set the database path and start the MCP server:
+
+```bash
+SQLITE_DB_PATH=/absolute/path/to/your.sqlite npm start
+```
+
+The server runs over **stdio**, as required by MCP clients (e.g. Claude Desktop, Cursor MCP, etc.).
+
+### Example Database
+
+An example SQLite database (`example-small.sqlite`) is included with sample data:
+- `users` table: 3 users (Alice, Bob, Charlie)
+- `posts` table: 3 posts linked to users
+
+### Claude Desktop Configuration
+
+Add this to your Claude Desktop config file (usually `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "@airabbit/sqlite-mcp-server": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/sqlite-mcp-server/build/index.js"
+      ],
+      "env": {
+        "SQLITE_DB_PATH": "/absolute/path/to/your/database.sqlite"
+      }
+    }
+  }
+}
+```
+
+**Example with included database:**
+```json
+{
+  "mcpServers": {
+    "@airabbit/sqlite-mcp-server": {
+      "command": "node",
+      "args": [
+        "/path/to/sqlite-mcp-server/build/index.js"
+      ],
+      "env": {
+        "SQLITE_DB_PATH": "/path/to/sqlite-mcp-server/example-small.sqlite"
+      }
+    }
+  }
+}
+```
+
+Replace the paths with your actual installation path and database file path.
+
+

package/build/index.js

@@ -0,0 +1,453 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+function resolveDbPath() {
+    let envPath = process.env.SQLITE_DB_PATH || process.env.MCP_DB_PATH;
+    if (envPath) {
+        // If host failed to substitute template (still contains ${user_config.db_path}),
+        // try to read the actual configured value from manifest.json
+        if (envPath.includes('${user_config.db_path}')) {
+            try {
+                const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+                const manifestPath = path.join(moduleDir, '..', 'manifest.json');
+                if (fs.existsSync(manifestPath)) {
+                    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                    const userConfig = manifest.user_config?.db_path;
+                    if (userConfig?.default && typeof userConfig.default === 'string') {
+                        let resolvedPath = userConfig.default;
+                        // Resolve ${__dirname} if present
+                        if (resolvedPath.includes('${__dirname}')) {
+                            resolvedPath = resolvedPath.replace(/\$\{__dirname\}/g, path.join(moduleDir, '..'));
+                        }
+                        envPath = resolvedPath;
+                        console.error(`SQLite MCP: resolved template to configured default: ${envPath}`);
+                    }
+                }
+            }
+            catch (e) {
+                console.error(`SQLite MCP: failed to read manifest for template resolution: ${e}`);
+            }
+        }
+        // Use the env path (either original or resolved from manifest)
+        if (envPath) {
+            return path.resolve(envPath);
+        }
+    }
+    // Default: cwd/database.sqlite for local dev if no env var is set
+    return path.join(process.cwd(), 'database.sqlite');
+}
+export class SqliteMcpServer {
+    constructor() {
+        this.db = null;
+        this.dbErrorReason = null;
+        this.dbPath = resolveDbPath();
+        this.server = new Server({
+            name: 'sqlite-mcp-server',
+            version: '0.1.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.server.onerror = (error) => {
+            console.error('[SQLite MCP Error]', error);
+        };
+        process.on('SIGINT', async () => {
+            await this.server.close();
+            if (this.db) {
+                this.db.close();
+            }
+            process.exit(0);
+        });
+        this.initializeDatabase();
+        this.setupToolHandlers();
+    }
+    initializeDatabase() {
+        try {
+            console.error(`SQLite MCP: attempting to open DB at ${this.dbPath}`);
+            if (!fs.existsSync(this.dbPath)) {
+                const msg = `SQLite database file not found at: ${this.dbPath}`;
+                console.error(msg);
+                this.dbErrorReason = msg;
+                return;
+            }
+            this.db = new Database(this.dbPath, { readonly: true });
+            console.error(`SQLite MCP: connected to ${this.dbPath}`);
+        }
+        catch (error) {
+            const msg = `Failed to initialize SQLite database: ${error.message}`;
+            console.error(msg, error);
+            this.dbErrorReason = msg + (error.stack ? `\nStack: ${error.stack}` : '');
+        }
+    }
+    ensureDb() {
+        if (!this.db) {
+            const reason = this.dbErrorReason || 'Database not initialized';
+            throw new McpError(ErrorCode.InternalError, reason);
+        }
+        return this.db;
+    }
+    setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'sqlite_list_tables',
+                    description: 'List tables in the SQLite database (optionally filter by pattern).',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            like: {
+                                type: 'string',
+                                description: "Optional LIKE pattern to filter table names (e.g., 'user%'). Uses SQLite LIKE semantics.",
+                            },
+                        },
+                    },
+                },
+                {
+                    name: 'sqlite_get_table_info',
+                    description: 'Describe a table: columns, types, primary key info, row count, and optional sample rows.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            table: {
+                                type: 'string',
+                                description: 'Table name to inspect.',
+                            },
+                            sampleRows: {
+                                type: 'number',
+                                description: 'Number of sample rows to fetch (default 5, max 100).',
+                                minimum: 0,
+                                maximum: 100,
+                            },
+                        },
+                        required: ['table'],
+                    },
+                },
+                {
+                    name: 'sqlite_run_query',
+                    description: 'Run a read-only SQL query (SELECT only) against the SQLite database and return the rows.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            sql: {
+                                type: 'string',
+                                description: 'SQL query to execute. Must be a single SELECT statement.',
+                            },
+                            params: {
+                                type: 'array',
+                                description: 'Positional parameters for the query (e.g., ["foo", 123]). Use ? placeholders in SQL.',
+                                items: {},
+                            },
+                            maxRows: {
+                                type: 'number',
+                                description: 'Maximum number of rows to return (default 100, max 1000).',
+                                minimum: 1,
+                                maximum: 1000,
+                            },
+                        },
+                        required: ['sql'],
+                    },
+                },
+                {
+                    name: 'sqlite_get_db_info',
+                    description: 'Return basic information about the SQLite database (path, size, tables count).',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                },
+                {
+                    name: 'sqlite_set_db_path',
+                    description: 'Change the SQLite database file at runtime. Closes current connection and opens the new database.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            path: {
+                                type: 'string',
+                                description: 'Absolute path to the SQLite database file to open.',
+                            },
+                        },
+                        required: ['path'],
+                    },
+                },
+                {
+                    name: 'sqlite_list_databases',
+                    description: 'List SQLite database files (.sqlite, .db, .sqlite3) in a given folder. Checks folder access first.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            folder: {
+                                type: 'string',
+                                description: 'Absolute path to the folder to search for SQLite files.',
+                            },
+                        },
+                        required: ['folder'],
+                    },
+                },
+            ],
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                const args = request.params.arguments;
+                switch (request.params.name) {
+                    case 'sqlite_list_tables':
+                        return this.handleListTables(args);
+                    case 'sqlite_get_table_info':
+                        return this.handleGetTableInfo(args);
+                    case 'sqlite_run_query':
+                        return this.handleRunQuery(args);
+                    case 'sqlite_get_db_info':
+                        return this.handleGetDbInfo();
+                    case 'sqlite_set_db_path':
+                        return this.handleSetDbPath(args);
+                    case 'sqlite_list_databases':
+                        return this.handleListDatabases(args);
+                    default:
+                        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+                }
+            }
+            catch (error) {
+                const message = error instanceof McpError ? error.message : `SQLite MCP tool error: ${error.message}`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: message,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    handleListTables(args) {
+        const db = this.ensureDb();
+        const like = args?.like;
+        let sql = `
+      SELECT name 
+      FROM sqlite_master 
+      WHERE type = 'table'
+    `;
+        const params = [];
+        if (like) {
+            sql += ' AND name LIKE ?';
+            params.push(like);
+        }
+        sql += ' ORDER BY name';
+        const stmt = db.prepare(sql);
+        const rows = stmt.all(...params);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(rows, null, 2),
+                },
+            ],
+        };
+    }
+    handleGetTableInfo(args) {
+        if (!args || !args.table) {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing required "table" parameter');
+        }
+        const db = this.ensureDb();
+        const table = args.table;
+        const sampleRows = Math.max(0, Math.min(typeof args.sampleRows === 'number' ? args.sampleRows : 5, 100));
+        // Schema info
+        const pragmaStmt = db.prepare(`PRAGMA table_info(${JSON.stringify(table).slice(1, -1)})`);
+        const columns = pragmaStmt.all();
+        // Row count
+        const countStmt = db.prepare(`SELECT COUNT(*) as count FROM "${table}"`);
+        const countRow = countStmt.get();
+        let samples = [];
+        if (sampleRows > 0) {
+            const sampleStmt = db.prepare(`SELECT * FROM "${table}" LIMIT ${sampleRows}`);
+            samples = sampleStmt.all();
+        }
+        const info = {
+            table,
+            columns,
+            rowCount: countRow?.count ?? 0,
+            sampleRows: samples,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(info, null, 2),
+                },
+            ],
+        };
+    }
+    handleRunQuery(args) {
+        if (!args || !args.sql) {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing required "sql" parameter');
+        }
+        const db = this.ensureDb();
+        // Normalize SQL: trim and drop trailing semicolons; still reject multiple statements
+        const trimmed = args.sql.trim();
+        const sql = trimmed.replace(/;+\s*$/g, ''); // allow a trailing semicolon
+        // Enforce read-only: only allow single SELECT statement
+        const lower = sql.toLowerCase();
+        if (!lower.startsWith('select')) {
+            throw new McpError(ErrorCode.InvalidParams, 'Only read-only SELECT queries are allowed in sqlite_run_query');
+        }
+        // Reject any remaining semicolons (would indicate additional statements)
+        if (sql.includes(';')) {
+            throw new McpError(ErrorCode.InvalidParams, 'Multiple statements are not allowed; provide a single SELECT query (trailing semicolon is optional)');
+        }
+        const maxRows = Math.max(1, Math.min(typeof args.maxRows === 'number' ? args.maxRows : 100, 1000));
+        const params = Array.isArray(args.params) ? args.params : [];
+        const stmt = db.prepare(sql);
+        let rows = stmt.all(...params);
+        if (rows.length > maxRows) {
+            rows = rows.slice(0, maxRows);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        rowCount: rows.length,
+                        rows,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    handleGetDbInfo() {
+        const dbExists = fs.existsSync(this.dbPath);
+        const stats = dbExists ? fs.statSync(this.dbPath) : null;
+        const info = {
+            path: this.dbPath,
+            exists: dbExists,
+            sizeBytes: stats?.size ?? null,
+            modifiedAt: stats?.mtime?.toISOString() ?? null,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(info, null, 2),
+                },
+            ],
+        };
+    }
+    handleSetDbPath(args) {
+        if (!args || !args.path) {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing required "path" parameter');
+        }
+        const newPath = path.resolve(args.path);
+        // Validate file exists
+        if (!fs.existsSync(newPath)) {
+            throw new McpError(ErrorCode.InvalidParams, `SQLite database file not found at: ${newPath}`);
+        }
+        try {
+            // Close current DB if open
+            if (this.db) {
+                this.db.close();
+                this.db = null;
+            }
+            // Clear error state
+            this.dbErrorReason = null;
+            // Open new database
+            this.dbPath = newPath;
+            this.db = new Database(newPath, { readonly: true });
+            console.error(`SQLite MCP: switched to database at ${newPath}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            path: newPath,
+                            message: `Successfully switched to database at ${newPath}`,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const msg = `Failed to open SQLite database at ${newPath}: ${error.message}`;
+            console.error(msg, error);
+            this.dbErrorReason = msg + (error.stack ? `\nStack: ${error.stack}` : '');
+            throw new McpError(ErrorCode.InternalError, msg);
+        }
+    }
+    handleListDatabases(args) {
+        if (!args || !args.folder) {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing required "folder" parameter');
+        }
+        const folderPath = path.resolve(args.folder);
+        // Check if folder exists
+        if (!fs.existsSync(folderPath)) {
+            throw new McpError(ErrorCode.InvalidParams, `Folder does not exist: ${folderPath}`);
+        }
+        // Check if it's actually a directory
+        const stats = fs.statSync(folderPath);
+        if (!stats.isDirectory()) {
+            throw new McpError(ErrorCode.InvalidParams, `Path is not a directory: ${folderPath}`);
+        }
+        // Check read access
+        try {
+            fs.accessSync(folderPath, fs.constants.R_OK);
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Access denied: Cannot read folder ${folderPath}. ${error.message}`);
+        }
+        // List SQLite files
+        try {
+            const files = fs.readdirSync(folderPath);
+            const sqliteFiles = files
+                .filter((file) => {
+                const ext = path.extname(file).toLowerCase();
+                return ext === '.sqlite' || ext === '.db' || ext === '.sqlite3';
+            })
+                .map((file) => {
+                const fullPath = path.join(folderPath, file);
+                try {
+                    const fileStats = fs.statSync(fullPath);
+                    return {
+                        name: file,
+                        path: fullPath,
+                        sizeBytes: fileStats.size,
+                        modifiedAt: fileStats.mtime.toISOString(),
+                    };
+                }
+                catch (e) {
+                    // Skip files we can't stat
+                    return null;
+                }
+            })
+                .filter((f) => f !== null);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            folder: folderPath,
+                            count: sqliteFiles.length,
+                            databases: sqliteFiles,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to read folder ${folderPath}: ${error.message}`);
+        }
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('SQLite MCP server running on stdio');
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const server = new SqliteMcpServer();
+    server.run().catch(console.error);
+}

package/manifest.json

@@ -0,0 +1,32 @@
+{
+  "dxt_version": "1",
+  "name": "sqlite-mcp-server",
+  "display_name": "SQLite MCP Server",
+  "version": "0.1.0",
+  "description": "Read-only SQLite MCP server exposing tools to inspect schema, list tables, and run SELECT queries.",
+  "author": {
+    "name": "Airabbit"
+  },
+  "license": "MIT",
+  "server": {
+    "type": "node",
+    "entry_point": "build/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/build/index.js"
+      ]
+    }
+  },
+  "user_config": {
+    "db_path": {
+      "type": "string",
+      "title": "SQLite database path",
+      "description": "Absolute path to the SQLite database file to open in read-only mode.",
+      "default": "${__dirname}/example.sqlite"
+    }
+  }
+}
+
+
+

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@airabbit/sqlite-mcp-server",
+  "version": "0.1.3",
+  "description": "Generic SQLite Model Context Protocol (MCP) server",
+  "main": "build/index.js",
+  "type": "module",
+  "files": [
+    "build/",
+    "manifest.json"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x build/index.js",
+    "prepublishOnly": "npm run build",
+    "start": "node build/index.js",
+    "smoke:test": "npm run build && node test/smoke.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "better-sqlite3": "^8.5.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.4",
+    "@types/node": "^20.4.5",
+    "typescript": "^5.1.6"
+  }
+}