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 eea07bc095b Align public contract documentation (#38725)
eea07bc095b is described below
commit eea07bc095b040eb7c22a80825acd9a8f1d1560e
Author: Liang Zhang <[email protected]>
AuthorDate: Tue May 26 22:45:25 2026 +0800
Align public contract documentation (#38725)
* Remove slack because workspace has been disabled
* Refactor MCPToolClarificationPolicy
* mcp: Align public contract documentation
Clarify MCP V1 submit-ready scope in README files and historical design
documents. Mark early tool matrices and bare execute_query references as
historical context, and point the current contract to descriptor-first
resources and database_gateway_* tools.
Also align the extension directory wording from ext-lib to plugins.
* mcp: Align public contract documentation
Clarify MCP V1 submit-ready scope in README files and historical design
documents. Mark early tool matrices and bare execute_query references as
historical context, and point the current contract to descriptor-first
resources and database_gateway_* tools.
Also align the extension directory wording from ext-lib to plugins.
* for code format
* for code format
---
docs/mcp/ShardingSphere-MCP-Detailed-Design.md | 27 ++++++++++------
docs/mcp/ShardingSphere-MCP-PRD.md | 33 ++++++++++++++------
docs/mcp/ShardingSphere-MCP-Technical-Design.md | 41 +++++++++++++++----------
mcp/README.md | 6 +++-
mcp/README_ZH.md | 8 ++++-
5 files changed, 78 insertions(+), 37 deletions(-)
diff --git a/docs/mcp/ShardingSphere-MCP-Detailed-Design.md
b/docs/mcp/ShardingSphere-MCP-Detailed-Design.md
index 500f39bad3b..e660e464e53 100644
--- a/docs/mcp/ShardingSphere-MCP-Detailed-Design.md
+++ b/docs/mcp/ShardingSphere-MCP-Detailed-Design.md
@@ -1,6 +1,9 @@
# ShardingSphere MCP 详细设计说明书
-> 状态说明：本文档保留早期详细设计背景，不是当前 MCP public surface 契约。当前契约以
`shardingsphere://capabilities`、descriptor、`mcp/README.md` 和 `mcp/README_ZH.md`
为准；不要从本文档推导 `list_databases`、`describe_table` 等早期工具矩阵。
+> 状态说明：本文档保留早期详细设计背景，不是当前 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 详细设计说明书
@@ -175,7 +178,7 @@ shardingsphere
- metadata discovery facade
- JDBC metadata discovery and runtime configuration
- `execute`
- - `execute_query` facade
+ - SQL tool facade
- `DatabaseRuntime` assembly and JDBC-backed runtime context factory
- `trace`
- SQL execution trace facade
@@ -380,10 +383,13 @@ stateDiagram-v2
3. 应用部署时覆盖项
4. 生成数据库级 capability
-## 10. `execute_query` 详细设计
+## 10. SQL tool 详细设计
+
+> 本节保留早期 `execute_query` 术语。
+> 当前 MCP public surface 将读查询与变更执行拆分为 `database_gateway_execute_query` 和
`database_gateway_execute_update`。
### 10.1 职责
-- `execute_query` 负责：
+- 当前 SQL tool facade 负责：
- 单语句校验
- statement class 归类
- request-level schema semantics 解释
@@ -404,7 +410,7 @@ stateDiagram-v2
6. result / error mapping
### 10.2A `database` / `schema` 边界
-- `database` 是 `execute_query` 的唯一强执行边界。
+- `database` 是当前 SQL tools 的唯一强执行边界。
- `schema` 是可选 namespace hint，用于表达未限定对象名的目标命名空间意图。
- 当数据库级 capability `schema_execution_semantics = fixed_to_database` 时，
request-level `schema` 不被承诺为独立执行命名空间切换器。
@@ -521,7 +527,7 @@ stateDiagram-v2
- capability assembler
- transaction matrix registry
- session manager
- - `execute_query` facade
+ - SQL tool facade
- error mapper
### 13.3 模块集成测试重点
@@ -579,7 +585,10 @@ stateDiagram-v2
- E. capability 组
- capability 与矩阵一致
-### 13.8 E2E 最小冒烟场景
+### 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
@@ -634,7 +643,7 @@ apache-shardingsphere-mcp-<version>/
3. `mcp/core` 的 capability / error / session
4. `mcp/bootstrap` 的 HTTP / STDIO transport
5. `/mcp` 的 Streamable HTTP endpoint
- 6. `execute_query` 与 metadata discovery
+ 6. SQL tool pair 与 metadata discovery
7. `distribution/mcp`
8. 单元测试
9. 模块集成测试
@@ -650,7 +659,7 @@ apache-shardingsphere-mcp-<version>/
- `DELETE /mcp` 会话关闭行为已定
- SDK provider 与 ShardingSphere glue 的职责边界已定
- transaction matrix 存储方式已定
- - capability / `execute_query` 输入输出边界已定
+ - capability / SQL tool 输入输出边界已定
### 16.1 AI-Friendly 增量开工前重新取证
diff --git a/docs/mcp/ShardingSphere-MCP-PRD.md
b/docs/mcp/ShardingSphere-MCP-PRD.md
index 60e5f7fd598..8fd1eda91bf 100644
--- a/docs/mcp/ShardingSphere-MCP-PRD.md
+++ b/docs/mcp/ShardingSphere-MCP-PRD.md
@@ -1,6 +1,9 @@
# ShardingSphere MCP PRD
-> 状态说明：本文档保留早期 PRD 背景，不是当前 MCP public surface 契约。当前契约以
`shardingsphere://capabilities`、descriptor、`mcp/README.md` 和 `mcp/README_ZH.md`
为准；不要从本文档推导 `list_*`、`describe_*` 等早期工具矩阵。
+> 状态说明：本文档保留早期 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
@@ -120,7 +123,7 @@
## 10. 对象语义定义
- `database`：MCP 对外暴露的一级访问目标，也是每次 SQL 执行必须显式指定的目标。
-- `schema`：`database` 内部命名空间；在 `execute_query` 中只作为可选 namespace
hint，不是第二个强执行边界。
+- `schema`：`database` 内部命名空间；在当前 SQL tools 中只作为可选 namespace hint，不是第二个强执行边界。
- `table / view`：通过 `(database, schema, name)` 唯一确定。
- `column`：从属于某个表或视图。
- `index`：从属于某个表，仅在当前 `database` 支持时暴露。
@@ -160,7 +163,9 @@
- 凡列为 V1 公共对象者，必须在 `resources` 和 / 或 `tools` 中有正式承载路径。
- 当当前 `database` 的 `supported_object_types` 不包含 `index` 时，`index` 相关
`resources` 统一返回 `unsupported`。
-## 12. V1 公共 Tools
+## 12. 历史 V1 公共 Tools 设想（非当前契约）
+
+> 本节记录早期 PRD 工具拆分设想。当前 public tools 以 `mcp/README.md`、`mcp/README_ZH.md` 和
descriptors 中的 `database_gateway_*` 工具为准。
### 正式工具清单
- `list_databases`
@@ -233,15 +238,18 @@
- 该行为不等同于跨 `database` SQL 执行。
- 当 `schema` 被指定时，`database` 必须同时指定，否则返回 `invalid_request`。
-## 14. SQL 执行能力
-- SQL 执行通过 `execute_query` 统一暴露。
+## 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`。
-- 事务存续期间若 `execute_query` 指定其他 `database`，统一返回 `conflict`。
+- 事务存续期间若 SQL tool 指定其他 `database`，统一返回 `conflict`。
## 15. V1 允许的 SQL 类型
@@ -339,7 +347,7 @@
但 data-modifying CTE 等场景允许 `statement_class = dml` 且返回 `result_set`。
- `CREATE`、`ALTER`、`DROP`、`TRUNCATE`、`GRANT`、`REVOKE`、事务控制语句默认返回
`statement_ack`。
- `EXPLAIN ANALYZE` 的返回形态由数据库级 `capability` 决定。
-- 一次 `execute_query` 只返回一个结果对象。
+- 一次 SQL tool call 只返回一个结果对象。
- V1 不支持多结果集返回。
## 18. 统一结果数据类型约束
@@ -387,7 +395,7 @@
### 19.4 说明
- `default_autocommit` 指 ShardingSphere MCP 会话默认行为，不等同于底层数据库原生默认 `autocommit`。
- `default_schema_semantics` 解决 metadata/discovery 侧的统一 schema 语义。
-- `schema_execution_semantics` 解决 `execute_query.schema` 在执行时如何解释。
+- `schema_execution_semantics` 解决 SQL tool request-level `schema` 在执行时如何解释。
- 对原生支持事务控制的 `database`，`supports_transaction_control = true`。
- 对原生不支持事务控制的 `database`，`supports_transaction_control = false`。
- 对原生支持 `savepoint` 的 `database`，`supports_savepoint = true`。
@@ -459,7 +467,10 @@
- 当前 `database` 不支持事务控制时执行事务控制语句，返回 `unsupported`。
- 当前 `database` 不支持 `savepoint` 时执行 `savepoint` 语句，返回 `unsupported`。
-## 25. V1 最低统一能力基线
+## 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`
@@ -516,7 +527,9 @@
- DDL、DCL、`EXPLAIN ANALYZE` 在事务中的行为以数据库级 `capability` 为准。
- `index` 相关能力仅在 `supported_object_types` 包含 `index` 时暴露。
-## 30. 压缩版需求清单
+## 30. 历史压缩版需求清单（非当前提交门禁）
+
+> 本清单保留早期目标，不表示当前提交必须完成完整统一治理能力。
1. 必须提供统一数据库访问与 SQL 执行公共面。
2. 必须统一 `database / schema / table / view / column / capability` 对象语义。
3. `index` 必须作为数据库级可选公共对象，通过 `capability` 明确声明。
diff --git a/docs/mcp/ShardingSphere-MCP-Technical-Design.md
b/docs/mcp/ShardingSphere-MCP-Technical-Design.md
index 0b7ec0ed921..6c0bc30cb9c 100644
--- a/docs/mcp/ShardingSphere-MCP-Technical-Design.md
+++ b/docs/mcp/ShardingSphere-MCP-Technical-Design.md
@@ -1,6 +1,9 @@
# ShardingSphere MCP 技术设计方案
-> 状态说明：本文档保留早期技术设计背景，不是当前 MCP public surface 契约。当前契约以
`shardingsphere://capabilities`、descriptor、`mcp/README.md` 和 `mcp/README_ZH.md`
为准；不要从本文档推导早期工具矩阵或额外兼容层。
+> 状态说明：本文档保留早期技术设计背景，不是当前 MCP public surface 契约。
+> 当前契约以 `shardingsphere://capabilities`、descriptor、`mcp/README.md` 和
`mcp/README_ZH.md` 为准。
+> 不要从本文档推导早期工具矩阵或额外兼容层。
+> 当前可提交范围是 MCP V1 runtime readiness，不是完整 ShardingSphere governance
administration surface。
## 1. 文档信息
- 文档名称：ShardingSphere MCP 技术设计方案
@@ -28,7 +31,7 @@
- 根据前期 PRD，ShardingSphere MCP 要解决的不是“把 MCP 跑起来”，而是形成正式的数据库统一 AI/Agent 接入面，覆盖：
- 统一 metadata 发现
- 统一 capability 声明
- - 统一 SQL 执行入口 `execute_query`
+ - 统一 SQL 执行入口的早期设想；当前 public tools 使用 `database_gateway_execute_query` 与
`database_gateway_execute_update`
- 统一错误模型
- 统一事务与 `savepoint` 能力边界
- 统一 SQL execution trace 与治理可见性
@@ -48,7 +51,7 @@
- MCP 进入主仓库
- 不破坏根工程 Java 8 默认构建
- 保持与现有 distribution 结构一致
- - 覆盖 PRD 中定义的 `capability / execute_query / transaction semantics`
+ - 覆盖当前 descriptor public surface 中的 capability、SQL execution 与 transaction
semantics
## 4. 目标
- 本方案目标如下：
@@ -58,7 +61,8 @@
- 形成独立部署、独立运行、独立发布的 MCP 服务。
- 支撑 PRD 中定义的：
- `capability`
- - `execute_query`
+ - `database_gateway_execute_query`
+ - `database_gateway_execute_update`
- `transaction matrix`
- `SQL execution trace`
- 统一错误模型
@@ -209,7 +213,7 @@ shardingsphere
- MCP 公共对象模型
- capability 组装
- metadata discovery facade
-- execute_query facade
+- SQL tool facade
- session / transaction facade
- session lifecycle registry
- resource URI resolver
@@ -298,7 +302,7 @@ shardingsphere
- `/mcp` Streamable HTTP 会话初始化与关闭
- STDIO 本地调试入口
- metadata discovery
- - `execute_query`
+ - SQL tool pair
- SQL execution trace 与变化可见性
#### 9.1.4 Rollback Guidance
@@ -430,7 +434,7 @@ flowchart TB
- 统一提供：
- metadata discovery
- capability
- - execute_query
+ - SQL tool pair
- transaction / savepoint handling
#### ShardingSphere Integration Layer
@@ -481,10 +485,13 @@ flowchart TB
- `index` 由数据库级 capability 的 `supported_object_types` 声明
- 不支持时 direct API 返回 `unsupported`
-## 13. `execute_query` 统一执行入口设计
+## 13. SQL 执行入口设计
+
+> 本节标题和部分正文保留早期 `execute_query` 术语。
+> 当前 MCP public surface 将读查询与变更执行拆分为 `database_gateway_execute_query` 和
`database_gateway_execute_update`。
### 13.1 设计原则
-- `execute_query` 是 V1 唯一 SQL 执行入口。
+- 早期 `execute_query` 设计已收敛为当前 descriptor 中的 SQL tool pair。
- 它不是 SQL 透传接口，而是统一执行与治理入口。
- `database` 是唯一强执行边界。
- `schema` 是可选 namespace hint，不是第二个强路由键。
@@ -620,9 +627,11 @@ flowchart TB
### 16.2.1 默认发行包启动面
- distribution 默认启动使用 HTTP 配置，STDIO 通过 `conf/mcp-stdio.yaml` 或
`SHARDINGSPHERE_MCP_TRANSPORT=stdio` 显式选择。
-- 默认 `conf/mcp-http.yaml` 内置一段 demo JDBC runtime，用于首次启动时验证非空 metadata 和真实
`execute_query` 行为。
-- `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 驱动，可放入发行包根目录下的 `ext-lib/`。
+- 默认 `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 服务集群
@@ -670,7 +679,7 @@ sequenceDiagram
participant F as Metadata Facade
participant S as ShardingSphere Metadata
- C->>M: list_tables / list_views / search_metadata
+ C->>M: resources/read or database_gateway_search_metadata
M->>F: metadata discovery
F->>S: metadata 查询
S-->>F: 可访问对象
@@ -686,7 +695,7 @@ sequenceDiagram
participant E as ExecuteQuery Facade
participant S as ShardingSphere Core
- C->>M: execute_query(database, schema?, sql)
+ C->>M: database_gateway_execute_query or database_gateway_execute_update
M->>E: 执行统一 SQL 请求
E->>S: parse / route / execute
S-->>E: raw result
@@ -817,7 +826,7 @@ apache-shardingsphere-mcp-<version>/
- 完成 capability 组装链
- 完成统一 error model
- 阶段 3：执行与治理
- - 完成 `execute_query`
+ - 完成 SQL tool pair
- 完成事务能力矩阵
- 完成 SQL execution trace 治理可见性链路
- 阶段 4：部署与联调
@@ -832,7 +841,7 @@ apache-shardingsphere-mcp-<version>/
- 是否未反向污染主仓库 Java 8 主线
- 是否使用官方 SDK 而非自研协议实现
- capability 是否实现分层清晰
- - `execute_query` 是否成为统一执行入口
+ - 当前 SQL tool pair 是否覆盖查询与变更执行入口
- 事务能力矩阵是否显式维护
- HTTP 会话与事务语义是否闭合
- distribution 是否形成独立运维单元
diff --git a/mcp/README.md b/mcp/README.md
index 33813f3d78e..4228a0ffc65 100644
--- a/mcp/README.md
+++ b/mcp/README.md
@@ -118,7 +118,8 @@ Expected result:
Notes:
- Metadata list/detail/capability discovery is unified through
`resources/read`.
-- The current public tools are `database_gateway_search_metadata`,
`database_gateway_execute_query`, `database_gateway_execute_update`,
`database_gateway_plan_encrypt_rule`, `database_gateway_plan_mask_rule`,
`database_gateway_apply_workflow`, and `database_gateway_validate_workflow`.
+- The current public tools are `database_gateway_search_metadata`,
`database_gateway_execute_query`, `database_gateway_execute_update`,
+ `database_gateway_plan_encrypt_rule`, `database_gateway_plan_mask_rule`,
`database_gateway_apply_workflow`, and `database_gateway_validate_workflow`.
- `database_gateway_execute_query` accepts classifier-approved `SELECT` and
`EXPLAIN ANALYZE` statements only, and rejects known side-effecting query forms.
Use `database_gateway_execute_update` for DML, DDL, DCL, transaction
control, savepoints, and other supported side-effecting SQL.
- SQL execution classification recognizes qualified and quoted object names
only for safety checks and cross-schema guarding.
@@ -229,6 +230,9 @@ ShardingSphere MCP targets MCP protocol revision
`2025-11-25`. The public protoc
### ShardingSphere Feature Scope
+This submit-ready scope is MCP V1 runtime readiness, not a complete
ShardingSphere governance administration surface.
+The current public contract is descriptor-first and resource-first, with the
`database_gateway_*` tools listed above as the supported tool entry points.
+
The runtime exposes ShardingSphere through logical database metadata, safe SQL
tools, and selected workflow helpers. Current V1 scope:
- Supported: logical database discovery; schemas, tables, views, columns,
indexes, and sequences where JDBC metadata and dialect capability permit;
diff --git a/mcp/README_ZH.md b/mcp/README_ZH.md
index 4b7d25b3a91..6eb62b22aa7 100644
--- a/mcp/README_ZH.md
+++ b/mcp/README_ZH.md
@@ -117,7 +117,8 @@ curl -sS http://127.0.0.1:18088/mcp \
说明：
- metadata 的 list / detail / capability discovery 统一走 `resources/read`。
-- 当前 public tools 包括
`database_gateway_search_metadata`、`database_gateway_execute_query`、`database_gateway_execute_update`、`database_gateway_plan_encrypt_rule`、`database_gateway_plan_mask_rule`、`database_gateway_apply_workflow`
和 `database_gateway_validate_workflow`。
+- 当前 public tools 包括
`database_gateway_search_metadata`、`database_gateway_execute_query`、`database_gateway_execute_update`、
+
`database_gateway_plan_encrypt_rule`、`database_gateway_plan_mask_rule`、`database_gateway_apply_workflow`
和 `database_gateway_validate_workflow`。
- `database_gateway_execute_query` 只接受分类器批准的 `SELECT` 和 `EXPLAIN
ANALYZE`，并拒绝已知有副作用的查询形态；
DML、DDL、DCL、事务控制、savepoint 以及其他支持的有副作用 SQL 要使用
`database_gateway_execute_update`。
- SQL 执行分类会识别限定名和带引号对象名，但用途仅限安全分类与跨 schema 防护；
@@ -212,6 +213,11 @@ Descriptor annotations 遵循 MCP `2025-11-25` schema，并且属于开发者维
- MCP `icons` 和 `Tool.execution` 是官方 `2025-11-25` descriptor 字段，但 MCP Java SDK
`1.1.2` 尚未在 `Resource`、`ResourceTemplate` 或 `Tool` 中暴露 `icons`，也尚未在 `Tool` 中暴露
`execution`；
在 SDK 边界支持前，它们属于后续范围。
+### 当前提交范围
+
+本次可提交范围是 MCP V1 runtime readiness，不是完整的 ShardingSphere 治理管理入口。
+当前 public contract 以 descriptor 和 resource-first discovery 为准，并以上文列出的
`database_gateway_*` tools 作为正式 tool 入口。
+
### 读取 `shardingsphere://databases/orders/schemas/public/sequences`
```bash
