@yanzhang123/readonly-db-mcp 0.7.2

package/SECURITY.md

@@ -0,0 +1,214 @@
+## MySQL Security Configuration
+
+### Creating a Restricted MySQL User
+
+It's crucial to create a dedicated MySQL user with minimal permissions for the MCP server. Never use the root account or a user with full administrative privileges.
+
+#### 1. Create a new MySQL user
+
+```sql
+-- Connect as root or administrator
+CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'your_secure_password';
+```
+
+#### 2. Grant minimal required permissions
+
+Basic read-only access (recommended for exploration and analysis):
+```sql
+-- Grant SELECT permission only
+GRANT SELECT ON your_database.* TO 'mcp_user'@'localhost';
+```
+
+Do not grant `INSERT`, `UPDATE`, `DELETE`, DDL, routine execution, file, lock, or
+temporary-table privileges to the MCP account. The server rejects those operations,
+and MySQL permissions provide the final security boundary.
+
+#### 3. Apply the permissions
+```sql
+FLUSH PRIVILEGES;
+```
+
+### Additional Security Measures
+
+1. **Network Access**
+   - Restrict the user to connecting only from localhost if the MCP server runs on the same machine
+   - If remote access is needed, specify exact IP addresses rather than using wildcards
+
+2. **Query Restrictions**
+   - Consider using VIEWs to further restrict data access
+   - Set an appropriate `max_queries_per_hour` limit:
+   ```sql
+   ALTER USER 'mcp_user'@'localhost' 
+   WITH MAX_QUERIES_PER_HOUR 1000;
+   ```
+
+3. **Data Access Control**
+   - Grant access only to specific tables when possible
+   - Use column-level permissions for sensitive data:
+   ```sql
+   GRANT SELECT (public_column1, public_column2) 
+   ON your_database.sensitive_table TO 'mcp_user'@'localhost';
+   ```
+
+4. **Regular Auditing**
+   - Enable MySQL audit logging for the MCP user
+   - Regularly review logs for unusual patterns
+   - Periodically review and adjust permissions
+
+### Environment Configuration
+
+When setting up the MCP server, use these restricted credentials in your environment:
+
+```bash
+MYSQL_USER=mcp_user
+MYSQL_PASSWORD=your_secure_password
+MYSQL_DATABASE=your_database
+MYSQL_HOST=localhost
+```
+
+### Monitoring Usage
+
+To monitor the MCP user's database usage:
+
+```sql
+-- Check current connections
+SELECT * FROM information_schema.PROCESSLIST 
+WHERE user = 'mcp_user';
+
+-- View user privileges
+SHOW GRANTS FOR 'mcp_user'@'localhost';
+
+-- Check resource limits
+SELECT * FROM mysql.user 
+WHERE user = 'mcp_user' AND host = 'localhost';
+```
+
+### Best Practices
+
+1. **Regular Password Rotation**
+   - Change the MCP user's password periodically
+   - Use strong, randomly generated passwords
+   - Update application configurations after password changes
+
+2. **Permission Review**
+   - Regularly audit granted permissions
+   - Remove unnecessary privileges
+   - Keep permissions as restrictive as possible
+
+3. **Access Patterns**
+   - Monitor query patterns for potential issues
+   - Set up alerts for unusual activity
+   - Maintain detailed logs of database access
+
+4. **Data Protection**
+   - Consider encrypting sensitive columns
+   - Use SSL/TLS for database connections (see **SSL/TLS Support** below)
+   - Implement data masking where appropriate
+
+### Secure Remote Access (SSH Tunneling)
+
+If your MySQL server is not on the same network as the MCP server, **do not expose MySQL directly to the internet.** Instead, use the built-in SSH tunneling support:
+
+1. Enable SSH tunneling by setting `MYSQL_SSH_ENABLE=true`.
+2. Configure your SSH jump host credentials and private key path.
+3. The MCP server will establish a secure encrypted tunnel and connect to MySQL over `localhost`, keeping your database port closed to the outside world.
+
+### SSL/TLS Support
+
+For production environments, always encrypt the connection between the MCP server and MySQL.
+
+Use the `MYSQL_SSL_MODE` environment variable to control encryption:
+- `DISABLED`: Allows plaintext only when explicitly selected; do not use in production.
+- `REQUIRED`: Ensures the connection is encrypted.
+- `VERIFY_CA`: Encrypts and verifies the server's certificate against a CA.
+- `VERIFY_IDENTITY`: Encrypts and verifies that the server's hostname matches the certificate.
+
+`REQUIRED` is the default, and the MCP verifies after connection that the
+connector reports an encrypted session. Specify the CA certificate path using
+`MYSQL_SSL_CA` when using either verification mode.
+
+### SQL Injection Protection
+
+The MCP server includes built-in protection against SQL injection for administrative operations:
+- All database and table identifiers provided via resources or tool arguments are strictly validated against a regex whitelist (`^[a-zA-Z0-9_$]+$`).
+- Identifiers are automatically quoted with backticks in internal queries.
+- `execute_sql` uses a lexer-style guard that ignores ordinary strings and comments but rejects MySQL `/*!...*/` and MariaDB `/*M!...*/` executable comments, multiple statements, DML, DDL, locks, transactions, `SELECT INTO`, and session assignment.
+- Stored functions and UDFs are fail-closed unless sqlglot recognizes them as a
+  built-in or their reviewed name is explicitly listed in `allowed_functions`.
+  Sequence advancement, lock functions and other known side-effecting functions
+  remain blocked even inside `SELECT`.
+- All exposed SQL then runs inside a MySQL read-only transaction. Normal completion rolls back; cancellation or result truncation closes the socket, forcing rollback and stopping unread-row production.
+- Every MCP tool is advertised as read-only and non-destructive.
+- Named profiles can define `allowed_databases`; SQL table/function qualifiers and resource URIs are checked against it with a MySQL AST parser.
+- User-supplied `SHOW` statements must be safely scoped to an allowed database; server-wide account, process, engine, binary-log, status, and variable inspection is blocked.
+- System schemas are blocked for user SQL unless `allow_system_databases=true` is explicitly configured.
+- Full-call, connector socket, and MySQL/MariaDB statement timeouts limit resource exhaustion. MCP cancellation actively closes the connector socket.
+- Audit logs never contain SQL text, result data, credentials, hosts, usernames,
+  or SSH key paths. They contain a literal-free fingerprint plus the policy and
+  execution metadata needed for investigation.
+- Result cells whose output or source columns match `mask_columns` are replaced
+  with `[REDACTED]`. Source-column detection traverses aliases, expressions and
+  CTEs; review the patterns for your schema because name-based masking cannot
+  replace database views or column-level permissions.
+
+These controls enforce the MCP read-only contract even when the supplied MySQL
+account has write privileges. A `SELECT`-only account is still recommended as
+an independent containment layer, and `check_connection` reports broader grants.
+
+### Enterprise Audit Controls
+
+For durable audit records, set an absolute `audit_log_file` on each named
+profile. The server writes one canonical JSON object per line and rotates it by
+size. Events include:
+
+- schema version, UTC timestamp, unique event ID and MCP request ID
+- MCP operation and client name/version when exposed by the SDK
+- optional `actor`, `purpose`, and `ticket_id`
+- connection profile, target database, query type and literal-free fingerprint
+- allowed/denied policy decision, internal/user-query flag and read-only
+  enforcement marker
+- success, denial, error, timeout or cancellation outcome, duration, row count,
+  truncation and error type
+
+Set `audit_required_context = ["actor", "purpose", "ticket_id"]` to reject
+queries missing attribution before connecting. Set `audit_hmac_key_env` to the
+name of a secret-manager supplied environment variable to sign every event with
+HMAC-SHA256. `audit_fail_closed=true` requires a durable audit file and makes
+audit sink/signing failures fail the MCP call. `audit_fsync=true` trades
+throughput for stronger local durability.
+
+Fail-closed query execution uses two-phase audit recording: an fsynced
+`status=started` event must be durable before a database connection is opened,
+then a terminal success, denial, error, timeout, or cancellation event is
+written. Monitoring should alert on started events without a matching terminal
+event, which can indicate process termination or an unavailable audit sink.
+
+The audit context and MCP client metadata are caller assertions. For
+cryptographically strong human attribution, terminate the remote transport at
+an authenticated gateway, map the authenticated principal into request
+metadata, and forward the JSONL stream to an append-only SIEM or log service.
+Restrict audit file and HMAC-key access at the operating-system level.
+
+Rejected DML, DDL, multi-statement, locking and cross-database attempts are
+audited without sending them to MySQL and without recording their SQL text.
+
+Connection diagnostics do not return raw authenticated usernames, grant
+statements, profile-file paths, or database-supplied error messages. They expose
+an irreversible account fingerprint, grant count, privilege classification,
+numeric MySQL error references and policy metadata instead.
+
+### Remote Transport
+
+SSE binds to `127.0.0.1` by default. A non-loopback bind is rejected unless
+`MCP_SSE_BEARER_TOKEN` contains at least 32 characters or
+`MCP_SSE_TRUST_PROXY_AUTH=true` explicitly declares that an authenticated
+reverse proxy is the only entry point. DNS-rebinding Host validation remains
+enabled. Never set the proxy-trust flag if clients can reach the MCP port
+directly.
+
+### SSH and Connection Reuse
+
+Named SSH tunnels are started once per profile, use a dynamic local port by
+default, are health-checked before reuse, restart after failure, and terminate at
+server shutdown. Connection pools are isolated by profile, endpoint, database,
+and credential fingerprint. Set `pool_size=0` to disable pooling.

package/npm/bin/mysql-mcp-server-readonly.cjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { main } = require("../lib/launcher.cjs");
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`mysql-mcp-server-readonly: ${message}\n`);
+  process.exitCode = 1;
+});

package/npm/lib/launcher.cjs

@@ -0,0 +1,294 @@
+"use strict";
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+
+const manifest = require("../../package.json");
+const packageRoot = path.resolve(__dirname, "..", "..");
+
+function pythonCandidates(environment = process.env, platform = process.platform) {
+  if (environment.MYSQL_MCP_PYTHON) {
+    return [[environment.MYSQL_MCP_PYTHON, []]];
+  }
+  if (platform === "win32") {
+    return [
+      ["py", ["-3.11"]],
+      ["py", ["-3"]],
+      ["python", []],
+    ];
+  }
+  return [
+    ["python3", []],
+    ["python", []],
+  ];
+}
+
+function detectPython(options = {}) {
+  const candidates = options.candidates || pythonCandidates();
+  const run = options.spawnSync || spawnSync;
+  for (const [command, prefix] of candidates) {
+    const result = run(
+      command,
+      [
+        ...prefix,
+        "-c",
+        "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')",
+      ],
+      {
+        encoding: "utf8",
+        windowsHide: true,
+      },
+    );
+    if (result.status !== 0) {
+      continue;
+    }
+    const match = String(result.stdout).trim().match(/^(\d+)\.(\d+)$/);
+    if (match && (Number(match[1]) > 3 || Number(match[2]) >= 11)) {
+      return { command, prefix };
+    }
+  }
+  throw new Error(
+    "Python 3.11 or newer is required. Install Python or set MYSQL_MCP_PYTHON.",
+  );
+}
+
+function cacheBase(environment = process.env, platform = process.platform) {
+  if (environment.MYSQL_MCP_NPM_CACHE_DIR) {
+    return path.resolve(environment.MYSQL_MCP_NPM_CACHE_DIR);
+  }
+  if (platform === "win32") {
+    return path.join(
+      environment.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"),
+      "mysql-mcp-server-readonly",
+    );
+  }
+  if (platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Caches", "mysql-mcp-server-readonly");
+  }
+  return path.join(
+    environment.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"),
+    "mysql-mcp-server-readonly",
+  );
+}
+
+function bundledWheel(root = packageRoot) {
+  const vendor = path.join(root, "npm", "vendor");
+  if (!fs.existsSync(vendor)) {
+    throw new Error("The npm package is missing its bundled Python wheel.");
+  }
+  const wheels = fs
+    .readdirSync(vendor)
+    .filter((name) => name.endsWith(".whl"))
+    .sort();
+  if (wheels.length !== 1) {
+    throw new Error(
+      `Expected exactly one bundled Python wheel, found ${wheels.length}.`,
+    );
+  }
+  return path.join(vendor, wheels[0]);
+}
+
+function dependencyLock(root = packageRoot) {
+  const lock = path.join(root, "npm", "requirements.lock");
+  if (!fs.existsSync(lock)) {
+    throw new Error("The npm package is missing its hashed Python dependency lock.");
+  }
+  return lock;
+}
+
+function runtimeFingerprint(wheel, lock) {
+  const digest = crypto.createHash("sha256");
+  digest.update(fs.readFileSync(wheel));
+  digest.update(fs.readFileSync(lock));
+  return digest.digest("hex");
+}
+
+function runtimeIsReady(marker, runtimePython, fingerprint) {
+  if (!fs.existsSync(marker) || !fs.existsSync(runtimePython)) {
+    return false;
+  }
+  try {
+    const state = JSON.parse(fs.readFileSync(marker, "utf8"));
+    return state.runtimeFingerprint === fingerprint;
+  } catch {
+    return false;
+  }
+}
+
+function virtualenvPython(virtualenv, platform = process.platform) {
+  return platform === "win32"
+    ? path.join(virtualenv, "Scripts", "python.exe")
+    : path.join(virtualenv, "bin", "python");
+}
+
+function runChecked(command, args, label) {
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  if (result.error) {
+    throw new Error(`${label} failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`${label} failed with exit code ${result.status}`);
+  }
+}
+
+function sleep(milliseconds) {
+  Atomics.wait(
+    new Int32Array(new SharedArrayBuffer(4)),
+    0,
+    0,
+    milliseconds,
+  );
+}
+
+function acquireInstallLock(lockPath, markerPath) {
+  const deadline = Date.now() + 180_000;
+  while (true) {
+    try {
+      return fs.openSync(lockPath, "wx");
+    } catch (error) {
+      if (!error || error.code !== "EEXIST") {
+        throw error;
+      }
+      if (fs.existsSync(markerPath)) {
+        return null;
+      }
+      const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+      if (age > 600_000) {
+        fs.rmSync(lockPath, { force: true });
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error("Timed out waiting for another runtime installation.");
+      }
+      sleep(250);
+    }
+  }
+}
+
+function ensureRuntime() {
+  const wheel = bundledWheel();
+  const lockfile = dependencyLock();
+  const fingerprint = runtimeFingerprint(wheel, lockfile);
+  const runtimeRoot = path.join(cacheBase(), manifest.version);
+  const virtualenv = path.join(runtimeRoot, "venv");
+  const marker = path.join(runtimeRoot, "ready.json");
+  const lock = path.join(runtimeRoot, "install.lock");
+  const runtimePython = virtualenvPython(virtualenv);
+
+  if (runtimeIsReady(marker, runtimePython, fingerprint)) {
+    return runtimePython;
+  }
+
+  fs.mkdirSync(runtimeRoot, { recursive: true });
+  const lockHandle = acquireInstallLock(lock, marker);
+  if (lockHandle === null) {
+    return runtimePython;
+  }
+  try {
+    if (runtimeIsReady(marker, runtimePython, fingerprint)) {
+      return runtimePython;
+    }
+    const python = detectPython();
+    if (!fs.existsSync(runtimePython)) {
+      runChecked(
+        python.command,
+        [...python.prefix, "-m", "venv", virtualenv],
+        "Python virtual environment creation",
+      );
+    }
+    runChecked(
+      runtimePython,
+      [
+        "-m",
+        "pip",
+        "install",
+        "--disable-pip-version-check",
+        "--no-input",
+        "--require-hashes",
+        "--only-binary=:all:",
+        "--upgrade",
+        "-r",
+        lockfile,
+      ],
+      "Locked Python dependency installation",
+    );
+    runChecked(
+      runtimePython,
+      [
+        "-m",
+        "pip",
+        "install",
+        "--disable-pip-version-check",
+        "--no-input",
+        "--no-deps",
+        "--upgrade",
+        wheel,
+      ],
+      "Bundled Python package installation",
+    );
+    fs.writeFileSync(
+      marker,
+      `${JSON.stringify({
+        packageVersion: manifest.version,
+        wheel: path.basename(wheel),
+        runtimeFingerprint: fingerprint,
+      })}\n`,
+      "utf8",
+    );
+    return runtimePython;
+  } finally {
+    fs.closeSync(lockHandle);
+    fs.rmSync(lock, { force: true });
+  }
+}
+
+async function main(argv = process.argv.slice(2)) {
+  if (argv.includes("--launcher-version")) {
+    process.stdout.write(`${manifest.version}\n`);
+    return;
+  }
+
+  const python = ensureRuntime();
+  const child = spawn(python, ["-m", "mysql_mcp_server", ...argv], {
+    env: process.env,
+    stdio: "inherit",
+    windowsHide: true,
+  });
+
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      if (!child.killed) {
+        child.kill(signal);
+      }
+    });
+  }
+
+  await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`Python MCP exited after signal ${signal}`));
+      } else {
+        process.exitCode = code === null ? 1 : code;
+        resolve();
+      }
+    });
+  });
+}
+
+module.exports = {
+  bundledWheel,
+  cacheBase,
+  dependencyLock,
+  detectPython,
+  ensureRuntime,
+  main,
+  pythonCandidates,
+  virtualenvPython,
+};