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 a31579b1083 Refine ShardingSphere-MCP user documentation (#38787)
a31579b1083 is described below
commit a31579b10833d5714d234f358686e4fb222ea8e2
Author: Liang Zhang <[email protected]>
AuthorDate: Wed Jun 3 17:14:46 2026 +0800
Refine ShardingSphere-MCP user documentation (#38787)
- Emphasize natural-language database tasks in user-facing MCP docs
- Move protocol-level details and generic client examples to the custom
integration appendix
- Align Chinese and English quick start, capability, configuration, client
integration, feature plugin, workflow, and troubleshooting pages
---
.../user-manual/shardingsphere-mcp/_index.cn.md | 5 ++-
.../user-manual/shardingsphere-mcp/_index.en.md | 5 ++-
.../shardingsphere-mcp/capabilities.cn.md | 9 ++--
.../shardingsphere-mcp/capabilities.en.md | 9 ++--
.../client-integration/_index.cn.md | 51 +++-------------------
.../client-integration/_index.en.md | 51 +++-------------------
.../shardingsphere-mcp/configuration.cn.md | 34 +++++----------
.../shardingsphere-mcp/configuration.en.md | 34 +++++----------
.../shardingsphere-mcp/developer-appendix.cn.md | 35 ++++++++++++++-
.../shardingsphere-mcp/developer-appendix.en.md | 33 +++++++++++++-
.../shardingsphere-mcp/features/_index.cn.md | 3 +-
.../shardingsphere-mcp/features/_index.en.md | 3 +-
.../shardingsphere-mcp/features/encrypt.cn.md | 20 ++++-----
.../shardingsphere-mcp/features/encrypt.en.md | 20 ++++-----
.../shardingsphere-mcp/features/mask.cn.md | 8 ++--
.../shardingsphere-mcp/features/mask.en.md | 8 ++--
.../features/plugin-workflow.cn.md | 12 ++---
.../features/plugin-workflow.en.md | 12 ++---
.../shardingsphere-mcp/quick-start.cn.md | 20 +++------
.../shardingsphere-mcp/quick-start.en.md | 20 +++------
.../shardingsphere-mcp/troubleshooting.cn.md | 14 +++---
.../shardingsphere-mcp/troubleshooting.en.md | 14 +++---
22 files changed, 181 insertions(+), 239 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 cef771b19b3..7a00f2741dc 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
@@ -35,9 +35,10 @@ ShardingSphere-MCP 面向支持 MCP 的 AI 应用、IDE 插件和 Agent 平台
- 配置说明：说明传输方式、`runtimeDatabases`、插件目录和启动参数。
- 客户端集成：说明如何通过 HTTP 或 STDIO 把 MCP Server 接入 AI 应用，并提供 Codex 和 Claude Code 示例。
- 部署说明：说明发行包、OCI 镜像和安全部署建议。
-- 常见问题：排查 MCP Server、连接、配置、元数据和 SQL 执行的通用问题。
+- 常见问题：排查 MCP Server、连接、配置、元数据、查询和变更的通用问题。
- 功能插件：说明官方 MCP 功能插件能力，以及插件变更的审查、执行和校验流程。
- 规则变更流程：说明规则变更任务的确认、预览、执行和校验流程。
- 数据加密：说明如何通过 MCP 功能插件规划、执行和校验数据加密规则变更。
- 数据脱敏：说明如何通过 MCP 功能插件规划、执行和校验数据脱敏规则变更。
-- 开发者附录：说明自研集成或协议调试需要的协议细节和 HTTP 调试示例。
+
+自研集成或协议调试场景可参考[自研集成附录](developer-appendix/)。
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 4b784b28a15..0a9347b2a57 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
@@ -35,9 +35,10 @@ Tasks with side effects should create or preview a plan
first, then run only aft
- Configuration: configure transport, `runtimeDatabases`, plugin directories,
and launch parameters.
- Client Integration: connect the MCP Server to an AI application through HTTP
or STDIO, with Codex and Claude Code examples.
- Deployment: deploy the binary distribution and OCI image safely.
-- Troubleshooting: diagnose common MCP Server, connection, configuration,
metadata, and SQL execution issues.
+- Troubleshooting: diagnose common MCP Server, connection, configuration,
metadata, query, and change issues.
- Feature Plugins: use official MCP feature plugins and understand how to
review, apply, and validate plugin changes.
- Rule Change Flow: understand confirmation, preview, execution, and
validation for rule change tasks.
- Data Encryption: plan, apply, and validate data encryption rule changes
through MCP feature plugins.
- Data Masking: plan, apply, and validate data masking rule changes through
MCP feature plugins.
-- Developer Appendix: reference protocol details and HTTP debugging examples
for custom integration or protocol debugging.
+
+For custom integration or protocol debugging, see the [Custom Integration
Appendix](developer-appendix/).
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 790e723b41f..0c663d571ce 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
@@ -4,7 +4,6 @@ weight = 2
+++
本页说明用户可以通过自然语言完成的数据库任务，以及连接 ShardingSphere-Proxy 和普通数据库时的使用边界。
-协议级对接信息见[开发者附录](../developer-appendix/)。
## 连接目标
@@ -62,14 +61,14 @@ weight = 2
| 按对象类型搜索 | “查找名字包含 `user` 的表和视图。” | Proxy 或普通数据库 | 可以指定只看表、视图或列等对象。 |
| 查找后继续查看详情 | “打开刚才找到的 `orders` 表，查看字段和索引。” | Proxy 或普通数据库 |
搜索结果可作为后续自然语言任务的上下文。 |
-## SQL 执行
+## 查询与变更预览
| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
| --- | --- | --- | --- |
-| 执行只读查询 | “查询 `orders` 表前 10 行。” | Proxy 或普通数据库 | 适合查看样例数据或验证 SQL 结果。 |
+| 执行查询 | “查询 `orders` 表前 10 行。” | Proxy 或普通数据库 | 适合查看样例数据或验证查询结果。 |
| 限制返回行数 | “查询 `orders` 表前 100 行，不要返回更多数据。” | Proxy 或普通数据库 | 避免返回过多数据。 |
-| 预览有副作用 SQL | “预览这条变更 SQL，先不要执行。” | Proxy 或普通数据库 | 执行前审查影响范围。 |
-| 确认执行有副作用 SQL | “确认执行刚才预览过的 SQL。” | Proxy 或普通数据库 | 需要确认已审查副作用。 |
+| 预览会修改数据或规则的操作 | “预览这条变更，先不要执行。” | Proxy 或普通数据库 | 执行前审查影响范围。 |
+| 确认执行已预览的变更 | “确认执行刚才预览过的变更。” | Proxy 或普通数据库 | 需要确认已审查副作用。 |
## ShardingSphere 规则变更
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 2fff928d7e4..2e52db335f0 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
@@ -4,7 +4,6 @@ weight = 2
+++
This page describes the database tasks that users can complete through natural
language, and the usage boundaries when connecting to ShardingSphere-Proxy or a
regular database.
-For protocol-level integration details, see the [Developer
Appendix](../developer-appendix/).
## Connection Targets
@@ -62,14 +61,14 @@ Usage boundaries:
| Search by object type | "Find tables and views whose names contain `user`."
| Proxy or regular database | Narrow the search to tables, views, columns, or
other object types. |
| Continue from search results | "Open the `orders` table found earlier and
show columns and indexes." | Proxy or regular database | Search results can
provide context for follow-up natural-language tasks. |
-## SQL Execution
+## Queries and Change Preview
| Task | Natural language example | Connection target | User focus |
| --- | --- | --- | --- |
-| Run a read-only query | "Query the first 10 rows from `orders`." | Proxy or
regular database | Use for sample data inspection or SQL result validation. |
+| Run a query | "Query the first 10 rows from `orders`." | Proxy or regular
database | Use for sample data inspection or query result validation. |
| Limit returned rows | "Query the first 100 rows from `orders` and do not
return more." | Proxy or regular database | Avoid returning too much data. |
-| Preview side-effecting SQL | "Preview this change SQL without executing it."
| Proxy or regular database | Review impact before execution. |
-| Execute side-effecting SQL after confirmation | "Confirm and execute the SQL
that was just previewed." | Proxy or regular database | Requires confirmation
that side effects were reviewed. |
+| Preview an operation that may change data or rules | "Preview this change
without executing it." | Proxy or regular database | Review impact before
execution. |
+| Confirm a previewed change | "Confirm and execute the change that was just
previewed." | Proxy or regular database | Requires confirmation that side
effects were reviewed. |
## ShardingSphere Rule Changes
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
index b65dc8b2831..b27ad2799cd 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
@@ -20,51 +20,12 @@ weight = 4
- [Codex](./codex/)：适合在 Codex CLI 或 IDE 扩展中使用 ShardingSphere-MCP。
- [Claude Code](./claude-code/)：适合在 Claude Code 项目或用户配置中使用 ShardingSphere-MCP。
-## 选择传输方式
+## 选择接入方式
-- HTTP 适合 MCP Server 独立启动，AI 应用通过固定端点访问的场景。
-- STDIO 适合本地 AI 应用拉起 ShardingSphere-MCP 子进程的场景。
-
-## HTTP 配置
-
-将下面片段写入 AI 应用的 MCP Server 配置；具体文件位置由应用决定。
-`url` 指向已经启动的 HTTP MCP Server。
-
-```json
-{
- "mcpServers": {
- "shardingsphere-http": {
- "url": "http://127.0.0.1:18088/mcp";
- }
- }
-}
-```
-
-不同 AI 应用的配置文件位置和字段名称可能不同，请以应用自身文档为准。
-Codex 和 Claude Code 的配置示例见本章对应子页面。
-
-## STDIO 配置
-
-将下面片段写入 AI 应用的 MCP Server 配置；具体文件位置由应用决定。
-`command` 指向发行包内的启动脚本，`args` 指向 STDIO 配置文件。
-
-```json
-{
- "mcpServers": {
- "shardingsphere": {
- "command": "/path/to/apache-shardingsphere-mcp/bin/start.sh",
- "args": ["/path/to/apache-shardingsphere-mcp/conf/mcp-stdio.yaml"]
- }
- }
-}
-```
-
-将 `/path/to/apache-shardingsphere-mcp` 替换为实际发行包目录。
-
-STDIO 模式下：
-
-- 诊断日志写到 stderr 或 `logs/mcp.log`。
-- 配置中的 `command` 和 `args` 应指向发行包内的启动脚本和 STDIO 配置文件。
+- 如果 ShardingSphere-MCP 已经独立启动，或者需要多个应用访问同一个服务，选择 HTTP 接入方式。
+- 如果只在本地开发环境使用，并希望 AI 应用在需要时启动 ShardingSphere-MCP，选择 STDIO 接入方式。
+- 如果使用 Codex 或 Claude Code，优先参考本章对应子页面。
+- 如果使用其他客户端，请按客户端自身文档配置 ShardingSphere-MCP 的地址或启动脚本。
## 集成后的使用方式
@@ -78,4 +39,4 @@ AI 应用完成 MCP Server 配置后，用户在对话中直接描述任务。
- 规划一个数据加密或数据脱敏规则，先预览不要执行。
涉及 SQL 执行、规则变更或规则变更计划执行时，应先审查预览内容，再确认执行。
-自研集成或协议调试场景见[开发者附录](../developer-appendix/)。
+自研集成或协议调试场景见[自研集成附录](../developer-appendix/)。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
index 4121464db33..4b28acad2ea 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
@@ -20,51 +20,12 @@ See [Capability Catalog](../capabilities/) for supported
tasks and usage boundar
- [Codex](./codex/): use ShardingSphere-MCP in Codex CLI or IDE extension.
- [Claude Code](./claude-code/): use ShardingSphere-MCP in Claude Code project
or user configuration.
-## Choose a Transport
+## Choose an Integration Method
-- HTTP is suitable when the MCP Server is started independently and AI
applications use a fixed endpoint.
-- STDIO is suitable when a local AI application starts ShardingSphere-MCP as a
child process.
-
-## HTTP Configuration
-
-Add the following snippet to the AI application's MCP Server configuration.
The exact file location depends on the application.
-`url` points to an already running HTTP MCP Server.
-
-```json
-{
- "mcpServers": {
- "shardingsphere-http": {
- "url": "http://127.0.0.1:18088/mcp";
- }
- }
-}
-```
-
-Configuration file locations and field names may differ between AI
applications. Follow the documentation of the application you use.
-For Codex and Claude Code examples, see the corresponding pages in this
section.
-
-## STDIO Configuration
-
-Add the following snippet to the AI application's MCP Server configuration.
The exact file location depends on the application.
-`command` points to the packaged startup script, and `args` points to the
STDIO configuration file.
-
-```json
-{
- "mcpServers": {
- "shardingsphere": {
- "command": "/path/to/apache-shardingsphere-mcp/bin/start.sh",
- "args": ["/path/to/apache-shardingsphere-mcp/conf/mcp-stdio.yaml"]
- }
- }
-}
-```
-
-Replace `/path/to/apache-shardingsphere-mcp` with the actual distribution
directory.
-
-In STDIO mode:
-
-- Diagnostics are written to stderr or `logs/mcp.log`.
-- `command` and `args` in the configuration should point to the packaged
startup script and STDIO config file.
+- If ShardingSphere-MCP is already started independently, or multiple
applications need to access the same service, choose HTTP integration.
+- If it is used only in a local development environment and the AI application
should start ShardingSphere-MCP when needed, choose STDIO integration.
+- If you use Codex or Claude Code, start with the corresponding page in this
section.
+- If you use another client, follow that client's documentation and configure
the ShardingSphere-MCP address or startup script.
## Using the Integration
@@ -78,4 +39,4 @@ Examples:
- Plan a data encryption or data masking rule and preview it without execution.
When SQL execution, rule changes, or rule change plan execution is involved,
review the preview content before confirming execution.
-For custom integration or protocol debugging, see the [Developer
Appendix](../developer-appendix/).
+For custom integration or protocol debugging, see the [Custom Integration
Appendix](../developer-appendix/).
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 cf76088079d..6823c7b54de 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
@@ -53,7 +53,7 @@ runtimeDatabases:
| *名称* | *说明* |
| --- | --- |
-| `databaseType` (+) | 连接端点的数据库协议或方言类型，例如 `MySQL` 或
`PostgreSQL`。它用于正确读取目标数据库元数据，不表示连接目标一定是真实数据库或 ShardingSphere-Proxy。 |
+| `databaseType` (+) | 连接端点的数据库协议或方言类型，例如 `MySQL` 或 `PostgreSQL`。它影响元数据识别和 SQL
能力判断，不表示连接目标一定是真实数据库或 ShardingSphere-Proxy。 |
| `jdbcUrl` (+) | MCP Server 连接运行时数据库的 JDBC URL；使用 ShardingSphere 规则能力时应指向
Proxy 逻辑库。 |
| `username` (+) | 连接运行时数据库的用户名，通常是 ShardingSphere-Proxy 逻辑库用户名。 |
| `password` (?) | 连接运行时数据库的密码。 |
@@ -71,39 +71,25 @@ runtimeDatabases:
- 模式、表、视图、索引和序列等元数据依赖目标数据库的 JDBC 元数据；Proxy 和真实数据库的可见结果可能不同。
- 如果目标 JDBC 驱动没有随发行包提供，请把驱动 jar 放入 `plugins/`。
-## 连接目标与能力边界
+## 连接目标选择
-`runtimeDatabases` 当前可以配置任意可用的 JDBC URL。不同连接目标的语义不同，能力边界也不同。
+`runtimeDatabases` 可以配置任意可连接的 JDBC URL。用户能看到的数据库对象和可执行的治理任务取决于连接目标。
### 连接 ShardingSphere-Proxy 逻辑库
-这是使用 ShardingSphere 规则能力时的推荐连接方式。该模式面向 Proxy 暴露的逻辑库和逻辑 SQL 视图，适合使用以下能力：
+如果需要使用 ShardingSphere 规则状态、数据加密、数据脱敏或规则变更能力，应连接 ShardingSphere-Proxy 逻辑库。
-- 读取 ShardingSphere 逻辑库、逻辑表和逻辑列元数据。
-- 查询 Proxy 可见的加密、脱敏算法插件。
-- 查询、规划、应用和校验加密或脱敏规则。
-- 通过 Proxy 执行逻辑 SQL 和规则变更生成的待执行语句。
-
-该模式受 Proxy 能力限制：
-
-- JDBC 元数据、`information_schema`、索引、序列和列类型信息以 Proxy 暴露结果为准，不等同于完整底层物理库元数据。
-- 物理列、物理索引和多存储节点一致性不作为 MCP 自动确认的稳定契约。
-- 可用规则变更语句、规则类型和算法插件取决于 Proxy 版本、已安装插件和当前账号权限。
-- 物理变更语句应先审查；只有 Proxy 能安全路由并执行时才适合自动应用。
+此时用户看到的是 Proxy 暴露的逻辑库、逻辑表和逻辑列。
+Proxy 可见元数据可能不同于底层物理库的完整结构；涉及物理列、索引或规则变更的计划应先审查再执行。
### 连接真实数据库
-该模式只适合把 MCP 作为通用 JDBC 元数据和 SQL 入口使用，适合以下能力：
-
-- 浏览数据库、模式、表、视图、列、索引和序列等 JDBC 元数据。
-- 搜索元数据。
-- 执行通用只读查询，或在明确授权后执行普通 DML、DDL、DCL。
+如果只需要查看普通数据库元数据、搜索对象或执行受控查询，可以连接真实数据库。
-该模式不提供 ShardingSphere 规则能力：
+此时用户看到的是目标数据库自身元数据，不代表 ShardingSphere 规则状态。
+数据加密、数据脱敏等依赖 ShardingSphere 规则的任务不适用于真实数据库连接。
-- 不能发现 Proxy 中可见的加密或脱敏算法插件。
-- 不能查询、规划、应用或校验 ShardingSphere 加密、脱敏规则。
-- 不能使用依赖 ShardingSphere 规则变更语句的能力；真实数据库通常不识别 ShardingSphere 规则变更语句。
+不同连接目标支持的自然语言任务见[能力清单](../capabilities/)。
## 插件目录
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 933b7fc27ae..d04eaf93b2f 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
@@ -53,7 +53,7 @@ runtimeDatabases:
| *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. |
+| `databaseType` (+) | Database protocol or dialect type of the connection
endpoint, such as `MySQL` or `PostgreSQL`. It affects metadata recognition and
SQL capability judgment; 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. |
@@ -71,39 +71,25 @@ Notes:
- Schema, table, view, index, and sequence metadata depends on target JDBC
metadata. Proxy-visible metadata and physical database metadata may differ.
- If the target JDBC driver is not packaged, copy the driver jar under
`plugins/`.
-## Connection Targets and Capability Boundaries
+## Choose a Connection Target
-`runtimeDatabases` currently accepts any reachable JDBC URL. Different targets
have different semantics and capability boundaries.
+`runtimeDatabases` can use any reachable JDBC URL. The database objects users
can see and the governance tasks they can perform depend on the connection
target.
### Connecting to a ShardingSphere-Proxy logical database
-This is the recommended target when using ShardingSphere rule capabilities. In
this mode, MCP works against the logical database and logical SQL view exposed
by Proxy, and is suitable for these capabilities:
+Connect to a ShardingSphere-Proxy logical database when ShardingSphere rule
state, data encryption, data masking, or rule change capabilities are required.
-- Reading ShardingSphere logical database, table, and column metadata.
-- Listing encryption and masking algorithm plugins visible from Proxy.
-- Querying, planning, applying, and validating encryption or masking rules.
-- Executing logical SQL and statements generated by rule changes through Proxy.
-
-This mode is constrained by Proxy capabilities:
-
-- JDBC metadata, `information_schema`, indexes, sequences, and column type
information follow what Proxy exposes. They are not equivalent to a complete
physical database catalog.
-- Physical columns, physical indexes, and consistency across multiple storage
nodes are not stable contracts that MCP can automatically confirm.
-- Available rule change statements, rule types, and algorithm plugins depend
on the Proxy version, installed plugins, and current account privileges.
-- Physical change statements should be reviewed first. They are suitable for
automatic execution only when Proxy can route and execute them safely.
+Users see the logical databases, tables, and columns exposed by Proxy.
+Proxy-visible metadata may differ from the complete physical database
structure. Plans involving physical columns, indexes, or rule changes should be
reviewed before execution.
### Connecting to a physical database
-This mode is suitable only when MCP is used as a general JDBC metadata and SQL
entry point, including these capabilities:
-
-- Browsing JDBC metadata for databases, schemas, tables, views, columns,
indexes, and sequences.
-- Searching metadata.
-- Executing general read-only queries, or ordinary DML, DDL, and DCL after
explicit authorization.
+Connect directly to a physical database when only ordinary metadata
inspection, object search, or controlled queries are needed.
-This mode does not provide ShardingSphere rule capabilities:
+Users see metadata from the target database itself, not ShardingSphere rule
state.
+Tasks that depend on ShardingSphere rules, such as data encryption and data
masking, do not apply to direct physical database connections.
-- It cannot discover encryption or masking algorithm plugins visible from
Proxy.
-- It cannot query, plan, apply, or validate ShardingSphere encryption or
masking rules.
-- It cannot use capabilities that depend on ShardingSphere rule change
statements. Physical databases usually do not understand those statements.
+For natural-language tasks supported by each connection target, see
[Capability Catalog](../capabilities/).
## Plugin directory
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
index b7f87017851..fb0b890fa55 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
@@ -1,11 +1,42 @@
+++
-title = "开发者附录"
+title = "自研集成附录"
weight = 9
+++
-本页面向需要自研 MCP 集成、调试协议请求或定位客户端适配问题的开发者。
+本页面面向需要自研 MCP 集成、调试协议请求或定位客户端适配问题的开发者。
普通用户通常不需要阅读本页，可直接参考[快速开始](../quick-start/)、[客户端集成](../client-integration/)和[能力清单](../capabilities/)。
+## 通用客户端配置示例
+
+如果使用的 AI 应用没有专门页面，可按客户端自身文档选择 HTTP 或 STDIO 配置方式。
+
+HTTP 示例：
+
+```json
+{
+ "mcpServers": {
+ "shardingsphere-http": {
+ "url": "http://127.0.0.1:18088/mcp";
+ }
+ }
+}
+```
+
+STDIO 示例：
+
+```json
+{
+ "mcpServers": {
+ "shardingsphere": {
+ "command": "/path/to/apache-shardingsphere-mcp/bin/start.sh",
+ "args": ["/path/to/apache-shardingsphere-mcp/conf/mcp-stdio.yaml"]
+ }
+ }
+}
+```
+
+将 `/path/to/apache-shardingsphere-mcp` 替换为实际发行包目录。
+
## 协议能力发现
| 入口 | 返回内容 | 适用场景 |
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
index dc789d84b04..b6ca1fd0573 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
@@ -1,11 +1,42 @@
+++
-title = "Developer Appendix"
+title = "Custom Integration Appendix"
weight = 9
+++
This page is for developers who build custom MCP integrations, debug protocol
requests, or troubleshoot client adaptation issues.
Most users do not need this page. Use [Quick Start](../quick-start/), [Client
Integration](../client-integration/), and [Capability
Catalog](../capabilities/) for normal usage.
+## Generic Client Configuration Examples
+
+If the AI application you use does not have a dedicated page, choose HTTP or
STDIO configuration according to that client's own documentation.
+
+HTTP example:
+
+```json
+{
+ "mcpServers": {
+ "shardingsphere-http": {
+ "url": "http://127.0.0.1:18088/mcp";
+ }
+ }
+}
+```
+
+STDIO example:
+
+```json
+{
+ "mcpServers": {
+ "shardingsphere": {
+ "command": "/path/to/apache-shardingsphere-mcp/bin/start.sh",
+ "args": ["/path/to/apache-shardingsphere-mcp/conf/mcp-stdio.yaml"]
+ }
+ }
+}
+```
+
+Replace `/path/to/apache-shardingsphere-mcp` with the actual distribution
directory.
+
## Protocol Capability Discovery
| Entry | Returned content | Usage scenario |
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 f4a190809a0..989bbd2776e 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
@@ -12,5 +12,4 @@ ShardingSphere-MCP 通过功能插件扩展领域能力。
- 数据加密：规划、审查、执行和校验数据加密规则。
- 数据脱敏：规划、审查、执行和校验数据脱敏规则。
-新增或第三方功能插件可以通过 `plugins/` 目录加入运行时类路径。
-如果功能插件未随发行包提供，启动前需要同时准备它依赖的 ShardingSphere 模块和第三方 jar。
+如果使用额外功能插件，请按插件提供方说明准备对应 jar 和依赖，并在启动前放入发行包 `plugins/` 目录。
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 8eae02ee807..2109e640be7 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
@@ -12,5 +12,4 @@ The packaged distribution includes these official MCP feature
plugins:
- Data Encryption: plan, review, apply, and validate data encryption rules.
- Data Masking: plan, review, 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.
+When using additional feature plugins, follow the plugin provider's
instructions, prepare the required jars and dependencies, and place them under
the distribution `plugins/` directory 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 5a2ea658030..630d94b026c 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
@@ -58,15 +58,15 @@ weight = 2
- 密钥、凭证等敏感参数是否只以占位符或受保护方式传递。
- 是否会影响查询能力、运行时规则或已有业务 SQL。
-## 派生列与索引计划
+## 审查派生列与索引建议
加密规则可能需要物理派生列来保存密文或支持查询。
-MCP 会根据逻辑列、用户意图和已有规则生成派生列建议。
+计划中出现派生列或索引建议时，用户应确认真实物理表是否允许新增列或索引，以及命名是否符合运维规范。
- `*_cipher` 用于保存密文，是加密规则的默认派生列。
-- 如果需要等值查询，会生成 `*_assisted_query`，并在允许生成索引建议时返回相应索引计划。
+- 如果需要等值查询，计划可能包含 `*_assisted_query` 和对应索引建议。
- 如果需要模糊查询，会生成 `*_like_query`，用于支持 LIKE 查询场景。
-- 如果默认列名冲突，系统会追加数字后缀，并在计划中返回最终命名。
+- 如果计划给出调整后的物理列名，应确认它不会与现有物理对象冲突。
## 预览、执行和校验
@@ -88,21 +88,21 @@ MCP 会根据逻辑列、用户意图和已有规则生成派生列建议。
- 仅支持 ShardingSphere-Proxy 逻辑库。
- 直连真实数据库时，本功能不适用。
-### MCP 插件边界
+### 能力边界
-- MCP Server 不实现加密算法，也不替代用户判断加密策略是否满足业务安全要求。
+- ShardingSphere-MCP 不提供加密算法本身，也不替代用户判断加密策略是否满足业务安全要求。
- 规划结果是可审查的变更计划；是否执行仍需要用户确认。
- 删除加密规则只移除规则本身，不会恢复历史明文数据；不再需要的物理派生列或索引仍需人工清理。
-### Proxy 可见元数据边界
+### 元数据边界
-- MCP 根据 Proxy 暴露的逻辑元数据生成派生列、索引和列类型建议；它不会直接检查每个物理库。
+- ShardingSphere-MCP 根据 Proxy 暴露的逻辑元数据生成派生列、索引和列类型建议；它不会直接检查每个物理库。
- 执行前应结合真实物理库表结构审查生成的物理变更语句。
-### ShardingSphere 功能边界
+### ShardingSphere 能力边界
- 不处理已有数据迁移或回填。
### 对象名处理边界
-- MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 对象名。为保证生成的 SQL
或规则变更语句可审查，对象名内容不能包含反引号、NUL、回车或换行。
+- ShardingSphere-MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 对象名。为保证生成的 SQL
或规则变更语句可审查，对象名内容不能包含反引号、NUL、回车或换行。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
index 7a8763f96c6..3afe8d74619 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
@@ -58,15 +58,15 @@ After a plan is generated, review:
- 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
+## Review Derived Columns and Index Suggestions
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.
+When a plan contains derived columns or index suggestions, users should
confirm whether the real physical table can accept new columns or indexes, and
whether the generated names match operational conventions.
- `*_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 returned when index suggestions are allowed.
+- If equality query is required, the plan may contain `*_assisted_query` and
corresponding index suggestions.
- 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 the plan.
+- If the plan provides adjusted physical column names, confirm that they do
not conflict with existing physical objects.
## Preview, apply, and validate
@@ -88,21 +88,21 @@ For the general review flow of rule changes, see [Rule
Change Flow](../plugin-wo
- Supports ShardingSphere-Proxy logical databases only.
- This feature does not apply to direct physical database connections.
-### MCP plugin boundaries
+### Capability boundaries
-- The MCP Server does not implement encryption algorithms and does not replace
the user's judgment on whether an encryption strategy satisfies business
security requirements.
+- ShardingSphere-MCP does not provide encryption algorithms and does not
replace the user's judgment on whether an encryption strategy satisfies
business security requirements.
- Planning results are reviewable change plans. Execution still requires user
confirmation.
- Dropping an encryption rule removes the rule only. It does not restore
historical plaintext data, and physical derived columns or indexes still
require manual cleanup when they are no longer needed.
-### Proxy-visible metadata boundaries
+### Metadata boundaries
-- MCP generates derived-column, index, and column-type suggestions from
logical metadata exposed by Proxy. It does not inspect every physical database
directly.
+- ShardingSphere-MCP generates derived-column, index, and column-type
suggestions from logical metadata exposed by Proxy. It does not inspect every
physical database directly.
- Review generated physical change statements against the real physical table
structure before applying them.
-### ShardingSphere feature boundaries
+### ShardingSphere capability boundaries
- Existing data migration or backfill is not handled.
### Identifier handling boundaries
-- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode object
names. To keep generated SQL or rule change statements reviewable, object name
content must not contain backticks, NUL, carriage returns, or line feeds.
+- ShardingSphere-MCP handles quoted, case-sensitive, keyword, whitespace, and
Unicode object names. To keep generated SQL or rule change statements
reviewable, object name content must not contain backticks, NUL, carriage
returns, or line feeds.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
index d017febcbf8..612ffdf8d6f 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
@@ -76,17 +76,17 @@ weight = 3
- 仅支持 ShardingSphere-Proxy 逻辑库。
- 直连真实数据库时，本功能不适用。
-### MCP 插件边界
+### 能力边界
-- MCP Server 不实现脱敏算法，也不替代用户判断脱敏策略是否满足业务合规要求。
+- ShardingSphere-MCP 不提供脱敏算法本身，也不替代用户判断脱敏策略是否满足业务合规要求。
- 规划结果是可审查的变更计划；是否执行仍需要用户确认。
- 删除脱敏规则只移除规则本身；后续通过 Proxy 查询该列时不再应用该脱敏规则。
-### Proxy 可见元数据边界
+### 元数据边界
- 逻辑列和规则校验以 Proxy 可见信息为准。
- 直连真实数据库只能执行普通 SQL，不代表脱敏规则状态。
### 对象名处理边界
-- MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 对象名。为保证生成的 SQL
或规则变更语句可审查，对象名内容不能包含反引号、NUL、回车或换行。
+- ShardingSphere-MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 对象名。为保证生成的 SQL
或规则变更语句可审查，对象名内容不能包含反引号、NUL、回车或换行。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
index 33ddd4be7a6..45e14971909 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
@@ -76,17 +76,17 @@ For the general review flow of rule changes, see [Rule
Change Flow](../plugin-wo
- Supports ShardingSphere-Proxy logical databases only.
- This feature does not apply to direct physical database connections.
-### MCP plugin boundaries
+### Capability boundaries
-- The MCP Server does not implement masking algorithms and does not replace
the user's judgment on whether a masking strategy satisfies business compliance
requirements.
+- ShardingSphere-MCP does not provide masking algorithms and does not replace
the user's judgment on whether a masking strategy satisfies business compliance
requirements.
- Planning results are reviewable change plans. Execution still requires user
confirmation.
- Dropping a masking rule removes the rule only. Later queries through Proxy
no longer apply that masking rule to the column.
-### Proxy-visible metadata boundaries
+### Metadata boundaries
- Logical column and rule validation are based on what Proxy exposes.
- Direct physical database connections can execute ordinary SQL only and do
not represent masking rule state.
### Identifier handling boundaries
-- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode object
names. To keep generated SQL or rule change statements reviewable, object name
content must not contain backticks, NUL, carriage returns, or line feeds.
+- ShardingSphere-MCP handles quoted, case-sensitive, keyword, whitespace, and
Unicode object names. To keep generated SQL or rule change statements
reviewable, object name content must not contain backticks, NUL, carriage
returns, or line feeds.
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 54b122c025e..d5c3e31cc2f 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
@@ -24,13 +24,13 @@ weight = 1
| 执行变更 | 确认自动执行，或导出人工执行包后由运维执行。 | 有副作用的变更必须经过确认。 |
| 校验结果 | 执行后查看规则状态、元数据和 SQL 可执行性。 | 确认变更是否生效。 |
-## 执行方式
+## 变更执行选择
-| 执行方式 | 是否修改运行时状态 | 适用场景 |
+| 用户说法 | 用户会得到什么 | 关注点 |
| --- | --- | --- |
-| 只预览 | 否 | 先查看变更内容和副作用范围。 |
-| 审查后执行 | 是 | 用户确认后，由 MCP Server 执行变更。 |
-| 人工执行包 | 否 | 不自动执行，返回可由运维人员审查和执行的语句。 |
+| “先预览，不要执行。” | 只返回变更内容和影响范围。 | 适合先确认语句、物理列、索引建议和副作用。 |
+| “确认执行刚才的计划。” | 执行已经预览并确认的变更。 | 适合用户已经完成审查的场景。 |
+| “导出人工执行包。” | 返回可由运维人员审查和执行的语句。 | 适合需要审批、变更窗口或受控环境执行的场景。 |
## 敏感输入
@@ -40,7 +40,7 @@ weight = 1
推荐处理方式：
- 在计划中保留占位符。
-- 由客户端或运维侧通过密钥管理系统、受保护环境变量或运维控制通道取得真实值。
+- 由 AI 应用或运维侧通过密钥管理系统、受保护环境变量或运维控制通道取得真实值。
- 在受控环境中替换占位符并执行。
ShardingSphere-MCP 不直接读取密钥管理系统。
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 205ef348ebd..139b12706e7 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
@@ -24,13 +24,13 @@ It is not a standalone business feature. Users usually
enter this flow from a co
| 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. |
-## Execution Choices
+## Change Execution Choices
-| Choice | Changes runtime state | Use case |
+| User wording | What users receive | Focus |
| --- | --- | --- |
-| Preview only | No | Inspect change content 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. |
+| "Preview first, do not execute." | Change content and impact scope only. |
Use this to confirm statements, physical columns, index suggestions, and side
effects first. |
+| "Confirm and execute the previous plan." | The previewed and confirmed
change is executed. | Use this only after the user has completed review. |
+| "Export a manual execution package." | Statements that operators can review
and execute manually. | Use this when approval, a change window, or a
controlled execution environment is required. |
## Sensitive Inputs
@@ -40,7 +40,7 @@ These values should not be written into ordinary documents,
chat records, or log
Recommended handling:
- Keep placeholders in the plan.
-- Let the client or operator obtain real values through a secret manager,
protected environment variable, or controlled operations channel.
+- Let the AI application 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.
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 eb00151845d..194993a88bc 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
@@ -65,20 +65,14 @@ start "ShardingSphere MCP" cmd /c "bin\start.bat >
logs\mcp-http.log 2>&1"
## 接入 AI 应用
-在 AI 应用、IDE 插件或 Agent 平台中配置 HTTP MCP Server 地址：
-
-```json
-{
- "mcpServers": {
- "shardingsphere": {
- "url": "http://127.0.0.1:18088/mcp";
- }
- }
-}
-```
+选择一个支持 MCP 的 AI 应用、IDE 插件或 Agent 平台，并配置上一步启动的 HTTP MCP Server 地址。
+
+典型客户端配置见：
+
+- [Codex](../client-integration/codex/)
+- [Claude Code](../client-integration/claude-code/)
-不同 AI 应用的配置文件位置和字段名称可能不同，请以客户端自身文档为准。
-更多 HTTP 和 STDIO 配置方式见[客户端集成](../client-integration/)。
+其他客户端请按其自身文档配置 ShardingSphere-MCP 地址：`http://127.0.0.1:18088/mcp`。
## 通过自然语言验证
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 3107852d2e1..42514501e6f 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
@@ -65,20 +65,14 @@ The default configuration file is `conf/mcp-http.yaml`, and
the default endpoint
## Connect an AI Application
-Configure the HTTP MCP Server address in the AI application, IDE extension, or
agent platform:
-
-```json
-{
- "mcpServers": {
- "shardingsphere": {
- "url": "http://127.0.0.1:18088/mcp";
- }
- }
-}
-```
+Choose an MCP-capable AI application, IDE extension, or agent platform, and
configure the HTTP MCP Server address started in the previous step.
+
+Typical client configuration examples:
+
+- [Codex](../client-integration/codex/)
+- [Claude Code](../client-integration/claude-code/)
-Configuration file locations and field names may differ between AI
applications. Follow the documentation of the client you use.
-For more HTTP and STDIO options, see [Client
Integration](../client-integration/).
+For other clients, follow their own documentation and use the
ShardingSphere-MCP address: `http://127.0.0.1:18088/mcp`.
## Verify through Natural Language
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 c03c2122c99..bac3c79d903 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -3,7 +3,7 @@ title = "常见问题"
weight = 7
+++
-本页按用户侧现象整理 ShardingSphere-MCP、AI 应用集成、数据库连接、元数据查看、SQL 执行和规则变更的排查方法。
+本页按用户侧现象整理 ShardingSphere-MCP、AI 应用集成、数据库连接、元数据查看、查询和规则变更的排查方法。
功能插件的业务规则问题请查看对应功能插件文档。
## 排查索引
@@ -27,7 +27,7 @@ weight = 7
- `username` 和 `driverClassName` 必须显式写出且不能为空；无密码账号可以省略 `password` 或写 `""`。
- 人工执行包中的密钥占位符应由执行人员在受控环境替换。
-- 开发者需要排查协议请求时，可参考[开发者附录](../developer-appendix/)。
+- 开发者需要排查协议请求时，可参考[自研集成附录](../developer-appendix/)。
## 连接错误分类
@@ -44,13 +44,13 @@ weight = 7
| `connection_failed` | 连接失败，但无法归类为更具体的原因。 |
| `database_not_visible` | 指定逻辑库对当前连接不可见。 |
-## SQL 执行建议
+## 查询与变更建议
-| SQL 类型 | 建议 |
+| 场景 | 建议 |
| --- | --- |
-| `SELECT` | 用于只读查询，建议限制返回行数。 |
-| `EXPLAIN ANALYZE` | 仅在目标逻辑库能力允许时使用。 |
-| DML、DDL、DCL、事务控制、savepoint | 先预览并审查副作用，再决定是否执行。 |
+| 查询数据 | 建议限制返回行数。 |
+| 分析 SQL 执行计划 | 仅在目标逻辑库能力允许时使用。 |
+| 修改数据、结构、规则或事务状态 | 先预览并审查副作用，再决定是否执行。 |
## 提供给管理员或排障人员的信息
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 b4f745c6733..64188cadeb7 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -3,7 +3,7 @@ title = "Troubleshooting"
weight = 7
+++
-This page organizes troubleshooting by user-visible symptoms for
ShardingSphere-MCP, AI application integration, database connectivity, metadata
inspection, SQL execution, and rule changes.
+This page organizes troubleshooting by user-visible symptoms for
ShardingSphere-MCP, AI application integration, database connectivity, metadata
inspection, queries, and rule changes.
For feature-specific business rule issues, see the corresponding feature
plugin documentation.
## Troubleshooting Index
@@ -27,7 +27,7 @@ Additional notes:
- `username` and `driverClassName` must be declared explicitly and cannot be
empty; a no-password account can omit `password` or use `""`.
- Secret placeholders in manual packages should be replaced by operators in a
controlled environment.
-- For protocol request debugging, see the [Developer
Appendix](../developer-appendix/).
+- For protocol request debugging, see the [Custom Integration
Appendix](../developer-appendix/).
## Connection Failure Categories
@@ -44,13 +44,13 @@ When a runtime database or ShardingSphere-Proxy connection
fails, MCP responses
| `connection_failed` | The connection failed, but cannot be classified into a
more specific cause. |
| `database_not_visible` | The specified logical database is not visible to
the current connection. |
-## SQL Execution Recommendations
+## Query and Change Recommendations
-| SQL type | Recommendation |
+| Scenario | Recommendation |
| --- | --- |
-| `SELECT` | Use for read-only queries and limit returned rows. |
-| `EXPLAIN ANALYZE` | Use only when the target logical database capability
allows it. |
-| DML, DDL, DCL, transaction control, savepoint | Preview and review side
effects before deciding whether to execute. |
+| Query data | Limit returned rows. |
+| Analyze an SQL execution plan | Use only when the target logical database
capability allows it. |
+| Change data, structure, rules, or transaction state | Preview and review
side effects before deciding whether to execute. |
## Information for Administrators or Troubleshooters
