@sigma4life/mysql-mcp-server 1.0.0

package/src/handlers/accessible-schema.ts

@@ -0,0 +1,314 @@
+import { resolveDatabase, resolveSchema } from '../core/config.js';
+import { logger } from '../core/logger.js';
+import {
+  getAccessControlConfig,
+  getTableConfigForSchema,
+  isAccessControlInitialized,
+} from '../core/security/access-control.js';
+import {
+  AccessControlConfig,
+  ColumnAccessPolicy,
+  TableConfig,
+} from '../core/security/types.js';
+import { getTableInfo } from './schema.js';
+import { findTables } from './search.js';
+
+export interface AccessibleColumn {
+  name: string;
+  dataType: string;
+  nullable: boolean;
+  isIdentity: boolean;
+  isPrimaryKey: boolean;
+  isForeignKey: boolean;
+  description?: string | null;
+}
+
+export interface AccessibleTable {
+  schema: string;
+  name: string;
+  type: 'TABLE' | 'VIEW';
+  columnAccessMode?: 'inclusion' | 'exclusion';
+  accessibleColumns: AccessibleColumn[];
+  blockedColumns?: string[];
+  allowedColumnsList?: string[];
+}
+
+export interface AccessibleSchemaResult {
+  database: string;
+  requireExplicitColumns: boolean;
+  configuredSchemas: string[];
+  tables: AccessibleTable[];
+  notes?: string[];
+}
+
+export interface AccessibleColumnInfo extends AccessibleColumn {
+  isAccessible: boolean;
+  accessDeniedReason?: string;
+}
+
+export interface AccessibleTableInfo {
+  database: string;
+  schema: string;
+  table: string;
+  type: 'TABLE' | 'VIEW';
+  isAccessible: boolean;
+  accessDeniedReason?: string;
+  columnAccessMode?: 'inclusion' | 'exclusion';
+  columns?: AccessibleColumnInfo[];
+  indexes?: unknown[];
+  foreignKeys?: unknown[];
+  accessibleColumnCount?: number;
+  totalColumnCount?: number;
+}
+
+function requireAccessConfig(database: string): AccessControlConfig {
+  if (!isAccessControlInitialized()) {
+    throw new Error(
+      'Access control not configured. Set QUERY_ACCESS_CONFIG to enable accessible schema introspection.',
+    );
+  }
+
+  const config = getAccessControlConfig();
+  if (!config.databases[database.toUpperCase()]) {
+    throw new Error(
+      `Database '${database}' is not configured in query access control. ` +
+        `Configured databases: ${Object.keys(config.databases).join(', ') || '(none)'}`,
+    );
+  }
+
+  return config;
+}
+
+function getConfiguredSchemas(config: AccessControlConfig, database: string): string[] {
+  const dbConfig = config.databases[database.toUpperCase()];
+  if (!dbConfig) {
+    return [];
+  }
+  return dbConfig.schemas ? Object.keys(dbConfig.schemas) : [database];
+}
+
+function isTableAccessible(
+  tableName: string,
+  tableConfig: TableConfig,
+): { accessible: boolean; reason?: string } {
+  const listLower = tableConfig.list.map((table) => table.toLowerCase());
+  const tableNameLower = tableName.toLowerCase();
+
+  if (tableConfig.mode === 'whitelist' && !listLower.includes(tableNameLower)) {
+    return {
+      accessible: false,
+      reason: `Table not in whitelist. Allowed tables: ${tableConfig.list.join(', ') || '(none)'}`,
+    };
+  }
+
+  if (tableConfig.mode === 'blacklist' && listLower.includes(tableNameLower)) {
+    return { accessible: false, reason: 'Table is in blacklist' };
+  }
+
+  return { accessible: true };
+}
+
+function findColumnPolicy(
+  tableName: string,
+  columnAccess: Record<string, ColumnAccessPolicy>,
+): ColumnAccessPolicy | null {
+  for (const [table, policy] of Object.entries(columnAccess)) {
+    if (table.toLowerCase() === tableName.toLowerCase()) {
+      return policy;
+    }
+  }
+  return null;
+}
+
+function filterColumns(
+  columns: AccessibleColumn[],
+  tableName: string,
+  columnAccess: Record<string, ColumnAccessPolicy>,
+): {
+  accessibleColumns: AccessibleColumn[];
+  blockedColumns?: string[];
+  allowedColumnsList?: string[];
+  mode?: 'inclusion' | 'exclusion';
+} {
+  const policy = findColumnPolicy(tableName, columnAccess);
+  if (!policy) {
+    return { accessibleColumns: columns };
+  }
+
+  const policyColumns = policy.columns.map((column) => column.toLowerCase());
+  if (policy.mode === 'inclusion') {
+    return {
+      accessibleColumns: columns.filter((column) => policyColumns.includes(column.name.toLowerCase())),
+      allowedColumnsList: policy.columns,
+      mode: 'inclusion',
+    };
+  }
+
+  return {
+    accessibleColumns: columns.filter((column) => !policyColumns.includes(column.name.toLowerCase())),
+    blockedColumns: policy.columns,
+    mode: 'exclusion',
+  };
+}
+
+function annotateColumnsWithAccess(
+  columns: AccessibleColumn[],
+  tableName: string,
+  columnAccess: Record<string, ColumnAccessPolicy>,
+): {
+  annotatedColumns: AccessibleColumnInfo[];
+  mode?: 'inclusion' | 'exclusion';
+} {
+  const policy = findColumnPolicy(tableName, columnAccess);
+  if (!policy) {
+    return {
+      annotatedColumns: columns.map((column) => ({ ...column, isAccessible: true })),
+    };
+  }
+
+  const policyColumns = policy.columns.map((column) => column.toLowerCase());
+  return {
+    annotatedColumns: columns.map((column) => {
+      const listed = policyColumns.includes(column.name.toLowerCase());
+      const isAccessible = policy.mode === 'inclusion' ? listed : !listed;
+      return {
+        ...column,
+        isAccessible,
+        accessDeniedReason: isAccessible
+          ? undefined
+          : policy.mode === 'inclusion'
+            ? `Column not in inclusion list. Allowed: ${policy.columns.join(', ')}`
+            : `Column in exclusion list: ${policy.columns.join(', ')}`,
+      };
+    }),
+    mode: policy.mode,
+  };
+}
+
+export async function getAccessibleSchema(args: {
+  database?: string;
+  schema?: string;
+}): Promise<AccessibleSchemaResult> {
+  const database = resolveDatabase(args.database);
+  const schema = resolveSchema(args.schema);
+  const config = requireAccessConfig(database);
+  const notes: string[] = [];
+
+  const schemaConfig = getTableConfigForSchema(config, database, schema);
+  if (!schemaConfig) {
+    throw new Error(`Schema '${schema}' is not configured for query access in database '${database}'.`);
+  }
+
+  const { tableConfig, columnAccess } = schemaConfig;
+  const tableNames = tableConfig.mode === 'whitelist'
+    ? tableConfig.list
+    : (await findTables({ database })).map((table) => table.tableName);
+  const blacklist = tableConfig.mode === 'blacklist'
+    ? new Set(tableConfig.list.map((table) => table.toLowerCase()))
+    : new Set<string>();
+  const accessibleTableNames = tableNames.filter((table) => !blacklist.has(table.toLowerCase()));
+
+  if (tableConfig.mode === 'blacklist' && tableConfig.list.length > 0) {
+    notes.push(`${tableConfig.list.length} table(s) blocked by blacklist: ${tableConfig.list.join(', ')}`);
+  }
+
+  const tables: AccessibleTable[] = [];
+  for (const tableName of accessibleTableNames) {
+    try {
+      const tableInfo = await getTableInfo({ database, table: tableName });
+      const { accessibleColumns, blockedColumns, allowedColumnsList, mode } = filterColumns(
+        tableInfo.columns,
+        tableInfo.name,
+        columnAccess,
+      );
+
+      tables.push({
+        schema,
+        name: tableInfo.name,
+        type: tableInfo.type,
+        accessibleColumns,
+        columnAccessMode: mode,
+        blockedColumns,
+        allowedColumnsList,
+      });
+    } catch (error) {
+      logger.warn(`Could not get info for table ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  return {
+    database,
+    requireExplicitColumns: config.requireExplicitColumns,
+    configuredSchemas: getConfiguredSchemas(config, database),
+    tables,
+    notes: notes.length ? notes : undefined,
+  };
+}
+
+export async function getAccessibleTableInfo(args: {
+  database?: string;
+  table: string;
+  schema?: string;
+}): Promise<AccessibleTableInfo> {
+  const database = resolveDatabase(args.database);
+  const schema = resolveSchema(args.schema);
+  const config = requireAccessConfig(database);
+
+  let tableInfo;
+  try {
+    tableInfo = await getTableInfo({ database, table: args.table });
+  } catch (error) {
+    return {
+      database,
+      schema,
+      table: args.table,
+      type: 'TABLE',
+      isAccessible: false,
+      accessDeniedReason: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  const schemaConfig = getTableConfigForSchema(config, database, schema);
+  if (!schemaConfig) {
+    return {
+      database,
+      schema,
+      table: tableInfo.name,
+      type: tableInfo.type,
+      isAccessible: false,
+      accessDeniedReason: `Schema '${schema}' is not configured for query access in database '${database}'`,
+    };
+  }
+
+  const tableAccess = isTableAccessible(tableInfo.name, schemaConfig.tableConfig);
+  if (!tableAccess.accessible) {
+    return {
+      database,
+      schema,
+      table: tableInfo.name,
+      type: tableInfo.type,
+      isAccessible: false,
+      accessDeniedReason: tableAccess.reason,
+    };
+  }
+
+  const { annotatedColumns, mode } = annotateColumnsWithAccess(
+    tableInfo.columns,
+    tableInfo.name,
+    schemaConfig.columnAccess,
+  );
+
+  return {
+    database,
+    schema,
+    table: tableInfo.name,
+    type: tableInfo.type,
+    isAccessible: true,
+    columnAccessMode: mode,
+    columns: annotatedColumns,
+    indexes: tableInfo.indexes,
+    foreignKeys: tableInfo.foreignKeys,
+    accessibleColumnCount: annotatedColumns.filter((column) => column.isAccessible).length,
+    totalColumnCount: annotatedColumns.length,
+  };
+}

package/src/handlers/data.ts

@@ -0,0 +1,66 @@
+import { appConfig, resolveDatabase } from '../core/config.js';
+import { logger } from '../core/logger.js';
+import {
+  QueryModificationResult,
+  enforceRowLimit,
+  validateQuerySafety,
+} from '../core/query-safety.js';
+import {
+  getAccessControlConfig,
+  isAccessControlInitialized,
+  validateQueryAccess,
+} from '../core/security/access-control.js';
+import { db } from '../mysql/connection.js';
+
+export interface DataQueryResult {
+  originalQuery: string;
+  executedQuery: string;
+  wasModified: boolean;
+  modifications: string[];
+  rows: unknown[];
+  rowCount: number;
+  executionTimeMs: number;
+  limitReached: boolean;
+  columnNames?: string[];
+}
+
+export async function executeQuery(args: {
+  database?: string;
+  query: string;
+  parameters?: Record<string, unknown>;
+}): Promise<DataQueryResult> {
+  const database = resolveDatabase(args.database);
+  const startTime = Date.now();
+
+  logger.info(`Executing read query on database: ${database}`);
+
+  validateQuerySafety(args.query);
+
+  if (!isAccessControlInitialized()) {
+    throw new Error(
+      'Access control not configured. Data queries are blocked until QUERY_ACCESS_CONFIG is set.',
+    );
+  }
+
+  validateQueryAccess(args.query, database, getAccessControlConfig());
+
+  const modResult: QueryModificationResult = enforceRowLimit(
+    args.query,
+    appConfig.query.maxRows,
+  );
+
+  const rows = await db.query<any>(modResult.modifiedQuery, args.parameters);
+  const executionTimeMs = Date.now() - startTime;
+
+  return {
+    originalQuery: args.query,
+    executedQuery: modResult.modifiedQuery,
+    wasModified: modResult.wasModified,
+    modifications: modResult.modifications,
+    rows,
+    rowCount: rows.length,
+    executionTimeMs,
+    limitReached: rows.length === modResult.appliedLimitValue,
+    columnNames: rows.length ? Object.keys(rows[0]) : [],
+  };
+}

package/src/handlers/relationships.ts

@@ -0,0 +1,114 @@
+import { cache } from '../core/cache.js';
+import { resolveDatabase, resolveSchema } from '../core/config.js';
+import { logger } from '../core/logger.js';
+import {
+  getRelationships as getMysqlRelationships,
+  Relationship,
+} from '../mysql/queries.js';
+
+interface RelationshipPath {
+  path: Relationship[];
+  joinCondition: string;
+}
+
+export async function getRelationships(args: {
+  database?: string;
+  fromTable: string;
+  toTable?: string;
+  maxDepth?: number;
+  schema?: string;
+}): Promise<RelationshipPath[]> {
+  const database = resolveDatabase(args.database);
+  resolveSchema(args.schema);
+  const { fromTable, toTable, maxDepth = 2 } = args;
+
+  const cacheKey = `relationships:${database}:${fromTable}:${toTable || 'all'}:${maxDepth}`;
+  const cached = cache.get<RelationshipPath[]>(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const relationships = await getMysqlRelationships();
+  const paths = toTable
+    ? findPaths(fromTable, toTable, relationships, maxDepth)
+    : relationships
+        .filter((rel) => rel.fromTable === fromTable || rel.toTable === fromTable)
+        .map((rel) => ({
+          path: [rel],
+          joinCondition: buildJoinCondition([rel]),
+        }));
+
+  cache.set(cacheKey, paths);
+  logger.info(`Found ${paths.length} relationship path(s) for ${fromTable}`);
+  return paths;
+}
+
+function findPaths(
+  fromTable: string,
+  toTable: string,
+  relationships: Relationship[],
+  maxDepth: number,
+): RelationshipPath[] {
+  const paths: RelationshipPath[] = [];
+  const visited = new Set<string>();
+
+  function dfs(currentTable: string, currentPath: Relationship[], depth: number): void {
+    if (depth > maxDepth) {
+      return;
+    }
+
+    if (currentTable === toTable && currentPath.length > 0) {
+      paths.push({
+        path: [...currentPath],
+        joinCondition: buildJoinCondition(currentPath),
+      });
+      return;
+    }
+
+    visited.add(currentTable);
+
+    for (const rel of relationships) {
+      if (rel.fromTable === currentTable && !visited.has(rel.toTable)) {
+        currentPath.push(rel);
+        dfs(rel.toTable, currentPath, depth + 1);
+        currentPath.pop();
+      }
+
+      if (rel.toTable === currentTable && !visited.has(rel.fromTable)) {
+        currentPath.push(rel);
+        dfs(rel.fromTable, currentPath, depth + 1);
+        currentPath.pop();
+      }
+    }
+
+    visited.delete(currentTable);
+  }
+
+  dfs(fromTable, [], 0);
+  return paths;
+}
+
+function buildJoinCondition(path: Relationship[]): string {
+  if (path.length === 0) {
+    return '';
+  }
+
+  const conditions: string[] = [];
+  let currentTable = path[0].fromTable;
+
+  for (const rel of path) {
+    if (rel.fromTable === currentTable) {
+      conditions.push(
+        `JOIN ${rel.toTable} ON ${rel.fromTable}.${rel.fromColumn} = ${rel.toTable}.${rel.toColumn}`,
+      );
+      currentTable = rel.toTable;
+    } else {
+      conditions.push(
+        `JOIN ${rel.fromTable} ON ${rel.toTable}.${rel.toColumn} = ${rel.fromTable}.${rel.fromColumn}`,
+      );
+      currentTable = rel.fromTable;
+    }
+  }
+
+  return conditions.join('\n');
+}

package/src/handlers/schema.ts

@@ -0,0 +1,154 @@
+import { cache } from '../core/cache.js';
+import { resolveDatabase, resolveSchema } from '../core/config.js';
+import {
+  SchemaResult,
+  TableMetadata,
+} from '../core/schema-types.js';
+import { logger } from '../core/logger.js';
+import {
+  getColumns,
+  getForeignKeys,
+  getIndexes,
+  getPrimaryKeys,
+  getStatistics,
+  listTables,
+} from '../mysql/queries.js';
+import { validateDatabaseObject } from './validation.js';
+
+function byTable<T extends { tableName: string }>(rows: T[]): Map<string, T[]> {
+  const map = new Map<string, T[]>();
+  for (const row of rows) {
+    const list = map.get(row.tableName) || [];
+    list.push(row);
+    map.set(row.tableName, list);
+  }
+  return map;
+}
+
+async function buildMetadata(
+  tableNames?: string[],
+  includeRelationships = true,
+  includeStatistics = false,
+): Promise<TableMetadata[]> {
+  const tables = await listTables(tableNames);
+  const actualTableNames = tables.map((table) => table.tableName);
+
+  const [columns, primaryKeys, foreignKeys, indexes, statistics] = await Promise.all([
+    getColumns(actualTableNames),
+    getPrimaryKeys(actualTableNames),
+    includeRelationships ? getForeignKeys(actualTableNames) : Promise.resolve([]),
+    getIndexes(actualTableNames),
+    includeStatistics ? getStatistics(actualTableNames) : Promise.resolve([]),
+  ]);
+
+  const columnsByTable = byTable(columns as any[]);
+  const pksByTable = byTable(primaryKeys);
+  const fksByTable = byTable(foreignKeys);
+  const indexesByTable = byTable(indexes);
+  const statsByTable = byTable(statistics);
+
+  return tables.map((table) => {
+    const metadata: TableMetadata = {
+      schema: table.schemaName,
+      name: table.tableName,
+      type: table.tableType === 'VIEW' ? 'VIEW' : 'TABLE',
+      columns: (columnsByTable.get(table.tableName) || []).map(({ tableName: _tableName, ...column }) => ({
+        ...column,
+        nullable: Boolean(column.nullable),
+        isIdentity: Boolean(column.isIdentity),
+        isComputed: Boolean(column.isComputed),
+        isPrimaryKey: Boolean(column.isPrimaryKey),
+        isForeignKey: Boolean(column.isForeignKey),
+      })),
+      indexes: (indexesByTable.get(table.tableName) || []).map(({ tableName: _tableName, ...index }) => ({
+        ...index,
+        isUnique: Boolean(index.isUnique),
+        isPrimaryKey: Boolean(index.isPrimaryKey),
+      })),
+    };
+
+    const primaryKey = pksByTable.get(table.tableName)?.[0];
+    if (primaryKey) {
+      const { tableName: _tableName, ...pk } = primaryKey;
+      metadata.primaryKey = pk;
+    }
+
+    if (includeRelationships) {
+      metadata.foreignKeys = (fksByTable.get(table.tableName) || []).map(({ tableName: _tableName, ...fk }) => fk);
+    }
+
+    const stats = statsByTable.get(table.tableName)?.[0];
+    if (includeStatistics && stats) {
+      const { tableName: _tableName, ...tableStats } = stats;
+      metadata.statistics = tableStats;
+    }
+
+    return metadata;
+  });
+}
+
+export async function getSchema(args: {
+  database?: string;
+  tables?: string[];
+  schema?: string;
+  includeRelationships?: boolean;
+  includeStatistics?: boolean;
+}): Promise<SchemaResult> {
+  const database = resolveDatabase(args.database);
+  resolveSchema(args.schema);
+
+  const {
+    tables,
+    includeRelationships = true,
+    includeStatistics = false,
+  } = args;
+
+  const cacheKey = `schema:${database}:${tables?.join(',') || 'all'}:${includeRelationships}:${includeStatistics}`;
+  const cached = cache.get<SchemaResult>(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  if (tables?.length) {
+    const validation = await Promise.all(
+      tables.map((table) => validateDatabaseObject(database, table)),
+    );
+    const missing = validation.filter((result) => !result.valid);
+    if (missing.length) {
+      throw new Error(missing.map((result) => result.message).join('\n'));
+    }
+  }
+
+  const result = {
+    schema: await buildMetadata(tables, includeRelationships, includeStatistics),
+  };
+
+  cache.set(cacheKey, result);
+  logger.info(`Retrieved schema for ${result.schema.length} objects from ${database}`);
+  return result;
+}
+
+export async function getTableInfo(args: {
+  database?: string;
+  table: string;
+  schema?: string;
+}): Promise<TableMetadata> {
+  const database = resolveDatabase(args.database);
+  resolveSchema(args.schema);
+
+  const validation = await validateDatabaseObject(database, args.table);
+  if (!validation.valid || !validation.table?.actualName) {
+    throw new Error(validation.message);
+  }
+
+  const tableName = validation.table.actualName.includes('.')
+    ? validation.table.actualName.split('.').pop()!
+    : validation.table.actualName;
+  const metadata = await buildMetadata([tableName], true, false);
+
+  if (!metadata[0]) {
+    throw new Error(`Table '${args.table}' not found in database '${database}'`);
+  }
+
+  return metadata[0];
+}

package/src/handlers/search.ts

@@ -0,0 +1,34 @@
+import { resolveDatabase, resolveSchema } from '../core/config.js';
+import { logger } from '../core/logger.js';
+import {
+  findTables as findMysqlTables,
+  searchObjects as searchMysqlObjects,
+  ObjectSearchResult,
+  TableSearchResult,
+} from '../mysql/queries.js';
+
+export async function findTables(args: {
+  database?: string;
+  pattern?: string;
+  hasColumn?: string;
+  schema?: string;
+}): Promise<TableSearchResult[]> {
+  const database = resolveDatabase(args.database);
+  resolveSchema(args.schema);
+  const tables = await findMysqlTables(args.pattern, args.hasColumn);
+  logger.info(`Found ${tables.length} tables matching criteria in ${database}`);
+  return tables;
+}
+
+export async function searchObjects(args: {
+  database?: string;
+  search: string;
+  schema?: string;
+  type?: string;
+}): Promise<ObjectSearchResult[]> {
+  const database = resolveDatabase(args.database);
+  resolveSchema(args.schema);
+  const results = await searchMysqlObjects(args.search, args.type);
+  logger.info(`Found ${results.length} matches for '${args.search}' in ${database}`);
+  return results;
+}