mcp-database-inspector 2.0.1

package/src/database/postgres-connection.ts

@@ -0,0 +1,123 @@
+import pg from 'pg';
+import { URL } from 'url';
+import { DatabaseConnectionOptions, QueryResult, DatabaseType } from './types.js';
+import { Logger } from '../utils/logger.js';
+import { DatabaseError } from '../utils/errors.js';
+
+export class PostgresConnection {
+  static parseConnectionUrl(url: string): DatabaseConnectionOptions {
+    try {
+      const parsedUrl = new URL(url);
+
+      if (parsedUrl.protocol !== 'postgresql:' && parsedUrl.protocol !== 'postgres:') {
+        throw new DatabaseError(`Unsupported protocol: ${parsedUrl.protocol}. Only 'postgresql:' or 'postgres:' is supported.`);
+      }
+
+      const options: DatabaseConnectionOptions = {
+        type: DatabaseType.PostgreSQL,
+        host: parsedUrl.hostname,
+        port: parsedUrl.port ? parseInt(parsedUrl.port) : 5432,
+        user: parsedUrl.username,
+        password: parsedUrl.password,
+        database: parsedUrl.pathname.slice(1), // Remove leading slash
+        reconnect: true
+      };
+
+      // Parse SSL settings from query parameters
+      const searchParams = parsedUrl.searchParams;
+      if (searchParams.has('ssl')) {
+        const sslValue = searchParams.get('ssl');
+        if (sslValue === 'true' || sslValue === '1') {
+          options.ssl = true;
+        } else if (sslValue === 'false' || sslValue === '0') {
+          options.ssl = false;
+        } else if (sslValue === 'no-verify') {
+          options.ssl = { rejectUnauthorized: false };
+        }
+      }
+
+      return options;
+    } catch (error) {
+      throw new DatabaseError(`Invalid connection URL: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  static async createClient(options: DatabaseConnectionOptions): Promise<pg.Client> {
+    try {
+      Logger.info(`Connecting to PostgreSQL database at ${options.host}:${options.port}/${options.database}`);
+
+      const clientConfig: pg.ClientConfig = {
+        host: options.host,
+        port: options.port,
+        user: options.user,
+        password: options.password,
+        database: options.database,
+      };
+
+      if (options.ssl) {
+        clientConfig.ssl = options.ssl;
+      }
+
+      const client = new pg.Client(clientConfig);
+      await client.connect();
+
+      // Test the connection
+      await client.query('SELECT 1');
+
+      Logger.info(`Successfully connected to PostgreSQL database: ${options.database}`);
+      return client;
+    } catch (error) {
+      Logger.error(`Failed to connect to PostgreSQL database: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      throw new DatabaseError(`Connection failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  static async executeQuery(client: pg.Client, query: string, params?: any[]): Promise<QueryResult> {
+    try {
+      Logger.debug(`Executing PostgreSQL query: ${query.substring(0, 100)}${query.length > 100 ? '...' : ''}`);
+
+      // PostgreSQL uses $1, $2 for parameters, but if we receive ? from MySQL style queries
+      // we might need translation, but for now we expect raw compatibility or manual handling
+      const res = await client.query(query, params);
+
+      const result: QueryResult = {
+        rows: res.rows,
+        fields: res.fields.map((f: any) => ({ name: f.name, type: f.dataTypeID })),
+      };
+
+      Logger.debug(`Query executed successfully, returned ${result.rows.length} rows`);
+      return result;
+    } catch (error) {
+      Logger.error(
+        `PostgreSQL query execution failed: ${error instanceof Error ? error.message : 'Unknown error'}\n` +
+        `Full SQL: ${query}\n` +
+        `Params: ${JSON.stringify(params)}`
+      );
+      throw new DatabaseError(`Query execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  static async closeConnection(client: pg.Client): Promise<void> {
+    try {
+      await client.end();
+      Logger.info('PostgreSQL connection closed successfully');
+    } catch (error) {
+      Logger.warn(`Error closing PostgreSQL connection: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  static async testConnection(options: DatabaseConnectionOptions): Promise<boolean> {
+    let client: pg.Client | null = null;
+    try {
+      client = await this.createClient(options);
+      return true;
+    } catch (error) {
+      Logger.warn(`PostgreSQL connection test failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return false;
+    } finally {
+      if (client) {
+        await this.closeConnection(client);
+      }
+    }
+  }
+}

package/src/database/types.ts

@@ -0,0 +1,93 @@
+export enum DatabaseType {
+  MySQL = 'mysql',
+  PostgreSQL = 'postgresql'
+}
+
+export interface DatabaseConfig {
+  name: string;
+  url: string;
+  type: DatabaseType;
+  connection: any | null; // Can be mysql.Connection or pg.Client
+  lastUsed: Date;
+  host: string;
+  port: number;
+  username: string;
+  password?: string;
+  database: string;
+  ssl?: boolean | any;
+}
+
+export interface DatabaseInfo {
+  name: string;
+  type: DatabaseType;
+  connected: boolean;
+  lastUsed: Date;
+  host: string;
+  database: string;
+}
+
+export interface TableInfo {
+  tableName: string;
+  tableType: string;
+  engine?: string;
+  tableRows?: number;
+  tableComment?: string;
+}
+
+export interface ColumnInfo {
+  columnName: string;
+  dataType: string;
+  isNullable: string;
+  columnDefault?: any;
+  isPrimaryKey: boolean;
+  isAutoIncrement: boolean;
+  columnComment?: string;
+  characterMaximumLength?: number;
+  numericPrecision?: number;
+  numericScale?: number;
+}
+
+export interface ForeignKeyInfo {
+  constraintName: string;
+  tableName: string;
+  columnName: string;
+  referencedTableName: string;
+  referencedColumnName: string;
+  updateRule?: string;
+  deleteRule?: string;
+}
+
+export interface IndexInfo {
+  tableName: string;
+  indexName: string;
+  columnName: string;
+  nonUnique: boolean;
+  indexType?: string;
+  cardinality?: number;
+  subPart?: number;
+  nullable: boolean;
+  isPrimary?: boolean;
+}
+
+export interface QueryResult {
+  rows: any[];
+  fields: any[];
+}
+
+export interface ValidationResult {
+  isValid: boolean;
+  error?: string;
+  warnings?: string[];
+}
+
+export interface DatabaseConnectionOptions {
+  type: DatabaseType;
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+  ssl?: boolean | object;
+  // timeout and acquireTimeout are not valid for Connection configs and should not be used
+  reconnect?: boolean;
+}

package/src/index.ts

@@ -0,0 +1,136 @@
+import { DatabaseInspectorServer } from './server.js';
+import { Logger } from './utils/logger.js';
+import { InputValidator } from './validators/input-validator.js';
+
+async function main() {
+  try {
+    // Parse command line arguments
+    const args = process.argv.slice(2);
+
+    if (args.length === 0) {
+      console.error(`
+Usage: mcp-database-inspector <database_url1> [database_url2] [database_url3] ...
+
+Examples:
+  # Single MySQL database
+  mcp-database-inspector "mysql://user:password@localhost:3306/mydb"
+
+  # Single PostgreSQL database
+  mcp-database-inspector "postgresql://user:password@localhost:5432/mydb"
+
+  # Mixed databases
+  mcp-database-inspector \\
+    "mysql://user:pass@mysql-host:3306/orders" \\
+    "postgresql://user:pass@pg-host:5432/analytics"
+
+  # With SSL
+  mcp-database-inspector "mysql://user:pass@localhost:3306/db?ssl=true"
+
+Environment Variables:
+  LOG_LEVEL - Set logging level (error, warn, info, debug, trace)
+              Default: info
+
+Database URL Format:
+  mysql://username:password@hostname:port/database?options
+  postgresql://username:password@hostname:port/database?options
+
+Supported Options:
+  - ssl=true/false - Enable/disable SSL connection
+  - timeout=30 - Connection timeout in seconds (default: 30)
+`);
+      process.exit(1);
+    }
+
+    // Set log level from environment
+    const logLevel = process.env.LOG_LEVEL?.toLowerCase();
+    if (logLevel && ['error', 'warn', 'info', 'debug', 'trace'].includes(logLevel)) {
+      Logger.setLogLevel(logLevel as any);
+    }
+
+    Logger.info('MCP Database Inspector starting...');
+    Logger.info(`Log level: ${Logger.getLogLevel()}`);
+
+    // Validate connection URLs
+    const connectionUrls: string[] = [];
+    for (const url of args) {
+      Logger.debug(`Validating connection URL: ${InputValidator.sanitizeForLogging(url)}`);
+
+      const validation = InputValidator.validateConnectionUrl(url);
+      if (!validation.isValid) {
+        Logger.error(`Invalid connection URL: ${validation.error}`);
+        console.error(`Error: Invalid connection URL - ${validation.error}`);
+        process.exit(1);
+      }
+
+      connectionUrls.push(url);
+      Logger.debug(`Connection URL validated successfully`);
+    }
+
+    Logger.info(`Validated ${connectionUrls.length} connection URL(s)`);
+
+    // Create and initialize server
+    const server = new DatabaseInspectorServer();
+
+    // Set up graceful shutdown
+    let isShuttingDown = false;
+    const shutdownHandler = async () => {
+      if (isShuttingDown) return;
+      isShuttingDown = true;
+
+      Logger.info('Shutting down...');
+      try {
+        await server.shutdown();
+      } catch (error) {
+        Logger.error('Error during shutdown:', error);
+      }
+      process.exit(0);
+    };
+
+    process.on('SIGINT', shutdownHandler);
+    process.on('SIGTERM', shutdownHandler);
+
+    // Initialize with database connections
+    Logger.info('Initializing database connections...');
+    await server.initialize(connectionUrls);
+
+    // Get server info for logging
+    const serverInfo = await server.getServerInfo();
+    Logger.info('Server initialization complete', {
+      connectedDatabases: serverInfo.connectedDatabases,
+      databases: serverInfo.databases.map((db: any) => db.name),
+      status: serverInfo.status
+    });
+
+    // Start the server
+    await server.run();
+
+    // This point should not be reached as the server runs indefinitely
+    Logger.warn('Server.run() returned unexpectedly');
+
+  } catch (error) {
+    Logger.error('Fatal error during startup:', error);
+    console.error(`Fatal error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    process.exit(1);
+  }
+}
+
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (reason, promise) => {
+  Logger.error('Unhandled Promise Rejection:', { promise, reason });
+  console.error('Unhandled Promise Rejection:', reason);
+  process.exit(1);
+});
+
+// Handle uncaught exceptions
+process.on('uncaughtException', (error) => {
+  Logger.error('Uncaught Exception:', error);
+  console.error('Uncaught Exception:', error.message);
+  process.exit(1);
+});
+
+// Start the application
+main().catch((error) => {
+  Logger.error('Error in main function:', error);
+  console.error('Startup error:', error.message);
+  process.exit(1);
+});

package/src/server.ts

@@ -0,0 +1,254 @@
+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 { DatabaseManager } from './database/manager.js';
+import { Logger } from './utils/logger.js';
+import { createErrorResponse, ToolError } from './utils/errors.js';
+
+// Import tool handlers
+import {
+  listDatabasesToolDefinition,
+  handleListDatabases
+} from './tools/list-databases.js';
+import {
+  listTablesToolDefinition,
+  handleListTables
+} from './tools/list-tables.js';
+import {
+  inspectTableToolDefinition,
+  handleInspectTable
+} from './tools/inspect-table.js';
+import {
+  getForeignKeysToolDefinition,
+  handleGetForeignKeys
+} from './tools/get-foreign-keys.js';
+import {
+  getIndexesToolDefinition,
+  handleGetIndexes
+} from './tools/get-indexes.js';
+
+import {
+  informationSchemaQueryToolDefinition,
+  handleInformationSchemaQuery
+} from './tools/information-schema-query.js';
+
+import {
+  executeQueryToolDefinition,
+  handleExecuteQuery
+} from './tools/execute-query.js';
+
+import {
+  analyzeQueryToolDefinition,
+  handleAnalyzeQuery
+} from './tools/analyze-query.js';
+
+export class DatabaseInspectorServer {
+  private server: Server;
+  private dbManager: DatabaseManager;
+
+  constructor() {
+    this.server = new Server(
+      {
+        name: 'mcp-database-inspector',
+        version: '2.0.1',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.dbManager = new DatabaseManager();
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      Logger.debug('Received list_tools request');
+
+      return {
+        tools: [
+          listDatabasesToolDefinition,
+          listTablesToolDefinition,
+          inspectTableToolDefinition,
+          getForeignKeysToolDefinition,
+          getIndexesToolDefinition,
+          informationSchemaQueryToolDefinition,
+          executeQueryToolDefinition,
+          analyzeQueryToolDefinition
+        ]
+      };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      Logger.info(`Received tool call: ${name}`);
+      Logger.debug(`Tool arguments:`, args);
+
+      try {
+        switch (name) {
+          case 'list_databases':
+            return await handleListDatabases(args, this.dbManager);
+
+          case 'list_tables':
+            return await handleListTables(args, this.dbManager);
+
+          case 'inspect_table':
+            return await handleInspectTable(args, this.dbManager);
+
+          case 'get_foreign_keys':
+            return await handleGetForeignKeys(args, this.dbManager);
+
+          case 'get_indexes':
+            return await handleGetIndexes(args, this.dbManager);
+
+          case 'information_schema_query':
+            return await handleInformationSchemaQuery(args, this.dbManager);
+
+          case 'execute_query':
+            return await handleExecuteQuery(args, this.dbManager);
+
+          case 'analyze_query':
+            return await handleAnalyzeQuery(args, this.dbManager);
+
+          default:
+            Logger.warn(`Unknown tool requested: ${name}`);
+            throw new ToolError(`Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        Logger.error(`Error executing tool ${name}:`, error);
+
+        const errorResponse = createErrorResponse(error instanceof Error ? error : new Error('Unknown error'));
+
+        return {
+          content: [{
+            type: 'text',
+            text: `Error: ${errorResponse.error}`
+          }],
+          isError: true
+        };
+      }
+    });
+
+    // Handle server errors
+    this.server.onerror = (error) => {
+      Logger.error('Server error:', error);
+    };
+  }
+
+  async initialize(connectionUrls: string[]): Promise<void> {
+    Logger.info('Initializing MySQL Inspector Server');
+    Logger.info(`Connection URLs provided: ${connectionUrls.length}`);
+
+    if (connectionUrls.length === 0) {
+      throw new Error('At least one database connection URL is required');
+    }
+
+    // Add databases to manager
+    for (let i = 0; i < connectionUrls.length; i++) {
+      const url = connectionUrls[i];
+      try {
+        Logger.info(`Adding database connection ${i + 1}/${connectionUrls.length}`);
+        const dbName = await this.dbManager.addDatabase(url);
+        Logger.info(`Successfully added database: ${dbName}`);
+      } catch (error) {
+        Logger.error(`Failed to add database from URL: ${url}`, error);
+        // Continue with other databases instead of failing completely
+      }
+    }
+
+    const databases = this.dbManager.listDatabases();
+    if (databases.length === 0) {
+      throw new Error('No valid database connections could be established');
+    }
+
+    Logger.info(`Server initialized with ${databases.length} database(s): ${databases.map(db => db.name).join(', ')}`);
+  }
+
+  async run(): Promise<void> {
+    Logger.info('Starting MySQL Inspector MCP Server');
+
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    Logger.info('Server started and listening for requests');
+  }
+
+  async shutdown(): Promise<void> {
+    Logger.info('Shutting down MySQL Inspector Server');
+
+    try {
+      await this.dbManager.cleanup();
+      Logger.info('Database connections cleaned up');
+    } catch (error) {
+      Logger.error('Error during database cleanup:', error);
+    }
+
+    Logger.info('Server shutdown complete');
+  }
+
+  // Utility methods for external use
+  getDatabaseManager(): DatabaseManager {
+    return this.dbManager;
+  }
+
+  async getServerInfo(): Promise<any> {
+    const databases = this.dbManager.listDatabases();
+    return {
+      serverName: 'mcp-database-inspector',
+      version: '2.0.0',
+      connectedDatabases: databases.length,
+      databases: databases.map(db => ({
+        name: db.name,
+        host: db.host,
+        database: db.database,
+        connected: db.connected,
+        lastUsed: db.lastUsed.toISOString()
+      })),
+      capabilities: [
+        'list_databases',
+        'list_tables',
+        'inspect_table',
+        'get_foreign_keys',
+        'get_foreign_keys',
+        'get_indexes',
+        'information_schema_query',
+        'execute_query',
+        'analyze_query'
+      ],
+      status: databases.length > 0 ? 'ready' : 'no_connections'
+    };
+  }
+}
+
+// Error handling for uncaught exceptions
+process.on('uncaughtException', (error) => {
+  Logger.error('Uncaught exception:', error);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+  Logger.error('Unhandled rejection:', { promise, reason });
+  process.exit(1);
+});
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  Logger.info('Received SIGINT, shutting down gracefully...');
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  Logger.info('Received SIGTERM, shutting down gracefully...');
+  process.exit(0);
+});
+
+export default DatabaseInspectorServer;

package/src/test-defaults.ts

@@ -0,0 +1,63 @@
+import { DatabaseManager } from './database/manager.js';
+import { Logger } from './utils/logger.js';
+
+async function testConnections() {
+  const dbManager = new DatabaseManager();
+
+  // Default credentials
+  const mysqlUrl = 'mysql://root:root@localhost:3306/mysql';
+  const postgresUrl = 'postgresql://postgres:postgres@localhost:5432/postgres';
+
+  Logger.setLogLevel('info');
+  console.log('Starting connectivity test with default credentials...');
+
+  // Test MySQL
+  console.log('\n--- Testing MySQL (root/root) ---');
+  try {
+    const mysqlName = await dbManager.addDatabase(mysqlUrl, 'mysql_default');
+    console.log(`✅ Successfully added MySQL database: ${mysqlName}`);
+
+    const tables = await dbManager.getTables(mysqlName);
+    console.log(`✅ Retrieved ${tables.length} tables from MySQL`);
+    if (tables.length > 0) {
+      const table = tables[0].tableName;
+      console.log(`\n--- Analyzing MySQL Query on ${table} ---`);
+      const analysis = await dbManager.analyzeQuery(mysqlName, `SELECT * FROM ${table} LIMIT 10`);
+      console.log('✅ Analysis Success');
+      console.log('   Cost:', analysis.summary.cost);
+      console.log('   Operations:', analysis.summary.operations.join(', '));
+      if (analysis.summary.potentialIssues.length > 0) {
+        console.log('   ⚠️ Issues:', analysis.summary.potentialIssues.join(', '));
+      }
+    }
+  } catch (error) {
+    console.error(`❌ MySQL test failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  // Test PostgreSQL
+  console.log('\n--- Testing PostgreSQL (postgres/postgres) ---');
+  try {
+    const pgName = await dbManager.addDatabase(postgresUrl, 'postgres_default');
+    console.log(`✅ Successfully added PostgreSQL database: ${pgName}`);
+
+    console.log(`\n--- Analyzing PostgreSQL Query ---`);
+    // Use a system table that always exists
+    const analysis = await dbManager.analyzeQuery(pgName, 'SELECT * FROM pg_catalog.pg_class LIMIT 5');
+    console.log('✅ Analysis Success');
+    console.log('   Cost:', analysis.summary.cost);
+    console.log('   Operations:', analysis.summary.operations.join(', '));
+    if (analysis.summary.potentialIssues.length > 0) {
+      console.log('   ⚠️ Issues:', analysis.summary.potentialIssues.join(', '));
+    }
+  } catch (error) {
+    console.error(`❌ PostgreSQL test failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  await dbManager.cleanup();
+  console.log('\nTest complete.');
+}
+
+testConnections().catch(err => {
+  console.error('Fatal error during test:', err);
+  process.exit(1);
+});