@neverinfamous/mysql-mcp 2.3.1 → 3.0.1

package/src/__tests__/perf.test.ts

@@ -65,9 +65,9 @@ describe("Performance Tests", () => {
       expect(cachedCallTime.avg).toBeLessThan(0.5);
     });
 
-    it("should return consistent count of 193 tools", () => {
+    it("should return consistent count of 192 tools", () => {
       const tools = getAllToolNames();
-      expect(tools).toHaveLength(193);
+      expect(tools).toHaveLength(192);
     });
   });
 
@@ -165,7 +165,7 @@ describe("Performance Tests", () => {
     describe("filterTools performance", () => {
       const mockHandler = async () => ({ result: "ok" });
 
-      it("should filter 193 tools efficiently", () => {
+      it("should filter 192 tools efficiently", () => {
         // Create mock tools matching all tool names
         const allToolNames = getAllToolNames();
         const mockTools: ToolDefinition[] = allToolNames.map((name) => ({
@@ -198,7 +198,7 @@ describe("Performance Tests", () => {
 
         // First call builds the cache
         const firstCall = adapter.getToolDefinitions();
-        expect(firstCall).toHaveLength(193);
+        expect(firstCall).toHaveLength(192);
 
         // Subsequent calls should return same reference (cached)
         const secondCall = adapter.getToolDefinitions();
@@ -213,7 +213,7 @@ describe("Performance Tests", () => {
         expect(timing.avg).toBeLessThan(0.5);
       });
 
-      it("should return consistent tool count of 193 regardless of filter default", () => {
+      it("should return consistent tool count of 192 regardless of filter default", () => {
         const adapter = new MySQLAdapter();
 
         // getToolDefinitions returns ALL definitions available in the adapter,
@@ -221,7 +221,7 @@ describe("Performance Tests", () => {
         // Wait, MySQLAdapter.getToolDefinitions() returns all tools?
         // Yes, checking the implementation... it usually does.
         const tools = adapter.getToolDefinitions();
-        expect(tools).toHaveLength(193);
+        expect(tools).toHaveLength(192);
       });
     });
   });

package/src/adapters/DatabaseAdapter.ts

@@ -322,26 +322,57 @@ export abstract class DatabaseAdapter {
    * Register a single prompt with the MCP server
    */
   protected registerPrompt(server: McpServer, prompt: PromptDefinition): void {
-    // Build Zod schema from prompt.arguments definitions
-    const zodShape: Record<string, z.ZodType> = {};
-    if (prompt.arguments) {
+    // Build a Zod raw shape from prompt.arguments so the SDK can
+    // advertise argument metadata in prompts/list via promptArgumentsFromSchema().
+    //
+    // ALL fields are .optional() because the SDK validates BEFORE our handler
+    // runs. If required fields used z.string() (non-optional), clients that
+    // invoke prompts without filling in required args would get a raw Zod
+    // error instead of our graceful guide message. Required-ness is enforced
+    // by the handler-level missing-arg check below.
+    let argsSchema: Record<string, z.ZodType> | undefined;
+    if (prompt.arguments && prompt.arguments.length > 0) {
+      argsSchema = {};
       for (const arg of prompt.arguments) {
-        zodShape[arg.name] = arg.required
-          ? z.string().describe(arg.description)
-          : z.string().optional().describe(arg.description);
+        argsSchema[arg.name] = z.string().optional().describe(arg.description);
       }
     }
 
-    server.registerPrompt(
+    const registered = server.registerPrompt(
       prompt.name,
       {
         description: prompt.description,
-        argsSchema: zodShape,
+        argsSchema,
       },
       async (providedArgs) => {
         const context = this.createContext();
         // Cast args to Record<string, string> for handler compatibility
-        const args = providedArgs as Record<string, string>;
+        const args = (providedArgs ?? {}) as Record<string, string>;
+
+        // Check for missing required arguments
+        const requiredArgs = prompt.arguments?.filter((a) => a.required) ?? [];
+        const missingArgs = requiredArgs.filter((a) => !args[a.name]);
+        if (missingArgs.length > 0) {
+          // Return a helpful guide listing expected arguments
+          const argList = (prompt.arguments ?? [])
+            .map(
+              (a) =>
+                `- **${a.name}**${a.required ? " (required)" : " (optional)"}: ${a.description}`,
+            )
+            .join("\n");
+          return {
+            messages: [
+              {
+                role: "user" as const,
+                content: {
+                  type: "text" as const,
+                  text: `# ${prompt.name}\n\n${prompt.description}\n\n## Arguments\n\n${argList}\n\nPlease provide the required arguments to use this prompt.`,
+                },
+              },
+            ],
+          };
+        }
+
         const result = await prompt.handler(args, context);
         return {
           messages: [
@@ -359,6 +390,24 @@ export abstract class DatabaseAdapter {
         };
       },
     );
+
+    // Patch the SDK's stored Zod object schema to accept `undefined` input.
+    // The SDK's prompts/get handler calls safeParseAsync(argsSchema, args)
+    // where args may be `undefined` when clients omit them. Zod v4's
+    // z.object().safeParse(undefined) rejects — but we need it to succeed
+    // (coercing to {}) so our handler-level required-arg check can provide
+    // a graceful guide message instead of a raw Zod crash.
+    // The metadata (shape, type) is preserved for promptArgumentsFromSchema().
+    if (registered.argsSchema) {
+      const schema = registered.argsSchema as unknown as {
+        _zod: { run: (ctx: { value: unknown }) => unknown };
+      };
+      const originalRun = schema._zod.run.bind(schema._zod);
+      schema._zod.run = (ctx: { value: unknown }) => {
+        ctx.value ??= {};
+        return originalRun(ctx);
+      };
+    }
   }
 
   // =========================================================================

package/src/adapters/__tests__/DatabaseAdapter.test.ts

@@ -370,7 +370,22 @@ describe("DatabaseAdapter", () => {
       mockServer = {
         registerTool: vi.fn(),
         registerResource: vi.fn(),
-        registerPrompt: vi.fn(),
+        // Return a RegisteredPrompt-like object so `registered.argsSchema`
+        // is accessible for schema patching in DatabaseAdapter.registerPrompt()
+        registerPrompt: vi.fn().mockImplementation((_name, config, _cb) => {
+          // Mimic SDK: if argsSchema is provided, create a z.object() from it.
+          // Use a mock with _zod.run so the patching code doesn't crash.
+          let argsSchema: unknown = undefined;
+          if (config?.argsSchema) {
+            argsSchema = {
+              _zod: {
+                def: { type: "object", shape: config.argsSchema },
+                run: vi.fn((ctx: { value: unknown }) => ctx),
+              },
+            };
+          }
+          return { argsSchema };
+        }),
       };
     });
 
@@ -438,7 +453,7 @@ describe("DatabaseAdapter", () => {
         );
       });
 
-      it("should handle prompts with arguments", () => {
+      it("should pass argsSchema for prompts with arguments so SDK advertises them", () => {
         const promptWithArgs: PromptDefinition = {
           name: "arg_prompt",
           description: "desc",
@@ -454,18 +469,84 @@ describe("DatabaseAdapter", () => {
         ]);
         adapter.registerPrompts(mockServer as never);
 
+        // argsSchema must be a Zod raw shape so the SDK can:
+        // 1. Advertise arguments in prompts/list
+        // 2. Validate arguments in prompts/get
+        const calledConfig = mockServer.registerPrompt.mock.calls[0][1];
+        expect(calledConfig.argsSchema).toBeDefined();
+        expect(calledConfig.argsSchema).toHaveProperty("required_arg");
+        expect(calledConfig.argsSchema).toHaveProperty("optional_arg");
+      });
+
+      it("should not pass argsSchema for prompts without arguments", () => {
+        adapter.registerPrompts(mockServer as never);
+
         expect(mockServer.registerPrompt).toHaveBeenCalledWith(
-          "arg_prompt",
+          "test_prompt",
           expect.objectContaining({
-            description: "desc",
-            argsSchema: expect.objectContaining({
-              required_arg: expect.anything(),
-              optional_arg: expect.anything(),
-            }),
+            description: "A test prompt",
+            argsSchema: undefined,
           }),
           expect.any(Function),
         );
       });
+
+      it("should pass argsSchema for prompts with all-optional arguments", () => {
+        const allOptionalPrompt: PromptDefinition = {
+          name: "all_optional_prompt",
+          description: "All optional args",
+          arguments: [
+            { name: "opt_a", description: "optional a", required: false },
+            { name: "opt_b", description: "optional b", required: false },
+          ],
+          handler: async () => "result",
+        };
+
+        vi.spyOn(adapter, "getPromptDefinitions").mockReturnValue([
+          allOptionalPrompt,
+        ]);
+        adapter.registerPrompts(mockServer as never);
+
+        // argsSchema must be a Zod raw shape (even when all optional)
+        // so the SDK advertises arguments in prompts/list
+        const calledConfig = mockServer.registerPrompt.mock.calls[0][1];
+        expect(calledConfig.argsSchema).toBeDefined();
+        expect(calledConfig.argsSchema).toHaveProperty("opt_a");
+        expect(calledConfig.argsSchema).toHaveProperty("opt_b");
+      });
+
+      it("should return guide message when required args are missing", async () => {
+        const promptWithRequired: PromptDefinition = {
+          name: "required_prompt",
+          description: "Needs args",
+          arguments: [
+            { name: "operation", description: "The operation", required: true },
+            { name: "note", description: "A note", required: false },
+          ],
+          handler: async () => "should not reach",
+        };
+
+        vi.spyOn(adapter, "getPromptDefinitions").mockReturnValue([
+          promptWithRequired,
+        ]);
+        adapter.registerPrompts(mockServer as never);
+
+        // Call handler with no args (simulates MCP client sending undefined)
+        const handler = mockServer.registerPrompt.mock.calls[0][2] as Function;
+        const result = await handler({});
+
+        // Should return a guide message, not the handler output
+        expect(result.messages[0].content.text).toContain("required_prompt");
+        expect(result.messages[0].content.text).toContain(
+          "**operation** (required)",
+        );
+        expect(result.messages[0].content.text).toContain(
+          "**note** (optional)",
+        );
+        expect(result.messages[0].content.text).toContain(
+          "Please provide the required arguments",
+        );
+      });
     });
 
     describe("handler execution", () => {

package/src/adapters/mysql/MySQLAdapter.ts

@@ -269,13 +269,19 @@ export class MySQLAdapter extends DatabaseAdapter {
     const startTime = Date.now();
 
     try {
-      const [results, fields] = await connection.execute(sql, params);
+      const [results, fields] = await connection.execute(
+        sql,
+        params as (string | number | null)[],
+      );
       return this.processExecutionResult(results, fields, startTime);
     } catch (error) {
       if (this.isUnsupportedPreparedStatementError(error)) {
         // Fallback to text protocol
         try {
-          const [results, fields] = await connection.query(sql, params);
+          const [results, fields] = await connection.query(
+            sql,
+            params as (string | number | null)[],
+          );
           return this.processExecutionResult(results, fields, startTime);
         } catch (fallbackError) {
           const err = fallbackError as Error;
@@ -544,6 +550,15 @@ export class MySQLAdapter extends DatabaseAdapter {
     return this.pool;
   }
 
+  /**
+   * Clear the schema metadata cache.
+   * Should be called after any DDL operation (CREATE/DROP/ALTER TABLE, INDEX, VIEW)
+   * to prevent stale metadata from being served during the cache TTL window.
+   */
+  clearSchemaCache(): void {
+    this.schemaManager.clearCache();
+  }
+
   /**
    * Get IDs of all active transactions (for Code Mode cleanup)
    */

package/src/adapters/mysql/SchemaManager.ts

@@ -201,9 +201,10 @@ export class SchemaManager {
       : "TABLE_SCHEMA = DATABASE()";
     const params = schemaName ? [schemaName, shortTableName] : [shortTableName];
 
-    // Get column information
-    const columnsResult = await this.executor.executeQuery(
-      `
+    // Performance optimization: run column and table queries in parallel
+    const [columnsResult, tableResult] = await Promise.all([
+      this.executor.executeQuery(
+        `
             SELECT 
                 COLUMN_NAME as name,
                 DATA_TYPE as type,
@@ -219,8 +220,23 @@ export class SchemaManager {
               AND TABLE_NAME = ?
             ORDER BY ORDINAL_POSITION
         `,
-      params,
-    );
+        params,
+      ),
+      this.executor.executeQuery(
+        `
+            SELECT 
+                TABLE_TYPE as type,
+                ENGINE as engine,
+                TABLE_ROWS as rowCount,
+                TABLE_COLLATION as collation,
+                TABLE_COMMENT as comment
+            FROM information_schema.TABLES
+            WHERE ${schemaClause}
+              AND TABLE_NAME = ?
+        `,
+        params,
+      ),
+    ]);
 
     const columns: ColumnInfo[] = (columnsResult.rows ?? []).map((row) => ({
       name: row["name"] as string,
@@ -234,22 +250,6 @@ export class SchemaManager {
       comment: row["comment"] as string | undefined,
     }));
 
-    // Get table info
-    const tableResult = await this.executor.executeQuery(
-      `
-            SELECT 
-                TABLE_TYPE as type,
-                ENGINE as engine,
-                TABLE_ROWS as rowCount,
-                TABLE_COLLATION as collation,
-                TABLE_COMMENT as comment
-            FROM information_schema.TABLES
-            WHERE ${schemaClause}
-              AND TABLE_NAME = ?
-        `,
-      params,
-    );
-
     const tableRow = tableResult.rows?.[0];
 
     const result: TableInfo = {

package/src/adapters/mysql/__tests__/MySQLAdapter.test.ts

@@ -606,7 +606,7 @@ describe("MySQLAdapter", () => {
       const first = adapter.getToolDefinitions();
       const second = adapter.getToolDefinitions();
       expect(first).toBe(second); // Same reference = cached
-      expect(first.length).toBe(193);
+      expect(first.length).toBe(192);
     });
   });
 

package/src/adapters/mysql/prompts/index.ts

@@ -256,31 +256,21 @@ function createSchemaDesignPrompt(): PromptDefinition {
     ],
     handler: (args: Record<string, string>, _context: RequestContext) => {
       return Promise.resolve(`
-You are a MySQL database architect. Design a schema for: ${args["entity"]}
+Design a MySQL schema for: ${args["entity"]}
 
 ${args["requirements"] ? `Requirements: ${args["requirements"]}` : ""}
 
-Please provide:
-1. CREATE TABLE statement with:
-   - Appropriate data types
-   - Primary key
-   - Indexes for common queries
-   - Foreign key relationships if applicable
-   - Engine: InnoDB (for transactions)
-   - Charset: utf8mb4 (for full Unicode support)
-
-2. Explanation of design choices
-
-3. Sample INSERT statements
-
-4. Common SELECT queries with indexes
-
-Best practices to follow:
-- Use underscore_case for column names
-- Include created_at and updated_at timestamps
-- Use UNSIGNED for positive-only integers
-- Consider JSON columns for flexible data
-- Add appropriate indexes based on query patterns
+Provide a CREATE TABLE statement with:
+- Appropriate data types
+- Primary key
+- Indexes for common queries
+- Foreign key relationships if applicable
+- Engine: InnoDB (for transactions)
+- Charset: utf8mb4 (for full Unicode support)
+
+Follow these conventions: underscore_case columns, created_at/updated_at timestamps, UNSIGNED for positive integers, JSON columns where appropriate.
+
+Briefly explain key design decisions.
 `);
     },
   };

package/src/adapters/mysql/prompts/proxysqlSetup.ts

@@ -82,7 +82,7 @@ PROXYSQL_PASSWORD=admin
 Use ProxySQL tools to verify:
 - \`proxysql_status\` - Check ProxySQL is running
 - \`proxysql_servers\` - List configured servers
-- \`proxysql_hostgroups\` - View hostgroup configuration
+- \`proxysql_connection_pool\` - View connection pool stats (filterable by hostgroup_id)
 - \`proxysql_query_rules\` - Review routing rules
 - \`proxysql_query_digest\` - Analyze query patterns
 

package/src/adapters/mysql/resources/docstore.ts

@@ -22,15 +22,14 @@ export function createDocstoreResource(
     },
     handler: async (_uri: string, _context: RequestContext) => {
       try {
-        // Check if X Plugin is enabled
-        const pluginResult = await adapter.executeQuery(
-          "SELECT PLUGIN_STATUS FROM information_schema.PLUGINS WHERE PLUGIN_NAME = 'mysqlx'",
-        );
-        const pluginRow = pluginResult.rows?.[0];
-        const xPluginEnabled = pluginRow?.["PLUGIN_STATUS"] === "ACTIVE";
-
-        // Get collections (tables with _id column and doc JSON column)
-        const collectionsResult = await adapter.executeQuery(`
+        // Performance optimization: run both independent queries in parallel
+        const [pluginResult, collectionsResult] = await Promise.all([
+          // Check if X Plugin is enabled
+          adapter.executeQuery(
+            "SELECT PLUGIN_STATUS FROM information_schema.PLUGINS WHERE PLUGIN_NAME = 'mysqlx'",
+          ),
+          // Get collections (tables with _id column and doc JSON column)
+          adapter.executeQuery(`
                     SELECT 
                         t.TABLE_NAME as collection_name,
                         t.TABLE_ROWS as row_count,
@@ -51,7 +50,11 @@ export function createDocstoreResource(
                             AND c2.COLUMN_NAME = '_id'
                       )
                     ORDER BY t.TABLE_NAME
-                `);
+                `),
+        ]);
+
+        const pluginRow = pluginResult.rows?.[0];
+        const xPluginEnabled = pluginRow?.["PLUGIN_STATUS"] === "ACTIVE";
 
         return {
           xPluginEnabled,

package/src/adapters/mysql/resources/events.ts

@@ -21,17 +21,12 @@ export function createEventsResource(
       priority: 0.6,
     },
     handler: async (_uri: string, _context: RequestContext) => {
-      // Get scheduler status
-      const schedulerResult = await adapter.executeQuery(
-        "SHOW VARIABLES LIKE 'event_scheduler'",
-      );
-      const schedulerRow = schedulerResult.rows?.[0];
-      const schedulerVal = schedulerRow?.["Value"];
-      const schedulerStatus =
-        typeof schedulerVal === "string" ? schedulerVal : "OFF";
-
-      // Get all events
-      const eventsResult = await adapter.executeQuery(`
+      // Performance optimization: run both independent queries in parallel
+      const [schedulerResult, eventsResult] = await Promise.all([
+        // Get scheduler status
+        adapter.executeQuery("SHOW VARIABLES LIKE 'event_scheduler'"),
+        // Get all events
+        adapter.executeQuery(`
                 SELECT 
                     EVENT_SCHEMA as schema_name,
                     EVENT_NAME as name,
@@ -43,7 +38,12 @@ export function createEventsResource(
                     LAST_EXECUTED as last_executed
                 FROM information_schema.EVENTS
                 ORDER BY EVENT_SCHEMA, EVENT_NAME
-            `);
+            `),
+      ]);
+      const schedulerRow = schedulerResult.rows?.[0];
+      const schedulerVal = schedulerRow?.["Value"];
+      const schedulerStatus =
+        typeof schedulerVal === "string" ? schedulerVal : "OFF";
 
       return {
         schedulerEnabled: schedulerStatus === "ON",

package/src/adapters/mysql/resources/indexes.ts

@@ -32,7 +32,7 @@ export function createIndexesResource(
         return { error: "No database selected" };
       }
 
-      // Get index statistics
+      // Get index statistics (required)
       const indexResult = await adapter.executeQuery(
         `
                 SELECT 
@@ -50,11 +50,15 @@ export function createIndexesResource(
         [database],
       );
 
-      // Try to get index usage from performance_schema if available
+      // Performance optimization: run unused + duplicate queries in parallel
+      // Both are optional — they may fail on older MySQL versions
       let unusedIndexes: unknown[] = [];
+      let duplicateIndexes: unknown[] = [];
+
       try {
-        const unusedResult = await adapter.executeQuery(
-          `
+        const [unusedResult, dupResult] = await Promise.all([
+          adapter.executeQuery(
+            `
                     SELECT 
                         object_schema as schema_name,
                         object_name as table_name,
@@ -65,18 +69,10 @@ export function createIndexesResource(
                       AND index_name != 'PRIMARY'
                       AND count_star = 0
                 `,
-          [database],
-        );
-        unusedIndexes = unusedResult.rows ?? [];
-      } catch {
-        // Performance schema may not be available
-      }
-
-      // Get duplicate/redundant indexes
-      let duplicateIndexes: unknown[] = [];
-      try {
-        const dupResult = await adapter.executeQuery(
-          `
+            [database],
+          ),
+          adapter.executeQuery(
+            `
                     SELECT 
                         a.TABLE_NAME as table_name,
                         a.INDEX_NAME as redundant_index,
@@ -94,11 +90,13 @@ export function createIndexesResource(
                       AND (a.INDEX_NAME != 'PRIMARY' AND b.INDEX_NAME != 'PRIMARY')
                     GROUP BY a.TABLE_NAME, a.INDEX_NAME, a.COLUMN_NAME, b.INDEX_NAME
                 `,
-          [database],
-        );
+            [database],
+          ),
+        ]);
+        unusedIndexes = unusedResult.rows ?? [];
         duplicateIndexes = dupResult.rows ?? [];
       } catch {
-        // May fail on older MySQL versions
+        // Performance schema may not be available on older MySQL versions
       }
 
       return {

package/src/adapters/mysql/resources/innodb.ts

@@ -23,10 +23,30 @@ export function createInnodbResource(
       priority: 0.7,
     },
     handler: async (_uri: string, _context: RequestContext) => {
-      // Get buffer pool status
-      const bufferPoolResult = await adapter.executeQuery(`
+      // Performance optimization: run all three independent queries in parallel
+      const [bufferPoolResult, configResult, opsResult] = await Promise.all([
+        // Get buffer pool status
+        adapter.executeQuery(`
                 SHOW GLOBAL STATUS WHERE Variable_name LIKE 'Innodb_buffer_pool%'
-            `);
+            `),
+        // Get buffer pool size configuration
+        adapter.executeQuery(`
+                SHOW GLOBAL VARIABLES WHERE Variable_name IN (
+                    'innodb_buffer_pool_size', 'innodb_buffer_pool_instances',
+                    'innodb_log_file_size', 'innodb_log_files_in_group',
+                    'innodb_flush_log_at_trx_commit', 'innodb_file_per_table'
+                )
+            `),
+        // Get row operations
+        adapter.executeQuery(`
+                SHOW GLOBAL STATUS WHERE Variable_name IN (
+                    'Innodb_rows_read', 'Innodb_rows_inserted', 
+                    'Innodb_rows_updated', 'Innodb_rows_deleted',
+                    'Innodb_data_reads', 'Innodb_data_writes',
+                    'Innodb_os_log_written', 'Innodb_log_writes'
+                )
+            `),
+      ]);
 
       const bufferPool: Record<string, number> = {};
       for (const row of bufferPoolResult.rows ?? []) {
@@ -36,30 +56,11 @@ export function createInnodbResource(
         );
       }
 
-      // Get buffer pool size configuration
-      const configResult = await adapter.executeQuery(`
-                SHOW GLOBAL VARIABLES WHERE Variable_name IN (
-                    'innodb_buffer_pool_size', 'innodb_buffer_pool_instances',
-                    'innodb_log_file_size', 'innodb_log_files_in_group',
-                    'innodb_flush_log_at_trx_commit', 'innodb_file_per_table'
-                )
-            `);
-
       const config: Record<string, string> = {};
       for (const row of configResult.rows ?? []) {
         config[row["Variable_name"] as string] = row["Value"] as string;
       }
 
-      // Get row operations
-      const opsResult = await adapter.executeQuery(`
-                SHOW GLOBAL STATUS WHERE Variable_name IN (
-                    'Innodb_rows_read', 'Innodb_rows_inserted', 
-                    'Innodb_rows_updated', 'Innodb_rows_deleted',
-                    'Innodb_data_reads', 'Innodb_data_writes',
-                    'Innodb_os_log_written', 'Innodb_log_writes'
-                )
-            `);
-
       const operations: Record<string, number> = {};
       for (const row of opsResult.rows ?? []) {
         operations[row["Variable_name"] as string] = parseInt(