(shardingsphere) branch master updated: Refine ShardingSphere-MCP user guide (#38770)

zhangliang Mon, 01 Jun 2026 21:50:49 -0700

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 a9ac265ad4a Refine ShardingSphere-MCP user guide (#38770)
a9ac265ad4a is described below

commit a9ac265ad4adcc247a8af27f1febca026e6cc8d4
Author: Liang Zhang <[email protected]>
AuthorDate: Tue Jun 2 12:48:58 2026 +0800

    Refine ShardingSphere-MCP user guide (#38770)
    
    Refocus the ShardingSphere-MCP user manual on natural-language usage
    instead of protocol and implementation details.
    
    Add user-facing examples to the capability catalog, simplify client
    integration guidance, align configuration field markers with existing
    documentation style, and move plugin workflows before concrete feature
    plugin pages.
    
    Rewrite the plugin workflow, encryption, and masking pages around
    requirement description, review, preview, apply, and validation flows in
    both Chinese and English.
---
 .../user-manual/shardingsphere-mcp/_index.cn.md    |  22 ++--
 .../user-manual/shardingsphere-mcp/_index.en.md    |  22 ++--
 .../shardingsphere-mcp/capabilities.cn.md          | 107 +++++++++----------
 .../shardingsphere-mcp/capabilities.en.md          | 107 +++++++++----------
 .../shardingsphere-mcp/client-integration.cn.md    |  35 ++----
 .../shardingsphere-mcp/client-integration.en.md    |  35 ++----
 .../shardingsphere-mcp/configuration.cn.md         |  14 +--
 .../shardingsphere-mcp/configuration.en.md         |  14 +--
 .../shardingsphere-mcp/features/_index.cn.md       |   2 +-
 .../shardingsphere-mcp/features/_index.en.md       |   2 +-
 .../shardingsphere-mcp/features/encrypt.cn.md      | 117 +++++++--------------
 .../shardingsphere-mcp/features/encrypt.en.md      | 117 +++++++--------------
 .../shardingsphere-mcp/features/mask.cn.md         | 103 ++++++------------
 .../shardingsphere-mcp/features/mask.en.md         | 103 ++++++------------
 .../features/plugin-workflow.cn.md                 | 108 ++++++-------------
 .../features/plugin-workflow.en.md                 | 108 ++++++-------------
 16 files changed, 354 insertions(+), 662 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 5bf73d625c5..fed1625e464 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
@@ -5,17 +5,15 @@ weight = 7
 chapter = true
 +++
 
-ShardingSphere-MCP 是 Apache ShardingSphere 的 MCP Server，可以独立启动，并向 MCP 客户端暴露 
ShardingSphere 逻辑库的元数据、安全 SQL 访问能力和插件工作流。
-ShardingSphere-MCP 为大模型和 Agent 提供一条受控访问 ShardingSphere 逻辑库的通路。
-模型通过 MCP 客户端主动发现数据库结构、读取治理状态，并在权限边界内调用 SQL 工具或生成可审查的治理变更计划；数据库连接、会话和执行边界由 MCP 
Server 管理。
+ShardingSphere-MCP 是 Apache ShardingSphere 的 MCP Server，可以独立启动。
+它把 ShardingSphere 逻辑库接入支持 MCP 的客户端，使用户能够通过自然语言查看元数据、执行受控 SQL 查询，并规划可审查的治理变更。
 
-ShardingSphere-MCP 的配置以数据库为核心：先配置 MCP Server 可以连接的 ShardingSphere 逻辑库，再通过 MCP 
客户端读取元数据或调用 SQL 工具。
+ShardingSphere-MCP 的配置以数据库为核心：先配置 MCP Server 可以连接的 ShardingSphere 
逻辑库，再在客户端中描述要完成的数据库任务。
 
 ## 通过自然语言使用 MCP
 
-ShardingSphere-MCP 面向支持 MCP 的模型客户端、IDE 插件和 Agent 平台使用。
-完成客户端集成后，用户在模型对话中描述数据库任务，模型会根据任务主动读取资源、调用工具、请求补全或生成插件工作流计划。
-普通用户不需要手工拼接 JSON-RPC 请求、记住资源 URI，或直接选择底层工具。
+ShardingSphere-MCP 面向支持 MCP 的客户端、IDE 插件和 Agent 平台使用。
+完成客户端集成后，用户可以在客户端对话中直接描述数据库任务。
 
 常见任务示例：
 
@@ -29,10 +27,10 @@ ShardingSphere-MCP 面向支持 MCP 的模型客户端、IDE 插件和 Agent 平
 
 ## 文档结构
 
-- 快速开始：构建发行包，配置一个可连接的逻辑库，启动 HTTP MCP Server，并验证元数据读取和只读 SQL 查询。
-- 功能介绍：说明 MCP Server 对外提供的资源、工具、提示、补全和工作流能力。
+- 快速开始：构建发行包，配置一个可连接的逻辑库，启动 HTTP MCP Server，并验证基础任务。
+- 功能介绍：说明 MCP Server 可以完成的数据库任务、可读取的信息和使用边界。
 - 配置说明：说明传输方式、`runtimeDatabases`、插件目录和启动参数。
-- 客户端集成：说明 HTTP、STDIO、会话响应头和能力发现调用方式。
-- 功能插件：说明官方 MCP 功能插件能力，以及插件工作流共享的规划、执行和校验阶段。
+- 客户端集成：说明如何通过 HTTP 或 STDIO 把 MCP Server 接入客户端，以及集成后的使用方式。
+- 功能插件：说明官方 MCP 功能插件能力，以及插件变更的审查、执行和校验流程。
 - 部署说明：说明发行包、OCI 镜像和安全部署建议。
-- 常见问题：排查 MCP Server、传输方式、会话和 SQL 工具的通用问题。
+- 常见问题：排查 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 934268a8313..4aa21734364 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
@@ -5,17 +5,15 @@ weight = 7
 chapter = true
 +++
 
-ShardingSphere-MCP is the MCP Server for Apache ShardingSphere. It can run 
independently and expose ShardingSphere logical database metadata, safe SQL 
access, and plugin workflows to MCP clients.
-ShardingSphere-MCP provides models and agents with a controlled access path to 
ShardingSphere logical databases.
-Through an MCP client, a model can actively discover database structure, read 
governance state, and call SQL tools or create reviewable governance change 
plans within defined boundaries. Database connections, sessions, and execution 
boundaries are managed by the MCP Server.
+ShardingSphere-MCP is the MCP Server for Apache ShardingSphere. It can run 
independently.
+It connects ShardingSphere logical databases to MCP-capable clients, so users 
can inspect metadata, run controlled SQL queries, and plan reviewable 
governance changes through natural language.
 
-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.
+ShardingSphere-MCP configuration starts from databases: configure the 
ShardingSphere logical databases that the MCP Server can connect to, then 
describe database tasks in the 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.
+ShardingSphere-MCP is designed for MCP-capable clients, IDE extensions, and 
agent platforms.
+After client integration, users can describe database tasks directly in the 
client conversation.
 
 Common task examples:
 
@@ -29,10 +27,10 @@ Tasks with side effects should create or preview a plan 
first, then run only aft
 
 ## 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.
+- Quick Start: build the distribution, configure a reachable logical database, 
start the HTTP MCP Server, and verify basic tasks.
+- Capabilities: understand the database tasks, readable information, and usage 
boundaries provided 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.
-- Feature Plugins: use official MCP feature plugins and understand the shared 
planning, apply, and validation phases used by plugin workflows.
+- Client Integration: connect the MCP Server to a client through HTTP or 
STDIO, and understand how to use it after integration.
+- Feature Plugins: use official MCP feature plugins and understand how to 
review, apply, and validate plugin changes.
 - Deployment: deploy the binary distribution and OCI image safely.
-- Troubleshooting: diagnose common MCP Server, transport, session, and SQL 
tool issues.
+- Troubleshooting: diagnose common MCP Server, connection, configuration, 
metadata, and SQL execution issues.
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md 
b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
index e836fdbe3a6..4a844247e38 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
@@ -3,34 +3,25 @@ title = "能力清单"
 weight = 2
 +++
 
-本页说明 ShardingSphere-MCP 的核心能力，以及协议方法、资源 URI、工具和提示之间的关系。
-文档用于解释能力语义；客户端应通过 MCP 列表方法和 `shardingsphere://capabilities` 读取当前 MCP Server 
实际暴露的内容。
+本页从用户任务角度说明 ShardingSphere-MCP 可以读取哪些信息、执行哪些动作，以及不同连接目标下的使用边界。
+客户端会自动发现当前 MCP Server 实际可用的能力；用户通常只需要在客户端中描述要完成的数据库任务。
 
 ## 能力发现
 
-下面列出的是 MCP 协议方法和 ShardingSphere-MCP 资源 URI。
-`tools/list`、`resources/list`、`resources/read`、`prompts/list` 和 
`completion/complete` 是 MCP JSON-RPC 方法名。
-`shardingsphere://...` 是 ShardingSphere-MCP 资源 URI 前缀。
-方法名、工具名和提示名不加 URI 前缀；只有资源 URI 和资源模板使用该前缀。
+能力发现用于让客户端确认当前 MCP Server 可以访问哪些数据库、支持哪些任务，以及哪些任务可能产生副作用。
 
-| 方法或资源 | 类型 | 用途 |
+| 发现内容 | 用途 | 用户侧效果 |
 | --- | --- | --- |
-| `tools/list` | MCP 协议方法 | 列出可调用工具。 |
-| `tools/call` | MCP 协议方法 | 按工具名调用一个工具。 |
-| `resources/list` | MCP 协议方法 | 列出不需要参数即可读取的资源描述；它不返回资源内容。 |
-| `resources/templates/list` | MCP 协议方法 | 列出带参数的资源 URI 模板；客户端需要先填充模板。 |
-| `resources/read` | MCP 协议方法 | 读取一个具体资源 URI 的内容；读取 
`shardingsphere://capabilities` 可获得 ShardingSphere 领域能力目录。 |
-| `prompts/list` | MCP 协议方法 | 列出可用提示。 |
-| `prompts/get` | MCP 协议方法 | 读取一个提示内容，并按提示参数生成消息。 |
-| `completion/complete` | MCP 协议方法 | 获取资源、提示或参数的补全候选。 |
-| `shardingsphere://capabilities` | ShardingSphere-MCP 资源 URI | 读取 
ShardingSphere 领域能力目录。 |
-
-能力发现返回的是当前 MCP Server 的协议表面；实际能否使用某项能力，还取决于 `runtimeDatabases` 连接的是 
ShardingSphere-Proxy 还是普通数据库。
-客户端应先读取 `shardingsphere://runtime` 和 
`shardingsphere://databases/{database}/capabilities`，再决定要读取哪些资源或调用哪些工具。
+| 基础能力列表 | 确认当前 MCP Server 可读取的信息和可执行的动作。 | 客户端可以判断是否支持元数据查看、SQL 查询或治理变更。 |
+| ShardingSphere 能力摘要 | 汇总运行时数据库、连接目标、功能插件和副作用边界。 | 用户可以询问“这个逻辑库支持哪些治理任务？” |
+| 数据库能力摘要 | 确认某个运行时数据库支持的 SQL、事务、schema 和元数据对象能力。 | 用户可以询问“这个库支持只读查询和规则规划吗？” |
+
+能力发现结果代表当前 MCP Server 实际对外可用的内容；实际能否使用某项能力，还取决于 `runtimeDatabases` 连接的是 
ShardingSphere-Proxy 还是普通数据库。
+客户端会根据连接目标选择可用能力。
 
 ### 连接 ShardingSphere-Proxy
 
-适合让模型理解 ShardingSphere 逻辑库结构、读取治理规则状态、执行受控 SQL，或通过功能插件生成可审查的治理变更计划。
+适合查看 ShardingSphere 逻辑库结构、读取治理规则状态、执行受控 SQL，或通过功能插件生成可审查的治理变更计划。
 此模式下，逻辑元数据、逻辑 SQL、DistSQL、规则状态、算法插件和插件工作流可以被 MCP 能力使用。
 
 使用限制：
@@ -52,66 +43,66 @@ weight = 2
 
 ## 资源
 
-资源用于给模型提供上下文，例如运行时状态、数据库列表、表结构、列信息或工作流计划。
-客户端或模型通过 `resources/read` 读取具体资源 URI；资源模板需要先填充参数，再读取。
+资源用于提供运行时状态、数据库列表、表结构、列信息或工作流计划等上下文。
+客户端会按任务需要读取对应资源。
 
-| 资源 URI 或模板 | 类型 | 用途 |
+| 资源 URI 或模板 | 用途 | 自然语言示例 |
 | --- | --- | --- |
-| `shardingsphere://capabilities` | 资源 URI | 查看资源 
URI、资源模板、工具、提示、补全、工作流关系和副作用提示。 |
-| `shardingsphere://runtime` | 资源 URI | 查看当前传输方式、运行状态和已配置运行时数据库摘要。 |
-| `shardingsphere://databases` | 资源 URI | 列出当前 MCP Server 可以访问的运行时数据库；连接 Proxy 
时对应 ShardingSphere 逻辑库。 |
-| `shardingsphere://databases/{database}` | 资源模板 | 读取一个运行时数据库的详情和元数据摘要。 |
-| `shardingsphere://databases/{database}/capabilities` | 资源模板 | 读取一个运行时数据库的 
SQL、事务、schema 和元数据对象能力。 |
-| `shardingsphere://databases/{database}/schemas` | 资源模板 | 列出一个运行时数据库中的 schema 
或 namespace。 |
-| `shardingsphere://databases/{database}/schemas/{schema}` | 资源模板 | 读取一个 
schema 或 namespace 的详情。 |
-| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | 资源模板 | 
列出一个 schema 中的 sequence。 |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` | 
资源模板 | 读取一个 sequence 的详情。 |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables` | 资源模板 | 
列出一个 schema 中的表。 |
-| `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}/tables/{table}/indexes` 
| 资源模板 | 列出一个表的索引。 |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
 | 资源模板 | 读取一个表索引的详情。 |
-| `shardingsphere://databases/{database}/schemas/{schema}/views` | 资源模板 | 列出一个 
schema 中的视图。 |
-| `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://workflows/{plan_id}` | 资源模板 | 
读取当前会话中的工作流计划、补问信息、变更产物和下一步动作。 |
+| `shardingsphere://capabilities` | 查看 MCP Server 的可用任务和副作用提示。 | “这个 MCP 
Server 支持哪些数据库任务？” |
+| `shardingsphere://runtime` | 查看当前传输方式、运行状态和已配置运行时数据库摘要。 | “当前 MCP Server 
配置了哪些逻辑库？” |
+| `shardingsphere://databases` | 列出当前 MCP Server 可以访问的运行时数据库；连接 Proxy 时对应 
ShardingSphere 逻辑库。 | “列出可以访问的逻辑库。” |
+| `shardingsphere://databases/{database}` | 读取一个运行时数据库的详情和元数据摘要。 | “查看 
`<logic-database>` 的元数据摘要。” |
+| `shardingsphere://databases/{database}/capabilities` | 读取一个运行时数据库的 
SQL、事务、schema 和元数据对象能力。 | “`<logic-database>` 支持哪些 SQL 和元数据能力？” |
+| `shardingsphere://databases/{database}/schemas` | 列出一个运行时数据库中的 schema 或 
namespace。 | “查看 `<logic-database>` 中有哪些 schema。” |
+| `shardingsphere://databases/{database}/schemas/{schema}` | 读取一个 schema 或 
namespace 的详情。 | “查看 `<schema-name>` 的详情。” |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | 列出一个 
schema 中的 sequence。 | “列出 `<schema-name>` 中的 sequence。” |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` | 
读取一个 sequence 的详情。 | “查看 `<sequence-name>` 的详情。” |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` | 列出一个 
schema 中的表。 | “列出 `<schema-name>` 中的表。” |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` | 
读取一个表的详情。 | “查看 `<table-name>` 的表结构。” |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns` 
| 列出一个表的列。 | “查看 `<table-name>` 有哪些列。” |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
 | 读取一个表列的详情。 | “查看 `<column-name>` 的类型和约束。” |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes` 
| 列出一个表的索引。 | “查看 `<table-name>` 的索引。” |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
 | 读取一个表索引的详情。 | “查看 `<index-name>` 包含哪些列。” |
+| `shardingsphere://databases/{database}/schemas/{schema}/views` | 列出一个 schema 
中的视图。 | “列出 `<schema-name>` 中的视图。” |
+| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` | 
读取一个视图的详情。 | “查看 `<view-name>` 的定义摘要。” |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` | 
列出一个视图的列。 | “查看 `<view-name>` 有哪些列。” |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
 | 读取一个视图列的详情。 | “查看视图列 `<column-name>` 的详情。” |
+| `shardingsphere://workflows/{plan_id}` | 查看当前治理变更计划、补问信息、变更产物和下一步动作。 | 
“查看刚才的规则变更计划和下一步动作。” |
 
 插件提供的资源、工具、提示和补全目标在对应插件页面说明。
 
 ## 工具
 
 工具用于执行动作，例如搜索元数据、执行 SQL，或处理插件工作流阶段。
-模型通过 `tools/call` 调用工具；有副作用的工具需要显式执行模式，并应先预览或审查。
+有副作用的动作应先预览或审查。
 
-| 工具 | 用途 | 副作用 |
-| --- | --- | --- |
-| `database_gateway_search_metadata` | 按名称片段和对象类型搜索运行时数据库元数据，并返回后续资源读取提示。 | 无。 
|
-| `database_gateway_execute_query` | 执行一个已判定为查询类的 `SELECT` 或 `EXPLAIN 
ANALYZE`。 | 无；拒绝 DML、DDL、DCL、事务控制、savepoint 和其他有副作用 SQL。 |
-| `database_gateway_execute_update` | 预览或执行一个可能修改数据、元数据、规则或事务状态的 SQL。 | 
有；必须显式传入 `execution_mode=preview` 或 `execution_mode=execute`。 |
-| `database_gateway_apply_workflow` | 插件规划返回 `plan_id` 后，预览、执行或导出人工执行包。 | 取决于 
`execution_mode`；`preview` 和 `manual-only` 不修改运行时状态。 |
-| `database_gateway_validate_workflow` | 插件工作流执行后，根据可见元数据和生成产物校验结果。 | 无。 |
+| 工具 | 用途 | 自然语言示例 | 副作用 |
+| --- | --- | --- | --- |
+| `database_gateway_search_metadata` | 按名称片段和对象类型搜索运行时数据库元数据，并返回后续资源读取提示。 | 
“查找名字包含 `order` 的表。” | 无。 |
+| `database_gateway_execute_query` | 执行一个已判定为查询类的 `SELECT` 或 `EXPLAIN 
ANALYZE`。 | “查询 `orders` 表前 10 行。” | 无；拒绝 DML、DDL、DCL、事务控制、savepoint 和其他有副作用 
SQL。 |
+| `database_gateway_execute_update` | 预览或执行一个可能修改数据、元数据、规则或事务状态的 SQL。 | 
“预览这条变更 SQL，先不要执行。” | 有；应先预览并确认。 |
+| `database_gateway_apply_workflow` | 预览、执行或导出功能插件生成的治理变更计划。 | “先预览刚才的加密规则计划。” 
| 取决于执行方式；预览和人工执行包不修改运行时状态。 |
+| `database_gateway_validate_workflow` | 插件工作流执行后，根据可见元数据和生成产物校验结果。 | 
“校验刚才的脱敏规则是否生效。” | 无。 |
 
 插件工具在对应插件页面说明。
 
 ## 提示
 
-提示用于给模型提供任务引导，例如先读取哪些资源、如何选择工具、如何处理失败恢复。
-客户端通过 `prompts/get` 取得提示内容后，将其交给模型参与推理；提示不是需要用户手工执行的命令。
+提示用于任务引导，例如先读取哪些信息、如何处理 SQL 执行边界、如何从失败中恢复。
+用户通常不需要直接使用提示。
 
 | 提示 | 用途 |
 | --- | --- |
-| `inspect_metadata` | 引导模型读取数据库元数据，再选择搜索工具或详情资源。 |
-| `safe_sql_execution` | 引导模型区分只读查询和有副作用 SQL，并选择正确 SQL 工具。 |
-| `recover_workflow` | 引导模型在插件工作流失败或 `plan_id` 不可用时恢复或重新规划。 |
+| `inspect_metadata` | 引导元数据查看任务先读取数据库元数据，再选择搜索工具或详情资源。 |
+| `safe_sql_execution` | 引导 SQL 执行任务区分只读查询和有副作用 SQL。 |
+| `recover_workflow` | 引导插件工作流失败后恢复或重新规划。 |
 
 插件提示在对应插件页面说明。
 
 ## 补全目标
 
-补全目标用于帮助客户端或模型填写资源 URI、提示参数或工具参数。
-例如用户只输入部分数据库、schema、表或列名时，客户端可以通过 `completion/complete` 获取候选值。
+补全目标用于帮助客户端补齐数据库、schema、表、列等名称。
+例如用户只输入部分对象名时，客户端可以给出候选值。
 
 ### 资源补全目标
 
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
index 63040b47b83..c99d027dfbf 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
@@ -3,34 +3,25 @@ title = "Capability Catalog"
 weight = 2
 +++
 
-This page explains the core capabilities of ShardingSphere-MCP and how 
protocol methods, resource URIs, tools, and prompts relate to each other.
-The documentation explains capability semantics. Clients should use MCP list 
methods and `shardingsphere://capabilities` to read what the current MCP Server 
actually exposes.
+This page explains the information that ShardingSphere-MCP can read, the 
actions it can perform, and the usage boundaries for different connection 
targets.
+Clients discover the capabilities currently available from the MCP Server 
automatically. Users usually only need to describe the database task they want 
to complete.
 
 ## Capability discovery
 
-The following entries include MCP protocol methods and ShardingSphere-MCP 
resource URIs.
-`tools/list`, `resources/list`, `resources/read`, `prompts/list`, and 
`completion/complete` are MCP JSON-RPC method names.
-`shardingsphere://...` is the ShardingSphere-MCP resource URI prefix.
-Method names, tool names, and prompt names do not use a URI prefix. Only 
resource URIs and resource templates use it.
+Capability discovery lets clients confirm which databases the current MCP 
Server can access, which tasks it supports, and which tasks may have side 
effects.
 
-| Method or resource | Type | Purpose |
+| Discovery content | Purpose | User-facing result |
 | --- | --- | --- |
-| `tools/list` | MCP protocol method | Lists callable tools. |
-| `tools/call` | MCP protocol method | Calls one tool by tool name. |
-| `resources/list` | MCP protocol method | Lists descriptors for resources 
that can be read without template arguments. It does not return resource 
content. |
-| `resources/templates/list` | MCP protocol method | Lists parameterized 
resource URI templates. Clients fill the template first. |
-| `resources/read` | MCP protocol method | Reads the content of one concrete 
resource URI. Reading `shardingsphere://capabilities` returns the 
ShardingSphere domain capability catalog. |
-| `prompts/list` | MCP protocol method | Lists available prompts. |
-| `prompts/get` | MCP protocol method | Reads one prompt and generates 
messages from its arguments. |
-| `completion/complete` | MCP protocol method | Gets completion candidates for 
resources, prompts, or arguments. |
-| `shardingsphere://capabilities` | ShardingSphere-MCP resource URI | Reads 
the ShardingSphere domain capability catalog. |
-
-Capability discovery returns the protocol surface of the current MCP Server. 
Whether a capability is actually useful still depends on whether 
`runtimeDatabases` connects to ShardingSphere-Proxy or to a regular database.
-Clients should read `shardingsphere://runtime` and 
`shardingsphere://databases/{database}/capabilities` before deciding which 
resources to read or which tools to call.
+| Basic capability list | Confirms readable information and executable actions 
from the current MCP Server. | The client can determine whether metadata 
inspection, SQL query, or governance changes are supported. |
+| ShardingSphere capability summary | Summarizes runtime databases, connection 
targets, feature plugins, and side-effect boundaries. | Users can ask, "Which 
governance tasks does this logical database support?" |
+| Database capability summary | Confirms SQL, transaction, schema, and 
metadata-object capabilities for one runtime database. | Users can ask, "Does 
this database support read-only queries and rule planning?" |
+
+Capability discovery represents what the current MCP Server actually makes 
available. Whether a capability is actually useful still depends on whether 
`runtimeDatabases` connects to ShardingSphere-Proxy or to a regular database.
+Clients select available capabilities according to the connection target.
 
 ### Connecting to ShardingSphere-Proxy
 
-Use this mode when a model needs to understand ShardingSphere logical database 
structure, read governance rule state, execute controlled SQL, or create 
reviewable governance change plans through feature plugins.
+Use this mode to inspect ShardingSphere logical database structure, read 
governance rule state, execute controlled SQL, or create reviewable governance 
change plans through feature plugins.
 In this mode, logical metadata, logical SQL, DistSQL, rule state, algorithm 
plugins, and plugin workflows can be used through MCP capabilities.
 
 Usage limits:
@@ -52,66 +43,66 @@ Usage limits:
 
 ## Resources
 
-Resources provide context to the model, such as runtime status, database 
lists, table structure, column information, or workflow plans.
-Clients or models read concrete resource URIs through `resources/read`; 
resource templates must be filled before they are read.
+Resources provide context such as runtime status, database lists, table 
structure, column information, or workflow plans.
+Clients read the corresponding resources as needed for the task.
 
-| Resource URI or template | Type | Purpose |
+| Resource URI or template | Purpose | Natural language example |
 | --- | --- | --- |
-| `shardingsphere://capabilities` | Resource URI | Reads resource URIs, 
resource templates, tools, prompts, completions, workflow relationships, and 
side-effect notes. |
-| `shardingsphere://runtime` | Resource URI | Reads the current transport, 
runtime status, and configured runtime database summary. |
-| `shardingsphere://databases` | Resource URI | Lists runtime databases 
reachable by the current MCP Server. When connected to Proxy, they correspond 
to ShardingSphere logical databases. |
-| `shardingsphere://databases/{database}` | Resource template | Reads one 
runtime database and its metadata summary. |
-| `shardingsphere://databases/{database}/capabilities` | Resource template | 
Reads SQL, transaction, schema, and metadata-object capabilities for one 
runtime database. |
-| `shardingsphere://databases/{database}/schemas` | Resource template | Lists 
schemas or namespaces inside one runtime database. |
-| `shardingsphere://databases/{database}/schemas/{schema}` | Resource template 
| Reads one schema or namespace. |
-| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | 
Resource template | Lists sequences in one schema. |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` | 
Resource template | Reads one sequence. |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables` | Resource 
template | Lists tables in one schema. |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` | 
Resource template | Reads one table. |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns` 
| Resource template | Lists columns for one table. |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
 | Resource template | Reads one table column. |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes` 
| Resource template | Lists indexes for one table. |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
 | Resource template | Reads one table index. |
-| `shardingsphere://databases/{database}/schemas/{schema}/views` | Resource 
template | Lists views in one schema. |
-| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` | 
Resource template | Reads one view. |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` | 
Resource template | Lists columns for one view. |
-| 
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
 | Resource template | Reads one view column. |
-| `shardingsphere://workflows/{plan_id}` | Resource template | Reads a 
current-session workflow plan, clarification questions, artifacts, and next 
actions. |
+| `shardingsphere://capabilities` | Reads available tasks and side-effect 
notes for the MCP Server. | "Which database tasks does this MCP Server 
support?" |
+| `shardingsphere://runtime` | Reads the current transport, runtime status, 
and configured runtime database summary. | "Which logical databases are 
configured on the MCP Server?" |
+| `shardingsphere://databases` | Lists runtime databases reachable by the 
current MCP Server. When connected to Proxy, they correspond to ShardingSphere 
logical databases. | "List the logical databases that can be accessed." |
+| `shardingsphere://databases/{database}` | Reads one runtime database and its 
metadata summary. | "Show the metadata summary for `<logic-database>`." |
+| `shardingsphere://databases/{database}/capabilities` | Reads SQL, 
transaction, schema, and metadata-object capabilities for one runtime database. 
| "Which SQL and metadata capabilities does `<logic-database>` support?" |
+| `shardingsphere://databases/{database}/schemas` | Lists schemas or 
namespaces inside one runtime database. | "Show schemas in `<logic-database>`." 
|
+| `shardingsphere://databases/{database}/schemas/{schema}` | Reads one schema 
or namespace. | "Show details for `<schema-name>`." |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | Lists 
sequences in one schema. | "List sequences in `<schema-name>`." |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` | 
Reads one sequence. | "Show details for `<sequence-name>`." |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` | Lists 
tables in one schema. | "List tables in `<schema-name>`." |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` | 
Reads one table. | "Inspect the structure of `<table-name>`." |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns` 
| Lists columns for one table. | "Show columns for `<table-name>`." |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
 | Reads one table column. | "Show the type and constraints of 
`<column-name>`." |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes` 
| Lists indexes for one table. | "Show indexes for `<table-name>`." |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
 | Reads one table index. | "Show which columns `<index-name>` contains." |
+| `shardingsphere://databases/{database}/schemas/{schema}/views` | Lists views 
in one schema. | "List views in `<schema-name>`." |
+| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` | 
Reads one view. | "Show a summary of `<view-name>`." |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` | 
Lists columns for one view. | "Show columns for `<view-name>`." |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
 | Reads one view column. | "Show details for view column `<column-name>`." |
+| `shardingsphere://workflows/{plan_id}` | Reads the current governance change 
plan, clarification questions, artifacts, and next actions. | "Show the 
previous rule change plan and next action." |
 
 Plugin resources, tools, prompts, and completion targets are documented on the 
corresponding plugin pages.
 
 ## Tools
 
 Tools execute actions, such as searching metadata, executing SQL, or handling 
plugin workflow phases.
-Models call tools through `tools/call`. Tools with side effects require an 
explicit execution mode and should be previewed or reviewed first.
+Actions with side effects should be previewed or reviewed first.
 
-| Tool | Purpose | Side effects |
-| --- | --- | --- |
-| `database_gateway_search_metadata` | Search runtime database metadata by 
name fragment and object type, and return resource hints for follow-up reads. | 
None. |
-| `database_gateway_execute_query` | Execute exactly one classifier-approved 
`SELECT` or `EXPLAIN ANALYZE` statement. | None; rejects DML, DDL, DCL, 
transaction control, savepoints, and other side-effecting SQL. |
-| `database_gateway_execute_update` | Preview or execute one SQL statement 
that may mutate data, metadata, rules, or transaction state. | Yes; requires 
explicit `execution_mode=preview` or `execution_mode=execute`. |
-| `database_gateway_apply_workflow` | After plugin planning returns `plan_id`, 
preview, execute, or export a manual package. | Depends on `execution_mode`; 
`preview` and `manual-only` do not change runtime state. |
-| `database_gateway_validate_workflow` | After plugin workflow execution, 
validate the result against visible metadata and generated artifacts. | None. |
+| Tool | Purpose | Natural language example | Side effects |
+| --- | --- | --- | --- |
+| `database_gateway_search_metadata` | Search runtime database metadata by 
name fragment and object type, and return resource hints for follow-up reads. | 
"Find tables whose names contain `order`." | None. |
+| `database_gateway_execute_query` | Execute exactly one classifier-approved 
`SELECT` or `EXPLAIN ANALYZE` statement. | "Query the first 10 rows from 
`orders`." | None; rejects DML, DDL, DCL, transaction control, savepoints, and 
other side-effecting SQL. |
+| `database_gateway_execute_update` | Preview or execute one SQL statement 
that may mutate data, metadata, rules, or transaction state. | "Preview this 
change SQL without executing it." | Yes; preview and confirmation are 
recommended first. |
+| `database_gateway_apply_workflow` | Preview, execute, or export a governance 
change plan created by a feature plugin. | "Preview the previous encryption 
rule plan first." | Depends on the execution choice; preview and manual 
packages do not change runtime state. |
+| `database_gateway_validate_workflow` | After plugin workflow execution, 
validate the result against visible metadata and generated artifacts. | 
"Validate whether the previous masking rule has taken effect." | None. |
 
 Plugin tools are documented on the corresponding plugin pages.
 
 ## Prompts
 
-Prompts guide the model through a task, such as which resources to read first, 
which tool to choose, or how to recover from failure.
-Clients fetch prompt content through `prompts/get` and provide it to the model 
for reasoning. Prompts are not commands that users need to run manually.
+Prompts provide task guidance, such as which information to read first, how to 
handle SQL execution boundaries, or how to recover from failure.
+Users usually do not use prompts directly.
 
 | Prompt | Purpose |
 | --- | --- |
-| `inspect_metadata` | Guide the model to read database metadata before 
choosing a search tool or detail resource. |
-| `safe_sql_execution` | Guide the model to choose the correct SQL tool for 
read-only queries or side-effecting SQL. |
-| `recover_workflow` | Guide the model to recover or re-plan after plugin 
workflow failure or unavailable `plan_id`. |
+| `inspect_metadata` | Guides metadata inspection tasks to read database 
metadata before choosing a search tool or detail resource. |
+| `safe_sql_execution` | Guides SQL execution tasks to distinguish read-only 
queries from side-effecting SQL. |
+| `recover_workflow` | Guides recovery or re-planning after plugin workflow 
failure. |
 
 Plugin prompts are documented on the corresponding plugin pages.
 
 ## Completion targets
 
-Completion targets help clients or models fill resource URIs, prompt 
arguments, or tool arguments.
-For example, when a user provides only part of a database, schema, table, or 
column name, the client can request candidates through `completion/complete`.
+Completion targets help clients complete database, schema, table, and column 
names.
+For example, when a user provides only part of an object name, the client can 
provide candidates.
 
 ### Resource completion targets
 
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 bc049593d67..427da7dedd3 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
@@ -3,25 +3,22 @@ title = "客户端集成"
 weight = 4
 +++
 
-客户端集成用于把这条受控数据库访问通路接入桌面客户端、IDE 插件、Agent 平台或自研 LLM 应用。
-接入后，大模型不是直接连接数据库，而是通过 MCP 客户端调用 ShardingSphere-MCP 暴露的资源、工具、提示和补全能力。
-它不是快速开始中 curl 手工验证流程的替代说明，也不是让用户手工拼 JSON-RPC 的操作手册。
-客户端负责连接配置、会话头、补全和调用编排。
-用户只需要表达要完成的元数据查询、只读 SQL 查询或数据库治理任务。
+客户端集成用于把 ShardingSphere-MCP 接入支持 MCP 的桌面客户端、IDE 插件、Agent 平台或自研应用。
+配置完成后，用户可以在客户端中通过自然语言查看元数据、执行受控 SQL 查询，或发起数据库治理任务。
 
 适合使用客户端集成的场景：
 
-- 在支持 MCP 的模型客户端、IDE 插件或 Agent 平台中接入 ShardingSphere。
-- 让模型基于 ShardingSphere 元数据完成查询辅助、结构理解、问题诊断或治理规划。
-- 为团队提供受控数据库访问通路，而不是把数据库连接信息直接交给模型。
+- 在支持 MCP 的客户端、IDE 插件或 Agent 平台中接入 ShardingSphere。
+- 基于 ShardingSphere 元数据完成查询辅助、结构理解、问题诊断或治理规划。
+- 为团队提供统一的受控数据库访问通路。
 - 为自研 Agent 平台集成 ShardingSphere 元数据、安全 SQL 和治理插件能力。
 
-完整的资源、工具、提示和补全说明见[能力清单](../capabilities/)。
+可完成的任务和使用边界见[能力清单](../capabilities/)。
 
 ## 选择传输方式
 
-- HTTP 适合 MCP Server 独立启动，客户端通过固定端点访问的场景。客户端需要完成会话初始化，并在后续请求中携带会话响应头。
-- STDIO 适合本地 MCP 客户端拉起 ShardingSphere-MCP 子进程的场景。客户端负责进程生命周期，stdout 只传输 MCP 
协议帧。
+- HTTP 适合 MCP Server 独立启动，客户端通过固定端点访问的场景。
+- STDIO 适合本地客户端拉起 ShardingSphere-MCP 子进程的场景。
 
 ## HTTP 配置
 
@@ -38,14 +35,7 @@ weight = 4
 }
 ```
 
-HTTP 客户端需要在正常 MCP 调用前完成会话生命周期：
-
-1. 调用 `initialize`。
-2. 保存 `MCP-Session-Id` 和 `MCP-Protocol-Version` 响应头。
-3. 携带这两个响应头发送 `notifications/initialized`，并预期 HTTP 状态码为 `202`。
-4. 后续 MCP 请求继续携带这两个响应头。
-
-关闭会话后，该会话 ID 不能继续复用。
+不同客户端的配置文件位置和字段名称可能不同，请以客户端自身文档为准。
 
 ## STDIO 配置
 
@@ -64,19 +54,16 @@ HTTP 客户端需要在正常 MCP 调用前完成会话生命周期：
 ```
 
 STDIO 模式适合由本地 MCP 客户端拉起 ShardingSphere-MCP 子进程。
-它不是面向人工手输请求的交互式 Shell。
 将 `/path/to/apache-shardingsphere-mcp` 替换为实际发行包目录。
 
 STDIO 模式下：
 
-- stdout 只用于 MCP 协议帧。
 - 诊断日志写到 stderr 或 `logs/mcp.log`。
 - 客户端配置中的 `command` 和 `args` 应指向发行包内的启动脚本和 STDIO 配置文件。
 
 ## 集成后的使用方式
 
-客户端完成 MCP Server 配置后，用户在模型对话中直接描述任务。
-客户端负责会话初始化、能力发现、补全和工具调用；模型根据任务选择读取资源或调用工具。
+客户端完成 MCP Server 配置后，用户在客户端对话中直接描述任务。
 
 示例：
 
@@ -86,4 +73,4 @@ STDIO 模式下：
 - 规划一个数据加密或数据脱敏规则，先预览不要执行。
 
 如果客户端提供工具调用审批界面，应重点审查 SQL 执行、规则变更、插件工作流执行等有副作用的调用。
-自研客户端或协议调试场景，可结合[能力清单](../capabilities/)确认资源、工具、提示和补全目标。
+自研客户端或协议调试场景，可结合[能力清单](../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 5378714c44b..87a8062f7e8 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
@@ -3,25 +3,22 @@ title = "Client Integration"
 weight = 4
 +++
 
-Client integration connects this controlled database access path to desktop 
clients, IDE extensions, agent platforms, or custom LLM applications.
-After integration, the model does not connect to the database directly. It 
calls the resources, tools, prompts, and completion capabilities exposed by 
ShardingSphere-MCP through an MCP client.
-It is not a replacement for the curl-based smoke test in Quick Start, and it 
is not a guide for users to hand-write JSON-RPC.
-The client manages connection configuration, session headers, completion, and 
call orchestration.
-Users only need to describe the metadata lookup, read-only SQL query, or 
database governance task they want to complete.
+Client integration connects ShardingSphere-MCP to MCP-capable desktop clients, 
IDE extensions, agent platforms, or custom applications.
+After configuration, users can inspect metadata, run controlled SQL queries, 
or start database governance tasks through natural language in the client.
 
 Use client integration when:
 
-- A model client, IDE extension, or agent platform that supports MCP needs to 
connect to ShardingSphere.
-- A model should use ShardingSphere metadata for query assistance, structure 
understanding, diagnostics, or governance planning.
-- A team needs a controlled database access path instead of handing database 
connection information directly to a model.
+- An MCP-capable client, IDE extension, or agent platform needs to connect to 
ShardingSphere.
+- ShardingSphere metadata should be used for query assistance, structure 
understanding, diagnostics, or governance planning.
+- A team needs a unified controlled database access path.
 - A custom agent platform needs ShardingSphere metadata, safe SQL, and 
governance plugin capabilities.
 
-See [Capability Catalog](../capabilities/) for the full list of resources, 
tools, prompts, and completion targets.
+See [Capability Catalog](../capabilities/) for supported tasks and usage 
boundaries.
 
 ## Choose a transport
 
-- HTTP is suitable when the MCP Server is started independently and clients 
use a fixed endpoint. The client must initialize the session and keep session 
response headers.
-- STDIO is suitable when a local MCP client starts ShardingSphere-MCP as a 
child process. The client owns the process lifecycle, and stdout carries only 
MCP protocol frames.
+- HTTP is suitable when the MCP Server is started independently and clients 
use a fixed endpoint.
+- STDIO is suitable when a local client starts ShardingSphere-MCP as a child 
process.
 
 ## HTTP configuration
 
@@ -38,14 +35,7 @@ Add the following snippet to the MCP client's server 
configuration. The exact fi
 }
 ```
 
-An HTTP client must complete the session lifecycle before normal MCP calls:
-
-1. Call `initialize`.
-2. Keep the `MCP-Session-Id` and `MCP-Protocol-Version` response headers.
-3. Send `notifications/initialized` with both response headers and expect HTTP 
status code `202`.
-4. Include both headers on later MCP requests.
-
-After the session is closed, the session id cannot be reused.
+The exact configuration file location and field names may differ by client. 
Follow the client's own documentation.
 
 ## STDIO configuration
 
@@ -64,19 +54,16 @@ Add the following snippet to the MCP client's server 
configuration. The exact fi
 ```
 
 STDIO mode is for local MCP clients that launch ShardingSphere-MCP as a child 
process.
-It is not a human-oriented interactive shell.
 Replace `/path/to/apache-shardingsphere-mcp` with the actual distribution 
directory.
 
 In STDIO mode:
 
-- stdout is reserved for MCP protocol frames.
 - 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.
 
 ## Using the integration
 
-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.
+After the client is configured with the MCP Server, users describe tasks 
directly in the client conversation.
 
 Examples:
 
@@ -86,4 +73,4 @@ Examples:
 - Plan a data encryption or data masking rule and preview it without execution.
 
 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.
+For custom clients or protocol debugging, use the [Capability 
Catalog](../capabilities/) to confirm available capabilities.
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md 
b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
index b678bf67d88..d15d0da3326 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
@@ -51,13 +51,13 @@ runtimeDatabases:
     driverClassName: "com.mysql.cj.jdbc.Driver"
 ```
 
-| 字段 | 是否必填 | 说明 |
-| --- | --- | --- |
-| `databaseType` | 是 | 连接端点的数据库协议或方言类型，例如 `MySQL` 或 `PostgreSQL`。它用于选择 JDBC 
元数据和能力判断逻辑，不表示连接目标一定是真实数据库或 ShardingSphere-Proxy。 |
-| `jdbcUrl` | 是 | MCP Server 连接运行时数据库的 JDBC URL；使用 ShardingSphere 规则能力时应指向 
Proxy 逻辑库。 |
-| `username` | 是 | 连接运行时数据库的用户名，通常是 ShardingSphere-Proxy 逻辑库用户名。 |
-| `password` | 否 | 连接运行时数据库的密码；无密码账号可以省略或写空字符串 `""`。 |
-| `driverClassName` | 是 | JDBC 驱动类名，例如 MySQL 驱动使用 `com.mysql.cj.jdbc.Driver`。 |
+| *名称* | *说明* |
+| --- | --- |
+| `databaseType (+)` | 连接端点的数据库协议或方言类型，例如 `MySQL` 或 
`PostgreSQL`。它用于正确读取目标数据库元数据，不表示连接目标一定是真实数据库或 ShardingSphere-Proxy。 |
+| `jdbcUrl (+)` | MCP Server 连接运行时数据库的 JDBC URL；使用 ShardingSphere 规则能力时应指向 
Proxy 逻辑库。 |
+| `username (+)` | 连接运行时数据库的用户名，通常是 ShardingSphere-Proxy 逻辑库用户名。 |
+| `password (?)` | 连接运行时数据库的密码。 |
+| `driverClassName (+)` | JDBC 驱动类名，例如 MySQL 驱动使用 `com.mysql.cj.jdbc.Driver`。 |
 
 注意事项：
 
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
index a11854e2622..11c17836613 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
@@ -51,13 +51,13 @@ runtimeDatabases:
     driverClassName: "com.mysql.cj.jdbc.Driver"
 ```
 
-| Field | Required | Description |
-| --- | --- | --- |
-| `databaseType` | Yes | Database protocol or dialect type of the connection 
endpoint, such as `MySQL` or `PostgreSQL`. It selects JDBC metadata and 
capability logic; it does not mean the endpoint is necessarily a physical 
database or ShardingSphere-Proxy. |
-| `jdbcUrl` | Yes | JDBC URL used by the MCP Server to connect to the runtime 
database. Point it to a Proxy logical database when using ShardingSphere rule 
capabilities. |
-| `username` | Yes | Username for the runtime database, usually the 
ShardingSphere-Proxy logical database username. |
-| `password` | No | Password for the runtime database. Omit it or use an empty 
string `""` for a no-password account. |
-| `driverClassName` | Yes | JDBC driver class name, such as 
`com.mysql.cj.jdbc.Driver` for the MySQL driver. |
+| *Name* | *Description* |
+| --- | --- |
+| `databaseType (+)` | Database protocol or dialect type of the connection 
endpoint, such as `MySQL` or `PostgreSQL`. It is used to read target database 
metadata correctly; it does not mean the endpoint is necessarily a physical 
database or ShardingSphere-Proxy. |
+| `jdbcUrl (+)` | JDBC URL used by the MCP Server to connect to the runtime 
database. Point it to a Proxy logical database when using ShardingSphere rule 
capabilities. |
+| `username (+)` | Username for the runtime database, usually the 
ShardingSphere-Proxy logical database username. |
+| `password (?)` | Password for the runtime database. |
+| `driverClassName (+)` | JDBC driver class name, such as 
`com.mysql.cj.jdbc.Driver` for the MySQL driver. |
 
 Notes:
 
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 889ae25136d..4ab54462193 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 通过功能插件扩展领域能力。
-功能插件如果需要多步骤治理变更，会使用[插件工作流](plugin-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 ac9cc8ac14c..efc80d6aa8a 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](plugin-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 requirement confirmation, preview, apply, and 
validation.
 
 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 df1cd557cf6..e9df7204fd4 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
@@ -1,10 +1,10 @@
 +++
 title = "数据加密"
-weight = 1
+weight = 2
 +++
 
-数据加密 MCP 功能插件帮助 MCP 客户端把加密需求规划成 ShardingSphere-Proxy 可执行的 
DDL、DistSQL、索引计划和校验步骤。
-它不在 MCP Server 内实现加密算法，而是面向 ShardingSphere 逻辑库生成和执行加密规则变更。
+数据加密 MCP 功能插件帮助用户为 ShardingSphere-Proxy 逻辑库规划、审查、执行和校验数据加密规则变更。
+实际加密能力由 ShardingSphere-Proxy 及其加密算法插件提供。
 
 ## 前置条件
 
@@ -16,8 +16,6 @@ weight = 1
 ## 通过自然语言使用
 
 用户在 MCP 客户端中描述加密目标即可。
-模型会读取表结构、可用加密算法和已有规则，再生成可审查的加密规则计划。
-用户不需要手工拼接工具参数或 JSON-RPC 请求。
 
 示例：
 
@@ -26,105 +24,62 @@ weight = 1
 - 使用 AES 算法继续刚才的计划，密钥通过受保护渠道提供。
 - 确认并执行刚才的加密规则计划，然后校验结果。
 
-模型或客户端会把这些任务拆成读取资源、规划规则、预览执行和校验结果。
 用户需要审查计划中的 DistSQL、DDL、索引建议和副作用范围，再批准有副作用的执行。
 
-## 规则规划
+## 提出加密需求
 
-规则规划是数据加密插件的第一阶段。
-模型通常先读取算法和已有规则资源，再调用规划工具生成 `plan_id` 和可审查计划。
-规划工具不会直接修改数据库；后续预览、执行和校验由[插件工作流](../plugin-workflow/)阶段工具完成。
+建议在自然语言中说明以下信息：
 
-### 规划输入
+| 信息 | 说明 | 示例 |
+| --- | --- | --- |
+| 逻辑库、表和列 | 指定要配置加密规则的 ShardingSphere-Proxy 逻辑对象。 | “为 
`<logic-database>.orders.status` 配置加密。” |
+| schema 或 namespace | 多 schema 逻辑库建议说明。 | “schema 是 `public`。” |
+| 操作类型 | 创建、修改或删除加密规则。 | “新增加密规则”或“删除这个列的加密规则”。 |
+| 加密目标 | 说明是否需要可逆加密、等值查询或模糊查询。 | “需要可逆加密，并支持等值查询。” |
+| 算法偏好 | 可以指定算法，也可以要求 MCP 根据可用算法推荐。 | “优先使用 AES。” |
+| 算法参数 | 例如密钥等敏感参数，应通过受保护渠道提供。 | “密钥通过受保护渠道提供。” |
+| 索引建议 | 是否允许为辅助查询列生成物理索引建议。 | “允许生成等值查询辅助列的索引建议。” |
 
-规划工具的公共输入如下：
+## 创建、修改和删除规则
 
-| 参数 | 是否必填 | 作用 |
-| --- | --- | --- |
-| `database` | 必填 | ShardingSphere-Proxy 暴露的逻辑库名称。 |
-| `table` | 必填 | 要配置加密规则的逻辑表。 |
-| `column` | 必填 | 要配置加密规则的逻辑列。 |
-| `schema` | 可选 | schema 或 namespace；多 schema 逻辑库建议填写。 |
-| `natural_language_intent` | 推荐 | 描述是否需要可逆加密、等值查询或模糊查询；当未显式填写规则细节时，MCP 
会用它推断规划意图。 |
-| `operation_type` | 可选 | 规则操作类型；支持 `create`、`alter` 和 `drop`。不填写时由 MCP 
根据自然语言和已有规则推断。 |
-| `algorithm_type` | 可选 | 主加密算法类型；如果希望 MCP 基于可用算法给出建议，可以先不填。 |
-| `primary_algorithm_properties` | 按算法必填 | 主加密算法参数，例如 AES 密钥。具体参数以算法资源返回值为准。 |
-| `allow_index_ddl` | 可选 | 是否允许为辅助查询列生成物理索引计划。 |
-
-`database`、`schema`、`table` 和 `column` 是结构化工具参数，不是从 `natural_language_intent` 
中解析出来的 SQL 片段。
-MCP 客户端或模型应先通过 Proxy 元数据、资源或补全确认对象名，再把选中的对象名填入这些参数。
-MCP 会基于这些参数生成可审查的 DistSQL 和 SQL 产物。显式定界的意图会被保留；DistSQL 只在自身语法需要时补反引号；物理 SQL 
只在参数显式定界或无法作为普通 SQL token 输出时使用目标数据库的引用字符。
-标识符内容不能包含反引号、NUL、回车或换行等无法生成可审查 SQL 的字符。
-
-不同操作的输入重点如下：
-
-| 操作 | 输入重点 | 规划结果 |
+| 操作 | 自然语言示例 | 计划内容 |
 | --- | --- | --- |
-| `create` | 提供目标列、加密意图、算法类型和算法参数；如果希望 MCP 推荐算法，可以先只提供自然语言意图。 | 生成新增规则 
DistSQL，并在需要时生成物理派生列 DDL 和索引建议。 |
-| `alter` | 提供目标列和要调整的算法、查询能力或算法参数。 | 生成保留同表其他列规则的修改规则 DistSQL，并按需更新 DDL 
或索引建议。 |
-| `drop` | 至少提供 `database`、`table`、`column` 和 `operation_type=drop`。 | 
如果同表还有其他加密列，生成保留其他列的 `ALTER ENCRYPT RULE`；如果目标表不再保留任何加密列，生成 `DROP ENCRYPT 
RULE`。 |
+| 创建 | “为 `orders.status` 规划可逆加密，需要支持等值查询，先预览不要执行。” | 生成新增规则 
DistSQL，并在需要时生成物理派生列 DDL 和索引建议。 |
+| 修改 | “把刚才的加密计划改成 AES 算法，并继续预览。” | 生成保留同表其他列规则的修改规则 DistSQL，并按需更新 DDL 或索引建议。 |
+| 删除 | “删除 `orders.status` 的加密规则，先预览影响范围。” | 生成删除目标列规则的 
DistSQL；如同表还有其他加密列，会保留其他列规则。 |
 
-### 规划结果
+## 审查加密计划
 
-典型规划结果包括：
+计划生成后，应重点审查：
 
-- `plan_id`，用于后续预览、执行和校验。
-- `status`，取值通常为 `planned` 或 `clarifying`。
-- `derived_column_plan`，说明派生列命名。
-- `ddl_artifacts`，可能包含物理列 DDL。
-- `distsql_artifacts`，包含 `CREATE/ALTER/DROP ENCRYPT RULE`。
-- `index_plan`，可能包含辅助查询索引建议。
-
-如果返回 `clarifying`，继续使用同一个 `plan_id` 补齐缺失字段。
-敏感字段不会明文回显，应通过密钥管理系统、受保护环境变量或运维控制通道取得后再继续。
+- DistSQL 是否符合创建、修改或删除加密规则的预期。
+- 是否需要新增物理派生列。
+- 是否生成索引建议，以及索引是否适合当前物理库表结构。
+- 密钥、凭证等敏感参数是否只以占位符或受保护方式传递。
+- 是否会影响查询能力、运行时规则或已有业务 SQL。
 
 ## 派生列与索引计划
 
-派生列与索引计划是规则规划的输出内容，不是需要用户单独调用的能力。
 加密规则可能需要物理派生列来保存密文或支持查询。
-MCP 会根据逻辑列、用户意图和已有规则生成派生列建议，并把最终命名写入 `derived_column_plan`。
+MCP 会根据逻辑列、用户意图和已有规则生成派生列建议。
 
 - `*_cipher` 用于保存密文，是加密规则的默认派生列。
 - 如果需要等值查询，会生成 `*_assisted_query`，并在允许索引 DDL 时生成相应索引计划。
 - 如果需要模糊查询，会生成 `*_like_query`，用于支持 LIKE 查询场景。
-- 如果默认列名冲突，系统会追加数字后缀，并把最终命名写回 `derived_column_plan`。
+- 如果默认列名冲突，系统会追加数字后缀，并在计划中返回最终命名。
 
-## 执行与校验
+## 预览、执行和校验
 
-规划工具返回 `plan_id` 后，模型或客户端再使用插件工作流阶段工具处理执行和校验。
 建议先预览，确认 DistSQL、DDL、索引计划和副作用范围后再执行。
 
-| 阶段 | 用户表达 | 模型或客户端动作 |
+| 阶段 | 自然语言示例 | 用户关注点 |
 | --- | --- | --- |
-| 预览 | “先预览刚才的加密规则计划，不要执行。” | 使用 `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 可执行性。 |
-
-校验重点：
-
-- `ddl_validation`
-- `rule_validation`
-- `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` 候选值。 |
+| 预览 | “先预览刚才的加密规则计划，不要执行。” | 查看将要执行的 DistSQL、DDL 和索引建议。 |
+| 执行 | “确认执行刚才的计划。” | 确认有副作用的变更已经过审查。 |
+| 人工执行 | “导出人工执行包，不要自动执行。” | 由运维人员在受控环境审查和执行。 |
+| 校验 | “校验刚才的加密规则是否生效。” | 查看规则状态、逻辑元数据、物理列建议和 SQL 可执行性。 |
+
+插件变更的通用审查流程见[插件工作流](../plugin-workflow/)。
 
 ## 限制
 
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 cbd7758d868..9964f0ae0c0 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
@@ -1,10 +1,10 @@
 +++
 title = "Data Encryption"
-weight = 1
+weight = 2
 +++
 
-The Data Encryption MCP feature helps MCP clients plan encryption requirements 
into DDL, DistSQL, index plans, and validation steps executable through 
ShardingSphere-Proxy.
-It does not implement encryption algorithms inside the MCP Server. It 
generates and applies encryption rule changes for ShardingSphere logical 
databases.
+The Data Encryption MCP feature plugin helps users plan, review, apply, and 
validate data encryption rule changes for ShardingSphere-Proxy logical 
databases.
+Actual encryption capability is provided by ShardingSphere-Proxy and its 
encryption algorithm plugins.
 
 ## Prerequisites
 
@@ -16,8 +16,6 @@ It does not implement encryption algorithms inside the MCP 
Server. It generates
 ## Use through natural language
 
 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:
 
@@ -26,105 +24,62 @@ Examples:
 - 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
+## Describe an encryption requirement
 
-Rule planning is the first phase of the encryption 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.
+When using natural language, include the following information when possible:
 
-### Planning input
+| Information | Description | Example |
+| --- | --- | --- |
+| Logical database, table, and column | Specify the ShardingSphere-Proxy 
logical object to configure. | "Configure encryption for 
`<logic-database>.orders.status`." |
+| Schema or namespace | Recommended for multi-schema logical databases. | "The 
schema is `public`." |
+| Operation type | Create, alter, or drop an encryption rule. | "Create an 
encryption rule" or "drop the encryption rule for this column." |
+| Encryption goal | Describe whether reversible encryption, equality query, or 
LIKE query is required. | "Use reversible encryption and support equality 
queries." |
+| Algorithm preference | Specify an algorithm, or let MCP recommend one from 
available algorithms. | "Prefer AES." |
+| Algorithm properties | Sensitive values such as keys should be supplied 
through protected channels. | "The key is supplied through a protected 
channel." |
+| Index suggestions | Whether physical index suggestions for assisted query 
columns are allowed. | "Allow index suggestions for the assisted query column." 
|
 
-The planning tool uses these common inputs:
+## Create, alter, and drop rules
 
-| Argument | Required | Purpose |
-| --- | --- | --- |
-| `database` | Required | Logical database name exposed by 
ShardingSphere-Proxy. |
-| `table` | Required | Logical table to configure. |
-| `column` | Required | Logical column to configure. |
-| `schema` | Optional | Schema or namespace. Recommended for multi-schema 
logical databases. |
-| `natural_language_intent` | Recommended | Describes whether reversible 
encryption, equality query, or LIKE query support is needed. MCP uses it to 
infer planning intent when rule details are not explicit. |
-| `operation_type` | Optional | Rule operation type. Supported values are 
`create`, `alter`, and `drop`. If omitted, MCP infers it from natural language 
and existing rules. |
-| `algorithm_type` | Optional | Primary encryption algorithm type. Omit it if 
you want MCP to recommend one from available algorithms. |
-| `primary_algorithm_properties` | Required by algorithm | Primary encryption 
algorithm properties, such as an AES key. The required properties come from the 
algorithm resource. |
-| `allow_index_ddl` | Optional | Whether physical index plans may be generated 
for assisted-query columns. |
-
-`database`, `schema`, `table`, and `column` are structured tool arguments, not 
SQL snippets parsed from `natural_language_intent`.
-A client or model should resolve object names from Proxy metadata, resources, 
or completions before filling these arguments.
-MCP renders reviewable DistSQL and SQL artifacts from those arguments. 
Explicit delimiter intent is preserved; DistSQL identifiers are quoted only 
when DistSQL syntax requires it; physical SQL identifiers use the target 
database quote style only when the argument is explicitly delimited or cannot 
be rendered as a plain SQL token.
-Identifier content must not contain backticks, NUL, carriage-return, or 
line-feed characters because they cannot be rendered as reviewable SQL.
-
-Different operations focus on different inputs:
-
-| Operation | Input focus | Planning result |
+| Operation | Natural language example | Plan content |
 | --- | --- | --- |
-| `create` | Provide the target column, encryption 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, and physical 
derived-column DDL or index suggestions when needed. |
-| `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. |
+| Create | "Plan reversible encryption for `orders.status`, support equality 
queries, and preview first." | Generates new rule DistSQL, and physical 
derived-column DDL or index suggestions when needed. |
+| Alter | "Change the previous encryption plan to use AES, then preview it 
again." | Generates alter-rule DistSQL that keeps sibling column rules on the 
same table and updates DDL or index suggestions when needed. |
+| Drop | "Drop the encryption rule for `orders.status` and preview the impact 
first." | Generates DistSQL to drop the target column rule. Sibling encrypted 
columns on the same table are preserved. |
 
-### Planning result
+## Review the encryption plan
 
-A typical planning result includes:
+After a plan is generated, review:
 
-- `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.
+- Whether DistSQL matches the expected create, alter, or drop operation.
+- Whether physical derived columns are required.
+- Whether index suggestions are generated and suitable for the current 
physical table structure.
+- Whether keys, credentials, or other sensitive parameters are passed only 
through placeholders or protected channels.
+- Whether query capability, runtime rules, or existing business SQL may be 
affected.
 
 ## 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`.
+MCP creates derived-column suggestions from the logical column, user intent, 
and existing rules.
 
 - `*_cipher` stores ciphertext and is the default derived column for 
encryption rules.
 - If equality query is required, `*_assisted_query` is generated. Its index 
plan is generated when index DDL is allowed.
 - If LIKE query is required, `*_like_query` is generated for LIKE query 
scenarios.
-- If a default column name conflicts, the system appends a numeric suffix and 
returns the final name in `derived_column_plan`.
+- If a default column name conflicts, the system appends a numeric suffix and 
returns the final name in the plan.
 
-## Apply and validate
+## Preview, apply, and validate
 
-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.
 
-| Phase | User expression | Model or client action |
+| Phase | Natural language example | User focus |
 | --- | --- | --- |
-| 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:
-
-- `ddl_validation`
-- `rule_validation`
-- `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`. |
+| Preview | "Preview the previous encryption rule plan without executing it." 
| Inspect DistSQL, DDL, and index suggestions before execution. |
+| Execute | "Confirm and execute the previous plan." | Confirm that the 
side-effecting change has been reviewed. |
+| Manual execution | "Export a manual execution package without automatic 
execution." | Let operators review and execute in a controlled environment. |
+| Validate | "Validate whether the previous encryption rule has taken effect." 
| Check rule state, logical metadata, physical column suggestions, and SQL 
executability. |
+
+For the general review flow of plugin changes, see [Plugin 
Workflows](../plugin-workflow/).
 
 ## Limitations
 
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 ed6db047053..e6d4f1b4550 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
@@ -1,9 +1,9 @@
 +++
 title = "数据脱敏"
-weight = 2
+weight = 3
 +++
 
-数据脱敏 MCP 功能插件帮助 MCP 客户端把脱敏需求规划成 ShardingSphere-Proxy 可执行的 DistSQL 和校验步骤。
+数据脱敏 MCP 功能插件帮助用户为 ShardingSphere-Proxy 逻辑库规划、审查、执行和校验数据脱敏规则变更。
 脱敏规则直接作用于逻辑列，不生成加密功能使用的物理派生列。
 
 ## 前置条件
@@ -16,8 +16,6 @@ weight = 2
 ## 通过自然语言使用
 
 用户在 MCP 客户端中描述脱敏目标即可。
-模型会读取表结构、可用脱敏算法和已有规则，再生成可审查的脱敏规则计划。
-用户不需要手工拼接工具参数或 JSON-RPC 请求。
 
 示例：
 
@@ -26,91 +24,50 @@ weight = 2
 - 调整刚才的计划，把替换字符改成 `*`。
 - 确认并执行刚才的脱敏规则计划，然后校验结果。
 
-模型或客户端会把这些任务拆成读取资源、规划规则、预览执行和校验结果。
 用户需要审查计划中的 DistSQL 和副作用范围，再批准有副作用的执行。
 
-## 规则规划
+## 提出脱敏需求
 
-规则规划是数据脱敏插件的第一阶段。
-模型通常先读取算法和已有规则资源，再调用规划工具生成 `plan_id` 和可审查计划。
-规划工具不会直接修改数据库；后续预览、执行和校验由[插件工作流](../plugin-workflow/)阶段工具完成。
+建议在自然语言中说明以下信息：
 
-### 规划输入
+| 信息 | 说明 | 示例 |
+| --- | --- | --- |
+| 逻辑库、表和列 | 指定要配置脱敏规则的 ShardingSphere-Proxy 逻辑对象。 | “为 
`<logic-database>.orders.phone` 配置脱敏。” |
+| schema 或 namespace | 多 schema 逻辑库建议说明。 | “schema 是 `public`。” |
+| 操作类型 | 创建、修改或删除脱敏规则。 | “新增脱敏规则”或“删除这个列的脱敏规则”。 |
+| 脱敏目标 | 说明保留位数、替换字符或其他脱敏效果。 | “手机号保留前 3 后 4，中间用 `*` 替换。” |
+| 算法偏好 | 可以指定算法，也可以要求 MCP 根据可用算法推荐。 | “优先使用 keep-first-n-last-m 算法。” |
+| 算法参数 | 例如保留位数和替换字符。 | “保留前 3 后 4，替换字符是 `*`。” |
 
-规划工具的公共输入如下：
+## 创建、修改和删除规则
 
-| 参数 | 是否必填 | 作用 |
-| --- | --- | --- |
-| `database` | 必填 | ShardingSphere-Proxy 暴露的逻辑库名称。 |
-| `table` | 必填 | 要配置脱敏规则的逻辑表。 |
-| `column` | 必填 | 要配置脱敏规则的逻辑列。 |
-| `schema` | 可选 | schema 或 namespace；多 schema 逻辑库建议填写。 |
-| `natural_language_intent` | 推荐 | 描述脱敏目标，例如手机号保留位数或替换字符；当未显式填写规则细节时，MCP 
会用它推断规划意图。 |
-| `operation_type` | 可选 | 规则操作类型；支持 `create`、`alter` 和 `drop`。不填写时由 MCP 
根据自然语言和已有规则推断。 |
-| `algorithm_type` | 可选 | 脱敏算法类型；如果希望 MCP 基于可用算法给出建议，可以先不填。 |
-| `primary_algorithm_properties` | 按算法必填 | 脱敏算法参数，例如保留位数和替换字符。具体参数以算法资源返回值为准。 |
-
-`database`、`schema`、`table` 和 `column` 是结构化工具参数，不是从 `natural_language_intent` 
中解析出来的 SQL 片段。
-MCP 客户端或模型应先通过 Proxy 元数据、资源或补全确认对象名，再把选中的对象名填入这些参数。
-MCP 会基于这些参数生成可审查的 DistSQL 和 SQL 产物。显式定界的意图会被保留；DistSQL 只在自身语法需要时补反引号；物理 SQL 
只在参数显式定界或无法作为普通 SQL token 输出时使用目标数据库的引用字符。
-标识符内容不能包含反引号、NUL、回车或换行等无法生成可审查 SQL 的字符。
-
-不同操作的输入重点如下：
-
-| 操作 | 输入重点 | 规划结果 |
+| 操作 | 自然语言示例 | 计划内容 |
 | --- | --- | --- |
-| `create` | 提供目标列、脱敏意图、算法类型和算法参数；如果希望 MCP 推荐算法，可以先只提供自然语言意图。 | 生成新增规则 
DistSQL。 |
-| `alter` | 提供目标列和要调整的算法或算法参数。 | 生成保留同表其他列规则的修改规则 DistSQL。 |
-| `drop` | 至少提供 `database`、`table`、`column` 和 `operation_type=drop`。 | 
如果同表还有其他脱敏列，生成保留其他列的 `ALTER MASK RULE`；如果目标表不再保留任何脱敏列，生成 `DROP MASK RULE`。 |
+| 创建 | “为 `orders.phone` 规划手机号脱敏，先预览不要执行。” | 生成新增规则 DistSQL。 |
+| 修改 | “把刚才的脱敏规则改成保留前 3 后 4。” | 生成保留同表其他列规则的修改规则 DistSQL。 |
+| 删除 | “删除 `orders.phone` 的脱敏规则，先预览影响范围。” | 生成删除目标列规则的 
DistSQL；如同表还有其他脱敏列，会保留其他列规则。 |
 
-### 规划结果
+## 审查脱敏计划
 
-典型规划结果包括：
+计划生成后，应重点审查：
 
-- `plan_id`，用于后续预览、执行和校验。
-- `status`，取值通常为 `planned` 或 `clarifying`。
-- `distsql_artifacts`，包含 `CREATE/ALTER/DROP MASK RULE`。
-- `ddl_artifacts`，通常为空。
-- `index_plan`，通常为空。
-
-如果返回 `clarifying`，继续使用同一个 `plan_id` 补齐缺失字段。
-敏感字段不会明文回显，应通过密钥管理系统、受保护环境变量或运维控制通道取得后再继续。
+- DistSQL 是否符合创建、修改或删除脱敏规则的预期。
+- 脱敏算法和参数是否符合业务合规要求。
+- 删除规则后，通过 Proxy 查询该列时是否不再应用该脱敏规则。
+- 是否会影响运行时规则或已有业务 SQL。
 
 ## 执行与校验
 
-规划工具返回 `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 可执行性。 |
-
-校验重点：
-
-- `rule_validation`
-- `logical_metadata_validation`
-- `sql_executability_validation`
-
-插件工作流的状态、执行模式和敏感输入处理方式见[插件工作流](../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` 候选值。 |
+| 预览 | “先预览刚才的脱敏规则计划，不要执行。” | 查看将要执行的 DistSQL 和副作用范围。 |
+| 执行 | “确认执行刚才的计划。” | 确认有副作用的变更已经过审查。 |
+| 人工执行 | “导出人工执行包，不要自动执行。” | 由运维人员在受控环境审查和执行。 |
+| 校验 | “校验刚才的脱敏规则是否生效。” | 查看规则状态、逻辑元数据和 SQL 可执行性。 |
+
+插件变更的通用审查流程见[插件工作流](../plugin-workflow/)。
 
 ## 限制
 
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 c1c02d7d64e..8c8b86b9d07 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
@@ -1,9 +1,9 @@
 +++
 title = "Data Masking"
-weight = 2
+weight = 3
 +++
 
-The Data Masking MCP feature helps MCP clients plan masking requirements into 
DistSQL and validation steps executable through ShardingSphere-Proxy.
+The Data Masking MCP feature plugin helps users plan, review, apply, and 
validate data masking rule changes for ShardingSphere-Proxy logical databases.
 Mask rules apply directly to logical columns and do not generate physical 
derived columns used by the Encrypt feature.
 
 ## Prerequisites
@@ -16,8 +16,6 @@ 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.
-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:
 
@@ -26,91 +24,50 @@ Examples:
 - 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.
 
-## Rule planning
+## Describe a masking requirement
 
-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.
+When using natural language, include the following information when possible:
 
-### Planning input
+| Information | Description | Example |
+| --- | --- | --- |
+| Logical database, table, and column | Specify the ShardingSphere-Proxy 
logical object to configure. | "Configure masking for 
`<logic-database>.orders.phone`." |
+| Schema or namespace | Recommended for multi-schema logical databases. | "The 
schema is `public`." |
+| Operation type | Create, alter, or drop a masking rule. | "Create a masking 
rule" or "drop the masking rule for this column." |
+| Masking goal | Describe retained characters, replacement characters, or 
other masking effects. | "Keep the first 3 and last 4 phone-number characters, 
and replace the middle part with `*`." |
+| Algorithm preference | Specify an algorithm, or let MCP recommend one from 
available algorithms. | "Prefer the keep-first-n-last-m algorithm." |
+| Algorithm properties | Provide retained character counts and replacement 
characters. | "Keep the first 3 and last 4 characters, and use `*` as the 
replacement character." |
 
-The planning tool uses these common inputs:
+## Create, alter, and drop rules
 
-| Argument | Required | Purpose |
-| --- | --- | --- |
-| `database` | Required | Logical database name exposed by 
ShardingSphere-Proxy. |
-| `table` | Required | Logical table to configure. |
-| `column` | Required | Logical column to configure. |
-| `schema` | Optional | Schema or namespace. Recommended for multi-schema 
logical databases. |
-| `natural_language_intent` | Recommended | Describes the masking target, such 
as retained phone-number digits or replacement character. MCP uses it to infer 
planning intent when rule details are not explicit. |
-| `operation_type` | Optional | Rule operation type. Supported values are 
`create`, `alter`, and `drop`. If omitted, MCP infers it from natural language 
and existing rules. |
-| `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. |
-
-`database`, `schema`, `table`, and `column` are structured tool arguments, not 
SQL snippets parsed from `natural_language_intent`.
-A client or model should resolve object names from Proxy metadata, resources, 
or completions before filling these arguments.
-MCP renders reviewable DistSQL and SQL artifacts from those arguments. 
Explicit delimiter intent is preserved; DistSQL identifiers are quoted only 
when DistSQL syntax requires it; physical SQL identifiers use the target 
database quote style only when the argument is explicitly delimited or cannot 
be rendered as a plain SQL token.
-Identifier content must not contain backticks, NUL, carriage-return, or 
line-feed characters because they cannot be rendered as reviewable SQL.
-
-Different operations focus on different inputs:
-
-| Operation | Input focus | Planning result |
+| Operation | Natural language example | Plan content |
 | --- | --- | --- |
-| `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. |
+| Create | "Plan phone-number masking for `orders.phone` and preview it 
without execution." | Generates DistSQL for adding the rule. |
+| Alter | "Change the previous masking rule to keep the first 3 and last 4 
characters." | Generates DistSQL that preserves sibling column rules on the 
same table. |
+| Drop | "Drop the masking rule for `orders.phone` and preview the impact 
first." | Generates DistSQL to drop the target column rule. Sibling masking 
columns on the same table are preserved. |
 
-### Planning result
+## Review the masking plan
 
-A typical planning result includes:
+After a plan is generated, review:
 
-- `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.
+- Whether DistSQL matches the expected create, alter, or drop operation.
+- Whether the masking algorithm and properties satisfy business compliance 
requirements.
+- Whether queries through Proxy no longer apply masking to the column after 
dropping a rule.
+- Whether runtime rules or existing business SQL may be affected.
 
 ## Apply and validate
 
-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 |
+| Phase | Natural language example | User focus |
 | --- | --- | --- |
-| 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:
-
-- `rule_validation`
-- `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_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`. |
+| Preview | "Preview the previous masking rule plan without executing it." | 
Inspect DistSQL and side-effect scope before execution. |
+| Execute | "Confirm and execute the previous plan." | Confirm that the 
side-effecting change has been reviewed. |
+| Manual execution | "Export a manual execution package without automatic 
execution." | Let operators review and execute in a controlled environment. |
+| Validate | "Validate whether the previous masking rule has taken effect." | 
Check rule state, logical metadata, and SQL executability. |
+
+For the general review flow of plugin changes, see [Plugin 
Workflows](../plugin-workflow/).
 
 ## Limitations
 
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
 
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
index 0f9f579e0f3..22bab1be90c 100644
--- 
a/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
+++ 
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
@@ -1,97 +1,55 @@
 +++
 title = "插件工作流"
-weight = 3
+weight = 1
 +++
 
-插件工作流是 ShardingSphere-MCP 处理多步骤治理变更的共享机制，不是一个独立的业务功能。
-功能插件负责理解具体业务、生成 `plan_id` 和变更产物；MCP Server 负责保存当前会话中的计划，并提供统一的预览、执行、导出和校验阶段接口。
+插件工作流用于功能插件生成可审查的数据库治理变更时，引导用户完成需求确认、预览、执行和校验。
+它不是一个独立业务功能；用户通常会在数据加密、数据脱敏等插件任务中进入这个流程。
 
-用户不会为了读取元数据、搜索对象或执行只读 SQL 单独使用插件工作流。
-只有当插件规划工具返回 `plan_id` 时，模型或客户端才需要继续按照本页完成审查、应用和校验。
-本页说明插件工作流，是因为这些阶段工具会出现在 MCP 工具列表中，并且不同插件共享同一套状态、执行模式和敏感输入处理方式。
-具体可规划的业务能力仍以各功能插件页面为准。
+## 适用场景
 
-## 基本阶段
+- 创建、修改或删除 ShardingSphere 规则。
+- 变更前需要查看将要执行的 DistSQL、DDL 或索引建议。
+- 不希望自动执行，希望导出人工执行包。
+- 执行后需要确认规则状态、逻辑元数据和 SQL 可执行性。
 
-一个典型工作流包含：
+## 基本流程
 
-1. 调用功能插件规划工具，生成计划并返回 `plan_id`。
-2. 如果返回 `status = clarifying`，按 `clarification_questions` 补齐缺失输入。
-3. 如果返回 `status = planned`，审查生成的变更产物。
-4. 模型或客户端调用 `database_gateway_apply_workflow`，并先使用 `execution_mode=preview`。
-5. 用户审查预览结果后，模型或客户端使用 `execution_mode=review-then-execute` 执行，或使用 
`manual-only` 导出人工执行包。
-6. 模型或客户端调用 `database_gateway_validate_workflow` 校验最终状态。
-
-## 会话与 plan_id
-
-- `plan_id` 是当前工作流的句柄。
-- `plan_id` 只在当前 MCP 会话内有效。
-- `plan`、`apply`、`validate` 必须使用同一个 `MCP-Session-Id`。
-- 第一次规划调用不需要传 `plan_id`。
-- 后续补问、执行和校验必须继续传同一个 `plan_id`。
-
-## 常见状态
-
-| 状态 | 说明 | 下一步 |
+| 阶段 | 用户操作 | 关注点 |
 | --- | --- | --- |
-| `clarifying` | 信息不足，需要补齐参数。 | 使用同一个 `plan_id` 再次调用原规划工具。 |
-| `planned` | 计划已生成，可以审查变更产物。 | 预览或导出人工执行包。 |
-| `completed` | 已执行完成。 | 调用校验工具确认最终状态。 |
-| `awaiting-manual-execution` | 选择了 `manual-only`。 | 人工执行返回的变更产物后再校验。 |
-| `validated` | 校验已通过。 | 向用户返回结果。 |
-| `failed` | 当前阶段失败。 | 查看 `issues`、`mismatches` 和 `recovery_guidance`。 |
-
-## 执行模式
+| 描述需求 | 说明要变更的逻辑库、表、列和治理目标。 | 信息越明确，生成的计划越稳定。 |
+| 补充信息 | 根据提示补齐算法、参数、密钥占位符或执行偏好。 | 敏感值应通过受保护渠道提供。 |
+| 审查计划 | 查看生成的 DistSQL、DDL、索引建议和影响范围。 | 确认是否符合业务预期。 |
+| 预览变更 | 要求先预览，不修改运行时状态。 | 检查将执行的语句和副作用。 |
+| 执行变更 | 确认自动执行，或导出人工执行包后由运维执行。 | 有副作用的变更必须经过确认。 |
+| 校验结果 | 执行后查看规则状态、元数据和 SQL 可执行性。 | 确认变更是否生效。 |
 
-`database_gateway_apply_workflow` 必须显式传入 `execution_mode`：
+## 执行方式
 
-| 执行模式 | 是否修改运行时状态 | 用途 |
+| 执行方式 | 是否修改运行时状态 | 适用场景 |
 | --- | --- | --- |
-| `preview` | 否 | 只预览变更产物和副作用范围。 |
-| `review-then-execute` | 是 | 审查后由 MCP Server 执行变更产物。 |
-| `manual-only` | 否 | 不自动执行，返回人工执行包。 |
-
-如果使用 `approved_steps` 分步执行，只能使用预览结果返回的 `preview_artifacts[].approval_step` 值。
-未知步骤会被拒绝。
+| 只预览 | 否 | 先查看变更产物和副作用范围。 |
+| 审查后执行 | 是 | 用户确认后，由 MCP Server 执行变更。 |
+| 人工执行包 | 否 | 不自动执行，返回可由运维人员审查和执行的语句。 |
 
 ## 敏感输入
 
-插件可能要求补充敏感字段，例如密钥或凭证。
-带有 `secret: true`、`input_type: "secret"`，或字段名包含 
password、token、key、secret、credential 的补问，不应通过普通表单明文回传。
+插件可能需要密钥或凭证等敏感字段。
+这些值不应写入普通文档、聊天记录或日志。
 
 推荐处理方式：
 
-- 保留 `plan_id`。
-- 客户端或运维侧通过密钥管理系统、受保护环境变量或运维控制通道取得值。
-- 用同一个 `plan_id` 再次调用原规划工具，并只在受保护的 MCP 调用中传入敏感字段。
+- 在计划中保留占位符。
+- 由客户端或运维侧通过密钥管理系统、受保护环境变量或运维控制通道取得真实值。
+- 在受控环境中替换占位符并执行。
 
 ShardingSphere-MCP 不直接读取密钥管理系统。
-如果使用人工执行包，可以在返回的 DistSQL 中保留占位符，并由执行人员在受控环境替换。
+使用人工执行包时，可以在 DistSQL 中保留占位符，由执行人员在受控环境替换。
 
-示例：
-
-```json
-{
-  "name": "database_gateway_plan_encrypt_rule",
-  "arguments": {
-    "plan_id": "${PLAN_ID}",
-    "primary_algorithm_properties": {
-      "aes-key-value": "${VALUE_FROM_SECRET_MANAGER}"
-    }
-  }
-}
-```
-
-## 阶段工具
-
-`database_gateway_apply_workflow` 和 `database_gateway_validate_workflow` 会出现在 
MCP 工具列表中，因此需要在文档中说明。
-它们不是独立业务功能，而是插件规划返回 `plan_id` 后使用的阶段接口。
-用户通常不需要直接选择它们；模型或客户端会在审查、执行和校验阶段调用。
-
-| 工具 | 实际作用 | 使用时机 |
-| --- | --- | --- |
-| `database_gateway_apply_workflow` | 对已有 `plan_id` 
做预览、审查后执行，或导出人工执行包；它不创建加密、脱敏等业务计划。 | 插件规划工具返回 `status = planned` 后。 |
-| `database_gateway_validate_workflow` | 根据可见元数据、规则状态和生成产物校验计划或执行结果；它不执行业务变更。 
| 自动执行或人工执行完成后。 |
+## 审查重点
 
-它们不决定业务语义，只处理当前会话中已存在的工作流计划。
-具体规划工具由功能插件提供。
+- DistSQL 是否符合预期规则变更。
+- DDL 或索引建议是否适合当前物理库表结构。
+- 是否会修改运行时规则、元数据或数据。
+- 是否需要人工执行、备份、回滚预案或业务审批。
+- 校验结果是否覆盖规则状态、逻辑元数据和 SQL 可执行性。
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
 
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
index 7df0414f637..e9d26808127 100644
--- 
a/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
+++ 
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
@@ -1,97 +1,55 @@
 +++
 title = "Plugin Workflows"
-weight = 3
+weight = 1
 +++
 
-Plugin workflows are the shared mechanism that ShardingSphere-MCP uses for 
multi-step governance changes. They are not standalone business features.
-Feature plugins understand concrete business semantics and create `plan_id` 
plus change artifacts. The MCP Server stores the current-session plan and 
provides shared phase interfaces for preview, apply, export, and validation.
+Plugin workflows guide users through requirement confirmation, preview, apply, 
and validation when a feature plugin creates a reviewable database governance 
change.
+They are not standalone business features. Users usually enter this flow from 
feature tasks such as data encryption or data masking.
 
-Users do not use plugin workflows just to read metadata, search objects, or 
run read-only SQL.
-Follow this page only after a plugin planning tool returns `plan_id`; then the 
model or client can review, apply, and validate that plan.
-This page explains plugin workflows because these phase tools appear in the 
MCP tool list, and multiple plugins share the same state model, execution 
modes, and sensitive-input handling.
-The concrete planning capabilities are still documented on the corresponding 
feature plugin pages.
+## When to use
 
-## Basic phases
+- Create, alter, or drop ShardingSphere rules.
+- Review DistSQL, DDL, or index suggestions before a change.
+- Export a manual execution package instead of applying changes automatically.
+- Validate rule state, logical metadata, and SQL executability after execution.
 
-A typical workflow contains:
+## Basic flow
 
-1. Call the feature plugin planning tool to create a plan and return `plan_id`.
-2. If the response returns `status = clarifying`, provide the missing inputs 
from `clarification_questions`.
-3. If the response returns `status = planned`, review the generated change 
artifacts.
-4. The model or client calls `database_gateway_apply_workflow` with 
`execution_mode=preview` first.
-5. After the user reviews the preview, the model or client calls with 
`execution_mode=review-then-execute`, or uses `manual-only` to export a manual 
execution package.
-6. The model or client calls `database_gateway_validate_workflow` to validate 
the final state.
-
-## Session and plan_id
-
-- `plan_id` is the handle for the current workflow.
-- `plan_id` is valid only in the current MCP session.
-- `plan`, `apply`, and `validate` must use the same `MCP-Session-Id`.
-- The first planning call does not need `plan_id`.
-- Follow-up clarification, apply, and validate calls must reuse the same 
`plan_id`.
-
-## Common statuses
-
-| Status | Meaning | Next step |
+| Phase | User action | Focus |
 | --- | --- | --- |
-| `clarifying` | More input is required. | Call the original planning tool 
again with the same `plan_id`. |
-| `planned` | The plan is ready and change artifacts should be reviewed. | 
Preview the plan or export a manual package. |
-| `completed` | Apply has completed. | Call the validation tool to confirm the 
final state. |
-| `awaiting-manual-execution` | `manual-only` was selected. | Execute the 
returned artifacts manually, then validate. |
-| `validated` | Validation passed. | Return the result to the user. |
-| `failed` | The current phase failed. | Inspect `issues`, `mismatches`, and 
`recovery_guidance`. |
-
-## Execution modes
+| Describe the requirement | Provide the logical database, table, column, and 
governance goal. | Clear input makes the generated plan more stable. |
+| Provide missing information | Add algorithm choices, parameters, secret 
placeholders, or execution preferences when asked. | Sensitive values should be 
provided through protected channels. |
+| Review the plan | Review generated DistSQL, DDL, index suggestions, and 
impact scope. | Confirm that the plan matches business expectations. |
+| Preview the change | Ask to preview first without changing runtime state. | 
Check statements and side effects before execution. |
+| Apply the change | Confirm automatic execution, or export a manual package 
for operators. | Side-effecting changes must be confirmed. |
+| Validate the result | Inspect rule state, metadata, and SQL executability 
after execution. | Confirm that the change has taken effect. |
 
-`database_gateway_apply_workflow` requires an explicit `execution_mode`:
+## Execution choices
 
-| Execution mode | Changes runtime state | Purpose |
+| Choice | Changes runtime state | Use case |
 | --- | --- | --- |
-| `preview` | No | Preview change artifacts and side-effect scope only. |
-| `review-then-execute` | Yes | Execute change artifacts through the MCP 
Server after review. |
-| `manual-only` | No | Export a manual artifact package without automatic 
execution. |
-
-When using `approved_steps` for partial execution, pass only values returned 
by `preview_artifacts[].approval_step`.
-Unknown steps are rejected.
+| Preview only | No | Inspect change artifacts and side-effect scope first. |
+| Execute after review | Yes | Execute the change through the MCP Server after 
user confirmation. |
+| Manual package | No | Return statements for operators to review and execute 
manually. |
 
 ## Sensitive inputs
 
-Plugins may ask for secret fields, such as keys or credentials.
-Questions with `secret: true`, `input_type: "secret"`, or field names 
containing password, token, key, secret, or credential should not be returned 
in plain text through ordinary forms.
+Plugins may require sensitive fields such as keys or credentials.
+These values should not be written into ordinary documents, chat records, or 
logs.
 
 Recommended handling:
 
-- Keep the `plan_id`.
-- Let the client or operator obtain the value through a secret manager, 
protected environment variable, or controlled operations channel.
-- Call the original planning tool again with the same `plan_id`, and pass the 
secret field only through a protected MCP call.
+- Keep placeholders in the plan.
+- Let the client or operator obtain real values through a secret manager, 
protected environment variable, or controlled operations channel.
+- Replace placeholders and execute in a controlled environment.
 
 ShardingSphere-MCP does not read secret managers directly.
-When using a manual package, keep placeholders in the returned DistSQL and let 
the operator replace them in a controlled environment.
+When using a manual package, placeholders can remain in DistSQL and be 
replaced by the operator in a controlled environment.
 
-Example:
-
-```json
-{
-  "name": "database_gateway_plan_encrypt_rule",
-  "arguments": {
-    "plan_id": "${PLAN_ID}",
-    "primary_algorithm_properties": {
-      "aes-key-value": "${VALUE_FROM_SECRET_MANAGER}"
-    }
-  }
-}
-```
-
-## Phase tools
-
-`database_gateway_apply_workflow` and `database_gateway_validate_workflow` 
appear in the MCP tool list, so they need to be documented.
-They are not standalone business features. They are phase interfaces used 
after plugin planning returns `plan_id`.
-Users usually do not choose them directly. A model or client calls them during 
review, apply, and validation phases.
-
-| Tool | Actual role | When to use |
-| --- | --- | --- |
-| `database_gateway_apply_workflow` | Previews an existing `plan_id`, executes 
reviewed artifacts, or exports a manual package. It does not create encryption, 
masking, or other business plans. | After a plugin planning tool returns 
`status = planned`. |
-| `database_gateway_validate_workflow` | Validates a plan or execution result 
against visible metadata, rule state, and generated artifacts. It does not 
execute business changes. | After automatic or manual execution finishes. |
+## Review checklist
 
-They do not define business semantics; they operate on workflow plans that 
already exist in the current session.
-Feature plugins provide the concrete planning tools.
+- Whether DistSQL matches the expected rule change.
+- Whether DDL or index suggestions fit the current physical table structure.
+- Whether runtime rules, metadata, or data may be changed.
+- Whether manual execution, backup, rollback planning, or business approval is 
required.
+- Whether validation covers rule state, logical metadata, and SQL 
executability.

(shardingsphere) branch master updated: Refine ShardingSphere-MCP user guide (#38770)

Reply via email to