Allow SHOW/DESCRIBE in read-only mode, add sql.assistant.role prompt

- Policy: allow SHOW, DESCRIBE, DESC as read-only statements (MySQL/PG support)
- Add sql.assistant.role MCP prompt with rules for tool usage and dialect detection
- Update sql.query description to list all allowed statement types
- Add pymysql to requirements.txt for MySQL support
- README: add ChatGPT custom instructions, update tool/prompt tables

Author: loglux

README.md

@@ -63,7 +63,7 @@ SSE endpoint:  http://localhost:8123/mcp (GET for Server-Sent Events)
 
 | Tool | Description |
 |---|---|
-| `sql.query` | Execute read-only SQL queries (SELECT, WITH, EXPLAIN) |
+| `sql.query` | Execute read-only SQL queries (SELECT, WITH, EXPLAIN, SHOW, DESCRIBE) |
 | `sql.schema` | Introspect tables, columns, types, and indexes |
 | `sql.explain` | Get EXPLAIN plan for a query |
 | `db.design` | Generate a desired schema template |
@@ -84,9 +84,33 @@ SSE endpoint:  http://localhost:8123/mcp (GET for Server-Sent Events)
 
 | Prompt | Description |
 |---|---|
+| `sql.assistant.role` | System prompt with rules for correct tool usage, dialect detection, and schema discovery |
 | `sql.query.plan` | Generate a safe SQL query plan from a natural language question |
 | `db.design.schema` | Propose a SQL schema from a domain description |
 
+> **Note:** ChatGPT's MCP connector supports only tools, not prompts or resources.
+> If you use ChatGPT, paste the following into your Custom Instructions:
+
+<details>
+<summary>Recommended system prompt for ChatGPT</summary>
+
+```
+You are a database assistant connected to a live SQL database via MCP
+(Model Context Protocol).
+
+Rules:
+1. ALWAYS call sql.schema first at the start of each conversation to get
+   the current schema. Never assume or cache table names from previous messages.
+2. Read the sql.query tool description — it tells you the database engine
+   (SQLite, MySQL, PostgreSQL). Use the correct SQL dialect.
+3. For read queries use sql.query. For writes use db.apply. Never mix them.
+4. If a query fails with a syntax error, check the dialect and retry
+   with correct syntax.
+5. Prefer sql.schema over SHOW TABLES / information_schema for discovering tables.
+6. When presenting results, format them as clean tables. Keep explanations concise.
+```
+</details>
+
 ## Admin UI
 
 The built-in web UI provides:

app/mcp/prompts.py

@@ -2,6 +2,21 @@
 
 from app.config import Config
 
+_ASSISTANT_ROLE = (
+    "You are a database assistant connected to a live SQL database via MCP "
+    "(Model Context Protocol).\n\n"
+    "Rules:\n"
+    "1. ALWAYS call sql.schema first at the start of each conversation to get "
+    "the current schema. Never assume or cache table names from previous messages.\n"
+    "2. Read the sql.query tool description — it tells you the database engine "
+    "(SQLite, MySQL, PostgreSQL). Use the correct SQL dialect.\n"
+    "3. For read queries use sql.query. For writes use db.apply. Never mix them.\n"
+    "4. If a query fails with a syntax error, check the dialect and retry "
+    "with correct syntax.\n"
+    "5. Prefer sql.schema over SHOW TABLES / information_schema for discovering tables.\n"
+    "6. When presenting results, format them as clean tables. Keep explanations concise."
+)
+
 
 class PromptRegistry:
     def __init__(self, config: Config) -> None:
@@ -10,6 +25,15 @@ def __init__(self, config: Config) -> None:
     def list_prompts(self) -> Dict[str, Any]:
         return {
             "prompts": [
+                {
+                    "name": "sql.assistant.role",
+                    "description": (
+                        "System prompt for an AI assistant working with this database. "
+                        "Provides rules for correct tool usage, dialect detection, "
+                        "and schema discovery."
+                    ),
+                    "arguments": [],
+                },
                 {
                     "name": "sql.query.plan",
                     "description": "Generate a safe SQL query plan before execution.",
@@ -40,7 +64,17 @@ def list_prompts(self) -> Dict[str, Any]:
             ]
         }
 
-    def get_prompt(self, name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+    def get_prompt(self, name: str, arguments: Dict[str, Any]) -> Dict[str, Any] | None:
+        if name == "sql.assistant.role":
+            return {
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": {"type": "text", "text": _ASSISTANT_ROLE},
+                    },
+                ]
+            }
+
         if name == "sql.query.plan":
             question = arguments.get("question", "")
             content = (

app/mcp/tools.py

@@ -387,7 +387,7 @@ def db_migrate_plan_apply(payload: Dict[str, Any]) -> Dict[str, Any]:
                 description=(
                     f"Execute a read-only SQL query against {config.db_type}. "
                     f"Use {config.db_type}-compatible syntax. "
-                    "Only SELECT, WITH, and EXPLAIN statements are allowed. "
+                    "SELECT, WITH, EXPLAIN, SHOW, and DESCRIBE statements are allowed. "
                     "For INSERT, UPDATE, DELETE, or DDL statements use db.apply."
                 ),
                 input_schema={

app/sql/policy.py

@@ -1,6 +1,6 @@
 import re
 
-READ_ONLY_PREFIXES = ("select", "with", "explain")
+READ_ONLY_PREFIXES = ("select", "with", "explain", "show", "describe", "desc")
 READ_QUERY_PREFIXES = ("select", "with")
 
 
@@ -119,6 +119,10 @@ def _is_read_only_core(normalized_sql: str) -> bool:
     if normalized_sql.startswith("explain"):
         return _is_explain_readonly(normalized_sql)
 
+    # MySQL/PostgreSQL metadata commands are always read-only
+    if normalized_sql.startswith(("show", "describe", "desc ")):
+        return True
+
     if not normalized_sql.startswith(("select", "with")):
         return False
 

requirements.txt

@@ -4,6 +4,7 @@ sqlalchemy
 jinja2
 python-dotenv
 psycopg2-binary
+pymysql
 python-multipart
 httpx
 cryptography

tests/test_sql_policy.py

@@ -38,6 +38,21 @@ def test_ignores_keywords_inside_literals(self) -> None:
             is_allowed("SELECT '-- drop table users' AS note FROM users", mode="read-only")
         )
 
+    def test_allows_show_tables_in_read_only(self) -> None:
+        self.assertTrue(is_allowed("SHOW TABLES", mode="read-only"))
+
+    def test_allows_show_databases_in_read_only(self) -> None:
+        self.assertTrue(is_allowed("SHOW DATABASES", mode="read-only"))
+
+    def test_allows_show_create_table_in_read_only(self) -> None:
+        self.assertTrue(is_allowed("SHOW CREATE TABLE users", mode="read-only"))
+
+    def test_allows_describe_in_read_only(self) -> None:
+        self.assertTrue(is_allowed("DESCRIBE users", mode="read-only"))
+
+    def test_allows_desc_in_read_only(self) -> None:
+        self.assertTrue(is_allowed("DESC users", mode="read-only"))
+
     def test_execute_mode_allows_single_write_statement(self) -> None:
         self.assertTrue(is_allowed("DELETE FROM users WHERE id = 1", mode="execute"))