UXDB MCP Server

概述

UXDB MCP Server 是UXDB 基于 Model Context Protocol（MCP）规范构建的数据库管理中间件，。它将UXDB数据库管理能力——Schema 管理、数据 CRUD、查询分析、安全审计、实时监控、数据迁移等——封装为 15 款标准化 MCP Tool，使各类支持 MCP 协议的 AI 助手能够在自然语言交互中直接执行数据库运维操作。

1.1 核心能力

1.2 关键技术指标

• 15 款数据库管理工具，覆盖 Schema、数据、查询、用户、索引、约束、触发器、函数、注释、分析、调试、监控、迁移等完整领域；
• 3 种传输协议：stdio（本地）、SSE（Web 遗留兼容）、Streamable HTTP（推荐）；
• 4 个 MCP 协议版本：2026-07-28、2025-11-25、2025-06-18、2024-11-05，支持自动协商；
• Python ≥ 3.8，零编译依赖，pip install 即用，单条命令启动。

1.3 与传统运维方式的对比

1.4 缩略语

2. 快速入门

2.1 前置条件

1. 一套可访问的 UXDB 数据库实例，并具备数据库账号（建议使用专用低权限账号，见 10.1）；
2. Python ≥ 3.8 环境；
3. 一个支持 MCP 协议的 AI 客户端（IDE 插件、桌面 AI 助手、自研 Agent 等）。

2.2 安装

pip install uxdb-mcp-server

零编译依赖，无需额外系统组件。

2.3 配置连接

UXDB MCP Server 通过连接字符串定位目标数据库，解析优先级为：

1. 工具调用参数显式传入；
2. 服务初始化默认值；
3. UXDB_CONNECTION_STRING 环境变量。

推荐使用 .env 文件集中管理配置（CLI 入口启动时自动加载）：

# .env 示例（变量名以发行包附带的 .env.example 为准）
UXDB_CONNECTION_STRING=postgresql://username:password@127.0.0.1:5432/mydb

安全提示：连接字符串包含明文凭据。生产环境建议通过密钥管理系统或受限权限的环境变量注入，避免提交到代码仓库。

2.4 启动服务

# 本地 stdio 传输（默认）
uxdb-mcp-server

# Web 部署：Streamable HTTP 传输（推荐）
uxdb-mcp-server --transport streamable_http --host 127.0.0.1 --port 8080

# Web 部署：SSE 传输（遗留客户端兼容）
uxdb-mcp-server --transport sse --host 127.0.0.1 --port 8080

配置优先级：显式参数 > 环境变量 > 硬编码默认值。

2.5 接入 AI 客户端

stdio 传输（本地客户端，如 IDE 插件、桌面 AI 助手）——客户端以子进程方式拉起服务：

{
  "mcpServers": {
    "uxdb": {
      "command": "uxdb-mcp-server",
      "env": {
        "UXDB_CONNECTION_STRING": "uxdb://username:password@127.0.0.1:5432/mydb"
      }
    }
  }
}

Streamable HTTP / SSE 传输（Web 客户端）——先在服务器上启动 HTTP 模式，再在客户端中配置端点 URL：

{
  "mcpServers": {
    "uxdb": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

各客户端的配置入口：

2.6 验证连通

接入后在 AI 客户端中发出自然语言指令：

"列出当前数据库有哪些 Schema 和表。"

AI 将调用 ux_manage_schema（get_info）并返回结果。也可直接访问健康检查端点（HTTP 传输，无需认证）：

curl http://127.0.0.1:8080/health

3. 核心概念

3.1 MCP 协议

MCP（Model Context Protocol）是 AI 模型与外部工具交互的开放标准协议，底层基于 JSON-RPC 2.0。UXDB MCP Server 作为 MCP 服务器，向 AI 客户端暴露三类标准能力：

消息编码为 UTF-8 的 JSON-RPC 请求/通知/响应。服务器实现的标准方法包括：initialize（旧版协议协商）、server/discover（2026-07-28 服务发现）、tools/list、tools/call、resources/list、resources/templates/list、resources/read、prompts/list、prompts/get、subscriptions/listen。ping 在 stdio 传输下由 SDK 处理；HTTP 传输下 ping 与 logging/setLevel 返回 Method not found。

3.2 协议版本协商

服务器支持 2026-07-28、2025-11-25、2025-06-18、2024-11-05 四个 MCP 协议版本，协商策略：

• 客户端请求版本若在支持列表中，直接使用；
• 否则返回服务器最新支持版本（2026-07-28），由客户端决定是否继续。

其中 2026-07-28 为现代无状态协议（server/discover + 每请求 _meta 声明协议版本与能力），其余版本沿用 initialize / notifications/initialized 握手。SSE 传输仅支持旧版协议（不含 2026-07-28）。

4. 架构概览

4.1 分层架构

┌─────────────────────────────────────────────┐
│  CLI 入口层                                  │
│  命令行参数解析 / .env 加载 / 配置初始化 /     │
│  操作系统信号管理（优雅关闭）                  │
├─────────────────────────────────────────────┤
│  核心编排层（UXDBMCPServer）                  │
│  工具实例管理 / MCP 标准处理器绑定 /           │
│  协议版本协商 / 传输层适配                     │
├─────────────────────────────────────────────┤
│  传输层                                      │
│  stdio（本地） / SSE（遗留） /                │
│  Streamable HTTP（推荐）                     │
├─────────────────────────────────────────────┤
│  工具层                                      │
│  15 款 ux_* 数据库管理工具                    │
├─────────────────────────────────────────────┤
│  安全与认证层                                 │
│  Token 认证 / 参数化查询 / 操作语义校验 /      │
│  数据库标识符格式验证                         │
├─────────────────────────────────────────────┤
│  连接管理层（DatabaseConnection）             │
│  线程安全连接池 / 事务自动 commit-rollback /   │
│  连接健康检查 / 错误智能分类与脱敏             │
└─────────────────────────────────────────────┘

4.2 逻辑组件职责

4.3 核心设计模式

• 工具抽象基类：所有工具继承 UXDBTool ABC，实现 name、description、inputSchema、execute()，确保工具实现的统一性和可发现性。
• 连接字符串解析链：_get_connection_string() 按优先级解析——工具调用参数显式传入 → 服务初始化默认值 → UXDB_CONNECTION_STRING 环境变量。
• 配置优先级链（CLI）：显式参数 > 环境变量 > 硬编码默认值。
• 单例连接池：DatabaseConnection 采用双重检查锁的单例模式 + ThreadedConnectionPool，确保连接安全复用。
• 共享传输基类：SSE 与 Streamable HTTP 两种传输的核心逻辑抽象到 _IntegratedTransportBase，避免逻辑重复。

5. 核心技术设计

5.1 核心编排器（UXDBMCPServer）

UXDBMCPServer 是整个系统的中央调度器，负责：

• 工具注册：初始化 15 款工具实例，注册到 MCP Server；
• 处理器绑定：绑定 9 个 MCP 标准处理器：tools/list、tools/call、resources/list、resources/templates/list、resources/read、prompts/list、prompts/get、subscriptions/listen、server/discover；
• 协议协商：根据客户端请求版本与服务器支持版本自动协商；
• 传输适配：通过 SSETransportIntegrated / StreamableHTTPTransportIntegrated 包装类，将工具处理逻辑注入传输层。

共享传输基类 _IntegratedTransportBase 承载两种 HTTP 传输的公共逻辑：

• initialize 响应构建（旧版协议协商、能力公告）与 server/discover 处理（2026-07-28）
• tools/list、tools/call 处理
• resources/list、resources/templates/list、resources/read 处理
• prompts/list、prompts/get 处理
• subscriptions/listen 处理
• ping 与 logging/setLevel 返回 Method not found（stdio 下由 SDK 处理）

5.2 连接管理（DatabaseConnection）

采用线程安全单例 + 连接池设计：

DatabaseConnection
├── 双重检查锁单例（_instance + _lock）
├── ThreadedConnectionPool（minconn=1, maxconn=10）
├── RealDictCursor（结果以字典形式返回）
├── 连接字符串解析（URL → ConnectionConfig）
├── 查询方法：query() / query_single() / query_scalar()
├── 执行方法：execute()          # DML/DDL
├── 事务支持：transaction() 异步上下文管理器
└── 智能错误分类：认证失败 / 连接拒绝 / 权限不足 / 外键冲突 / 超时

连接安全机制：

• 每次操作后自动归还连接到池，防止连接泄漏；
• 事务自动 commit / rollback；
• autocommit 状态在操作后还原；
• 连接测试：connect() 时执行 SELECT 1 验证。

5.3 配置体系（Config）

分层级联的配置数据类：

ServerConfig
├── name: "uxdb-mcp-server"
├── version: "1.1.0"
├── connection_string: str | None
├── log_level: "INFO"
├── TransportConfig
│   ├── transport_type: "stdio" | "sse" | "streamable_http"
│   ├── host: "127.0.0.1"
│   ├── port: 8080
│   ├── cors_origins: ["*"]
│   └── enable_cors: True
├── ProtocolConfig
│   ├── supported_versions: ["2026-07-28", "2025-11-25", "2025-06-18", "2024-11-05"]
│   ├── default_version_by_transport: {stdio → 2026-07-28, sse → 2025-11-25, streamable_http → 2026-07-28}
│   └── negotiate_version(client_version) → negotiated_version
└── AuthConfig
    ├── auth_token: str | None
    └── enabled: bool            # 设置 token 后自动启用

5.4 资源与提示系统

除工具外，服务器还通过 MCP 标准机制暴露资源与提示模板。

资源（Resources）：

提示模板（Prompts）：

6. 工具参考

UXDB MCP Server 提供 15 款标准化工具，每个工具均实现 UXDBTool 抽象基类，包含 name（以 ux_ 为前缀）、description、inputSchema（JSON Schema）和 execute() 方法。

6.1 工具全景

6.2 ux_manage_schema — Schema 管理

6.3 ux_execute_query — 数据查询

三合一查询工具，统一处理不同查询场景：

6.4 ux_execute_mutation — 数据变更

6.5 ux_execute_sql — 原生 SQL

灵活性最高的 SQL 执行能力：

• 支持任意 DDL / DML / 复合语句；
• 可选事务模式（transactional=true）；
• 可选期望返回行（expectRows=true）；
• 参数化查询支持；
• 可选执行超时（timeout，秒）。

注意：该工具无操作类型限制，生产环境应通过数据库账号权限控制其影响面（见 10.1）。

6.6 ux_manage_query — 查询分析

EXPLAIN 选项矩阵：

6.7 ux_analyze_database — 数据库分析

三维度分析引擎：

6.8 ux_monitor_database — 实时监控

五层监控体系（各层均可通过开关参数按需启用）：

Database 层（默认）
├── 数据库名称、大小、运行时间
├── 连接统计（active / idle / total / max）
├── 事务统计（committed / rolledBack）
└── 缓存命中率

Table 层（includeTables=true）
├── 表大小、行数、死元组数
├── 上次 VACUUM / ANALYZE 时间
├── 扫描计数、索引使用率
└── 长期未 VACUUM 告警

Query 层（includeQueries=true）
├── 活跃查询列表（PID、用户、耗时、状态）
├── 等待事件详情
└── 长查询告警（可配置阈值）

Lock 层（includeLocks=true）
├── 锁关系、模式、授予状态
├── 阻塞锁检测
└── 阻塞告警

Replication 层（includeReplication=true）
├── 复制客户端状态
├── LSN 进度（sent / write / flush / replay）
├── 复制延迟（write / flush / replay lag）
└── 同步状态 + 延迟告警

可配置告警阈值参数：

6.9 ux_debug_database — 问题调试

6.10 ux_manage_indexes — 索引管理

6.11 ux_manage_users — 用户与权限

6.12 ux_manage_constraints — 约束管理

6.13 ux_manage_functions — 函数与行级安全（RLS）管理

6.14 ux_manage_triggers — 触发器管理

6.15 ux_manage_comments — 注释管理

6.16 ux_manage_data_migration — 数据迁移

7. 传输层

7.1 传输方式对比

注：表中协议版本为各传输的默认版本。Streamable HTTP 同时兼容 2025-11-25 / 2025-06-18 / 2024-11-05 旧版客户端；SSE 不支持 2026-07-28。

选型建议：

• 本地开发、IDE 插件、桌面 AI 助手 → stdio（最低延迟，客户端自动管理进程生命周期）；
• 新建 Web 部署 → Streamable HTTP（多客户端共享、无状态设计易于横向扩展、符合 MCP 最新规范）；
• 已有旧版 Web 客户端无法升级 → SSE（仅为兼容保留）。

7.2 stdio 传输（本地开发）

• 客户端将 MCP Server 作为子进程启动；
• 服务器从标准输入（stdin）读取 JSON-RPC 消息，向标准输出（stdout）写出消息，消息以换行分隔；
• 标准错误（stderr）用于日志输出，客户端可选择捕获或忽略；
• stdout 不会输出任何非 MCP 消息内容，保证协议流干净。

7.3 SSE 传输（遗留兼容）

保持与早期 MCP 客户端的兼容性；默认协议版本为 2025-11-25（不支持 2026-07-28）；支持查询参数传递认证凭证，适配无法设置 HTTP Header 的 SSE 客户端。

7.4 Streamable HTTP 传输（推荐）

基于 MCP 2026-07-28 规范的无状态实现：

• 无状态设计：不维护会话，无 Mcp-Session-Id；每个请求自包含，现代客户端通过请求体 _meta（io.modelcontextprotocol/protocolVersion 与 clientCapabilities）声明协议版本与能力；
• 消息交换：客户端所有 JSON-RPC 消息以 HTTP POST 发送至 MCP 端点（GET 已移除）；服务器返回单个 JSON 响应，通知类消息返回 202 Accepted；
• 协议版本头校验：携带 MCP-Protocol-Version 头的请求按 2026-07-28 规则校验：Mcp-Method 头须与请求体方法一致，tools/call / resources/read / prompts/get 请求须携带匹配的 Mcp-Name 头；头与请求体不一致返回 HeaderMismatch（-32020），版本不受支持返回 UnsupportedProtocolVersion（-32022）；未携带该头的请求按旧版客户端处理（仅校验版本）；
• CORS 与来源校验：CLI 默认仅允许 http://localhost / http://127.0.0.1 来源（可用 --allowed-origins 扩展），非允许来源的请求返回 403；
• 认证集成：Bearer Token 验证嵌入请求处理流程；
• 健康检查：/health 端点绕过认证，便于负载均衡探活；
• Protected Resource Metadata：/.well-known/oauth-protected-resource 端点，符合 MCP Authorization 规范（RFC 9728）。

8. 安全与认证

8.1 认证架构

HTTP 传输层采用 Token 认证机制，所有到达 MCP 端点的请求均需携带有效凭证：

AI 客户端                          UXDB MCP Server
   │                                     │
   │  initialize / server/discover（协商）  │
   │ ───────────────────────────────────► │
   │  ◄───── InitializeResult ─────────── │
   │                                      │
   │  tools/call                          │
   │  Authorization: Bearer <token>       │
   │ ───────────────────────────────────► │
   │                              ┌───────┴────────┐
   │                              │ Token 验证      │
   │                              │ 语义校验        │
   │                              │ 参数化执行      │
   │                              └───────┬────────┘
   │  ◄───── 工具执行结果 ──────────────── │

• 认证在 AuthConfig 中配置：设置 auth_token 后自动启用；
• /health 端点绕过认证，供探活使用；
• SSE 传输额外支持查询参数传递凭证，适配无法设置 HTTP Header 的旧客户端。

8.2 多层安全机制

8.3 Protected Resource Metadata

服务器在 /.well-known/oauth-protected-resource 返回符合 MCP Authorization 规范（RFC 9728）的元数据：

{
  "resource": "/mcp",
  "authorization_servers": [],
  "scopes_supported": ["mcp:tools", "mcp:resources"]
}

支持未来接入外部 OAuth 2.0 授权服务器。

8.4 部署侧安全要求

生产部署 HTTP 传输时，除产品内置机制外，还需遵守 MCP 规范的传输层安全要求：

1. 校验 Origin 头：所有入站连接应验证 Origin 头，防止 DNS 重绑定攻击；
2. 仅绑定本机地址：本地运行时绑定 127.0.0.1 而非 0.0.0.0，确需对外提供服务时应置于反向代理 / API 网关之后；
3. 强制认证：对外暴露的端点必须启用 Token 认证；
4. 收紧 CORS：将 cors_origins 从 * 收敛为明确的客户端来源列表；
5. 网络隔离：MCP Server 与数据库实例之间建议部署于内网，仅开放必要端口。

9. 典型使用场景

以下示例均为直接对 AI 客户端发出的自然语言指令，AI 将自动选择并调用对应工具。

9.1 日常开发

"帮我创建一张 orders 表，包含 id 主键、customer_id、amount、status 和创建时间。"
      → ux_manage_schema / create_table

"给 orders 表批量插入 1000 条测试数据。"
      → ux_execute_mutation / insert

"查询最近 7 天金额最高的 10 笔订单。"
      → ux_execute_query / select

"orders.status 的值改成 'PAID'，条件是 id 等于 1001。"
      → ux_execute_mutation / update

9.2 查询性能调优

"这条 SQL 为什么慢？SELECT * FROM orders JOIN customers ON ... WHERE ..."
      → ux_manage_query / explain（含 EXPLAIN ANALYZE 选项）

"找出数据库里最慢的前 10 条查询。"
      → ux_manage_query / get_slow_queries

"分析 orders 表的索引使用情况，哪些索引没被用到？"
      → ux_manage_indexes / analyze

"给 orders.customer_id 建一个 B-tree 索引。"
      → ux_manage_indexes / create

9.3 DBA 日常巡检

"对数据库做一次全面体检。"
      → ux_analyze_database（configuration + performance + security）

"当前有多少活跃连接？有没有长事务？"
      → ux_monitor_database（Query 层）

"检查一下复制延迟和 WAL 积压情况。"
      → ux_monitor_database（Replication 层）/ ux_debug_database（replication）

"哪些表死元组比例过高，需要 VACUUM？"
      → ux_monitor_database（Table 层，deadTuplesPercentage 阈值）

9.4 故障诊断

"数据库连不上了，帮我排查。"
      → ux_debug_database（connection）

"系统卡住了，是不是有锁阻塞？"
      → ux_debug_database（locks，锁等待链分析）

9.5 数据迁移

"把 public.orders 表导出为 CSV 文件。"
      → ux_manage_data_migration / export

"把这批 JSON 数据导入到新库的 orders 表。"
      → ux_manage_data_migration / import

10. 部署与运维最佳实践

10.1 最小权限原则

MCP Server 让 AI 获得了直接操作数据库的能力，权限边界务必由数据库账号控制：

• 为 MCP 接入创建专用数据库账号，不要复用 DBA 超级用户账号；
• 按实际需要授权：只读场景仅授予 SELECT；开发场景授予目标 Schema 的 DML；DDL 与用户管理权限仅在确有需要时授予；
• ux_execute_sql 无操作类型限制，账号权限是其唯一约束——生产库上该账号不应拥有危险权限（如超级用户、批量删除整表的隐式能力）；
• 定期通过 ux_manage_users（get_users）审计账号与权限分配。

10.2 凭据管理

• 连接字符串优先通过服务初始化默认值或环境变量注入，避免在工具调用参数中动态传入凭据——经工具参数传入的内容会进入 AI 对话上下文；
• .env 文件应加入版本控制忽略清单；
• HTTP 部署时，Token 与数据库凭据均应通过密钥管理系统下发，避免明文落盘。

10.3 传输与暴露面

• 本地开发：stdio，凭据经环境变量注入子进程；
• Web 生产：Streamable HTTP + Token 认证 + 反向代理（TLS 终止、来源校验）；
• 服务器默认绑定 127.0.0.1，对外服务需显式配置并配合防火墙 / 安全组；
• CORS 收敛为明确的客户端来源。

10.4 监控接入建议

• 将 /health 端点纳入负载均衡 / 监控系统探活；
• 利用 ux_monitor_database 的阈值参数（连接使用率、长查询秒数、缓存命中率、死元组比例、VACUUM 间隔）建立周期性巡检；
• 慢查询统计依赖 ux_stat_statements 扩展，需在实例参数中预加载并在目标库中启用后，get_slow_queries / get_stats 才能返回数据；
• 告警阈值初始建议：连接使用率 80%、长查询 60 秒、缓存命中率 95%、死元组比例 20%，再依据业务负载调整。

10.5 连接池与容量

• 默认连接池为 1–10 连接；多客户端共享同一 MCP Server（HTTP 传输）时，需结合数据库 max_connections 评估，避免与业务应用争抢连接配额；
• 每次工具调用后连接自动归还，长事务通过 transaction() 上下文管理器包裹，异常自动 rollback；
• 若出现连接耗尽类错误，优先排查是否有未归还的长会话或并发过高的 AI 客户端。

11. 故障排查

排查时可结合内置诊断工具：

"帮我诊断连接问题。"   → ux_debug_database（connection）

12. 常见问题（FAQ）

Q1：AI 客户端不支持 MCP，能用吗？ 不能直接使用。UXDB MCP Server 只通过 MCP 协议暴露能力，客户端需支持 MCP（stdio 或 Streamable HTTP / SSE 任一传输）。

Q2：一个 MCP Server 实例能连多个数据库吗？ 服务器通过连接字符串定位单一默认目标库；工具调用也支持显式传入连接串参数切换目标，但推荐一库一实例部署，便于权限与审计隔离。

Q3：AI 会不会误删数据？ 产品内置多层防护：DELETE 强制 WHERE 条件、参数化查询、标识符格式校验、Token 认证。但语义校验不能替代权限控制，生产环境务必遵循最小权限原则（见 10.1）。

Q4：查询结果会泄露敏感数据给 AI 吗？ 查询结果会进入 AI 对话上下文，这是 MCP 工具调用机制的固有特性。对敏感库表，应在数据库侧通过权限、行级安全（RLS）或脱敏视图控制 AI 账号可见范围。

Q5：stdio 和 Streamable HTTP 该选哪个？ 本地开发选 stdio（客户端自动管理进程，延迟最低）；需要多客户端共享、远程访问或 Web 集成时选 Streamable HTTP（需配置认证）。SSE 仅用于兼容旧客户端。

Q6：升级 MCP 协议版本有什么影响？ 服务器支持四个协议版本并自动协商，客户端无需固定版本。新客户端建议协商至 2026-07-28 以获得无状态 Streamable HTTP 的完整特性；注意 2026-07-28 不支持 SSE 传输。

Q7：生产环境能开 ux_execute_sql 吗？ 可以但需谨慎。该工具无操作类型限制，安全性完全取决于数据库账号权限。生产库若开放，建议配合只读账号、变更审批流程与操作审计使用。

13. 参考资料

• MCP 规范：Model Context Protocol（传输、生命周期、授权等规范章节）：https://modelcontextprotocol.io/
• MCP Authorization 规范与 RFC 9728（Protected Resource Metadata）：https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
• UXDB MCP Server 发行包：README 与 .env.example（以包内实际配置项为准）