docs: expand Performance Tuning section, fix insecure temp file, update CI (#40)

Co-authored-by: Temp <mike@adamic.ai>

Author: neverinfamous

.github/workflows/docker-publish.yml

@@ -311,7 +311,7 @@ jobs:
           password: ${{ secrets.DOCKER_PASSWORD }}
           repository: ${{ env.IMAGE_NAME }}
           readme-filepath: ./DOCKER_README.md
-          short-description: "MySQL MCP with 191 tools, OAuth 2.1, HTTP Streamable, Smart Tool Filtering & Connection Pooling."
+          short-description: "MySQL MCP with 192 tools, OAuth 2.1, HTTP Streamable, Smart Tool Filtering & Connection Pooling."
 
       - name: Deployment Summary
         if: github.ref == 'refs/heads/master'

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Security
+
+- **`mysqlsh_run_script` Secure Temporary File Handling (CodeQL)** — Replaced insecure `os.tmpdir()` + manual filename pattern with `fs.mkdtemp()` for SQL script temp files. The previous approach created predictable files in the shared OS temp directory, flagged by CodeQL as `js/insecure-temporary-file`. Now creates a unique temporary directory with restrictive permissions via `mkdtemp`, writes the script inside it, and recursively removes the directory after execution.
+
 ## [2.2.0] - 2026-02-08
 
 ### Fixed

DOCKER_README.md

@@ -236,6 +236,8 @@ Use the remote hostname directly:
 > [!IMPORTANT]
 > **AI IDEs like Cursor have tool limits (typically 40-50 tools).** With 192 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend `starter` (38 tools) as a starting point.
 
+> **AntiGravity Users:** Server instructions are automatically sent to MCP clients during initialization. However, AntiGravity does not currently support MCP server instructions. For optimal usage in AntiGravity, manually provide the contents of [`src/constants/ServerInstructions.ts`](src/constants/ServerInstructions.ts) to the agent in your prompt or user rules.
+
 ### What Can You Filter?
 
 The `--tool-filter` argument accepts **shortcuts**, **groups**, or **tool names** — mix and match freely:
@@ -497,13 +499,17 @@ For specialized setups, see these Wiki pages:
 
 ## ⚡ Performance Tuning
 
+Schema metadata is cached to reduce repeated queries during tool/resource invocations.
+
 | Variable                | Default | Description                                        |
 | ----------------------- | ------- | -------------------------------------------------- |
 | `METADATA_CACHE_TTL_MS` | `30000` | Cache TTL for schema metadata (milliseconds)       |
 | `LOG_LEVEL`             | `info`  | Log verbosity: `debug`, `info`, `warning`, `error` |
 
 > **Tip:** Lower `METADATA_CACHE_TTL_MS` for development (e.g., `5000`), or increase it for production with stable schemas (e.g., `300000` = 5 min).
 
+> **Built-in payload optimization:** Many tools support optional `summary: true` for condensed responses and `limit` parameters to cap result sizes. These are particularly useful for cluster status, monitoring, and sys schema tools where full responses can be large. See [`ServerInstructions.ts`](https://github.com/neverinfamous/mysql-mcp/blob/master/src/constants/ServerInstructions.ts) for per-tool details.
+
 ---
 
 ### CLI Options

README.md

@@ -238,6 +238,8 @@ Use the remote hostname directly:
 > [!IMPORTANT]
 > **AI IDEs like Cursor have tool limits (typically 40-50 tools).** With 192 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend `starter` (38 tools) as a starting point.
 
+> **AntiGravity Users:** Server instructions are automatically sent to MCP clients during initialization. However, AntiGravity does not currently support MCP server instructions. For optimal usage in AntiGravity, manually provide the contents of [`src/constants/ServerInstructions.ts`](src/constants/ServerInstructions.ts) to the agent in your prompt or user rules.
+
 ### What Can You Filter?
 
 The `--tool-filter` argument accepts **shortcuts**, **groups**, or **tool names** — mix and match freely:
@@ -515,13 +517,17 @@ For specialized setups, see these Wiki pages:
 
 ## ⚡ Performance Tuning
 
+Schema metadata is cached to reduce repeated queries during tool/resource invocations.
+
 | Variable                | Default | Description                                        |
 | ----------------------- | ------- | -------------------------------------------------- |
 | `METADATA_CACHE_TTL_MS` | `30000` | Cache TTL for schema metadata (milliseconds)       |
 | `LOG_LEVEL`             | `info`  | Log verbosity: `debug`, `info`, `warning`, `error` |
 
 > **Tip:** Lower `METADATA_CACHE_TTL_MS` for development (e.g., `5000`), or increase it for production with stable schemas (e.g., `300000` = 5 min).
 
+> **Built-in payload optimization:** Many tools support optional `summary: true` for condensed responses and `limit` parameters to cap result sizes. These are particularly useful for cluster status, monitoring, and sys schema tools where full responses can be large. See [ServerInstructions.ts](src/constants/ServerInstructions.ts) for per-tool details.
+
 ---
 
 ### CLI Options

src/adapters/mysql/tools/shell/__tests__/restore.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import * as child_process from "child_process";
+import * as fsModule from "fs";
 import {
   createMockMySQLAdapter,
   createMockRequestContext,
@@ -13,6 +14,20 @@ vi.mock("child_process", () => ({
   spawn: vi.fn(),
 }));
 
+vi.mock("fs", async () => {
+  const actual =
+    await vi.importActual<typeof import("fs")>("fs");
+  return {
+    ...actual,
+    promises: {
+      ...actual.promises,
+      mkdtemp: vi.fn().mockResolvedValue("/tmp/mysqlsh_script_abc123"),
+      writeFile: vi.fn().mockResolvedValue(undefined),
+      rm: vi.fn().mockResolvedValue(undefined),
+    },
+  };
+});
+
 describe("Shell Restore and Script Tools", () => {
   let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
   let mockContext: ReturnType<typeof createMockRequestContext>;
@@ -226,7 +241,7 @@ describe("Shell Restore and Script Tools", () => {
       expect(args).toContain("--py");
     });
 
-    it("should run sql script", async () => {
+    it("should run sql script via secure temp file", async () => {
       setupMockSpawn("SQL output");
 
       const tool = createShellRunScriptTool();
@@ -241,6 +256,20 @@ describe("Shell Restore and Script Tools", () => {
       expect(result.success).toBe(true);
       const args = mockSpawn.mock.calls[0][1];
       expect(args).toContain("--sql");
+      expect(args).toContain("--file");
+
+      // Verify secure temp dir was created and cleaned up
+      const fsp = fsModule.promises;
+      expect(fsp.mkdtemp).toHaveBeenCalled();
+      expect(fsp.writeFile).toHaveBeenCalledWith(
+        expect.stringContaining("script.sql"),
+        "SELECT 1",
+        "utf8",
+      );
+      expect(fsp.rm).toHaveBeenCalledWith(
+        "/tmp/mysqlsh_script_abc123",
+        { recursive: true },
+      );
     });
   });
 });

src/adapters/mysql/tools/shell/restore.ts

@@ -169,10 +169,12 @@ export function createShellRunScriptTool(): ToolDefinition {
       // SQL scripts with comments or multi-line content break when passed via -e
       // Use --file approach for SQL to properly handle all syntax
       if (language === "sql") {
-        const tempFile = join(
-          tmpdir(),
-          `mysqlsh_script_${Date.now()}_${Math.random().toString(36).slice(2)}.sql`,
+        // Create a secure temp directory via mkdtemp (restrictive permissions,
+        // unique path) to avoid CodeQL js/insecure-temporary-file alert.
+        const tempDir = await fs.mkdtemp(
+          join(tmpdir(), `mysqlsh_script_`),
         );
+        const tempFile = join(tempDir, "script.sql");
         try {
           await fs.writeFile(tempFile, script, "utf8");
           const args = [
@@ -184,8 +186,8 @@ export function createShellRunScriptTool(): ToolDefinition {
           ];
           result = await execMySQLShell(args, { timeout });
         } finally {
-          // Cleanup temp file
-          await fs.unlink(tempFile).catch(() => void 0);
+          // Cleanup temp directory and its contents
+          await fs.rm(tempDir, { recursive: true }).catch(() => void 0);
         }
       } else {
         // JS and Python work fine with -e