flowchart TD
    subgraph ClientSide ["AI 客户端生态 (MCP Client)"]
        Client["Claude Desktop / Cursor / VS Code / Dify / Windsurf"]
    end

    subgraph ProtocolLayer ["通信传输、自解释元数据与环境层"]
        FastMCP["FastMCP 协议服务器 (stdio / sse / streamable-http)"]
        Meta["服务元数据自解释 (--server-name / --server-instructions)"]
        Doctor["健康体检探针与版本反射 (--doctor / --version)"]
        Env["分层环境解析器 (core/env.py)"]
        Dotenv[".env 自动探测与 RFC 1738 密码免转义拼装"]
    end

    subgraph GuardLayer ["AST 深度语法安全守卫 (core/guard.py)"]
        ASTParse["sqlglot AST 语法树解析与分析"]
        ReadOnly["只读语义校验 (Select / CTE With)"]
        LimitInject["自动注入安全 LIMIT 截断 (默认 100 行)"]
        WhereGuard["DML 强制阻断无 WHERE 条件与恒真伪条件"]
        ExplainGuard["sql_query explain 危险修饰符 (ANALYZE) 拦截与剥离"]
    end

    subgraph EngineLayer ["连接池、分级审计与多库路由中枢 (core/)"]
        Registry["ConnectionRegistry (多库配置中心)"]
        Pool["连接池健康预检与自愈 (pool_pre_ping)"]
        Audit["分级审计与防爆截断器 (mutation/all/off, 4096 字符截断)"]
        Resources["MCP 只读资源暴露器 (rdbms://connections, schema, audit)"]
    end

    subgraph DatabaseLayer ["多元关系型数据库集群 (SQLAlchemy 2.0)"]
        MySQL[("MySQL 8.x / 5.7 / MariaDB")]
        PostgreSQL[("PostgreSQL 12~17")]
        SQLite[("SQLite 内存库 / 本地文件库")]
        Oracle[("Oracle 19c / 21c")]
        MSSQL[("SQL Server / ClickHouse / 国产库")]
    end

    Client -->|"JSON-RPC / SSE"| FastMCP
    FastMCP --> Meta
    Doctor -.-> Registry
    Dotenv --> Env --> Registry
    FastMCP -->|"6 核心工具调用 (带多库路由引导)"| GuardLayer
    FastMCP -->|"3 大 MCP 只读资源"| Resources
    GuardLayer -->|"AST 验证通过"| Registry
    Registry --> Pool
    Pool -->|"工作线程池异步卸载 (anyio)"| DatabaseLayer
    Registry -.->|"审计流水异步落盘"| Audit

# 1. 单数据库直连启动 (只读安全模式)
uvx atengk-mcp-server-rdbms --db-url "postgresql+psycopg://user:password@localhost:5432/mydb"

# 2. 多数据库配置文件启动
uvx atengk-mcp-server-rdbms --config ./connections.yaml

# 3. 开启写入权限 (允许 DML 与 DDL)
uvx atengk-mcp-server-rdbms --db-url "sqlite:///./demo.db" --allow-dml --allow-ddl

git clone https://github.com/atengk/mcp-server-rdbms.git
cd mcp-server-rdbms
uv sync
uv run atengk-mcp-server-rdbms --db-url "sqlite:///./demo.db"

# 1. 执行全方位自检探针 (诊断本地驱动就绪矩阵、命名空间合规性与连通性)
uvx atengk-mcp-server-rdbms --doctor

# 2. 携带目标数据库连接执行真实握手探活 (测试网络通畅度与账号权限)
uvx atengk-mcp-server-rdbms --db-url "postgresql+psycopg://user:password@localhost:5432/mydb" --doctor

# 3. 机器可读模式 (输出 JSON，便于 CI/CD 自动化流水线集成)
uvx atengk-mcp-server-rdbms --doctor --format json

# 4. 显示服务版本、Python 运行时、SQLAlchemy 版本与操作系统基线
uvx atengk-mcp-server-rdbms --version

┌─────────────────────────────────────────────────────────────────────────────┐
│ MCP Server RDBMS 运行环境与健康体检探针 (Doctor Diagnostics)                │
│ 服务版本: 1.3.0 | Python: 3.12.14 (CPython) | SQLAlchemy: 2.1.3 | SQLGlot:  │
│ 30.21.0                                                                     │
└─────────────────────────────────────────────────────────────────────────────┘
                          1. 关系型数据库驱动就绪矩阵                          
┌─────────────────────┬────────────────────┬────────────┬─────────────────────┐
│ 目标方言            │ 对应驱动包         │  就绪状态  │ 驱动版本 / 安装指引 │
├─────────────────────┼────────────────────┼────────────┼─────────────────────┤
│ sqlite              │ sqlite3            │  [✓] 就绪  │ 3.12.14             │
│ mysql / mariadb     │ pymysql            │  [✓] 就绪  │ 1.2.3               │
│ postgresql          │ psycopg            │  [✓] 就绪  │ 3.3.6               │
│ oracle              │ oracledb           │ [!] 未安装 │ 可选驱动未安装。如… │
│ mssql (SQL Server)  │ pyodbc             │ [!] 未安装 │ 可选驱动未安装。如… │
│ clickhouse          │ clickhouse-connect │ [!] 未安装 │ 可选驱动未安装。如… │
│ dm (达梦)           │ dmPython           │ [!] 未安装 │ 可选驱动未安装。如… │
│ kingbase (人大金仓) │ ksycopg2           │ [!] 未安装 │ 可选驱动未安装。如… │
└─────────────────────┴────────────────────┴────────────┴─────────────────────┘

                       2. 环境变量命名空间与配置合规审计                       
┌──────────────────────────┬──────────┬───────────────────┬───────────────────┐
│ 审计检测项               │   状态   │ 取值 / 命中       │ 合规诊断明细与建议│
├──────────────────────────┼──────────┼───────────────────┼───────────────────┤
│ 通用无前缀环境变量扫描   │ [✓] 合规 │ 合规              │ 未发现导致意外串库│
│ MCP_RDBMS_* 专属变量纳管 │ [✓] 合规 │ 2 项生效          │ 当前环境生效 2 项 │
│ 单库连接串语法合法性     │ [✓] 合规 │ postgresql+psy... │ URL 语法校验通过  │
└──────────────────────────┴──────────┴───────────────────┴───────────────────┘

                          3. 数据库连接握手与探活探针                          
┌──────────┬────────────┬───────────────────────┬──────────┬──────────────────┐
│ 连接别名 │ 方言       │ 连接串 (脱敏)         │  连通性  │ 延迟 / 错误原因  │
├──────────┼────────────┼───────────────────────┼──────────┼──────────────────┤
│ default  │ postgresql │ postgresql+psycopg... │ [✓] 通畅 │ 14.25 ms (Ping)  │
└──────────┴────────────┴───────────────────────┴──────────┴──────────────────┘

┌────────────────────── ✓ 诊断通过：环境与服务状态健康 ───────────────────────┐
│ 全部核心诊断项通过，运行环境与数据库连接通畅。                              │
└─────────────────────────────────────────────────────────────────────────────┘

{
  "mcpServers": {
    "rdbms": {
      "command": "uvx",
      "args": ["atengk-mcp-server-rdbms"],
      "env": {
        "MCP_RDBMS_DIALECT": "mysql",
        "MCP_RDBMS_DB_HOST": "127.0.0.1",
        "MCP_RDBMS_DB_PORT": "3306",
        "MCP_RDBMS_USER": "root",
        "MCP_RDBMS_PASSWORD": "Admin@123#2026",
        "MCP_RDBMS_DATABASE": "mydb"
      }
    }
  }
}

{
  "mcpServers": {
    "rdbms": {
      "command": "uvx",
      "args": ["atengk-mcp-server-rdbms"],
      "env": {
        "MCP_RDBMS_DB_URL": "postgresql+psycopg://user:password@localhost:5432/mydb"
      }
    }
  }
}

{
  "mcpServers": {
    "rdbms": {
      "command": "uvx",
      "args": [
        "atengk-mcp-server-rdbms",
        "--db-url",
        "mysql+pymysql://root:Admin%40123@127.0.0.1:3306/mydb?charset=utf8mb4"
      ]
    }
  }
}

{
  "mcpServers": {
    "rdbms_cluster": {
      "command": "uvx",
      "args": ["atengk-mcp-server-rdbms"],
      "env": {
        "MCP_RDBMS_DB_CRM": "postgresql+psycopg://user:pass@10.0.0.1:5432/crm_db",
        "MCP_RDBMS_DB_ERP": "mysql+pymysql://root:pass@10.0.0.2:3306/erp_db",
        "MCP_RDBMS_DEFAULT_DB": "crm",
        "MCP_RDBMS_ALLOW_DML": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "crm_database": {
      "command": "uvx",
      "args": [
        "atengk-mcp-server-rdbms",
        "--db-url", "postgresql+psycopg://user:pass@10.0.0.1:5432/crm",
        "--server-name", "crm-database-service",
        "--server-instructions", "企业 CRM 客户库专用通道。负责客户档案、跟进线索与商机表查询。"
      ]
    },
    "erp_database": {
      "command": "uvx",
      "args": [
        "atengk-mcp-server-rdbms",
        "--db-url", "mysql+pymysql://root:pass@10.0.0.2:3306/erp",
        "--server-name", "erp-database-service",
        "--server-instructions", "企业 ERP 进销存专用通道。负责采购入库、库存盘点与财务凭证表查询。"
      ]
    }
  }
}

{
  "mcpServers": {
    "rdbms-remote": {
      "url": "http://<服务器IP>:8000/sse",
      "headers": {
        "Authorization": "Bearer YOUR_STRONG_SECRET_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "rdbms-secure": {
      "url": "https://mcp.yourdomain.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_STRONG_SECRET_TOKEN"
      }
    }
  }
}

你是一名精通关系型数据库与 SQL 调优的高级数据专家与研发助理。当前环境已通过通用关系型数据库 MCP 服务接入数据源，请严格遵循以下日常交互准则：

1. 【库表摸底与多库路由】：
   - 对话初次涉及业务时，可通过只读资源 `rdbms://connections` 或 `db_info` 工具获取所有已配置连接别名与默认库状态；
   - 系统支持多库路由。若用户提问涉及指定库（如“在 CRM 库查…”），请在调用工具时显式传入 `db="crm"`；缺省时将自动路由至默认数据库。
2. 【安全只读探索与小样本采样】：
   - 探查业务宽表或未知数据时，请显式使用 `sql_query(sql=..., limit=3~5)` 进行微采样，确认实际列名与数据形态后再编写复杂统计分析；
   - 严禁盲目执行全量扫描；未显式指定 limit 时系统底层将安全截断至 100 行；单次查询内置 30 秒超时熔断保护（支持传入 timeout 参数，最高 120 秒）。
3. 【慢查询与执行计划诊断】：
   - 当用户要求“分析性能/优化慢查询/诊断索引”时，请调用 `sql_query(sql=..., explain=True)`；
   - 根据返回的执行计划（扫描类型、过滤条件、索引使用）为用户输出通俗、专业的性能诊断与建索引建议。
4. 【受控变更与破坏防御】：
   - 数据变更（DML）必须在单一事务中执行：`sql_dml(sql=...)`，单步失败自动全量回滚；系统 AST 会强制拦截无 WHERE 条件或恒真伪条件的误操作；
   - 结构变更（DDL）必须显式确认：调用 `sql_ddl(sql=..., confirm=True)`，调用前向用户清晰列出变更脚本并提示影响。

# 启动常驻服务
docker compose up -d

# 查看运行日志与连接池状态
docker compose logs -f

# 停止服务
docker compose down

services:
  mcp-rdbms:
    image: ghcr.io/atengk/mcp-server-rdbms:latest
    # image: ghcr.io/atengk/mcp-server-rdbms:1.4.0
    # build: .  # 开发者二次构建镜像时解开注释即可
    container_name: mcp-server-rdbms
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - MCP_RDBMS_TRANSPORT=sse
      - MCP_RDBMS_SERVER_HOST=0.0.0.0
      - MCP_RDBMS_SERVER_PORT=8000
      - MCP_RDBMS_CONFIG=/app/connections.yaml
    volumes:
      # 挂载多库配置（只读）
      - ./connections.yaml:/app/connections.yaml:ro
      # 挂载操作审计流水日志（宿主机持久化保存）
      - ./rdbms_mcp_audit.log:/app/rdbms_mcp_audit.log:rw

# 方式 A：挂载本地 connections.yaml 多库配置启动
docker run -d \
  --name mcp-rdbms \
  -p 8000:8000 \
  -v $(pwd)/connections.yaml:/app/connections.yaml:ro \
  -v $(pwd)/rdbms_mcp_audit.log:/app/rdbms_mcp_audit.log:rw \
  -e MCP_RDBMS_CONFIG=/app/connections.yaml \
  ghcr.io/atengk/mcp-server-rdbms:latest

# 方式 B：纯环境变量直连单数据库（免挂载任何文件，密码特殊字符自动免转义！）
docker run -d \
  --name mcp-rdbms \
  -p 8000:8000 \
  -e MCP_RDBMS_DIALECT=mysql \
  -e MCP_RDBMS_DB_HOST=192.168.1.100 \
  -e MCP_RDBMS_DB_PORT=3306 \
  -e MCP_RDBMS_USER=root \
  -e MCP_RDBMS_PASSWORD="Admin@123#2026" \
  -e MCP_RDBMS_DATABASE=mydb \
  ghcr.io/atengk/mcp-server-rdbms:latest

# 默认连接别名 (调用工具未传 db 参数时默认使用的连接)
default: "pg_main"

connections:
  # 1. 核心业务主库 (支持读写模式与事务)
  pg_main:
    url: "postgresql+psycopg://postgres:Admin%40123@10.0.0.1:5432/business_db"
    read_only: false       # 设为 false 配合 --allow-dml 允许修改
    is_default: true

  # 2. 只读离线数据仓库 (强制只读保护)
  mysql_analytics:
    url: "mysql+pymysql://reader:Public%40123@10.0.0.2:3306/dw_db?charset=utf8mb4"
    read_only: true        # 该连接强制只读，即使传入 --allow-dml 也禁止修改

  # 3. 本地嵌入式开发数据库
  sqlite_local:
    url: "sqlite:///./dev_cache.db"
    read_only: false

uvx atengk-mcp-server-rdbms --config ./connections.yaml --allow-dml

# 挂载 Oracle 驱动
uvx --with oracledb atengk-mcp-server-rdbms --db-url "oracle+oracledb://scott:tiger@host:1521/?service_name=orcl"

# 挂载 SQL Server 驱动
uvx --with pyodbc atengk-mcp-server-rdbms --db-url "mssql+pyodbc://sa:pass@host:1433/db?driver=ODBC+Driver+18+for+SQL+Server"

# 挂载 ClickHouse 驱动
uvx --with clickhouse-connect atengk-mcp-server-rdbms --db-url "clickhouse+connect://default:pass@host:8123/default"

uv pip install "atengk-mcp-server-rdbms[oracle]"      # 安装 Oracle 支持
uv pip install "atengk-mcp-server-rdbms[mssql]"       # 安装 SQL Server 支持
uv pip install "atengk-mcp-server-rdbms[clickhouse]"  # 安装 ClickHouse 支持
uv pip install "atengk-mcp-server-rdbms[all]"         # 一键安装所有驱动扩展

用法: atengk-mcp-server-rdbms [-h] [--version] [--doctor] [--format {text,json}]
                              [--server-name SERVER_NAME]
                              [--server-instructions SERVER_INSTRUCTIONS]
                              [--db-url DB_URL] [--config CONFIG]
                              [--allow-dml] [--allow-ddl]
                              [--transport {stdio,sse,streamable-http}]
                              [--host HOST] [--port PORT]
                              [--auth-token AUTH_TOKEN]
                              [--audit-log AUDIT_LOG]
                              [--audit-mode {mutation,all,off}]
                              [--audit-max-bytes AUDIT_MAX_BYTES]
                              [--audit-backup-count AUDIT_BACKUP_COUNT]