UXDB MCP Server

概述

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

1.1 核心能力

1.2 关键技术指标

• 当前版本：1.1.0；
• 15 款数据库管理工具，覆盖 Schema、数据、查询、用户、索引、约束、触发器、函数、注释、分析、调试、监控、迁移等领域；
• 3 种传输方式：stdio（本地）、Streamable HTTP（推荐）、SSE（已弃用，仅保留旧客户端兼容）；
• 4 个 MCP 协议版本：2026-07-28、2025-11-25、2025-06-18、2024-11-05，支持自动协商；
• 2 个静态资源、2 个资源模板、3 个提示模板；
• 源码声明支持 Python ≥ 3.8；发行 wheel 内置平台相关的 pycouxdb 原生驱动，安装包必须与 Python ABI 和操作系统平台匹配。

1.3 与传统运维方式的对比

1.4 缩略语

2. 快速入门

2.1 前置条件

1. 一套可访问的 UXDB 数据库实例，并具备数据库账号（建议使用专用低权限账号，见 10.1）；
2. 与安装包匹配的 Python 和操作系统环境。项目源码声明 Python ≥ 3.8；当前仓库附带的驱动 wheel 面向 CPython 3.12 / Linux x86_64，使用现有构建产物时应采用该环境；
3. 一个支持 MCP 协议的 AI 客户端（IDE 插件、桌面 AI 助手、自研 Agent 等）。

2.2 安装

安装已构建的发行包：

python -m pip install uxdb_mcp_server-*.whl
uxdb-mcp-server --version

pycouxdb 已内置在发行 wheel 中，无需单独安装；其余 Python 依赖仍由 pip 从软件源安装。由于驱动包含原生扩展，wheel 不是跨平台纯 Python 包，出现 is not a supported wheel on this platform 时，应换用匹配 Python ABI 和平台的构建产物。

2.3 配置连接

连接字符串格式为 uxdb://用户名:密码@主机:端口/数据库名。主机省略时默认 localhost，端口默认 52025，数据库名默认 uxdb；可通过查询参数 sslmode 指定 SSL 模式，例如 ?sslmode=require。密码含 @、:、/ 等字符时需先进行 URL 编码。

连接字符串解析优先级为：

1. 工具调用参数 connectionString；
2. 启动参数 --connection-string（或程序初始化时传入的默认值）；
3. UXDB_CONNECTION_STRING 环境变量。

CLI 入口会自动加载当前环境中的 .env 文件，也可直接注入环境变量：

UXDB_CONNECTION_STRING=uxdb://username:password@127.0.0.1:52025/uxdb
UXDB_AUTH_TOKEN=replace-with-a-strong-token
SERVER_TRANSPORT=streamable_http
SERVER_HOST=127.0.0.1
SERVER_PORT=8080

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

2.4 启动服务

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

# Web 部署：Streamable HTTP 传输（推荐），生产环境应设置 Token
uxdb-mcp-server --transport streamable_http --host 127.0.0.1 --port 8080 --auth-token "replace-with-a-strong-token"

# SSE 传输（已弃用，仅用于旧客户端兼容）
uxdb-mcp-server --transport sse --host 127.0.0.1 --port 8080

--transport、--host、--port、--auth-token 的取值优先级为显式 CLI 参数 > 对应环境变量 > 硬编码默认值。完整参数可通过 uxdb-mcp-server --help 查看。

2.5 接入 AI 客户端

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

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

Streamable HTTP（Web 客户端）——先启动 HTTP 服务，再在客户端中配置端点 URL：

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

SSE 客户端使用 GET /sse 建立事件流，再通过服务端返回的 /messages?sessionId=... 端点发送 JSON-RPC 消息；新部署不要再选择 SSE。

各客户端的配置入口：

2.6 验证连通

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

"列出 public Schema 下有哪些表。"

AI 将调用 ux_manage_schema（operation=get_info）并返回结果。HTTP 健康检查端点无需认证：

curl http://127.0.0.1:8080/health

注意：HTTP /health 只反映服务进程及传输状态，不会实际连接数据库。如需数据库连通性检查，应调用 ux_debug_database（issue=connection）或读取 MCP 资源 uxdb://health；后者会执行 SELECT 1，失败时返回 degraded。

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_* 数据库管理工具                    │
├─────────────────────────────────────────────┤
│  安全与认证层                                 │
│  Bearer Token / Origin 校验 / 参数化查询 /     │
│  部分操作语义与标识符验证                      │
├─────────────────────────────────────────────┤
│  连接管理层（DatabaseConnection）             │
│  单例连接管理器 / 线程连接池 /                 │
│  事务 commit-rollback / 错误分类              │
└─────────────────────────────────────────────┘

4.2 逻辑组件职责

4.3 核心设计模式

• 工具抽象基类：所有工具继承 UXDBTool ABC，实现 name、description、inputSchema、execute()；还可选提供 title、icons、outputSchema、annotations 等 MCP 2026 元数据。
• 连接字符串解析链：_get_connection_string() 按优先级解析——工具调用参数显式传入 → 服务初始化默认值 → UXDB_CONNECTION_STRING 环境变量。
• 配置优先级链（CLI）：显式参数 > 环境变量 > 硬编码默认值。
• 单例连接管理：DatabaseConnection 采用双重检查锁单例和 ThreadedConnectionPool。当前工具通常在一次调用开始时 connect()、结束时 disconnect()，因此连接池按工具调用创建和销毁，并非跨调用常驻复用。
• 共享传输基类：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() 异步上下文管理器
└── 智能错误分类：认证失败 / 连接拒绝 / 权限不足 / 外键冲突 / 超时

连接与事务机制：

• connect() 创建 1–10 连接的池，并执行 SELECT 1 验证连通性；
• query() / execute() 每次从池中获取连接，操作结束后归还；
• 普通查询和执行使用 autocommit，操作结束后还原连接原有状态；
• transaction() 在正常退出时 commit，异常时 rollback，并归还连接；
• 工具执行完成后通常调用 disconnect() 关闭整个池。部署容量评估时需注意当前按调用建池、拆池的开销。

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 工具全景

各工具参数的权威定义以 tools/list 返回的 inputSchema 为准。connectionString 为通用可选参数；ux_analyze_database 使用 analysisType，ux_debug_database 使用 issue，其余带操作分派的工具使用 operation。

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）；
• 支持 %s 占位符与 parameters 参数化传值。

注意：该工具无操作类型限制，生产环境应通过数据库账号权限控制其影响面（见 10.1）。inputSchema 虽声明了 timeout，当前执行路径尚未应用该参数，不能依赖它限制 SQL 执行时间。

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 — 数据迁移

文件路径均相对于 MCP Server 所在主机解析，而非 AI 客户端主机。where 是直接拼入 SQL 的表达式，不是键值条件或参数化值，仅应传入受信任内容；导入、复制前的 TRUNCATE 操作具有破坏性，执行前必须确认目标表并备份。

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。客户端通过 GET /sse 建立连接，使用 sessionId 向 /messages 发送消息，会话默认空闲 300 秒过期、每 60 秒清理一次。

当前限制：SSE 路径在中间件中绕过 Bearer Token 校验，查询参数 auth_token 的读取逻辑也没有形成有效鉴权。因此不能把 --auth-token 视为 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 认证架构

Streamable HTTP 支持预共享 Bearer Token。通过 --auth-token 或 UXDB_AUTH_TOKEN 设置后，AuthConfig 自动启用认证，访问 MCP 端点需携带：

Authorization: Bearer <your-token>

认证失败返回 HTTP 401、JSON-RPC 错误码 -32001，并携带 WWW-Authenticate 响应头。/health、/.well-known/oauth-protected-resource 和 CORS OPTIONS 预检请求免认证。未设置 Token 时认证关闭，服务可被能够访问该端点的客户端直接调用。

stdio 不使用 HTTP Token；其安全边界由本机进程权限、客户端配置和数据库账号共同决定。SSE 当前未强制 Token 校验，限制见 7.3。

8.2 安全机制与边界

因此，“参数化查询 + Token”不能替代最小权限、变更审批、审计和数据备份。特别是 ux_execute_sql 与管理类工具可执行高权限操作，敏感生产环境应限制其可用账号和网络调用方。

8.3 Protected Resource Metadata

服务器在 /.well-known/oauth-protected-resource 返回 RFC 9728 风格的元数据。启用认证时响应为：

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

未启用认证时 scopes_supported 为空数组。该端点只提供预共享 Token 模式下的元数据，authorization_servers 当前为空，不代表已经实现完整 OAuth 2.0 授权流程。元数据中的 resource 固定为 /mcp，自定义 --path 时需在网关注意这一限制。

8.4 部署侧安全要求

生产部署 HTTP 传输时，除当前内置机制外，还需遵守以下要求：

1. 校验 Origin 头：服务默认仅接受本机 HTTP 来源；远程浏览器客户端应通过 --allowed-origins 显式配置精确来源；
2. 限制绑定地址：本地运行时绑定 127.0.0.1 而非 0.0.0.0，确需对外提供服务时应置于反向代理 / API 网关之后；
3. 强制认证与 TLS：对外暴露的 Streamable HTTP 端点必须设置高强度 Token，并由网关或代理提供 TLS、限流和访问审计；
4. 收紧 CORS：不要为方便调试长期使用 *，应明确列出客户端来源；
5. 网络隔离：MCP Server 与数据库实例之间建议部署于内网，仅开放必要端口；SSE 不应暴露到不可信网络；
6. 限制文件与 SQL 能力：迁移工具可读写服务端文件，原生 SQL 和表达式参数可影响数据库，应通过系统权限、目录隔离和数据库授权共同约束。

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 / get_permissions）审计账号与权限分配。

10.2 凭据管理

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

10.3 传输与暴露面

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

10.4 监控接入建议

• 将 /health 用于进程存活探针；它不会验证数据库，数据库可用性需通过 uxdb://health 资源或诊断工具检查；
• 利用 ux_monitor_database 的 alertThresholds 参数（连接使用率、长查询秒数、缓存命中率、死元组比例、VACUUM 间隔）建立周期性巡检；该工具只返回告警数据，不会主动推送告警；
• 慢查询统计依赖 ux_stat_statements 扩展，需在实例参数中预加载并在目标库中启用后，get_slow_queries / get_stats 才能返回数据；
• 告警阈值初始建议：连接使用率 80%、长查询 60 秒、缓存命中率 95%、死元组比例 20%，再依据业务负载调整。

10.5 连接池与容量

• 单个连接池配置为 1–10 连接；多客户端共享同一 MCP Server 时，需结合并发量和数据库 max_connections 评估，避免与业务应用争抢连接配额；
• 当前工具通常在每次调用时创建连接池，并在结束后关闭，高并发下还需关注建连延迟及同一单例连接管理器的竞争；
• 普通操作后连接自动归还，事务通过 transaction() 上下文管理器提交或回滚；
• 若出现连接耗尽或连接状态异常，优先检查并发客户端、数据库活跃会话及连接错误日志；当前没有 CLI 连接池上限配置项，不能通过 --port 等无关参数调整。

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、部分值参数化和部分标识符校验；UPDATE、DROP、TRUNCATE、原生 SQL 等仍可改变或删除数据。生产环境必须使用专用低权限账号，并配合变更审批、审计和备份，不能仅依赖工具校验或 Token。

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 吗？ 可以但需谨慎。该工具无操作类型限制，数据库账号权限是数据库侧的最终约束，同时还需控制网络调用方、执行变更审批与操作审计。只读场景应使用只读账号；写入与 DDL 场景应按业务范围单独授权。

13. 参考资料

• MCP 规范：Model Context Protocol（传输、生命周期、授权等规范章节）：https://modelcontextprotocol.io/
• MCP Authorization 规范与 RFC 9728（Protected Resource Metadata）：https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization