sqlcipher-mcp-server 1.0.2 → 1.0.3

package/index.js

@@ -1,241 +1,14 @@
 #!/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 { connectDatabase, executeQuery, closeConnection } from './lib/database.js';
-
-/**
- * SQLCipher MCP Server
- * Provides read-only access to SQLCipher-encrypted SQLite databases
- */
-
-// Get database configuration from environment variables
-const DB_PASSWORD = process.env.SQLCIPHER_PASSWORD;
-const DB_PATH = process.env.SQLCIPHER_DATABASE_PATH;
-
-// Create MCP server instance
-const server = new Server(
-    {
-        name: 'sqlcipher-mcp-server',
-        version: '1.0.0',
-    },
-    {
-        capabilities: {
-            tools: {},
-        },
-    }
-);
-
-/**
- * List available tools
- */
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: [
-            {
-                name: 'execute_query',
-                description: 'Execute a SELECT query on a SQLCipher-encrypted SQLite database. Only read-only queries are allowed. Database path can be provided as parameter or via SQLCIPHER_DATABASE_PATH environment variable.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        database_path: {
-                            type: 'string',
-                            description: 'Path to the SQLCipher database file (optional if SQLCIPHER_DATABASE_PATH is set)',
-                        },
-                        query: {
-                            type: 'string',
-                            description: 'SQL SELECT query to execute (read-only)',
-                        },
-                    },
-                    required: ['query'],
-                },
-            },
-        ],
-    };
-});
-
-/**
- * Handle tool execution requests
- */
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-
-    if (name === 'execute_query') {
-        try {
-            // Validate required parameters
-            if (!args || typeof args !== 'object') {
-                throw new Error('Invalid arguments: arguments must be an object');
-            }
-
-            const { database_path, query } = args;
-
-            // Validate query
-            if (!query || typeof query !== 'string') {
-                throw new Error('query is required and must be a string');
-            }
-
-            // Determine database path: use parameter if provided, otherwise use environment variable
-            const dbPath = database_path || DB_PATH;
-            
-            // Validate database_path
-            if (!dbPath || typeof dbPath !== 'string') {
-                throw new Error(
-                    'database_path is required. Provide it as a parameter or set SQLCIPHER_DATABASE_PATH environment variable.'
-                );
-            }
-
-            // Connect to database (password is optional - will work with unencrypted databases)
-            let db = null;
-            try {
-                db = await connectDatabase(dbPath, DB_PASSWORD);
-            } catch (error) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Failed to connect to database: ${error.message}`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-
-            // Execute query
-            try {
-                const result = await executeQuery(db, query);
-
-                // Format results for response
-                const responseText = formatQueryResults(result);
-
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: responseText,
-                        },
-                    ],
-                };
-            } catch (error) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Query execution failed: ${error.message}`,
-                        },
-                    ],
-                    isError: true,
-                };
-            } finally {
-                // Always close the database connection
-                closeConnection(db);
-            }
-        } catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Error: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    } else {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Unknown tool: ${name}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
-
 /**
- * Format query results as a readable string
- * 
- * @param {Object} result - Query result object with columns, rows, and rowCount
- * @returns {string} Formatted result string
+ * SQLCipher MCP Server - Entry Point
+ * Provides read-only access to SQLCipher-encrypted SQLite databases via MCP
  */
-function formatQueryResults(result) {
-    const { columns, rows, rowCount } = result;
-
-    if (rowCount === 0) {
-        return `Query executed successfully. No rows returned.\nColumns: ${columns.join(', ')}`;
-    }
-
-    // Build table-like output
-    let output = `Query executed successfully. ${rowCount} row(s) returned.\n\n`;
-
-    // Add column headers
-    output += `Columns: ${columns.join(' | ')}\n`;
-    output += '-'.repeat(columns.join(' | ').length) + '\n';
-
-    // Add rows (limit to first 1000 rows for display)
-    const displayRows = rows.slice(0, 1000);
-    for (const row of displayRows) {
-        const values = columns.map(col => {
-            const value = row[col];
-            // Handle null/undefined
-            if (value === null || value === undefined) {
-                return 'NULL';
-            }
-            // Convert to string and truncate long values
-            const str = String(value);
-            return str.length > 50 ? str.substring(0, 47) + '...' : str;
-        });
-        output += values.join(' | ') + '\n';
-    }
-
-    if (rows.length > 1000) {
-        output += `\n... (showing first 1000 of ${rowCount} rows)`;
-    }
-
-    // Add JSON representation for programmatic access
-    output += '\n\nJSON representation:\n';
-    output += JSON.stringify(result, null, 2);
-
-    return output;
-}
-
-/**
- * Start the MCP server
- */
-async function main() {
-    // Check if configuration is set (warn but don't fail - might be set later)
-    const warnings = [];
-    
-    if (!DB_PASSWORD) {
-        warnings.push('SQLCIPHER_PASSWORD environment variable is not set. Database connections may fail if password is required.');
-    }
-    
-    if (!DB_PATH) {
-        warnings.push('SQLCIPHER_DATABASE_PATH environment variable is not set. Database path must be provided in each query.');
-    }
-    
-    if (warnings.length > 0) {
-        console.error('Warning: ' + warnings.join(' '));
-    } else {
-        console.error('Configuration loaded: Database path and password set via environment variables.');
-    }
-
-    // Create stdio transport
-    const transport = new StdioServerTransport();
-
-    // Connect server to transport
-    await server.connect(transport);
 
-    console.error('SQLCipher MCP Server running on stdio');
-}
+import { startMcpServer } from './src/server/mcp-server.js';
 
 // Start the server
-main().catch((error) => {
+startMcpServer().catch((error) => {
     console.error('Fatal error starting server:', error);
     process.exit(1);
 });

package/package.json

@@ -1,54 +1,56 @@
 {
   "name": "sqlcipher-mcp-server",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "MCP Server for querying SQLCipher-encrypted SQLite databases",
+  "keywords": [
+    "mcp",
+    "sqlcipher",
+    "sqlite",
+    "database",
+    "model-context-protocol",
+    "encrypted-database",
+    "cursor-ide"
+  ],
+  "homepage": "https://github.com/sathiraguruge/SQLLiteMCP",
+  "bugs": {
+    "url": "https://github.com/sathiraguruge/SQLLiteMCP/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sathiraguruge/SQLLiteMCP.git"
+  },
+  "license": "MIT",
+  "author": "Sathira Guruge",
   "main": "index.js",
-  "type": "module",
   "bin": {
     "sqlcipher-mcp-server": "./index.js"
   },
+  "type": "module",
   "files": [
     "index.js",
+    "server-http.js",
+    "src/**/*",
     "lib/**/*",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "start": "node index.js",
-    "start:http": "node server-http.js",
-    "test:http": "node server-http.js",
     "dev": "nodemon index.js",
+    "start:http": "node server-http.js",
     "dev:http": "nodemon server-http.js",
+    "test:http": "node server-http.js",
     "prepublishOnly": "npm test || exit 0"
   },
-  "keywords": [
-    "mcp",
-    "sqlcipher",
-    "sqlite",
-    "database",
-    "model-context-protocol",
-    "encrypted-database",
-    "cursor-ide"
-  ],
-  "author": "Sathira Guruge",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/sathiraguruge/SQLLiteMCP.git"
-  },
-  "bugs": {
-    "url": "https://github.com/sathiraguruge/SQLLiteMCP/issues"
-  },
-  "homepage": "https://github.com/sathiraguruge/SQLLiteMCP",
-  "engines": {
-    "node": ">=18.0.0"
-  },
   "dependencies": {
     "@journeyapps/sqlcipher": "^5.1.1",
-    "@modelcontextprotocol/sdk": "^0.5.0",
+    "@modelcontextprotocol/sdk": "^1.25.2",
     "express": "^4.22.1"
   },
   "devDependencies": {
     "nodemon": "^3.1.11"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/server-http.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+/**
+ * SQLCipher MCP HTTP Server - Entry Point
+ * HTTP wrapper for testing the SQLCipher MCP Server with tools like Postman
+ */
+
+import { startHttpServer } from './src/server/http-server.js';
+
+// Start the server
+startHttpServer().catch((error) => {
+    console.error('Fatal error starting HTTP server:', error);
+    process.exit(1);
+});

package/src/config/constants.js

@@ -0,0 +1,40 @@
+/**
+ * Application Constants
+ * Central location for all application constants
+ */
+
+export const SERVER_CONFIG = {
+    name: 'sqlcipher-mcp-server',
+    version: '1.0.2',
+    description: 'MCP Server for querying SQLCipher-encrypted SQLite databases',
+};
+
+export const QUERY_CONFIG = {
+    maxDisplayRows: 1000,
+    maxValueLength: 50,
+};
+
+export const HTTP_CONFIG = {
+    defaultPort: 3000,
+};
+
+export const TOOL_DEFINITIONS = {
+    execute_query: {
+        name: 'execute_query',
+        description: 'Execute a SELECT query on a SQLCipher-encrypted SQLite database. Only read-only queries are allowed. Database path can be provided as parameter or via SQLCIPHER_DATABASE_PATH environment variable.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database_path: {
+                    type: 'string',
+                    description: 'Path to the SQLCipher database file (optional if SQLCIPHER_DATABASE_PATH is set)',
+                },
+                query: {
+                    type: 'string',
+                    description: 'SQL SELECT query to execute (read-only)',
+                },
+            },
+            required: ['query'],
+        },
+    },
+};

package/src/config/environment.js

@@ -0,0 +1,63 @@
+/**
+ * Environment Configuration
+ * Manages environment variables and application configuration
+ */
+
+/**
+ * Get database password from environment variable
+ * @returns {string|undefined} Database password or undefined if not set
+ */
+export function getDatabasePassword() {
+    return process.env.SQLCIPHER_PASSWORD;
+}
+
+/**
+ * Get default database path from environment variable
+ * @returns {string|undefined} Database path or undefined if not set
+ */
+export function getDatabasePath() {
+    return process.env.SQLCIPHER_DATABASE_PATH;
+}
+
+/**
+ * Get HTTP server port from environment variable
+ * @param {number} defaultPort - Default port to use if not set
+ * @returns {number} Port number
+ */
+export function getPort(defaultPort = 3000) {
+    return process.env.PORT || defaultPort;
+}
+
+/**
+ * Check if password is configured
+ * @returns {boolean} True if password is set
+ */
+export function isPasswordConfigured() {
+    return !!getDatabasePassword();
+}
+
+/**
+ * Check if database path is configured
+ * @returns {boolean} True if database path is set
+ */
+export function isDatabasePathConfigured() {
+    return !!getDatabasePath();
+}
+
+/**
+ * Get configuration warnings for missing environment variables
+ * @returns {string[]} Array of warning messages
+ */
+export function getConfigurationWarnings() {
+    const warnings = [];
+    
+    if (!isPasswordConfigured()) {
+        warnings.push('SQLCIPHER_PASSWORD environment variable is not set. Database connections may fail if password is required.');
+    }
+    
+    if (!isDatabasePathConfigured()) {
+        warnings.push('SQLCIPHER_DATABASE_PATH environment variable is not set. Database path must be provided in each query.');
+    }
+    
+    return warnings;
+}

package/src/handlers/http-handlers.js

@@ -0,0 +1,89 @@
+/**
+ * HTTP Route Handlers
+ * Handlers for HTTP API endpoints
+ */
+
+import { SERVER_CONFIG } from '../config/constants.js';
+import { getDatabasePassword, isPasswordConfigured } from '../config/environment.js';
+import { validateDatabasePath, validateQuery } from '../utils/validators.js';
+import { executeQueryOnDatabase } from '../services/database-service.js';
+
+/**
+ * Handle health check endpoint
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ */
+export function handleHealthCheck(req, res) {
+    res.json({
+        status: 'ok',
+        message: 'SQLCipher MCP HTTP Server is running',
+        passwordConfigured: isPasswordConfigured(),
+    });
+}
+
+/**
+ * Handle server info endpoint
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ */
+export function handleInfo(req, res) {
+    res.json({
+        name: SERVER_CONFIG.name,
+        version: SERVER_CONFIG.version,
+        description: 'HTTP wrapper for SQLCipher MCP Server',
+        endpoints: {
+            health: 'GET /health',
+            query: 'POST /api/query',
+            info: 'GET /api/info',
+        },
+        passwordConfigured: isPasswordConfigured(),
+    });
+}
+
+/**
+ * Handle query execution endpoint
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ */
+export async function handleQuery(req, res) {
+    try {
+        const { database_path, query } = req.body;
+        
+        // Validate database_path
+        try {
+            validateDatabasePath(database_path);
+        } catch (error) {
+            return res.status(400).json({ error: error.message });
+        }
+        
+        // Validate query
+        try {
+            validateQuery(query);
+        } catch (error) {
+            return res.status(400).json({ error: error.message });
+        }
+        
+        // Get database password
+        const password = getDatabasePassword();
+        
+        // Execute query
+        try {
+            const result = await executeQueryOnDatabase(database_path, password, query);
+            
+            // Return successful response
+            res.json({
+                success: true,
+                data: result,
+                message: `Query executed successfully. ${result.rowCount} row(s) returned.`,
+            });
+        } catch (error) {
+            res.status(400).json({
+                error: `Query execution failed: ${error.message}`,
+            });
+        }
+    } catch (error) {
+        res.status(500).json({
+            error: `Internal server error: ${error.message}`,
+        });
+    }
+}

package/src/handlers/mcp-handlers.js

@@ -0,0 +1,69 @@
+/**
+ * MCP Tool Handlers
+ * Handlers for MCP tool requests
+ */
+
+import { TOOL_DEFINITIONS } from '../config/constants.js';
+import { getDatabasePassword } from '../config/environment.js';
+import { validateArguments, validateQuery, resolveDatabasePath } from '../utils/validators.js';
+import { formatQueryResults } from '../utils/formatters.js';
+import { createMcpErrorResponse, createMcpSuccessResponse } from '../utils/errors.js';
+import { executeQueryOnDatabase } from '../services/database-service.js';
+
+/**
+ * Handle list tools request
+ * @returns {Object} List of available tools
+ */
+export function handleListTools() {
+    return {
+        tools: [TOOL_DEFINITIONS.execute_query],
+    };
+}
+
+/**
+ * Handle execute_query tool request
+ * @param {Object} args - Tool arguments
+ * @param {string} [args.database_path] - Database path (optional if env var set)
+ * @param {string} args.query - SQL query to execute
+ * @returns {Promise<Object>} MCP response object
+ */
+export async function handleExecuteQuery(args) {
+    try {
+        // Validate arguments
+        validateArguments(args);
+        
+        const { database_path, query } = args;
+        
+        // Validate query
+        validateQuery(query);
+        
+        // Resolve database path
+        const dbPath = resolveDatabasePath(database_path);
+        
+        // Get database password
+        const password = getDatabasePassword();
+        
+        // Execute query
+        try {
+            const result = await executeQueryOnDatabase(dbPath, password, query);
+            
+            // Format results for response
+            const responseText = formatQueryResults(result);
+            
+            return createMcpSuccessResponse(responseText);
+        } catch (error) {
+            return createMcpErrorResponse(`Query execution failed: ${error.message}`);
+        }
+    } catch (error) {
+        return createMcpErrorResponse(`Error: ${error.message}`);
+    }
+}
+
+/**
+ * Handle unknown tool request
+ * @param {string} toolName - Name of the unknown tool
+ * @returns {Object} Error response
+ */
+export function handleUnknownTool(toolName) {
+    return createMcpErrorResponse(`Unknown tool: ${toolName}`);
+}

package/src/server/http-server.js

@@ -0,0 +1,54 @@
+/**
+ * HTTP Server
+ * Express HTTP server setup and initialization
+ */
+
+import express from 'express';
+import { HTTP_CONFIG } from '../config/constants.js';
+import { getPort, isPasswordConfigured } from '../config/environment.js';
+import { handleHealthCheck, handleInfo, handleQuery } from '../handlers/http-handlers.js';
+
+/**
+ * Create and configure Express app
+ * @returns {express.Application} Configured Express app
+ */
+export function createHttpApp() {
+    const app = express();
+    
+    // Middleware to parse JSON request bodies
+    app.use(express.json());
+    
+    // Register routes
+    app.get('/health', handleHealthCheck);
+    app.get('/api/info', handleInfo);
+    app.post('/api/query', handleQuery);
+    
+    return app;
+}
+
+/**
+ * Start the HTTP server
+ * @param {number} [port] - Port to listen on (defaults to env or 3000)
+ * @returns {Promise<void>}
+ */
+export async function startHttpServer(port) {
+    const app = createHttpApp();
+    const serverPort = port || getPort(HTTP_CONFIG.defaultPort);
+    
+    return new Promise((resolve) => {
+        app.listen(serverPort, () => {
+            console.log(`SQLCipher MCP HTTP Server running on http://localhost:${serverPort}`);
+            console.log(`Health check: http://localhost:${serverPort}/health`);
+            console.log(`API info: http://localhost:${serverPort}/api/info`);
+            
+            if (!isPasswordConfigured()) {
+                console.warn('\n⚠️  Warning: SQLCIPHER_PASSWORD environment variable is not set.');
+                console.warn('   Database queries will fail until this is configured.\n');
+            } else {
+                console.log('✅ Database password is configured.\n');
+            }
+            
+            resolve();
+        });
+    });
+}

package/src/server/mcp-server.js

@@ -0,0 +1,76 @@
+/**
+ * MCP Server
+ * Model Context Protocol server setup and initialization
+ */
+
+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 { SERVER_CONFIG } from '../config/constants.js';
+import { getConfigurationWarnings } from '../config/environment.js';
+import { handleListTools, handleExecuteQuery, handleUnknownTool } from '../handlers/mcp-handlers.js';
+
+/**
+ * Create and configure MCP server
+ * @returns {Server} Configured MCP server instance
+ */
+export function createMcpServer() {
+    const server = new Server(
+        {
+            name: SERVER_CONFIG.name,
+            version: SERVER_CONFIG.version,
+        },
+        {
+            capabilities: {
+                tools: {},
+            },
+        }
+    );
+    
+    // Register list tools handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return handleListTools();
+    });
+    
+    // Register tool execution handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        
+        if (name === 'execute_query') {
+            return await handleExecuteQuery(args);
+        } else {
+            return handleUnknownTool(name);
+        }
+    });
+    
+    return server;
+}
+
+/**
+ * Start the MCP server
+ * @returns {Promise<void>}
+ */
+export async function startMcpServer() {
+    // Check configuration and log warnings
+    const warnings = getConfigurationWarnings();
+    if (warnings.length > 0) {
+        console.error('Warning: ' + warnings.join(' '));
+    } else {
+        console.error('Configuration loaded: Database path and password set via environment variables.');
+    }
+    
+    // Create server
+    const server = createMcpServer();
+    
+    // Create stdio transport
+    const transport = new StdioServerTransport();
+    
+    // Connect server to transport
+    await server.connect(transport);
+    
+    console.error('SQLCipher MCP Server running on stdio');
+}

package/src/services/database-service.js

@@ -0,0 +1,55 @@
+/**
+ * Database Service
+ * Service layer that wraps database operations with error handling
+ */
+
+import { connectDatabase, executeQuery, closeConnection } from '../../lib/database.js';
+
+/**
+ * Execute a query on a database
+ * Handles connection, query execution, and cleanup
+ * @param {string} dbPath - Path to the database file
+ * @param {string|undefined} password - Database password (optional)
+ * @param {string} query - SQL query to execute
+ * @returns {Promise<Object>} Query results
+ * @throws {Error} If connection or query execution fails
+ */
+export async function executeQueryOnDatabase(dbPath, password, query) {
+    let db = null;
+    
+    try {
+        // Connect to database
+        db = await connectDatabase(dbPath, password);
+        
+        // Execute query
+        const result = await executeQuery(db, query);
+        
+        return result;
+    } finally {
+        // Always close the database connection
+        if (db) {
+            closeConnection(db);
+        }
+    }
+}
+
+/**
+ * Test database connection
+ * @param {string} dbPath - Path to the database file
+ * @param {string|undefined} password - Database password (optional)
+ * @returns {Promise<boolean>} True if connection successful
+ */
+export async function testDatabaseConnection(dbPath, password) {
+    let db = null;
+    
+    try {
+        db = await connectDatabase(dbPath, password);
+        return true;
+    } catch (error) {
+        throw new Error(`Failed to connect to database: ${error.message}`);
+    } finally {
+        if (db) {
+            closeConnection(db);
+        }
+    }
+}

package/src/utils/errors.js

@@ -0,0 +1,69 @@
+/**
+ * Error Handling Utilities
+ * Standardized error response creation for MCP and HTTP
+ */
+
+/**
+ * Create MCP error response
+ * @param {string} message - Error message
+ * @returns {Object} MCP error response object
+ */
+export function createMcpErrorResponse(message) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: message,
+            },
+        ],
+        isError: true,
+    };
+}
+
+/**
+ * Create MCP success response
+ * @param {string} text - Response text
+ * @returns {Object} MCP success response object
+ */
+export function createMcpSuccessResponse(text) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: text,
+            },
+        ],
+    };
+}
+
+/**
+ * Create HTTP error response
+ * @param {number} statusCode - HTTP status code
+ * @param {string} message - Error message
+ * @returns {Object} HTTP error response object
+ */
+export function createHttpErrorResponse(statusCode, message) {
+    return {
+        statusCode,
+        body: {
+            error: message,
+        },
+    };
+}
+
+/**
+ * Create HTTP success response
+ * @param {Object} data - Response data
+ * @param {string} message - Success message
+ * @returns {Object} HTTP success response object
+ */
+export function createHttpSuccessResponse(data, message) {
+    return {
+        statusCode: 200,
+        body: {
+            success: true,
+            data: data,
+            message: message,
+        },
+    };
+}

package/src/utils/formatters.js

@@ -0,0 +1,64 @@
+/**
+ * Formatting Utilities
+ * Functions for formatting query results and other data
+ */
+
+import { QUERY_CONFIG } from '../config/constants.js';
+
+/**
+ * Format query results as a readable string
+ * @param {Object} result - Query result object with columns, rows, and rowCount
+ * @param {string[]} result.columns - Array of column names
+ * @param {Object[]} result.rows - Array of row objects
+ * @param {number} result.rowCount - Number of rows returned
+ * @returns {string} Formatted result string
+ */
+export function formatQueryResults(result) {
+    const { columns, rows, rowCount } = result;
+
+    if (rowCount === 0) {
+        return `Query executed successfully. No rows returned.\nColumns: ${columns.join(', ')}`;
+    }
+
+    // Build table-like output
+    let output = `Query executed successfully. ${rowCount} row(s) returned.\n\n`;
+
+    // Add column headers
+    output += `Columns: ${columns.join(' | ')}\n`;
+    output += '-'.repeat(columns.join(' | ').length) + '\n';
+
+    // Add rows (limit to first maxDisplayRows for display)
+    const displayRows = rows.slice(0, QUERY_CONFIG.maxDisplayRows);
+    for (const row of displayRows) {
+        const values = columns.map(col => formatCellValue(row[col]));
+        output += values.join(' | ') + '\n';
+    }
+
+    if (rows.length > QUERY_CONFIG.maxDisplayRows) {
+        output += `\n... (showing first ${QUERY_CONFIG.maxDisplayRows} of ${rowCount} rows)`;
+    }
+
+    // Add JSON representation for programmatic access
+    output += '\n\nJSON representation:\n';
+    output += JSON.stringify(result, null, 2);
+
+    return output;
+}
+
+/**
+ * Format a single cell value for display
+ * @param {any} value - Cell value to format
+ * @returns {string} Formatted cell value
+ */
+function formatCellValue(value) {
+    // Handle null/undefined
+    if (value === null || value === undefined) {
+        return 'NULL';
+    }
+    
+    // Convert to string and truncate long values
+    const str = String(value);
+    return str.length > QUERY_CONFIG.maxValueLength 
+        ? str.substring(0, QUERY_CONFIG.maxValueLength - 3) + '...' 
+        : str;
+}

package/src/utils/validators.js

@@ -0,0 +1,58 @@
+/**
+ * Validation Utilities
+ * Input validation and sanitization functions
+ */
+
+import { getDatabasePath } from '../config/environment.js';
+
+/**
+ * Validate that arguments is a valid object
+ * @param {any} args - Arguments to validate
+ * @throws {Error} If args is not a valid object
+ */
+export function validateArguments(args) {
+    if (!args || typeof args !== 'object') {
+        throw new Error('Invalid arguments: arguments must be an object');
+    }
+}
+
+/**
+ * Validate query parameter
+ * @param {any} query - Query to validate
+ * @throws {Error} If query is invalid
+ */
+export function validateQuery(query) {
+    if (!query || typeof query !== 'string') {
+        throw new Error('query is required and must be a string');
+    }
+}
+
+/**
+ * Validate and resolve database path
+ * Uses provided path or falls back to environment variable
+ * @param {string|undefined} providedPath - Database path from arguments
+ * @returns {string} Resolved database path
+ * @throws {Error} If no valid path is available
+ */
+export function resolveDatabasePath(providedPath) {
+    const dbPath = providedPath || getDatabasePath();
+    
+    if (!dbPath || typeof dbPath !== 'string') {
+        throw new Error(
+            'database_path is required. Provide it as a parameter or set SQLCIPHER_DATABASE_PATH environment variable.'
+        );
+    }
+    
+    return dbPath;
+}
+
+/**
+ * Validate database path parameter for HTTP requests
+ * @param {any} database_path - Database path to validate
+ * @throws {Error} If database_path is invalid
+ */
+export function validateDatabasePath(database_path) {
+    if (!database_path || typeof database_path !== 'string') {
+        throw new Error('database_path is required and must be a string');
+    }
+}