@futuretea/mysql-mcp-server 0.0.2 → 0.2.0

package/README.md

@@ -13,8 +13,12 @@ support writes, administration, backups, replication, or dynamic targets.
 make build
 ./bin/mysql-mcp-server version
 
-# Set this only in the runtime environment. Do not commit it.
-export MYSQL_DSN='<runtime-dsn>'
+# Set these only in the runtime environment. Do not commit the password.
+export MYSQL_MCP_HOST='127.0.0.1'
+export MYSQL_MCP_DB_PORT='3306'
+export MYSQL_MCP_USERNAME='readonly'
+export MYSQL_MCP_PASSWORD='<runtime-secret>'
+export MYSQL_MCP_DATABASE='inventory'
 
 # Start MCP server (stdio, default)
 ./bin/mysql-mcp-server mcp
@@ -52,8 +56,10 @@ blocked session/file functions. Accepted queries run in a read-only transaction
 that is always rolled back.
 
 This is not proof that stored functions, UDFs, views, or plugins have no side
-effects. Use a least-privilege account; do not grant `EXECUTE`, `FILE`,
-`LOCK TABLES`, or administrative privileges.
+effects. Use a least-privilege account. Startup rejects `EXECUTE`, schema-wide `ALL`, `FILE`,
+`SHOW_ROUTINE`, grants on the `mysql` schema, global `SELECT`, and other
+administrative privileges unless `allow_unsafe_database_role` is set. See
+[Service account](#service-account).
 
 ## CLI commands
 
@@ -92,7 +98,14 @@ Cursor / Claude Desktop style config:
   "mcpServers": {
     "mysql-mcp-server": {
       "command": "/absolute/path/to/bin/mysql-mcp-server",
-      "args": ["mcp"]
+      "args": ["mcp"],
+      "env": {
+        "MYSQL_MCP_HOST": "127.0.0.1",
+        "MYSQL_MCP_DB_PORT": "3306",
+        "MYSQL_MCP_USERNAME": "readonly",
+        "MYSQL_MCP_PASSWORD": "<runtime-secret>",
+        "MYSQL_MCP_DATABASE": "inventory"
+      }
     }
   }
 }
@@ -139,10 +152,16 @@ Same process as HTTP mode. Endpoints:
 make docker
 
 # Stdio (default ENTRYPOINT is `mysql-mcp-server mcp`)
-docker run -i --rm -e MYSQL_DSN ghcr.io/futuretea/mysql-mcp-server:dev
+docker run -i --rm \
+  -e MYSQL_MCP_HOST -e MYSQL_MCP_DB_PORT -e MYSQL_MCP_USERNAME \
+  -e MYSQL_MCP_PASSWORD -e MYSQL_MCP_DATABASE \
+  ghcr.io/futuretea/mysql-mcp-server:dev
 
 # HTTP
-docker run --rm -e MYSQL_DSN -p 8080:8080 ghcr.io/futuretea/mysql-mcp-server:dev --port 8080 --listen 0.0.0.0
+docker run --rm \
+  -e MYSQL_MCP_HOST -e MYSQL_MCP_DB_PORT -e MYSQL_MCP_USERNAME \
+  -e MYSQL_MCP_PASSWORD -e MYSQL_MCP_DATABASE \
+  -p 8080:8080 ghcr.io/futuretea/mysql-mcp-server:dev --port 8080 --listen 0.0.0.0
 ```
 
 HTTP / SSE have **no auth and no TLS**. Default `--listen 127.0.0.1`. Use only on trusted networks; put a reverse proxy in front if you expose the port.
@@ -155,11 +174,39 @@ Priority: **flags > environment variables > config file > defaults**.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `MCP_LOG_LEVEL` | Log level | `info` |
-| `MCP_PORT` | HTTP port (`0` = stdio) | `0` |
-| `MCP_LISTEN` | HTTP listen host | `127.0.0.1` |
-| `MCP_SSE_BASE_URL` | Public SSE base URL | `""` |
-| `MYSQL_DSN` | Required single MySQL runtime DSN; never logged or returned | none |
+| `MYSQL_MCP_LOG_LEVEL` | Log level | `info` |
+| `MYSQL_MCP_PORT` | MCP HTTP port (`0` = stdio) | `0` |
+| `MYSQL_MCP_LISTEN` | MCP HTTP listen host | `127.0.0.1` |
+| `MYSQL_MCP_SSE_BASE_URL` | Public SSE base URL | `""` |
+| `MYSQL_MCP_HOST` | MySQL TCP host | `127.0.0.1` |
+| `MYSQL_MCP_DB_PORT` | MySQL TCP port; distinct from `MYSQL_MCP_PORT` | `3306` |
+| `MYSQL_MCP_USERNAME` | Required MySQL username | none |
+| `MYSQL_MCP_PASSWORD` | Optional MySQL password; never logged or returned | none |
+| `MYSQL_MCP_DATABASE` | Optional default MySQL database | none |
+| `MYSQL_MCP_ALLOW_UNSAFE_DATABASE_ROLE` | Skip only the startup unsafe-privilege rejection | `false` |
+
+### Service account
+
+After the process connects, and before any tool runs SQL, startup reads `SHOW GRANTS` for the current account. Plain `SHOW GRANTS` includes mandatory roles; `SHOW GRANTS FOR CURRENT_USER()` does not. Privileges inherited through those roles and through explicitly granted roles are expanded before any tool runs. The process exits with `[mysql_unsafe_service_role]` when the account has any of:
+
+- `SUPER`, `FILE`, `PROCESS`, `SHUTDOWN`, `RELOAD`, `CREATE USER`, `CREATE TABLESPACE`, or `PROXY`
+- `CREATE ROLE`, `DROP ROLE`, or `EXECUTE`
+- `REPLICATION SLAVE` or `REPLICATION CLIENT`
+- `SHOW_ROUTINE` or `RESOURCE_GROUP_USER`
+- global `SELECT`, `ALL`, or `ALL PRIVILEGES` (`ON *.*`)
+- schema-wide `ALL` or `ALL PRIVILEGES` (`ON db.*`). MySQL stores `EXECUTE` on that database privilege row and `SHOW GRANTS` keeps the shorthand, so the word `EXECUTE` never appears. `ALL` on one table (`ON db.table`) does not include `EXECUTE`
+- any privilege on the `mysql` schema, including `SELECT` on `mysql.user`
+- MySQL 8 dynamic privileges that replace `SUPER` or administer the server, including `SYSTEM_VARIABLES_ADMIN`, `SESSION_VARIABLES_ADMIN`, `CONNECTION_ADMIN`, `TP_CONNECTION_ADMIN`, `SYSTEM_USER`, `ROLE_ADMIN`, `BINLOG_ADMIN`, `REPLICATION_SLAVE_ADMIN`, `SET_USER_ID`, `ALLOW_NONEXISTENT_DEFINER`, `BACKUP_ADMIN`, `CLONE_ADMIN`, `FLUSH_PRIVILEGES`, `FLUSH_TABLES`, `FIREWALL_ADMIN`, `OPTIMIZE_LOCAL_TABLE`, and `VERSION_TOKEN_ADMIN`
+
+`USAGE` plus `SELECT` on an application schema starts with the default configuration. No opt-out is required. `SELECT` on `*.*` does not start: that grant includes the `mysql` grant tables. An expanded database privilege list that does not include `EXECUTE` also starts. A routine call then fails in MySQL rather than at startup.
+
+A view created by a DBA with `SQL SECURITY DEFINER` is published schema. An account that can `SELECT` the view can read its output, including a `mysql.user` count or a function result, without holding `EXECUTE`. Startup does not classify that body. For this account `VIEW_DEFINITION` is empty and `SHOW CREATE VIEW` is denied, so the check cannot tell a normal default-definer application view from one that publishes catalog data. Do not publish a definer view that exposes data the service account should not see. That boundary is not a substitute for rejecting `EXECUTE` or schema-wide `ALL`.
+
+Startup allows 5 seconds for the TCP connection and the grant probe. A server that does not answer in that time stops startup. `allow_unsafe_database_role` does not extend the deadline.
+
+`allow_unsafe_database_role` defaults to `false`. Set it to `true` in the config file, or export `MYSQL_MCP_ALLOW_UNSAFE_DATABASE_ROLE=true`, only when you cannot provision a least-privilege account. The server logs a warning and skips this privilege rejection. A refused connection, a failed grant probe, a startup timeout, and every other startup check still stop startup. Queries still run in a read-only transaction, but that transaction does not constrain `FILE`, `SHUTDOWN`, `SUPER`, replication privileges, `PROXY`, `EXECUTE`, or the dynamic privileges above. Enable the option only for a MySQL instance you control.
+
+Stdio MCP and `tools call` keep logs at error level so protocol output stays intact. The opt-out warning is emitted at warn level and is visible in HTTP mode at the default `info` level.
 
 ### Config file
 
@@ -174,6 +221,7 @@ enabled_tools: []
 disabled_tools: []
 enabled_domains: []
 disabled_domains: []
+allow_unsafe_database_role: false
 ```
 
 ```bash
@@ -193,6 +241,34 @@ pkg/toolset/              # Toolset interface and filters
 pkg/toolset/mysql/        # six MySQL tool definitions and shared parameter decoder
 ```
 
+## Output masking
+
+Masking is off when the `masking` object is absent, when `enabled` is omitted, or when `enabled` is false. Tool results then keep their current JSON. Set `enabled` to true and at least one rule to mask configured data. `MYSQL_MCP_MASKING_JSON` replaces the whole YAML object when the variable is present. An empty value is rejected. Unset leaves the YAML object in place.
+
+```yaml
+masking:
+  enabled: true
+  placeholder: "[masked]"
+  names: ["synthetic_field"]
+  name_patterns: ["token_.+"]
+  values: ["synthetic-token-value"]
+  value_patterns: ["sk_live_[0-9]+"]
+```
+
+```bash
+export MYSQL_MCP_MASKING_JSON='{"enabled":true,"names":["synthetic_field"],"values":["synthetic-token-value"]}'
+```
+
+Name rules match a whole column, table, index, or database name, and a decoded JSON object key. The pattern is parsed before it is anchored, so a fragment such as `a)|(b` is rejected instead of matching a prefix or a suffix. A value pattern uses RE2 leftmost-first matching and does not look for a longer alternative. A matched string becomes the placeholder and keeps a MySQL `{"encoding","value"}` cell when the cell was text or base64. A matched number or other non-string becomes JSON `null`. An existing SQL `NULL` stays `null`. A JSON `null` in a masked result can therefore be either a database NULL or a redacted value, and the JSON type can change.
+
+Value rules are substring matches on the original text, including one-character literals. They run once and do not search the placeholder. A pattern is rejected when any alternative can match without consuming a character, such as a word-boundary branch. JSON objects and arrays stored in utf8 cells are read as JSON, including escaped keys. A value rule that hits a JSON number or bool, or a MySQL integer or float cell, replaces that whole value with null and does not splice the digits. An unmatched number keeps its original text. Standard base64 cells are decoded, masked, and encoded again, including a value pattern that matches an ASCII secret next to invalid UTF-8. Ordinary prose that looks like base64 is not decoded. One result shares a node and output budget. This is not a detector for every private value, compressed payload, or encoding.
+
+`schema_version` and the tool name are server constants and are not masked. Fixed public errors are not rewritten, so a short literal that also occurs in an error sentence or in the placeholder can still appear there. The guarantee is that the original configured data is removed from the covered result text.
+
+Invalid masking configuration, including `enabled: true` with no rules, stops startup with `invalid masking config` and does not echo the document. A result that exceeds a bound, has duplicate JSON keys, has two masked names that collide, or has an unsupported cell fails with `[mysql_masking_failed] result was not returned`. The database command is unchanged.
+
+HTTP debug logs record a route class (`mcp`, `sse`, `message`, or `other`) instead of the raw path or query. The masker does not write the source value to a log.
+
 ## Operational limits
 
 This slice deliberately does not impose query timeouts, row limits, response
@@ -240,7 +316,14 @@ Configure an MCP client that supports stdio with npm:
   "mcpServers": {
     "mysql-mcp-server": {
       "command": "npx",
-      "args": ["-y", "@futuretea/mysql-mcp-server@<version>"]
+      "args": ["-y", "@futuretea/mysql-mcp-server@<version>"],
+      "env": {
+        "MYSQL_MCP_HOST": "127.0.0.1",
+        "MYSQL_MCP_DB_PORT": "3306",
+        "MYSQL_MCP_USERNAME": "readonly",
+        "MYSQL_MCP_PASSWORD": "<runtime-secret>",
+        "MYSQL_MCP_DATABASE": "inventory"
+      }
     }
   }
 }

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@futuretea/mysql-mcp-server",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "MCP server binary launcher",
   "main": "./bin/index.js",
   "bin": {
     "mysql-mcp-server": "bin/index.js"
   },
   "optionalDependencies": {
-    "@futuretea/mysql-mcp-server-darwin-amd64": "0.0.2",
-    "@futuretea/mysql-mcp-server-darwin-arm64": "0.0.2",
-    "@futuretea/mysql-mcp-server-linux-amd64": "0.0.2",
-    "@futuretea/mysql-mcp-server-linux-arm64": "0.0.2",
-    "@futuretea/mysql-mcp-server-windows-amd64": "0.0.2"
+    "@futuretea/mysql-mcp-server-darwin-amd64": "0.2.0",
+    "@futuretea/mysql-mcp-server-darwin-arm64": "0.2.0",
+    "@futuretea/mysql-mcp-server-linux-amd64": "0.2.0",
+    "@futuretea/mysql-mcp-server-linux-arm64": "0.2.0",
+    "@futuretea/mysql-mcp-server-windows-amd64": "0.2.0"
   },
   "license": "MIT"
 }