(shardingsphere) branch master updated: Refine ShardingSphere MCP manual (#38751)

zhangliang Fri, 29 May 2026 00:05:30 -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 543a55be3eb Refine ShardingSphere MCP manual (#38751)
543a55be3eb is described below

commit 543a55be3eb257b254fb094dcac9e1dd520515d4
Author: Liang Zhang <[email protected]>
AuthorDate: Fri May 29 15:05:11 2026 +0800

    Refine ShardingSphere MCP manual (#38751)
    
    * Refine ShardingSphere MCP manual
    
    - Add a complete MCP capability index for resources, tools, prompts, and 
completions
    - Rename workflow documentation from workflow basics to workflow
    - Simplify quick start placeholders and platform-specific startup guidance
    - Convert configuration and workflow explanations to clearer tables
    - Rewrite troubleshooting around symptoms, actions, and code-improvement 
follow-ups
    - Align feature plugin naming and remove redundant limitation entries
    
    * Refine ShardingSphere MCP manual
    
    - Add a complete MCP capability index for resources, tools, prompts, and 
completions
    - Rename workflow documentation from workflow basics to workflow
    - Simplify quick start placeholders and platform-specific startup guidance
    - Convert configuration and workflow explanations to clearer tables
    - Rewrite troubleshooting around symptoms, actions, and code-improvement 
follow-ups
    - Align feature plugin naming and remove redundant limitation entries
---
 .../user-manual/shardingsphere-mcp/_index.cn.md    |   4 +-
 .../user-manual/shardingsphere-mcp/_index.en.md    |   4 +-
 .../shardingsphere-mcp/capabilities.cn.md          | 100 +++++++++++++++
 .../shardingsphere-mcp/capabilities.en.md          | 100 +++++++++++++++
 .../shardingsphere-mcp/client-integration.cn.md    |  35 +++---
 .../shardingsphere-mcp/client-integration.en.md    |  35 +++---
 .../shardingsphere-mcp/configuration.cn.md         |  58 ++++-----
 .../shardingsphere-mcp/configuration.en.md         |  58 ++++-----
 .../shardingsphere-mcp/deployment.cn.md            |   2 +-
 .../shardingsphere-mcp/deployment.en.md            |   2 +-
 .../shardingsphere-mcp/features/_index.cn.md       |   7 +-
 .../shardingsphere-mcp/features/_index.en.md       |   7 +-
 .../shardingsphere-mcp/features/encrypt.cn.md      |   9 +-
 .../shardingsphere-mcp/features/encrypt.en.md      |   9 +-
 .../shardingsphere-mcp/features/mask.cn.md         |  10 +-
 .../shardingsphere-mcp/features/mask.en.md         |  10 +-
 .../shardingsphere-mcp/quick-start.cn.md           |  88 +++++++++----
 .../shardingsphere-mcp/quick-start.en.md           |  88 +++++++++----
 .../shardingsphere-mcp/troubleshooting.cn.md       | 138 +++++----------------
 .../shardingsphere-mcp/troubleshooting.en.md       | 138 +++++----------------
 .../shardingsphere-mcp/workflow-basics.cn.md       |  63 ----------
 .../shardingsphere-mcp/workflow-basics.en.md       |  63 ----------
 .../user-manual/shardingsphere-mcp/workflow.cn.md  |  88 +++++++++++++
 .../user-manual/shardingsphere-mcp/workflow.en.md  |  88 +++++++++++++
 24 files changed, 682 insertions(+), 522 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 ed709b113bd..0b1b8451085 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
@@ -6,16 +6,16 @@ chapter = true
 +++
 
 ShardingSphere-MCP 是 Apache ShardingSphere 的 MCP Server，可以独立启动，并向 MCP 客户端暴露 
ShardingSphere 逻辑库的元数据、安全 SQL 访问能力和插件工作流。
-本文将 MCP 协议中的 tools、resources、prompts 和 completions 分别称为工具、资源、提示和补全；协议方法名和 JSON 
字段名仍保留英文，例如 `tools/list` 和 `resources/read`。
 
 ShardingSphere-MCP 的配置以数据库为核心：先配置 MCP Server 可以连接的 ShardingSphere 逻辑库，再通过 MCP 
客户端读取元数据或调用 SQL 工具。
 
 ## 文档结构
 
 - 快速开始：构建发行包，配置一个可连接的逻辑库，启动 HTTP MCP Server，并验证元数据读取和只读 SQL 查询。
+- 功能介绍：说明 MCP Server 对外提供的资源、工具、提示、补全和工作流能力。
 - 配置说明：说明传输方式、`runtimeDatabases`、插件目录和启动参数。
 - 客户端集成：说明 HTTP、STDIO、会话响应头和能力发现调用方式。
-- 工作流基础：说明插件工作流共享的规划、执行和校验机制。
+- 工作流：说明插件工作流共享的规划、执行和校验机制。
 - 功能插件：说明官方 MCP 功能插件能力。
 - 部署说明：说明发行包、OCI 镜像和安全部署建议。
 - 常见问题：排查 MCP Server、传输方式、会话和 SQL 工具的通用问题。
diff --git a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
index 90b8eb64670..947bf53456f 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
@@ -6,16 +6,16 @@ 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.
-This manual uses the MCP terms tools, resources, prompts, and completions for 
the corresponding protocol capabilities. Protocol method names and JSON field 
names stay in their original form, such as `tools/list` and `resources/read`.
 
 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.
 
 ## Structure
 
 - Quick Start: build the distribution, configure a reachable logical database, 
start the HTTP MCP Server, and verify metadata reads and read-only SQL queries.
+- Capabilities: understand the resources, tools, prompts, completions, and 
workflows exposed by the MCP Server.
 - Configuration: configure transport, `runtimeDatabases`, plugin directories, 
and launch parameters.
 - Client Integration: use HTTP, STDIO, session response headers, and 
capability discovery calls.
-- Workflow Basics: understand the shared planning, apply, and validation flow 
used by feature plugins.
+- Workflows: understand the shared planning, apply, and validation flow used 
by feature plugins.
 - Feature Plugins: use official MCP feature plugins.
 - Deployment: deploy the binary distribution and OCI image safely.
 - Troubleshooting: diagnose common MCP Server, transport, session, and SQL 
tool issues.
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md 
b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
new file mode 100644
index 00000000000..f0464fa99d1
--- /dev/null
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
@@ -0,0 +1,100 @@
++++
+title = "功能介绍"
+weight = 2
++++
+
+本页列出 ShardingSphere-MCP 对外暴露的协议能力。
+运行时实际可用能力以 `shardingsphere://capabilities` 以及 MCP 官方列表方法返回值为准。
+
+## 发现入口
+
+| 协议能力 | 用途 |
+| --- | --- |
+| `tools/list` | 发现可调用工具。 |
+| `resources/list` | 发现可直接读取的资源。 |
+| `resources/templates/list` | 发现带参数的资源模板。 |
+| `prompts/list` | 发现可用提示。 |
+| `completion/complete` | 获取资源、提示或参数的补全候选。 |
+| `resources/read` 读取 `shardingsphere://capabilities` | 读取 ShardingSphere 
领域能力目录。 |
+
+## 静态资源
+
+| 资源 | 用途 |
+| --- | --- |
+| `shardingsphere://capabilities` | 查看资源、资源模板、工具、提示、补全、工作流关系和副作用提示。 |
+| `shardingsphere://runtime` | 查看当前传输方式、运行状态和已配置逻辑库摘要。 |
+| `shardingsphere://databases` | 列出当前 MCP Server 可以访问的 ShardingSphere 逻辑库。 |
+| `shardingsphere://features/encrypt/algorithms` | 列出当前 ShardingSphere-Proxy 
可见的数据加密算法插件。 |
+| `shardingsphere://features/mask/algorithms` | 列出当前 ShardingSphere-Proxy 
可见的数据脱敏算法插件。 |
+
+## 资源模板
+
+| 资源模板 | 用途 |
+| --- | --- |
+| `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://features/encrypt/databases/{database}/rules` | 
列出一个逻辑库中的数据加密规则。 |
+| 
`shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules` | 
读取一个逻辑表的数据加密规则。 |
+| `shardingsphere://features/mask/databases/{database}/rules` | 
列出一个逻辑库中的数据脱敏规则。 |
+| `shardingsphere://features/mask/databases/{database}/tables/{table}/rules` | 
读取一个逻辑表的数据脱敏规则。 |
+
+## 工具
+
+| 工具 | 用途 | 副作用 |
+| --- | --- | --- |
+| `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` | 预览、执行或导出已规划工作流的人工执行包。 | 取决于 
`execution_mode`；`preview` 和 `manual-only` 不修改运行时状态。 |
+| `database_gateway_validate_workflow` | 根据可见元数据和生成产物校验计划或执行结果。 | 无。 |
+| `database_gateway_plan_encrypt_rule` | 规划数据加密规则变更，生成可审查的 
DDL、DistSQL、索引计划和校验步骤。 | 无；只生成计划。 |
+| `database_gateway_plan_mask_rule` | 规划数据脱敏规则变更，生成可审查的 DistSQL 和校验步骤。 | 
无；只生成计划。 |
+
+## 提示
+
+| 提示 | 用途 |
+| --- | --- |
+| `inspect_metadata` | 引导模型读取逻辑库元数据，再选择搜索工具或详情资源。 |
+| `safe_sql_execution` | 引导模型区分只读查询和有副作用 SQL，并选择正确 SQL 工具。 |
+| `recover_workflow` | 引导模型在工作流失败或 `plan_id` 不可用时恢复或重新规划。 |
+| `plan_encrypt_rule` | 引导模型在规划数据加密规则前读取逻辑元数据、可用算法和已有规则。 |
+| `plan_mask_rule` | 引导模型在规划数据脱敏规则前读取逻辑元数据、可用算法和已有规则。 |
+
+## 补全目标
+
+| 目标类型 | 目标 | 补全参数 |
+| --- | --- | --- |
+| resource | `shardingsphere://databases/{database}` | `database` |
+| resource | `shardingsphere://databases/{database}/schemas` | `database` |
+| resource | `shardingsphere://databases/{database}/schemas/{schema}` | 
`database`、`schema` |
+| resource | `shardingsphere://databases/{database}/schemas/{schema}/tables` | 
`database`、`schema` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` | 
`database`、`schema`、`table` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns` 
| `database`、`schema`、`table` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
 | `database`、`schema`、`table`、`column` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes` 
| `database`、`schema`、`table` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
 | `database`、`schema`、`table`、`index` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/sequences` | 
`database`、`schema` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` | 
`database`、`schema`、`sequence` |
+| resource | `shardingsphere://workflows/{plan_id}` | `plan_id` |
+| resource | `shardingsphere://features/encrypt/algorithms` | 
`algorithm_type`、`assisted_query_algorithm_type`、`like_query_algorithm_type` |
+| resource | `shardingsphere://features/mask/algorithms` | `algorithm_type` |
+| prompt | `inspect_metadata` | `database`、`schema` |
+| prompt | `safe_sql_execution` | `database`、`schema` |
+| prompt | `recover_workflow` | `plan_id` |
+| prompt | `plan_encrypt_rule` | 
`database`、`schema`、`table`、`column`、`algorithm_type`、`assisted_query_algorithm_type`、`like_query_algorithm_type`、`plan_id`
 |
+| prompt | `plan_mask_rule` | 
`database`、`schema`、`table`、`column`、`algorithm_type`、`plan_id` |
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
new file mode 100644
index 00000000000..d8a5b1cc529
--- /dev/null
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
@@ -0,0 +1,100 @@
++++
+title = "Capabilities"
+weight = 2
++++
+
+This page lists the protocol capabilities exposed by ShardingSphere-MCP.
+The runtime source of truth is `shardingsphere://capabilities` plus the 
official MCP list methods.
+
+## Discovery entry points
+
+| Protocol capability | Purpose |
+| --- | --- |
+| `tools/list` | Discover callable tools. |
+| `resources/list` | Discover directly readable resources. |
+| `resources/templates/list` | Discover parameterized resource templates. |
+| `prompts/list` | Discover available prompts. |
+| `completion/complete` | Get completion candidates for resources, prompts, or 
arguments. |
+| `resources/read` with `shardingsphere://capabilities` | Read the 
ShardingSphere domain capability catalog. |
+
+## Static resources
+
+| Resource | Purpose |
+| --- | --- |
+| `shardingsphere://capabilities` | Read resources, resource templates, tools, 
prompts, completions, workflow relationships, and side-effect notes. |
+| `shardingsphere://runtime` | Read the current transport, runtime status, and 
configured logical database summary. |
+| `shardingsphere://databases` | List ShardingSphere logical databases 
reachable by the current MCP Server. |
+| `shardingsphere://features/encrypt/algorithms` | List data encryption 
algorithm plugins visible from the current ShardingSphere-Proxy runtime. |
+| `shardingsphere://features/mask/algorithms` | List data masking algorithm 
plugins visible from the current ShardingSphere-Proxy runtime. |
+
+## Resource templates
+
+| Resource template | Purpose |
+| --- | --- |
+| `shardingsphere://databases/{database}` | Read one logical database and its 
metadata summary. |
+| `shardingsphere://databases/{database}/capabilities` | Read SQL, 
transaction, schema, and metadata-object capabilities for one logical database. 
|
+| `shardingsphere://databases/{database}/schemas` | List schemas or namespaces 
inside one logical database. |
+| `shardingsphere://databases/{database}/schemas/{schema}` | Read one schema 
or namespace. |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | List 
sequences in one schema. |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` | 
Read one sequence. |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` | List 
logical tables in one schema. |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` | 
Read one logical table. |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns` 
| List columns for one logical table. |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
 | Read one logical table column. |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes` 
| List indexes for one logical table. |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
 | Read one logical table index. |
+| `shardingsphere://databases/{database}/schemas/{schema}/views` | List views 
in one schema. |
+| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` | Read 
one view. |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` | 
List columns for one view. |
+| 
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
 | Read one view column. |
+| `shardingsphere://workflows/{plan_id}` | Read a current-session workflow 
plan, clarification questions, artifacts, and next actions. |
+| `shardingsphere://features/encrypt/databases/{database}/rules` | List data 
encryption rules in one logical database. |
+| 
`shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules` | 
Read data encryption rules for one logical table. |
+| `shardingsphere://features/mask/databases/{database}/rules` | List data 
masking rules in one logical database. |
+| `shardingsphere://features/mask/databases/{database}/tables/{table}/rules` | 
Read data masking rules for one logical table. |
+
+## Tools
+
+| Tool | Purpose | Side effects |
+| --- | --- | --- |
+| `database_gateway_search_metadata` | Search logical 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` | Preview, execute, or export a manual 
package for a planned workflow. | Depends on `execution_mode`; `preview` and 
`manual-only` do not change runtime state. |
+| `database_gateway_validate_workflow` | Validate a planned or applied 
workflow against visible metadata and generated artifacts. | None. |
+| `database_gateway_plan_encrypt_rule` | Plan data encryption rule changes and 
generate reviewable DDL, DistSQL, index plans, and validation steps. | None; 
creates a plan only. |
+| `database_gateway_plan_mask_rule` | Plan data masking rule changes and 
generate reviewable DistSQL and validation steps. | None; creates a plan only. |
+
+## Prompts
+
+| Prompt | Purpose |
+| --- | --- |
+| `inspect_metadata` | Guide the model to read logical 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 workflow 
failure or unavailable `plan_id`. |
+| `plan_encrypt_rule` | Guide the model to read logical metadata, available 
algorithms, and existing rules before planning data encryption. |
+| `plan_mask_rule` | Guide the model to read logical metadata, available 
algorithms, and existing rules before planning data masking. |
+
+## Completion targets
+
+| Target type | Target | Completed arguments |
+| --- | --- | --- |
+| resource | `shardingsphere://databases/{database}` | `database` |
+| resource | `shardingsphere://databases/{database}/schemas` | `database` |
+| resource | `shardingsphere://databases/{database}/schemas/{schema}` | 
`database`, `schema` |
+| resource | `shardingsphere://databases/{database}/schemas/{schema}/tables` | 
`database`, `schema` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` | 
`database`, `schema`, `table` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns` 
| `database`, `schema`, `table` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
 | `database`, `schema`, `table`, `column` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes` 
| `database`, `schema`, `table` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
 | `database`, `schema`, `table`, `index` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/sequences` | 
`database`, `schema` |
+| resource | 
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` | 
`database`, `schema`, `sequence` |
+| resource | `shardingsphere://workflows/{plan_id}` | `plan_id` |
+| resource | `shardingsphere://features/encrypt/algorithms` | 
`algorithm_type`, `assisted_query_algorithm_type`, `like_query_algorithm_type` |
+| resource | `shardingsphere://features/mask/algorithms` | `algorithm_type` |
+| prompt | `inspect_metadata` | `database`, `schema` |
+| prompt | `safe_sql_execution` | `database`, `schema` |
+| prompt | `recover_workflow` | `plan_id` |
+| prompt | `plan_encrypt_rule` | `database`, `schema`, `table`, `column`, 
`algorithm_type`, `assisted_query_algorithm_type`, `like_query_algorithm_type`, 
`plan_id` |
+| prompt | `plan_mask_rule` | `database`, `schema`, `table`, `column`, 
`algorithm_type`, `plan_id` |
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 a9579dadfe8..fe05a12a1f8 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
@@ -1,6 +1,6 @@
 +++
 title = "客户端集成"
-weight = 3
+weight = 4
 +++
 
 MCP 客户端可以通过 Streamable HTTP 或 STDIO 连接 ShardingSphere-MCP。
@@ -18,12 +18,13 @@ MCP 客户端可以通过 Streamable HTTP 或 STDIO 连接 ShardingSphere-MCP。
 }
 ```
 
-HTTP 客户端需要先调用 `initialize`，并保存响应头中的：
+HTTP 客户端需要在正常 MCP 调用前完成会话生命周期：
 
-- `MCP-Session-Id`
-- `MCP-Protocol-Version`
+1. 调用 `initialize`。
+2. 保存 `MCP-Session-Id` 和 `MCP-Protocol-Version` 响应头。
+3. 携带这两个响应头发送 `notifications/initialized`，并预期 HTTP 状态码为 `202`。
+4. 后续 MCP 请求继续携带这两个响应头。
 
-后续请求必须继续携带这两个响应头。
 关闭会话后，该会话 ID 不能继续复用。
 
 ## STDIO 配置
@@ -48,17 +49,19 @@ STDIO 模式下：
 - 诊断日志写到 stderr 或 `logs/mcp.log`。
 - 客户端配置中的 `command` 和 `args` 应指向发行包内的启动脚本和 STDIO 配置文件。
 
-## 能力发现顺序
+## 能力发现
 
-建议客户端按下面顺序发现能力：
+MCP 官方列表方法用于发现协议层能力；`shardingsphere://capabilities` 用于理解 ShardingSphere 领域能力。
+客户端不需要固定调用顺序，可以按任务需要选择。
 
-1. `tools/list`
-2. `resources/list`
-3. `resources/templates/list`
-4. `prompts/list`
-5. `completion/complete`
-
-`shardingsphere://capabilities` 是 ShardingSphere 领域目录资源，可作为模型理解可用能力的补充信息，但不替代 
MCP 官方列表方法。
+| 能力 | 作用 |
+| --- | --- |
+| `shardingsphere://capabilities` | 读取 ShardingSphere 
领域能力目录，了解资源、工具、提示、补全、工作流关系和副作用提示。 |
+| `tools/list` | 发现可调用工具。 |
+| `resources/list` | 发现可直接读取的资源。 |
+| `resources/templates/list` | 发现带参数的资源模板；客户端需要构造资源 URI 时使用。 |
+| `prompts/list` | 发现可用提示。 |
+| `completion/complete` | 获取资源、提示或参数的补全候选。 |
 
 ## 常用调用
 
@@ -77,11 +80,11 @@ STDIO 模式下：
 搜索元数据：
 
 ```json
-{"jsonrpc":"2.0","id":"search-1","method":"tools/call","params":{"name":"database_gateway_search_metadata","arguments":{"database":"logic_db","query":"sample","object_types":["table"]}}}
+{"jsonrpc":"2.0","id":"search-1","method":"tools/call","params":{"name":"database_gateway_search_metadata","arguments":{"database":"<logic-database>","query":"<metadata-keyword>","object_types":["table"]}}}
 ```
 
 执行只读 SQL：
 
 ```json
-{"jsonrpc":"2.0","id":"query-1","method":"tools/call","params":{"name":"database_gateway_execute_query","arguments":{"database":"logic_db","sql":"SELECT
 * FROM sample_table LIMIT 100","max_rows":100}}}
+{"jsonrpc":"2.0","id":"query-1","method":"tools/call","params":{"name":"database_gateway_execute_query","arguments":{"database":"<logic-database>","sql":"SELECT
 * FROM <table-name> LIMIT 100","max_rows":100}}}
 ```
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 6aa03521cdb..b9610365813 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
@@ -1,6 +1,6 @@
 +++
 title = "Client Integration"
-weight = 3
+weight = 4
 +++
 
 MCP clients can connect to ShardingSphere-MCP through Streamable HTTP or STDIO.
@@ -18,12 +18,13 @@ Clients should use official MCP capability discovery 
methods first, then call to
 }
 ```
 
-An HTTP client must call `initialize` first and keep these response headers:
+An HTTP client must complete the session lifecycle before normal MCP calls:
 
-- `MCP-Session-Id`
-- `MCP-Protocol-Version`
+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.
 
-Later requests must include both headers.
 After the session is closed, the session id cannot be reused.
 
 ## STDIO configuration
@@ -48,17 +49,19 @@ In STDIO mode:
 - Diagnostics are written to stderr or `logs/mcp.log`.
 - `command` and `args` in the client configuration should point to the 
packaged startup script and STDIO config file.
 
-## Capability discovery order
+## Capability discovery
 
-Recommended client discovery order:
+Official MCP list methods discover protocol-level capabilities. 
`shardingsphere://capabilities` explains ShardingSphere domain capabilities.
+Clients do not need a fixed discovery order; call the method or resource that 
matches the task.
 
-1. `tools/list`
-2. `resources/list`
-3. `resources/templates/list`
-4. `prompts/list`
-5. `completion/complete`
-
-`shardingsphere://capabilities` is a ShardingSphere domain catalog resource. 
It can help models understand available capabilities, but it does not replace 
official MCP list methods.
+| Capability | Purpose |
+| --- | --- |
+| `shardingsphere://capabilities` | Read the ShardingSphere domain capability 
catalog for resources, tools, prompts, completions, workflow relationships, and 
side-effect notes. |
+| `tools/list` | Discover callable tools. |
+| `resources/list` | Discover directly readable resources. |
+| `resources/templates/list` | Discover parameterized resource templates when 
the client needs to construct resource URIs. |
+| `prompts/list` | Discover available prompts. |
+| `completion/complete` | Get completion candidates for resources, prompts, or 
arguments. |
 
 ## Common calls
 
@@ -77,11 +80,11 @@ Read the capability catalog:
 Search metadata:
 
 ```json
-{"jsonrpc":"2.0","id":"search-1","method":"tools/call","params":{"name":"database_gateway_search_metadata","arguments":{"database":"logic_db","query":"sample","object_types":["table"]}}}
+{"jsonrpc":"2.0","id":"search-1","method":"tools/call","params":{"name":"database_gateway_search_metadata","arguments":{"database":"<logic-database>","query":"<metadata-keyword>","object_types":["table"]}}}
 ```
 
 Execute read-only SQL:
 
 ```json
-{"jsonrpc":"2.0","id":"query-1","method":"tools/call","params":{"name":"database_gateway_execute_query","arguments":{"database":"logic_db","sql":"SELECT
 * FROM sample_table LIMIT 100","max_rows":100}}}
+{"jsonrpc":"2.0","id":"query-1","method":"tools/call","params":{"name":"database_gateway_execute_query","arguments":{"database":"<logic-database>","sql":"SELECT
 * FROM <table-name> LIMIT 100","max_rows":100}}}
 ```
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 243fa6312bb..7c7d80d57ae 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
@@ -1,6 +1,6 @@
 +++
 title = "配置说明"
-weight = 2
+weight = 3
 +++
 
 ShardingSphere-MCP 使用 YAML 文件配置传输方式和 MCP Server 可以连接的数据库。
@@ -28,13 +28,18 @@ transport:
   type: STDIO
 ```
 
-说明：
+| 配置项 | 说明 |
+| --- | --- |
+| `transport.type` | 传输方式，支持 `STREAMABLE_HTTP` 和 `STDIO`。 |
+| `transport.http` | HTTP 传输配置，只在 `transport.type` 为 `STREAMABLE_HTTP` 时生效。 |
+| `transport.http.bindHost` | HTTP 监听地址，默认值为 `127.0.0.1`。 |
+| `transport.http.port` | HTTP 监听端口，默认值为 `18088`。 |
+| `transport.http.endpointPath` | HTTP 端点路径，默认值为 `/mcp`。 |
 
-- `transport.type` 支持 `STREAMABLE_HTTP` 和 `STDIO`。
-- `transport.http` 只在 `transport.type` 为 `STREAMABLE_HTTP` 时合法。
-- HTTP 模式下 `transport.http` 可以省略，默认 `bindHost`、`port`、`endpointPath` 分别是 
`127.0.0.1`、`18088`、`/mcp`。
-- `127.0.0.1`、`localhost`、`::1` 只面向本机。
-- `0.0.0.0` 或指定内网 IP 会面向对应网络接口。
+| 监听地址 | 说明 |
+| --- | --- |
+| `127.0.0.1`、`localhost`、`::1` | 只允许本机访问。 |
+| `0.0.0.0` 或指定内网 IP | 允许对应网络接口访问。 |
 
 ## 数据库配置
 
@@ -43,32 +48,31 @@ transport:
 
 ```yaml
 runtimeDatabases:
-  logic_db:
+  "<logic-database>":
     databaseType: MySQL
-    jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db"
-    username: "root"
-    password: "root"
+    jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
+    username: "<proxy-username>"
+    password: "<proxy-password>"
     driverClassName: "com.mysql.cj.jdbc.Driver"
 ```
 
-字段说明：
-
-- `databaseType`：必填，声明数据库类型，例如 `MySQL` 或 `PostgreSQL`。
-- `jdbcUrl`：必填，MCP Server 连接数据库的 JDBC URL。
-- `username`：必填字段；无用户名时写空字符串 `""`。
-- `password`：必填字段；无密码时写空字符串 `""`。
-- `driverClassName`：必填字段；如果 JDBC 4 驱动可自动注册且不需要显式覆盖，写空字符串 `""`。
+| 字段 | 是否必填 | 说明 |
+| --- | --- | --- |
+| `databaseType` | 是 | 数据库类型，例如 `MySQL` 或 `PostgreSQL`。 |
+| `jdbcUrl` | 是 | MCP Server 连接逻辑库的 JDBC URL。 |
+| `username` | 是 | 连接逻辑库的用户名；无用户名时写空字符串 `""`。 |
+| `password` | 是 | 连接逻辑库的密码；无密码时写空字符串 `""`。 |
+| `driverClassName` | 是 | JDBC 驱动类名；如果 JDBC 4 驱动可自动注册且不需要显式覆盖，写空字符串 `""`。 |
 
 注意事项：
 
 - MCP 资源暴露的是 ShardingSphere 逻辑库，不是底层物理存储单元。
-- 加密和脱敏插件的工作流应连接 ShardingSphere-Proxy 暴露的逻辑库。
 - Schema、table、view、index 和 sequence 等元数据依赖目标数据库的 JDBC 元数据。
 - 如果目标 JDBC 驱动没有随发行包提供，请把驱动 jar 放入 `plugins/`。
 
 ## 插件目录
 
-发行包默认把 MCP Server 依赖和官方功能插件 jar 放入 `lib/`，包括 Encrypt 和 Mask 插件。
+发行包默认把 MCP Server 依赖和内置 MCP 功能插件 jar 放入 `lib/`。
 如果目标数据库驱动或额外 MCP 功能插件 jar 没有随发行包提供，请放入发行包根目录下的 `plugins/`，再启动 MCP Server。
 
 ## 自定义配置文件
@@ -86,17 +90,3 @@ bin\start.bat path\to\mcp-http.yaml
 ```
 
 Docker 中可以通过 `SHARDINGSPHERE_MCP_CONFIG` 指定容器内的配置文件路径。
-
-## JVM 参数
-
-Unix-like 系统：
-
-```bash
-JAVA_OPTS="-Xms256m -Xmx256m" bin/start.sh
-```
-
-Windows：
-
-```bat
-set "JAVA_OPTS=-Xms256m -Xmx256m" && bin\start.bat
-```
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 2b3abd3a58a..c74f20597c1 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
@@ -1,6 +1,6 @@
 +++
 title = "Configuration"
-weight = 2
+weight = 3
 +++
 
 ShardingSphere-MCP uses YAML files to configure the transport and the 
databases that the MCP Server can connect to.
@@ -28,13 +28,18 @@ transport:
   type: STDIO
 ```
 
-Notes:
+| Configuration item | Description |
+| --- | --- |
+| `transport.type` | Transport type. Supported values are `STREAMABLE_HTTP` 
and `STDIO`. |
+| `transport.http` | HTTP transport configuration, used only when 
`transport.type` is `STREAMABLE_HTTP`. |
+| `transport.http.bindHost` | HTTP bind host. The default value is 
`127.0.0.1`. |
+| `transport.http.port` | HTTP bind port. The default value is `18088`. |
+| `transport.http.endpointPath` | HTTP endpoint path. The default value is 
`/mcp`. |
 
-- `transport.type` supports `STREAMABLE_HTTP` and `STDIO`.
-- `transport.http` is valid only when `transport.type` is `STREAMABLE_HTTP`.
-- In HTTP mode, `transport.http` can be omitted. The default `bindHost`, 
`port`, and `endpointPath` are `127.0.0.1`, `18088`, and `/mcp`.
-- `127.0.0.1`, `localhost`, and `::1` are local-only bindings.
-- `0.0.0.0` or a specific intranet IP exposes the matching network interface.
+| Bind address | Description |
+| --- | --- |
+| `127.0.0.1`, `localhost`, `::1` | Allows local access only. |
+| `0.0.0.0` or a specific intranet IP | Allows access through the matching 
network interface. |
 
 ## Database configuration
 
@@ -43,32 +48,31 @@ Each entry key is the database name used in MCP calls. It 
usually maps to a logi
 
 ```yaml
 runtimeDatabases:
-  logic_db:
+  "<logic-database>":
     databaseType: MySQL
-    jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db"
-    username: "root"
-    password: "root"
+    jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
+    username: "<proxy-username>"
+    password: "<proxy-password>"
     driverClassName: "com.mysql.cj.jdbc.Driver"
 ```
 
-Fields:
-
-- `databaseType`: required database type, such as `MySQL` or `PostgreSQL`.
-- `jdbcUrl`: required JDBC URL used by the MCP Server to connect to the 
database.
-- `username`: required field; use an empty string `""` when no username is 
needed.
-- `password`: required field; use an empty string `""` when no password is 
needed.
-- `driverClassName`: required field; use an empty string `""` when a JDBC 4 
driver auto-registers and no explicit override is needed.
+| Field | Required | Description |
+| --- | --- | --- |
+| `databaseType` | Yes | Database type, such as `MySQL` or `PostgreSQL`. |
+| `jdbcUrl` | Yes | JDBC URL used by the MCP Server to connect to the logical 
database. |
+| `username` | Yes | Username for the logical database; use an empty string 
`""` when no username is needed. |
+| `password` | Yes | Password for the logical database; use an empty string 
`""` when no password is needed. |
+| `driverClassName` | Yes | JDBC driver class name; use an empty string `""` 
when a JDBC 4 driver auto-registers and no explicit override is needed. |
 
 Notes:
 
 - MCP resources expose ShardingSphere logical databases, not physical storage 
units.
-- Encrypt and Mask plugin workflows should connect to logical databases 
exposed by ShardingSphere-Proxy.
 - Schema, table, view, index, and sequence metadata depends on target JDBC 
metadata.
 - If the target JDBC driver is not packaged, copy the driver jar under 
`plugins/`.
 
 ## Plugin directory
 
-The packaged distribution keeps MCP Server dependencies and official feature 
plugin jars under `lib/`, including Encrypt and Mask plugins.
+The packaged distribution keeps MCP Server dependencies and built-in MCP 
feature plugin jars under `lib/`.
 If your target database driver or an extra MCP feature plugin jar is not 
packaged, copy it under the distribution `plugins/` directory before starting 
the MCP Server.
 
 ## Custom configuration file
@@ -86,17 +90,3 @@ bin\start.bat path\to\mcp-http.yaml
 ```
 
 For Docker, set `SHARDINGSPHERE_MCP_CONFIG` to an absolute config path inside 
the container.
-
-## JVM options
-
-Unix-like systems:
-
-```bash
-JAVA_OPTS="-Xms256m -Xmx256m" bin/start.sh
-```
-
-Windows:
-
-```bat
-set "JAVA_OPTS=-Xms256m -Xmx256m" && bin\start.bat
-```
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md 
b/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
index 771b8763e36..4bc2684cc07 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
@@ -1,6 +1,6 @@
 +++
 title = "部署说明"
-weight = 5
+weight = 6
 +++
 
 ShardingSphere-MCP 可以通过源码构建的独立发行包运行，也可以通过官方 OCI 镜像运行。
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
index 4440fc64bf0..f29ffa97c5b 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
@@ -1,6 +1,6 @@
 +++
 title = "Deployment"
-weight = 5
+weight = 6
 +++
 
 ShardingSphere-MCP can run from the standalone distribution built from source 
or from the official OCI image.
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 d843dd5d7b1..e1ce6f082db 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
@@ -1,16 +1,15 @@
 +++
 title = "功能插件"
-weight = 7
+weight = 8
 chapter = true
 +++
 
 ShardingSphere-MCP 通过功能插件扩展领域能力。
-MCP Server 负责传输方式、会话、描述符发现、元数据和工作流基础设施；功能插件负责提供具体工具、资源和业务语义。
 
 发行包默认包含以下官方 MCP 功能插件：
 
-- Encrypt：规划、执行和校验数据加密规则。
-- Mask：规划、执行和校验数据脱敏规则。
+- 数据加密：规划、执行和校验数据加密规则。
+- 数据脱敏：规划、执行和校验数据脱敏规则。
 
 新增或第三方功能插件可以通过 `plugins/` 目录加入运行时类路径。
 如果功能插件未随发行包提供，启动前需要同时准备它依赖的 ShardingSphere 模块和第三方 jar。
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 b43815f369a..adefd72604c 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
@@ -1,16 +1,15 @@
 +++
 title = "Feature Plugins"
-weight = 7
+weight = 8
 chapter = true
 +++
 
 ShardingSphere-MCP extends domain capabilities through feature plugins.
-The MCP Server provides transport, sessions, descriptor discovery, metadata, 
and workflow infrastructure. Feature plugins provide concrete tools, resources, 
and business semantics.
 
 The packaged distribution includes these official MCP feature plugins:
 
-- Encrypt: plan, apply, and validate data encryption rules.
-- Mask: plan, apply, and validate data masking rules.
+- Data Encryption: plan, apply, and validate data encryption rules.
+- Data Masking: plan, apply, and validate data masking rules.
 
 Additional or third-party feature plugins can be added to the runtime 
classpath through the `plugins/` directory.
 If a feature plugin is not packaged by default, prepare its required 
ShardingSphere modules and third-party jars before startup.
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 fe7fa99c57d..6cad99ed204 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,9 +1,9 @@
 +++
-title = "Encrypt"
+title = "数据加密"
 weight = 1
 +++
 
-Encrypt MCP 功能插件帮助 MCP 客户端把加密需求规划成 ShardingSphere-Proxy 可执行的 
DDL、DistSQL、索引计划和校验步骤。
+数据加密 MCP 功能插件帮助 MCP 客户端把加密需求规划成 ShardingSphere-Proxy 可执行的 
DDL、DistSQL、索引计划和校验步骤。
 它不在 MCP Server 内实现加密算法，而是面向 ShardingSphere 逻辑库生成和执行加密规则变更。
 
 ## 前置条件
@@ -59,7 +59,7 @@ Encrypt MCP 功能插件帮助 MCP 客户端把加密需求规划成 ShardingSph
   "params": {
     "name": "database_gateway_plan_encrypt_rule",
     "arguments": {
-      "database": "logic_db",
+      "database": "<logic-database>",
       "table": "orders",
       "column": "status",
       "natural_language_intent": "给 status 做可逆加密，需要等值查询，不需要模糊查询",
@@ -145,7 +145,7 @@ Encrypt MCP 功能插件帮助 MCP 客户端把加密需求规划成 ShardingSph
   "params": {
     "name": "database_gateway_plan_encrypt_rule",
     "arguments": {
-      "database": "logic_db",
+      "database": "<logic-database>",
       "table": "orders",
       "column": "status",
       "operation_type": "drop"
@@ -160,7 +160,6 @@ Encrypt MCP 功能插件帮助 MCP 客户端把加密需求规划成 ShardingSph
 ## 限制
 
 - 仅支持 ShardingSphere-Proxy 逻辑库。
-- 支持 `create`、`alter`、`drop`。
 - `drop` 只删除规则，不自动清理物理派生列和索引。
 - 不处理存量数据迁移或回填。
 - 不提供自动回滚能力。
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 6a74863f277..392e5394f0b 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,9 +1,9 @@
 +++
-title = "Encrypt"
+title = "Data Encryption"
 weight = 1
 +++
 
-The Encrypt MCP feature helps MCP clients plan encryption requirements into 
DDL, DistSQL, index plans, and validation steps executable through 
ShardingSphere-Proxy.
+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.
 
 ## Prerequisites
@@ -59,7 +59,7 @@ For dropping an encryption rule, the minimum input is:
   "params": {
     "name": "database_gateway_plan_encrypt_rule",
     "arguments": {
-      "database": "logic_db",
+      "database": "<logic-database>",
       "table": "orders",
       "column": "status",
       "natural_language_intent": "Encrypt status reversibly with equality 
query support and without LIKE query support",
@@ -145,7 +145,7 @@ Validation focuses on:
   "params": {
     "name": "database_gateway_plan_encrypt_rule",
     "arguments": {
-      "database": "logic_db",
+      "database": "<logic-database>",
       "table": "orders",
       "column": "status",
       "operation_type": "drop"
@@ -160,7 +160,6 @@ It generates `DROP ENCRYPT RULE` only when no encryption 
column remains on the t
 ## Limitations
 
 - Supports ShardingSphere-Proxy logical databases only.
-- Supports `create`, `alter`, and `drop`.
 - `drop` removes rules only; physical derived columns and indexes still 
require manual cleanup.
 - Does not handle existing data migration or backfill.
 - Does not provide automatic rollback.
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 378257a3c07..f92930ab781 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 = "Mask"
+title = "数据脱敏"
 weight = 2
 +++
 
-Mask MCP 功能插件帮助 MCP 客户端把脱敏需求规划成 ShardingSphere-Proxy 可执行的 DistSQL 和校验步骤。
+数据脱敏 MCP 功能插件帮助 MCP 客户端把脱敏需求规划成 ShardingSphere-Proxy 可执行的 DistSQL 和校验步骤。
 脱敏规则直接作用于逻辑列，不生成加密功能使用的物理派生列。
 
 ## 前置条件
@@ -58,7 +58,7 @@ Mask MCP 功能插件帮助 MCP 客户端把脱敏需求规划成 ShardingSphere
   "params": {
     "name": "database_gateway_plan_mask_rule",
     "arguments": {
-      "database": "logic_db",
+      "database": "<logic-database>",
       "table": "orders",
       "column": "phone",
       "natural_language_intent": "把 phone 当作手机号做脱敏，保留前3后4",
@@ -137,7 +137,7 @@ Mask MCP 功能插件帮助 MCP 客户端把脱敏需求规划成 ShardingSphere
   "params": {
     "name": "database_gateway_plan_mask_rule",
     "arguments": {
-      "database": "logic_db",
+      "database": "<logic-database>",
       "table": "orders",
       "column": "phone",
       "operation_type": "drop"
@@ -152,7 +152,5 @@ Mask MCP 功能插件帮助 MCP 客户端把脱敏需求规划成 ShardingSphere
 ## 限制
 
 - 仅支持 ShardingSphere-Proxy 逻辑库。
-- 支持 `create`、`alter`、`drop`。
-- 不生成物理派生列。
 - 不提供自动回滚能力。
 - 规划输入只接受标准未加引号的逻辑标识符。
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 f795afe3f06..306bbc6ad46 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 = "Mask"
+title = "Data Masking"
 weight = 2
 +++
 
-The Mask MCP feature helps MCP clients plan masking requirements into DistSQL 
and validation steps executable through ShardingSphere-Proxy.
+The Data Masking MCP feature helps MCP clients plan masking requirements into 
DistSQL and validation steps executable through ShardingSphere-Proxy.
 Mask rules apply directly to logical columns and do not generate physical 
derived columns used by the Encrypt feature.
 
 ## Prerequisites
@@ -58,7 +58,7 @@ For dropping a mask rule, the minimum input is:
   "params": {
     "name": "database_gateway_plan_mask_rule",
     "arguments": {
-      "database": "logic_db",
+      "database": "<logic-database>",
       "table": "orders",
       "column": "phone",
       "natural_language_intent": "Mask phone as a phone number and keep the 
first 3 and last 4 characters",
@@ -137,7 +137,7 @@ Validation focuses on:
   "params": {
     "name": "database_gateway_plan_mask_rule",
     "arguments": {
-      "database": "logic_db",
+      "database": "<logic-database>",
       "table": "orders",
       "column": "phone",
       "operation_type": "drop"
@@ -152,7 +152,5 @@ It generates `DROP MASK RULE` only when no mask column 
remains on the target tab
 ## Limitations
 
 - Supports ShardingSphere-Proxy logical databases only.
-- Supports `create`, `alter`, and `drop`.
-- Does not generate physical derived columns.
 - Does not provide automatic rollback.
 - Planning input accepts only standard unquoted logical identifiers.
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/quick-start.cn.md 
b/docs/document/content/user-manual/shardingsphere-mcp/quick-start.cn.md
index 84754c43d6a..1a8eec2d36a 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/quick-start.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/quick-start.cn.md
@@ -4,14 +4,12 @@ weight = 1
 +++
 
 本页演示如何从源码构建 ShardingSphere-MCP，连接一个用户已准备好的 ShardingSphere-Proxy 逻辑库，并通过 HTTP 
验证元数据读取和只读 SQL 查询。
-文中的 `logic_db`、`sample_table`、用户名和密码都是占位符；运行前请替换为自己的逻辑库、表和账号。
 
 ## 前置条件
 
 - `JAVA_HOME` 或 `PATH` 中可用的 JDK 21。
 - 一个可通过 JDBC 访问的 ShardingSphere-Proxy 逻辑库。
 - `curl`，用于发送 HTTP 请求。
-- 支持 sh/bash 语法的终端。
 
 ## 构建发行包
 
@@ -37,25 +35,34 @@ cd distribution/mcp/target/apache-shardingsphere-mcp-*
 
 ```yaml
 runtimeDatabases:
-  logic_db:
+  "<logic-database>":
     databaseType: MySQL
-    jdbcUrl: 
"jdbc:mysql://127.0.0.1:3307/logic_db?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC"
-    username: "proxy_user"
-    password: "proxy_password"
+    jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
+    username: "<proxy-username>"
+    password: "<proxy-password>"
     driverClassName: "com.mysql.cj.jdbc.Driver"
 ```
 
+将 `<logic-database>`、`<proxy-host>`、`<proxy-port>`、`<proxy-username>` 和 
`<proxy-password>` 替换为 ShardingSphere-Proxy 的实际连接信息。
 如果目标数据库驱动没有随发行包提供，请在启动前把对应 JDBC 驱动 jar 放入 `plugins/`。
 
 ## 启动 HTTP MCP Server
 
+Unix-like 系统：
+
 ```bash
 bin/start.sh > logs/mcp-http.log 2>&1 &
 MCP_PID=$!
 ```
 
+Windows：
+
+```bat
+start "ShardingSphere MCP" cmd /c "bin\start.bat > logs\mcp-http.log 2>&1"
+```
+
 默认配置文件是 `conf/mcp-http.yaml`，默认端点是 `http://127.0.0.1:18088/mcp`。
-上面的命令会在当前终端后台启动 MCP Server，并把进程号保存到 `MCP_PID`，方便最后停止服务。
+Unix-like 示例会在当前终端后台启动 MCP Server，并把进程号保存到 `MCP_PID`，方便最后停止服务。
 
 ## 初始化 MCP 会话
 
@@ -63,30 +70,38 @@ MCP_PID=$!
 curl -i -sS http://127.0.0.1:18088/mcp \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json, text/event-stream' \
-  --data 
'{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
+  --data 
'{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
 ```
 
 预期结果：
 
 - 响应头包含 `MCP-Session-Id`。
 - 响应头包含 `MCP-Protocol-Version`。
-- 后续 HTTP 请求必须携带这两个响应头。
 
-从响应头复制取值，并在当前终端设置变量：
+通知服务端客户端已完成初始化：
 
 ```bash
-export SESSION_ID="<MCP-Session-Id value>"
-export PROTOCOL_VERSION="<MCP-Protocol-Version value>"
+curl -i -sS http://127.0.0.1:18088/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
+  --data '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'
 ```
 
+预期结果：
+
+- HTTP 状态码是 `202`。
+- 后续 HTTP 请求必须携带这两个响应头。
+
 ## 读取元数据资源
 
 ```bash
 curl -sS http://127.0.0.1:18088/mcp \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json, text/event-stream' \
-  -H "MCP-Session-Id: ${SESSION_ID}" \
-  -H "MCP-Protocol-Version: ${PROTOCOL_VERSION}" \
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
   --data 
'{"jsonrpc":"2.0","id":"resource-1","method":"resources/read","params":{"uri":"shardingsphere://databases"}}'
 ```
 
@@ -94,7 +109,7 @@ curl -sS http://127.0.0.1:18088/mcp \
 
 - 响应类型是 `text/event-stream`。
 - JSON 负载位于 `data:` 行。
-- 返回内容包含 `logic_db`。
+- 返回内容包含 `<logic-database>` 对应的逻辑库名称。
 
 ## 搜索元数据
 
@@ -102,9 +117,21 @@ curl -sS http://127.0.0.1:18088/mcp \
 curl -sS http://127.0.0.1:18088/mcp \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json, text/event-stream' \
-  -H "MCP-Session-Id: ${SESSION_ID}" \
-  -H "MCP-Protocol-Version: ${PROTOCOL_VERSION}" \
-  --data 
'{"jsonrpc":"2.0","id":"tool-1","method":"tools/call","params":{"name":"database_gateway_search_metadata","arguments":{"database":"logic_db","query":"sample","object_types":["table","view"]}}}'
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
+  --data '{
+    "jsonrpc":"2.0",
+    "id":"tool-1",
+    "method":"tools/call",
+    "params":{
+      "name":"database_gateway_search_metadata",
+      "arguments":{
+        "database":"<logic-database>",
+        "query":"<metadata-keyword>",
+        "object_types":["table","view"]
+      }
+    }
+  }'
 ```
 
 预期结果：
@@ -118,8 +145,8 @@ curl -sS http://127.0.0.1:18088/mcp \
 curl -sS http://127.0.0.1:18088/mcp \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json, text/event-stream' \
-  -H "MCP-Session-Id: ${SESSION_ID}" \
-  -H "MCP-Protocol-Version: ${PROTOCOL_VERSION}" \
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
   --data '{
     "jsonrpc":"2.0",
     "id":"tool-2",
@@ -127,8 +154,8 @@ curl -sS http://127.0.0.1:18088/mcp \
     "params":{
       "name":"database_gateway_execute_query",
       "arguments":{
-        "database":"logic_db",
-        "sql":"SELECT * FROM sample_table LIMIT 10",
+        "database":"<logic-database>",
+        "sql":"SELECT * FROM <table-name> LIMIT 10",
         "max_rows":10
       }
     }
@@ -143,14 +170,27 @@ curl -sS http://127.0.0.1:18088/mcp \
 
 ## 关闭会话并停止服务
 
+Unix-like 系统：
+
 ```bash
 curl -sS -D - -o /dev/null \
   -X DELETE http://127.0.0.1:18088/mcp \
-  -H "MCP-Session-Id: ${SESSION_ID}" \
-  -H "MCP-Protocol-Version: ${PROTOCOL_VERSION}"
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>'
 kill "${MCP_PID}"
 ```
 
+Windows：
+
+```bat
+curl -sS -D - -o NUL ^
+  -X DELETE http://127.0.0.1:18088/mcp ^
+  -H "MCP-Session-Id: <MCP-Session-Id value>" ^
+  -H "MCP-Protocol-Version: <MCP-Protocol-Version value>"
+```
+
+然后在 `ShardingSphere MCP` 启动窗口按 `Ctrl+C`，或直接关闭该窗口，停止 MCP Server 进程。
+
 预期结果：
 
 - HTTP 状态码是 `200`。
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/quick-start.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/quick-start.en.md
index b7a13b81313..0b1c60dd48c 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/quick-start.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/quick-start.en.md
@@ -4,14 +4,12 @@ weight = 1
 +++
 
 This page shows how to build ShardingSphere-MCP from source, connect to a 
ShardingSphere-Proxy logical database prepared by the user, and verify metadata 
reads and read-only SQL queries over HTTP.
-`logic_db`, `sample_table`, username, and password are placeholders. Replace 
them with your own logical database, table, and account before running the 
commands.
 
 ## Prerequisites
 
 - JDK 21 available from `JAVA_HOME` or `PATH`.
 - A ShardingSphere-Proxy logical database reachable through JDBC.
 - `curl` for HTTP requests.
-- A terminal that supports sh/bash syntax.
 
 ## Build the distribution
 
@@ -37,25 +35,34 @@ Edit `conf/mcp-http.yaml` and point `runtimeDatabases` to 
an existing ShardingSp
 
 ```yaml
 runtimeDatabases:
-  logic_db:
+  "<logic-database>":
     databaseType: MySQL
-    jdbcUrl: 
"jdbc:mysql://127.0.0.1:3307/logic_db?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC"
-    username: "proxy_user"
-    password: "proxy_password"
+    jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
+    username: "<proxy-username>"
+    password: "<proxy-password>"
     driverClassName: "com.mysql.cj.jdbc.Driver"
 ```
 
+Replace `<logic-database>`, `<proxy-host>`, `<proxy-port>`, 
`<proxy-username>`, and `<proxy-password>` with the actual ShardingSphere-Proxy 
connection information.
 If the target database driver is not packaged, copy the corresponding JDBC 
driver jar to `plugins/` before startup.
 
 ## Start the HTTP MCP Server
 
+Unix-like systems:
+
 ```bash
 bin/start.sh > logs/mcp-http.log 2>&1 &
 MCP_PID=$!
 ```
 
+Windows:
+
+```bat
+start "ShardingSphere MCP" cmd /c "bin\start.bat > logs\mcp-http.log 2>&1"
+```
+
 The default configuration file is `conf/mcp-http.yaml`, and the default 
endpoint is `http://127.0.0.1:18088/mcp`.
-The command above starts the MCP Server in the background and stores the 
process id in `MCP_PID` so it can be stopped at the end.
+The Unix-like example starts the MCP Server in the background and stores the 
process id in `MCP_PID` so it can be stopped at the end.
 
 ## Initialize an MCP session
 
@@ -63,30 +70,38 @@ The command above starts the MCP Server in the background 
and stores the process
 curl -i -sS http://127.0.0.1:18088/mcp \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json, text/event-stream' \
-  --data 
'{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
+  --data 
'{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
 ```
 
 Expected result:
 
 - The response headers include `MCP-Session-Id`.
 - The response headers include `MCP-Protocol-Version`.
-- Later HTTP requests must include both response headers.
 
-Copy the values from the response headers and set them in the current terminal:
+Notify the server that the client has completed initialization:
 
 ```bash
-export SESSION_ID="<MCP-Session-Id value>"
-export PROTOCOL_VERSION="<MCP-Protocol-Version value>"
+curl -i -sS http://127.0.0.1:18088/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
+  --data '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'
 ```
 
+Expected result:
+
+- The HTTP status code is `202`.
+- Later HTTP requests must include both response headers.
+
 ## Read a metadata resource
 
 ```bash
 curl -sS http://127.0.0.1:18088/mcp \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json, text/event-stream' \
-  -H "MCP-Session-Id: ${SESSION_ID}" \
-  -H "MCP-Protocol-Version: ${PROTOCOL_VERSION}" \
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
   --data 
'{"jsonrpc":"2.0","id":"resource-1","method":"resources/read","params":{"uri":"shardingsphere://databases"}}'
 ```
 
@@ -94,7 +109,7 @@ Expected result:
 
 - The response type is `text/event-stream`.
 - The JSON payload is in the `data:` line.
-- The payload contains `logic_db`.
+- The payload contains the logical database name that replaces 
`<logic-database>`.
 
 ## Search metadata
 
@@ -102,9 +117,21 @@ Expected result:
 curl -sS http://127.0.0.1:18088/mcp \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json, text/event-stream' \
-  -H "MCP-Session-Id: ${SESSION_ID}" \
-  -H "MCP-Protocol-Version: ${PROTOCOL_VERSION}" \
-  --data 
'{"jsonrpc":"2.0","id":"tool-1","method":"tools/call","params":{"name":"database_gateway_search_metadata","arguments":{"database":"logic_db","query":"sample","object_types":["table","view"]}}}'
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
+  --data '{
+    "jsonrpc":"2.0",
+    "id":"tool-1",
+    "method":"tools/call",
+    "params":{
+      "name":"database_gateway_search_metadata",
+      "arguments":{
+        "database":"<logic-database>",
+        "query":"<metadata-keyword>",
+        "object_types":["table","view"]
+      }
+    }
+  }'
 ```
 
 Expected result:
@@ -118,8 +145,8 @@ Expected result:
 curl -sS http://127.0.0.1:18088/mcp \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json, text/event-stream' \
-  -H "MCP-Session-Id: ${SESSION_ID}" \
-  -H "MCP-Protocol-Version: ${PROTOCOL_VERSION}" \
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
   --data '{
     "jsonrpc":"2.0",
     "id":"tool-2",
@@ -127,8 +154,8 @@ curl -sS http://127.0.0.1:18088/mcp \
     "params":{
       "name":"database_gateway_execute_query",
       "arguments":{
-        "database":"logic_db",
-        "sql":"SELECT * FROM sample_table LIMIT 10",
+        "database":"<logic-database>",
+        "sql":"SELECT * FROM <table-name> LIMIT 10",
         "max_rows":10
       }
     }
@@ -143,14 +170,27 @@ Expected result:
 
 ## Close the session and stop the server
 
+Unix-like systems:
+
 ```bash
 curl -sS -D - -o /dev/null \
   -X DELETE http://127.0.0.1:18088/mcp \
-  -H "MCP-Session-Id: ${SESSION_ID}" \
-  -H "MCP-Protocol-Version: ${PROTOCOL_VERSION}"
+  -H 'MCP-Session-Id: <MCP-Session-Id value>' \
+  -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>'
 kill "${MCP_PID}"
 ```
 
+Windows:
+
+```bat
+curl -sS -D - -o NUL ^
+  -X DELETE http://127.0.0.1:18088/mcp ^
+  -H "MCP-Session-Id: <MCP-Session-Id value>" ^
+  -H "MCP-Protocol-Version: <MCP-Protocol-Version value>"
+```
+
+Then press `Ctrl+C` in the `ShardingSphere MCP` startup window, or close that 
window, to stop the MCP Server process.
+
 Expected result:
 
 - The HTTP status code is `200`.
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md 
b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
index ec000a43142..7c7c0e614f4 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -1,135 +1,61 @@
 +++
 title = "常见问题"
-weight = 6
+weight = 7
 +++
 
-这里汇总 MCP Server、传输方式、会话、SQL 工具和工作流机制的常见问题。
-插件业务问题请查看对应功能插件文档。
+本页按现象整理 MCP Server、传输方式、会话、SQL 工具和工作流机制的排查方法。
+功能插件的业务规则问题请查看对应功能插件文档。
 
-## 启动失败
+## 排查索引
 
-优先检查：
+| 现象 | 可能原因 | 处理方式 | 是否需要代码改进 |
+| --- | --- | --- | --- |
+| 启动失败 | JDK、配置路径、YAML 字段或必填字段不正确。 | 查看终端错误和 `logs/mcp.log`。 | 
部分需要：字段可省略能力待优化。 |
+| HTTP 无法连接 | 端口、端点路径、传输方式或绑定地址不正确。 | 检查 `port`、`endpointPath`、`bindHost` 和客户端 
URL。 | 通常不需要。 |
+| HTTP 返回 403 | 请求 `Origin` 与绑定地址安全策略不匹配。 | 本机调试用回环地址；远程访问走受控网关。 | 
可以改进：错误响应可给出更明确提示。 |
+| 会话请求失败 | 未初始化、缺少会话头，或复用已关闭会话。 | 先调用 `initialize`，后续请求持续携带响应头。 | 通常不需要。 |
+| STDIO 没有响应 | 被当成人工交互 Shell，或 stdout 被日志污染。 | 由 MCP 客户端拉起进程；诊断信息看 stderr 或日志。 
| 可以改进：继续保护 stdout。 |
+| 逻辑库或元数据为空 | 配置、驱动或权限不正确。 | 确认连接 Proxy 逻辑库，并检查驱动和权限。 | 可以改进：空结果可给出诊断。 |
+| JDBC 驱动错误 | 驱动不在类路径，或 `driverClassName` 不正确。 | 把驱动 jar 放入 
`plugins/`，或加入嵌入式运行时类路径。 | 部分需要：字段可省略能力待优化。 |
+| SQL 工具调用失败 | 工具选错、多语句被拒绝或参数超限。 | 查询用 `execute_query`；有副作用 SQL 用 
`execute_update` 并先预览。 | 通常不需要；错误消息可增强。 |
+| 工作流失败 | `plan_id`、会话、执行模式或人工执行步骤不正确。 | 同一会话内复用 `plan_id`；先预览；人工执行后再校验。 | 
通常不需要。 |
+| 敏感输入无法传递 | 补问要求密钥或凭证。 | 由客户端或运维侧取值，再通过受保护 MCP 调用传入。 | 如需服务端解析密钥引用，需要改代码。 |
 
-- JDK 版本是否为 JDK 21。
-- 配置文件路径是否正确。
-- `conf/mcp-http.yaml` 或 `conf/mcp-stdio.yaml` 是否存在。
-- YAML 是否包含不受支持字段。
-- `username`、`password`、`driverClassName` 是否显式写出；不需要值时写空字符串 `""`。
+补充说明：
 
-启动失败时，先查看终端错误和 `logs/mcp.log`。
+- `username`、`password` 和 `driverClassName` 目前必须显式写出；不需要值时写 `""`。
+- `MCP-Session-Id` 和 `MCP-Protocol-Version` 来自 `initialize` 响应头，关闭会话后不能复用。
+- 使用 `manual-only` 后，应先人工执行返回的 SQL 或 DistSQL，再调用校验工具。
+- 人工执行包中的密钥占位符应由执行人员在受控环境替换。
 
-## HTTP 连接失败
+## SQL 工具选择
 
-检查：
+| SQL 类型 | 工具 | 建议 |
+| --- | --- | --- |
+| `SELECT` | `database_gateway_execute_query` | 用于只读查询。 |
+| `EXPLAIN ANALYZE` | `database_gateway_execute_query` | 仅在目标逻辑库能力允许时使用。 |
+| DML、DDL、DCL、事务控制、savepoint | `database_gateway_execute_update` | 先用 
`execution_mode=preview` 查看副作用，再决定是否执行。 |
 
-- 默认端点是否为 `http://127.0.0.1:18088/mcp`。
-- 端口是否被占用。
-- `transport.type` 是否为 `STREAMABLE_HTTP`。
-- `transport.http.endpointPath` 是否和客户端 URL 一致。
-- 绑定 `127.0.0.1` 时，远程机器无法直接访问。
-- 绑定 `0.0.0.0` 时，应由外层网关处理鉴权和网络访问控制。
-
-## HTTP 返回 403
-
-Origin 校验规则：
-
-- 回环地址绑定下，如果请求带 `Origin`，该 Origin 也必须是回环地址。
-- 非回环地址绑定下，缺失 `Origin` 的非浏览器请求会被接受。
-- 非回环地址绑定下，任何显式 `Origin` 都会被拒绝。
-
-可选处理方式：
-
-- 调整客户端的 Origin 策略。
-- 使用本机回环地址访问。
-- 通过受控网关转发请求。
-
-## 会话或协议头问题
-
-HTTP 客户端调用 `initialize` 后，必须保存：
-
-- `MCP-Session-Id`
-- `MCP-Protocol-Version`
-
-后续请求都要携带这两个响应头。
-会话关闭后不能继续复用。
-工作流的 `plan_id` 也只在当前会话内有效。
-
-## STDIO 模式没有响应
-
-STDIO 是给 MCP 客户端拉起子进程使用的，不是人工交互 shell。
-
-检查：
-
-- 客户端配置里的 `command` 是否指向 `bin/start.sh` 或 `bin\start.bat`。
-- `args` 是否包含 `conf/mcp-stdio.yaml`。
-- stdout 是否被日志污染。
-- 诊断信息应查看 stderr 或 `logs/mcp.log`。
-
-## 找不到逻辑库或元数据为空
-
-检查：
-
-- `runtimeDatabases` 是否配置了目标逻辑库。
-- MCP 暴露的是 ShardingSphere 逻辑库，不是底层物理存储单元。
-- `databaseType` 和 `jdbcUrl` 是否匹配目标逻辑库。
-- 目标 JDBC 驱动 jar 是否位于 `plugins/`。
-- 连接用户是否有读取 JDBC 元数据的权限。
-
-## JDBC 驱动错误
-
-发行包只内置有限的 JDBC 驱动。
-如果目标数据库驱动缺失，请把对应 jar 放入 `plugins/`。
-
-如果以嵌入方式使用 `shardingsphere-mcp-bootstrap`，需要把驱动加到运行时类路径。
-
-`driverClassName` 字段必须显式存在。
-当驱动可自动注册且不需要显式覆盖时，写 `""`。
-
-## SQL 工具调用失败
-
-`database_gateway_execute_query` 只用于：
-
-- `SELECT`
-- `EXPLAIN ANALYZE`
-
-DML、DDL、DCL、事务控制、savepoint 和其他有副作用 SQL 应使用 `database_gateway_execute_update`。
-
-有副作用 SQL 建议先使用：
+`database_gateway_execute_update` 的预览参数：
 
 ```json
 {"execution_mode":"preview"}
 ```
 
-再在确认后使用：
+确认后执行：
 
 ```json
 {"execution_mode":"execute"}
 ```
 
-其他限制：
-
-- 多语句会被拒绝。
-- `max_rows` 范围是 `0..5000`。
-- `timeout_ms` 范围是 `0..300000`。
-
-## 工作流通用问题
-
-检查：
-
-- 是否丢失 `plan_id`。
-- 是否换了 `MCP-Session-Id` 后继续执行或校验。
-- `database_gateway_apply_workflow` 是否传入 `execution_mode`。
-- 使用 `manual-only` 后，是否已经人工执行返回的 SQL 或 DistSQL。
-- `approved_steps` 是否来自预览结果返回的 `preview_artifacts[].approval_step`。
-
-## 收集诊断信息
+## 诊断信息
 
 报告问题时建议提供：
 
 - 启动命令。
-- MCP 配置文件，注意移除密码和密钥。
+- MCP 配置文件，注意移除密码、密钥和令牌。
 - 传输方式和端点。
-- `MCP-Session-Id` 是否已初始化，注意不要公开真实敏感响应头。
+- 是否已完成 `initialize`，不要公开真实 `MCP-Session-Id`。
 - 工具或资源请求体。
 - JSON-RPC 错误负载。
 - `logs/mcp.log` 中相关错误。
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
index 333fc66dc8c..33163f1c957 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -1,135 +1,61 @@
 +++
 title = "Troubleshooting"
-weight = 6
+weight = 7
 +++
 
-This page covers common MCP Server, transport, session, SQL tool, and workflow 
mechanism issues.
-For plugin-specific business issues, see the corresponding feature plugin 
documentation.
+This page organizes troubleshooting by symptom for the MCP Server, transport, 
sessions, SQL tools, and workflow mechanism.
+For feature-specific business rule issues, see the corresponding feature 
plugin documentation.
 
-## Startup failure
+## Troubleshooting index
 
-Check:
+| Symptom | Possible cause | Action | Needs code improvement |
+| --- | --- | --- | --- |
+| Startup failure | JDK, config path, YAML field, or required field is wrong. 
| Inspect terminal output and `logs/mcp.log`. | Partially: optional field 
support can be improved. |
+| HTTP connection failure | Port, endpoint path, transport type, or bind 
address is wrong. | Check `port`, `endpointPath`, `bindHost`, and client URL. | 
Usually no. |
+| HTTP 403 response | Request `Origin` does not match the bind-address policy. 
| Use loopback locally; use a controlled gateway for remote access. | Yes: 
error response can give clearer hints. |
+| Session request failure | Session was not initialized, headers are missing, 
or a closed session is reused. | Call `initialize` first and keep sending the 
response headers. | Usually no. |
+| No response in STDIO mode | STDIO is used as a shell, or stdout is polluted 
by logs. | Let an MCP client launch the process; read stderr or logs for 
diagnostics. | Yes: keep protecting stdout. |
+| Logical database or metadata is empty | Config, driver, or permission is 
wrong. | Confirm Proxy logical database, driver, and permissions. | Yes: empty 
results can include diagnostics. |
+| JDBC driver error | Driver is not on classpath, or `driverClassName` is 
wrong. | Put the driver jar under `plugins/`, or add it to the embedded runtime 
classpath. | Partially: optional field support can be improved. |
+| SQL tool call failure | Wrong tool, multiple statements, or argument out of 
range. | Use `execute_query` for queries; use `execute_update` with preview for 
side effects. | Usually no; messages can improve. |
+| Workflow failure | `plan_id`, session, execution mode, or manual step is 
wrong. | Reuse `plan_id` in one session; preview first; validate after manual 
execution. | Usually no. |
+| Secret input cannot be passed safely | A clarification asks for a key or 
credential. | Resolve it outside the server, then pass it through a protected 
MCP call. | Server-side secret references require code changes. |
 
-- JDK version is JDK 21.
-- The configuration file path is correct.
-- `conf/mcp-http.yaml` or `conf/mcp-stdio.yaml` exists.
-- The YAML file does not contain unsupported fields.
-- `username`, `password`, and `driverClassName` are explicitly declared; use 
an empty string `""` when no value is needed.
+Additional notes:
 
-When startup fails, inspect the terminal error and `logs/mcp.log` first.
+- `username`, `password`, and `driverClassName` must currently be declared 
explicitly; use `""` when no value is needed.
+- `MCP-Session-Id` and `MCP-Protocol-Version` come from the `initialize` 
response headers and cannot be reused after close.
+- After `manual-only`, execute the returned SQL or DistSQL manually before 
calling validation.
+- Secret placeholders in manual packages should be replaced by operators in a 
controlled environment.
 
-## HTTP connection failure
+## SQL tool selection
 
-Check:
+| SQL type | Tool | Recommendation |
+| --- | --- | --- |
+| `SELECT` | `database_gateway_execute_query` | Use for read-only queries. |
+| `EXPLAIN ANALYZE` | `database_gateway_execute_query` | Use only when the 
target logical database capability allows it. |
+| DML, DDL, DCL, transaction control, savepoint | 
`database_gateway_execute_update` | Preview with `execution_mode=preview` 
before deciding whether to execute. |
 
-- The default endpoint is `http://127.0.0.1:18088/mcp`.
-- The port is not occupied.
-- `transport.type` is `STREAMABLE_HTTP`.
-- `transport.http.endpointPath` matches the client URL.
-- Remote machines cannot access an MCP Server bound to `127.0.0.1` directly.
-- When binding to `0.0.0.0`, authentication and network access control should 
be handled by an upstream gateway.
-
-## HTTP 403 response
-
-Origin validation rules:
-
-- For loopback bindings, if the request carries `Origin`, the Origin must also 
be loopback.
-- For non-loopback bindings, non-browser requests without `Origin` are 
accepted.
-- For non-loopback bindings, any explicit `Origin` is rejected.
-
-Possible actions:
-
-- Adjust the client Origin behavior.
-- Use local loopback access.
-- Forward requests through a controlled gateway.
-
-## Session or protocol header issues
-
-After an HTTP client calls `initialize`, it must keep:
-
-- `MCP-Session-Id`
-- `MCP-Protocol-Version`
-
-Later requests must include both headers.
-After the session is closed, it cannot be reused.
-Workflow `plan_id` values are valid only in the current session.
-
-## No response in STDIO mode
-
-STDIO is for MCP clients that launch the MCP Server as a child process. It is 
not an interactive shell.
-
-Check:
-
-- `command` points to `bin/start.sh` or `bin\start.bat`.
-- `args` includes `conf/mcp-stdio.yaml`.
-- stdout is not polluted by logs.
-- Diagnostics are read from stderr or `logs/mcp.log`.
-
-## Logical database not found or metadata is empty
-
-Check:
-
-- `runtimeDatabases` contains the target logical database.
-- MCP exposes ShardingSphere logical databases, not physical storage units.
-- `databaseType` and `jdbcUrl` match the target logical database.
-- The target JDBC driver jar is under `plugins/`.
-- The connection user has permission to read JDBC metadata.
-
-## JDBC driver errors
-
-The distribution only packages a limited set of JDBC drivers.
-If the target database driver is missing, place the driver jar under 
`plugins/`.
-
-If embedding `shardingsphere-mcp-bootstrap` directly, add the driver to the 
runtime classpath.
-
-The `driverClassName` field must be explicitly present.
-When the driver auto-registers and no explicit override is needed, set it to 
`""`.
-
-## SQL tool call failure
-
-`database_gateway_execute_query` is for:
-
-- `SELECT`
-- `EXPLAIN ANALYZE`
-
-Use `database_gateway_execute_update` for DML, DDL, DCL, transaction control, 
savepoints, and other side-effecting SQL.
-
-For side-effecting SQL, preview first:
+Preview parameter for `database_gateway_execute_update`:
 
 ```json
 {"execution_mode":"preview"}
 ```
 
-Then execute after review:
+Execute after review:
 
 ```json
 {"execution_mode":"execute"}
 ```
 
-Other limits:
-
-- Multiple statements are rejected.
-- `max_rows` range is `0..5000`.
-- `timeout_ms` range is `0..300000`.
-
-## Common workflow issues
-
-Check:
-
-- `plan_id` was not lost.
-- The same `MCP-Session-Id` is used for apply and validate.
-- `database_gateway_apply_workflow` includes `execution_mode`.
-- After `manual-only`, the returned SQL or DistSQL artifacts have been 
executed manually.
-- `approved_steps` values come from `preview_artifacts[].approval_step`.
-
-## Collect diagnostics
+## Diagnostics
 
 When reporting an issue, provide:
 
 - Startup command.
-- MCP configuration file, with passwords and keys removed.
+- MCP configuration file, with passwords, keys, and tokens removed.
 - Transport type and endpoint.
-- Whether `MCP-Session-Id` was initialized. Do not publish sensitive real 
headers.
+- Whether `initialize` has completed. Do not publish a real `MCP-Session-Id`.
 - Tool or resource request body.
 - JSON-RPC error payload.
 - Relevant errors from `logs/mcp.log`.
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/workflow-basics.cn.md 
b/docs/document/content/user-manual/shardingsphere-mcp/workflow-basics.cn.md
deleted file mode 100644
index 715c8069bdc..00000000000
--- a/docs/document/content/user-manual/shardingsphere-mcp/workflow-basics.cn.md
+++ /dev/null
@@ -1,63 +0,0 @@
-+++
-title = "工作流基础"
-weight = 4
-+++
-
-ShardingSphere-MCP 的功能插件可以通过共享工作流机制实现复杂治理任务。
-MCP Server 提供通用工作流机制，插件提供具体业务语义。
-
-## 基本阶段
-
-一个典型工作流包含：
-
-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`：信息不足，需要补齐参数。
-- `planned`：计划已生成，可以审查变更产物。
-- `completed`：已执行完成。
-- `awaiting-manual-execution`：选择了 `manual-only`，需要人工执行返回的变更产物。
-- `validated`：校验已通过。
-- `failed`：当前阶段失败，应查看 `issues`、`mismatches` 和 `recovery_guidance`。
-
-## 执行模式
-
-`database_gateway_apply_workflow` 必须显式传入 `execution_mode`：
-
-- `preview`：只预览变更产物和副作用范围，不修改服务状态。
-- `review-then-execute`：在审查后执行变更产物。
-- `manual-only`：不自动执行，返回人工执行包。
-
-如果使用 `approved_steps` 分步执行，只能使用预览结果返回的 `preview_artifacts[].approval_step` 值。
-未知步骤会被拒绝。
-
-## 敏感输入
-
-插件可能要求补充敏感字段，例如密钥或凭证。
-带有 `secret: true`、`input_type: "secret"`，或字段名包含 
password、token、key、secret、credential 的补问，不应通过普通表单明文回传。
-
-推荐处理方式：
-
-- 保留 `plan_id`。
-- 通过密钥管理系统、受保护环境变量或运维控制通道取得值。
-- 用同一个 `plan_id` 再次调用原规划工具。
-
-## 通用工具
-
-`database_gateway_apply_workflow` 和 `database_gateway_validate_workflow` 
是通用工作流工具。
-它们不决定业务语义，只处理当前会话中已存在的工作流计划。
-具体规划工具由功能插件提供。
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/workflow-basics.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/workflow-basics.en.md
deleted file mode 100644
index 7f58ea2b988..00000000000
--- a/docs/document/content/user-manual/shardingsphere-mcp/workflow-basics.en.md
+++ /dev/null
@@ -1,63 +0,0 @@
-+++
-title = "Workflow Basics"
-weight = 4
-+++
-
-ShardingSphere-MCP feature plugins can use the shared workflow mechanism to 
implement complex governance tasks.
-The MCP Server provides the common workflow mechanism, while each plugin 
provides its own business semantics.
-
-## Basic phases
-
-A typical workflow contains:
-
-1. Call the 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. Call `database_gateway_apply_workflow` with `execution_mode=preview` first.
-5. After reviewing the preview, call with 
`execution_mode=review-then-execute`, or use `manual-only` to export a manual 
execution package.
-6. Call `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
-
-- `clarifying`: more input is required.
-- `planned`: the plan is ready and change artifacts should be reviewed.
-- `completed`: apply has completed.
-- `awaiting-manual-execution`: `manual-only` was selected; execute the 
returned change artifacts manually.
-- `validated`: validation passed.
-- `failed`: the current phase failed; inspect `issues`, `mismatches`, and 
`recovery_guidance`.
-
-## Execution modes
-
-`database_gateway_apply_workflow` requires an explicit `execution_mode`:
-
-- `preview`: preview change artifacts and side-effect scope without changing 
server state.
-- `review-then-execute`: execute change artifacts after review.
-- `manual-only`: 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.
-
-## 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.
-
-Recommended handling:
-
-- Keep the `plan_id`.
-- 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`.
-
-## Common tools
-
-`database_gateway_apply_workflow` and `database_gateway_validate_workflow` are 
common workflow tools.
-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.
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md 
b/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
new file mode 100644
index 00000000000..8c7b67f120a
--- /dev/null
+++ b/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
@@ -0,0 +1,88 @@
++++
+title = "工作流"
+weight = 5
++++
+
+ShardingSphere-MCP 的功能插件可以通过共享工作流机制实现复杂治理任务。
+MCP Server 提供通用工作流机制，插件提供具体业务语义。
+
+工作流适合需要规划、审查、执行和校验的多步骤治理变更，例如规划数据加密规则或数据脱敏规则。
+如果只是读取元数据或执行只读 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`。 |
+
+## 执行模式
+
+`database_gateway_apply_workflow` 必须显式传入 `execution_mode`：
+
+| 执行模式 | 是否修改运行时状态 | 用途 |
+| --- | --- | --- |
+| `preview` | 否 | 只预览变更产物和副作用范围。 |
+| `review-then-execute` | 是 | 审查后由 MCP Server 执行变更产物。 |
+| `manual-only` | 否 | 不自动执行，返回人工执行包。 |
+
+如果使用 `approved_steps` 分步执行，只能使用预览结果返回的 `preview_artifacts[].approval_step` 值。
+未知步骤会被拒绝。
+
+## 敏感输入
+
+插件可能要求补充敏感字段，例如密钥或凭证。
+带有 `secret: true`、`input_type: "secret"`，或字段名包含 
password、token、key、secret、credential 的补问，不应通过普通表单明文回传。
+
+推荐处理方式：
+
+- 保留 `plan_id`。
+- 客户端或运维侧通过密钥管理系统、受保护环境变量或运维控制通道取得值。
+- 用同一个 `plan_id` 再次调用原规划工具，并只在受保护的 MCP 调用中传入敏感字段。
+
+ShardingSphere-MCP 不直接读取密钥管理系统。
+如果使用人工执行包，可以在返回的 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` 
是通用工作流工具。
+用户只需要知道：功能插件返回 `plan_id` 后，后续预览、执行和校验都通过这两个工具完成。
+它们不决定业务语义，只处理当前会话中已存在的工作流计划。
+具体规划工具由功能插件提供。
diff --git 
a/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md 
b/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
new file mode 100644
index 00000000000..eeabe449e10
--- /dev/null
+++ b/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
@@ -0,0 +1,88 @@
++++
+title = "Workflows"
+weight = 5
++++
+
+ShardingSphere-MCP feature plugins can use the shared workflow mechanism to 
implement complex governance tasks.
+The MCP Server provides the common workflow mechanism, while each plugin 
provides its own business semantics.
+
+Workflows are useful for multi-step governance changes that need planning, 
review, execution, and validation, such as planning data encryption or data 
masking rules.
+For metadata reads or read-only SQL, workflows are usually unnecessary.
+
+## Basic phases
+
+A typical workflow contains:
+
+1. Call the 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. Call `database_gateway_apply_workflow` with `execution_mode=preview` first.
+5. After reviewing the preview, call with 
`execution_mode=review-then-execute`, or use `manual-only` to export a manual 
execution package.
+6. Call `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 |
+| --- | --- | --- |
+| `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
+
+`database_gateway_apply_workflow` requires an explicit `execution_mode`:
+
+| Execution mode | Changes runtime state | Purpose |
+| --- | --- | --- |
+| `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.
+
+## 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.
+
+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.
+
+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.
+
+Example:
+
+```json
+{
+  "name": "database_gateway_plan_encrypt_rule",
+  "arguments": {
+    "plan_id": "${PLAN_ID}",
+    "primary_algorithm_properties": {
+      "aes-key-value": "${VALUE_FROM_SECRET_MANAGER}"
+    }
+  }
+}
+```
+
+## Apply and validation tools
+
+`database_gateway_apply_workflow` and `database_gateway_validate_workflow` are 
common workflow tools.
+Users only need to know that after a feature plugin returns `plan_id`, 
preview, apply, and validation use these two tools.
+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.

(shardingsphere) branch master updated: Refine ShardingSphere MCP manual (#38751)

Reply via email to