mcp-database-inspector 2.0.1

package/src/tools/get-foreign-keys.ts

@@ -0,0 +1,488 @@
+import { z } from 'zod';
+import { DatabaseManager } from '../database/manager.js';
+import { InputValidator } from '../validators/input-validator.js';
+import { Logger } from '../utils/logger.js';
+import { ToolError } from '../utils/errors.js';
+
+// Tool schema
+const GetForeignKeysArgsSchema = z.object({
+  database: z.string().min(1, 'Database name is required'),
+  table: z.string().optional(),
+  tables: z.array(z.string().min(1)).optional()
+}).superRefine((data, ctx) => {
+  const hasTable = typeof data.table === 'string' && data.table.length > 0;
+  const hasTables = Array.isArray(data.tables) && data.tables.length > 0;
+  if (hasTable && hasTables) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Provide either 'table' or 'tables', not both"
+    });
+  } else if (!hasTable && !hasTables) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Either 'table' or non-empty 'tables' must be provided"
+    });
+  }
+});
+
+/**
+ * Tool: get_foreign_keys
+ * Get foreign key relationships for one or more tables, or the entire database.
+ *
+ * Supports both single-table and multi-table inspection:
+ * - Provide either `table` (string) for a single table, or `tables` (string[]) for multiple tables.
+ * - If `tables` is provided, returns a mapping of table names to their foreign key analysis.
+ * - Do not provide both `table` and `tables` at the same time.
+ */
+export interface GetForeignKeysTool {
+  name: 'get_foreign_keys';
+  description: 'Get foreign key relationships for one or more tables, or the entire database. Supports multi-table inspection via the tables: string[] parameter.';
+  inputSchema: {
+    type: 'object';
+    properties: {
+      database: {
+        type: 'string';
+        description: 'Name of the database to analyze';
+      };
+      table: {
+        type: 'string';
+        description: 'Specific table name to get foreign keys for (single-table mode)';
+      };
+      tables: {
+        type: 'array';
+        items: { type: 'string' };
+        description: 'Array of table names to get foreign keys for (multi-table mode)';
+      };
+    };
+    required: ['database'];
+  };
+}
+
+export const getForeignKeysToolDefinition: GetForeignKeysTool = {
+  name: 'get_foreign_keys',
+  description: 'Get foreign key relationships for one or more tables, or the entire database. Supports multi-table inspection via the tables: string[] parameter.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      database: {
+        type: 'string',
+        description: 'Name of the database to analyze'
+      },
+      table: {
+        type: 'string',
+        description: 'Specific table name to get foreign keys for (single-table mode)'
+      },
+      tables: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Array of table names to get foreign keys for (multi-table mode)'
+      }
+    },
+    required: ['database']
+  }
+};
+
+export async function handleGetForeignKeys(
+  args: unknown,
+  dbManager: DatabaseManager
+): Promise<any> {
+  try {
+    Logger.info('Executing get_foreign_keys tool');
+
+    // Validate arguments
+    const validationResult = GetForeignKeysArgsSchema.safeParse(args);
+    if (!validationResult.success) {
+      Logger.warn('Invalid arguments for get_foreign_keys', validationResult.error);
+      throw new ToolError(
+        `Invalid arguments: ${validationResult.error.issues.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`,
+        'get_foreign_keys'
+      );
+    }
+
+    const { database, table, tables } = validationResult.data;
+
+    // Sanitize inputs
+    const sanitizedDatabase = InputValidator.sanitizeString(database);
+    const sanitizedTable = table ? InputValidator.sanitizeString(table) : undefined;
+    const sanitizedTables = tables ? tables.map(InputValidator.sanitizeString) : undefined;
+
+    // Validate database name format
+    const dbNameValidation = InputValidator.validateDatabaseName(sanitizedDatabase);
+    if (!dbNameValidation.isValid) {
+      throw new ToolError(
+        `Invalid database name: ${dbNameValidation.error}`,
+        'get_foreign_keys'
+      );
+    }
+
+    // Multi-table mode
+    if (sanitizedTables && sanitizedTables.length > 0) {
+      Logger.info(`Multi-table mode: Getting foreign keys for tables: ${sanitizedTables.join(', ')} in database: ${sanitizedDatabase}`);
+      const results: Record<string, any> = {};
+      const errors: Record<string, string> = {};
+
+      for (const tbl of sanitizedTables) {
+        try {
+          const tableNameValidation = InputValidator.validateTableName(tbl);
+          if (!tableNameValidation.isValid) {
+            throw new ToolError(
+              `Invalid table name: ${tableNameValidation.error}`,
+              'get_foreign_keys'
+            );
+          }
+
+          Logger.info(`Getting foreign keys for table: ${tbl} in database: ${sanitizedDatabase}`);
+          Logger.time(`get_foreign_keys_execution_${tbl}`);
+
+          const foreignKeys = await dbManager.getForeignKeys(sanitizedDatabase, tbl);
+
+          Logger.timeEnd(`get_foreign_keys_execution_${tbl}`);
+          Logger.info(`Found ${foreignKeys.length} foreign key(s) in table: ${tbl}`);
+
+          const analysis = analyzeForeignKeyRelationships(foreignKeys);
+          const foreignKeysByTable = groupForeignKeysByTable(foreignKeys);
+
+          results[tbl] = {
+            database: sanitizedDatabase,
+            table: tbl,
+            scope: 'table',
+            foreignKeys: foreignKeys.map(fk => ({
+              constraintName: fk.constraintName,
+              sourceTable: fk.tableName,
+              sourceColumn: fk.columnName,
+              targetTable: fk.referencedTableName,
+              targetColumn: fk.referencedColumnName,
+              updateRule: fk.updateRule,
+              deleteRule: fk.deleteRule,
+              relationshipType: determineRelationshipType(fk.updateRule || 'NO ACTION', fk.deleteRule || 'NO ACTION')
+            })),
+            relationships: analysis.relationships,
+            statistics: {
+              totalForeignKeys: foreignKeys.length,
+              uniqueConstraints: [...new Set(foreignKeys.map(fk => fk.constraintName))].length,
+              affectedTables: [...new Set(foreignKeys.map(fk => fk.tableName))].length,
+              referencedTables: [...new Set(foreignKeys.map(fk => fk.referencedTableName))].length,
+              cascadeDeleteCount: foreignKeys.filter(fk => fk.deleteRule === 'CASCADE').length,
+              cascadeUpdateCount: foreignKeys.filter(fk => fk.updateRule === 'CASCADE').length,
+              restrictDeleteCount: foreignKeys.filter(fk => fk.deleteRule === 'RESTRICT').length,
+              restrictUpdateCount: foreignKeys.filter(fk => fk.updateRule === 'RESTRICT').length
+            },
+            foreignKeysByTable,
+            analysis: {
+              ...analysis,
+              integrityRules: analyzeIntegrityRules(foreignKeys),
+              potentialIssues: identifyPotentialIssues(foreignKeys)
+            },
+            summary: {
+              hasRelationships: foreignKeys.length > 0,
+              message: foreignKeys.length === 0
+                ? `No foreign key relationships found in table '${tbl}' of database '${sanitizedDatabase}'`
+                : `Found ${foreignKeys.length} foreign key relationship(s) in table '${tbl}' involving ${analysis.relationships.length} table connection(s)`
+            }
+          };
+
+          Logger.debug('get_foreign_keys completed for table', {
+            database: sanitizedDatabase,
+            table: tbl,
+            foreignKeyCount: foreignKeys.length,
+            relationshipCount: analysis.relationships.length
+          });
+
+        } catch (err) {
+          Logger.error(`Error processing table '${tbl}' in get_foreign_keys`, err);
+          errors[tbl] = err instanceof Error ? err.message : String(err);
+        }
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ database: sanitizedDatabase, results, errors }, null, 2)
+        }]
+      };
+    }
+
+    // Single-table or all-tables mode (original behavior)
+    // Validate table name format if provided
+    if (sanitizedTable) {
+      const tableNameValidation = InputValidator.validateTableName(sanitizedTable);
+      if (!tableNameValidation.isValid) {
+        throw new ToolError(
+          `Invalid table name: ${tableNameValidation.error}`,
+          'get_foreign_keys'
+        );
+      }
+    }
+
+    const scope = sanitizedTable ? `table: ${sanitizedTable}` : 'entire database';
+    Logger.info(`Getting foreign keys for ${scope} in database: ${sanitizedDatabase}`);
+    Logger.time('get_foreign_keys_execution');
+
+    // Get foreign keys
+    const foreignKeys = await dbManager.getForeignKeys(sanitizedDatabase, sanitizedTable);
+
+    Logger.timeEnd('get_foreign_keys_execution');
+    Logger.info(`Found ${foreignKeys.length} foreign key(s) in ${scope}`);
+
+    // Analyze relationships
+    const analysis = analyzeForeignKeyRelationships(foreignKeys);
+
+    // Group foreign keys by table
+    const foreignKeysByTable = groupForeignKeysByTable(foreignKeys);
+
+    // Create response
+    const response = {
+      database: sanitizedDatabase,
+      table: sanitizedTable || null,
+      scope: sanitizedTable ? 'table' : 'database',
+      foreignKeys: foreignKeys.map(fk => ({
+        constraintName: fk.constraintName,
+        sourceTable: fk.tableName,
+        sourceColumn: fk.columnName,
+        targetTable: fk.referencedTableName,
+        targetColumn: fk.referencedColumnName,
+        updateRule: fk.updateRule,
+        deleteRule: fk.deleteRule,
+        relationshipType: determineRelationshipType(fk.updateRule || 'NO ACTION', fk.deleteRule || 'NO ACTION')
+      })),
+      relationships: analysis.relationships,
+      statistics: {
+        totalForeignKeys: foreignKeys.length,
+        uniqueConstraints: [...new Set(foreignKeys.map(fk => fk.constraintName))].length,
+        affectedTables: [...new Set(foreignKeys.map(fk => fk.tableName))].length,
+        referencedTables: [...new Set(foreignKeys.map(fk => fk.referencedTableName))].length,
+        cascadeDeleteCount: foreignKeys.filter(fk => fk.deleteRule === 'CASCADE').length,
+        cascadeUpdateCount: foreignKeys.filter(fk => fk.updateRule === 'CASCADE').length,
+        restrictDeleteCount: foreignKeys.filter(fk => fk.deleteRule === 'RESTRICT').length,
+        restrictUpdateCount: foreignKeys.filter(fk => fk.updateRule === 'RESTRICT').length
+      },
+      foreignKeysByTable,
+      analysis: {
+        ...analysis,
+        integrityRules: analyzeIntegrityRules(foreignKeys),
+        potentialIssues: identifyPotentialIssues(foreignKeys)
+      },
+      summary: {
+        hasRelationships: foreignKeys.length > 0,
+        message: foreignKeys.length === 0
+          ? `No foreign key relationships found in ${scope} of database '${sanitizedDatabase}'`
+          : `Found ${foreignKeys.length} foreign key relationship(s) in ${scope} involving ${analysis.relationships.length} table connection(s)`
+      }
+    };
+
+    Logger.debug('get_foreign_keys completed successfully', {
+      database: sanitizedDatabase,
+      table: sanitizedTable,
+      foreignKeyCount: foreignKeys.length,
+      relationshipCount: analysis.relationships.length
+    });
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(response, null, 2)
+      }]
+    };
+
+  } catch (error) {
+    // Add table context to error logs
+    let tableContext: string | undefined;
+    let argTables: string[] | undefined;
+    let argTable: string | undefined;
+    if (args && typeof args === 'object') {
+      // @ts-ignore
+      argTables = Array.isArray(args.tables) ? args.tables : undefined;
+      // @ts-ignore
+      argTable = typeof args.table === 'string' ? args.table : undefined;
+    }
+    if (Array.isArray(argTables) && argTables.length > 0) {
+      tableContext = `tables: [${argTables.join(', ')}]`;
+    } else if (typeof argTable === 'string' && argTable.length > 0) {
+      tableContext = `table: ${argTable}`;
+    } else {
+      tableContext = 'no table(s) specified';
+    }
+    Logger.error(`Error in get_foreign_keys tool (${tableContext})`, error);
+
+    if (error instanceof ToolError) {
+      throw error;
+    }
+
+    throw new ToolError(
+      `Failed to get foreign keys (${tableContext}): ${error instanceof Error ? error.message : 'Unknown error'}`,
+      'get_foreign_keys',
+      error instanceof Error ? error : undefined
+    );
+  }
+}
+
+// Helper functions
+function groupForeignKeysByTable(foreignKeys: any[]): Record<string, any[]> {
+  const groups: Record<string, any[]> = {};
+
+  foreignKeys.forEach(fk => {
+    if (!groups[fk.tableName]) {
+      groups[fk.tableName] = [];
+    }
+    groups[fk.tableName].push({
+      constraintName: fk.constraintName,
+      column: fk.columnName,
+      referencedTable: fk.referencedTableName,
+      referencedColumn: fk.referencedColumnName,
+      updateRule: fk.updateRule,
+      deleteRule: fk.deleteRule
+    });
+  });
+
+  return groups;
+}
+
+function analyzeForeignKeyRelationships(foreignKeys: any[]): any {
+  const relationships: any[] = [];
+  const tableConnections: Record<string, Set<string>> = {};
+
+  // Group by constraint to handle composite foreign keys
+  const constraintGroups: Record<string, any[]> = {};
+  foreignKeys.forEach(fk => {
+    if (!constraintGroups[fk.constraintName]) {
+      constraintGroups[fk.constraintName] = [];
+    }
+    constraintGroups[fk.constraintName].push(fk);
+  });
+
+  // Analyze each constraint
+  Object.keys(constraintGroups).forEach(constraintName => {
+    const fks = constraintGroups[constraintName];
+    const firstFK = fks[0];
+
+    relationships.push({
+      constraintName,
+      fromTable: firstFK.tableName,
+      toTable: firstFK.referencedTableName,
+      columns: fks.map(fk => ({
+        from: fk.columnName,
+        to: fk.referencedColumnName
+      })),
+      isComposite: fks.length > 1,
+      updateRule: firstFK.updateRule,
+      deleteRule: firstFK.deleteRule,
+      relationshipStrength: determineRelationshipStrength(firstFK.updateRule, firstFK.deleteRule)
+    });
+
+    // Track table connections
+    if (!tableConnections[firstFK.tableName]) {
+      tableConnections[firstFK.tableName] = new Set();
+    }
+    tableConnections[firstFK.tableName].add(firstFK.referencedTableName);
+  });
+
+  return {
+    relationships,
+    tableConnections: Object.fromEntries(
+      Object.entries(tableConnections).map(([table, connections]) => [
+        table,
+        Array.from(connections)
+      ])
+    ),
+    totalRelationships: relationships.length,
+    compositeRelationships: relationships.filter(r => r.isComposite).length
+  };
+}
+
+function determineRelationshipType(updateRule: string | undefined, deleteRule: string | undefined): string {
+  const ur = updateRule || 'NO ACTION';
+  const dr = deleteRule || 'NO ACTION';
+
+  if (ur === 'CASCADE' || dr === 'CASCADE') {
+    return 'strong_dependency'; // Child cannot exist without parent
+  } else if (dr === 'RESTRICT' || dr === 'NO ACTION') {
+    return 'protective'; // Prevents accidental deletion
+  } else if (dr === 'SET NULL') {
+    return 'optional_reference'; // Relationship can be broken
+  } else {
+    return 'unknown';
+  }
+}
+
+function determineRelationshipStrength(updateRule: string, deleteRule: string): 'strong' | 'medium' | 'weak' {
+  if (deleteRule === 'CASCADE' && updateRule === 'CASCADE') {
+    return 'strong';
+  } else if (deleteRule === 'RESTRICT' || updateRule === 'RESTRICT') {
+    return 'medium';
+  } else {
+    return 'weak';
+  }
+}
+
+function analyzeIntegrityRules(foreignKeys: any[]): any {
+  const rules = {
+    cascade: {
+      delete: foreignKeys.filter(fk => fk.deleteRule === 'CASCADE'),
+      update: foreignKeys.filter(fk => fk.updateRule === 'CASCADE')
+    },
+    restrict: {
+      delete: foreignKeys.filter(fk => fk.deleteRule === 'RESTRICT' || fk.deleteRule === 'NO ACTION'),
+      update: foreignKeys.filter(fk => fk.updateRule === 'RESTRICT' || fk.updateRule === 'NO ACTION')
+    },
+    setNull: {
+      delete: foreignKeys.filter(fk => fk.deleteRule === 'SET NULL'),
+      update: foreignKeys.filter(fk => fk.updateRule === 'SET NULL')
+    }
+  };
+
+  return {
+    rules,
+    summary: {
+      cascadeDeleteTables: [...new Set(rules.cascade.delete.map(fk => fk.tableName))],
+      protectedTables: [...new Set(rules.restrict.delete.map(fk => fk.referencedTableName))],
+      weaklyReferencedTables: [...new Set(rules.setNull.delete.map(fk => fk.referencedTableName))]
+    }
+  };
+}
+
+function identifyPotentialIssues(foreignKeys: any[]): string[] {
+  const issues: string[] = [];
+
+  // Check for circular references
+  const tableGraph: Record<string, string[]> = {};
+  foreignKeys.forEach(fk => {
+    if (!tableGraph[fk.tableName]) {
+      tableGraph[fk.tableName] = [];
+    }
+    tableGraph[fk.tableName].push(fk.referencedTableName);
+  });
+
+  // Simple cycle detection (this is a basic check, not comprehensive)
+  Object.keys(tableGraph).forEach(table => {
+    tableGraph[table].forEach(referenced => {
+      if (tableGraph[referenced] && tableGraph[referenced].includes(table)) {
+        issues.push(`Potential circular reference detected between tables '${table}' and '${referenced}'`);
+      }
+    });
+  });
+
+  // Check for many cascade delete relationships from same parent
+  const cascadeParents: Record<string, number> = {};
+  foreignKeys.filter(fk => fk.deleteRule === 'CASCADE').forEach(fk => {
+    cascadeParents[fk.referencedTableName] = (cascadeParents[fk.referencedTableName] || 0) + 1;
+  });
+
+  Object.entries(cascadeParents).forEach(([table, count]) => {
+    if (count > 5) {
+      issues.push(`Table '${table}' has ${count} cascade delete relationships - consider the impact of deletions`);
+    }
+  });
+
+  // Check for inconsistent naming patterns
+  const constraintNames = foreignKeys.map(fk => fk.constraintName);
+  const hasConsistentNaming = constraintNames.every(name =>
+    name.startsWith('fk_') || name.startsWith('FK_') ||
+    name.includes('_fk') || name.includes('_FK')
+  );
+
+  if (!hasConsistentNaming && constraintNames.length > 1) {
+    issues.push('Foreign key constraint names follow inconsistent naming patterns');
+  }
+
+  return issues;
+}

package/src/tools/get-indexes.test.ts

@@ -0,0 +1,51 @@
+// @ts-nocheck
+import { describe, it, expect, vi } from 'vitest';
+import { handleGetIndexes } from './get-indexes';
+import { DatabaseManager } from '../database/manager';
+
+const mockDbManager = {
+  getIndexes: vi.fn()
+} as unknown as DatabaseManager;
+
+describe('get_indexes', () => {
+  it('should return indexes for a single table', async () => {
+    mockDbManager.getIndexes.mockResolvedValueOnce([{ indexName: 'PRIMARY', tableName: 'products', columnName: 'id', nonUnique: false, nullable: false, isPrimary: true }]);
+    const args = { database: 'testdb', table: 'products' };
+    const result = await handleGetIndexes(args, mockDbManager);
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.table).toBe('products');
+    expect(parsed.indexes[0].name).toBe('PRIMARY');
+  });
+
+  it('should return indexes for multiple tables', async () => {
+    mockDbManager.getIndexes
+      .mockResolvedValueOnce([{ indexName: 'PRIMARY', tableName: 'products', columnName: 'id', nonUnique: false, nullable: false, isPrimary: true }])
+      .mockResolvedValueOnce([{ indexName: 'PRIMARY', tableName: 'categories', columnName: 'id', nonUnique: false, nullable: false, isPrimary: true }]);
+    const args = { database: 'testdb', tables: ['products', 'categories'] };
+    const result = await handleGetIndexes(args, mockDbManager);
+    const parsed = JSON.parse(result.content[0].text);
+    expect(Object.keys(parsed)).toHaveLength(2);
+    expect(parsed.products.table).toBe('products');
+    expect(parsed.categories.table).toBe('categories');
+  });
+
+  it('should throw error if neither table nor tables is provided', async () => {
+    await expect(() =>
+      handleGetIndexes({ database: 'testdb' }, mockDbManager)
+    ).rejects.toThrow(/Either 'table' or non-empty 'tables'/);
+  });
+
+  it('should throw error for invalid table name', async () => {
+    await expect(() =>
+      handleGetIndexes({ database: 'testdb', table: 'invalid;DROP' }, mockDbManager)
+    ).rejects.toThrow(/Invalid table name/);
+  });
+
+  it('should return empty result if table not found', async () => {
+    mockDbManager.getIndexes.mockResolvedValueOnce([]);
+    const result = await handleGetIndexes({ database: 'testdb', table: 'notfound' }, mockDbManager);
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.indexes).toHaveLength(0);
+    expect(parsed.summary.message).toMatch(/No indexes found/);
+  });
+});