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 5504a1ad856 Refine documentation (#38764)
5504a1ad856 is described below
commit 5504a1ad85647008ed69e8dbd71e4f48fba5a685
Author: Liang Zhang <[email protected]>
AuthorDate: Sun May 31 12:22:03 2026 +0800
Refine documentation (#38764)
* Refactor MCPToolElicitationHandler
* Refactor MCPToolElicitationHandler
* Refactor MCPToolElicitationHandler
* Refactor MCPToolElicitationHandler
* Refactor MCPToolElicitationHandler
* Refactor MCPToolElicitationHandler
* Refine documentation
---
.../user-manual/shardingsphere-mcp/_index.cn.md | 19 +-
.../user-manual/shardingsphere-mcp/_index.en.md | 19 +-
.../shardingsphere-mcp/client-integration.cn.md | 59 +-----
.../shardingsphere-mcp/client-integration.en.md | 59 +-----
.../shardingsphere-mcp/features/_index.cn.md | 2 +-
.../shardingsphere-mcp/features/_index.en.md | 2 +-
.../shardingsphere-mcp/features/encrypt.cn.md | 145 +++++++--------
.../shardingsphere-mcp/features/encrypt.en.md | 143 +++++++-------
.../shardingsphere-mcp/features/mask.cn.md | 206 +++++++++------------
.../shardingsphere-mcp/features/mask.en.md | 206 +++++++++------------
.../plugin-workflow.cn.md} | 2 +-
.../plugin-workflow.en.md} | 2 +-
12 files changed, 361 insertions(+), 503 deletions(-)
diff --git a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
index d5e518b4804..5bf73d625c5 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
@@ -11,13 +11,28 @@ ShardingSphere-MCP 为大模型和 Agent 提供一条受控访问 ShardingSphere
ShardingSphere-MCP 的配置以数据库为核心：先配置 MCP Server 可以连接的 ShardingSphere 逻辑库，再通过 MCP
客户端读取元数据或调用 SQL 工具。
+## 通过自然语言使用 MCP
+
+ShardingSphere-MCP 面向支持 MCP 的模型客户端、IDE 插件和 Agent 平台使用。
+完成客户端集成后，用户在模型对话中描述数据库任务，模型会根据任务主动读取资源、调用工具、请求补全或生成插件工作流计划。
+普通用户不需要手工拼接 JSON-RPC 请求、记住资源 URI，或直接选择底层工具。
+
+常见任务示例：
+
+- 查看 `<logic-database>` 中有哪些表。
+- 查询 `<table-name>` 的字段、索引和表结构。
+- 检查 `<table-name>` 当前是否已有加密或脱敏规则。
+- 为 `<table-name>.<column-name>` 规划脱敏规则，先预览不要执行。
+- 确认刚才的治理变更计划，并校验执行结果。
+
+有副作用的任务应先生成或预览计划，由用户审查变更内容后再执行。
+
## 文档结构
- 快速开始：构建发行包，配置一个可连接的逻辑库，启动 HTTP MCP Server，并验证元数据读取和只读 SQL 查询。
- 功能介绍：说明 MCP Server 对外提供的资源、工具、提示、补全和工作流能力。
- 配置说明：说明传输方式、`runtimeDatabases`、插件目录和启动参数。
- 客户端集成：说明 HTTP、STDIO、会话响应头和能力发现调用方式。
-- 插件工作流：说明功能插件共享的规划、执行和校验阶段。
-- 功能插件：说明官方 MCP 功能插件能力。
+- 功能插件：说明官方 MCP 功能插件能力，以及插件工作流共享的规划、执行和校验阶段。
- 部署说明：说明发行包、OCI 镜像和安全部署建议。
- 常见问题：排查 MCP Server、传输方式、会话和 SQL 工具的通用问题。
diff --git a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
index 41d2876cf75..934268a8313 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
@@ -11,13 +11,28 @@ Through an MCP client, a model can actively discover
database structure, read go
ShardingSphere-MCP configuration starts from databases: configure the
ShardingSphere logical databases that the MCP Server can connect to, then read
metadata or call SQL tools through an MCP client.
+## Use MCP through natural language
+
+ShardingSphere-MCP is designed for model clients, IDE extensions, and agent
platforms that support MCP.
+After client integration, users describe database tasks in the model
conversation, and the model can read resources, call tools, request
completions, or create plugin workflow plans as needed.
+Regular users do not need to hand-write JSON-RPC requests, remember resource
URIs, or directly choose low-level tools.
+
+Common task examples:
+
+- Show the tables in `<logic-database>`.
+- Inspect columns, indexes, and structure for `<table-name>`.
+- Check whether `<table-name>` already has encryption or masking rules.
+- Plan a masking rule for `<table-name>.<column-name>` and preview it without
execution.
+- Confirm the previous governance change plan and validate the result.
+
+Tasks with side effects should create or preview a plan first, then run only
after the user reviews the changes.
+
## Structure
- Quick Start: build the distribution, configure a reachable logical database,
start the HTTP MCP Server, and verify metadata reads and read-only SQL queries.
- Capabilities: understand the resources, tools, prompts, completions, and
workflows exposed by the MCP Server.
- Configuration: configure transport, `runtimeDatabases`, plugin directories,
and launch parameters.
- Client Integration: use HTTP, STDIO, session response headers, and
capability discovery calls.
-- Plugin Workflows: understand the shared planning, apply, and validation
phases used by feature plugins.
-- Feature Plugins: use official MCP feature plugins.
+- Feature Plugins: use official MCP feature plugins and understand the shared
planning, apply, and validation phases used by plugin workflows.
- Deployment: deploy the binary distribution and OCI image safely.
- Troubleshooting: diagnose common MCP Server, transport, session, and SQL
tool issues.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
index 11692d6bbc0..bc049593d67 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
@@ -73,56 +73,17 @@ STDIO 模式下：
- 诊断日志写到 stderr 或 `logs/mcp.log`。
- 客户端配置中的 `command` 和 `args` 应指向发行包内的启动脚本和 STDIO 配置文件。
-## 协议调用示例
+## 集成后的使用方式
-使用现成 MCP 客户端或 Agent 平台时，用户通常通过自然语言提出任务，例如“查看逻辑库有哪些表”或“查询订单表的字段”。
-客户端会根据模型选择自动发送 MCP 协议请求，用户不需要把下面的 JSON 粘贴到模型对话框。
-下面的示例用于说明客户端背后发送的协议消息，适合客户端开发、集成调试或排查问题。
+客户端完成 MCP Server 配置后，用户在模型对话中直接描述任务。
+客户端负责会话初始化、能力发现、补全和工具调用；模型根据任务选择读取资源或调用工具。
-读取服务状态：
+示例：
-```json
-{"jsonrpc":"2.0","id":"runtime-1","method":"resources/read","params":{"uri":"shardingsphere://runtime"}}
-```
-
-读取能力目录：
-
-```json
-{"jsonrpc":"2.0","id":"capabilities-1","method":"resources/read","params":{"uri":"shardingsphere://capabilities"}}
-```
+- 查看 `<logic-database>` 中有哪些表。
+- 查询 `<table-name>` 的字段和索引。
+- 执行一条只读查询，并限制返回 100 行。
+- 规划一个数据加密或数据脱敏规则，先预览不要执行。
-搜索元数据：
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "search-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_search_metadata",
- "arguments": {
- "database": "<logic-database>",
- "query": "<metadata-keyword>",
- "object_types": ["table"]
- }
- }
-}
-```
-
-执行只读 SQL：
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "query-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_execute_query",
- "arguments": {
- "database": "<logic-database>",
- "sql": "SELECT * FROM <table-name> LIMIT 100",
- "max_rows": 100
- }
- }
-}
-```
+如果客户端提供工具调用审批界面，应重点审查 SQL 执行、规则变更、插件工作流执行等有副作用的调用。
+自研客户端或协议调试场景，可结合[能力清单](../capabilities/)确认资源、工具、提示和补全目标。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
index e35c74092a8..5378714c44b 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
@@ -73,56 +73,17 @@ In STDIO mode:
- Diagnostics are written to stderr or `logs/mcp.log`.
- `command` and `args` in the client configuration should point to the
packaged startup script and STDIO config file.
-## Protocol call examples
+## Using the integration
-When using an existing MCP client or agent platform, users usually describe
tasks in natural language, such as "show tables in the logical database" or
"inspect columns in the orders table".
-The client sends MCP protocol requests automatically based on the model's
choices. Users do not paste the following JSON into a model chat.
-The examples below show protocol messages sent behind the scenes, and are
useful for client development, integration debugging, or troubleshooting.
+After the client is configured with the MCP Server, users describe tasks
directly in the model conversation.
+The client handles session initialization, capability discovery, completion,
and tool calls; the model chooses which resources to read or which tools to
call.
-Read runtime status:
+Examples:
-```json
-{"jsonrpc":"2.0","id":"runtime-1","method":"resources/read","params":{"uri":"shardingsphere://runtime"}}
-```
-
-Read the capability catalog:
-
-```json
-{"jsonrpc":"2.0","id":"capabilities-1","method":"resources/read","params":{"uri":"shardingsphere://capabilities"}}
-```
+- Show the tables in `<logic-database>`.
+- Inspect columns and indexes for `<table-name>`.
+- Run a read-only query and limit the result to 100 rows.
+- Plan a data encryption or data masking rule and preview it without execution.
-Search metadata:
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "search-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_search_metadata",
- "arguments": {
- "database": "<logic-database>",
- "query": "<metadata-keyword>",
- "object_types": ["table"]
- }
- }
-}
-```
-
-Execute read-only SQL:
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "query-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_execute_query",
- "arguments": {
- "database": "<logic-database>",
- "sql": "SELECT * FROM <table-name> LIMIT 100",
- "max_rows": 100
- }
- }
-}
-```
+If the client provides a tool approval UI, pay special attention to
side-effecting calls such as SQL execution, rule changes, and plugin workflow
execution.
+For custom clients or protocol debugging, use the [Capability
Catalog](../capabilities/) to confirm resources, tools, prompts, and completion
targets.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/_index.cn.md
index 3921194edbe..889ae25136d 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/_index.cn.md
@@ -5,7 +5,7 @@ chapter = true
+++
ShardingSphere-MCP 通过功能插件扩展领域能力。
-功能插件如果需要多步骤治理变更，会使用[插件工作流](../workflow/)完成规划、预览、执行和校验阶段。
+功能插件如果需要多步骤治理变更，会使用[插件工作流](plugin-workflow/)完成规划、预览、执行和校验阶段。
发行包默认包含以下官方 MCP 功能插件：
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/_index.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/_index.en.md
index c61f6b549d2..ac9cc8ac14c 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/_index.en.md
@@ -5,7 +5,7 @@ chapter = true
+++
ShardingSphere-MCP extends domain capabilities through feature plugins.
-When a feature plugin needs a multi-step governance change, it uses [Plugin
Workflows](../workflow/) for planning, preview, apply, and validation phases.
+When a feature plugin needs a multi-step governance change, it uses [Plugin
Workflows](plugin-workflow/) for planning, preview, apply, and validation
phases.
The packaged distribution includes these official MCP feature plugins:
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 9c89a2947b5..9bd7a47dbe6 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
@@ -13,24 +13,27 @@ weight = 1
- 直连真实数据库时，本功能不适用；真实数据库通常不识别 ShardingSphere 加密 DistSQL，也不能暴露 Proxy
中可见的加密算法插件和规则状态。
- 目标逻辑表和逻辑列应能通过 Proxy 暴露的 JDBC 元数据发现；这些信息不保证等同于底层物理库的完整元数据。
-## 可调用能力
+## 通过自然语言使用
-| MCP 能力 | 类型 | 调用入口 | 适用阶段 | 结果 |
-| --- | --- | --- | --- | --- |
-| `database_gateway_plan_encrypt_rule` | 工具 | `tools/call` | 规划创建、修改或删除加密规则。 |
返回 `plan_id`、规划状态、DistSQL、校验步骤，以及适用场景下的 DDL、派生列和索引建议。 |
-| `database_gateway_apply_workflow` | 阶段工具 | `tools/call`，传入 `plan_id`。 |
规划完成后预览、执行或导出人工执行包。 | 返回预览产物、执行结果或人工执行包。 |
-| `database_gateway_validate_workflow` | 阶段工具 | `tools/call`，传入同一个 `plan_id`。
| 自动执行或人工执行完成后校验结果。 | 返回规则状态、逻辑元数据和 SQL 可执行性校验结果。 |
-| `shardingsphere://features/encrypt/algorithms` | 资源 | `resources/read` |
规划前查看 Proxy 当前可见的加密算法。 | 返回算法类型和参数要求。 |
-| `shardingsphere://features/encrypt/databases/{database}/rules` | 资源模板 | 填充
`{database}` 后通过 `resources/read` 读取。 | 规划修改前查看逻辑库已有加密规则。 | 返回逻辑库级加密规则。 |
-|
`shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules` |
资源模板 | 填充 `{database}` 和 `{table}` 后通过 `resources/read` 读取。 |
只关心单表规则，或需要保留同表其他列规则时读取。 | 返回表级加密规则。 |
-| `plan_encrypt_rule` | 提示 | `prompts/get` | 客户端希望引导模型先读取表结构、算法和已有规则时使用。 |
返回规划加密规则的模型提示。 |
-| `plan_encrypt_rule` 补全 | 补全目标 | `completion/complete` | 客户端填写规划参数时使用。 | 返回
`database`、`schema`、`table`、`column`、算法类型或 `plan_id` 候选值。 |
+用户在 MCP 客户端中描述加密目标即可。
+模型会读取表结构、可用加密算法和已有规则，再生成可审查的加密规则计划。
+用户不需要手工拼接工具参数或 JSON-RPC 请求。
+
+示例：
+
+- 检查 `<logic-database>.orders.status` 当前是否已有加密规则。
+- 为 `<logic-database>.orders.status` 规划可逆加密，需要支持等值查询，先预览不要执行。
+- 使用 AES 算法继续刚才的计划，密钥通过受保护渠道提供。
+- 确认并执行刚才的加密规则计划，然后校验结果。
+
+模型或客户端会把这些任务拆成读取资源、规划规则、预览执行和校验结果。
+用户需要审查计划中的 DistSQL、DDL、索引建议和副作用范围，再批准有副作用的执行。
## 规则规划
-规则规划是加密插件的第一阶段。
-模型通常先读取算法和已有规则资源，再调用 `database_gateway_plan_encrypt_rule` 生成可审查计划。
-规划工具不会直接修改数据库；后续预览、执行和校验由插件工作流阶段工具完成。
+规则规划是数据加密插件的第一阶段。
+模型通常先读取算法和已有规则资源，再调用规划工具生成 `plan_id` 和可审查计划。
+规划工具不会直接修改数据库；后续预览、执行和校验由[插件工作流](../plugin-workflow/)阶段工具完成。
### 规划输入
@@ -56,43 +59,23 @@ weight = 1
| `alter` | 提供目标列和要调整的算法、查询能力或算法参数。 | 生成保留同表其他列规则的修改规则 DistSQL，并按需更新 DDL
或索引建议。 |
| `drop` | 至少提供 `database`、`table`、`column` 和 `operation_type=drop`。 |
如果同表还有其他加密列，生成保留其他列的 `ALTER ENCRYPT RULE`；如果目标表不再保留任何加密列，生成 `DROP ENCRYPT
RULE`。 |
-### 调用示例
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "encrypt-plan-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_plan_encrypt_rule",
- "arguments": {
- "database": "<logic-database>",
- "table": "orders",
- "column": "status",
- "natural_language_intent": "给 status 做可逆加密，需要等值查询，不需要模糊查询",
- "algorithm_type": "AES",
- "primary_algorithm_properties": {
- "aes-key-value": "${AES_KEY_VALUE}"
- }
- }
- }
-}
-```
-
-典型结果：
-
-- 返回 `plan_id`。
-- `status` 为 `planned` 或 `clarifying`。
-- `derived_column_plan` 说明派生列命名。
-- `ddl_artifacts` 可能包含物理列 DDL。
-- `distsql_artifacts` 包含 `CREATE/ALTER ENCRYPT RULE`。
-- `index_plan` 可能包含辅助查询索引。
+### 规划结果
+
+典型规划结果包括：
+
+- `plan_id`，用于后续预览、执行和校验。
+- `status`，取值通常为 `planned` 或 `clarifying`。
+- `derived_column_plan`，说明派生列命名。
+- `ddl_artifacts`，可能包含物理列 DDL。
+- `distsql_artifacts`，包含 `CREATE/ALTER/DROP ENCRYPT RULE`。
+- `index_plan`，可能包含辅助查询索引建议。
如果返回 `clarifying`，继续使用同一个 `plan_id` 补齐缺失字段。
敏感字段不会明文回显，应通过密钥管理系统、受保护环境变量或运维控制通道取得后再继续。
## 派生列与索引计划
+派生列与索引计划是规则规划的输出内容，不是需要用户单独调用的能力。
加密规则可能需要物理派生列来保存密文或支持查询。
MCP 会根据逻辑列、用户意图和已有规则生成派生列建议，并把最终命名写入 `derived_column_plan`。
@@ -103,43 +86,15 @@ MCP 会根据逻辑列、用户意图和已有规则生成派生列建议，并
## 执行与校验
-规划工具返回 `plan_id` 后，再使用插件工作流阶段工具处理执行和校验。
+规划工具返回 `plan_id` 后，模型或客户端再使用插件工作流阶段工具处理执行和校验。
建议先预览，确认 DistSQL、DDL、索引计划和副作用范围后再执行。
-执行前先预览：
-
-```json
-{
- "name": "database_gateway_apply_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}",
- "execution_mode": "preview"
- }
-}
-```
-
-确认变更产物后执行：
-
-```json
-{
- "name": "database_gateway_apply_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}",
- "execution_mode": "review-then-execute"
- }
-}
-```
-
-校验：
-
-```json
-{
- "name": "database_gateway_validate_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}"
- }
-}
-```
+| 阶段 | 用户表达 | 模型或客户端动作 |
+| --- | --- | --- |
+| 预览 | “先预览刚才的加密规则计划，不要执行。” | 使用 `database_gateway_apply_workflow` 和
`execution_mode=preview` 生成预览结果。 |
+| 执行 | “确认执行刚才的计划。” | 用户审查后，使用 `database_gateway_apply_workflow` 和
`execution_mode=review-then-execute` 执行。 |
+| 人工执行 | “导出人工执行包，不要自动执行。” | 使用 `database_gateway_apply_workflow` 和
`execution_mode=manual-only` 返回人工执行包。 |
+| 校验 | “校验刚才的加密规则是否生效。” | 使用 `database_gateway_validate_workflow`
校验规则状态、逻辑元数据和 SQL 可执行性。 |
校验重点：
@@ -148,6 +103,24 @@ MCP 会根据逻辑列、用户意图和已有规则生成派生列建议，并
- `logical_metadata_validation`
- `sql_executability_validation`
+插件工作流的状态、执行模式和敏感输入处理方式见[插件工作流](../plugin-workflow/)。
+
+## MCP 能力参考
+
+本节用于自研客户端、协议调试或理解模型背后的 MCP 调用。
+普通用户通常只需要使用自然语言描述任务。
+
+| MCP 能力 | 类型 | 调用入口 | 适用阶段 | 结果 |
+| --- | --- | --- | --- | --- |
+| `database_gateway_plan_encrypt_rule` | 工具 | `tools/call` | 规划创建、修改或删除加密规则。 |
返回 `plan_id`、规划状态、DistSQL、校验步骤，以及适用场景下的 DDL、派生列和索引建议。 |
+| `database_gateway_apply_workflow` | 阶段工具 | `tools/call`，传入 `plan_id`。 |
规划完成后预览、执行或导出人工执行包。 | 返回预览产物、执行结果或人工执行包。 |
+| `database_gateway_validate_workflow` | 阶段工具 | `tools/call`，传入同一个 `plan_id`。
| 自动执行或人工执行完成后校验结果。 | 返回规则状态、逻辑元数据和 SQL 可执行性校验结果。 |
+| `shardingsphere://features/encrypt/algorithms` | 资源 | `resources/read` |
规划前查看 Proxy 当前可见的加密算法。 | 返回算法类型和参数要求。 |
+| `shardingsphere://features/encrypt/databases/{database}/rules` | 资源模板 | 填充
`{database}` 后通过 `resources/read` 读取。 | 规划修改前查看逻辑库已有加密规则。 | 返回逻辑库级加密规则。 |
+|
`shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules` |
资源模板 | 填充 `{database}` 和 `{table}` 后通过 `resources/read` 读取。 |
只关心单表规则，或需要保留同表其他列规则时读取。 | 返回表级加密规则。 |
+| `plan_encrypt_rule` | 提示 | `prompts/get` | 客户端希望引导模型先读取表结构、算法和已有规则时使用。 |
返回规划加密规则的模型提示。 |
+| `plan_encrypt_rule` 补全 | 补全目标 | `completion/complete` | 客户端填写规划参数时使用。 | 返回
`database`、`schema`、`table`、`column`、算法类型或 `plan_id` 候选值。 |
+
## 限制
### 支持范围
@@ -155,13 +128,21 @@ MCP 会根据逻辑列、用户意图和已有规则生成派生列建议，并
- 仅支持 ShardingSphere-Proxy 逻辑库。
- 直连真实数据库时，本功能不适用。
-### 规则变更边界
+### MCP 插件边界
+
+- MCP Server 不实现加密算法，也不替代用户判断加密策略是否满足业务安全要求。
+- 规划结果是可审查的变更计划；是否执行仍需要用户确认。
+- 删除加密规则只移除规则本身，不会恢复历史明文数据；不再需要的物理派生列或索引仍需人工清理。
+
+### Proxy 可见元数据边界
- MCP 根据 Proxy 暴露的逻辑元数据生成派生列、索引和列类型建议；它不会直接检查每个物理库。
- 执行前应结合真实物理库表结构审查生成的 DDL。
+
+### ShardingSphere 功能边界
+
- 不处理已有数据迁移或回填。
- 不提供自动回滚。
-- 删除加密规则只移除规则本身，不会恢复历史明文数据；不再需要的物理派生列或索引仍需人工清理。
### 规划器输入限制
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 804964cd32e..d9d13f9fcbf 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
@@ -13,24 +13,27 @@ It does not implement encryption algorithms inside the MCP
Server. It generates
- This feature does not apply to direct physical database connections. A
physical database usually does not understand ShardingSphere encryption DistSQL
and cannot expose Proxy-visible encryption algorithm plugins or rule state.
- The target logical table and column should be discoverable through JDBC
metadata exposed by Proxy. This metadata should not be treated as a complete
physical database catalog.
-## Public Surface
+## Use through natural language
-| MCP capability | Type | Call entry | Phase | Result |
-| --- | --- | --- | --- | --- |
-| `database_gateway_plan_encrypt_rule` | Tool | `tools/call` | Plan creation,
alteration, or deletion of encryption rules. | Returns `plan_id`, planning
status, DistSQL, validation steps, and DDL, derived column, or index
suggestions when applicable. |
-| `database_gateway_apply_workflow` | Phase tool | `tools/call` with
`plan_id`. | Preview, execute, or export a manual package after planning
completes. | Returns preview artifacts, execution result, or manual execution
package. |
-| `database_gateway_validate_workflow` | Phase tool | `tools/call` with the
same `plan_id`. | Validate results after automatic or manual execution. |
Returns rule state, logical metadata, and SQL executability validation results.
|
-| `shardingsphere://features/encrypt/algorithms` | Resource | `resources/read`
| Inspect encryption algorithms visible through Proxy before planning. |
Returns algorithm types and required properties. |
-| `shardingsphere://features/encrypt/databases/{database}/rules` | Resource
template | Fill `{database}` and read through `resources/read`. | Inspect
existing encryption rules before altering a logical database. | Returns logical
database-level encryption rules. |
-|
`shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules` |
Resource template | Fill `{database}` and `{table}`, then read through
`resources/read`. | Inspect one table's rules or keep sibling column rules on
the same table. | Returns table-level encryption rules. |
-| `plan_encrypt_rule` | Prompt | `prompts/get` | Guide the model to read table
metadata, algorithms, and existing rules before planning. | Returns the model
prompt for encryption rule planning. |
-| `plan_encrypt_rule` completion | Completion target | `completion/complete` |
Fill planning arguments in a client. | Returns candidates for `database`,
`schema`, `table`, `column`, algorithm types, or `plan_id`. |
+Users describe the encryption goal in the MCP client.
+The model reads table structure, available encryption algorithms, and existing
rules, then creates a reviewable encryption rule plan.
+Users do not need to hand-write tool arguments or JSON-RPC requests.
+
+Examples:
+
+- Check whether `<logic-database>.orders.status` already has an encryption
rule.
+- Plan reversible encryption for `<logic-database>.orders.status` with
equality query support, and preview it without execution.
+- Continue the previous plan with the AES algorithm and provide the key
through a protected channel.
+- Confirm and execute the previous encryption rule plan, then validate the
result.
+
+The model or client breaks these tasks into resource reads, rule planning,
preview, execution, and validation.
+Users should review DistSQL, DDL, index suggestions, and side-effect scope
before approving any side-effecting execution.
## Rule planning
Rule planning is the first phase of the encryption plugin.
-The model usually reads algorithm and existing-rule resources first, then
calls `database_gateway_plan_encrypt_rule` to create a reviewable plan.
-The planning tool does not modify the database directly. Preview, apply, and
validation are handled by plugin workflow phase tools.
+The model usually reads algorithm and existing-rule resources first, then
calls the planning tool to create `plan_id` and a reviewable plan.
+The planning tool does not modify the database directly. Preview, apply, and
validation are handled by [Plugin Workflows](../plugin-workflow/) phase tools.
### Planning input
@@ -56,43 +59,23 @@ Different operations focus on different inputs:
| `alter` | Provide the target column and the algorithm, query capability, or
algorithm properties to change. | Generates DistSQL that preserves sibling
column rules on the same table, and updates DDL or index suggestions when
needed. |
| `drop` | Provide at least `database`, `table`, `column`, and
`operation_type=drop`. | Generates `ALTER ENCRYPT RULE` when sibling encryption
columns remain on the same table, or `DROP ENCRYPT RULE` when no encryption
column remains on the target table. |
-### Call example
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "encrypt-plan-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_plan_encrypt_rule",
- "arguments": {
- "database": "<logic-database>",
- "table": "orders",
- "column": "status",
- "natural_language_intent": "Encrypt status reversibly with equality
query support and without LIKE query support",
- "algorithm_type": "AES",
- "primary_algorithm_properties": {
- "aes-key-value": "${AES_KEY_VALUE}"
- }
- }
- }
-}
-```
-
-Typical result:
-
-- Returns `plan_id`.
-- `status` is `planned` or `clarifying`.
-- `derived_column_plan` describes derived column names.
-- `ddl_artifacts` may contain physical column DDL.
-- `distsql_artifacts` contains `CREATE/ALTER ENCRYPT RULE`.
-- `index_plan` may contain assisted-query indexes.
+### Planning result
+
+A typical planning result includes:
+
+- `plan_id`, used for preview, apply, and validation.
+- `status`, usually `planned` or `clarifying`.
+- `derived_column_plan`, describing derived column names.
+- `ddl_artifacts`, which may contain physical column DDL.
+- `distsql_artifacts`, containing `CREATE/ALTER/DROP ENCRYPT RULE`.
+- `index_plan`, which may contain assisted-query index suggestions.
If the response returns `clarifying`, continue with the same `plan_id`.
Secret fields are not echoed in plain text. Obtain them through a secret
manager, protected environment variable, or controlled operations channel
before continuing.
## Derived columns and index plans
+Derived columns and index plans are outputs of rule planning, not capabilities
that users call separately.
Encryption rules may need physical derived columns to store ciphertext or
support queries.
MCP creates derived-column suggestions from the logical column, user intent,
and existing rules, and writes the final names to `derived_column_plan`.
@@ -103,43 +86,15 @@ MCP creates derived-column suggestions from the logical
column, user intent, and
## Apply and validate
-After the planning tool returns `plan_id`, use plugin workflow phase tools for
apply and validation.
+After the planning tool returns `plan_id`, the model or client uses plugin
workflow phase tools for apply and validation.
Preview first, then review DistSQL, DDL, index plans, and side-effect scope
before execution.
-Preview first:
-
-```json
-{
- "name": "database_gateway_apply_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}",
- "execution_mode": "preview"
- }
-}
-```
-
-Execute after reviewing artifacts:
-
-```json
-{
- "name": "database_gateway_apply_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}",
- "execution_mode": "review-then-execute"
- }
-}
-```
-
-Validate:
-
-```json
-{
- "name": "database_gateway_validate_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}"
- }
-}
-```
+| Phase | User expression | Model or client action |
+| --- | --- | --- |
+| Preview | "Preview the previous encryption rule plan without execution." |
Use `database_gateway_apply_workflow` with `execution_mode=preview` to create
preview results. |
+| Execute | "Confirm and execute the previous plan." | After user review, use
`database_gateway_apply_workflow` with `execution_mode=review-then-execute`. |
+| Manual execution | "Export a manual execution package without automatic
execution." | Use `database_gateway_apply_workflow` with
`execution_mode=manual-only`. |
+| Validate | "Validate whether the previous encryption rule took effect." |
Use `database_gateway_validate_workflow` to validate rule state, logical
metadata, and SQL executability. |
Validation focuses on:
@@ -148,6 +103,24 @@ Validation focuses on:
- `logical_metadata_validation`
- `sql_executability_validation`
+See [Plugin Workflows](../plugin-workflow/) for workflow statuses, execution
modes, and sensitive-input handling.
+
+## MCP capability reference
+
+This section is for custom clients, protocol debugging, or understanding the
MCP calls behind model behavior.
+Regular users usually only need to describe tasks in natural language.
+
+| MCP capability | Type | Call entry | Phase | Result |
+| --- | --- | --- | --- | --- |
+| `database_gateway_plan_encrypt_rule` | Tool | `tools/call` | Plan creation,
alteration, or deletion of encryption rules. | Returns `plan_id`, planning
status, DistSQL, validation steps, and DDL, derived column, or index
suggestions when applicable. |
+| `database_gateway_apply_workflow` | Phase tool | `tools/call` with
`plan_id`. | Preview, execute, or export a manual package after planning
completes. | Returns preview artifacts, execution result, or manual execution
package. |
+| `database_gateway_validate_workflow` | Phase tool | `tools/call` with the
same `plan_id`. | Validate results after automatic or manual execution. |
Returns rule state, logical metadata, and SQL executability validation results.
|
+| `shardingsphere://features/encrypt/algorithms` | Resource | `resources/read`
| Inspect encryption algorithms visible through Proxy before planning. |
Returns algorithm types and required properties. |
+| `shardingsphere://features/encrypt/databases/{database}/rules` | Resource
template | Fill `{database}` and read through `resources/read`. | Inspect
existing encryption rules before altering a logical database. | Returns logical
database-level encryption rules. |
+|
`shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules` |
Resource template | Fill `{database}` and `{table}`, then read through
`resources/read`. | Inspect one table's rules or keep sibling column rules on
the same table. | Returns table-level encryption rules. |
+| `plan_encrypt_rule` | Prompt | `prompts/get` | Guide the model to read table
metadata, algorithms, and existing rules before planning. | Returns the model
prompt for encryption rule planning. |
+| `plan_encrypt_rule` completion | Completion target | `completion/complete` |
Fill planning arguments in a client. | Returns candidates for `database`,
`schema`, `table`, `column`, algorithm types, or `plan_id`. |
+
## Limitations
### Supported scope
@@ -155,13 +128,21 @@ Validation focuses on:
- Supports ShardingSphere-Proxy logical databases only.
- This feature does not apply to direct physical database connections.
-### Rule change boundaries
+### MCP plugin boundaries
+
+- The MCP Server does not implement encryption algorithms and does not replace
the user's judgment on whether an encryption strategy satisfies business
security requirements.
+- Planning results are reviewable change plans. Execution still requires user
confirmation.
+- Dropping an encryption rule removes the rule only. It does not restore
historical plaintext data, and physical derived columns or indexes still
require manual cleanup when they are no longer needed.
+
+### Proxy-visible metadata boundaries
- MCP generates derived-column, index, and column-type suggestions from
logical metadata exposed by Proxy. It does not inspect every physical database
directly.
- Review generated DDL against the real physical table structure before
applying it.
+
+### ShardingSphere feature boundaries
+
- Existing data migration or backfill is not handled.
- Automatic rollback is not provided.
-- Dropping an encryption rule removes the rule only. It does not restore
historical plaintext data, and physical derived columns or indexes still
require manual cleanup when they are no longer needed.
### Planner input limits
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 6fd7a1787ef..e8340272fef 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
@@ -13,22 +13,31 @@ weight = 2
- 直连真实数据库时，本功能不适用；真实数据库通常不识别 ShardingSphere 脱敏 DistSQL，也不能暴露 Proxy
中可见的脱敏算法插件和规则状态。
- 目标逻辑表和逻辑列应能通过 Proxy 暴露的 JDBC 元数据发现；这些信息不保证等同于底层物理库的完整元数据。
-## 可调用能力
+## 通过自然语言使用
-| 能力 | 怎么调用 | 什么时候用 |
-| --- | --- | --- |
-| `database_gateway_plan_mask_rule` | 通过 `tools/call` 调用。 |
用户提出创建、调整或删除脱敏规则需求时，用它生成 `plan_id`、DistSQL 和校验步骤。 |
-| `database_gateway_apply_workflow` | 通过 `tools/call` 调用，并传入规划阶段返回的 `plan_id`。
| 先预览计划，再在审查后执行，或导出人工执行包。 |
-| `database_gateway_validate_workflow` | 通过 `tools/call` 调用，并传入同一个 `plan_id`。
| 自动执行或人工执行完成后，校验规则状态、逻辑元数据和 SQL 可执行性。 |
-| `shardingsphere://features/mask/algorithms` | 通过 `resources/read` 读取。 |
规划前查看 Proxy 当前可见的脱敏算法类型和参数要求。 |
-| `shardingsphere://features/mask/databases/{database}/rules` | 填充
`{database}` 后通过 `resources/read` 读取。 | 规划修改前查看逻辑库已有脱敏规则。 |
-| `shardingsphere://features/mask/databases/{database}/tables/{table}/rules` |
填充 `{database}` 和 `{table}` 后通过 `resources/read` 读取。 |
只关心单表脱敏规则，或需要保留同表其他列规则时读取。 |
-| `plan_mask_rule` | 通过 `prompts/get` 获取提示。 |
客户端希望先引导模型读取表结构、算法和已有规则，再调用规划工具时使用。 |
-| `plan_mask_rule` 补全 | 通过 `completion/complete` 获取候选值。 | 为
`database`、`schema`、`table`、`column`、`algorithm_type` 或 `plan_id` 补全。 |
+用户在 MCP 客户端中描述脱敏目标即可。
+模型会读取表结构、可用脱敏算法和已有规则，再生成可审查的脱敏规则计划。
+用户不需要手工拼接工具参数或 JSON-RPC 请求。
+
+示例：
+
+- 检查 `<logic-database>.orders.phone` 当前是否已有脱敏规则。
+- 为 `<logic-database>.orders.phone` 规划手机号脱敏，保留前 3 后 4，先预览不要执行。
+- 调整刚才的计划，把替换字符改成 `*`。
+- 确认并执行刚才的脱敏规则计划，然后校验结果。
+
+模型或客户端会把这些任务拆成读取资源、规划规则、预览执行和校验结果。
+用户需要审查计划中的 DistSQL 和副作用范围，再批准有副作用的执行。
-## 最小输入
+## 规则规划
-创建或修改脱敏规则时，规划工具主要使用以下输入：
+规则规划是数据脱敏插件的第一阶段。
+模型通常先读取算法和已有规则资源，再调用规划工具生成 `plan_id` 和可审查计划。
+规划工具不会直接修改数据库；后续预览、执行和校验由[插件工作流](../plugin-workflow/)阶段工具完成。
+
+### 规划输入
+
+规划工具的公共输入如下：
| 参数 | 是否必填 | 作用 |
| --- | --- | --- |
@@ -37,94 +46,42 @@ weight = 2
| `column` | 必填 | 要配置脱敏规则的逻辑列。 |
| `schema` | 可选 | schema 或 namespace；多 schema 逻辑库建议填写。 |
| `natural_language_intent` | 推荐 | 描述脱敏目标，例如手机号保留位数或替换字符；当未显式填写规则细节时，MCP
会用它推断规划意图。 |
-| `operation_type` | 可选 | 规则操作类型；支持 `create`、`alter` 和 `drop`。不填写时由 MCP
根据自然语言和现有规则推断。 |
+| `operation_type` | 可选 | 规则操作类型；支持 `create`、`alter` 和 `drop`。不填写时由 MCP
根据自然语言和已有规则推断。 |
| `algorithm_type` | 可选 | 脱敏算法类型；如果希望 MCP 基于可用算法给出建议，可以先不填。 |
| `primary_algorithm_properties` | 按算法必填 | 脱敏算法参数，例如保留位数和替换字符。具体参数以算法资源返回值为准。 |
-删除脱敏规则时，至少提供：
-
-- `database`
-- `table`
-- `column`
-- `operation_type=drop`
-
-## 规划脱敏规则
-
-规划脱敏规则就是调用 `database_gateway_plan_mask_rule`。
-它只生成可审查的计划，不直接修改数据库。
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "mask-plan-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_plan_mask_rule",
- "arguments": {
- "database": "<logic-database>",
- "table": "orders",
- "column": "phone",
- "natural_language_intent": "把 phone 当作手机号做脱敏，保留前3后4",
- "algorithm_type": "KEEP_FIRST_N_LAST_M",
- "primary_algorithm_properties": {
- "first-n": "3",
- "last-m": "4",
- "replace-char": "*"
- }
- }
- }
-}
-```
-
-典型结果：
-
-- 返回 `plan_id`。
-- `status` 为 `planned` 或 `clarifying`。
-- `distsql_artifacts` 包含 `CREATE/ALTER MASK RULE`。
-- `ddl_artifacts` 通常为空。
-- `index_plan` 通常为空。
-
-如果自然语言没有说清算法或缺少算法属性，MCP 会返回 `clarifying`。
-此时应继续使用同一个 `plan_id` 补齐 `clarification_questions` 中要求的字段。
+不同操作的输入重点如下：
+
+| 操作 | 输入重点 | 规划结果 |
+| --- | --- | --- |
+| `create` | 提供目标列、脱敏意图、算法类型和算法参数；如果希望 MCP 推荐算法，可以先只提供自然语言意图。 | 生成新增规则
DistSQL。 |
+| `alter` | 提供目标列和要调整的算法或算法参数。 | 生成保留同表其他列规则的修改规则 DistSQL。 |
+| `drop` | 至少提供 `database`、`table`、`column` 和 `operation_type=drop`。 |
如果同表还有其他脱敏列，生成保留其他列的 `ALTER MASK RULE`；如果目标表不再保留任何脱敏列，生成 `DROP MASK RULE`。 |
+
+### 规划结果
+
+典型规划结果包括：
+
+- `plan_id`，用于后续预览、执行和校验。
+- `status`，取值通常为 `planned` 或 `clarifying`。
+- `distsql_artifacts`，包含 `CREATE/ALTER/DROP MASK RULE`。
+- `ddl_artifacts`，通常为空。
+- `index_plan`，通常为空。
+
+如果返回 `clarifying`，继续使用同一个 `plan_id` 补齐缺失字段。
+敏感字段不会明文回显，应通过密钥管理系统、受保护环境变量或运维控制通道取得后再继续。
## 执行与校验
-规划工具返回 `plan_id` 后，再使用通用工作流工具处理执行和校验。
-
-执行前先预览：
-
-```json
-{
- "name": "database_gateway_apply_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}",
- "execution_mode": "preview"
- }
-}
-```
-
-确认变更产物后执行：
-
-```json
-{
- "name": "database_gateway_apply_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}",
- "execution_mode": "review-then-execute"
- }
-}
-```
-
-校验：
-
-```json
-{
- "name": "database_gateway_validate_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}"
- }
-}
-```
+规划工具返回 `plan_id` 后，模型或客户端再使用插件工作流阶段工具处理执行和校验。
+建议先预览，确认 DistSQL 和副作用范围后再执行。
+
+| 阶段 | 用户表达 | 模型或客户端动作 |
+| --- | --- | --- |
+| 预览 | “先预览刚才的脱敏规则计划，不要执行。” | 使用 `database_gateway_apply_workflow` 和
`execution_mode=preview` 生成预览结果。 |
+| 执行 | “确认执行刚才的计划。” | 用户审查后，使用 `database_gateway_apply_workflow` 和
`execution_mode=review-then-execute` 执行。 |
+| 人工执行 | “导出人工执行包，不要自动执行。” | 使用 `database_gateway_apply_workflow` 和
`execution_mode=manual-only` 返回人工执行包。 |
+| 校验 | “校验刚才的脱敏规则是否生效。” | 使用 `database_gateway_validate_workflow`
校验规则状态、逻辑元数据和 SQL 可执行性。 |
校验重点：
@@ -132,31 +89,46 @@ weight = 2
- `logical_metadata_validation`
- `sql_executability_validation`
-## 删除脱敏规则
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "mask-drop-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_plan_mask_rule",
- "arguments": {
- "database": "<logic-database>",
- "table": "orders",
- "column": "phone",
- "operation_type": "drop"
- }
- }
-}
-```
-
-如果同一个表上还有其他脱敏列，MCP 会生成 `ALTER MASK RULE` 并保留这些同表规则。
-只有目标表不再保留任何脱敏列时，MCP 才会生成 `DROP MASK RULE`。
+插件工作流的状态、执行模式和敏感输入处理方式见[插件工作流](../plugin-workflow/)。
+
+## MCP 能力参考
+
+本节用于自研客户端、协议调试或理解模型背后的 MCP 调用。
+普通用户通常只需要使用自然语言描述任务。
+
+| MCP 能力 | 类型 | 调用入口 | 适用阶段 | 结果 |
+| --- | --- | --- | --- | --- |
+| `database_gateway_plan_mask_rule` | 工具 | `tools/call` | 规划创建、修改或删除脱敏规则。 | 返回
`plan_id`、规划状态、DistSQL 和校验步骤。 |
+| `database_gateway_apply_workflow` | 阶段工具 | `tools/call`，传入 `plan_id`。 |
规划完成后预览、执行或导出人工执行包。 | 返回预览产物、执行结果或人工执行包。 |
+| `database_gateway_validate_workflow` | 阶段工具 | `tools/call`，传入同一个 `plan_id`。
| 自动执行或人工执行完成后校验结果。 | 返回规则状态、逻辑元数据和 SQL 可执行性校验结果。 |
+| `shardingsphere://features/mask/algorithms` | 资源 | `resources/read` | 规划前查看
Proxy 当前可见的脱敏算法。 | 返回算法类型和参数要求。 |
+| `shardingsphere://features/mask/databases/{database}/rules` | 资源模板 | 填充
`{database}` 后通过 `resources/read` 读取。 | 规划修改前查看逻辑库已有脱敏规则。 | 返回逻辑库级脱敏规则。 |
+| `shardingsphere://features/mask/databases/{database}/tables/{table}/rules` |
资源模板 | 填充 `{database}` 和 `{table}` 后通过 `resources/read` 读取。 |
只关心单表规则，或需要保留同表其他列规则时读取。 | 返回表级脱敏规则。 |
+| `plan_mask_rule` | 提示 | `prompts/get` | 客户端希望引导模型先读取表结构、算法和已有规则时使用。 |
返回规划脱敏规则的模型提示。 |
+| `plan_mask_rule` 补全 | 补全目标 | `completion/complete` | 客户端填写规划参数时使用。 | 返回
`database`、`schema`、`table`、`column`、算法类型或 `plan_id` 候选值。 |
## 限制
+### 支持范围
+
- 仅支持 ShardingSphere-Proxy 逻辑库。
-- 逻辑列和规则校验以 Proxy 可见信息为准；直连真实数据库只能执行普通 SQL，不代表脱敏规则状态。
+- 直连真实数据库时，本功能不适用。
+
+### MCP 插件边界
+
+- MCP Server 不实现脱敏算法，也不替代用户判断脱敏策略是否满足业务合规要求。
+- 规划结果是可审查的变更计划；是否执行仍需要用户确认。
+- 删除脱敏规则只移除规则本身；后续通过 Proxy 查询该列时不再应用该脱敏规则。
+
+### Proxy 可见元数据边界
+
+- 逻辑列和规则校验以 Proxy 可见信息为准。
+- 直连真实数据库只能执行普通 SQL，不代表脱敏规则状态。
+
+### ShardingSphere 功能边界
+
- 不提供自动回滚。
+
+### 规划器输入限制
+
- 规划器只接受普通未加引号的逻辑库、schema、表和列名，用于降低自动生成 SQL 的歧义；这不是 ShardingSphere SQL 能力限制。
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 602bc49d23d..5f2102de9c2 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
@@ -13,22 +13,31 @@ Mask rules apply directly to logical columns and do not
generate physical derive
- This feature does not apply to direct physical database connections. A
physical database usually does not understand ShardingSphere masking DistSQL
and cannot expose Proxy-visible masking algorithm plugins or rule state.
- The target logical table and column should be discoverable through JDBC
metadata exposed by Proxy. This metadata should not be treated as a complete
physical database catalog.
-## Public Surface
+## Use through natural language
-| Capability | How to call | When to use |
-| --- | --- | --- |
-| `database_gateway_plan_mask_rule` | Call through `tools/call`. | When a user
asks to create, adjust, or drop a masking rule. It creates `plan_id`, DistSQL,
and validation steps. |
-| `database_gateway_apply_workflow` | Call through `tools/call` with the
`plan_id` returned by planning. | Preview the plan, execute reviewed artifacts,
or export a manual package. |
-| `database_gateway_validate_workflow` | Call through `tools/call` with the
same `plan_id`. | After automatic or manual execution, validate rule state,
logical metadata, and SQL executability. |
-| `shardingsphere://features/mask/algorithms` | Read through `resources/read`.
| Before planning, inspect masking algorithm types and required properties
visible through Proxy. |
-| `shardingsphere://features/mask/databases/{database}/rules` | Fill
`{database}` and read through `resources/read`. | Before altering rules,
inspect existing masking rules in the logical database. |
-| `shardingsphere://features/mask/databases/{database}/tables/{table}/rules` |
Fill `{database}` and `{table}`, then read through `resources/read`. | Inspect
one table's masking rules or keep sibling column rules on the same table. |
-| `plan_mask_rule` | Get through `prompts/get`. | When a client wants to guide
the model to read table metadata, algorithms, and existing rules before calling
the planning tool. |
-| `plan_mask_rule` completion | Get candidates through `completion/complete`.
| Completes `database`, `schema`, `table`, `column`, `algorithm_type`, or
`plan_id`. |
+Users describe the masking goal in the MCP client.
+The model reads table structure, available masking algorithms, and existing
rules, then creates a reviewable masking rule plan.
+Users do not need to hand-write tool arguments or JSON-RPC requests.
+
+Examples:
+
+- Check whether `<logic-database>.orders.phone` already has a masking rule.
+- Plan phone-number masking for `<logic-database>.orders.phone`, keep the
first 3 and last 4 characters, and preview it without execution.
+- Adjust the previous plan to use `*` as the replacement character.
+- Confirm and execute the previous masking rule plan, then validate the result.
+
+The model or client breaks these tasks into resource reads, rule planning,
preview, execution, and validation.
+Users should review DistSQL and side-effect scope before approving any
side-effecting execution.
-## Minimum input
+## Rule planning
-For creating or altering a masking rule, the planning tool mainly uses these
inputs:
+Rule planning is the first phase of the masking plugin.
+The model usually reads algorithm and existing-rule resources first, then
calls the planning tool to create `plan_id` and a reviewable plan.
+The planning tool does not modify the database directly. Preview, apply, and
validation are handled by [Plugin Workflows](../plugin-workflow/) phase tools.
+
+### Planning input
+
+The planning tool uses these common inputs:
| Argument | Required | Purpose |
| --- | --- | --- |
@@ -41,90 +50,38 @@ For creating or altering a masking rule, the planning tool
mainly uses these inp
| `algorithm_type` | Optional | Masking algorithm type. Omit it if you want
MCP to recommend one from available algorithms. |
| `primary_algorithm_properties` | Required by algorithm | Masking algorithm
properties, such as retained characters and replacement character. The required
properties come from the algorithm resource. |
-For dropping a mask rule, provide at least:
-
-- `database`
-- `table`
-- `column`
-- `operation_type=drop`
-
-## Plan a mask rule
-
-Planning a masking rule means calling `database_gateway_plan_mask_rule`.
-It creates a reviewable plan only and does not modify the database directly.
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "mask-plan-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_plan_mask_rule",
- "arguments": {
- "database": "<logic-database>",
- "table": "orders",
- "column": "phone",
- "natural_language_intent": "Mask phone as a phone number and keep the
first 3 and last 4 characters",
- "algorithm_type": "KEEP_FIRST_N_LAST_M",
- "primary_algorithm_properties": {
- "first-n": "3",
- "last-m": "4",
- "replace-char": "*"
- }
- }
- }
-}
-```
-
-Typical result:
-
-- Returns `plan_id`.
-- `status` is `planned` or `clarifying`.
-- `distsql_artifacts` contains `CREATE/ALTER MASK RULE`.
-- `ddl_artifacts` is normally empty.
-- `index_plan` is normally empty.
-
-If the natural language input does not identify the algorithm clearly or
required algorithm properties are missing, MCP returns `clarifying`.
-Continue with the same `plan_id` and provide fields requested by
`clarification_questions`.
+Different operations focus on different inputs:
+
+| Operation | Input focus | Planning result |
+| --- | --- | --- |
+| `create` | Provide the target column, masking intent, algorithm type, and
algorithm properties. If you want MCP to recommend an algorithm, start with
natural-language intent. | Generates DistSQL for adding the rule. |
+| `alter` | Provide the target column and the algorithm or algorithm
properties to change. | Generates DistSQL that preserves sibling column rules
on the same table. |
+| `drop` | Provide at least `database`, `table`, `column`, and
`operation_type=drop`. | Generates `ALTER MASK RULE` when sibling masking
columns remain on the same table, or `DROP MASK RULE` when no masking column
remains on the target table. |
+
+### Planning result
+
+A typical planning result includes:
+
+- `plan_id`, used for preview, apply, and validation.
+- `status`, usually `planned` or `clarifying`.
+- `distsql_artifacts`, containing `CREATE/ALTER/DROP MASK RULE`.
+- `ddl_artifacts`, normally empty.
+- `index_plan`, normally empty.
+
+If the response returns `clarifying`, continue with the same `plan_id`.
+Secret fields are not echoed in plain text. Obtain them through a secret
manager, protected environment variable, or controlled operations channel
before continuing.
## Apply and validate
-After the planning tool returns `plan_id`, use the common workflow tools for
apply and validation.
-
-Preview first:
-
-```json
-{
- "name": "database_gateway_apply_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}",
- "execution_mode": "preview"
- }
-}
-```
-
-Execute after reviewing artifacts:
-
-```json
-{
- "name": "database_gateway_apply_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}",
- "execution_mode": "review-then-execute"
- }
-}
-```
-
-Validate:
-
-```json
-{
- "name": "database_gateway_validate_workflow",
- "arguments": {
- "plan_id": "${PLAN_ID}"
- }
-}
-```
+After the planning tool returns `plan_id`, the model or client uses plugin
workflow phase tools for apply and validation.
+Preview first, then review DistSQL and side-effect scope before execution.
+
+| Phase | User expression | Model or client action |
+| --- | --- | --- |
+| Preview | "Preview the previous masking rule plan without execution." | Use
`database_gateway_apply_workflow` with `execution_mode=preview` to create
preview results. |
+| Execute | "Confirm and execute the previous plan." | After user review, use
`database_gateway_apply_workflow` with `execution_mode=review-then-execute`. |
+| Manual execution | "Export a manual execution package without automatic
execution." | Use `database_gateway_apply_workflow` with
`execution_mode=manual-only`. |
+| Validate | "Validate whether the previous masking rule took effect." | Use
`database_gateway_validate_workflow` to validate rule state, logical metadata,
and SQL executability. |
Validation focuses on:
@@ -132,31 +89,46 @@ Validation focuses on:
- `logical_metadata_validation`
- `sql_executability_validation`
-## Drop a mask rule
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "mask-drop-1",
- "method": "tools/call",
- "params": {
- "name": "database_gateway_plan_mask_rule",
- "arguments": {
- "database": "<logic-database>",
- "table": "orders",
- "column": "phone",
- "operation_type": "drop"
- }
- }
-}
-```
-
-If sibling mask columns still exist on the same table, MCP generates `ALTER
MASK RULE` and keeps the sibling rules.
-It generates `DROP MASK RULE` only when no mask column remains on the target
table.
+See [Plugin Workflows](../plugin-workflow/) for workflow statuses, execution
modes, and sensitive-input handling.
+
+## MCP capability reference
+
+This section is for custom clients, protocol debugging, or understanding the
MCP calls behind model behavior.
+Regular users usually only need to describe tasks in natural language.
+
+| MCP capability | Type | Call entry | Phase | Result |
+| --- | --- | --- | --- | --- |
+| `database_gateway_plan_mask_rule` | Tool | `tools/call` | Plan creation,
alteration, or deletion of masking rules. | Returns `plan_id`, planning status,
DistSQL, and validation steps. |
+| `database_gateway_apply_workflow` | Phase tool | `tools/call` with
`plan_id`. | Preview, execute, or export a manual package after planning
completes. | Returns preview artifacts, execution result, or manual execution
package. |
+| `database_gateway_validate_workflow` | Phase tool | `tools/call` with the
same `plan_id`. | Validate results after automatic or manual execution. |
Returns rule state, logical metadata, and SQL executability validation results.
|
+| `shardingsphere://features/mask/algorithms` | Resource | `resources/read` |
Inspect masking algorithms visible through Proxy before planning. | Returns
algorithm types and required properties. |
+| `shardingsphere://features/mask/databases/{database}/rules` | Resource
template | Fill `{database}` and read through `resources/read`. | Inspect
existing masking rules before altering a logical database. | Returns logical
database-level masking rules. |
+| `shardingsphere://features/mask/databases/{database}/tables/{table}/rules` |
Resource template | Fill `{database}` and `{table}`, then read through
`resources/read`. | Inspect one table's rules or keep sibling column rules on
the same table. | Returns table-level masking rules. |
+| `plan_mask_rule` | Prompt | `prompts/get` | Guide the model to read table
metadata, algorithms, and existing rules before planning. | Returns the model
prompt for masking rule planning. |
+| `plan_mask_rule` completion | Completion target | `completion/complete` |
Fill planning arguments in a client. | Returns candidates for `database`,
`schema`, `table`, `column`, algorithm types, or `plan_id`. |
## Limitations
+### Supported scope
+
- Supports ShardingSphere-Proxy logical databases only.
-- 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.
-- Does not provide automatic rollback.
+- This feature does not apply to direct physical database connections.
+
+### MCP plugin boundaries
+
+- The MCP Server does not implement masking algorithms and does not replace
the user's judgment on whether a masking strategy satisfies business compliance
requirements.
+- Planning results are reviewable change plans. Execution still requires user
confirmation.
+- Dropping a masking rule removes the rule only. Later queries through Proxy
no longer apply that masking rule to the column.
+
+### Proxy-visible metadata boundaries
+
+- 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
+
+- Automatic rollback is not provided.
+
+### Planner input limits
+
- The planner accepts ordinary unquoted logical database, schema, table, and
column names to reduce ambiguity in generated SQL. This is not a ShardingSphere
SQL capability limit.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
similarity index 99%
rename from docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
rename to
docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
index 080ef3b4dcd..0f9f579e0f3 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
@@ -1,6 +1,6 @@
+++
title = "插件工作流"
-weight = 5
+weight = 3
+++
插件工作流是 ShardingSphere-MCP 处理多步骤治理变更的共享机制，不是一个独立的业务功能。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
similarity index 99%
rename from docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
rename to
docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
index 5ce37b4d418..7df0414f637 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
@@ -1,6 +1,6 @@
+++
title = "Plugin Workflows"
-weight = 5
+weight = 3
+++
Plugin workflows are the shared mechanism that ShardingSphere-MCP uses for
multi-step governance changes. They are not standalone business features.
