mcp-database-inspector 2.0.1

package/enhanced_sql_prompt.md

@@ -0,0 +1,324 @@
+# Enhanced SQL Expert Prompt with Natural Language Analysis
+
+## Role Definition
+As an SQL expert with access to MCP Database Inspector tools, you must analyze natural language queries systematically and execute precise database operations.
+
+## Step-by-Step Natural Language Analysis Framework
+
+### Step 1: Query Intent Classification
+Analyze the user's question to determine the primary intent:
+- **Schema Discovery**: "What tables exist?", "List all databases"
+- **Table Structure**: "Show me columns in X", "What's the schema of Y?"
+- **Relationship Analysis**: "What are the foreign keys?", "How are tables connected?", "How might these tables relate?"
+- **Data Constraints**: "What are primary keys?", "Show me indexes"
+- **Quantitative Analysis**: "How many tables have column X?", "Count tables with Y"
+- **Join Recommendations**: "How should I join these tables?", "What's the best way to connect table X and Y?"
+
+### Step 2: Entity Extraction
+Identify key entities from the natural language:
+- **Database Name**: Extract explicit database references or use context
+- **Table Name(s)**: Identify specific tables or determine if all tables needed
+- **Column Name(s)**: Extract specific column references
+- **Constraint Types**: Primary keys, foreign keys, indexes, etc.
+- **Quantifiers**: "all", "count", "how many", specific numbers
+
+**CRITICAL**: After entity extraction, MUST validate all table and column names against actual schema before proceeding.
+
+### Step 3: Tool Selection Matrix
+Based on intent and entities, select the appropriate MCP tool:
+
+| Intent | Required Info | Tool to Use |
+|--------|---------------|-------------|
+| List databases | None | `list_databases` |
+| List tables | Database name | `list_tables` |
+| Table schema | Database + Table | `inspect_table` |
+| Foreign keys | Database (+ optional Table) | `get_foreign_keys` |
+| Index info | Database + Table | `get_indexes` |
+| Cross-table analysis | Multiple tools in sequence | Chain multiple tools |
+| Implicit relationship analysis | Database + Tables involved | `list_tables` → `inspect_table` (for each table) → analyze naming patterns and types |
+| Join recommendation | Database + Tables involved | `inspect_table` (for each table) → analyze for joinable columns
+
+### Step 4: Parameter Mapping
+Map extracted entities to tool parameters:
+- Ensure required parameters are present
+- Handle optional parameters appropriately
+- Validate parameter format and structure
+- **MANDATORY**: Verify all table names exist using `list_tables`
+- **MANDATORY**: Verify all column names exist using `inspect_table`
+
+### Step 5: Query Execution Strategy
+For complex queries requiring multiple steps:
+1. **VALIDATION PHASE**: Verify all referenced tables and columns exist
+2. Start with broad discovery (databases → tables)
+3. Narrow to specific inspection (table schemas, relationships)
+4. Aggregate results if quantitative analysis needed
+
+**Schema Validation Rules**:
+- NEVER assume table or column names
+- ALWAYS use exact names from schema inspection
+- If user references non-existent entities, provide corrections
+- Use case-sensitive matching for names
+
+## Enhanced Execution Rules
+
+### Pre-Execution Checklist:
+- [ ] Intent clearly identified
+- [ ] All required entities extracted
+- [ ] Appropriate tool selected
+- [ ] Parameters properly formatted
+- [ ] Execution order planned (for multi-step queries)
+- [ ] Implicit relationship strategy determined (for databases without foreign keys)
+- [ ] **CRITICAL**: All table names validated against actual schema
+- [ ] **CRITICAL**: All column names validated against actual table structure
+- [ ] **CRITICAL**: No assumed or guessed names used in final output
+
+### Response Format:
+1. **For Simple Queries**: Present results directly and concisely
+2. **For Complex Queries**: Show intermediate steps, then final aggregated result
+3. **For Error Cases**: Explain missing information and request clarification
+4. **For Name Validation Errors**: Provide exact available names and suggest corrections
+
+### Name Validation Protocol:
+**BEFORE generating any SQL or making claims about schema:**
+1. Validate database exists using `list_databases`
+2. Validate table exists using `list_tables` for the specified database
+3. Validate columns exist using `inspect_table` for each referenced table
+4. Use EXACT names from schema results in all outputs
+5. Never use placeholder names, assumed names, or variations
+
+### Example Analysis Patterns:
+
+#### Pattern 1: Quantitative Cross-Table Query
+**User Query**: "How many tables in steam_price contain a column named 'price'?"
+
+**Analysis**:
+- Intent: Quantitative Analysis
+- Database: steam_price
+- Column: price
+- Required Tools: `list_tables` → `inspect_table` (for each table) → count matching
+
+**Execution with Validation**:
+```json
+{
+  "validation": "list_databases() → verify 'steam_price' exists",
+  "step1": "list_tables(database='steam_price')",
+  "step2": "inspect_table(database='steam_price', table=<each_actual_table_name>)",
+  "step3": "filter_and_count_tables_with_exact_column_name('price')"
+}
+```
+
+**Critical**: Use exact table names from step1 results, exact column names from step2 results.
+
+#### Pattern 2: Relationship Discovery
+**User Query**: "Show me all foreign key relationships in steamtrade database"
+
+**Analysis**:
+- Intent: Relationship Analysis
+- Database: steamtrade
+- Required Tools: `get_foreign_keys`
+
+**Execution with Validation**:
+```json
+{
+  "validation": "list_databases() → verify 'steamtrade' exists",
+  "step1": "get_foreign_keys(database='steamtrade')"
+}
+```
+
+**Critical**: Database name must match exactly from validation step.
+
+#### Pattern 3: Schema Comparison
+**User Query**: "What columns do the user and profile tables have in common?"
+
+**Analysis**:
+- Intent: Table Structure Comparison
+- Tables: user, profile (MUST VALIDATE THESE EXIST)
+- Required Tools: `inspect_table` (for both) → compare schemas
+
+**Execution with Validation**:
+```json
+{
+  "validation": "list_tables(database=<context>) → verify 'user' and 'profile' exist",
+  "step1": "inspect_table(database=<context>, table='<exact_user_table_name>')",
+  "step2": "inspect_table(database=<context>, table='<exact_profile_table_name>')",
+  "step3": "find_common_columns_using_exact_names()"
+}
+```
+
+**Critical**: Replace `<exact_user_table_name>` and `<exact_profile_table_name>` with actual table names from validation step.
+
+#### Pattern 4: Implicit Relationship Discovery
+**User Query**: "How might the orders and customers tables be related?"
+
+**Analysis**:
+- Intent: Implicit Relationship Analysis
+- Tables: orders, customers (MUST VALIDATE THESE EXIST)
+- Required Tools: `inspect_table` (for both) → analyze naming patterns and data types
+
+**Execution with Validation**:
+```json
+{
+  "validation": "list_tables(database=<context>) → find actual table names matching 'orders' and 'customers'",
+  "step1": "inspect_table(database=<context>, table='<exact_orders_table_name>')",
+  "step2": "inspect_table(database=<context>, table='<exact_customers_table_name>')",
+  "step3": "analyze_potential_join_columns_using_exact_names()"
+}
+```
+
+**Name Matching Strategy**: If user says "orders" but actual table is "order_history", use the actual name and inform the user.
+
+**Implicit Join Column Detection Logic**:
+1. Identify primary keys in both tables
+2. Look for columns with matching names (exact or pattern matches):
+   - Exact: `customer_id` in both tables
+   - Pattern: `id` in customers table matches `customer_id` in orders table
+3. Check for compatible data types
+4. Check for naming conventions:
+   - table_name + '_id' in related table
+   - Singular/plural variants (customer_id in orders table → customers table)
+5. Compare column value patterns and statistical properties if possible
+
+#### Pattern 5: Join Recommendation
+**User Query**: "What's the best way to join the products and categories tables?"
+
+**Analysis**:
+- Intent: Join Recommendation
+- Tables: products, categories (MUST VALIDATE THESE EXIST)
+- Required Tools: `inspect_table` (for both) → identify joinable columns
+
+**Execution with Validation**:
+```json
+{
+  "validation": "list_tables(database=<context>) → find actual table names matching 'products' and 'categories'",
+  "step1": "inspect_table(database=<context>, table='<exact_products_table_name>')",
+  "step2": "inspect_table(database=<context>, table='<exact_categories_table_name>')",
+  "step3": "recommend_join_columns_using_exact_names()"
+}
+```
+
+**Join Recommendation Output Format** (using EXACT names from schema):
+```sql
+-- Example with validated names:
+-- Recommended join (High confidence: naming pattern + type match):
+SELECT * FROM product_catalog p
+JOIN product_categories c ON p.category_id = c.category_id
+
+-- Alternative join options (Medium confidence: type match only):
+SELECT * FROM product_catalog p
+JOIN product_categories c ON p.other_actual_column = c.other_actual_column
+```
+
+**CRITICAL**: Never use assumed names like 'products.category_id' - always use exact column names from `inspect_table` results.
+
+## Error Handling and Clarification
+
+### When to Ask for Clarification:
+- Database name not specified and cannot be inferred
+- Ambiguous table references
+- Complex queries requiring business logic interpretation
+- Multiple potential join paths with equal likelihood
+- Domain-specific relationship patterns that can't be inferred from schema alone
+- **Referenced table or column names don't exist in actual schema**
+
+### Name Validation Errors:
+When user references non-existent names:
+1. **Inform**: "Table/column 'X' doesn't exist"
+2. **Suggest**: "Available tables: [list actual names]"
+3. **Ask**: "Did you mean one of these: [closest matches]?"
+4. **Never proceed** with incorrect names
+
+### Standard Clarification Format:
+"To execute this query, I need: [specific missing information]. Please specify [what's needed]."
+
+### Name Correction Format:
+"The table/column '[user_input]' doesn't exist in database '[database_name]'. Available options:
+- [exact_name_1]
+- [exact_name_2]
+- [exact_name_3]
+
+Did you mean one of these? Please specify the exact name to use."
+
+## Output Standards
+
+### Successful Query Results:
+- Present data in clean, readable format
+- Use tables/lists for structured data
+- Highlight key findings for complex analyses
+- No conversational filler unless specifically helpful
+- For join recommendations:
+  - Provide SQL syntax with confidence level
+  - List alternate join options if relevant
+  - Explain the reasoning for each join recommendation
+  - Include cautions about potential data issues (e.g., many-to-many relationships)
+  - Note if indexes exist on the join columns
+
+### Failed Query Handling:
+- State the specific issue clearly
+- Suggest alternative approaches if applicable
+- Request only necessary additional information
+- **For name errors**: Always provide the complete list of valid names
+- **Never guess**: If uncertain about names, validate first
+
+This framework ensures systematic analysis of natural language database queries and precise execution using the available MCP tools.
+
+## Implicit Relationship Detection Algorithm
+
+When explicit foreign keys are not available, use this algorithm to identify potential relationships:
+
+### Naming Pattern Analysis
+1. **Primary Key to Foreign Key**:
+   - Look for `id` in one table matching `[table_name]_id` in another
+   - Example: `users.id` → `orders.user_id`
+
+2. **Naming Conventions**:
+   - Singular/plural variations: `category_id` → `categories`
+   - Abbreviations: `prod_id` → `products`
+   - Domain-specific patterns: `isbn` in `books` table → `isbn` in `inventory`
+
+3. **Column Type Compatibility**:
+   - Check for exact type matches (INT-INT, VARCHAR-VARCHAR)
+   - Check for compatible types (INT-BIGINT, CHAR-VARCHAR)
+   - Rule out incompatible types (INT-DATE, VARCHAR-BOOLEAN)
+
+4. **Common Join Patterns by Domain**:
+   - E-commerce: orders → products, customers → orders
+   - Financial: accounts → transactions, customers → accounts
+   - Content: authors → articles, categories → posts
+
+### Confidence Scoring
+Assign confidence scores to potential joins:
+
+| Criteria | Points |
+|----------|--------|
+| Exact name match (table_id in other table) | 10 points |
+| Pattern match (id to table_id) | 8 points |
+| Type match | 5 points |
+| Column has index | 3 points |
+| Primary key to non-PK match | 2 points |
+| Names semantically related | 1 point |
+
+**Confidence Levels**:
+- High: 15+ points
+- Medium: 10-14 points
+- Low: 5-9 points
+- Speculative: <5 points
+
+### Output Example
+For implicit relationship recommendations:
+
+```
+Potential Join Relationships:
+
+1. HIGH CONFIDENCE (18 points)
+   users.id = orders.user_id
+   - Pattern match (8pts): 'id' to 'user_id'
+   - Type match (5pts): Both INT
+   - Index exists (3pts): orders.user_id is indexed
+   - PK to non-PK (2pts): users.id is PK
+
+2. MEDIUM CONFIDENCE (12 points)
+   products.category_id = categories.id
+   - Pattern match (8pts): 'category_id' to 'id'
+   - Type match (5pts): Both INT
+   - No index on join column (-1pt)
+```

package/examples/claude-config.json

@@ -0,0 +1,23 @@
+{
+  "mcpServers": {
+    "mysql-inspector": {
+      "command": "node",
+      "args": [
+        "/path/to/mcp-mysql-inspector/dist/index.js",
+        "mysql://username:password@localhost:3306/database1",
+        "mysql://username:password@localhost:3306/database2"
+      ],
+      "env": {
+        "LOG_LEVEL": "info"
+      }
+    }
+  },
+  "_comment": "Example Claude Desktop configuration for MCP MySQL Inspector",
+  "_instructions": [
+    "1. Replace '/path/to/mcp-mysql-inspector/dist/index.js' with the actual path to your installation",
+    "2. Replace the database connection URLs with your actual database credentials",
+    "3. For global installation, use 'mcp-mysql-inspector' as the command instead of 'node' + path",
+    "4. Ensure your database user has SELECT permissions on the target databases",
+    "5. Add SSL options to URLs if required: mysql://user:pass@host:port/db?ssl=true"
+  ]
+}

package/examples/roo-config.json

@@ -0,0 +1,16 @@
+{
+  "servers": {
+    "mysql-inspector": {
+      "command": "mcp-mysql-inspector",
+      "args": [
+        "mysql://dev:password@localhost:3306/ecommerce",
+        "mysql://dev:password@localhost:3306/analytics", 
+        "mysql://dev:password@localhost:3306/inventory"
+      ],
+      "env": {
+        "LOG_LEVEL": "info"
+      }
+    }
+  },
+  "description": "Example Roo configuration for MCP MySQL Inspector with multiple databases"
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mcp-database-inspector",
+  "version": "2.0.1",
+  "description": "MCP server for inspecting MySQL and PostgreSQL database schemas and structure",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "mysql",
+    "database",
+    "inspector",
+    "schema",
+    "ai"
+  ],
+  "author": "kokorolx",
+  "license": "MIT",
+  "homepage": "https://github.com/kokorolx/mcp-mysql-inspector",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "mysql2": "^3.15.3",
+    "pg": "^8.13.1",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/pg": "^8.11.10",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "mcp-database-inspector": "dist/index.js"
+  }
+}

package/src/database/connection.ts

@@ -0,0 +1,165 @@
+import mysql from 'mysql2/promise';
+import { URL } from 'url';
+import { DatabaseType, DatabaseConnectionOptions, QueryResult } from './types.js';
+import { Logger } from '../utils/logger.js';
+import { DatabaseError } from '../utils/errors.js';
+import { PostgresConnection } from './postgres-connection.js';
+
+export class DatabaseConnection {
+  private static readonly DEFAULT_TIMEOUT = 30000;
+  private static readonly DEFAULT_ACQUIRE_TIMEOUT = 60000;
+
+  static detectDatabaseType(url: string): DatabaseType {
+    try {
+      const protocol = new URL(url).protocol.replace(':', '');
+      if (protocol === 'mysql') return DatabaseType.MySQL;
+      if (protocol === 'postgresql' || protocol === 'postgres') return DatabaseType.PostgreSQL;
+      throw new DatabaseError(`Unsupported database protocol: ${protocol}. Supported protocols: mysql, postgresql, postgres.`);
+    } catch (error) {
+      if (error instanceof DatabaseError) throw error;
+      throw new DatabaseError(`Invalid connection URL: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  static parseConnectionUrl(url: string): DatabaseConnectionOptions {
+    const type = this.detectDatabaseType(url);
+    if (type === DatabaseType.PostgreSQL) {
+      return PostgresConnection.parseConnectionUrl(url);
+    }
+
+    // MySQL parsing logic (orig)
+    try {
+      const parsedUrl = new URL(url);
+
+      const options: DatabaseConnectionOptions = {
+        type: DatabaseType.MySQL,
+        host: parsedUrl.hostname,
+        port: parsedUrl.port ? parseInt(parsedUrl.port) : 3306,
+        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;
+        }
+      }
+
+      return options;
+    } catch (error) {
+      throw new DatabaseError(`Invalid connection URL: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  static async createConnection(options: DatabaseConnectionOptions): Promise<any> {
+    if (options.type === DatabaseType.PostgreSQL) {
+      return PostgresConnection.createClient(options);
+    }
+
+    try {
+      Logger.info(`Connecting to MySQL database at ${options.host}:${options.port}/${options.database}`);
+
+      const connectionConfig: any = {
+        host: options.host,
+        port: options.port,
+        user: options.user,
+        password: options.password,
+        database: options.database,
+        multipleStatements: false,
+        dateStrings: true,
+      };
+
+      if (options.ssl === false) {
+        connectionConfig.ssl = false;
+      } else if (options.ssl === true) {
+        connectionConfig.ssl = {};
+      } else if (options.ssl && typeof options.ssl === 'object') {
+        connectionConfig.ssl = options.ssl;
+      }
+
+      const connection = await mysql.createConnection(connectionConfig);
+      await connection.ping();
+
+      Logger.info(`Successfully connected to MySQL database: ${options.database}`);
+      return connection;
+    } catch (error) {
+      Logger.error(`Failed to connect to MySQL database: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      throw new DatabaseError(`Connection failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  static async executeQuery(connection: any, query: string, params?: any[], type: DatabaseType = DatabaseType.MySQL): Promise<QueryResult> {
+    if (type === DatabaseType.PostgreSQL) {
+      return PostgresConnection.executeQuery(connection, query, params);
+    }
+
+    try {
+      Logger.debug(`Executing MySQL query: ${query.substring(0, 100)}${query.length > 100 ? '...' : ''}`);
+
+      const [rows, fields] = await connection.execute(query, params);
+
+      const result: QueryResult = {
+        rows: Array.isArray(rows) ? rows : [],
+        fields: Array.isArray(fields) ? fields : [],
+      };
+
+      Logger.debug(`Query executed successfully, returned ${result.rows.length} rows`);
+      return result;
+    } catch (error) {
+      Logger.error(
+        `MySQL 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(connection: any, type: DatabaseType = DatabaseType.MySQL): Promise<void> {
+    if (type === DatabaseType.PostgreSQL) {
+      return PostgresConnection.closeConnection(connection);
+    }
+
+    try {
+      await connection.end();
+      Logger.info('MySQL connection closed successfully');
+    } catch (error) {
+      Logger.warn(`Error closing MySQL connection: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  static async testConnection(options: DatabaseConnectionOptions): Promise<boolean> {
+    if (options.type === DatabaseType.PostgreSQL) {
+      return PostgresConnection.testConnection(options);
+    }
+
+    let connection: mysql.Connection | null = null;
+    try {
+      connection = await this.createConnection(options);
+      return true;
+    } catch (error) {
+      Logger.warn(`MySQL connection test failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return false;
+    } finally {
+      if (connection) {
+        await this.closeConnection(connection);
+      }
+    }
+  }
+
+  static extractDatabaseName(url: string): string {
+    try {
+      const parsedUrl = new URL(url);
+      return parsedUrl.pathname.slice(1) || 'default';
+    } catch {
+      return 'default';
+    }
+  }
+}