@futuretea/clickhouse-mcp-server 0.0.1 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@ The MCP service has no authentication. It listens on `127.0.0.1` by default. Kee
 
 ## Quick start
 
-1. Copy the example configuration and set the ClickHouse HTTP address.
+1. Copy the example configuration and set the ClickHouse HTTP address. Use a read-only user; the built-in `default` user is rejected at startup. See [Service account](#service-account).
 
    ```bash
    cp config.example.yaml config.yaml
@@ -51,9 +51,9 @@ All successful tool calls return JSON in MCP text content.
 | `clickhouse_describe_table` | required `table`, optional `database` | column name, type, defaults, and comment |
 | `clickhouse_query` | required `query`, optional positive integer `max_rows` | columns, display-string rows, returned `row_count`, and `truncated` |
 
-`clickhouse_query` defaults to 1,000 rows. The server reads one additional row to report `truncated: true`; that extra row is not returned. Each non-null cell is rendered as a string so clients receive a stable JSON shape.
+`clickhouse_query` defaults to 1,000 rows. The server reads one additional row to report `truncated: true`; that extra row is not returned. While output masking is off, each non-null cell is rendered as a string. While it is on, an unmatched cell keeps that display text, and a matched nested map or slice is JSON.
 
-The query tool accepts exactly one statement. Semicolons in strings, quoted identifiers, and SQL comments are allowed; a second statement is rejected before it reaches ClickHouse. Every query is sent with ClickHouse `readonly=1`, so ClickHouse rejects writes and DDL for a user that honors that setting. The connected ClickHouse user should still have only the privileges appropriate for read access.
+The query tool accepts exactly one statement. Semicolons in strings, quoted identifiers, and SQL comments are allowed; a second statement is rejected before it reaches ClickHouse. Every query is sent with ClickHouse `readonly=1`. That setting rejects writes, DDL, `SYSTEM` statements, user administration, and source table functions such as `file` and `url`. It does not hide in-flight SQL in `system.processes`, and it does not reject AI functions. Startup rejects accounts that can administer ClickHouse, read external sources, run global DDL, read other sessions' query text, or call AI functions. See [Service account](#service-account).
 
 ## Configuration
 
@@ -69,6 +69,7 @@ clickhouse:
   secure: false
   username: ""
   password: ""
+allow_unsafe_database_role: false
 ```
 
 | Group | YAML key | Environment variable | Default | Meaning |
@@ -86,9 +87,75 @@ clickhouse:
 | Tool filters | `disabled_tools` | `MCP_DISABLED_TOOLS` | empty | Comma-separated tool names to disable |
 | Tool filters | `enabled_domains` | `MCP_ENABLED_DOMAINS` | empty | Comma-separated tool domains to enable |
 | Tool filters | `disabled_domains` | `MCP_DISABLED_DOMAINS` | empty | Comma-separated tool domains to disable |
+| Server | `allow_unsafe_database_role` | `MCP_ALLOW_UNSAFE_DATABASE_ROLE` | `false` | Skip only the startup unsafe-privilege rejection |
+| Output | `masking` | `MCP_MASKING_JSON` | disabled | Optional output masking. A present variable replaces the whole object. |
 
 The server never logs the configured password. `secure: true` protects the connection to ClickHouse; it does not add TLS or authentication to the MCP HTTP endpoint.
 
+### Output masking
+
+Masking stays off unless `masking.enabled` is `true`. An absent `masking` object leaves tool results, logs, and errors unchanged.
+
+```yaml
+masking:
+  enabled: true
+  placeholder: "[masked]"
+  names: ["synthetic_field"]
+  name_patterns: ["token_.+"]
+  values: ["synthetic-token-value"]
+  value_patterns: ["sk_live_[0-9]+"]
+```
+
+`MCP_MASKING_JSON`, when set, replaces that whole object. An empty value is rejected. An unset variable leaves the YAML object in place. Other `MCP_*` variables do not merge into the object. `enabled: true` with no rules is rejected. Unknown JSON fields are rejected. The error text is `invalid masking config` and does not include the document.
+
+`config check` prints `masking=enabled` or `masking=disabled`. The line is present when masking is off, as `masking=disabled source=default`. It does not print the rules. When masking is on, displayed configuration values are masked too.
+
+Name patterns are parsed on their own and then anchored to the whole field name. A fragment such as `a)|(b` is rejected. A grouped pattern such as `(?:a)|(b)` matches only the whole names `a` and `b`. Value literals and value patterns are substring matches on the original text, including a one-character literal. RE2 returns the leftmost-first match and does not look for a longer alternative. A matched string becomes the placeholder. A matched number, boolean, or other non-string becomes JSON null. An original null stays null. A null in a result can be a database NULL or a redacted value, and the JSON type can change when a rule matches.
+
+The server applies field rules to scanned driver values before `fmt.Sprint`. Unmatched cells keep the previous display text. Matched nested maps and slices become JSON. Strings and JSON text use those rules. ClickHouse does not decode a base64 string before masking it. A value rule that hits the original display text of a number, bool, time, duration, IP address, UUID, or geo value nulls the whole value. An unmatched value keeps that `fmt.Sprint` text. A JSON number keeps the digits from the document, including trailing zeros. A JSON value is counted again as its container, so it can exhaust the shared budget before a plain string of the same size. A name rule nulls the whole value. ClickHouse JSON and Variant values are walked. One set of size and node limits covers the whole tool result. An unknown value, a walk past the depth or node bound, or output past 1 MiB fails the result with `[clickhouse_masking_failed] result was not returned`. No partial result is returned.
+
+This does not find every private value. Compressed payloads and encodings the server does not recognize are not rewritten in place. Query text sent to ClickHouse is not modified.
+
+While masking is on, query, startup, setting, and connection errors omit driver and setting text. HTTP debug logs use a route class (`mcp`, `sse`, `message`, `healthz`, or `other`) instead of the request path. The placeholder and those fixed errors are not treated as stored data. A short literal that also occurs inside them can remain there.
+
+### Service account
+
+After the process connects, and before any tool runs a query, startup reads `SHOW GRANTS FINAL` for the current user. That statement includes privileges inherited through roles. Startup exits with `[clickhouse_unsafe_service_role] database service role is not permitted` when the account has any of:
+
+- `ACCESS MANAGEMENT`, or a privilege in that group, including `CREATE USER`, `ALTER USER`, `DROP USER`, `CREATE ROLE`, `DROP ROLE`, `ROLE ADMIN`, row policies, quotas, settings profiles, and `SHOW ACCESS`
+- `SYSTEM`, or any `SYSTEM …` privilege, such as `SYSTEM SHUTDOWN`
+- `SOURCES`, `READ`, `WRITE`, or an external source privilege such as `FILE`, `URL`, `REMOTE`, `S3`, `YTSAURUS`, or `ARROW FLIGHT`
+- global DDL or global `ALL` / `ALL PRIVILEGES` on `*.*`: `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `OPTIMIZE`, and their DDL children, including `ALTER HANDLER`
+- similar administrative grants: `BACKUP`, `KILL QUERY`, `KILL TRANSACTION`, `MOVE PARTITION BETWEEN SHARDS`, `TABLE ENGINE`, `CLUSTER`, `NAMED COLLECTION ADMIN` (including named-collection secrets), `SET DEFINER`, `ALLOW SQL SECURITY NONE`, `SHOW CONNECTIONS`, and `SHOW HANDLERS`
+- `AI FUNCTIONS`, or an individual AI function privilege such as `aiGenerate`. A later `ai*` privilege is rejected too. These lines are covered by unit tests. ClickHouse 26.5.6.64, 26.5.7.64, and 26.10.2.103 reject `GRANT AI FUNCTIONS` as a syntax error.
+- `SELECT` or `ALL` on a scope that matches `system.processes`, `system.query_log`, `system.query_thread_log`, `system.query_views_log`, `system.user_query_log`, `system.query_cache`, `system.asynchronous_inserts`, `system.asynchronous_query_log`, or `system.users`. An unquoted trailing `*` is a prefix on that database or table name, so `system.proc*` and `sys*.*` match. A backtick-quoted `*` is a literal name. Matching is case sensitive.
+
+`SELECT` on the account's own databases, plus `system.databases`, `system.tables`, and `system.columns`, starts with the default configuration. `SELECT` on `*.*` does not. `SHOW` by itself cannot read `system.processes`. DDL granted on one database, rather than on `*.*`, is not treated as a dangerous service role. Queries are still sent with `readonly=1`.
+
+`allow_unsafe_database_role` defaults to `false`. Set it to `true` in the config file, or export `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, and every other startup check still stop startup. The flag does not remove `readonly=1`.
+
+`readonly=1` rejects writes, DDL, `SYSTEM` statements, `CREATE USER`, and `SELECT` from the `file` and `url` table functions. It does not reject `SELECT` from `system.processes`. On ClickHouse 26.5.6.64, `GRANT SELECT ON system.proc*` is printed unchanged and reads another session's in-flight SQL. The same wildcard inlined from a role does too. `system.data*` matches `system.databases` and does not match `system.processes`, so that narrower prefix still starts. `REVOKE SELECT ON system.processes` removes that one exact table and leaves a broader `GRANT SELECT ON *.*` in `SHOW GRANTS FINAL`.
+
+AI functions are not a substitute for that grant check. Startup rejects `AI FUNCTIONS` and each `ai*` name when a server emits them. It also reads `allow_experimental_ai_functions` from `system.settings`. A value of enabled rejects the account only when `is_obsolete` is false. On 26.5.6.64 and 26.5.7.64 the setting is live. On 26.10.2.103 the same row is obsolete and does nothing, so a leftover value does not reject a scoped reader. The pinned integration image is 26.5.6.64, which has no AI privilege row. The integration script adds a live AI rejection only when that row exists.
+
+`system.connections` is absent on 26.5.6.64, 26.5.7.64, and 26.10.2.103. `SHOW CONNECTIONS` and `SHOW HANDLERS` stay on the denylist as administrative visibility privileges. Enable the opt-out only for a ClickHouse instance you control.
+
+The warning is logged at warn level. HTTP mode shows it at the default `info` log level. Stdio mode keeps logs disabled so MCP output stays intact.
+
+`config check --connect` only pings ClickHouse. It does not run this privilege check. `mcp` and `tools call` do.
+
+Do not use the ClickHouse `default` user. A standard installation grants that user `ALL ON *.*`.
+
+```sql
+CREATE USER mcp_reader IDENTIFIED WITH no_password;
+GRANT SELECT ON analytics.* TO mcp_reader;
+GRANT SELECT ON system.databases TO mcp_reader;
+GRANT SELECT ON system.tables TO mcp_reader;
+GRANT SELECT ON system.columns TO mcp_reader;
+```
+
+The discovery tools read those three system tables. Grant `SELECT` on each database the query tool should read.
+
 ### Environment-only configuration check
 
 For the smallest local setup, set just the ClickHouse HTTP address and inspect the effective configuration. This command does not start MCP or access the network.
@@ -98,7 +165,7 @@ export MCP_CLICKHOUSE_ADDRESS=127.0.0.1:8123
 ./bin/clickhouse-mcp-server config check
 ```
 
-The command prints the 13 configuration fields in a stable order with their source (`flag`, `environment`, `YAML`, or `default`). Passwords are reported only as `set` or `unset`. `sse_base_url` removes query and fragment values and redacts URL userinfo before display.
+The command prints the 15 configuration fields in a stable order with their source (`flag`, `environment`, `YAML`, or `default`). Passwords are reported only as `set` or `unset`. `masking` is `enabled` or `disabled` and does not include the rules. `sse_base_url` removes query and fragment values and redacts URL userinfo before display.
 
 Use `--connect` only when you intentionally want one ClickHouse HTTP(S) `Ping`; it opens, pings, and closes a short-lived connection without starting the MCP server.
 
@@ -155,10 +222,14 @@ Both commands launch the `mcp` command. Arguments after the package or image are
 
 ## Troubleshooting
 
+- `[clickhouse_unsafe_service_role]`: the configured user can administer ClickHouse, read external sources, run global DDL, or call AI functions. Create a `SELECT`-only user, or set `allow_unsafe_database_role: true` only on an instance you control. The opt-out does not remove `readonly=1`.
 - `clickhouse.address is required`: add a `host:port` value such as `127.0.0.1:8123` to the configuration or `MCP_CLICKHOUSE_ADDRESS`.
 - Connection failure: check the address, `secure` value, ClickHouse HTTP port, and network reachability.
 - Query rejection: verify the statement is a single read-only query and that the configured ClickHouse user has access to the database.
 - `truncated: true`: lower the result size in SQL or increase `max_rows` deliberately.
+- `invalid masking config`: the masking document is empty, unknown, or enabled with no rules. The message does not quote the document.
+- `[clickhouse_masking_failed]`: the result could not be masked inside the bounds, or the value type is not supported. No partial result is returned.
+- `[clickhouse_query_failed]`, `[clickhouse_startup_failed]`, and `[clickhouse_connect_failed]`: masking is on, so the server omits driver and setting text.
 
 ## Development
 
@@ -171,13 +242,13 @@ make ci
 
 ### Optional ClickHouse integration test
 
-The default test suite has no external dependency. The opt-in integration test starts an isolated local ClickHouse Docker container to verify database discovery, parameterized table inspection, `SELECT`, and that `readonly=1` rejects temporary DDL. It also builds the public server binary, starts it in HTTP mode on loopback, checks `/healthz`, and calls `tools/list` and `tools/call` through `/mcp`.
+The default test suite has no external dependency. The opt-in integration test starts an isolated local ClickHouse Docker container to verify database discovery, parameterized table inspection, `SELECT`, and that `CREATE TEMPORARY TABLE` is denied for the `SELECT`/`SHOW` account. ClickHouse returns `ACCESS_DENIED` (code 497) because that privilege can only be granted on `*.*`, which startup rejects. It also builds the public server binary, starts it in HTTP mode on loopback, checks `/healthz`, and calls `tools/list` and `tools/call` through `/mcp`.
 
 ```bash
 make test-integration
 ```
 
-The target requires Docker and `curl`, creates a random loopback port, waits for ClickHouse health, and removes its container on exit. Set `CLICKHOUSE_INTEGRATION_IMAGE` to test another isolated image. It runs the full MCP HTTP E2E test, the read-only toolset integration test, and `config check --connect`. It is local-only: neither `make test` nor the GitHub Actions CI workflow runs it.
+The target requires Docker and `curl`, creates a random loopback port, waits for ClickHouse health, and removes its container on exit. Set `CLICKHOUSE_INTEGRATION_IMAGE` to test another isolated image. It creates ClickHouse user `mcp_reader` with `SELECT` on `system.databases`, `system.tables`, and `system.columns`, and runs the tests as that user. `SELECT` on `*.*` is rejected. It also grants `SELECT ON system.proc*` to `wild_reader` and expects startup to reject that account. It runs the full MCP HTTP E2E test, the read-only toolset integration test, and `config check --connect`. When `system.privileges` contains `AI FUNCTIONS`, it also creates scoped `ai_probe` with that privilege and expects startup to reject the account. ClickHouse 26.5.6.64, the default image, has no such row, so that extra check does not run there. It is local-only: neither `make test` nor the GitHub Actions CI workflow runs it.
 
 The repository retains its template assets under `scripts/` and `templates/` for local reference; they are not part of the ClickHouse server runtime.
 

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@futuretea/clickhouse-mcp-server",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Read-only ClickHouse Model Context Protocol server",
   "main": "./bin/index.js",
   "bin": {
     "clickhouse-mcp-server": "bin/index.js"
   },
   "optionalDependencies": {
-    "@futuretea/clickhouse-mcp-server-darwin-amd64": "0.0.1",
-    "@futuretea/clickhouse-mcp-server-darwin-arm64": "0.0.1",
-    "@futuretea/clickhouse-mcp-server-linux-amd64": "0.0.1",
-    "@futuretea/clickhouse-mcp-server-linux-arm64": "0.0.1",
-    "@futuretea/clickhouse-mcp-server-windows-amd64": "0.0.1"
+    "@futuretea/clickhouse-mcp-server-darwin-amd64": "0.2.0",
+    "@futuretea/clickhouse-mcp-server-darwin-arm64": "0.2.0",
+    "@futuretea/clickhouse-mcp-server-linux-amd64": "0.2.0",
+    "@futuretea/clickhouse-mcp-server-linux-arm64": "0.2.0",
+    "@futuretea/clickhouse-mcp-server-windows-amd64": "0.2.0"
   },
   "repository": {
     "type": "git",