@hupan56/wlkj 2.7.11 → 3.0.0

package/templates/qoder/scripts/{mysql_mcp_server.py → mcp/mysql_mcp_server.py}

@@ -1,396 +1,347 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-"""MySQL Read-Only MCP Server (pure Python stdio, no external SDK).
-
-提供 3 个语义化只读工具查询 MySQL 数据库 (真实数据层真相源):
-  - query_schema:  查表结构 (列名/类型/注释/约束)
-  - query_data:    查数据 (自动 LIMIT, 防 SELECT * 拉爆)
-  - query_distinct:查枚举值 (DISTINCT 某字段的去重值 + 计数)
-
-安全设计 (硬约束):
-  1. 启动前 ping 内网, 不通 → 输出"请连接内网"并拒绝启动
-  2. SQL 只读白名单: 只允许 SELECT/SHOW/DESCRIBE/EXPLAIN/WITH
-     任何写操作 (INSERT/UPDATE/DELETE/DROP/ALTER/...) 直接拒绝
-  3. query_data 自动注入 LIMIT, 上限 200 行
-  4. 账号密码从环境变量读 (mcp.json env 配置, 不落代码)
-
-注册: ~/.qoderwork/mcp.json 的 "qoder-mysql"。
-工具名: mcp__qoder-mysql__query_schema / query_data / query_distinct
-"""
-import io
-import os
-import re
-import sys
-import json
-import socket
-import asyncio
-
-# UTF-8
-try:
-    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
-    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
-except Exception:
-    pass
-
-# ── 配置 (从环境变量, mcp.json env 注入) ──────────────────────────────
-MYSQL_HOST = os.environ.get('MYSQL_HOST', '10.54.6.9')
-MYSQL_PORT = int(os.environ.get('MYSQL_PORT', '3306'))
-MYSQL_USER = os.environ.get('MYSQL_USER', 'fywl_ics_test')
-MYSQL_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'Fywl_ics_test56476')
-PING_HOST = MYSQL_HOST  # 连通性校验目标
-PING_TIMEOUT = 3  # 秒
-
-# ── 环境可信度声明 (随每次工具返回, AI 不可能"忘记"边界) ──────────────
-# QAS 测试环境: 表结构/字段/枚举取值范围 = 生产一致 (可信);
-#               数据行/计数分布 = 测试数据, 不代表线上 (不可信)。
-ENV_NAME = os.environ.get('MYSQL_ENV_NAME', 'QAS 测试环境')
-ENV_NOTICE_SCHEMA = (
-    '\n[环境: %s] 表结构/字段/枚举定义与生产一致，可作为字段规格的真源。' % ENV_NAME
-)
-ENV_NOTICE_DATA = (
-    '\n⚠️ [环境: %s] 以下为测试数据样本，不代表线上真实分布。'
-    '字段取值范围可信，但具体数值/计数仅测试环境参考。' % ENV_NAME
-)
-
-# Suppress stdout non-JSON (MCP 用 stdout 传 JSON-RPC)
-_real_stdout = sys.stdout
-sys.stdout = sys.stderr
-
-
-# ── 安全: 内网连通性校验 ──────────────────────────────────────────────
-def check_intranet():
-    """TCP 连通性校验 (比 ICMP ping 更可靠, 不依赖管理员权限)。
-    连 3306 端口, 通=内网可达, 不通=提示连内网。
-    返回 (ok: bool, msg: str)。
-    """
-    try:
-        with socket.create_connection((MYSQL_HOST, MYSQL_PORT), timeout=PING_TIMEOUT):
-            return True, ''
-    except (socket.timeout, OSError) as e:
-        return False, (
-            '无法连接内网 MySQL (%s:%s): %s\n'
-            '⚠️ 请确认你已连接公司内网 (VPN/办公网), 然后重试。'
-            'MySQL MCP 仅在内网可用。'
-        ) % (MYSQL_HOST, MYSQL_PORT, str(e)[:80])
-
-
-# ── 安全: SQL 只读白名单 ──────────────────────────────────────────────
-# 允许的 SQL 首关键字 (只读操作)
-READONLY_PREFIXES = {
-    'select', 'show', 'describe', 'desc', 'explain', 'with',
-}
-# 明确禁止的关键字 (即使出现在子查询也拦截, 防注入写操作)
-FORBIDDEN_KEYWORDS = {
-    'insert', 'update', 'delete', 'drop', 'alter', 'create', 'truncate',
-    'replace', 'rename', 'grant', 'revoke', 'lock', 'unlock', 'call',
-    'handler', 'load', 'outfile', 'dumpfile',
-}
-
-
-def validate_readonly(sql):
-    """校验 SQL 是否只读。返回 (ok: bool, reason: str)。"""
-    if not sql or not sql.strip():
-        return False, '空 SQL'
-    s = sql.strip().lower().lstrip('(').strip()
-    # 去掉开头的 WITH ... AS ( ... ) 后看主语句
-    # 简化: 取第一个词
-    first_word = re.split(r'[\s(]', s, 1)[0]
-    if first_word not in READONLY_PREFIXES:
-        return False, '非只读操作: 首关键字 "%s" 不在白名单 %s' % (
-            first_word, sorted(READONLY_PREFIXES))
-    # 扫描是否含危险关键字 (作为独立词, 防 delete 嵌在字段名里)
-    tokens = set(re.findall(r'\b\w+\b', s))
-    hit = tokens & FORBIDDEN_KEYWORDS
-    if hit:
-        return False, 'SQL 含禁止的关键字: %s (只读模式拒绝写操作)' % sorted(hit)
-    return True, ''
-
-
-def inject_limit(sql, max_rows=200):
-    """给 SELECT 自动加 LIMIT (若用户没写)。防拉爆。"""
-    s = sql.strip().rstrip(';')
-    # 已有 limit → 不动 (但截断到 max_rows 由 fetch 控制)
-    if re.search(r'\blimit\s+\d+', s, re.IGNORECASE):
-        return s
-    return s + ' LIMIT %d' % max_rows
-
-
-# ── MySQL 连接 (惰性) ─────────────────────────────────────────────────
-_conn = None
-
-
-def _get_conn():
-    """惰性建连 (首次查询时才连)。"""
-    global _conn
-    if _conn is not None:
-        return _conn
-    # 用最普及的 pymysql, 纯 Python, 无编译依赖
-    import pymysql
-    _conn = pymysql.connect(
-        host=MYSQL_HOST, port=MYSQL_PORT,
-        user=MYSQL_USER, password=MYSQL_PASSWORD,
-        charset='utf8mb4',
-        cursorclass=pymysql.cursors.DictCursor,
-        connect_timeout=5, read_timeout=10,
-    )
-    return _conn
-
-
-def _execute_query(sql, db=None, max_rows=200):
-    """执行只读查询, 返回 (columns, rows)。失败抛异常。"""
-    ok, reason = validate_readonly(sql)
-    if not ok:
-        raise ValueError('SQL 被拒: ' + reason)
-    conn = _get_conn()
-    if db:
-        conn.select_db(db)
-    cur = conn.cursor()
-    try:
-        cur.execute(sql)
-        rows = cur.fetchmany(max_rows)  # 硬上限, 不全拉
-        cols = [d[0] for d in cur.description] if cur.description else []
-        return cols, rows
-    finally:
-        cur.close()
-
-
-# ── MCP 工具定义 ──────────────────────────────────────────────────────
-TOOLS = [
-    {
-        "name": "query_schema",
-        "description": "查表结构: 列名/类型/注释/是否可空/主键。用于写 PRD/spec 时核对真实字段。例: query_schema(table='t_quality_case') 或 query_schema(table='t_quality_case', db='fywl_ics')",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "table": {"type": "string", "description": "表名 (如 t_quality_case)"},
-                "db": {"type": "string", "description": "库名 (可选, 不填用默认库)"},
-            },
-            "required": ["table"],
-        },
-    },
-    {
-        "name": "query_data",
-        "description": "查数据: 按条件查表数据, 自动 LIMIT 200 行。[QAS测试环境] 数据行是测试数据, 不代表线上真实分布, 仅参考字段含义/格式。例: query_data(table='t_quality_case', columns='id,case_status', where='create_time > \"2026-06-01\"', limit=10)",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "table": {"type": "string", "description": "表名"},
-                "columns": {"type": "string", "description": "列名 (逗号分隔, 默认 *)"},
-                "where": {"type": "string", "description": "WHERE 条件 (不带 WHERE 关键字)"},
-                "db": {"type": "string", "description": "库名 (可选)"},
-                "limit": {"type": "integer", "description": "行数上限 (默认200, 最大200)"},
-            },
-            "required": ["table"],
-        },
-    },
-    {
-        "name": "query_distinct",
-        "description": "查枚举值: 某字段的去重值。[QAS测试环境] 取值范围可信(与生产一致), 计数不可信(测试分布)。用于确认状态/类型字段有哪些取值。例: query_distinct(table='t_quality_case', column='case_status')",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "table": {"type": "string", "description": "表名"},
-                "column": {"type": "string", "description": "要查枚举的列名"},
-                "db": {"type": "string", "description": "库名 (可选)"},
-                "limit": {"type": "integer", "description": "返回枚举值上限 (默认50)"},
-            },
-            "required": ["table", "column"],
-        },
-    },
-    {
-        "name": "list_databases",
-        "description": "列出所有可见的数据库。用于发现有哪些库可查。例: list_databases()",
-        "inputSchema": {"type": "object", "properties": {}},
-    },
-    {
-        "name": "list_tables",
-        "description": "列出某库的表 (支持模糊匹配)。用于发现有哪些表。例: list_tables(db='fywl_ics', pattern='quality%')",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "db": {"type": "string", "description": "库名"},
-                "pattern": {"type": "string", "description": "表名 LIKE 模式 (可选, 如 quality%)"},
-            },
-            "required": ["db"],
-        },
-    },
-]
-
-
-# ── 工具执行 ──────────────────────────────────────────────────────────
-def _execute_tool(name, args):
-    args = args or {}
-    # 内网校验 (每次工具调用都校验, 防 VPN 中途断开)
-    ok, msg = check_intranet()
-    if not ok:
-        return msg
-
-    if name == 'list_databases':
-        cols, rows = _execute_query('SHOW DATABASES')
-        dbs = [list(r.values())[0] for r in rows]
-        return '数据库 (%d 个):\n  %s' % (len(dbs), '\n  '.join(dbs))
-
-    if name == 'list_tables':
-        db = args.get('db', '')
-        pattern = args.get('pattern', '')
-        sql = 'SHOW TABLES'
-        if pattern:
-            sql += ' LIKE "%s"' % pattern.replace('"', '')
-        cols, rows = _execute_query(sql, db=db)
-        tables = [list(r.values())[0] for r in rows]
-        return '表 (%d 个, 库=%s):\n  %s' % (len(tables), db, '\n  '.join(tables[:100]))
-
-    if name == 'query_schema':
-        table = args.get('table', '').replace('"', '').replace("'", '')
-        db = args.get('db')
-        sql = (
-            'SELECT column_name, data_type, column_type, is_nullable, '
-            'column_key, column_default, column_comment '
-            'FROM information_schema.columns '
-            'WHERE table_name = "%s" ' % table
-        )
-        if db:
-            sql += 'AND table_schema = "%s" ' % db.replace('"', '')
-        sql += 'ORDER BY ordinal_position'
-        cols, rows = _execute_query(sql)
-        if not rows:
-            return '未找到表: %s (检查表名或库名)' % table
-        lines = ['%-20s %-12s %-6s %-6s %s' % (
-            '列名', '类型', '可空', '键', '注释')]
-        for r in rows:
-            lines.append('%-20s %-12s %-6s %-6s %s' % (
-                r.get('column_name', ''), r.get('column_type', '')[:12],
-                r.get('is_nullable', '')[:3], r.get('column_key', ''),
-                (r.get('column_comment', '') or '')[:30]))
-        return '\n'.join(lines) + ENV_NOTICE_SCHEMA
-
-    if name == 'query_data':
-        table = args.get('table', '').replace('"', '').replace("'", '')
-        columns = args.get('columns') or '*'
-        where = args.get('where', '').strip()
-        db = args.get('db')
-        limit = min(int(args.get('limit', 200)), 200)
-        sql = 'SELECT %s FROM `%s`' % (columns, table)
-        if where:
-            sql += ' WHERE %s' % where
-        sql = inject_limit(sql, limit)
-        cols, rows = _execute_query(sql, db=db, max_rows=limit)
-        if not rows:
-            return '无数据 (表=%s)' % table
-        lines = [' | '.join(cols)]
-        lines.append('-' * 40)
-        for r in rows[:limit]:
-            lines.append(' | '.join(str(r.get(c, ''))[:30] for c in cols))
-        return '\n'.join(lines) + ENV_NOTICE_DATA
-
-    if name == 'query_distinct':
-        table = args.get('table', '').replace('"', '').replace("'", '')
-        column = args.get('column', '').replace('"', '').replace("'", '')
-        db = args.get('db')
-        limit = min(int(args.get('limit', 50)), 50)
-        sql = (
-            'SELECT `%s` AS val, COUNT(*) AS cnt FROM `%s` '
-            'GROUP BY `%s` ORDER BY cnt DESC LIMIT %d'
-        ) % (column, table, column, limit)
-        cols, rows = _execute_query(sql, db=db, max_rows=limit)
-        if not rows:
-            return '无数据 (表=%s 列=%s)' % (table, column)
-        # 取值范围可信(和生产一致), 但计数是测试环境分布(不可信)
-        lines = ['枚举值 (表=%s 列=%s, 取值范围可信):' % (table, column)]
-        for r in rows:
-            lines.append('  %s: %s 次 (计数仅测试环境)' % (r.get('val', ''), r.get('cnt', '')))
-        return '\n'.join(lines) + ENV_NOTICE_DATA
-
-    return '未知工具: %s' % name
-
-
-# ── MCP Stdio Protocol (JSON-RPC 2.0, 同构 kg_mcp_server.py) ──────────
-def _send(msg):
-    _real_stdout.write(json.dumps(msg, ensure_ascii=False) + '\n')
-    _real_stdout.flush()
-
-
-async def _handle(req):
-    method = req.get('method', '')
-    req_id = req.get('id')
-    params = req.get('params', {})
-
-    if method == 'initialize':
-        # 启动时做一次内网校验, 不通就在 serverInfo 里提示
-        ok, msg = check_intranet()
-        info = {"name": "qoder-mysql", "version": "1.0.0"}
-        if not ok:
-            info['warning'] = msg
-        _send({
-            "jsonrpc": "2.0", "id": req_id,
-            "result": {
-                "protocolVersion": "2024-11-05",
-                "capabilities": {"tools": {}},
-                "serverInfo": info,
-            }
-        })
-    elif method == 'notifications/initialized':
-        pass
-    elif method == 'tools/list':
-        _send({"jsonrpc": "2.0", "id": req_id, "result": {"tools": TOOLS}})
-    elif method == 'tools/call':
-        tool_name = params.get('name', '')
-        arguments = params.get('arguments', {})
-        try:
-            result_text = await asyncio.get_event_loop().run_in_executor(
-                None, _execute_tool, tool_name, arguments)
-            _send({
-                "jsonrpc": "2.0", "id": req_id,
-                "result": {"content": [{"type": "text", "text": result_text}],
-                           "isError": False}
-            })
-        except ValueError as e:
-            # SQL 被拒 (只读校验)
-            _send({
-                "jsonrpc": "2.0", "id": req_id,
-                "result": {"content": [{"type": "text",
-                                         "text": "❌ " + str(e)}],
-                           "isError": True}
-            })
-        except Exception as e:
-            _send({
-                "jsonrpc": "2.0", "id": req_id,
-                "result": {"content": [{"type": "text",
-                                         "text": "[error] %s" % str(e)[:200]}],
-                           "isError": True}
-            })
-    elif method == 'ping':
-        _send({"jsonrpc": "2.0", "id": req_id, "result": {}})
-    elif req_id is not None:
-        _send({"jsonrpc": "2.0", "id": req_id,
-               "error": {"code": -32601, "message": "Method not found: %s" % method}})
-
-
-def main():
-    import threading
-    while True:
-        try:
-            line = sys.stdin.buffer.readline()
-        except (EOFError, OSError):
-            break
-        if not line:
-            break
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            req = json.loads(line.decode('utf-8'))
-            loop = asyncio.new_event_loop()
-            loop.run_until_complete(_handle(req))
-            loop.close()
-        except json.JSONDecodeError:
-            pass
-        except Exception as e:
-            print('[mysql-mcp] error: %s' % str(e), file=sys.stderr)
-
-
-if __name__ == '__main__':
-    try:
-        main()
-    except KeyboardInterrupt:
-        pass
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+"""MySQL Read-Only MCP Server (pure Python stdio, no external SDK).
+
+提供 3 个语义化只读工具查询 MySQL 数据库 (真实数据层真相源):
+  - query_schema:  查表结构 (列名/类型/注释/约束)
+  - query_data:    查数据 (自动 LIMIT, 防 SELECT * 拉爆)
+  - query_distinct:查枚举值 (DISTINCT 某字段的去重值 + 计数)
+
+安全设计 (硬约束):
+  1. 启动前 ping 内网, 不通 → 输出"请连接内网"并拒绝启动
+  2. SQL 只读白名单: 只允许 SELECT/SHOW/DESCRIBE/EXPLAIN/WITH
+     任何写操作 (INSERT/UPDATE/DELETE/DROP/ALTER/...) 直接拒绝
+  3. query_data 自动注入 LIMIT, 上限 200 行
+  4. 账号密码从环境变量读 (mcp.json env 配置, 不落代码)
+
+注册: ~/.qoderwork/mcp.json 的 "qoder-mysql"。
+工具名: mcp__qoder-mysql__query_schema / query_data / query_distinct
+"""
+import io
+import os
+import re
+import sys
+import json
+import socket
+import asyncio
+
+# UTF-8
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+# ── 配置 (从环境变量, mcp.json env 注入) ──────────────────────────────
+MYSQL_HOST = os.environ.get('MYSQL_HOST', '10.54.6.9')
+MYSQL_PORT = int(os.environ.get('MYSQL_PORT', '3306'))
+MYSQL_USER = os.environ.get('MYSQL_USER', 'fywl_ics_test')
+MYSQL_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'Fywl_ics_test56476')
+PING_HOST = MYSQL_HOST  # 连通性校验目标
+PING_TIMEOUT = 3  # 秒
+
+# ── 环境可信度声明 (随每次工具返回, AI 不可能"忘记"边界) ──────────────
+# QAS 测试环境: 表结构/字段/枚举取值范围 = 生产一致 (可信);
+#               数据行/计数分布 = 测试数据, 不代表线上 (不可信)。
+ENV_NAME = os.environ.get('MYSQL_ENV_NAME', 'QAS 测试环境')
+ENV_NOTICE_SCHEMA = (
+    '\n[环境: %s] 表结构/字段/枚举定义与生产一致，可作为字段规格的真源。' % ENV_NAME
+)
+ENV_NOTICE_DATA = (
+    '\n⚠️ [环境: %s] 以下为测试数据样本，不代表线上真实分布。'
+    '字段取值范围可信，但具体数值/计数仅测试环境参考。' % ENV_NAME
+)
+
+# stdout 重定向 + 协议层由 BaseMCPServer 接管 (v3.0 重构)
+
+
+# ── 安全: 内网连通性校验 ──────────────────────────────────────────────
+def check_intranet():
+    """TCP 连通性校验 (比 ICMP ping 更可靠, 不依赖管理员权限)。
+    连 3306 端口, 通=内网可达, 不通=提示连内网。
+    返回 (ok: bool, msg: str)。
+    """
+    try:
+        with socket.create_connection((MYSQL_HOST, MYSQL_PORT), timeout=PING_TIMEOUT):
+            return True, ''
+    except (socket.timeout, OSError) as e:
+        return False, (
+            '无法连接内网 MySQL (%s:%s): %s\n'
+            '⚠️ 请确认你已连接公司内网 (VPN/办公网), 然后重试。'
+            'MySQL MCP 仅在内网可用。'
+        ) % (MYSQL_HOST, MYSQL_PORT, str(e)[:80])
+
+
+# ── 安全: SQL 只读白名单 ──────────────────────────────────────────────
+# 允许的 SQL 首关键字 (只读操作)
+READONLY_PREFIXES = {
+    'select', 'show', 'describe', 'desc', 'explain', 'with',
+}
+# 明确禁止的关键字 (即使出现在子查询也拦截, 防注入写操作)
+FORBIDDEN_KEYWORDS = {
+    'insert', 'update', 'delete', 'drop', 'alter', 'create', 'truncate',
+    'replace', 'rename', 'grant', 'revoke', 'lock', 'unlock', 'call',
+    'handler', 'load', 'outfile', 'dumpfile',
+}
+
+
+def validate_readonly(sql):
+    """校验 SQL 是否只读。返回 (ok: bool, reason: str)。"""
+    if not sql or not sql.strip():
+        return False, '空 SQL'
+    s = sql.strip().lower().lstrip('(').strip()
+    # 去掉开头的 WITH ... AS ( ... ) 后看主语句
+    # 简化: 取第一个词
+    first_word = re.split(r'[\s(]', s, 1)[0]
+    if first_word not in READONLY_PREFIXES:
+        return False, '非只读操作: 首关键字 "%s" 不在白名单 %s' % (
+            first_word, sorted(READONLY_PREFIXES))
+    # 扫描是否含危险关键字 (作为独立词, 防 delete 嵌在字段名里)
+    tokens = set(re.findall(r'\b\w+\b', s))
+    hit = tokens & FORBIDDEN_KEYWORDS
+    if hit:
+        return False, 'SQL 含禁止的关键字: %s (只读模式拒绝写操作)' % sorted(hit)
+    return True, ''
+
+
+def inject_limit(sql, max_rows=200):
+    """给 SELECT 自动加 LIMIT (若用户没写)。防拉爆。"""
+    s = sql.strip().rstrip(';')
+    # 已有 limit → 不动 (但截断到 max_rows 由 fetch 控制)
+    if re.search(r'\blimit\s+\d+', s, re.IGNORECASE):
+        return s
+    return s + ' LIMIT %d' % max_rows
+
+
+# ── MySQL 连接 (惰性) ─────────────────────────────────────────────────
+_conn = None
+
+
+def _get_conn():
+    """惰性建连 (首次查询时才连)。"""
+    global _conn
+    if _conn is not None:
+        return _conn
+    # 用最普及的 pymysql, 纯 Python, 无编译依赖
+    import pymysql
+    _conn = pymysql.connect(
+        host=MYSQL_HOST, port=MYSQL_PORT,
+        user=MYSQL_USER, password=MYSQL_PASSWORD,
+        charset='utf8mb4',
+        cursorclass=pymysql.cursors.DictCursor,
+        connect_timeout=5, read_timeout=10,
+    )
+    return _conn
+
+
+def _execute_query(sql, db=None, max_rows=200):
+    """执行只读查询, 返回 (columns, rows)。失败抛异常。"""
+    ok, reason = validate_readonly(sql)
+    if not ok:
+        raise ValueError('SQL 被拒: ' + reason)
+    conn = _get_conn()
+    if db:
+        conn.select_db(db)
+    cur = conn.cursor()
+    try:
+        cur.execute(sql)
+        rows = cur.fetchmany(max_rows)  # 硬上限, 不全拉
+        cols = [d[0] for d in cur.description] if cur.description else []
+        return cols, rows
+    finally:
+        cur.close()
+
+
+# ── MCP 工具定义 ──────────────────────────────────────────────────────
+TOOLS = [
+    {
+        "name": "query_schema",
+        "description": "查表结构: 列名/类型/注释/是否可空/主键。用于写 PRD/spec 时核对真实字段。例: query_schema(table='t_quality_case') 或 query_schema(table='t_quality_case', db='fywl_ics')",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "table": {"type": "string", "description": "表名 (如 t_quality_case)"},
+                "db": {"type": "string", "description": "库名 (可选, 不填用默认库)"},
+            },
+            "required": ["table"],
+        },
+    },
+    {
+        "name": "query_data",
+        "description": "查数据: 按条件查表数据, 自动 LIMIT 200 行。[QAS测试环境] 数据行是测试数据, 不代表线上真实分布, 仅参考字段含义/格式。例: query_data(table='t_quality_case', columns='id,case_status', where='create_time > \"2026-06-01\"', limit=10)",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "table": {"type": "string", "description": "表名"},
+                "columns": {"type": "string", "description": "列名 (逗号分隔, 默认 *)"},
+                "where": {"type": "string", "description": "WHERE 条件 (不带 WHERE 关键字)"},
+                "db": {"type": "string", "description": "库名 (可选)"},
+                "limit": {"type": "integer", "description": "行数上限 (默认200, 最大200)"},
+            },
+            "required": ["table"],
+        },
+    },
+    {
+        "name": "query_distinct",
+        "description": "查枚举值: 某字段的去重值。[QAS测试环境] 取值范围可信(与生产一致), 计数不可信(测试分布)。用于确认状态/类型字段有哪些取值。例: query_distinct(table='t_quality_case', column='case_status')",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "table": {"type": "string", "description": "表名"},
+                "column": {"type": "string", "description": "要查枚举的列名"},
+                "db": {"type": "string", "description": "库名 (可选)"},
+                "limit": {"type": "integer", "description": "返回枚举值上限 (默认50)"},
+            },
+            "required": ["table", "column"],
+        },
+    },
+    {
+        "name": "list_databases",
+        "description": "列出所有可见的数据库。用于发现有哪些库可查。例: list_databases()",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "list_tables",
+        "description": "列出某库的表 (支持模糊匹配)。用于发现有哪些表。例: list_tables(db='fywl_ics', pattern='quality%')",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "db": {"type": "string", "description": "库名"},
+                "pattern": {"type": "string", "description": "表名 LIKE 模式 (可选, 如 quality%)"},
+            },
+            "required": ["db"],
+        },
+    },
+]
+
+
+# ── 工具执行 ──────────────────────────────────────────────────────────
+def _execute_tool(name, args):
+    args = args or {}
+    # 内网校验 (每次工具调用都校验, 防 VPN 中途断开)
+    ok, msg = check_intranet()
+    if not ok:
+        return msg
+
+    if name == 'list_databases':
+        cols, rows = _execute_query('SHOW DATABASES')
+        dbs = [list(r.values())[0] for r in rows]
+        return '数据库 (%d 个):\n  %s' % (len(dbs), '\n  '.join(dbs))
+
+    if name == 'list_tables':
+        db = args.get('db', '')
+        pattern = args.get('pattern', '')
+        sql = 'SHOW TABLES'
+        if pattern:
+            sql += ' LIKE "%s"' % pattern.replace('"', '')
+        cols, rows = _execute_query(sql, db=db)
+        tables = [list(r.values())[0] for r in rows]
+        return '表 (%d 个, 库=%s):\n  %s' % (len(tables), db, '\n  '.join(tables[:100]))
+
+    if name == 'query_schema':
+        table = args.get('table', '').replace('"', '').replace("'", '')
+        db = args.get('db')
+        sql = (
+            'SELECT column_name, data_type, column_type, is_nullable, '
+            'column_key, column_default, column_comment '
+            'FROM information_schema.columns '
+            'WHERE table_name = "%s" ' % table
+        )
+        if db:
+            sql += 'AND table_schema = "%s" ' % db.replace('"', '')
+        sql += 'ORDER BY ordinal_position'
+        cols, rows = _execute_query(sql)
+        if not rows:
+            return '未找到表: %s (检查表名或库名)' % table
+        lines = ['%-20s %-12s %-6s %-6s %s' % (
+            '列名', '类型', '可空', '键', '注释')]
+        for r in rows:
+            lines.append('%-20s %-12s %-6s %-6s %s' % (
+                r.get('column_name', ''), r.get('column_type', '')[:12],
+                r.get('is_nullable', '')[:3], r.get('column_key', ''),
+                (r.get('column_comment', '') or '')[:30]))
+        return '\n'.join(lines) + ENV_NOTICE_SCHEMA
+
+    if name == 'query_data':
+        table = args.get('table', '').replace('"', '').replace("'", '')
+        columns = args.get('columns') or '*'
+        where = args.get('where', '').strip()
+        db = args.get('db')
+        limit = min(int(args.get('limit', 200)), 200)
+        sql = 'SELECT %s FROM `%s`' % (columns, table)
+        if where:
+            sql += ' WHERE %s' % where
+        sql = inject_limit(sql, limit)
+        cols, rows = _execute_query(sql, db=db, max_rows=limit)
+        if not rows:
+            return '无数据 (表=%s)' % table
+        lines = [' | '.join(cols)]
+        lines.append('-' * 40)
+        for r in rows[:limit]:
+            lines.append(' | '.join(str(r.get(c, ''))[:30] for c in cols))
+        return '\n'.join(lines) + ENV_NOTICE_DATA
+
+    if name == 'query_distinct':
+        table = args.get('table', '').replace('"', '').replace("'", '')
+        column = args.get('column', '').replace('"', '').replace("'", '')
+        db = args.get('db')
+        limit = min(int(args.get('limit', 50)), 50)
+        sql = (
+            'SELECT `%s` AS val, COUNT(*) AS cnt FROM `%s` '
+            'GROUP BY `%s` ORDER BY cnt DESC LIMIT %d'
+        ) % (column, table, column, limit)
+        cols, rows = _execute_query(sql, db=db, max_rows=limit)
+        if not rows:
+            return '无数据 (表=%s 列=%s)' % (table, column)
+        # 取值范围可信(和生产一致), 但计数是测试环境分布(不可信)
+        lines = ['枚举值 (表=%s 列=%s, 取值范围可信):' % (table, column)]
+        for r in rows:
+            lines.append('  %s: %s 次 (计数仅测试环境)' % (r.get('val', ''), r.get('cnt', '')))
+        return '\n'.join(lines) + ENV_NOTICE_DATA
+
+    return '未知工具: %s' % name
+
+
+# ── MCP Server (继承 BaseMCPServer, 协议层由基类接管) ──────────────────
+# v3.0 重构: 删除 _send/_handle/main 三段逐字复制代码 (~90行),
+# 改为继承 BaseMCPServer, 覆写 on_tool_error 处理 ValueError(只读拒绝)。
+
+def _bootstrap_base():
+    """延迟 import BaseMCPServer (scripts/ 在 sys.path)。"""
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    from common.mcp_base import BaseMCPServer
+    return BaseMCPServer
+
+
+class MysqlMCPServer(_bootstrap_base()):
+    """MySQL 只读 MCP Server。继承基类协议层, 只填工具逻辑 + 异常分类。"""
+
+    SERVER_NAME = "qoder-mysql"
+    SERVER_VERSION = "1.0.0"
+    TOOLS = TOOLS  # 引用上方模块级 TOOLS
+
+    def handle_tool(self, name, args):
+        return _execute_tool(name, args)
+
+    def on_initialize_hook(self, info):
+        # 启动时内网校验, 不通塞 warning (与旧版行为一致)
+        ok, msg = check_intranet()
+        if not ok:
+            info['warning'] = msg
+
+    def on_tool_error(self, e):
+        # mysql 特有: ValueError = SQL 只读校验拒绝, 单独友好提示
+        if isinstance(e, ValueError):
+            return ("❌ " + str(e), True)
+        # 其它异常走基类默认
+        return super().on_tool_error(e)
+
+
+if __name__ == '__main__':
+    MysqlMCPServer().run()