sqlcipher-mcp-server 1.0.0 → 1.0.3

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');
+    }
+}