This is an automated email from the ASF dual-hosted git repository.
terrymanu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 72f436c6ea6 Remove obsolete documentation checks (#38743)
72f436c6ea6 is described below
commit 72f436c6ea6637fb9f8648265c62c745041b61a0
Author: Liang Zhang <[email protected]>
AuthorDate: Thu May 28 14:03:20 2026 +0800
Remove obsolete documentation checks (#38743)
* Remove obsolete documentation checks
Remove the standalone docs/mcp design documents and the bootstrap
documentation string test that depended on them. README content is not
treated
as a unit-test contract.
Keep the machine-consumed MCP Registry metadata validation in mcp/registry
by
checking environment variable shape for required, format, and secret fields.
* Remove obsolete documentation checks
Remove the standalone docs/mcp design documents and the bootstrap
documentation string test that depended on them. README content is not
treated
as a unit-test contract.
Keep the machine-consumed MCP Registry metadata validation in mcp/registry
by
checking environment variable shape for required, format, and secret fields.
* Remove obsolete documentation checks
Remove the standalone docs/mcp design documents and the bootstrap
documentation string test that depended on them. README content is not
treated
as a unit-test contract.
Keep the machine-consumed MCP Registry metadata validation in mcp/registry
by
checking environment variable shape for required, format, and secret fields.
---
docs/mcp/ShardingSphere-MCP-Detailed-Design.md | 699 -----------------
docs/mcp/ShardingSphere-MCP-PRD.md | 562 --------------
docs/mcp/ShardingSphere-MCP-Technical-Design.md | 854 ---------------------
.../bootstrap/MCPDocumentationContractTest.java | 120 ---
.../mcp/registry/MCPRegistryMetadataCommand.java | 13 +-
.../registry/MCPRegistryMetadataCommandTest.java | 37 +
6 files changed, 47 insertions(+), 2238 deletions(-)
diff --git a/docs/mcp/ShardingSphere-MCP-Detailed-Design.md
b/docs/mcp/ShardingSphere-MCP-Detailed-Design.md
deleted file mode 100644
index e660e464e53..00000000000
--- a/docs/mcp/ShardingSphere-MCP-Detailed-Design.md
+++ /dev/null
@@ -1,699 +0,0 @@
-# ShardingSphere MCP 详细设计说明书
-
-> 状态说明：本文档保留早期详细设计背景，不是当前 MCP public surface 契约。
-> 当前契约以 `shardingsphere://capabilities`、descriptor、`mcp/README.md` 和
`mcp/README_ZH.md` 为准。
-> 不要从本文档推导 `list_databases`、`describe_table` 等早期工具矩阵。
-> 当前可提交范围是 MCP V1 runtime readiness，不是完整 ShardingSphere governance
administration surface。
-
-## 1. 文档信息
-- 文档名称：ShardingSphere MCP 详细设计说明书
-- 文档版本：最终版
-- 文档类型：Detailed Design
-- 状态：可进入编码实现
-- 适用范围：ShardingSphere MCP V1
-
-## 2. 文档目标
-- 本文档用于将前面的 PRD 和技术设计方案落到实现级别。
- 目标是让 MCP 子系统能够直接进入开发，避免在实现过程中因为模块结构、协议契约、测试落位或构建链不明确而返工。
-- 本文档重点回答：
- - 代码模块如何组织
- - Maven / 模块 / JDK 21 子链路如何落地
- - MCP Streamable HTTP 如何实现
- - Session / transaction / savepoint 如何维护
- - capability / transaction matrix 如何建模
- - 配置如何组织
- - 单测、集成测试、E2E 如何落地
- - distribution 如何发布
-
-## 3. 已知输入与约束
-
-### 3.1 仓库现状
-- 当前仓库结构与基础约束如下：
- - 根工程模块链见 `pom.xml`（line 33）
- - 根工程 Java 基线为 8，`pom.xml`（line 55）
- - 根工程当前 Jackson 版本为 2.16.1，`pom.xml`（line 93）
- - 根 distribution 聚合结构见 `distribution/pom.xml`（line 30）
- - 根 test 聚合结构见 `test/pom.xml`（line 30）
- - `test/e2e` 聚合结构见 `test/e2e/pom.xml`（line 30）
-
-### 3.2 协议与运行时约束
-- 截至 2026-03-21，当前实现与协议基线如下：
- - MCP 当前标准 HTTP transport 为 Streamable HTTP
- - 当前协议版本基线为 `2025-11-25`
- - 仓库内实现采用 JDK 21 编译的自管 runtime
- - 远程 HTTP listener 由 `mcp/bootstrap` 局部引入的 embedded Tomcat 与 MCP Java SDK
servlet transport 承载
- - SDK 侧 JSON 绑定继续服从根工程 Jackson `2.16.1`
-- 来源：
- - 本仓库实现
- - MCP Transports 2025-11-25
-
-### 3.3 当前设计边界
-- 本说明书固定以下前提：
- - MCP 放在主仓库内
- - 代码模块位于根目录 `mcp/`
- - 发布模块位于根目录 `distribution/mcp`
- - E2E 模块位于 `test/e2e/mcp`
- - 不引入 Spring AI
- - 不推动全仓升级 JDK 21
- - 不实现分布式会话存储
- - 不实现事务态无损 failover
-
-## 4. 总体实现结论
-- V1 的最终实现结构如下：
-
-```text
-shardingsphere
-├── mcp
-│ ├── pom.xml
-│ ├── core
-│ └── bootstrap
-├── distribution
-│ └── mcp
-├── test
-│ └── e2e
-│ └── mcp
-└── pom.xml
-```
-
-- 三条子链路职责分别为：
- - `mcp`
- - 实现 MCP 运行时代码
- - `distribution/mcp`
- - 产出 `shardingsphere-mcp-distribution`
- - `test/e2e/mcp`
- - 承担 MCP 端到端验证
-- 这三条链路直接进入常规 Maven reactor 模块，不再通过独立 `mcp` profile 挂载。
-
-## 5. Maven 与模块落地设计
-
-### 5.1 artifact 命名
-- 建议固定为：
- - `shardingsphere-mcp`
- - `shardingsphere-mcp-core`
- - `shardingsphere-mcp-bootstrap`
- - `shardingsphere-mcp-distribution`
- - `shardingsphere-test-e2e-mcp`
-
-### 5.2 parent 关系
-- 建议：
- - `mcp/pom.xml`
- - `parent`：`org.apache.shardingsphere:shardingsphere`
- - `packaging`：`pom`
- - `modules`：
- - `features`
- - `core`
- - `bootstrap`
- - `distribution/mcp/pom.xml`
- - `parent`：`org.apache.shardingsphere:shardingsphere-distribution`
- - `packaging`：`pom`
- - `test/e2e/mcp/pom.xml`
- - `parent`：`org.apache.shardingsphere:shardingsphere-test-e2e`
- - `packaging`：`jar`
-- 这样可以同时保证：
- - 版本与主仓库统一
- - distribution 与 test 的聚合逻辑一致
- - 模块边界清晰
- - 测试夹具按模块本地收敛，避免额外 reactor 模块
-
-### 5.3 模块接入方式
-- 这是整个实现里最关键的结构性设计。
-
-#### 根 `pom.xml`
-- 在默认 `<modules>` 内引入 `<module>mcp</module>`
-
-#### `distribution/pom.xml`
-- 在默认 `<modules>` 内引入 `<module>mcp</module>`
-
-#### `test/e2e/pom.xml`
-- 在默认 `<modules>` 内引入 `<module>mcp</module>`
-
-#### 最终效果
-- 默认构建：包含 MCP
-- MCP 构建：直接走常规 Maven reactor
-- 这样可以保持：
- - `mcp`、`distribution/mcp`、`test/e2e/mcp` 与 JDBC、Proxy、agent 一致
- - 打包与 E2E 不依赖额外 profile
- - Java 21 设置仍局部收敛在 MCP 子模块
-
-### 5.4 JDK 21 隔离策略
-- 建议：
- - `mcp/pom.xml` 内局部声明 `maven.compiler.release=21`
- - 使用 Maven Toolchains
- - JDK 21 子链路 CI lane 固定 JDK 21
-- 禁止：
- - 将 Java 21 相关设置扩散到根工程统一配置
- - 将额外 HTTP 容器或 MCP SDK 依赖写入根工程统一依赖管理
- - 让 MCP Java SDK 类型进入 `mcp/core`
-
-## 6. 包结构设计
-
-### 6.1 `mcp/core`
-- 推荐根包：
- - `org.apache.shardingsphere.mcp`
-- 推荐子包：
- - `protocol`
- - `resource`
- - `tool`
- - `capability`
- - `session`
- - `metadata`
- - `execute`
- - `trace`
- - `config`
- - `common`
-- 说明：
- - `protocol`
- - 协议对象与 DTO
- - transport-neutral payload builder
- - `resource`
- - resource 映射、读取与 URI 解析
- - `tool`
- - tool catalog、参数归一化与 dispatcher
- - `capability`
- - capability matrix / assembler
- - `session`
- - session / tx / savepoint 管理
- - transport-independent session lifecycle cleanup
- - `metadata`
- - metadata discovery facade
- - JDBC metadata discovery and runtime configuration
- - `execute`
- - SQL tool facade
- - `DatabaseRuntime` assembly and JDBC-backed runtime context factory
- - `trace`
- - SQL execution trace facade
- - `config`
- - MCP 内部配置模型
- - `common`
- - 公共常量、枚举、异常
-
-### 6.2 `mcp/bootstrap`
-- 推荐子包：
- - `transport.http`
- - `transport.stdio`
- - `server`
- - `wiring`
- - `config`
- - `lifecycle`
-- 设计原则：
- - core 不依赖 bootstrap
- - bootstrap 依赖 core
- - transport 细节不进入 core
- - bootstrap 只保留 MCP Java SDK / Tomcat / servlet / stdio adapter
- - tool input schema 与 SDK `Tool` / `Resource` 注册留在 bootstrap
-
-## 7. 协议与 Transport 详细设计
-
-### 7.1 HTTP transport 固定为 Streamable HTTP
-- V1 的 HTTP transport 固定为：
- - MCP Streamable HTTP
- - 协议版本基线：`2025-11-25`
-- 这意味着不再使用模糊表述“HTTP 模式”，而是明确遵守当前 MCP 标准 transport。
-- transport implementation seam 上，routing、SDK session 与
- `DELETE` 基础语义优先复用官方 servlet provider；ShardingSphere 只补协议头、
- follow-up contract、managed session cleanup、本地运行边界策略、
- 内部 Origin 校验与必要兼容层。
-
-### 7.2 MCP endpoint
-- V1 使用单一 MCP endpoint，例如：
- - `/mcp`
-- 该 endpoint 必须支持：
- - `POST`
- - `GET`
- - `DELETE`
-
-#### `POST /mcp`
-- 用途：
- - 初始化 HTTP session
- - 处理 session 绑定后的 JSON-RPC follow-up 请求
-- 规则：
- - 缺少 `MCP-Session-Id` 时创建新会话
- - 初始化成功后返回 `MCP-Session-Id` 与协商后的 `MCP-Protocol-Version`
- - 带 `MCP-Session-Id` 的 follow-up `POST` 负责承载
`tools/list`、`tools/call`、`resources/list` 与 `resources/read`
- - follow-up `POST` 必须先完成 transport admission check，
- 再完成协议版本与 session 校验，最后进入 tool / resource dispatch
-
-#### `GET /mcp`
-- 用途：
- - 满足 Streamable HTTP 规范
- - 支持服务端到客户端的 SSE 流
-- V1 说明：
- - MCP 业务功能本身不依赖 server push
- - 但服务端仍提供 GET 能力，以满足 transport 规范与 future-proofing
-
-#### `DELETE /mcp`
-- 用途：
- - 客户端显式终止 MCP session
-- V1 设计选择：
- - 实现 DELETE
- - 不使用 405 作为默认行为
-- 原因：
- - 本设计是 stateful session 模型
- - 显式关闭会话有利于及时释放事务与会话资源
-
-### 7.3 会话头与版本头
-- V1 固定使用当前协议定义的头：
- - `MCP-Session-Id`
- - `MCP-Protocol-Version`
-- 规则：
- 1. 初始化成功后，服务端在 `InitializeResult` 对应 HTTP 响应头中返回 `MCP-Session-Id`
- 2. 后续 HTTP 请求必须带 `MCP-Session-Id`
- 3. 后续 HTTP 请求应带 `MCP-Protocol-Version`
- 4. 若请求缺少必须的 session id，返回 `400 Bad Request`
- 5. 若 session 已终止或不存在，返回 `404 Not Found`
-
-### 7.4 协议版本处理
-- V1 采用如下策略：
- - 服务端协议基线固定为 `2025-11-25`
- - 初始化阶段记录协商结果
- - 后续请求：
- - 若 header 存在，必须与会话协商版本一致
- - 若 header 缺失但 session 存在，服务端允许回退到会话协商版本并记录警告日志
- - 若既无 header 又无 session，上游请求视为不合法并返回 `400`
-- 这样既符合协议，也避免过度脆弱。
-
-### 7.5 本地模式运行边界
-- 根据 transport 规范，V1 要求：
- - 本地模式默认仅绑定 `127.0.0.1`
- - 若本地模式请求显式携带 `Origin`，服务端校验其 host 必须仍为 loopback / localhost
- - 当前内置 HTTP runtime 不提供授权
- - 远程模式仍应由外部网关、反向代理或网络边界提供保护
-- 上述 `Origin` 校验由 ShardingSphere 独立本地策略类在 servlet 前置阶段执行；
- delegate 不再重复执行同一规则。ShardingSphere 继续保留零损失兼容输出与
- session 语义 glue。
-- 以上约束用于限定本地运行边界，与 MCP session 语义分层处理。
-
-## 8. 会话、事务与 Savepoint 详细设计
-
-### 8.1 Session 状态
-- 定义 Session 状态：
- - `NEW`
- - `ACTIVE`
- - `IN_TRANSACTION`
- - `CLOSED`
- - `EXPIRED`
-
-### 8.2 Transaction 状态
-- 定义事务状态：
- - `NONE`
- - `ACTIVE`
- - `ROLLBACK_ONLY`
- - `FINISHED`
-
-### 8.3 Savepoint 前置条件
-- 只有同时满足以下条件，savepoint 才可用：
- - 当前 database capability `supportsSavepoint = true`
- - 当前事务状态为 `ACTIVE`
-- 否则：
- - 返回 `unsupported`
- - 或 `transaction_state_error`
-
-### 8.4 状态流转
-```mermaid
-stateDiagram-v2
- [*] --> NEW
- NEW --> ACTIVE: Initialize Success
- ACTIVE --> IN_TRANSACTION: BEGIN / START TRANSACTION
- IN_TRANSACTION --> ACTIVE: COMMIT / ROLLBACK
- ACTIVE --> CLOSED: DELETE / Session Close
- IN_TRANSACTION --> CLOSED: Disconnect with rollback
- ACTIVE --> EXPIRED: Idle timeout
- IN_TRANSACTION --> EXPIRED: Timeout with rollback
-```
-
-### 8.5 Timeout 设计
-- 分两类：
- - session idle timeout
- - transaction timeout
-- 规则：
- - session idle timeout 到期：
- - session 转为 `EXPIRED`
- - transaction timeout 到期：
- - 当前事务自动回滚
- - 会话转为 `ACTIVE` 或 `EXPIRED`
- - 后续针对旧事务上下文的操作返回 `transaction_state_error`
-
-### 8.6 故障语义
-- V1 采用：
- - sticky session
- - 本地内存 session store
-- 因此，节点故障语义必须明确：
- - 节点故障或重启时，本节点上的 session 丢失
- - 活动事务不做跨节点恢复
- - 未提交事务视为失败并回滚
- - 客户端需重新初始化 session
-- V1 不支持：
- - distributed session store
- - 无粘性路由事务恢复
- - savepoint 栈的跨节点恢复
-
-## 9. capability / transaction matrix 详细设计
-
-### 9.1 数据来源
-
-#### capability 来源
-- 由三层叠加得到：
- 1. 静态矩阵
- 2. 运行时 metadata
- 3. 部署时覆盖
-
-### 9.2 transaction matrix 存储方式
-- V1 推荐：
- - Java 强类型注册表
-- 不优先用 YAML / JSON 作为首版事实源。
-- 理由：
- - 更稳定
- - 更容易测试
- - 不容易被错误配置污染
- - 更适合作为 capability 默认事实源
-
-### 9.3 transaction matrix 字段
-- 至少包含：
- - `databaseType`
- - `supportsTransactionControl`
- - `supportsSavepoint`
- - `supportedObjectTypes`
- - `supportedStatementClasses`
- - `supportsExplainAnalyze`
-
-### 9.4 capability 组装顺序
-- 固定组装顺序：
- 1. 读取静态矩阵
- 2. 读取运行时 metadata
- 3. 应用部署时覆盖项
- 4. 生成数据库级 capability
-
-## 10. SQL tool 详细设计
-
-> 本节保留早期 `execute_query` 术语。
-> 当前 MCP public surface 将读查询与变更执行拆分为 `database_gateway_execute_query` 和
`database_gateway_execute_update`。
-
-### 10.1 职责
-- 当前 SQL tool facade 负责：
- - 单语句校验
- - statement class 归类
- - request-level schema semantics 解释
- - capability 校验
- - session / transaction 校验
- - 调用 ShardingSphere parse / route / execute
- - 统一结果映射
- - 统一错误映射
- - SQL execution trace 输出
-
-### 10.2 执行阶段
-- 内部固定为 7 个阶段：
- 1. request validation
- 2. statement classification
- 3. session validation
- 4. capability validation
- 5. kernel execution
- 6. result / error mapping
-
-### 10.2A `database` / `schema` 边界
-- `database` 是当前 SQL tools 的唯一强执行边界。
-- `schema` 是可选 namespace hint，用于表达未限定对象名的目标命名空间意图。
-- 当数据库级 capability `schema_execution_semantics = fixed_to_database` 时，
- request-level `schema` 不被承诺为独立执行命名空间切换器。
-- 当数据库级 capability `schema_execution_semantics = best_effort` 时，
- runtime 可以尝试应用 request-level `schema`，但不对外宣传 strict guarantee。
-- SQL 自身显式限定名优先于 request-level `schema`。
-
-### 10.3 Statement Class
-- 统一按以下维度治理：
- - `select`
- - `dml`
- - `ddl`
- - `dcl`
- - `transaction_control`
- - `savepoint`
- - `explain_analyze`
-- `WITH` 只表示 CTE 写法，不单独形成产品 statement class。
-- `statement class` 用于 capability、SQL execution trace 和执行分支。
-- `statement type` 用于表达更具体的用户可读动作，如 `SELECT`、`UPDATE`、`MERGE`。
-
-### 10.4 统一结果
-- 仅允许三类：
- - `result_set`
- - `update_count`
- - `statement_ack`
-- 每个成功结果都携带：
- - `statement_class`
- - `statement_type`
- - `status`
- - `truncated`
-- `result_kind` 只表达返回形状，不表达副作用等级。
-- data-modifying CTE 可被表达为 `statement_class = dml` 且 `result_kind =
result_set`。
-
-### 10.5 错误映射
-- 底层异常不得直接透传。
-- 统一映射为：
- - `invalid_request`
- - `not_found`
- - `unsupported`
- - `conflict`
- - `unavailable`
- - `transaction_state_error`
- - `query_failed`
-
-## 11. 配置设计
-
-### 11.1 配置文件
-- distribution 建议提供：
- - `conf/mcp-http.yaml`
- - `conf/mcp-stdio.yaml`
- - `conf/logback.xml`
-
-### 11.2 `mcp-http.yaml` 分层
-- 建议包含以下一级段：
- - `transport`
- - `runtimeDatabases`
-
-### 11.3 配置职责
-
-#### `transport`
-- `type`
-- `http.bindHost`
-- `http.port`
-- `http.endpointPath`
-- `type` 是唯一 transport 选择器，取值为 `STREAMABLE_HTTP` 或 `STDIO`
-- `http` 子配置仅在 `type: STREAMABLE_HTTP` 时有效；`type: STDIO` 时不携带 HTTP listener 字段
-- HTTP listener 字段可省略，默认值为 `127.0.0.1`、`18088` 与 `/mcp`
-- HTTP transport 固定使用 MCP `2025-11-25` 协议基线，不作为外部配置项暴露
-- distribution 提供 HTTP 与 STDIO 两份显式配置模板；STDIO 仍主要用于本地测试与进程内联调，不作为额外交互式文本 Shell
-
-#### `runtimeDatabases`
-- canonical logical database mapping
- - `databaseType`
- - `jdbcUrl`
- - `username`
- - `password`
- - `driverClassName`
-- schema 采用 strict mapping
- - unknown key 直接报错
- - `runtime.*` alias 不再作为专门迁移分支保留
- - per-database capability booleans 不再接受为 operator-facing 配置
-- distribution 默认配置提供一段 demo JDBC runtime，确保发行包第一次启动即可验证非空 metadata
与真实执行链路；真实部署需替换为目标环境配置
-
-## 12. 运行边界与 SQL Execution Trace 详细设计
-
-### 12.1 运行边界
-- V1 内置 runtime 聚焦 session 协商、会话状态维护与运行边界校验。
-- follow-up production runtime 路径要求通过 `runtimeDatabases` 显式装配真实 metadata
与执行适配，不再允许空 runtime 作为成功启动兜底。
-- HTTP 端点如需对外暴露，应放在受信网络、上游网关、反向代理或其他网络边界之后。
-
-### 12.2 SQL execution trace 模型
-- V1 只生成当前 SQL 执行路径的本地 trace 摘要，不承诺持久化合规日志或全量 MCP 活动记录。
-- 统一输出：
- - sessionId
- - database
- - statementClass
- - statementDigest
- - successOrFailure
- - errorCode
- - transactionMarker
- - timestamp
-
-## 13. 测试设计
-
-### 13.1 测试分层
-- V1 测试分 4 层：
- 1. 单元测试
- 2. 模块集成测试
- 3. 协议联调测试
- 4. E2E 测试
-
-### 13.2 单元测试重点
-- 重点覆盖：
- - capability assembler
- - transaction matrix registry
- - session manager
- - SQL tool facade
- - error mapper
-
-### 13.3 模块集成测试重点
-- 重点覆盖：
- - `/mcp` endpoint 行为
- - `MCP-Protocol-Version`
- - `MCP-Session-Id`
- - `transaction/savepoint` 状态流转
- - `DELETE /mcp`
-
-### 13.4 E2E 模块落位
-- 建议新增：
- - `test/e2e/mcp`
-- `artifactId`：
- - `shardingsphere-test-e2e-mcp`
-- `parent`：
- - `shardingsphere-test-e2e`
-- 不放在：
- - `test/e2e/operation/mcp`
-- 原因：
- - MCP 是新的接入面，不是 operation 子类型
- - `test/e2e/pom.xml` 的顶层聚合更适合把 MCP 作为一级测试模块承载
-
-### 13.5 E2E 模块接入约束
-- 和代码、distribution 一样，`test/e2e/mcp` 直接进入默认 `test/e2e` 模块链。
-- 也就是说：
- - `test/e2e/pom.xml` 默认 `<modules>` 直接加入 `<module>mcp</module>`
- - JDK 21 要求通过 MCP 子模块局部配置和 JDK 21 子链路 CI 兜底
-- 这样 E2E 与代码、distribution 的聚合方式保持一致，不再依赖额外 profile。
-
-### 13.6 E2E 依赖
-- `test/e2e/mcp` 直接依赖建议包括：
- - `shardingsphere-mcp-core`
- - `shardingsphere-mcp-bootstrap`
- - `shardingsphere-test-e2e-env`
- - `shardingsphere-test-e2e-fixture`
-- 必要时补充：
- - HTTP 客户端依赖
- - 数据库驱动依赖
-
-### 13.7 E2E 最小覆盖矩阵
-- A. 事务 + savepoint 组
- - MySQL
- - PostgreSQL
- - openGauss
-- B. 事务但不支持 savepoint 组
- - Doris
- - Presto
-- C. 不支持事务控制组
- - Hive
- - ClickHouse
-- D. optional object 组
- - 一个支持 index
- - 一个不支持 index
-- E. capability 组
- - capability 与矩阵一致
-
-### 13.8 历史 E2E 最小冒烟场景（非当前门禁）
-
-> 本节保留早期 tool matrix。
-> 当前 submit-ready E2E 门禁以
`tools/list`、`resources/read`、`database_gateway_search_metadata`、SQL tool
pair、workflow tools、HTTP 和 STDIO runtime 为准。
-- 至少固定以下 12 个场景：
- 1. 服务级 capability
- 2. 数据库级 capability
- 3. `list_databases`
- 4. `list_schemas`
- 5. `list_tables / search_metadata`
- 6. `describe_table`
- 7. `execute_query(SELECT)`
- 8. `execute_query(DML)`
- 9. `BEGIN / COMMIT / ROLLBACK`
- 10. `SAVEPOINT` 成功场景
- 11. `SAVEPOINT unsupported` 场景
- 12. `DELETE close / invalid session` 场景
-
-## 14. distribution 详细设计
-
-### 14.1 `distribution/mcp` 依赖关系
-- `distribution/mcp` 直接依赖：
- - `shardingsphere-mcp-bootstrap`
-- 运行时依赖分类建议参考 `distribution/proxy` 与 `distribution/jdbc`：
- - mode repositories
- - parser / runtime dialect support
- - JDBC drivers
- - logging
-
-### 14.2 目录结构
-- 建议产出：
-
-```text
-apache-shardingsphere-mcp-<version>/
-├── bin/
-├── conf/
-├── lib/
-├── logs/
-└── LICENSE / NOTICE / README.md
-```
-
-### 14.3 启动脚本
-- 建议至少提供：
- - `bin/start.sh`
-
-### 14.4 容器化
-- 当前 V1 建议提供：
- - Dockerfile
- - 配置挂载约定
-- 健康检查可作为后续运行时增强项追加，不阻塞当前打包与 smoke。
-
-## 15. 实施顺序
-- 建议实现顺序固定如下：
- 1. Maven / 模块 / toolchain 结构
- 2. `mcp/core` 公共模型与 transaction matrix
- 3. `mcp/core` 的 capability / error / session
- 4. `mcp/bootstrap` 的 HTTP / STDIO transport
- 5. `/mcp` 的 Streamable HTTP endpoint
- 6. SQL tool pair 与 metadata discovery
- 7. `distribution/mcp`
- 8. 单元测试
- 9. 模块集成测试
- 10. `test/e2e/mcp`
-
-## 16. 开工前检查清单
-- 开始写代码前必须全部满足：
- - `mcp` 与 `distribution/mcp` 的模块接入方式已定
- - `test/e2e/mcp` 的模块落位已定
- - JDK 21 Toolchains 已定
- - Streamable HTTP 版本已固定为 `2025-11-25`
- - `MCP-Session-Id / MCP-Protocol-Version` 行为已定
- - `DELETE /mcp` 会话关闭行为已定
- - SDK provider 与 ShardingSphere glue 的职责边界已定
- - transaction matrix 存储方式已定
- - capability / SQL tool 输入输出边界已定
-
-### 16.1 AI-Friendly 增量开工前重新取证
-
-AI-Friendly 轻量体验增量进入实现前，应先从当前代码重新确认以下事实。
-这些是实现取证点，不是需要反复向需求方澄清的问题。
-
-- 当前 MCP public surface：以 descriptor、capabilities 和 README 为准核对
tool、resource、prompt、completion 与 navigation。
-- `execute_update` preview 返回结构：先检查现有 handler 和测试，再决定补充字段或统一命名。
-- workflow preview guidance：确认 `apply_workflow` 是否能与 SQL preview 复用同一套轻量
`next_actions` 词汇。
-- 错误恢复现状：检查 missing database、missing execution mode、wrong SQL tool、unknown
tool/resource 和旧 `plan_id`。
-- descriptor lint 落点：优先复用 descriptor loader 或 support 层测试，不新增复杂 lint 框架。
-- capabilities contract test：只验证 section 和 shape，不锁定大段运行时 snapshot。
-- 历史文档状态：只标注会误导当前实现契约的旧设计说明，不批量重写历史文档。
-
-### 16.2 AI-Friendly 增量不重新打开的决策
-
-除非需求方明确改变范围，以下决策不重新打开。
-
-- 不切换或创建 git 分支。
-- 不引入 heavy planner、vector memory、跨会话长期记忆或完整 auth platform。
-- 保持 resource-first 作为当前 MCP surface 的主要发现路径。
-- 先完成 P0/P1 的模型困惑和操作风险收敛，再处理 P2 便利性增强。
-- `mcp/README.md` 与 `mcp/README_ZH.md` 的当前 public surface 说明同步。
-- 真实 LLM E2E 保持 opt-in，不进入默认 CI 门禁。
-
-## 17. 最终结论
-- 这份详细设计说明书的作用，是把前面的 PRD 与技术方案真正推进到“可以开工写代码”的状态。
-- 现在已经明确并固定了：
- - 仓库结构
- - Maven / 模块结构
- - JDK 21 隔离策略
- - Streamable HTTP 协议基线
- - session / transaction / savepoint 模型
- - capability / matrix 设计
- - configuration 结构
- - testing / E2E 落地方式
- - distribution 落地方式
diff --git a/docs/mcp/ShardingSphere-MCP-PRD.md
b/docs/mcp/ShardingSphere-MCP-PRD.md
deleted file mode 100644
index 8fd1eda91bf..00000000000
--- a/docs/mcp/ShardingSphere-MCP-PRD.md
+++ /dev/null
@@ -1,562 +0,0 @@
-# ShardingSphere MCP PRD
-
-> 状态说明：本文档保留早期 PRD 背景，不是当前 MCP public surface 契约。
-> 当前契约以 `shardingsphere://capabilities`、descriptor、`mcp/README.md` 和
`mcp/README_ZH.md` 为准。
-> 不要从本文档推导 `list_*`、`describe_*` 等早期工具矩阵。
-> 当前可提交范围是 MCP V1 runtime readiness：metadata discovery、safe SQL、encrypt/mask
workflow、HTTP/STDIO runtime、distribution 与 E2E infrastructure。
-
-## 文档信息
-- 产品名称：ShardingSphere MCP
-- 文档版本：定稿候选版
-- 文档类型：PRD
-- 当前阶段：需求确认版
-
-## 1. 产品概述
-- ShardingSphere MCP 是面向大模型、Agent 和 AI 平台的统一数据库 MCP 入口。
-- 它对上提供统一的数据库访问与 SQL 执行公共面。
-- 它对下屏蔽多种数据库在对象暴露、SQL 执行、结果模型、错误语义和治理边界上的差异。
-
-### 一句话定义
-- 上层只需接入一个 ShardingSphere MCP 服务，即可用一致方式访问多种数据库的结构信息、可用对象范围和 SQL 执行能力。
-
-## 2. 背景与问题
-- 当前数据库接入主要存在以下问题：
-- 不同数据库 MCP 的资源命名、工具定义、返回结构和能力边界不一致。
-- 上层 Agent 需要分别适配多种数据库，接入成本高。
-- 企业希望统一数据库访问的对象暴露、SQL execution trace、超时和结果限制。
-- 即使同样是列库、查结构、执行 SQL，不同数据库的行为、错误和结果表达也不一致。
-- ShardingSphere 具备统一接入多种数据库的能力，因此适合作为统一 MCP 出口。
-
-## 3. 产品目标
-- 统一不同数据库的 MCP 接入方式。
-- 统一数据库对象发现与元数据读取能力。
-- 统一 SQL 执行工具和执行结果模型。
-- 统一错误语义、运行边界和事务语义。
-- 统一能力声明表达。
-- 降低 Agent 对多种数据库 MCP 的适配成本。
-- 让结构变化和 DCL 变化能在分钟级反映到 MCP 出口。
-
-## 4. 非目标
-- 不负责自然语言理解、SQL 自动生成和问答体验。
-- 不抹平所有数据库专有对象和专有语义。
-- 不暴露 ShardingSphere 专有扩展面作为核心公共面。
-- 不兼容第三方数据库 MCP Server 的命名和行为细节。
-- 不支持 `USE`、`SET`、`COPY`、`LOAD`、`CALL`。
-- 不支持各数据库专有高风险元命令。
-
-## 5. 版本范围
-
-### V1 正式支持数据库
-- MySQL
-- PostgreSQL
-- openGauss
-- SQL Server
-- MariaDB
-- Oracle
-- ClickHouse
-- Doris
-- Hive
-- Presto
-- Firebird
-- H2
-
-### V1 不纳入正式验收范围
-- 其他类 SQL 或测试型方言
-
-## 6. 目标用户
-- 大模型 Agent 开发者
-- IDE / CLI 智能助手接入方
-- 企业内部 AI 平台
-- 数据分析 Agent
-- 数据问答 Agent
-- 运维排障 Agent
-- 需要统一接入多种数据库的平台团队
-
-## 7. 典型使用场景
-- Agent 统一发现多个数据库中的可访问对象。
-- Agent 统一读取表结构、字段、视图等元数据。
-- Agent 在不同数据库下使用同一套工具执行 SQL。
-- 平台统一承接 SQL execution trace、超时和结果限制要求。
-- 数据库结构变化后，Agent 在分钟级看到 MCP 资源更新。
-- MCP 会话内通过事务控制语句管理事务边界。
-
-## 8. 产品原则
-- 只做公共面，不做扩展面。
-- 先统一高频对象和高频工具，再扩展长尾能力。
-- 统一调用语义优先于统一底层实现方式。
-- 能统一的能力必须稳定一致，不能统一的能力必须明确标识。
-- 安全保守优先于能力激进。
-- 非 loopback HTTP 暴露必须具备最小接入门槛；
- 当前内置 HTTP runtime 不提供授权，必须由可信网络、网关或反向代理提供接入控制。
-- 所有 V1 公共对象必须有正式承载路径。
-- 所有 V1 正式支持数据库必须满足统一契约。
-- 对原生支持事务控制的数据库，V1 必须统一支持事务控制语义。
-- 对原生支持 `savepoint` 的数据库，V1 必须统一支持 `savepoint` 语义。
-- 对原生不支持事务控制或 `savepoint` 的数据库，必须通过 `capability` 明确声明不支持，并对相关语句统一返回
`unsupported`。
-- V1 不在 MCP runtime 内实现用户身份、角色和细粒度权限语义。
-
-## 9. 统一对象模型
-
-### 9.1 V1 核心统一对象
-- `database`
-- `schema`
-- `table`
-- `view`
-- `column`
-- `capability`
-
-### 9.2 V1 可选公共对象
-- `index`
-
-#### 说明
-- `index` 不是所有正式支持数据库的统一强制基线对象。
-- `index` 是否支持由数据库级 `capability` 的 `supported_object_types` 明确声明。
-
-### 9.3 V1 不统一对象
-- `materialized view`
-- `sequence`
-- `function / procedure`
-- `trigger`
-- `event`
-- `synonym`
-- 数据库专有对象
-
-## 10. 对象语义定义
-- `database`：MCP 对外暴露的一级访问目标，也是每次 SQL 执行必须显式指定的目标。
-- `schema`：`database` 内部命名空间；在当前 SQL tools 中只作为可选 namespace hint，不是第二个强执行边界。
-- `table / view`：通过 `(database, schema, name)` 唯一确定。
-- `column`：从属于某个表或视图。
-- `index`：从属于某个表，仅在当前 `database` 支持时暴露。
-- `capability`：描述服务级或数据库级能力边界的声明对象。
-
-### 统一约束
-- 每次 SQL 执行必须命中一个且仅一个 `database`。
-- V1 不支持跨 `database` SQL 执行。
-- 对没有独立 `schema` 概念的数据库，系统仍需暴露统一 `schema` 语义。
-- 对这类数据库，默认 `schema` 名称与 `database` 名称保持一致。
-- 对这类数据库，公共 `schema` 名称首先服务 MCP 统一 contract；
- 是否可作为独立执行命名空间切换由数据库级 capability 的 `schema_execution_semantics` 决定。
-- 本文中的 `database` 指 ShardingSphere MCP 对外暴露的逻辑数据库标识，不等同于底层物理数据库实例、存储单元或原生
`catalog`。
-
-## 11. V1 公共 Resources
-
-### 正式资源清单
-- `shardingsphere://capabilities`
-- `shardingsphere://databases`
-- `shardingsphere://databases/{database}`
-- `shardingsphere://databases/{database}/capabilities`
-- `shardingsphere://databases/{database}/schemas`
-- `shardingsphere://databases/{database}/schemas/{schema}`
-- `shardingsphere://databases/{database}/schemas/{schema}/tables`
-- `shardingsphere://databases/{database}/schemas/{schema}/views`
-- `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}`
--
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
--
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
-- `shardingsphere://databases/{database}/schemas/{schema}/views/{view}`
-- `shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns`
--
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
--
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
--
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
-
-### 资源原则
-- 资源只表达稳定、可读取、可理解的数据库结构和治理信息。
-- 凡列为 V1 公共对象者，必须在 `resources` 和 / 或 `tools` 中有正式承载路径。
-- 当当前 `database` 的 `supported_object_types` 不包含 `index` 时，`index` 相关
`resources` 统一返回 `unsupported`。
-
-## 12. 历史 V1 公共 Tools 设想（非当前契约）
-
-> 本节记录早期 PRD 工具拆分设想。当前 public tools 以 `mcp/README.md`、`mcp/README_ZH.md` 和
descriptors 中的 `database_gateway_*` 工具为准。
-
-### 正式工具清单
-- `list_databases`
-- `list_schemas`
-- `list_tables`
-- `list_views`
-- `list_columns`
-- `list_indexes`
-- `search_metadata`
-- `describe_table`
-- `describe_view`
-- `get_capabilities`
-- `execute_query`
-
-### 工具定义
-- `list_databases`
-- `list_schemas(database)`
-- `list_tables(database, schema, search?)`
-- `list_views(database, schema, search?)`
-- `list_columns(database, schema, object_type, object_name, search?)`
-- `list_indexes(database, schema, table, search?)`
-- `search_metadata(database?, schema?, query, object_types?)`
-- `describe_table(database, schema, table)`
-- `describe_view(database, schema, view)`
-- `get_capabilities(database?)`
-- `execute_query(database, schema?, sql, max_rows?, timeout_ms?)`
-
-### 补充定义
-- `object_type` 取值为 `table` 或 `view`。
-- `execute_query` 每次只允许执行单条 SQL，多语句统一返回 `invalid_request`。
-- `database` 是 `execute_query` 的唯一强边界。
-- `schema` 是可选 namespace hint，用于表达未限定对象名的目标命名空间意图。
-- SQL 已显式包含限定名时，SQL 自身限定关系优先于 request-level `schema`。
-
-#### `search_metadata` 返回项至少应包含
-- `database`
-- `schema`
-- `object_type`
-- `object_name`
-- `parent_object_type`
-- `parent_object_name`
-
-#### 额外约束
-- 对 `table / view`，父对象字段可为空。
-- 对 `column / index`，父对象字段必填。
-- `get_capabilities()` 返回服务级 `capability`。
-- `get_capabilities(database)` 返回数据库级 `capability`。
-- 当当前 `database` 不支持 `index` 时，`list_indexes` 统一返回 `unsupported`。
-
-## 13. 搜索、过滤与收窄
-
-### V1 必须支持
-- 列表查询支持关键字搜索。
-- 大结果通过 `truncated`、`total_count`、`returned_count` 和收窄提示表达。
-- 元数据搜索支持按对象类型过滤。
-- item-list 响应保留 application-level `has_more` 和 `continuation_mode` 字段；当响应支持
ShardingSphere application-level pagination 时才返回 `next_page_token`。
-- 上述 structured payload 字段不是 MCP list 方法的 `cursor` 或 `nextCursor`。
-- 不允许客户端通过完整枚举完成大型数据库结构发现。
-
-### `search_metadata.object_types` 正式支持
-- `database`
-- `schema`
-- `table`
-- `view`
-- `column`
-- `index`
-
-### 补充规则
-- `search_metadata` 在 `database` 省略时，表示在当前 runtime 暴露的所有 `database` 范围内搜索元数据。
-- 该行为不等同于跨 `database` SQL 执行。
-- 当 `schema` 被指定时，`database` 必须同时指定，否则返回 `invalid_request`。
-
-## 14. 历史 SQL 执行能力（非当前契约）
-
-> 本节使用早期 `execute_query` 术语。当前 public tools 使用
`database_gateway_execute_query` 与 `database_gateway_execute_update`。
-
-- SQL 执行通过早期 `execute_query` 设想统一暴露。
-- 每次 SQL 必须显式指定 `database`。
-- V1 不支持跨 `database` SQL 执行。
-- `schema` 不构成第二个强执行边界。
-- 同一 `database` 内的跨 `schema` SQL 可在数据库能力允许时支持。
-- 不支持时必须明确返回 `unsupported`。
-- 事务一旦开始，当前事务绑定单一 `database`。
-- 事务存续期间若 SQL tool 指定其他 `database`，统一返回 `conflict`。
-
-## 15. V1 允许的 SQL 类型
-
-### 允许
-- `SELECT`
-- `WITH ... SELECT`
-- `INSERT`
-- `UPDATE`
-- `DELETE`
-- `MERGE`
-- `TRUNCATE`
-- `CREATE`
-- `ALTER`
-- `DROP`
-- `GRANT`
-- `REVOKE`
-- `EXPLAIN ANALYZE`
-- `BEGIN`
-- `START TRANSACTION`
-- `COMMIT`
-- `ROLLBACK`
-- `SAVEPOINT`
-- `ROLLBACK TO SAVEPOINT`
-- `RELEASE SAVEPOINT`
-
-### 不允许
-- `USE`
-- `SET`
-- `COPY`
-- `LOAD`
-- `CALL`
-- 各数据库专有高风险元命令
-
-### 补充说明
-- 允许的 SQL 类型表示 V1 协议允许承载的语句范围，不代表所有正式支持数据库都必须支持该范围内的每一种语句。
-- 是否支持以数据库级 `capability` 为准，不支持时统一返回 `unsupported`。
-
-#### V1 对事务语义的一致性承诺分为两层
-- 事务控制语义：`BEGIN`、`START TRANSACTION`、`COMMIT`、`ROLLBACK`
-- `savepoint` 语义：`SAVEPOINT`、`ROLLBACK TO SAVEPOINT`、`RELEASE SAVEPOINT`
-- 对原生支持事务控制的 `database`，统一承诺事务控制语义。
-- 对原生支持 `savepoint` 的 `database`，统一承诺 `savepoint` 语义。
-- 对不支持事务控制或 `savepoint` 的 `database`，相关语句统一返回 `unsupported`。
-- DDL、DCL、`EXPLAIN ANALYZE` 在事务中的行为遵循数据库原生语义，并由 `capability` 显式声明。
-
-## 16. MCP 会话与事务语义
-- 每个 MCP 会话对应一个逻辑会话上下文。
-- V1 内置运行时直接使用 `session_id` 作为 SQL execution trace 标签。
-- 会话期间该 `session_id` 保持不变。
-- 会话不支持恢复；会话结束即逻辑上下文结束。
-- 默认执行模式为 `autocommit = true`。
-- 对原生支持事务控制的 `database`，显式执行 `BEGIN` 或 `START TRANSACTION` 后进入事务态。
-- 对原生支持 `savepoint` 的 `database`，支持 `SAVEPOINT`、`ROLLBACK TO
SAVEPOINT`、`RELEASE SAVEPOINT`。
-- 当前事务上下文仅在当前 MCP 会话内有效。
-- 事务存续期间绑定单一 `database`，不允许切换目标数据库。
-- MCP 会话结束时，未提交事务统一自动回滚。
-- V1 不支持通过 `USE` 或 `SET` 修改会话上下文。
-- 对原生不支持事务控制或 `savepoint` 的 `database`，相关事务语句统一返回 `unsupported`。
-
-## 17. 统一执行结果模型
-
-### `result_set`
-- 用于返回结果集的语句，至少包含：
-- `result_kind`
-- `statement_class`
-- `statement_type`
-- `status`
-- `columns`
-- `rows`
-- `truncated`
-
-### `update_count`
-- 用于返回更新计数的语句，至少包含：
-- `result_kind`
-- `statement_class`
-- `statement_type`
-- `status`
-- `affected_rows`
-- `truncated`
-
-### `statement_ack`
-- 用于 DDL、DCL、事务控制和其他非结果集语句，至少包含：
-- `result_kind`
-- `statement_class`
-- `statement_type`
-- `status`
-- `message`
-- `truncated`
-
-### 补充约束
-- `statement_class` 表达治理语义和副作用级别。
-- `statement_type` 表达用户可读的主要语句类型。
-- `result_kind` 表达返回形状，不能反向替代 `statement_class`。
-- `INSERT`、`UPDATE`、`DELETE`、`MERGE` 默认返回 `update_count`；
- 但 data-modifying CTE 等场景允许 `statement_class = dml` 且返回 `result_set`。
-- `CREATE`、`ALTER`、`DROP`、`TRUNCATE`、`GRANT`、`REVOKE`、事务控制语句默认返回
`statement_ack`。
-- `EXPLAIN ANALYZE` 的返回形态由数据库级 `capability` 决定。
-- 一次 SQL tool call 只返回一个结果对象。
-- V1 不支持多结果集返回。
-
-## 18. 统一结果数据类型约束
-- `columns` 至少包含字段名、统一逻辑类型、底层原生类型、是否可空。
-- `rows` 必须与 `columns` 顺序对齐。
-- `null` 值必须一致表达。
-- 日期、时间、时间戳必须使用统一可解析格式返回。
-- 高精度 `decimal / numeric` 建议按字符串返回，避免精度丢失。
-- `JSON`、数组、二进制等复杂类型必须使用统一可识别表达方式。
-- 结果被截断时必须显式返回 `truncated=true`。
-
-## 19. 能力声明
-
-### 19.1 服务级 capability
-- 服务级 `capability` 只表达协议公共能力，至少包含：
-- `supported_resources`
-- `supported_tools`
-- `supported_statement_classes`
-
-### 19.2 数据库级 capability
-- 数据库级 `capability` 表达某个 `database` 的具体行为边界，至少包含：
-- `supported_object_types`
-- `supported_statement_classes`
-- `supports_transaction_control`
-- `supports_savepoint`
-- `supported_transaction_statements`
-- `default_autocommit`
-- `max_rows_default`
-- `max_timeout_ms_default`
-- `default_schema_semantics`
-- `schema_execution_semantics`
-- `supports_cross_schema_sql`
-- `supports_explain_analyze`
-- `ddl_transaction_behavior`
-- `dcl_transaction_behavior`
-- `explain_analyze_result_behavior`
-- `explain_analyze_transaction_behavior`
-
-### 19.3 枚举约束
-- `ddl_transaction_behavior = uniform | native | unsupported`
-- `dcl_transaction_behavior = uniform | native | unsupported`
-- `explain_analyze_result_behavior = result_set | statement_ack | unsupported`
-- `explain_analyze_transaction_behavior = uniform | native | unsupported`
-
-### 19.4 说明
-- `default_autocommit` 指 ShardingSphere MCP 会话默认行为，不等同于底层数据库原生默认 `autocommit`。
-- `default_schema_semantics` 解决 metadata/discovery 侧的统一 schema 语义。
-- `schema_execution_semantics` 解决 SQL tool request-level `schema` 在执行时如何解释。
-- 对原生支持事务控制的 `database`，`supports_transaction_control = true`。
-- 对原生不支持事务控制的 `database`，`supports_transaction_control = false`。
-- 对原生支持 `savepoint` 的 `database`，`supports_savepoint = true`。
-- 对原生不支持 `savepoint` 的 `database`，`supports_savepoint = false`。
-- `index` 是否支持由 `supported_object_types` 明确声明。
-- DDL、DCL、`EXPLAIN ANALYZE` 的事务边界行为必须由数据库级 `capability` 明确声明。
-
-## 20. 运行边界与 SQL Execution Trace
-
-### V1 当前实现
-- 内置 runtime 不拦截调用请求。
-- HTTP 端点如需对外暴露，应放在受信网络、上游网关、反向代理或其他网络边界之后。
-- SQL 执行路径生成本地 trace 摘要；V1 不承诺持久化合规日志或全量 MCP 活动记录。
-
-### V1 不纳入正式验收
-- 内置对象级可见性裁剪
-- 内置语句类别拦截
-- 列级可见性裁剪
-- 字段脱敏
-- 行级数据过滤
-
-## 22. 元数据变化感知与同步 SLA
-
-### V1 正式承诺
-- 结构变化和 DCL 变化必须在 1 分钟内反映到 MCP 公共面。
-- 由 ShardingSphere 负责感知变化并同步 MCP 出口。
-
-### 覆盖变化包括
-- `schema` 新增、删除、重命名
-- `table / view` 新增、删除、重命名
-- `column` 新增、删除、重命名、类型变化
-- `index` 新增、删除
-
-### 补充规则
-- 若结构变更通过当前 MCP 会话执行成功，当前会话中应尽快可见。
-- 全局视角仍以 1 分钟内同步为准。
-
-## 23. SQL Execution Trace 基线
-
-### SQL execution trace 记录至少应包含
-- `session_id`
-- `database`
-- `statement_class`
-- `statement_digest`
-- `success_or_failure`
-- `error_code`
-- `transaction_marker`
-- `timestamp`
-
-### 补充说明
-- `operation_class` 统一表示 `resource_read`、`metadata_tool`、`query_execution`。
-- 对 SQL，`operation_digest` 表示语句摘要。
-- 对 `resources / tools`，`operation_digest` 表示资源路径或工具调用摘要。
-- `transaction_marker` 至少能标识 `BEGIN`、`COMMIT`、`ROLLBACK`、`SAVEPOINT`。
-
-## 24. 错误模型
-
-### 统一错误码
-- `invalid_request`
-- `not_found`
-- `unsupported`
-- `conflict`
-- `unavailable`
-- `transaction_state_error`
-- `query_failed`
-
-### 补充规则
-- 在无活动事务时执行 `COMMIT`、`ROLLBACK` 或引用不存在的保存点，返回 `transaction_state_error`。
-- 当前 `database` 不支持事务控制时执行事务控制语句，返回 `unsupported`。
-- 当前 `database` 不支持 `savepoint` 时执行 `savepoint` 语句，返回 `unsupported`。
-
-## 25. 历史 V1 最低统一能力基线（非当前提交门禁）
-
-> 本节是早期统一数据库入口目标，不是当前 submit-ready MCP V1 的完成门禁。
-> 当前提交门禁以 runtime readiness、distribution、E2E 与当前 descriptor public surface 为准。
-- V1 正式支持数据库必须统一满足以下最低能力基线：
-- 统一支持核心对象模型：`database / schema / table / view / column / capability`
-- 统一支持公共 `tools`：`list_databases / list_schemas / list_tables / list_views /
list_columns / search_metadata / describe_table / describe_view /
get_capabilities / execute_query`
-- 统一支持 `result_set / update_count / statement_ack` 三类结果模型
-- 统一支持结构变化在 1 分钟内同步到 MCP 出口
-- 对原生支持事务控制的 `database`，统一支持 `BEGIN / START TRANSACTION / COMMIT / ROLLBACK`
-- 对原生支持 `savepoint` 的 `database`，统一支持 `SAVEPOINT / ROLLBACK TO SAVEPOINT /
RELEASE SAVEPOINT`
-- 对不支持事务控制或 `savepoint` 的 `database`，相关 `capability` 必须明确声明，相关语句统一返回
`unsupported`
-- `index` 不属于 V1 强制统一基线对象，是否支持由 `supported_object_types` 声明
-- 数据库级 `capability` 必须显式声明 `supported_statement_classes`
-
-## 26. V1 事务能力矩阵
-- MySQL：`supports_transaction_control=true`，`supports_savepoint=true`
-- PostgreSQL：`true`，`true`
-- openGauss：`true`，`true`
-- SQL Server：`true`，`true`
-- MariaDB：`true`，`true`
-- Oracle：`true`，`true`
-- ClickHouse：`false`，`false`
-- Doris：`true`，`false`
-- Hive：`false`，`false`
-- Presto：`true`，`false`
-- Firebird：`true`，`true`
-- H2：`true`，`true`
-
-### 说明
-- 上述矩阵必须与数据库级 `capability` 的真实返回保持一致。
-- 若后续版本、部署模式或产品范围变化导致某 `database` 的事务能力变化，必须同步更新 `capability` 与验收口径。
-
-## 27. 成功指标
-- 支持数据库的正式接入数量
-- 上层 Agent 的单次接入成功率
-- 多数据库统一工具适用率
-- 元数据同步在 1 分钟内达标比例
-- SQL 执行成功率
-- 事务控制成功率
-- `savepoint` 成功率
-- 运行边界控制效果
-- 上层平台对多数据库 MCP 适配代码的减少比例
-
-## 28. 主要风险
-- 不同数据库对象语义差异过大，导致公共面过度抽象。
-- 支持矩阵扩大后，不同数据库在 `schema` 语义、对象模型、结果类型和执行能力上的差异显著增加。
-- ClickHouse、Doris、Hive、Presto 等数据库会成为统一契约的一致性风险重点区域。
-- 结果模型不稳定会导致上层仍需写数据库分支。
-- 元数据同步不稳定会直接影响 MCP 可信度。
-- 事务语义、`savepoint` 语义、写操作边界和多数据库一致性控制不清会带来安全风险。
-
-## 29. 标准 Demo
-
-### 说明原则
-- 服务级 `capability` 只表达协议公共能力。
-- 数据库级 `capability` 决定具体 `database` 的事务、高级语句、对象类型和边界行为。
-- DDL、DCL、`EXPLAIN ANALYZE` 在事务中的行为以数据库级 `capability` 为准。
-- `index` 相关能力仅在 `supported_object_types` 包含 `index` 时暴露。
-
-## 30. 历史压缩版需求清单（非当前提交门禁）
-
-> 本清单保留早期目标，不表示当前提交必须完成完整统一治理能力。
-1. 必须提供统一数据库访问与 SQL 执行公共面。
-2. 必须统一 `database / schema / table / view / column / capability` 对象语义。
-3. `index` 必须作为数据库级可选公共对象，通过 `capability` 明确声明。
-4. 必须支持对象发现的搜索、过滤和大结果收窄提示。
-5. 必须提供正式公共工具 `execute_query`。
-6. 必须支持通用 SQL 执行，但 V1 不包含 `USE`、`SET`、`COPY`、`LOAD`、`CALL` 和各数据库专有高风险元命令。
-7. 必须定义 MCP 会话语义、SQL execution trace 标签和事务语义。
-8. 必须区分事务控制语义与 `savepoint` 语义。
-9. 必须提供统一执行结果模型。
-10. 必须补充服务级 `capability` 与数据库级 `capability` 的正式内容模型。
-11. 必须保证结构变化在 1 分钟内同步到 MCP 出口。
-12. 必须提供统一错误模型，覆盖冲突、事务和执行失败。
-13. HTTP 端点如需对外暴露，必须放在受信网络、上游网关、反向代理或其他网络边界之后。
-14. 必须明确 DDL、DCL、`EXPLAIN ANALYZE` 在事务中的行为遵循数据库原生语义，并通过 `capability` 声明。
-15. 必须提供正式支持数据库的事务能力矩阵，并保证与 `capability` 一致。
-
-## 31. 压缩版验收清单
-1. Agent 只接入一个 ShardingSphere MCP 服务即可访问和执行多种数据库上的统一 SQL 公共能力。
-2. V1 正式支持数据库都满足统一对象模型、统一 `tools`、统一结果模型和统一错误语义。
-3. `search_metadata` 支持 `database / schema / table / view / column / index`。
-4. 对原生支持事务控制的 `database`，事务控制语义稳定一致。
-5. 对原生支持 `savepoint` 的 `database`，`savepoint` 语义稳定一致。
-6. 对不支持事务控制或 `savepoint` 的 `database`，相关语句统一返回 `unsupported`。
-7. `index` 仅在 `supported_object_types` 包含该对象时暴露。
-8. 通过 MCP 执行成功的结构变更，在当前会话中可快速可见，并在 1 分钟内全局可见。
-9. `USE`、`SET`、`COPY`、`LOAD`、`CALL` 在 V1 中被统一拒绝，并返回一致错误语义。
-10. DDL、DCL、`EXPLAIN ANALYZE` 在事务中的行为差异已通过数据库级 `capability` 明确声明。
-11. MCP 会话结束后上下文不恢复，未提交事务自动回滚。
-12. 事务能力矩阵与实际 `capability` 返回一致。
-13. 上层不再需要为不同数据库单独适配对象发现、执行工具和返回结构。
diff --git a/docs/mcp/ShardingSphere-MCP-Technical-Design.md
b/docs/mcp/ShardingSphere-MCP-Technical-Design.md
deleted file mode 100644
index 6c0bc30cb9c..00000000000
--- a/docs/mcp/ShardingSphere-MCP-Technical-Design.md
+++ /dev/null
@@ -1,854 +0,0 @@
-# ShardingSphere MCP 技术设计方案
-
-> 状态说明：本文档保留早期技术设计背景，不是当前 MCP public surface 契约。
-> 当前契约以 `shardingsphere://capabilities`、descriptor、`mcp/README.md` 和
`mcp/README_ZH.md` 为准。
-> 不要从本文档推导早期工具矩阵或额外兼容层。
-> 当前可提交范围是 MCP V1 runtime readiness，不是完整 ShardingSphere governance
administration surface。
-
-## 1. 文档信息
-- 文档名称：ShardingSphere MCP 技术设计方案
-- 文档版本：最终版
-- 文档类型：Technical Design
-- 状态：可进入正式架构评审
-- 目标范围：ShardingSphere MCP V1
-
-## 2. 方案摘要
-- ShardingSphere MCP 作为 ShardingSphere 主仓库内的新接入面落地，但采用“独立代码模块 + 根 distribution
发布模块”的组织方式。
-- 代码模块：
- - `mcp/core`
- - `mcp/bootstrap`
-- 发布模块：
- - `distribution/mcp`
- - `artifactId`：`shardingsphere-mcp-distribution`
-- 协议层与运行层采用仓库内自管 MCP 领域模型与 bootstrap 适配层，HTTP 服务承载采用：
- - `mcp/bootstrap` 中局部引入的 MCP Java SDK
- - embedded Tomcat 11
-- 本地调试采用：
- - STDIO
-- 同时通过 JDK 21 子链路 + 常规 reactor 模块接入 + JDK 21 子链路 CI + 独立 distribution
与当前主仓库主线共存。
-
-## 3. 背景
-- 根据前期 PRD，ShardingSphere MCP 要解决的不是“把 MCP 跑起来”，而是形成正式的数据库统一 AI/Agent 接入面，覆盖：
- - 统一 metadata 发现
- - 统一 capability 声明
- - 统一 SQL 执行入口的早期设想；当前 public tools 使用 `database_gateway_execute_query` 与
`database_gateway_execute_update`
- - 统一错误模型
- - 统一事务与 `savepoint` 能力边界
- - 统一 SQL execution trace 与治理可见性
-- 当前仓库和生态事实如下：
- - 根工程模块结构见 `pom.xml`（line 33）
- - 根工程 Java 基线为 8，`pom.xml`（line 55）
- - 根工程 Jackson 版本为 2.16.1，`pom.xml`（line 93）
- - 根 distribution 聚合当前管理：
- - `src`
- - `agent`
- - `jdbc`
- - `proxy`
- - `proxy-native`
- - 见 `distribution/pom.xml`（line 30）
- - MCP 子链路当前实现固定在 Java 21
-- 因此，技术方案必须同时满足：
- - MCP 进入主仓库
- - 不破坏根工程 Java 8 默认构建
- - 保持与现有 distribution 结构一致
- - 覆盖当前 descriptor public surface 中的 capability、SQL execution 与 transaction
semantics
-
-## 4. 目标
-- 本方案目标如下：
- - 将 MCP 作为 ShardingSphere 的正式接入子系统落地。
-- `mcp/core` 继续使用仓库内自管 runtime 与领域模型，`mcp/bootstrap` 局部引入 MCP Java SDK。
- - 在不推动全仓升级到 JDK 21 的前提下，引入 MCP 子链路的 Java 21 能力。
- - 形成独立部署、独立运行、独立发布的 MCP 服务。
- - 支撑 PRD 中定义的：
- - `capability`
- - `database_gateway_execute_query`
- - `database_gateway_execute_update`
- - `transaction matrix`
- - `SQL execution trace`
- - 统一错误模型
-
-## 5. 非目标
-- 本方案不包括以下内容：
- - 不展开类图、接口签名、方法级实现细节。
- - 不推动整个主仓库统一升级到 JDK 21。
- - 不引入 Spring AI 或 Spring Boot 作为主实现框架。
- - 不把 MCP 嵌入 proxy 或 jdbc。
- - 不在 V1 实现分布式会话存储。
- - 不在 V1 承诺事务态无损 failover。
- - 不在本阶段定义全部配置文件字段细节。
-
-## 6. 关键约束
-
-### 6.1 仓库约束
-- 根工程当前默认模块链固定，`pom.xml`（line 33）
-- 根工程 Java 基线是 8，`pom.xml`（line 55）
-- 根工程当前 Jakarta BOM 为 8.0.0，`pom.xml`（line 102）
-- 根 distribution 当前是默认构建链的一部分，`pom.xml`（line 49）
-
-### 6.2 运行时约束
-- 截至 2026-03-21：
- - MCP 子链路实现固定为 Java 21
- - Streamable HTTP 与 STDIO 双 transport 由仓库内 runtime 提供
-
-### 6.3 HTTP Runtime 约束
-- HTTP listener 由 `mcp/bootstrap` 局部引入的 embedded Tomcat 承载
-- MCP Java SDK 只允许出现在 `mcp/bootstrap`
-- 不引入 Spring runtime
-- HTTP transport mechanics 优先复用官方
- `HttpServletStreamableServerTransportProvider`
-- ShardingSphere 自定义代码只保留协议版本 contract、initialize 响应头、
- managed session cleanup 与必要兼容层
-
-### 6.4 合规约束
-- 官方 Java SDK 使用 MIT 许可
-- MIT/X11 属于 ASF Category A，可纳入 Apache 产品分发
-- 来源：ASF 3rd Party License Policy
-
-## 7. 关键设计决策
-
-### 7.1 MCP 进入主仓库并沿用常规模块接入
-- 最终决策：
- - `mcp` 放在主仓库根目录下
- - 作为独立代码子项目存在
- - 直接进入根 `pom.xml` 默认 `<modules>`
- - 不再通过独立 `mcp` profile 启用
-- 原因：
- - 保持统一版本、统一仓库、统一演进
- - 与 JDBC、Proxy、agent 保持一致的模块管理方式
- - 打包、测试和发布链路不再依赖额外 profile
-
-### 7.2 `distribution/mcp` 放在根 distribution 下
-- 最终决策：
- - 发布模块位于 `distribution/mcp`
- - `artifactId` 为 `shardingsphere-mcp-distribution`
-- 原因：
- - 与现有 distribution 结构一致
- - 更符合仓库发布与 release 组织方式
- - 与 `distribution/proxy`、`distribution/jdbc` 的模式一致
-
-### 7.3 `mcp` 和 `distribution/mcp` 直接进入默认 modules
-- 最终决策：
- - 根 `pom.xml` 直接加入 `mcp`
- - `distribution/pom.xml` 直接加入 `distribution/mcp`
- - `test/e2e/pom.xml` 直接加入 `test/e2e/mcp`
- - JDK 21 子链路 CI 继续保留独立 lane
-- 原因：
- - 这样可以让 MCP 与 JDBC、Proxy、agent 保持一致的模块接入方式
- - 打包、测试和发布链路不再依赖额外 profile
- - Java 21 约束仍局部收敛在 MCP 子模块
-
-### 7.4 不使用 Spring AI
-- 最终决策：
- - MCP 不采用 Spring AI 作为核心实现方案
-- 原因：
- - Spring AI 提供的是 Boot 集成增强
- - 本项目主复杂度不在 starter / 注解层
- - 主仓库当前不是 Spring 工程
- - 引入 Spring AI 会扩大技术栈侵入与长期维护成本
-
-### 7.5 Runtime 默认选型
-- 最终决策：
- - `mcp/core` 继续使用仓库内自管 protocol DTO 与领域模型
- - `mcp/bootstrap` 使用 MCP Java SDK 的 Jackson 2 适配与 Streamable HTTP transport
-- 不采用：
- - 让 `mcp/core` 直接依赖 SDK 类型
- - Spring AI / Spring Boot runtime
-- 原因：
- - 用最小边界复用官方协议实现
- - 保持 ShardingSphere 领域模型与外部 SDK 解耦
- - 通过根工程 Jackson 版本管理保证 2.16.1 一致性
-
-### 7.6 JSON 处理策略
-- 最终决策：
- - transport JSON 编解码通过 MCP Java SDK 的 Jackson 2 适配完成
- - Jackson 版本继续受根工程 `2.16.1` 约束
- - 业务对象继续使用仓库内 DTO
-- 原因：
- - 降低协议序列化样板代码
- - 避免引入与主仓库不一致的 Jackson 版本
-
-### 7.7 HTTP 服务承载
-- 最终决策：
- - 使用 embedded Tomcat 11 承载 MCP Java SDK 的 Streamable HTTP servlet
- - 当前内置 HTTP runtime 不提供授权，远程暴露由外部网关、反向代理或网络边界负责
- - `Origin` 边界保持独立本地策略类，并由 servlet 前置校验
-- 原因：
- - 只在 bootstrap 层引入最小 servlet 容器
- - 与官方 Streamable HTTP servlet transport 对齐
- - 仍然不把运行时依赖扩散到主仓库其他模块
- - 不在开源默认配置中扩展授权平台，避免引入与 MCP transport 无关的过度设计
-
-### 7.8 HTTP 会话与事务状态
-- 最终决策：
- - STDIO 为天然会话态
- - HTTP 也维护逻辑 MCP 会话
- - V1 采用：
- - sticky session
- - 本地内存会话状态
- - V1 不做：
- - distributed session store
- - 事务态无损故障切换
-- 原因：
- - PRD 已定义事务与 `savepoint` 语义
- - HTTP 不能被实现为完全无状态请求模型
-
-## 8. 仓库组织与模块设计
-
-### 8.1 推荐目录结构
-```text
-shardingsphere
-├── mcp
-│ ├── pom.xml
-│ ├── core
-│ ├── jdbc
-│ └── bootstrap
-├── distribution
-│ └── mcp
-└── pom.xml
-```
-
-### 8.2 模块职责
-
-#### `mcp/core`
-- MCP 公共对象模型
-- capability 组装
-- metadata discovery facade
-- SQL tool facade
-- session / transaction facade
-- session lifecycle registry
-- resource URI resolver
-- tool catalog 与参数归一化
-- 通用 payload / error payload builder
-- error model
-- SQL execution trace facade
-- 对 ShardingSphere 内核能力的统一门面
-- runtime service 聚合
-- JDBC runtime 配置模型
-- JDBC metadata 发现
-- `DatabaseRuntime` 装配
-- JDBC-backed runtime context factory
-
-#### `mcp/bootstrap`
-- MCP server 启动入口
-- HTTP / STDIO transport 装配
-- 配置加载
-- MCP Java SDK `Tool` / `ResourceTemplate` schema 适配
-- tools / resources 注册
-- servlet / stdio 生命周期接线
-
-#### `distribution/mcp`
-- `shardingsphere-mcp-distribution`
-- 二进制包
-- Docker 镜像
-- 启动脚本
-- 配置模板
-- 发布资产
-
-### 8.3 Parent 与版本对齐
-- 推荐：
- - `mcp/pom.xml` 继承根 `shardingsphere` parent，保持版本一致
- - `distribution/mcp/pom.xml` 继承 `shardingsphere-distribution` parent，保持发布结构一致
-- 这样既能保证版本统一，也能保证模块分层清晰。
-
-### 8.4 依赖方向
-- 允许：
- - `mcp/core` 依赖 `infra`
- - `mcp/core` 依赖 `database`
- - `mcp/core` 依赖 `parser`
- - `mcp/core` 依赖 `mode`
- - `mcp/core` 依赖 `kernel`
- - 必要时依赖少量 `features`
- - `mcp/bootstrap` 依赖 `mcp/core`
-- 禁止：
- - `kernel -> mcp`
- - `proxy -> mcp`
- - `jdbc -> mcp`
-
-### 8.5 MCP 与 Proxy/JDBC 的关系
-- MCP 与 Proxy/JDBC 的关系是：
- - 产品层：都属于 ShardingSphere 接入面
- - 实现层：都消费 ShardingSphere 内核
- - 运行层：彼此独立部署、独立治理、独立发布
-- MCP 不是 Proxy façade，也不是 JDBC wrapper。
-
-## 9. 构建与发布模型
-
-### 9.1 Operator Rollout Notes
-
-#### 9.1.1 Distribution Layout
-- `distribution/mcp` 在 `package` 阶段输出：
- - `apache-shardingsphere-mcp-<version>/bin`
- - `apache-shardingsphere-mcp-<version>/conf`
- - `apache-shardingsphere-mcp-<version>/lib`
- - `apache-shardingsphere-mcp-<version>/logs`
-- `bin/start.sh` 仅面向发布目录启动，避免把源码树调试逻辑混入发布入口
-
-#### 9.1.2 Runtime Assets
-- 默认配置模板：
- - `distribution/mcp/src/main/resources/conf/mcp-http.yaml`
- - `distribution/mcp/src/main/resources/conf/mcp-stdio.yaml`
-- 默认容器入口：
- - `distribution/mcp/Dockerfile`
-- 默认本地启动脚本：
- - `distribution/mcp/src/main/bin/start.sh`
-
-#### 9.1.3 Validation Flow
-- 运维侧推荐的最小验证顺序：
- 1. `./mvnw -pl mcp -am test -DskipITs -Dspotless.skip=true`
- 2. `./mvnw -pl distribution/mcp -am -DskipTests package`
- 3. `./mvnw -pl test/e2e/mcp -am test -Dsurefire.failIfNoSpecifiedTests=false`
- 4. `sh
distribution/mcp/target/apache-shardingsphere-mcp-<version>/bin/start.sh`
-- 验证重点：
- - `/mcp` Streamable HTTP 会话初始化与关闭
- - STDIO 本地调试入口
- - metadata discovery
- - SQL tool pair
- - SQL execution trace 与变化可见性
-
-#### 9.1.4 Rollback Guidance
-- 如需回滚：
- - 停止 MCP 独立进程或容器
- - 回退 `mcp`、`distribution/mcp` 与 `test/e2e/mcp` 子链路代码
- - 同时回退根 `pom.xml`、`distribution/pom.xml` 与 `test/e2e/pom.xml` 中对 MCP 模块的聚合变更
-- 本方案不修改 Proxy/JDBC 运行链，因此回滚边界限定在 MCP 子链路及其 reactor 聚合改动。
-
-### 9.2 总体策略
-- 采用“与 JDBC、Proxy、agent 一致的常规模块接入 + JDK 21 子链路 CI”的方案：
- - 根工程默认构建链直接包含 `mcp`
- - 根 distribution 默认构建链直接包含 `distribution/mcp`
- - 根 `test/e2e` 默认构建链直接包含 `test/e2e/mcp`
- - MCP 继续保留 JDK 21 子链路 CI lane，但不依赖独立 Maven profile
-
-### 9.3 模块接入方式
-
-#### 根 `pom.xml`
-- 直接在 `<modules>` 中加入：
- - `<module>mcp</module>`
-
-#### `distribution/pom.xml`
-- 直接在 `<modules>` 中加入：
- - `<module>mcp</module>`
-
-#### `test/e2e/pom.xml`
-- 直接在 `<modules>` 中加入：
- - `<module>mcp</module>`
-
-### 9.4 构建链
-
-#### 默认构建链
-- 默认 reactor 直接包含 `mcp`、`distribution/mcp` 与 `test/e2e/mcp`
-- 需要为 MCP 子模块提供 JDK 21 编译环境
-- Java 21 相关依赖与编译参数局部收敛在 MCP 子链路
-
-#### MCP 构建链
-- 固定 JDK 21
-- 构建：
- - `mcp/core`
- - `mcp/bootstrap`
- - `test/e2e/mcp`
- - `distribution/mcp`
-
-### 9.5 JDK 21 隔离策略
-- 推荐：
- - Maven Toolchains
- - `mcp/pom.xml` 明确 `maven.compiler.release=21`
- - JDK 21 子链路 CI lane 固定 JDK 21
-
-### 9.6 依赖管理隔离
-- 必须遵守：
- - 不把额外 MCP SDK 或 HTTP 容器依赖引入根工程 `dependencyManagement`
- - MCP 子链路内部独立管理依赖版本
- - MCP Java SDK transitive Jackson 版本必须服从根工程 Jackson `2.16.1`
-
-### 9.7 为什么 `distribution/mcp` 仍需局部隔离
-- 因为 `distribution/mcp` 依赖的是 Java 21 的 `mcp/bootstrap`。
-- 现在 `distribution/mcp` 已进入默认构建链，因此必须把 Java 21 约束局部收敛在 MCP 子链路内部，而不是重新引入独立
profile。
-
-## 10. 技术选型明细
-
-### 10.1 协议与 JSON
-- 默认采用：
- - `mcp/core` 仓库内 protocol DTO
- - `mcp/bootstrap` 中的 MCP Java SDK transport facade
- - `mcp-json-jackson2` 与仓库统一 Jackson 2.16.1
-- 不采用：
- - 让 SDK 类型进入 `mcp/core`
- - 外部 JSON bridge
-
-### 10.2 HTTP Runtime
-- 采用：
- - embedded Tomcat 11
- - MCP Java SDK `HttpServletStreamableServerTransportProvider`
-- 约束：
- - 运行时实现只出现在：
- - `mcp/bootstrap`
- - `distribution/mcp`
- - 不进入根工程统一依赖管理
- - routing、SDK session 与 `DELETE` 基础语义优先交给官方 provider
- - provider 继续执行严格 `Accept` 校验；missing/blank `Accept` 的零损失兼容由本地 shim 承接
- - initialize `MCP-Protocol-Version` 响应头、follow-up protocol contract、
- managed session cleanup 和零损失兼容 shim 继续由 ShardingSphere 保留
-
-### 10.3 本地调试
-- 采用：
- - STDIO
-
-### 10.4 联调工具
-- 推荐：
- - 本地 STDIO 集成测试路径
- - HTTP 冒烟联调
- - capability / transaction 专项联调
-
-## 11. 总体架构
-
-```mermaid
-flowchart TB
- A["Agent / IDE / AI Platform"] --> B["MCP Transport Layer"]
- B --> C["MCP Protocol Layer"]
- C --> D["MCP Domain Facade"]
- D --> E["ShardingSphere Integration Layer"]
- E --> F["Metadata / Governance / Execution"]
- F --> G["Underlying Databases"]
-
- H["Trace / Metrics / Logging"] --> C
- H --> D
-```
-
-### 11.1 分层职责
-
-#### MCP Transport Layer
-- 承载 HTTP 与 STDIO
-- 管理会话、连接、请求 / 响应生命周期
-- 不承载业务能力判断
-
-#### MCP Protocol Layer
-- 处理 MCP 概念：
- - resources
- - tools
- - capability
- - errors
-- 将协议对象转换为领域命令
-
-#### MCP Domain Facade
-- 是 MCP 子系统的核心语义层
-- 统一提供：
- - metadata discovery
- - capability
- - SQL tool pair
- - transaction / savepoint handling
-
-#### ShardingSphere Integration Layer
-- 适配 metadata、parser、mode、kernel 与相关治理模块能力
-- 屏蔽内核模块差异
-- 不向内核泄露 MCP 概念
-
-## 12. Capability 设计
-
-### 12.1 基本原则
-- capability = 客观能力边界
-
-### 12.2 服务级 Capability
-- 服务级 capability 只描述协议公共能力，例如：
- - supported resources
- - supported tools
- - supported statement classes
-- 服务级 capability 不携带单个 `database` 的事务与对象支持差异。
-
-### 12.3 数据库级 Capability
-- 数据库级 capability 至少覆盖：
- - `supported_object_types`
- - `supported_statement_classes`
- - `supports_transaction_control`
- - `supports_savepoint`
- - `supported_transaction_statements`
- - `default_autocommit`
- - `default_schema_semantics`
- - `schema_execution_semantics`
- - `supports_cross_schema_sql`
- - `supports_explain_analyze`
- - `ddl_transaction_behavior`
- - `dcl_transaction_behavior`
- - `explain_analyze_result_behavior`
- - `explain_analyze_transaction_behavior`
-
-### 12.4 Optional Object Types
-- V1 强制统一对象基线：
- - `database`
- - `schema`
- - `table`
- - `view`
- - `column`
- - `capability`
-- V1 可选对象：
- - `index`
-- 规则：
- - `index` 由数据库级 capability 的 `supported_object_types` 声明
- - 不支持时 direct API 返回 `unsupported`
-
-## 13. SQL 执行入口设计
-
-> 本节标题和部分正文保留早期 `execute_query` 术语。
-> 当前 MCP public surface 将读查询与变更执行拆分为 `database_gateway_execute_query` 和
`database_gateway_execute_update`。
-
-### 13.1 设计原则
-- 早期 `execute_query` 设计已收敛为当前 descriptor 中的 SQL tool pair。
-- 它不是 SQL 透传接口，而是统一执行与治理入口。
-- `database` 是唯一强执行边界。
-- `schema` 是可选 namespace hint，不是第二个强路由键。
-- `schema_execution_semantics` 用于向调用方显式声明 request-level `schema` 的执行语义。
-
-### 13.2 高层处理阶段
-- 统一划分为 5 个阶段：
- 1. 请求合法性校验
- 2. MCP 会话与事务状态校验
- 3. capability 校验
- 4. ShardingSphere parse / route / execute 适配
- 5. 统一结果与错误映射
-
-### 13.3 Statement Class 统一分类
-- `select`
-- `dml`
-- `ddl`
-- `dcl`
-- `transaction_control`
-- `savepoint`
-- `explain_analyze`
-- `WITH` 只是语法前导，不是独立 statement class。
-- `statement_class` 表达治理语义和副作用级别。
-- `statement_type` 表达用户可读的主要语句类型。
-
-### 13.4 统一结果模型
-- `result_set`
-- `update_count`
-- `statement_ack`
-- 每个成功结果都包含：
- - `statement_class`
- - `statement_type`
- - `status`
- - `truncated`
-- `statement_class = dml` 允许与 `result_set` 组合，
- 用于表达 data-modifying CTE。
-
-### 13.5 统一错误模型
-- `invalid_request`
-- `not_found`
-- `unsupported`
-- `conflict`
-- `unavailable`
-- `transaction_state_error`
-- `query_failed`
-
-## 14. 会话、事务与 Savepoint 设计
-
-### 14.1 会话模型
-- 每个 MCP 会话绑定：
- - 当前 database 上下文
- - 当前事务状态
- - `savepoint` 状态
- - SQL execution trace 使用的 session_id
-
-### 14.2 HTTP 会话策略
-- 由于 PRD 已定义事务与 `savepoint` 语义，HTTP 路径必须维护逻辑 MCP 会话。
-- 因此 V1 不采用完全无状态 HTTP 模型。
-
-### 14.3 V1 集群策略
-- 采用：
- - sticky session
- - 本地内存会话状态
-- 不纳入：
- - distributed session store
- - 任意节点无粘性事务恢复
- - 事务态无损 failover
-
-### 14.4 故障语义
-- 节点故障、重启或会话丢失时：
- - 该节点上的未提交事务视为失败
- - 相关 MCP 会话失效
- - 客户端需要重新建立会话并重新开始事务
-- 这属于 V1 的明确运行约束，而不是实现细节遗漏。
-
-### 14.5 事务能力矩阵
-- 事务能力必须显式维护为矩阵。
-- 矩阵至少包含：
- - `database_type`
- - `min_supported_version`
- - `supports_transaction_control`
- - `supports_savepoint`
- - `default_autocommit`
- - `supported_transaction_statements`
- - `supported_object_types`
- - `supported_statement_classes`
- - `supports_explain_analyze`
- - `ddl_transaction_behavior`
- - `dcl_transaction_behavior`
- - `explain_analyze_result_behavior`
- - `explain_analyze_transaction_behavior`
-- 矩阵角色：
- - capability 的默认事实源
- - 验收标准的技术来源
- - 支持矩阵维护的统一资产
-
-## 15. 运行边界与 SQL Execution Trace 设计
-
-### 15.1 运行边界
-- V1 内置 runtime 聚焦 session 协商、会话状态维护与运行边界校验。
-- follow-up production runtime 路径通过 `runtimeDatabases` 显式装配真实 metadata
与执行适配，不再允许默认空 `MetadataCatalog` / 空 `DatabaseRuntime` 作为成功启动路径。
-- HTTP 服务如需对外暴露，应放在受信网络、上游网关、反向代理或其他网络边界之后。
-
-### 15.2 SQL execution trace 基线
-- V1 只生成 SQL 执行路径的本地 trace 摘要，不承诺持久化合规日志或全量 MCP 活动记录。
-- 统一输出：
- - session_id
- - database
- - statement_class
- - statement_digest
- - success_or_failure
- - error_code
- - transaction_marker
- - timestamp
-
-## 16. 运行与部署模型
-
-### 16.1 生产主模型
-- 远程 HTTP MCP 服务
-- 特点：
- - 独立进程
- - 独立容器
- - 独立配置目录
- - 独立日志与 SQL execution trace
- - 独立版本发布
-
-### 16.2 调试模型
-- 本地 STDIO 模式
-- 特点：
- - 适合 IDE / 本地 Agent 的进程内联调
- - 不作为生产主模型
- - distribution 提供独立 STDIO 配置模板，但定位保持为本地集成辅助入口，而不是额外的交互式文本 Shell
-
-### 16.2.1 默认发行包启动面
-- distribution 默认启动使用 HTTP 配置，STDIO 通过 `conf/mcp-stdio.yaml` 或
`SHARDINGSPHERE_MCP_TRANSPORT=stdio` 显式选择。
-- 默认 `conf/mcp-http.yaml` 内置一段 demo JDBC runtime，用于首次启动时验证非空 metadata 和真实 SQL
tool 行为。
-- `conf/mcp-http.yaml` 采用 strict
schema：`transport.type`、`transport.http.bindHost`、`transport.http.port`、
- `transport.http.endpointPath` 以及每个 runtime database 的全部字段都必须使用受支持字段名。
-- 真实部署需要替换 `runtimeDatabases` 段为目标逻辑库与 JDBC 连接属性；schema 范围与默认 schema 由 JDBC
metadata 自动发现。
- 如需额外 JDBC 驱动，可放入发行包根目录下的 `plugins/`。
-
-### 16.3 推荐集群拓扑
-- MCP 服务集群
-- 前置 L7 网关
-- sticky session 打开
-- 每个实例维护本地会话状态
-- metadata 来源共享
-- 外部接入边界由前置网关或网络边界承担
-
-### 16.4 为什么不嵌入 Proxy
-- 因为：
- - proxy 是数据库协议代理
- - mcp 是 AI / Agent 控制与执行公共面
-- 把两者放在同一运行时，会让：
- - 运维边界不清
- - 治理边界不清
- - 版本与资源隔离变差
-
-## 17. 交互流程
-
-### 17.1 Capability 发现
-```mermaid
-sequenceDiagram
- participant C as Client
- participant M as MCP Server
- participant S as Service Capability
- participant D as Database Capability
-
- C->>M: 读取服务级 capability
- M->>S: 组装协议公共能力
- S-->>M: supported resources/tools/classes
- M-->>C: 服务级 capability
-
- C->>M: get_capabilities(database)
- M->>D: 组装数据库级 capability
- D-->>M: database capability
- M-->>C: 数据库级 capability
-```
-
-### 17.2 Metadata 发现
-```mermaid
-sequenceDiagram
- participant C as Client
- participant M as MCP Server
- participant F as Metadata Facade
- participant S as ShardingSphere Metadata
-
- C->>M: resources/read or database_gateway_search_metadata
- M->>F: metadata discovery
- F->>S: metadata 查询
- S-->>F: 可访问对象
- F-->>M: 统一对象结果
- M-->>C: MCP tool response
-```
-
-### 17.3 SQL 执行
-```mermaid
-sequenceDiagram
- participant C as Client
- participant M as MCP Server
- participant E as ExecuteQuery Facade
- participant S as ShardingSphere Core
-
- C->>M: database_gateway_execute_query or database_gateway_execute_update
- M->>E: 执行统一 SQL 请求
- E->>S: parse / route / execute
- S-->>E: raw result
- E-->>M: result_set / update_count / statement_ack
- M-->>C: MCP response
-```
-
-## 18. Distribution 与运维模型
-
-### 18.1 发布模块
-- 发布模块位于：
- - `distribution/mcp`
- - `artifactId`：`shardingsphere-mcp-distribution`
-
-### 18.2 发行物结构
-- 建议产出：
-
-```text
-apache-shardingsphere-mcp-<version>/
-├── bin/
-├── conf/
-├── lib/
-├── logs/
-└── LICENSE / NOTICE / README.md
-```
-
-### 18.3 配置分层
-- 当前 V1 打包模板直接暴露三类配置：
- - 服务配置
- - transport 配置
-- 更细粒度的暴露/治理配置保留为后续演进项，不在当前 `mcp-http.yaml` 模板中展开。
-
-### 18.4 容器化要求
-- V1 应提供：
- - 独立 Dockerfile
- - 独立镜像
- - 独立启动参数
- - 独立配置挂载约定
-
-### 18.5 可观测性
-- 当前 V1 打包运行时默认具备：
- - 服务日志目录
- - `conf/logback.xml` 日志配置
- - SQL execution trace 相关代码路径
-- `readiness / liveness` 属于后续运行时增强项，当前 standalone runtime 未直接提供。
- - capability 快照
- - tool 调用统计
- - 会话统计
-
-## 19. 第三方依赖与合规
-
-### 19.1 依赖策略
-- V1 默认采用：
- - `mcp/core`
- - `mcp/bootstrap`
-- `mcp/bootstrap` 局部采用：
- - MCP Java SDK
- - embedded Tomcat
-- 不采用：
- - SDK 类型扩散到 `mcp/core`
- - Spring runtime
-
-### 19.2 依赖管理边界
-- 以下依赖仅允许出现在 MCP 子链路：
- - MCP Java SDK
- - embedded Tomcat runtime 代码
- - MCP 子链路局部测试依赖
-- 不得：
- - 进入根工程统一依赖管理
- - 覆盖根工程现有依赖版本
- - 反向传播到 `kernel / proxy / jdbc`
-
-### 19.3 合规要求
-- 由于官方 Java SDK 采用 MIT 许可，需完成：
- - LICENSE / NOTICE 核对
- - 第三方依赖许可证审查
- - 发布前依赖清单确认
-
-## 20. 风险与缓解
-
-### 20.1 JDK 双基线风险
-- 风险：
- - 主仓库常规构建环境与 MCP 的 Java 21 需求并存
- - MCP Java 21
-- 缓解：
- - `mcp`、`distribution/mcp` 与 `test/e2e/mcp` 直接进入默认 reactor
- - MCP 子模块局部声明 Java 21
- - JDK 21 子链路 CI 固定 JDK 21
-
-### 20.2 依赖冲突风险
-- 风险：
- - MCP 子链路局部运行时依赖
- - JDK 21 runtime 边界
-- 缓解：
- - MCP 子链路内部独立管理
- - 不引额外根 BOM
- - 不让依赖外溢到主仓库主线
-
-### 20.3 数据库能力差异风险
-- 风险：
- - transaction
- - savepoint
- - index
- - explain analyze
-- 缓解：
- - 事务能力矩阵显式维护
- - capability 显式声明
- - optional object 明确控制
-
-### 20.4 集群事务会话风险
-- 风险：
- - HTTP 集群下事务上下文丢失
- - 节点故障导致会话失效
-- 缓解：
- - sticky session
- - 本地内存会话态
- - distributed session store 不纳入 V1
- - 明确 failover 语义，不承诺无损恢复
-
-## 21. 实施计划
-- 阶段 1：结构落位
- - 建立 `mcp` 子项目
- - 建立 `core / bootstrap`
- - 在根 distribution 下建立 `distribution/mcp`
- - 建立 MCP 专用 JDK 21 构建链
-- 阶段 2：协议公共面
- - 完成 resources / tools 框架
- - 完成 capability 组装链
- - 完成统一 error model
-- 阶段 3：执行与治理
- - 完成 SQL tool pair
- - 完成事务能力矩阵
- - 完成 SQL execution trace 治理可见性链路
-- 阶段 4：部署与联调
- - 完成 HTTP 服务化部署
- - 完成 STDIO 本地调试
- - 完成 capability / transaction 验证
-
-## 22. 验收标准
-- 技术验收建议至少覆盖：
- - MCP 是否作为独立代码模块存在
- - `distribution/mcp` 是否作为根 distribution 正式发布模块存在
- - 是否未反向污染主仓库 Java 8 主线
- - 是否使用官方 SDK 而非自研协议实现
- - capability 是否实现分层清晰
- - 当前 SQL tool pair 是否覆盖查询与变更执行入口
- - 事务能力矩阵是否显式维护
- - HTTP 会话与事务语义是否闭合
- - distribution 是否形成独立运维单元
-
-## 23. 最终结论
-- 最终方案可以压缩成四句话：
- - MCP 进入 ShardingSphere 主仓库，但代码模块与发布模块分层组织。
- - 代码模块位于 `mcp/core` 与 `mcp/bootstrap`，发布模块位于根
`distribution/mcp`，`artifactId` 为 `shardingsphere-mcp-distribution`。
- - `mcp/core` 继续自管领域模型，`mcp/bootstrap` 局部使用 MCP Java SDK 与 embedded Tomcat 承载
Streamable HTTP，STDIO 用于本地调试。
- - MCP 子链路通过 JDK 21、常规 reactor 模块接入、JDK 21 子链路 CI 和独立 distribution 与主仓库主线共存。
diff --git
a/mcp/bootstrap/src/test/java/org/apache/shardingsphere/mcp/bootstrap/MCPDocumentationContractTest.java
b/mcp/bootstrap/src/test/java/org/apache/shardingsphere/mcp/bootstrap/MCPDocumentationContractTest.java
deleted file mode 100644
index 1bab8ecde80..00000000000
---
a/mcp/bootstrap/src/test/java/org/apache/shardingsphere/mcp/bootstrap/MCPDocumentationContractTest.java
+++ /dev/null
@@ -1,120 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package org.apache.shardingsphere.mcp.bootstrap;
-
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import org.junit.jupiter.api.Test;
-
-import java.io.IOException;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.util.List;
-import java.util.Map;
-
-import static org.hamcrest.MatcherAssert.assertThat;
-import static org.hamcrest.Matchers.is;
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-class MCPDocumentationContractTest {
-
- private static final ObjectMapper JSON_MAPPER = new ObjectMapper();
-
- @Test
- void assertHttpDockerAndConfigurationDocs() throws IOException {
- String actualEnglish =
Files.readString(resolveMCPDirectory().resolve("README.md"));
- String actualChinese =
Files.readString(resolveMCPDirectory().resolve("README_ZH.md"));
- assertDocumentationIncludesRuntimeSafety(actualEnglish);
- assertDocumentationIncludesRuntimeSafety(actualChinese);
- assertDocumentationOmitsBuiltInAuthorization(actualEnglish);
- assertDocumentationOmitsBuiltInAuthorization(actualChinese);
- }
-
- @Test
- void assertDocumentationOmitsRemovedPayloadFields() throws IOException {
- String actual =
Files.readString(resolveMCPDirectory().resolve("README.md")) +
Files.readString(resolveMCPDirectory().resolve("README_ZH.md"));
- for (String each : List.of("pending_questions", "resource_uri",
"parent_uri", "next_resource_uris", "read_resources_first", "empty_reason",
"not_found_reason")) {
- assertFalse(actual.contains(each));
- }
- }
-
- @Test
- void assertDesignDocumentationOmitsBuiltInAuthorization() throws
IOException {
- Path docsDirectory = resolveRepositoryDirectory().resolve("docs/mcp");
- String actual =
Files.readString(docsDirectory.resolve("ShardingSphere-MCP-PRD.md"))
- +
Files.readString(docsDirectory.resolve("ShardingSphere-MCP-Detailed-Design.md"))
- +
Files.readString(docsDirectory.resolve("ShardingSphere-MCP-Technical-Design.md"));
- assertDocumentationOmitsBuiltInAuthorization(actual);
- }
-
- @Test
- void assertRegistryMetadataIncludesConfigVariable() throws IOException {
- Map<String, Object> actual =
JSON_MAPPER.readValue(resolveMCPDirectory().resolve("server.json").toFile(),
new TypeReference<>() {
- });
- List<?> packages = (List<?>) actual.get("packages");
- assertFalse(packages.isEmpty());
- for (Object each : packages) {
- Map<?, ?> actualConfigVariable = findEnvironmentVariable((Map<?,
?>) each, "SHARDINGSPHERE_MCP_CONFIG");
- assertFalse((Boolean) actualConfigVariable.get("isRequired"));
- assertFalse((Boolean) actualConfigVariable.get("isSecret"));
- assertThat(actualConfigVariable.get("format"), is("string"));
- }
- }
-
- private Map<?, ?> findEnvironmentVariable(final Map<?, ?> packageMetadata,
final String name) {
- return ((List<?>) packageMetadata.get("environmentVariables")).stream()
- .map(each -> (Map<?, ?>) each)
- .filter(each -> name.equals(each.get("name")))
- .findFirst()
- .orElseThrow();
- }
-
- private void assertDocumentationIncludesRuntimeSafety(final String
content) {
- assertTrue(content.contains("transport.type"));
- assertTrue(content.contains("STREAMABLE_HTTP"));
- assertTrue(content.contains("STDIO"));
- assertTrue(content.contains("transport.http.bindHost"));
- assertTrue(content.contains("transport.http.endpointPath"));
- assertTrue(content.contains("Origin"));
- assertTrue(content.contains("MCP form elicitation"));
- assertTrue(content.contains("URL mode"));
- assertTrue(content.contains("secret manager"));
- assertTrue(content.contains("SHARDINGSPHERE_MCP_CONFIG"));
- assertTrue(content.contains("configuration_required"));
- }
-
- private void assertDocumentationOmitsBuiltInAuthorization(final String
content) {
- for (String each : List.of("accessToken", "oauthIntrospection",
"authorizationServers", "scopesSupported", "protectedResource",
- "WWW-Authenticate", "Authorization: Bearer <token>",
"invalid_token", "insufficient_scope", "Bearer", "http.enabled",
"stdio.enabled")) {
- assertFalse(content.contains(each));
- }
- }
-
- private Path resolveMCPDirectory() {
- return resolveRepositoryDirectory().resolve("mcp");
- }
-
- private Path resolveRepositoryDirectory() {
- Path result = Path.of("").toAbsolutePath();
- while (null != result &&
!Files.exists(result.resolve("mcp/README.md"))) {
- result = result.getParent();
- }
- return result;
- }
-}
diff --git
a/mcp/registry/src/main/java/org/apache/shardingsphere/mcp/registry/MCPRegistryMetadataCommand.java
b/mcp/registry/src/main/java/org/apache/shardingsphere/mcp/registry/MCPRegistryMetadataCommand.java
index cfc45375cba..1e70519566b 100644
---
a/mcp/registry/src/main/java/org/apache/shardingsphere/mcp/registry/MCPRegistryMetadataCommand.java
+++
b/mcp/registry/src/main/java/org/apache/shardingsphere/mcp/registry/MCPRegistryMetadataCommand.java
@@ -237,11 +237,18 @@ public final class MCPRegistryMetadataCommand {
private static void validateEnvironmentVariable(final Map<String, Object>
packageMetadata, final String name) {
Object envVars = packageMetadata.get("environmentVariables");
ShardingSpherePreconditions.checkState(envVars instanceof List<?>, ()
-> new IllegalArgumentException("MCP Registry package must define " + name +
"."));
-
ShardingSpherePreconditions.checkState(containsEnvironmentVariable((List<?>)
envVars, name), () -> new IllegalArgumentException("MCP Registry package must
define " + name + "."));
+ Map<?, ?> envVar = findEnvironmentVariable((List<?>) envVars, name);
+
ShardingSpherePreconditions.checkState(Boolean.FALSE.equals(envVar.get("isRequired")),
+ () -> new IllegalArgumentException(String.format("MCP Registry
metadata for %s must declare isRequired as false.", name)));
+
ShardingSpherePreconditions.checkState(Boolean.FALSE.equals(envVar.get("isSecret")),
+ () -> new IllegalArgumentException(String.format("MCP Registry
metadata for %s must declare isSecret as false.", name)));
+
ShardingSpherePreconditions.checkState("string".equals(envVar.get("format")),
+ () -> new IllegalArgumentException(String.format("MCP Registry
metadata for %s format must be string.", name)));
}
- private static boolean containsEnvironmentVariable(final List<?> envVars,
final String name) {
- return envVars.stream().filter(each -> each instanceof Map<?,
?>).map(each -> (Map<?, ?>) each).anyMatch(each ->
name.equals(each.get("name")));
+ private static Map<?, ?> findEnvironmentVariable(final List<?> envVars,
final String name) {
+ return envVars.stream().filter(each -> each instanceof Map<?,
?>).map(each -> (Map<?, ?>) each).filter(each ->
name.equals(each.get("name"))).findFirst()
+ .orElseThrow(() -> new IllegalArgumentException("MCP Registry
package must define " + name + "."));
}
private record CommandOptions(Path path, String version, String
identifier, String dockerfilePath, boolean validateOnly, boolean allowSnapshot)
{
diff --git
a/mcp/registry/src/test/java/org/apache/shardingsphere/mcp/registry/MCPRegistryMetadataCommandTest.java
b/mcp/registry/src/test/java/org/apache/shardingsphere/mcp/registry/MCPRegistryMetadataCommandTest.java
index 9accd3549b1..8dfa2107fd3 100644
---
a/mcp/registry/src/test/java/org/apache/shardingsphere/mcp/registry/MCPRegistryMetadataCommandTest.java
+++
b/mcp/registry/src/test/java/org/apache/shardingsphere/mcp/registry/MCPRegistryMetadataCommandTest.java
@@ -121,6 +121,27 @@ class MCPRegistryMetadataCommandTest {
assertThat(actual.getMessage(), is("--version and --identifier are
required unless --validate-only is set."));
}
+ @Test
+ void assertExecuteRejectsRequiredEnvironmentVariable() throws IOException {
+ Map<String, Object> server = createServerMetadata();
+ getConfigEnvironmentVariable(server).put("isRequired", true);
+ assertEnvironmentVariableRejected(server, "MCP Registry metadata for
SHARDINGSPHERE_MCP_CONFIG must declare isRequired as false.");
+ }
+
+ @Test
+ void assertExecuteRejectsNonStringEnvironmentVariableFormat() throws
IOException {
+ Map<String, Object> server = createServerMetadata();
+ getConfigEnvironmentVariable(server).put("format", "path");
+ assertEnvironmentVariableRejected(server, "MCP Registry metadata for
SHARDINGSPHERE_MCP_CONFIG format must be string.");
+ }
+
+ @Test
+ void assertExecuteRejectsSecretEnvironmentVariable() throws IOException {
+ Map<String, Object> server = createServerMetadata();
+ getConfigEnvironmentVariable(server).put("isSecret", true);
+ assertEnvironmentVariableRejected(server, "MCP Registry metadata for
SHARDINGSPHERE_MCP_CONFIG must declare isSecret as false.");
+ }
+
@Test
void assertExecuteValidatesSourceMetadata() {
Path serverPath = resolveMCPDirectory().resolve("server.json");
@@ -221,6 +242,13 @@ class MCPRegistryMetadataCommandTest {
assertThat(actual.getMessage(), is(expectedMessage));
}
+ private void assertEnvironmentVariableRejected(final Map<String, Object>
server, final String expectedMessage) throws IOException {
+ Path serverPath = createServerJson(server);
+ IllegalArgumentException actual =
assertThrows(IllegalArgumentException.class,
+ () -> MCPRegistryMetadataCommand.execute("--path",
serverPath.toString(), "--validate-only", "--allow-snapshot"));
+ assertThat(actual.getMessage(), is(expectedMessage));
+ }
+
private Map<String, Object> readServerJson(final Path serverPath) throws
IOException {
return JSON_MAPPER.readValue(serverPath.toFile(), new
TypeReference<>() {
});
@@ -273,6 +301,15 @@ class MCPRegistryMetadataCommandTest {
return (List<Map<String, Object>>) server.get("packages");
}
+ @SuppressWarnings("unchecked")
+ private List<Map<String, Object>> getEnvironmentVariables(final
Map<String, Object> server, final int packageIndex) {
+ return (List<Map<String, Object>>)
getPackages(server).get(packageIndex).get("environmentVariables");
+ }
+
+ private Map<String, Object> getConfigEnvironmentVariable(final Map<String,
Object> server) {
+ return getEnvironmentVariables(server, 0).stream().filter(each ->
"SHARDINGSPHERE_MCP_CONFIG".equals(each.get("name"))).findFirst().orElseThrow();
+ }
+
private List<Object> getPackageValues(final Map<String, Object> server,
final String key) {
return getPackages(server).stream().map(each ->
each.get(key)).toList();
}
