@futuretea/mysql-mcp-server 0.0.2 → 0.1.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
@@ -240,7 +288,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.1.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.1.0",
+    "@futuretea/mysql-mcp-server-darwin-arm64": "0.1.0",
+    "@futuretea/mysql-mcp-server-linux-amd64": "0.1.0",
+    "@futuretea/mysql-mcp-server-linux-arm64": "0.1.0",
+    "@futuretea/mysql-mcp-server-windows-amd64": "0.1.0"
   },
   "license": "MIT"
 }