feat: adds allow write mode for dev (#41)

* feat: adds allow write mode for dev

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

* fix: redact database password in startup config log

Address PR #41 review: db_config contained the plaintext password and
was logged at INFO level, leaking credentials to anyone with log access.
Mask the password field before logging.

* chore: bump version to 0.5.0

---------

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

Author: killme2008

README.md

@@ -90,6 +90,7 @@ GREPTIMEDB_POOL_SIZE=5         # Connection pool size
 GREPTIMEDB_MASK_ENABLED=true   # Enable sensitive data masking
 GREPTIMEDB_MASK_PATTERNS=      # Additional patterns (comma-separated)
 GREPTIMEDB_AUDIT_ENABLED=true  # Enable audit logging
+GREPTIMEDB_ALLOW_WRITE=false   # Allow write/DDL via execute_sql (DANGEROUS, local/test only)
 
 # Transport (for HTTP server mode)
 GREPTIMEDB_TRANSPORT=stdio     # stdio, sse, or streamable-http
@@ -111,6 +112,7 @@ greptimedb-mcp-server \
   --timezone UTC \
   --pool-size 5 \
   --mask-enabled true \
+  --allow-write false \
   --transport stdio
 ```
 
@@ -165,6 +167,27 @@ All queries go through a security gate that:
 - **Blocks**: Encoded bypass attempts (hex, UNHEX, CHAR)
 - **Allows**: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION
 
+### Write Mode (Disabled by Default)
+
+The server is **read-only by default**. For local development or testing, you can
+allow write/destructive SQL (DDL/DML such as `CREATE`, `DROP`, `ALTER`, `INSERT`,
+`UPDATE`, `DELETE`) through the `execute_sql` tool by enabling write mode:
+
+```bash
+# Environment variable
+GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server
+
+# Or CLI argument
+greptimedb-mcp-server --allow-write true
+```
+
+When enabled, the security gate is **bypassed** for `execute_sql`, and the server
+logs a warning on startup.
+
+> ⚠️ **Danger**: This lets an AI assistant run destructive statements against your
+> database. Never enable it against production data. Combine with a read-only
+> database user if you only need read access.
+
 ### Data Masking
 
 Sensitive columns are automatically masked (`******`) based on column name patterns:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "greptimedb-mcp-server"
-version = "0.4.9"
+version = "0.5.0"
 description = "MCP server for GreptimeDB with SQL/TQL/PromQL support, sensitive data masking, and prompt templates for observability data analysis."
 readme = "README.md"
 license = {text = "MIT"}

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/GreptimeTeam/greptimedb-mcp-server",
     "source": "github"
   },
-  "version": "0.4.9",
+  "version": "0.5.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "greptimedb-mcp-server",
-      "version": "0.4.9",
+      "version": "0.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -119,6 +119,11 @@
           "name": "GREPTIMEDB_AUDIT_ENABLED",
           "description": "Enable audit logging for tool invocations (default: true)",
           "isRequired": false
+        },
+        {
+          "name": "GREPTIMEDB_ALLOW_WRITE",
+          "description": "Allow write/destructive SQL (DDL/DML) via execute_sql by skipping the security gate. DANGEROUS: only use on local or test instances (default: false)",
+          "isRequired": false
         }
       ]
     }

src/greptimedb_mcp_server/config.py

@@ -84,6 +84,13 @@ class Config:
     Enable audit logging for all tool calls
     """
 
+    allow_write: bool
+    """
+    Allow write/destructive SQL (DDL/DML such as CREATE, DROP, ALTER, INSERT,
+    UPDATE, DELETE) through the `execute_sql` tool by skipping the security
+    gate. Disabled by default; intended only for local development or testing.
+    """
+
     allowed_hosts: list[str]
     """
     Allowed hosts for DNS rebinding protection (for sse/streamable-http).
@@ -169,7 +176,7 @@ def from_env_arguments() -> "Config":
 
         parser.add_argument(
             "--mask-enabled",
-            type=lambda x: x.lower() not in ("false", "0", "no"),
+            type=_parse_bool,
             help="Enable data masking for sensitive columns (default: true)",
             default=os.getenv("GREPTIMEDB_MASK_ENABLED", "true"),
         )
@@ -205,11 +212,22 @@ def from_env_arguments() -> "Config":
 
         parser.add_argument(
             "--audit-enabled",
-            type=lambda x: x.lower() not in ("false", "0", "no"),
+            type=_parse_bool,
             help="Enable audit logging for all tool calls (default: true)",
             default=os.getenv("GREPTIMEDB_AUDIT_ENABLED", "true"),
         )
 
+        parser.add_argument(
+            "--allow-write",
+            type=_parse_bool,
+            help=(
+                "Allow write/destructive SQL (DDL/DML) via execute_sql by "
+                "skipping the security gate. DANGEROUS: only use on local or "
+                "test instances (default: false)"
+            ),
+            default=os.getenv("GREPTIMEDB_ALLOW_WRITE", "false"),
+        )
+
         parser.add_argument(
             "--allowed-hosts",
             type=str,
@@ -250,6 +268,7 @@ def from_env_arguments() -> "Config":
             listen_host=args.listen_host,
             listen_port=args.listen_port,
             audit_enabled=args.audit_enabled,
+            allow_write=args.allow_write,
             allowed_hosts=_parse_comma_separated(args.allowed_hosts),
             allowed_origins=_parse_comma_separated(args.allowed_origins),
         )
@@ -261,3 +280,15 @@ def _parse_comma_separated(value: str) -> list[str]:
     if not value:
         return []
     return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def _parse_bool(value: str) -> bool:
+    """Parse a strict boolean value for environment and CLI configuration."""
+    normalized = value.strip().lower()
+    if normalized in {"true", "1", "yes", "on"}:
+        return True
+    if normalized in {"false", "0", "no", "off"}:
+        return False
+    raise argparse.ArgumentTypeError(
+        "expected a boolean value: true/false, 1/0, yes/no, or on/off"
+    )

src/greptimedb_mcp_server/server.py

@@ -63,6 +63,7 @@ class AppState:
     http_base_url: str
     mask_enabled: bool = True
     mask_patterns: list[str] = field(default_factory=list)
+    allow_write: bool = False
     pool: MySQLConnectionPool | None = field(default=None)
     http_session: aiohttp.ClientSession | None = field(default=None)
 
@@ -430,11 +431,18 @@ async def lifespan(mcp: FastMCP):
         http_base_url=http_base_url,
         mask_enabled=config.mask_enabled,
         mask_patterns=mask_patterns,
+        allow_write=config.allow_write,
         http_session=aiohttp.ClientSession(),
     )
 
-    logger.info(f"GreptimeDB Config: {db_config}")
+    safe_db_config = {**db_config, "password": "***" if config.password else ""}
+    logger.info(f"GreptimeDB Config: {safe_db_config}")
     logger.info(f"Data masking: {'enabled' if config.mask_enabled else 'disabled'}")
+    if config.allow_write:
+        logger.warning(
+            "Write mode ENABLED: execute_sql allows destructive SQL (DDL/DML). "
+            "Do NOT use against production data."
+        )
     logger.info("Starting GreptimeDB MCP server...")
 
     try:
@@ -549,13 +557,19 @@ async def execute_sql(
     ] = "csv",
     limit: Annotated[int, "Maximum number of rows to return (default: 1000)"] = 1000,
 ) -> str:
-    """Execute SQL query against GreptimeDB. Please use MySQL dialect."""
+    """Execute SQL query against GreptimeDB. Please use MySQL dialect.
+
+    Read-only by default. When the server runs with write mode enabled
+    (--allow-write / GREPTIMEDB_ALLOW_WRITE), destructive SQL (DDL/DML) is
+    also permitted.
+    """
     state = get_state()
     limit = _validate_sql_params(query, format, limit)
 
-    is_dangerous, reason = security_gate(query=query)
-    if is_dangerous:
-        return f"Error: Dangerous operation blocked: {reason}"
+    if not state.allow_write:
+        is_dangerous, reason = security_gate(query=query)
+        if is_dangerous:
+            return f"Error: Dangerous operation blocked: {reason}"
 
     start_time = time.time()
 

tests/test_config.py

@@ -1,5 +1,7 @@
 import os
 from unittest.mock import patch
+import pytest
+
 from greptimedb_mcp_server.config import Config, _parse_comma_separated
 
 
@@ -23,6 +25,7 @@ def test_config_default_values():
             assert config.transport == "stdio"
             assert config.listen_host == "0.0.0.0"
             assert config.listen_port == 8080
+            assert config.allow_write is False
             assert config.allowed_hosts == []
             assert config.allowed_origins == []
 
@@ -44,6 +47,7 @@ def test_config_env_variables():
         "GREPTIMEDB_TRANSPORT": "streamable-http",
         "GREPTIMEDB_LISTEN_HOST": "127.0.0.1",
         "GREPTIMEDB_LISTEN_PORT": "3000",
+        "GREPTIMEDB_ALLOW_WRITE": "true",
         "GREPTIMEDB_ALLOWED_HOSTS": "localhost:*,127.0.0.1:*",
         "GREPTIMEDB_ALLOWED_ORIGINS": "http://localhost:*,https://example.com",
     }
@@ -64,6 +68,7 @@ def test_config_env_variables():
             assert config.transport == "streamable-http"
             assert config.listen_host == "127.0.0.1"
             assert config.listen_port == 3000
+            assert config.allow_write is True
             assert config.allowed_hosts == ["localhost:*", "127.0.0.1:*"]
             assert config.allowed_origins == [
                 "http://localhost:*",
@@ -101,6 +106,8 @@ def test_config_cli_arguments():
         "192.168.1.1",
         "--listen-port",
         "9090",
+        "--allow-write",
+        "true",
         "--allowed-hosts",
         "my-service.namespace:*",
         "--allowed-origins",
@@ -123,6 +130,7 @@ def test_config_cli_arguments():
             assert config.transport == "sse"
             assert config.listen_host == "192.168.1.1"
             assert config.listen_port == 9090
+            assert config.allow_write is True
             assert config.allowed_hosts == ["my-service.namespace:*"]
             assert config.allowed_origins == ["http://my-app.example.com"]
 
@@ -144,6 +152,7 @@ def test_config_precedence():
         "GREPTIMEDB_TRANSPORT": "stdio",
         "GREPTIMEDB_LISTEN_HOST": "env-listen-host",
         "GREPTIMEDB_LISTEN_PORT": "1111",
+        "GREPTIMEDB_ALLOW_WRITE": "false",
     }
 
     cli_args = [
@@ -172,6 +181,8 @@ def test_config_precedence():
         "cli-listen-host",
         "--listen-port",
         "2222",
+        "--allow-write",
+        "true",
     ]
 
     with patch.dict(os.environ, env_vars):
@@ -190,6 +201,42 @@ def test_config_precedence():
             assert config.transport == "streamable-http"
             assert config.listen_host == "cli-listen-host"
             assert config.listen_port == 2222
+            assert config.allow_write is True
+
+
+@pytest.mark.parametrize(
+    ("env_value", "expected"),
+    [
+        ("true", True),
+        ("1", True),
+        ("yes", True),
+        ("on", True),
+        ("false", False),
+        ("0", False),
+        ("no", False),
+        ("off", False),
+    ],
+)
+def test_config_allow_write_boolean_values(env_value, expected):
+    with patch.dict(os.environ, {"GREPTIMEDB_ALLOW_WRITE": env_value}, clear=True):
+        with patch("sys.argv", ["script_name"]):
+            config = Config.from_env_arguments()
+
+            assert config.allow_write is expected
+
+
+def test_config_allow_write_rejects_invalid_env_value():
+    with patch.dict(os.environ, {"GREPTIMEDB_ALLOW_WRITE": "maybe"}, clear=True):
+        with patch("sys.argv", ["script_name"]):
+            with pytest.raises(SystemExit):
+                Config.from_env_arguments()
+
+
+def test_config_allow_write_rejects_invalid_cli_value():
+    with patch.dict(os.environ, {}, clear=True):
+        with patch("sys.argv", ["script_name", "--allow-write", "maybe"]):
+            with pytest.raises(SystemExit):
+                Config.from_env_arguments()
 
 
 class TestParseCommaSeparated:

tests/test_server.py

@@ -44,6 +44,7 @@ def setup_state():
         listen_host="0.0.0.0",
         listen_port=8080,
         audit_enabled=False,
+        allow_write=False,
         allowed_hosts=[],
         allowed_origins=[],
     )
@@ -71,6 +72,7 @@ def setup_state():
         http_base_url=f"http://{config.host}:{config.http_port}",
         mask_enabled=config.mask_enabled,
         mask_patterns=[],
+        allow_write=config.allow_write,
         http_session=None,
     )
 
@@ -98,6 +100,19 @@ async def test_execute_sql_dangerous_blocked():
     assert "Forbidden `DROP` operation" in result
 
 
+@pytest.mark.asyncio
+async def test_execute_sql_write_allowed_when_enabled():
+    """Write mode lets destructive SQL bypass the security gate."""
+    server._state.allow_write = True
+    try:
+        result = await execute_sql(query="DROP TABLE users")
+    finally:
+        server._state.allow_write = False
+
+    assert "Dangerous operation blocked" not in result
+    assert "executed successfully" in result
+
+
 @pytest.mark.asyncio
 async def test_execute_sql_show_tables():
     """Test SHOW TABLES query execution"""