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 260022e756f Refine ShardingSphere-MCP feature boundaries (#38781)
260022e756f is described below
commit 260022e756f88b8b423c7efd3447b4738689c787
Author: Liang Zhang <[email protected]>
AuthorDate: Wed Jun 3 10:04:07 2026 +0800
Refine ShardingSphere-MCP feature boundaries (#38781)
Update ShardingSphere-MCP Encrypt and Mask docs to describe natural-language
usage from the AI application integration perspective.
Remove outdated automatic rollback and planner input limit wording, and
replace it with SQL generation boundaries aligned with current identifier
handling.
Simplify troubleshooting docs by removing internal code-improvement notes
and
rewriting diagnostics as user-facing failure actions.
Apply the updates to both Chinese and English documentation.
---
.../shardingsphere-mcp/features/encrypt.cn.md | 7 +++---
.../shardingsphere-mcp/features/encrypt.en.md | 7 +++---
.../shardingsphere-mcp/features/mask.cn.md | 10 +++------
.../shardingsphere-mcp/features/mask.en.md | 10 +++------
.../shardingsphere-mcp/troubleshooting.cn.md | 26 +++++++++++-----------
.../shardingsphere-mcp/troubleshooting.en.md | 26 +++++++++++-----------
6 files changed, 38 insertions(+), 48 deletions(-)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.cn.md
index e9df7204fd4..ba7f6b07a1d 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.cn.md
@@ -15,7 +15,7 @@ weight = 2
## 通过自然语言使用
-用户在 MCP 客户端中描述加密目标即可。
+用户在集成 ShardingSphere-MCP 的 AI 应用中描述加密目标即可。
示例：
@@ -102,8 +102,7 @@ MCP 会根据逻辑列、用户意图和已有规则生成派生列建议。
### ShardingSphere 功能边界
- 不处理已有数据迁移或回填。
-- 不提供自动回滚。
-### 规划器输入限制
+### SQL 生成边界
-- 标识符不能包含反引号、NUL、回车或换行等无法生成可审查 SQL 的字符。
+- MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 标识符。为保证生成的 SQL 或 DistSQL
可审查，标识符内容不能包含反引号、NUL、回车或换行。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
index 9964f0ae0c0..5fd6b3080ac 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
@@ -15,7 +15,7 @@ Actual encryption capability is provided by
ShardingSphere-Proxy and its encrypt
## Use through natural language
-Users describe the encryption goal in the MCP client.
+Users describe the encryption goal in an AI application that integrates
ShardingSphere-MCP.
Examples:
@@ -102,8 +102,7 @@ For the general review flow of plugin changes, see [Plugin
Workflows](../plugin-
### ShardingSphere feature boundaries
- Existing data migration or backfill is not handled.
-- Automatic rollback is not provided.
-### Planner input limits
+### SQL generation boundaries
-- Identifier content must not contain backticks, NUL, carriage-return, or
line-feed characters because they cannot be rendered as reviewable SQL.
+- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode
identifiers. To keep generated SQL or DistSQL reviewable, identifier content
must not contain backticks, NUL, carriage returns, or line feeds.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
index e6d4f1b4550..bf89b3fe408 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
@@ -15,7 +15,7 @@ weight = 3
## 通过自然语言使用
-用户在 MCP 客户端中描述脱敏目标即可。
+用户在集成 ShardingSphere-MCP 的 AI 应用中描述脱敏目标即可。
示例：
@@ -87,10 +87,6 @@ weight = 3
- 逻辑列和规则校验以 Proxy 可见信息为准。
- 直连真实数据库只能执行普通 SQL，不代表脱敏规则状态。
-### ShardingSphere 功能边界
+### SQL 生成边界
-- 不提供自动回滚。
-
-### 规划器输入限制
-
-- 标识符不能包含反引号、NUL、回车或换行等无法生成可审查 SQL 的字符。
+- MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 标识符。为保证生成的 SQL 或 DistSQL
可审查，标识符内容不能包含反引号、NUL、回车或换行。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
index 8c8b86b9d07..9e1dcb8ede4 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
@@ -15,7 +15,7 @@ Mask rules apply directly to logical columns and do not
generate physical derive
## Use through natural language
-Users describe the masking goal in the MCP client.
+Users describe the masking goal in an AI application that integrates
ShardingSphere-MCP.
Examples:
@@ -87,10 +87,6 @@ For the general review flow of plugin changes, see [Plugin
Workflows](../plugin-
- Logical column and rule validation are based on what Proxy exposes.
- Direct physical database connections can execute ordinary SQL only and do
not represent masking rule state.
-### ShardingSphere feature boundaries
+### SQL generation boundaries
-- Automatic rollback is not provided.
-
-### Planner input limits
-
-- Identifier content must not contain backticks, NUL, carriage-return, or
line-feed characters because they cannot be rendered as reviewable SQL.
+- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode
identifiers. To keep generated SQL or DistSQL reviewable, identifier content
must not contain backticks, NUL, carriage returns, or line feeds.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
index f048100ace7..760d8a51c80 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -8,18 +8,18 @@ weight = 7
## 排查索引
-| 现象 | 可能原因 | 处理方式 | 是否需要代码改进 |
-| --- | --- | --- | --- |
-| 启动失败 | JDK、配置路径、YAML 字段或必填字段不正确。 | 查看终端错误和 `logs/mcp.log`。 | 通常不需要。 |
-| HTTP 无法连接 | 端口、端点路径、传输方式或绑定地址不正确。 | 检查 `port`、`endpointPath`、`bindHost` 和客户端
URL。 | 通常不需要。 |
-| HTTP 返回 403 | 请求 `Origin` 与绑定地址安全策略不匹配。 | 本机调试用回环地址；远程访问走受控网关；详细原因看服务端日志。 |
通常不需要。 |
-| 会话请求失败 | 未初始化、缺少会话头，或复用已关闭会话。 | 先调用 `initialize`，后续请求持续携带响应头。 | 通常不需要。 |
-| STDIO 没有响应 | 被当成人工交互 Shell，或客户端未按 MCP stdio 协议发送 JSON-RPC。 | 由 MCP
客户端拉起进程；诊断信息看 stderr 或日志。 | 通常不需要。 |
-| 逻辑库或元数据为空 | 未配置逻辑库、逻辑库名称不正确、连接失败、权限不足，或目标范围确实为空。 | 先读
`shardingsphere://runtime`，再看资源返回的 `empty_state` 和 `recovery`。 | 通常不需要。 |
-| JDBC 驱动错误 | 驱动不在类路径，或 `driverClassName` 不正确。 | 把驱动 jar 放入 `plugins/`，并确认
`driverClassName` 非空且类名正确。 | 通常不需要。 |
-| SQL 工具调用失败 | 工具选错、多语句被拒绝或参数超限。 | 查询用 `execute_query`；有副作用 SQL 用
`execute_update` 并先预览。 | 通常不需要；错误消息可增强。 |
-| 工作流失败 | `plan_id`、会话、执行模式或人工执行步骤不正确。 | 同一会话内复用 `plan_id`；先预览；人工执行后再校验。 |
通常不需要。 |
-| 敏感输入无法传递 | 补问要求密钥或凭证。 | 由客户端或运维侧取值，再通过受保护 MCP 调用传入。 | 如需服务端解析密钥引用，需要改代码。 |
+| 现象 | 可能原因 | 处理方式 |
+| --- | --- | --- |
+| 启动失败 | JDK、配置路径、YAML 字段或必填字段不正确。 | 查看终端错误和 `logs/mcp.log`。 |
+| HTTP 无法连接 | 端口、端点路径、传输方式或绑定地址不正确。 | 检查 `port`、`endpointPath`、`bindHost` 和客户端
URL。 |
+| HTTP 返回 403 | 请求 `Origin` 与绑定地址安全策略不匹配。 | 本机调试用回环地址；远程访问走受控网关；详细原因看服务端日志。 |
+| 会话请求失败 | 未初始化、缺少会话头，或复用已关闭会话。 | 先调用 `initialize`，后续请求持续携带响应头。 |
+| STDIO 没有响应 | 被当成人工交互 Shell，或客户端未按 MCP stdio 协议发送 JSON-RPC。 | 由 MCP
客户端拉起进程；诊断信息看 stderr 或日志。 |
+| 逻辑库或元数据为空 | 未配置逻辑库、逻辑库名称不正确、连接失败、权限不足，或目标范围确实为空。 |
先查看运行时状态，确认数据库配置、逻辑库名称、连接错误分类和账号权限。 |
+| JDBC 驱动错误 | 驱动不在类路径，或 `driverClassName` 不正确。 | 把驱动 jar 放入 `plugins/`，并确认
`driverClassName` 非空且类名正确。 |
+| SQL 工具调用失败 | 工具选错、多语句被拒绝或参数超限。 | 查询用 `execute_query`；有副作用 SQL 用
`execute_update` 并先预览。 |
+| 工作流失败 | `plan_id`、会话、执行模式或人工执行步骤不正确。 | 同一会话内复用 `plan_id`；先预览；人工执行后再校验。 |
+| 敏感输入无法传递 | 补问要求密钥或凭证。 | 通过客户端、密钥管理系统或运维控制通道取得真实值，再在受保护调用或人工执行环节传入。 |
补充说明：
@@ -72,5 +72,5 @@ weight = 7
- 传输方式和端点。
- 是否已完成 `initialize`，不要公开真实 `MCP-Session-Id`。
- 工具或资源请求体。
-- JSON-RPC 错误负载。
+- 错误响应内容，包含错误分类和提示信息。
- `logs/mcp.log` 中相关错误。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
index dea9ccfa7b1..4514e042d4d 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -8,18 +8,18 @@ For feature-specific business rule issues, see the
corresponding feature plugin
## Troubleshooting index
-| Symptom | Possible cause | Action | Needs code improvement |
-| --- | --- | --- | --- |
-| Startup failure | JDK, config path, YAML field, or required field is wrong.
| Inspect terminal output and `logs/mcp.log`. | Usually no. |
-| HTTP connection failure | Port, endpoint path, transport type, or bind
address is wrong. | Check `port`, `endpointPath`, `bindHost`, and client URL. |
Usually no. |
-| HTTP 403 response | Request `Origin` does not match the bind-address policy.
| Use loopback locally; use a controlled gateway for remote access; inspect
server logs for the safe reason category. | Usually no. |
-| Session request failure | Session was not initialized, headers are missing,
or a closed session is reused. | Call `initialize` first and keep sending the
response headers. | Usually no. |
-| No response in STDIO mode | STDIO is used as a shell, or the client does not
send JSON-RPC over MCP stdio. | Let an MCP client launch the process; read
stderr or logs for diagnostics. | Usually no. |
-| Logical database or metadata is empty | No logical database is configured,
the logical database name is wrong, connection failed, permission is
insufficient, or the target scope is empty. | Read `shardingsphere://runtime`,
then inspect `empty_state` and `recovery` in resource responses. | Usually no. |
-| JDBC driver error | Driver is not on classpath, or `driverClassName` is
wrong. | Put the driver jar under `plugins/`, and keep `driverClassName`
non-empty and correct. | Usually no. |
-| SQL tool call failure | Wrong tool, multiple statements, or argument out of
range. | Use `execute_query` for queries; use `execute_update` with preview for
side effects. | Usually no; messages can improve. |
-| Workflow failure | `plan_id`, session, execution mode, or manual step is
wrong. | Reuse `plan_id` in one session; preview first; validate after manual
execution. | Usually no. |
-| Secret input cannot be passed safely | A clarification asks for a key or
credential. | Resolve it outside the server, then pass it through a protected
MCP call. | Server-side secret references require code changes. |
+| Symptom | Possible cause | Action |
+| --- | --- | --- |
+| Startup failure | JDK, config path, YAML field, or required field is wrong.
| Inspect terminal output and `logs/mcp.log`. |
+| HTTP connection failure | Port, endpoint path, transport type, or bind
address is wrong. | Check `port`, `endpointPath`, `bindHost`, and client URL. |
+| HTTP 403 response | Request `Origin` does not match the bind-address policy.
| Use loopback locally; use a controlled gateway for remote access; inspect
server logs for the safe reason category. |
+| Session request failure | Session was not initialized, headers are missing,
or a closed session is reused. | Call `initialize` first and keep sending the
response headers. |
+| No response in STDIO mode | STDIO is used as a shell, or the client does not
send JSON-RPC over MCP stdio. | Let an MCP client launch the process; read
stderr or logs for diagnostics. |
+| Logical database or metadata is empty | No logical database is configured,
the logical database name is wrong, connection failed, permission is
insufficient, or the target scope is empty. | Check runtime status, then verify
database configuration, logical database name, connection failure category, and
account privileges. |
+| JDBC driver error | Driver is not on classpath, or `driverClassName` is
wrong. | Put the driver jar under `plugins/`, and keep `driverClassName`
non-empty and correct. |
+| SQL tool call failure | Wrong tool, multiple statements, or argument out of
range. | Use `execute_query` for queries; use `execute_update` with preview for
side effects. |
+| Workflow failure | `plan_id`, session, execution mode, or manual step is
wrong. | Reuse `plan_id` in one session; preview first; validate after manual
execution. |
+| Secret input cannot be passed safely | A clarification asks for a key or
credential. | Resolve the value through the client, a key management system, or
an operations control channel, then pass it through a protected call or manual
execution step. |
Additional notes:
@@ -72,5 +72,5 @@ When reporting an issue, provide:
- Transport type and endpoint.
- Whether `initialize` has completed. Do not publish a real `MCP-Session-Id`.
- Tool or resource request body.
-- JSON-RPC error payload.
+- Error response content, including the failure category and guidance.
- Relevant errors from `logs/mcp.log`.
