@neverinfamous/mysql-mcp 2.1.0

package/src/filtering/ToolConstants.ts

@@ -0,0 +1,297 @@
+/**
+ * mysql-mcp - Tool Constants
+ * 
+ * Defines the tool groups and meta-groups used for filtering.
+ */
+
+import type { ToolGroup, MetaGroup } from '../types/index.js';
+
+/**
+ * Default tool groups and their member tools.
+ * This serves as the canonical mapping of tools to groups.
+ */
+export const TOOL_GROUPS: Record<ToolGroup, string[]> = {
+    core: [
+        'mysql_read_query',
+        'mysql_write_query',
+        'mysql_list_tables',
+        'mysql_describe_table',
+        'mysql_create_table',
+        'mysql_drop_table',
+        'mysql_create_index',
+        'mysql_get_indexes'
+    ],
+    json: [
+        'mysql_json_extract',
+        'mysql_json_set',
+        'mysql_json_insert',
+        'mysql_json_replace',
+        'mysql_json_remove',
+        'mysql_json_contains',
+        'mysql_json_keys',
+        'mysql_json_array_append',
+        'mysql_json_get',
+        'mysql_json_update',
+        'mysql_json_search',
+        'mysql_json_validate',
+        // Enhanced JSON tools (5 new)
+        'mysql_json_merge',
+        'mysql_json_diff',
+        'mysql_json_normalize',
+        'mysql_json_stats',
+        'mysql_json_index_suggest'
+    ],
+    text: [
+        'mysql_regexp_match',
+        'mysql_like_search',
+        'mysql_soundex',
+        'mysql_substring',
+        'mysql_concat',
+        'mysql_collation_convert'
+    ],
+    fulltext: [
+        'mysql_fulltext_create',
+        'mysql_fulltext_search',
+        'mysql_fulltext_boolean',
+        'mysql_fulltext_expand'
+    ],
+    performance: [
+        'mysql_explain',
+        'mysql_explain_analyze',
+        'mysql_slow_queries',
+        'mysql_query_stats',
+        'mysql_index_usage',
+        'mysql_table_stats',
+        'mysql_buffer_pool_stats',
+        'mysql_thread_stats'
+    ],
+    optimization: [
+        'mysql_index_recommendation',
+        'mysql_query_rewrite',
+        'mysql_force_index',
+        'mysql_optimizer_trace'
+    ],
+    admin: [
+        'mysql_optimize_table',
+        'mysql_analyze_table',
+        'mysql_check_table',
+        'mysql_repair_table',
+        'mysql_flush_tables',
+        'mysql_kill_query'
+    ],
+    monitoring: [
+        'mysql_show_processlist',
+        'mysql_show_status',
+        'mysql_show_variables',
+        'mysql_innodb_status',
+        'mysql_replication_status',
+        'mysql_pool_stats',
+        'mysql_server_health'
+    ],
+    backup: [
+        'mysql_export_table',
+        'mysql_import_data',
+        'mysql_create_dump',
+        'mysql_restore_dump'
+    ],
+    replication: [
+        'mysql_master_status',
+        'mysql_slave_status',
+        'mysql_binlog_events',
+        'mysql_gtid_status',
+        'mysql_replication_lag'
+    ],
+    partitioning: [
+        'mysql_partition_info',
+        'mysql_add_partition',
+        'mysql_drop_partition',
+        'mysql_reorganize_partition'
+    ],
+    transactions: [
+        'mysql_transaction_begin',
+        'mysql_transaction_commit',
+        'mysql_transaction_rollback',
+        'mysql_transaction_savepoint',
+        'mysql_transaction_release',
+        'mysql_transaction_rollback_to',
+        'mysql_transaction_execute'
+    ],
+    router: [
+        'mysql_router_status',
+        'mysql_router_routes',
+        'mysql_router_route_status',
+        'mysql_router_route_health',
+        'mysql_router_route_connections',
+        'mysql_router_route_destinations',
+        'mysql_router_route_blocked_hosts',
+        'mysql_router_metadata_status',
+        'mysql_router_pool_status'
+    ],
+    proxysql: [
+        'proxysql_status',
+        'proxysql_servers',
+        'proxysql_hostgroups',
+        'proxysql_query_rules',
+        'proxysql_query_digest',
+        'proxysql_connection_pool',
+        'proxysql_users',
+        'proxysql_global_variables',
+        'proxysql_runtime_status',
+        'proxysql_memory_stats',
+        'proxysql_commands',
+        'proxysql_process_list'
+    ],
+    shell: [
+        'mysqlsh_version',
+        'mysqlsh_check_upgrade',
+        'mysqlsh_export_table',
+        'mysqlsh_import_table',
+        'mysqlsh_import_json',
+        'mysqlsh_dump_instance',
+        'mysqlsh_dump_schemas',
+        'mysqlsh_dump_tables',
+        'mysqlsh_load_dump',
+        'mysqlsh_run_script'
+    ],
+    // New tool groups (v2.0.0)
+    schema: [
+        'mysql_list_schemas',
+        'mysql_create_schema',
+        'mysql_drop_schema',
+        'mysql_list_views',
+        'mysql_create_view',
+        'mysql_list_stored_procedures',
+        'mysql_list_functions',
+        'mysql_list_triggers',
+        'mysql_list_constraints',
+        'mysql_list_events'
+    ],
+    events: [
+        'mysql_event_create',
+        'mysql_event_alter',
+        'mysql_event_drop',
+        'mysql_event_list',
+        'mysql_event_status',
+        'mysql_scheduler_status'
+    ],
+    sysschema: [
+        'mysql_sys_user_summary',
+        'mysql_sys_io_summary',
+        'mysql_sys_statement_summary',
+        'mysql_sys_wait_summary',
+        'mysql_sys_innodb_lock_waits',
+        'mysql_sys_schema_stats',
+        'mysql_sys_host_summary',
+        'mysql_sys_memory_summary'
+    ],
+    stats: [
+        'mysql_stats_descriptive',
+        'mysql_stats_percentiles',
+        'mysql_stats_correlation',
+        'mysql_stats_distribution',
+        'mysql_stats_time_series',
+        'mysql_stats_regression',
+        'mysql_stats_sampling',
+        'mysql_stats_histogram'
+    ],
+    spatial: [
+        'mysql_spatial_create_column',
+        'mysql_spatial_create_index',
+        'mysql_spatial_point',
+        'mysql_spatial_polygon',
+        'mysql_spatial_distance',
+        'mysql_spatial_distance_sphere',
+        'mysql_spatial_contains',
+        'mysql_spatial_within',
+        'mysql_spatial_intersection',
+        'mysql_spatial_buffer',
+        'mysql_spatial_transform',
+        'mysql_spatial_geojson'
+    ],
+    security: [
+        'mysql_security_audit',
+        'mysql_security_firewall_status',
+        'mysql_security_firewall_rules',
+        'mysql_security_mask_data',
+        'mysql_security_password_validate',
+        'mysql_security_ssl_status',
+        'mysql_security_user_privileges',
+        'mysql_security_sensitive_tables',
+        'mysql_security_encryption_status'
+    ],
+    cluster: [
+        'mysql_gr_status',
+        'mysql_gr_members',
+        'mysql_gr_primary',
+        'mysql_gr_transactions',
+        'mysql_gr_flow_control',
+        'mysql_cluster_status',
+        'mysql_cluster_instances',
+        'mysql_cluster_topology',
+        'mysql_cluster_router_status',
+        'mysql_cluster_switchover'
+    ],
+    roles: [
+        'mysql_role_list',
+        'mysql_role_create',
+        'mysql_role_drop',
+        'mysql_role_grants',
+        'mysql_role_grant',
+        'mysql_role_assign',
+        'mysql_role_revoke',
+        'mysql_user_roles'
+    ],
+    docstore: [
+        'mysql_doc_list_collections',
+        'mysql_doc_create_collection',
+        'mysql_doc_drop_collection',
+        'mysql_doc_find',
+        'mysql_doc_add',
+        'mysql_doc_modify',
+        'mysql_doc_remove',
+        'mysql_doc_create_index',
+        'mysql_doc_collection_info'
+    ]
+};
+
+/**
+ * Meta-groups that expand to multiple tool groups.
+ * These provide shortcuts for common use cases.
+ * 
+ * STRICT LIMIT: NO group may exceed 50 tools.
+ * 
+ * Tool counts (verified):
+ *   starter:       38
+ *   essential:     15
+ *   dev-power:     45 (core:8 + schema:10 + performance:8 + stats:8 + fulltext:4 + transactions:7)
+ *   ai-data:       44 (core:8 + json:17 + docstore:9 + text:6 + fulltext:4)
+ *   ai-spatial:    43 (core:8 + spatial:12 + stats:8 + performance:8 + transactions:7)
+ *   dba-monitor:   35 (core:8 + monitoring:7 + performance:8 + sysschema:8 + optimization:4)
+ *   dba-manage:    33 (core:8 + admin:6 + backup:4 + replication:5 + partitioning:4 + events:6)
+ *   dba-secure:    42 (core:8 + security:9 + roles:8 + cluster:10 + transactions:7)
+ *   base-core:     48 (core:8 + json:17 + transactions:7 + text:6 + schema:10)
+ *   base-advanced: 39 (docstore:9 + spatial:12 + stats:8 + fulltext:4 + events:6)
+ *   ecosystem:     31
+ */
+export const META_GROUPS: Record<MetaGroup, ToolGroup[]> = {
+    // 1. General Use
+    starter: ['core', 'json', 'transactions', 'text'],
+    essential: ['core', 'transactions'],
+    'dev-power': ['core', 'schema', 'performance', 'stats', 'fulltext', 'transactions'],
+
+    // 2. AI Workloads
+    'ai-data': ['core', 'json', 'docstore', 'text', 'fulltext'],
+    'ai-spatial': ['core', 'spatial', 'stats', 'performance', 'transactions'],
+
+    // 3. DBA Workloads
+    'dba-monitor': ['core', 'monitoring', 'performance', 'sysschema', 'optimization'],
+    'dba-manage': ['core', 'admin', 'backup', 'replication', 'partitioning', 'events'],
+    'dba-secure': ['core', 'security', 'roles', 'cluster', 'transactions'],
+
+    // 4. Base Blocks (Building Blocks)
+    'base-core': ['core', 'json', 'transactions', 'text', 'schema'],
+    'base-advanced': ['docstore', 'spatial', 'stats', 'fulltext', 'events'],
+
+    // 5. Ecosystem
+    ecosystem: ['router', 'proxysql', 'shell']
+};

package/src/filtering/ToolFilter.ts

@@ -0,0 +1,363 @@
+/**
+ * mysql-mcp - Tool Filtering System
+ * 
+ * Parses and applies tool filter rules from environment variables.
+ * Compatible with db-mcp filtering syntax.
+ * 
+ * Syntax:
+ *   -group    → Disable all tools in a group
+ *   +group    → Enable all tools in a group
+ *   -tool     → Disable a specific tool
+ *   +tool     → Enable a specific tool (after group disable)
+ */
+
+import type {
+    ToolGroup,
+    MetaGroup,
+    ToolFilterConfig,
+    ToolDefinition
+} from '../types/index.js';
+
+/**
+ * Cached list of all tool names
+ * Lazy-initialized since TOOL_GROUPS is immutable
+ */
+let cachedAllToolNames: string[] | null = null;
+
+/**
+ * Reverse lookup map: tool name -> group
+ * Lazy-initialized for O(1) tool group lookups
+ */
+let toolToGroupMap: Map<string, ToolGroup> | null = null;
+
+/**
+ * Default tool groups and their member tools.
+ * This serves as the canonical mapping of tools to groups.
+ */
+export { TOOL_GROUPS, META_GROUPS } from './ToolConstants.js';
+import { TOOL_GROUPS, META_GROUPS } from './ToolConstants.js';
+
+/**
+ * Get all tool names from all groups (cached)
+ */
+export function getAllToolNames(): string[] {
+    if (cachedAllToolNames) {
+        return cachedAllToolNames;
+    }
+    const groups = Object.keys(TOOL_GROUPS) as ToolGroup[];
+    cachedAllToolNames = groups.flatMap(group => TOOL_GROUPS[group]);
+    return cachedAllToolNames;
+}
+
+/**
+ * Get or initialize the tool-to-group reverse lookup map
+ */
+function getToolToGroupMap(): Map<string, ToolGroup> {
+    if (toolToGroupMap) {
+        return toolToGroupMap;
+    }
+
+    toolToGroupMap = new Map<string, ToolGroup>();
+    const groups = Object.keys(TOOL_GROUPS) as ToolGroup[];
+    for (const group of groups) {
+        for (const tool of TOOL_GROUPS[group]) {
+            toolToGroupMap.set(tool, group);
+        }
+    }
+    return toolToGroupMap;
+}
+
+/**
+ * Get the group for a specific tool (O(1) lookup)
+ */
+export function getToolGroup(toolName: string): ToolGroup | undefined {
+    return getToolToGroupMap().get(toolName);
+}
+
+/**
+ * Clear all caches - useful for testing
+ */
+export function clearToolFilterCaches(): void {
+    cachedAllToolNames = null;
+    toolToGroupMap = null;
+}
+
+/**
+ * Check if a name is a valid tool group
+ */
+function isToolGroup(name: string): name is ToolGroup {
+    return name in TOOL_GROUPS;
+}
+
+/**
+ * Check if a name is a valid meta-group
+ */
+function isMetaGroup(name: string): name is MetaGroup {
+    return name in META_GROUPS;
+}
+
+/**
+ * Get all tool names from a meta-group
+ */
+export function getMetaGroupTools(metaGroup: MetaGroup): string[] {
+    const tools: string[] = [];
+    for (const group of META_GROUPS[metaGroup]) {
+        tools.push(...TOOL_GROUPS[group]);
+    }
+    return tools;
+}
+
+/**
+ * Parse a tool filter string into structured rules
+ * 
+ * @param filterString - The filter string (e.g., "-base,-ecosystem,+starter")
+ * @returns Parsed filter configuration
+ */
+export function parseToolFilter(filterString: string | undefined): ToolFilterConfig {
+    const allTools = getAllToolNames();
+    const enabledTools = new Set<string>(allTools);
+
+    if (!filterString || filterString.trim() === '') {
+        // Default to 'starter' group if no filter key is provided
+        const starterTools = new Set(getMetaGroupTools('starter'));
+        return {
+            raw: '',
+            rules: [],
+            enabledTools: starterTools
+        };
+    }
+
+    const rules: ToolFilterConfig['rules'] = [];
+    const parts = filterString.split(',').map(p => p.trim()).filter(p => p);
+
+    if (parts.length === 0) {
+        return {
+            raw: filterString,
+            rules: [],
+            enabledTools
+        };
+    }
+
+    // If first rule is exclusion (-), start with ALL tools
+    // If first rule is inclusion (+) or no prefix, start with NO tools (whitelist mode)
+    const firstPart = parts[0];
+    if (!firstPart) {
+        // Should be unreachable due to parts.length check above
+        return {
+            raw: filterString,
+            rules: [],
+            enabledTools
+        };
+    }
+    const startsWithExclude = firstPart.startsWith('-');
+
+    if (!startsWithExclude) {
+        enabledTools.clear();
+    }
+
+    for (const part of parts) {
+        if (!part) continue;
+
+        let isInclude = true; // Default to include
+        let isExclude = false;
+        let target = part;
+
+        if (part.startsWith('+')) {
+            isInclude = true;
+            target = part.substring(1);
+        } else if (part.startsWith('-')) {
+            isInclude = false;
+            isExclude = true;
+            target = part.substring(1);
+        }
+
+        // Special case: 'all'
+        if (target === 'all') {
+            if (isExclude) {
+                enabledTools.clear();
+            } else {
+                for (const tool of allTools) {
+                    enabledTools.add(tool);
+                }
+            }
+            continue;
+        }
+
+        const targetIsMetaGroup = isMetaGroup(target);
+        const targetIsGroup = isToolGroup(target);
+
+        rules.push({
+            type: isInclude ? 'include' : 'exclude',
+            target,
+            isGroup: targetIsGroup || targetIsMetaGroup
+        });
+
+        if (targetIsMetaGroup) {
+            // Expand meta-group to all its underlying groups' tools
+            const metaGroupTools = getMetaGroupTools(target as MetaGroup);
+            if (isExclude) {
+                for (const tool of metaGroupTools) {
+                    enabledTools.delete(tool);
+                }
+            } else {
+                for (const tool of metaGroupTools) {
+                    enabledTools.add(tool);
+                }
+            }
+        } else if (targetIsGroup) {
+            const groupTools = TOOL_GROUPS[target as ToolGroup];
+            if (isExclude) {
+                for (const tool of groupTools) {
+                    enabledTools.delete(tool);
+                }
+            } else {
+                for (const tool of groupTools) {
+                    enabledTools.add(tool);
+                }
+            }
+        } else {
+            // Individual tool
+            if (isExclude) {
+                enabledTools.delete(target);
+            } else {
+                enabledTools.add(target);
+            }
+        }
+    }
+
+    return {
+        raw: filterString,
+        rules,
+        enabledTools
+    };
+}
+
+/**
+ * Check if a tool is enabled based on filter configuration
+ */
+export function isToolEnabled(toolName: string, config: ToolFilterConfig): boolean {
+    return config.enabledTools.has(toolName);
+}
+
+/**
+ * Filter a list of tool definitions based on filter configuration
+ */
+export function filterTools(
+    tools: ToolDefinition[],
+    config: ToolFilterConfig
+): ToolDefinition[] {
+    return tools.filter(tool => config.enabledTools.has(tool.name));
+}
+
+/**
+ * Get the tool filter from environment variable
+ */
+export function getToolFilterFromEnv(): ToolFilterConfig {
+    const filterString = process.env['MYSQL_MCP_TOOL_FILTER'] ??
+        process.env['TOOL_FILTER'] ??
+        '';
+    return parseToolFilter(filterString);
+}
+
+/**
+ * Calculate token savings from tool filtering
+ * Assumes ~200 tokens per tool definition (description + parameters)
+ */
+export function calculateTokenSavings(
+    totalTools: number,
+    enabledTools: number,
+    tokensPerTool = 200
+): { tokensSaved: number; percentSaved: number } {
+    const disabledTools = totalTools - enabledTools;
+    const tokensSaved = disabledTools * tokensPerTool;
+    const percentSaved = totalTools > 0
+        ? Math.round((disabledTools / totalTools) * 100)
+        : 0;
+
+    return { tokensSaved, percentSaved };
+}
+
+/**
+ * Generate a summary of the current filter configuration
+ */
+export function getFilterSummary(config: ToolFilterConfig): string {
+    const allTools = getAllToolNames();
+    const enabledCount = config.enabledTools.size;
+    const totalCount = allTools.length;
+
+    const lines: string[] = [
+        `Tool Filter Summary:`,
+        `  Enabled: ${enabledCount}/${totalCount} tools`
+    ];
+
+    if (config.rules.length > 0) {
+        lines.push(`  Rules applied:`);
+        for (const rule of config.rules) {
+            const prefix = rule.type === 'include' ? '+' : '-';
+            // Determine type: meta-group, group, or tool
+            let type: string;
+            if (isMetaGroup(rule.target)) {
+                type = 'meta-group';
+            } else if (rule.isGroup) {
+                type = 'group';
+            } else {
+                type = 'tool';
+            }
+            lines.push(`    ${prefix}${rule.target} (${type})`);
+        }
+    }
+
+    // Show disabled groups
+    const disabledGroups: string[] = [];
+    const partialGroups: string[] = [];
+
+    const groups = Object.keys(TOOL_GROUPS) as ToolGroup[];
+    for (const group of groups) {
+        const groupTools = TOOL_GROUPS[group];
+        const enabledInGroup = groupTools.filter(t => config.enabledTools.has(t)).length;
+
+        if (enabledInGroup === 0) {
+            disabledGroups.push(group);
+        } else if (enabledInGroup < groupTools.length) {
+            partialGroups.push(`${group} (${enabledInGroup}/${groupTools.length})`);
+        }
+    }
+
+    if (disabledGroups.length > 0) {
+        lines.push(`  Disabled groups: ${disabledGroups.join(', ')}`);
+    }
+
+    if (partialGroups.length > 0) {
+        lines.push(`  Partial groups: ${partialGroups.join(', ')}`);
+    }
+
+    const { tokensSaved, percentSaved } = calculateTokenSavings(totalCount, enabledCount);
+    if (tokensSaved > 0) {
+        lines.push(`  Token savings: ~${tokensSaved} tokens (${percentSaved}%)`);
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Get a list of all tool groups with their tool counts
+ */
+export function getToolGroupInfo(): { group: ToolGroup; count: number; tools: string[] }[] {
+    const groups = Object.keys(TOOL_GROUPS) as ToolGroup[];
+    return groups.map(group => ({
+        group,
+        count: TOOL_GROUPS[group].length,
+        tools: [...TOOL_GROUPS[group]]
+    }));
+}
+
+/**
+ * Get a list of all meta-groups with their expanded tool counts
+ */
+export function getMetaGroupInfo(): { metaGroup: MetaGroup; groups: ToolGroup[]; count: number }[] {
+    return Object.entries(META_GROUPS).map(([metaGroup, groups]) => ({
+        metaGroup: metaGroup as MetaGroup,
+        groups,
+        count: getMetaGroupTools(metaGroup as MetaGroup).length
+    }));
+}