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 32478cb8a56 Reorganize ShardingSphere-MCP docs around natural language
usage (#38783)
32478cb8a56 is described below
commit 32478cb8a560044d814121ab7aef608ea5f1fd3b
Author: Liang Zhang <[email protected]>
AuthorDate: Wed Jun 3 12:14:46 2026 +0800
Reorganize ShardingSphere-MCP docs around natural language usage (#38783)
Refocus the ShardingSphere-MCP user manual on natural-language database
tasks in AI applications instead of protocol-level MCP details.
Rewrite quick start and capability catalog around user-facing tasks, move
JSON-RPC, tools, resources, prompts, completion targets, and URI references
into a new developer appendix, and rename plugin workflows to rule change
flow.
Update client integration, configuration, deployment, troubleshooting, and
feature plugin pages in both Chinese and English to keep protocol details
out
of the main user path.
---
.../user-manual/shardingsphere-mcp/_index.cn.md | 18 +--
.../user-manual/shardingsphere-mcp/_index.en.md | 18 +--
.../shardingsphere-mcp/capabilities.cn.md | 179 ++++++++-------------
.../shardingsphere-mcp/capabilities.en.md | 169 +++++++------------
.../shardingsphere-mcp/client-integration.cn.md | 27 ++--
.../shardingsphere-mcp/client-integration.en.md | 35 ++--
.../shardingsphere-mcp/configuration.cn.md | 14 +-
.../shardingsphere-mcp/configuration.en.md | 16 +-
.../shardingsphere-mcp/deployment.cn.md | 4 +-
.../shardingsphere-mcp/deployment.en.md | 4 +-
.../shardingsphere-mcp/developer-appendix.cn.md | 139 ++++++++++++++++
.../shardingsphere-mcp/developer-appendix.en.md | 139 ++++++++++++++++
.../shardingsphere-mcp/features/_index.cn.md | 6 +-
.../shardingsphere-mcp/features/_index.en.md | 6 +-
.../shardingsphere-mcp/features/encrypt.cn.md | 26 +--
.../shardingsphere-mcp/features/encrypt.en.md | 26 +--
.../shardingsphere-mcp/features/mask.cn.md | 22 +--
.../shardingsphere-mcp/features/mask.en.md | 22 +--
.../features/plugin-workflow.cn.md | 20 +--
.../features/plugin-workflow.en.md | 30 ++--
.../shardingsphere-mcp/quick-start.cn.md | 135 +++-------------
.../shardingsphere-mcp/quick-start.en.md | 145 ++++-------------
.../shardingsphere-mcp/troubleshooting.cn.md | 55 +++----
.../shardingsphere-mcp/troubleshooting.en.md | 59 +++----
24 files changed, 642 insertions(+), 672 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 3952b4eede2..dfe28604cb6 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
@@ -8,13 +8,10 @@ chapter = true
ShardingSphere-MCP 是 Apache ShardingSphere 的 MCP Server，可以独立启动。
MCP 是连接 AI 应用与外部数据源和工具的开放协议，协议说明参见 [MCP
官方文档](https://modelcontextprotocol.io/docs/learn/architecture)。
-AI 应用开发者可以将 ShardingSphere-MCP 作为数据库访问能力接入应用。
-用户通过自然语言描述数据库任务后，AI 应用在需要数据库上下文或数据库操作时，通过 MCP Client 调用
ShardingSphere-MCP；ShardingSphere-MCP 再访问 ShardingSphere 逻辑库或普通数据库。
+AI 应用开发者可以将 ShardingSphere-MCP 作为受控数据库访问能力接入应用。
+接入后，用户可以通过自然语言查看数据库结构、执行受控查询，并规划需要审查的 ShardingSphere 规则变更。
-通过这种方式，AI 应用可以查看 ShardingSphere 逻辑库元数据、执行受控 SQL 查询，并生成可审查的治理变更计划。
-治理变更计划用于描述数据加密、数据脱敏等规则变更的目标对象、影响范围和待执行语句，便于用户在执行前审查。
-
-ShardingSphere-MCP 的配置以数据库为核心：先配置 MCP Server 可以连接的 ShardingSphere 逻辑库或普通数据库，再在
AI 应用中完成 MCP 集成。
+ShardingSphere-MCP 的配置以数据库为核心：先配置可以连接的 ShardingSphere 逻辑库或普通数据库，再在 AI 应用中完成集成。
## 面向 AI 应用的数据库访问
@@ -33,13 +30,14 @@ ShardingSphere-MCP 面向支持 MCP 的 AI 应用、IDE 插件和 Agent 平台
## 文档结构
-- 快速开始：构建发行包，配置一个可连接的逻辑库，启动 HTTP MCP Server，并验证基础任务。
-- 能力清单：说明 MCP Server 可以完成的数据库任务、可读取的信息和使用边界。
+- 快速开始：构建发行包，配置一个可连接的逻辑库，启动 MCP Server，并在 AI 应用中验证自然语言任务。
+- 能力清单：说明用户可以通过自然语言完成的数据库任务和使用边界。
- 配置说明：说明传输方式、`runtimeDatabases`、插件目录和启动参数。
-- 客户端集成：说明如何通过 HTTP 或 STDIO 把 MCP Server 接入 AI 应用或 MCP 客户端，以及集成后的使用方式。
+- 客户端集成：说明如何通过 HTTP 或 STDIO 把 MCP Server 接入 AI 应用，以及集成后的使用方式。
- 部署说明：说明发行包、OCI 镜像和安全部署建议。
- 常见问题：排查 MCP Server、连接、配置、元数据和 SQL 执行的通用问题。
- 功能插件：说明官方 MCP 功能插件能力，以及插件变更的审查、执行和校验流程。
- - 插件工作流：说明插件变更任务的确认、预览、执行和校验流程。
+ - 规则变更流程：说明规则变更任务的确认、预览、执行和校验流程。
- 数据加密：说明如何通过 MCP 功能插件规划、执行和校验数据加密规则变更。
- 数据脱敏：说明如何通过 MCP 功能插件规划、执行和校验数据脱敏规则变更。
+- 开发者附录：说明自研集成或协议调试需要的协议细节和 HTTP 调试示例。
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 93f834abb08..90daa6c249e 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
@@ -8,13 +8,10 @@ chapter = true
ShardingSphere-MCP is the MCP Server for Apache ShardingSphere. It can run
independently.
MCP is an open protocol for connecting AI applications to external data
sources and tools. For protocol details, see the [official MCP
documentation](https://modelcontextprotocol.io/docs/learn/architecture).
-AI application developers can integrate ShardingSphere-MCP as a database
access capability.
-After users describe database tasks in natural language, the AI application
calls ShardingSphere-MCP through an MCP Client when it needs database context
or database operations. ShardingSphere-MCP then accesses ShardingSphere logical
databases or regular databases.
+AI application developers can integrate ShardingSphere-MCP as a controlled
database access capability.
+After integration, users can inspect database structure, run controlled
queries, and plan reviewable ShardingSphere rule changes through natural
language.
-In this way, AI applications can inspect ShardingSphere logical database
metadata, run controlled SQL queries, and generate reviewable governance change
plans.
-Governance change plans describe the target objects, impact scope, and
statements to be executed for rule changes such as data encryption and data
masking, so users can review them before execution.
-
-ShardingSphere-MCP configuration starts from databases: configure the
ShardingSphere logical databases or regular databases that the MCP Server can
connect to, then complete MCP integration in the AI application.
+ShardingSphere-MCP configuration starts from databases: configure the
ShardingSphere logical databases or regular databases that it can connect to,
then complete integration in the AI application.
## Database Access for AI Applications
@@ -33,13 +30,14 @@ Tasks with side effects should create or preview a plan
first, then run only aft
## Structure
-- Quick Start: build the distribution, configure a reachable logical database,
start the HTTP MCP Server, and verify basic tasks.
-- Capability Catalog: understand the database tasks, readable information, and
usage boundaries provided by the MCP Server.
+- Quick Start: build the distribution, configure a reachable logical database,
start the MCP Server, and verify natural-language tasks in an AI application.
+- Capability Catalog: understand the database tasks and usage boundaries that
users can access through natural language.
- Configuration: configure transport, `runtimeDatabases`, plugin directories,
and launch parameters.
-- Client Integration: connect the MCP Server to an AI application or MCP
client through HTTP or STDIO, and understand how to use it after integration.
+- Client Integration: connect the MCP Server to an AI application through HTTP
or STDIO, and understand how to use it after integration.
- Deployment: deploy the binary distribution and OCI image safely.
- Troubleshooting: diagnose common MCP Server, connection, configuration,
metadata, and SQL execution issues.
- Feature Plugins: use official MCP feature plugins and understand how to
review, apply, and validate plugin changes.
- - Plugin Workflows: understand confirmation, preview, execution, and
validation for plugin change tasks.
+ - 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.
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 abdc42fcd9b..53d9b248f99 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
@@ -3,132 +3,83 @@ title = "能力清单"
weight = 2
+++
-本页从 AI 应用开发者和集成者视角说明 ShardingSphere-MCP 可以读取哪些信息、执行哪些动作，以及不同连接目标下的使用边界。
-集成 MCP 的 AI 应用会发现当前 MCP Server 实际可用的能力；用户通常只需要在 AI 应用中描述要完成的数据库任务。
+本页说明用户可以通过自然语言完成的数据库任务，以及连接 ShardingSphere-Proxy 和普通数据库时的使用边界。
+协议级对接信息见[开发者附录](../developer-appendix/)。
-## 能力发现
+## 连接目标
-能力发现是 MCP 客户端或集成 MCP 的 AI 应用读取 ShardingSphere-MCP 可用能力的过程。
-使用现成客户端时，用户通常只需要描述数据库任务；AI 应用开发者需要在应用建立 MCP
连接后读取工具、资源、资源模板和提示，并把这些能力提供给模型或应用编排逻辑。
+### 连接 ShardingSphere-Proxy
-| 入口 | 类型 | 返回内容 | 使用场景 |
-| --- | --- | --- | --- |
-| `tools/list`、`resources/list`、`resources/templates/list`、`prompts/list` |
MCP 协议能力 | 当前 MCP Server 暴露的工具、资源、资源模板和提示。 | AI 应用建立可调用能力清单，并按任务选择可用上下文或动作。 |
-| `shardingsphere://capabilities` | ShardingSphere 服务能力 |
运行时数据库、连接目标、功能插件和副作用边界。 | 判断当前 MCP Server 可用于元数据查看、SQL 执行或治理变更。 |
-| `shardingsphere://databases/{database}/capabilities` | 数据库能力 | 指定运行时数据库的
SQL、事务、schema 和元数据对象能力。 | 针对某个数据库判断可用操作和限制。 |
+适合查看 ShardingSphere 逻辑库结构、读取规则状态、执行受控 SQL，或生成需要审查的规则变更计划。
-能力发现结果代表当前 MCP Server 实际对外可用的内容；实际能否使用某项能力，还取决于 `runtimeDatabases` 连接的是
ShardingSphere-Proxy 还是普通数据库。
-客户端会根据连接目标选择可用能力。
+可用任务包括：
-### 连接 ShardingSphere-Proxy
-
-适合查看 ShardingSphere 逻辑库结构、读取治理规则状态、执行受控 SQL，或通过功能插件生成可审查的治理变更计划。
-此模式下，逻辑元数据、逻辑 SQL、DistSQL、规则状态、算法插件和插件工作流可以被 MCP 能力使用。
+- 查看逻辑库、schema、表、视图、列、索引和 sequence。
+- 搜索表、视图、列、索引等元数据对象。
+- 执行只读 SQL 查询。
+- 预览可能修改数据、元数据或规则的 SQL。
+- 规划、审查、执行和校验数据加密或数据脱敏规则变更。
使用限制：
-- 物理元数据以 Proxy 暴露结果为准，不能等同于每个底层物理库的完整元数据。
-- 依赖 ShardingSphere 规则、算法或 DistSQL 的功能只适用于 Proxy 连接。
-- 规划类能力生成的是可审查计划，执行前仍需确认业务影响。
+- 用户看到的是 Proxy 暴露的逻辑元数据，不等同于每个底层物理库的完整元数据。
+- 依赖 ShardingSphere 规则、算法或规则变更语句的任务只适用于 Proxy 连接。
+- 有副作用的任务应先预览或生成计划，审查后再确认执行。
### 直接连接数据库
-适合把 MCP Server 作为普通数据库的受控访问通路，用于读取 JDBC 元数据、搜索对象、辅助生成查询，或执行受限 SQL。
-此模式下，通用数据库元数据和 SQL 工具可用。
+适合把 ShardingSphere-MCP 作为普通数据库的受控访问入口，用于查看元数据、搜索对象和执行受限 SQL。
+
+可用任务包括：
+
+- 查看数据库、schema、表、视图、列、索引和 sequence。
+- 搜索元数据对象。
+- 执行只读 SQL 查询。
+- 在明确授权后预览或执行普通 DML、DDL、DCL。
使用限制：
-- ShardingSphere 规则、算法插件和依赖 DistSQL 的插件工作流不适用。
-- 返回的是数据库自身元数据，不包含 ShardingSphere 逻辑规则视图。
-- 客户端不能假设直接连接数据库和连接 Proxy 时暴露的资源、工具行为完全一致。
-
-## 资源
-
-资源用于提供运行时状态、数据库列表、表结构、列信息或工作流计划等上下文。
-客户端会按任务需要读取对应资源。
-
-| 资源 URI 或模板 | 用途 | 自然语言示例 |
-| --- | --- | --- |
-| `shardingsphere://capabilities` | 查看 MCP Server 的可用任务和副作用提示。 | “这个 MCP
Server 支持哪些数据库任务？” |
-| `shardingsphere://runtime` | 查看当前传输方式、运行状态和已配置运行时数据库摘要。 | “当前 MCP Server
配置了哪些逻辑库？” |
-| `shardingsphere://databases` | 列出当前 MCP Server 可以访问的运行时数据库；连接 Proxy 时对应
ShardingSphere 逻辑库。 | “列出可以访问的逻辑库。” |
-| `shardingsphere://databases/{database}` | 读取一个运行时数据库的详情和元数据摘要。 | “查看
`<logic-database>` 的元数据摘要。” |
-| `shardingsphere://databases/{database}/capabilities` | 读取一个运行时数据库的
SQL、事务、schema 和元数据对象能力。 | “`<logic-database>` 支持哪些 SQL 和元数据能力？” |
-| `shardingsphere://databases/{database}/schemas` | 列出一个运行时数据库中的 schema 或
namespace。 | “查看 `<logic-database>` 中有哪些 schema。” |
-| `shardingsphere://databases/{database}/schemas/{schema}` | 读取一个 schema 或
namespace 的详情。 | “查看 `<schema-name>` 的详情。” |
-| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | 列出一个
schema 中的 sequence。 | “列出 `<schema-name>` 中的 sequence。” |
-|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
读取一个 sequence 的详情。 | “查看 `<sequence-name>` 的详情。” |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables` | 列出一个
schema 中的表。 | “列出 `<schema-name>` 中的表。” |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
读取一个表的详情。 | “查看 `<table-name>` 的表结构。” |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| 列出一个表的列。 | “查看 `<table-name>` 有哪些列。” |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| 读取一个表列的详情。 | “查看 `<column-name>` 的类型和约束。” |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| 列出一个表的索引。 | “查看 `<table-name>` 的索引。” |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| 读取一个表索引的详情。 | “查看 `<index-name>` 包含哪些列。” |
-| `shardingsphere://databases/{database}/schemas/{schema}/views` | 列出一个 schema
中的视图。 | “列出 `<schema-name>` 中的视图。” |
-| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` |
读取一个视图的详情。 | “查看 `<view-name>` 的定义摘要。” |
-|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
列出一个视图的列。 | “查看 `<view-name>` 有哪些列。” |
-|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| 读取一个视图列的详情。 | “查看视图列 `<column-name>` 的详情。” |
-| `shardingsphere://workflows/{plan_id}` | 查看当前治理变更计划、补问信息、变更产物和下一步动作。 |
“查看刚才的规则变更计划和下一步动作。” |
-
-插件提供的资源、工具、提示和补全目标在对应插件页面说明。
-
-## 工具
-
-工具用于执行动作，例如搜索元数据、执行 SQL，或处理插件工作流阶段。
-有副作用的动作应先预览或审查。
-
-| 工具 | 用途 | 自然语言示例 | 副作用 |
+- 不提供 ShardingSphere 规则状态。
+- 不适用于数据加密、数据脱敏等依赖 ShardingSphere 规则的功能插件。
+- 返回的是目标数据库自身元数据，不代表 ShardingSphere 逻辑规则视图。
+
+## 元数据查看
+
+| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
+| --- | --- | --- | --- |
+| 查看可访问的数据库 | “列出当前可以访问的逻辑库。” | Proxy 或普通数据库 | 确认数据库名称是否和配置一致。 |
+| 查看 schema 或 namespace | “查看 `<logic-database>` 中有哪些 schema。” | Proxy 或普通数据库
| 多 schema 数据库应先确认目标 schema。 |
+| 查看表或视图 | “列出 `<schema-name>` 中的表和视图。” | Proxy 或普通数据库 | Proxy 连接展示的是逻辑对象。 |
+| 查看列信息 | “查看 `<table-name>` 有哪些列，以及列类型是什么。” | Proxy 或普通数据库 | 列类型以连接目标可见元数据为准。
|
+| 查看索引 | “查看 `<table-name>` 的索引。” | Proxy 或普通数据库 | Proxy
连接下索引信息可能不同于底层物理库完整结构。 |
+| 查看 sequence | “列出 `<schema-name>` 中的 sequence。” | Proxy 或普通数据库 | 仅在连接目标支持
sequence 元数据时可用。 |
+
+## 元数据搜索
+
+| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
+| --- | --- | --- | --- |
+| 按名称搜索对象 | “查找名字包含 `order` 的表。” | Proxy 或普通数据库 | 适合不知道完整对象名时缩小范围。 |
+| 按对象类型搜索 | “查找名字包含 `user` 的表和视图。” | Proxy 或普通数据库 | 可以指定只看表、视图或列等对象。 |
+| 查找后继续查看详情 | “打开刚才找到的 `orders` 表，查看字段和索引。” | Proxy 或普通数据库 |
搜索结果可作为后续自然语言任务的上下文。 |
+
+## SQL 执行
+
+| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
+| --- | --- | --- | --- |
+| 执行只读查询 | “查询 `orders` 表前 10 行。” | Proxy 或普通数据库 | 适合查看样例数据或验证 SQL 结果。 |
+| 限制返回行数 | “查询 `orders` 表前 100 行，不要返回更多数据。” | Proxy 或普通数据库 | 避免返回过多数据。 |
+| 预览有副作用 SQL | “预览这条变更 SQL，先不要执行。” | Proxy 或普通数据库 | 执行前审查影响范围。 |
+| 确认执行有副作用 SQL | “确认执行刚才预览过的 SQL。” | Proxy 或普通数据库 | 需要确认已审查副作用。 |
+
+## ShardingSphere 规则变更
+
+| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
| --- | --- | --- | --- |
-| `database_gateway_search_metadata` | 按名称片段和对象类型搜索运行时数据库元数据，并返回后续资源读取提示。 |
“查找名字包含 `order` 的表。” | 无。 |
-| `database_gateway_validate_proxy_connectivity` |
校验运行时数据库配置是否可用，用于接入失败时定位连接问题。 | “检查 `logic_db` 为什么无法访问。” | 无。 |
-| `database_gateway_execute_query` | 执行一个已判定为查询类的 `SELECT` 或 `EXPLAIN
ANALYZE`。 | “查询 `orders` 表前 10 行。” | 无；拒绝 DML、DDL、DCL、事务控制、savepoint 和其他有副作用
SQL。 |
-| `database_gateway_execute_update` | 预览或执行一个可能修改数据、元数据、规则或事务状态的 SQL。 |
“预览这条变更 SQL，先不要执行。” | 有；应先预览并确认。 |
-| `database_gateway_apply_workflow` | 预览、执行或导出功能插件生成的治理变更计划。 | “先预览刚才的加密规则计划。”
| 取决于执行方式；预览和人工执行包不修改运行时状态。 |
-| `database_gateway_validate_workflow` | 插件工作流执行后，根据可见元数据和生成产物校验结果。 |
“校验刚才的脱敏规则是否生效。” | 无。 |
-
-插件工具在对应插件页面说明。
-
-## 提示
-
-提示用于任务引导，例如先读取哪些信息、如何处理 SQL 执行边界、如何从失败中恢复。
-用户通常不需要直接使用提示。
-
-| 提示 | 用途 |
-| --- | --- |
-| `inspect_metadata` | 引导元数据查看任务先读取数据库元数据，再选择搜索工具或详情资源。 |
-| `safe_sql_execution` | 引导 SQL 执行任务区分只读查询和有副作用 SQL。 |
-| `recover_workflow` | 引导插件工作流失败后恢复或重新规划。 |
-
-插件提示在对应插件页面说明。
-
-## 补全目标
-
-补全目标用于帮助客户端补齐数据库、schema、表、列等名称。
-例如用户只输入部分对象名时，客户端可以给出候选值。
-
-### 资源补全目标
-
-| 目标 | 补全参数 |
-| --- | --- |
-| `shardingsphere://databases/{database}` | `database` |
-| `shardingsphere://databases/{database}/schemas` | `database` |
-| `shardingsphere://databases/{database}/schemas/{schema}` |
`database`、`schema` |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables` |
`database`、`schema` |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
`database`、`schema`、`table` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| `database`、`schema`、`table` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| `database`、`schema`、`table`、`column` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| `database`、`schema`、`table` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| `database`、`schema`、`table`、`index` |
-| `shardingsphere://databases/{database}/schemas/{schema}/sequences` |
`database`、`schema` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
`database`、`schema`、`sequence` |
-| `shardingsphere://workflows/{plan_id}` | `plan_id` |
-
-### 提示补全目标
-
-| 目标 | 补全参数 |
-| --- | --- |
-| `inspect_metadata` | `database`、`schema` |
-| `safe_sql_execution` | `database`、`schema` |
-| `recover_workflow` | `plan_id` |
-
-插件提示补全目标在对应插件页面说明。
+| 检查已有规则 | “检查 `orders.phone` 当前是否已有脱敏规则。” | 仅 Proxy | 规则状态来自
ShardingSphere-Proxy。 |
+| 规划数据加密规则 | “为 `orders.status` 规划可逆加密，先预览不要执行。” | 仅 Proxy |
审查生成的规则变更、物理列和索引建议。 |
+| 规划数据脱敏规则 | “为 `orders.phone` 规划手机号脱敏，保留前 3 后 4，先预览不要执行。” | 仅 Proxy |
审查脱敏算法、参数和影响范围。 |
+| 调整规则计划 | “把刚才的计划改成使用 AES 算法。” | 仅 Proxy | 修改后应重新预览。 |
+| 执行规则变更 | “确认执行刚才的规则变更计划。” | 仅 Proxy | 有副作用，执行前应完成审查。 |
+| 校验规则变更 | “校验刚才的脱敏规则是否生效。” | 仅 Proxy | 查看规则状态、元数据和 SQL 可执行性。 |
+
+数据加密和数据脱敏的详细用法见[数据加密](../features/encrypt/)和[数据脱敏](../features/mask/)。
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 107a36a060d..2fff928d7e4 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
@@ -3,132 +3,83 @@ title = "Capability Catalog"
weight = 2
+++
-This page explains the information that ShardingSphere-MCP can read, the
actions it can perform, and the usage boundaries for different connection
targets from the perspective of AI application developers and integrators.
-AI applications that integrate MCP discover the capabilities currently
available from the MCP Server. Users usually only need to describe the database
task they want to complete in the AI application.
+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/).
-## Capability discovery
+## Connection Targets
-Capability discovery is the process by which an MCP client or an AI
application that integrates MCP reads the capabilities available from
ShardingSphere-MCP.
-When using an existing client, users usually only describe database tasks. AI
application developers need to read tools, resources, resource templates, and
prompts after the application establishes an MCP connection, then make those
capabilities available to the model or application orchestration logic.
+### Connecting to ShardingSphere-Proxy
-| Entry | Type | Returned content | Usage scenario |
-| --- | --- | --- | --- |
-| `tools/list`, `resources/list`, `resources/templates/list`, `prompts/list` |
MCP protocol capabilities | Tools, resources, resource templates, and prompts
exposed by the current MCP Server. | Build the callable capability catalog for
an AI application and select available context or actions by task. |
-| `shardingsphere://capabilities` | ShardingSphere service capability |
Runtime databases, connection targets, feature plugins, and side-effect
boundaries. | Determine whether the current MCP Server can be used for metadata
inspection, SQL execution, or governance changes. |
-| `shardingsphere://databases/{database}/capabilities` | Database capability |
SQL, transaction, schema, and metadata-object capabilities of the specified
runtime database. | Determine available operations and limits for a specific
database. |
+Use this mode to inspect ShardingSphere logical database structure, read rule
state, run controlled SQL, or create reviewable rule change plans.
-Capability discovery represents what the current MCP Server actually makes
available. Whether a capability is actually useful still depends on whether
`runtimeDatabases` connects to ShardingSphere-Proxy or to a regular database.
-Clients select available capabilities according to the connection target.
+Available tasks include:
-### Connecting to ShardingSphere-Proxy
+- Inspecting logical databases, schemas, tables, views, columns, indexes, and
sequences.
+- Searching metadata objects such as tables, views, columns, and indexes.
+- Running read-only SQL queries.
+- Previewing SQL that may change data, metadata, or rules.
+- Planning, reviewing, applying, and validating data encryption or data
masking rule changes.
+
+Usage boundaries:
-Use this mode to inspect ShardingSphere logical database structure, read
governance rule state, execute controlled SQL, or create reviewable governance
change plans through feature plugins.
-In this mode, logical metadata, logical SQL, DistSQL, rule state, algorithm
plugins, and plugin workflows can be used through MCP capabilities.
+- Users see logical metadata exposed by Proxy. It is not equivalent to the
complete catalog of every physical database.
+- Tasks that depend on ShardingSphere rules, algorithms, or rule change
statements apply only to Proxy connections.
+- Side-effecting tasks should be previewed or planned first, then reviewed
before execution.
-Usage limits:
+### Connecting Directly to a Database
-- Physical metadata follows what Proxy exposes and should not be treated as
the complete catalog of every underlying physical database.
-- Capabilities that depend on ShardingSphere rules, algorithms, or DistSQL
apply only to Proxy connections.
-- Planning capabilities create reviewable plans. Business impact still needs
to be reviewed before execution.
+Use this mode when ShardingSphere-MCP acts as a controlled access entry for a
regular database, including metadata inspection, object search, and restricted
SQL execution.
-### Connecting directly to a database
+Available tasks include:
-Use this mode when the MCP Server should act as a controlled access path to a
regular database for reading JDBC metadata, searching objects, assisting query
generation, or executing restricted SQL.
-In this mode, general database metadata and SQL tools are available.
+- Inspecting databases, schemas, tables, views, columns, indexes, and
sequences.
+- Searching metadata objects.
+- Running read-only SQL queries.
+- Previewing or executing ordinary DML, DDL, and DCL after explicit
authorization.
-Usage limits:
+Usage boundaries:
-- ShardingSphere rules, algorithm plugins, and plugin workflows that depend on
DistSQL do not apply.
-- Returned metadata is database-native metadata and does not include
ShardingSphere logical rule views.
-- Clients must not assume that resources and tools behave exactly the same for
direct database connections and Proxy connections.
+- ShardingSphere rule state is not available.
+- Feature plugins that depend on ShardingSphere rules, such as data encryption
and data masking, do not apply.
+- Returned metadata comes from the target database itself and does not
represent a ShardingSphere logical rule view.
-## Resources
+## Metadata Inspection
-Resources provide context such as runtime status, database lists, table
structure, column information, or workflow plans.
-Clients read the corresponding resources as needed for the task.
+| Task | Natural language example | Connection target | User focus |
+| --- | --- | --- | --- |
+| List accessible databases | "List the logical databases that can be
accessed." | Proxy or regular database | Confirm that database names match the
configuration. |
+| Inspect schemas or namespaces | "Show schemas in `<logic-database>`." |
Proxy or regular database | For multi-schema databases, confirm the target
schema first. |
+| Inspect tables or views | "List tables and views in `<schema-name>`." |
Proxy or regular database | Proxy connections show logical objects. |
+| Inspect columns | "Show columns and column types for `<table-name>`." |
Proxy or regular database | Column types follow metadata visible from the
connection target. |
+| Inspect indexes | "Show indexes for `<table-name>`." | Proxy or regular
database | With Proxy connections, index information may differ from the full
physical database structure. |
+| Inspect sequences | "List sequences in `<schema-name>`." | Proxy or regular
database | Available only when the connection target exposes sequence metadata.
|
+
+## Metadata Search
-| Resource URI or template | Purpose | Natural language example |
-| --- | --- | --- |
-| `shardingsphere://capabilities` | Reads available tasks and side-effect
notes for the MCP Server. | "Which database tasks does this MCP Server
support?" |
-| `shardingsphere://runtime` | Reads the current transport, runtime status,
and configured runtime database summary. | "Which logical databases are
configured on the MCP Server?" |
-| `shardingsphere://databases` | Lists runtime databases reachable by the
current MCP Server. When connected to Proxy, they correspond to ShardingSphere
logical databases. | "List the logical databases that can be accessed." |
-| `shardingsphere://databases/{database}` | Reads one runtime database and its
metadata summary. | "Show the metadata summary for `<logic-database>`." |
-| `shardingsphere://databases/{database}/capabilities` | Reads SQL,
transaction, schema, and metadata-object capabilities for one runtime database.
| "Which SQL and metadata capabilities does `<logic-database>` support?" |
-| `shardingsphere://databases/{database}/schemas` | Lists schemas or
namespaces inside one runtime database. | "Show schemas in `<logic-database>`."
|
-| `shardingsphere://databases/{database}/schemas/{schema}` | Reads one schema
or namespace. | "Show details for `<schema-name>`." |
-| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | Lists
sequences in one schema. | "List sequences in `<schema-name>`." |
-|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
Reads one sequence. | "Show details for `<sequence-name>`." |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables` | Lists
tables in one schema. | "List tables in `<schema-name>`." |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
Reads one table. | "Inspect the structure of `<table-name>`." |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| Lists columns for one table. | "Show columns for `<table-name>`." |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| Reads one table column. | "Show the type and constraints of
`<column-name>`." |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| Lists indexes for one table. | "Show indexes for `<table-name>`." |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| Reads one table index. | "Show which columns `<index-name>` contains." |
-| `shardingsphere://databases/{database}/schemas/{schema}/views` | Lists views
in one schema. | "List views in `<schema-name>`." |
-| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` |
Reads one view. | "Show a summary of `<view-name>`." |
-|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
Lists columns for one view. | "Show columns for `<view-name>`." |
-|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| Reads one view column. | "Show details for view column `<column-name>`." |
-| `shardingsphere://workflows/{plan_id}` | Reads the current governance change
plan, clarification questions, artifacts, and next actions. | "Show the
previous rule change plan and next action." |
+| Task | Natural language example | Connection target | User focus |
+| --- | --- | --- | --- |
+| Search objects by name | "Find tables whose names contain `order`." | Proxy
or regular database | Useful when the full object name is unknown. |
+| 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. |
-Plugin resources, tools, prompts, and completion targets are documented on the
corresponding plugin pages.
+## SQL Execution
-## Tools
+| 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. |
+| 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. |
-Tools execute actions, such as searching metadata, executing SQL, or handling
plugin workflow phases.
-Actions with side effects should be previewed or reviewed first.
+## ShardingSphere Rule Changes
-| Tool | Purpose | Natural language example | Side effects |
+| Task | Natural language example | Connection target | User focus |
| --- | --- | --- | --- |
-| `database_gateway_search_metadata` | Search runtime database metadata by
name fragment and object type, and return resource hints for follow-up reads. |
"Find tables whose names contain `order`." | None. |
-| `database_gateway_validate_proxy_connectivity` | Validate whether the
runtime database configuration is usable, for diagnosing connection issues
during integration. | "Check why `logic_db` cannot be accessed." | None. |
-| `database_gateway_execute_query` | Execute exactly one classifier-approved
`SELECT` or `EXPLAIN ANALYZE` statement. | "Query the first 10 rows from
`orders`." | None; rejects DML, DDL, DCL, transaction control, savepoints, and
other side-effecting SQL. |
-| `database_gateway_execute_update` | Preview or execute one SQL statement
that may mutate data, metadata, rules, or transaction state. | "Preview this
change SQL without executing it." | Yes; preview and confirmation are
recommended first. |
-| `database_gateway_apply_workflow` | Preview, execute, or export a governance
change plan created by a feature plugin. | "Preview the previous encryption
rule plan first." | Depends on the execution choice; preview and manual
packages do not change runtime state. |
-| `database_gateway_validate_workflow` | After plugin workflow execution,
validate the result against visible metadata and generated artifacts. |
"Validate whether the previous masking rule has taken effect." | None. |
-
-Plugin tools are documented on the corresponding plugin pages.
-
-## Prompts
-
-Prompts provide task guidance, such as which information to read first, how to
handle SQL execution boundaries, or how to recover from failure.
-Users usually do not use prompts directly.
-
-| Prompt | Purpose |
-| --- | --- |
-| `inspect_metadata` | Guides metadata inspection tasks to read database
metadata before choosing a search tool or detail resource. |
-| `safe_sql_execution` | Guides SQL execution tasks to distinguish read-only
queries from side-effecting SQL. |
-| `recover_workflow` | Guides recovery or re-planning after plugin workflow
failure. |
-
-Plugin prompts are documented on the corresponding plugin pages.
-
-## Completion targets
-
-Completion targets help clients complete database, schema, table, and column
names.
-For example, when a user provides only part of an object name, the client can
provide candidates.
-
-### Resource completion targets
-
-| Target | Completed arguments |
-| --- | --- |
-| `shardingsphere://databases/{database}` | `database` |
-| `shardingsphere://databases/{database}/schemas` | `database` |
-| `shardingsphere://databases/{database}/schemas/{schema}` | `database`,
`schema` |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables` |
`database`, `schema` |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
`database`, `schema`, `table` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| `database`, `schema`, `table` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| `database`, `schema`, `table`, `column` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| `database`, `schema`, `table` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| `database`, `schema`, `table`, `index` |
-| `shardingsphere://databases/{database}/schemas/{schema}/sequences` |
`database`, `schema` |
-|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
`database`, `schema`, `sequence` |
-| `shardingsphere://workflows/{plan_id}` | `plan_id` |
-
-### Prompt completion targets
-
-| Target | Completed arguments |
-| --- | --- |
-| `inspect_metadata` | `database`, `schema` |
-| `safe_sql_execution` | `database`, `schema` |
-| `recover_workflow` | `plan_id` |
-
-Plugin prompt completion targets are documented on the corresponding plugin
pages.
+| Check existing rules | "Check whether `orders.phone` already has a masking
rule." | Proxy only | Rule state comes from ShardingSphere-Proxy. |
+| Plan a data encryption rule | "Plan reversible encryption for
`orders.status` and preview it without execution." | Proxy only | Review the
rule change, physical columns, and index suggestions. |
+| Plan a data masking rule | "Plan phone-number masking for `orders.phone`,
keep the first 3 and last 4 characters, and preview it without execution." |
Proxy only | Review the masking algorithm, properties, and impact scope. |
+| Adjust a rule plan | "Change the previous plan to use AES." | Proxy only |
Preview again after changing the plan. |
+| Apply a rule change | "Confirm and execute the previous rule change plan." |
Proxy only | Side-effecting; review must be completed before execution. |
+| Validate a rule change | "Validate whether the previous masking rule has
taken effect." | Proxy only | Check rule state, metadata, and SQL
executability. |
+
+For detailed usage, see [Data Encryption](../features/encrypt/) and [Data
Masking](../features/mask/).
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 427da7dedd3..b44dbf3a241 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
@@ -3,26 +3,26 @@ title = "客户端集成"
weight = 4
+++
-客户端集成用于把 ShardingSphere-MCP 接入支持 MCP 的桌面客户端、IDE 插件、Agent 平台或自研应用。
-配置完成后，用户可以在客户端中通过自然语言查看元数据、执行受控 SQL 查询，或发起数据库治理任务。
+客户端集成用于把 ShardingSphere-MCP 接入支持 MCP 的 AI 应用、IDE 插件或 Agent 平台。
+配置完成后，用户可以在应用中通过自然语言查看元数据、执行受控 SQL 查询，或发起数据库治理任务。
适合使用客户端集成的场景：
-- 在支持 MCP 的客户端、IDE 插件或 Agent 平台中接入 ShardingSphere。
+- 在 AI 应用、IDE 插件或 Agent 平台中接入 ShardingSphere。
- 基于 ShardingSphere 元数据完成查询辅助、结构理解、问题诊断或治理规划。
- 为团队提供统一的受控数据库访问通路。
-- 为自研 Agent 平台集成 ShardingSphere 元数据、安全 SQL 和治理插件能力。
+- 为 AI 应用集成 ShardingSphere 元数据、受控 SQL 和规则变更能力。
可完成的任务和使用边界见[能力清单](../capabilities/)。
## 选择传输方式
-- HTTP 适合 MCP Server 独立启动，客户端通过固定端点访问的场景。
-- STDIO 适合本地客户端拉起 ShardingSphere-MCP 子进程的场景。
+- HTTP 适合 MCP Server 独立启动，AI 应用通过固定端点访问的场景。
+- STDIO 适合本地 AI 应用拉起 ShardingSphere-MCP 子进程的场景。
## HTTP 配置
-将下面片段写入 MCP 客户端的 server 配置；具体文件位置由客户端决定。
+将下面片段写入 AI 应用的 MCP Server 配置；具体文件位置由应用决定。
`url` 指向已经启动的 HTTP MCP Server。
```json
@@ -35,11 +35,11 @@ weight = 4
}
```
-不同客户端的配置文件位置和字段名称可能不同，请以客户端自身文档为准。
+不同 AI 应用的配置文件位置和字段名称可能不同，请以应用自身文档为准。
## STDIO 配置
-将下面片段写入 MCP 客户端的 server 配置；具体文件位置由客户端决定。
+将下面片段写入 AI 应用的 MCP Server 配置；具体文件位置由应用决定。
`command` 指向发行包内的启动脚本，`args` 指向 STDIO 配置文件。
```json
@@ -53,17 +53,16 @@ weight = 4
}
```
-STDIO 模式适合由本地 MCP 客户端拉起 ShardingSphere-MCP 子进程。
将 `/path/to/apache-shardingsphere-mcp` 替换为实际发行包目录。
STDIO 模式下：
- 诊断日志写到 stderr 或 `logs/mcp.log`。
-- 客户端配置中的 `command` 和 `args` 应指向发行包内的启动脚本和 STDIO 配置文件。
+- 配置中的 `command` 和 `args` 应指向发行包内的启动脚本和 STDIO 配置文件。
## 集成后的使用方式
-客户端完成 MCP Server 配置后，用户在客户端对话中直接描述任务。
+AI 应用完成 MCP Server 配置后，用户在对话中直接描述任务。
示例：
@@ -72,5 +71,5 @@ STDIO 模式下：
- 执行一条只读查询，并限制返回 100 行。
- 规划一个数据加密或数据脱敏规则，先预览不要执行。
-如果客户端提供工具调用审批界面，应重点审查 SQL 执行、规则变更、插件工作流执行等有副作用的调用。
-自研客户端或协议调试场景，可结合[能力清单](../capabilities/)确认可用能力。
+涉及 SQL 执行、规则变更或规则变更计划执行时，应先审查预览内容，再确认执行。
+自研集成或协议调试场景见[开发者附录](../developer-appendix/)。
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 87a8062f7e8..a17ca4744ff 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
@@ -3,26 +3,26 @@ title = "Client Integration"
weight = 4
+++
-Client integration connects ShardingSphere-MCP to MCP-capable desktop clients,
IDE extensions, agent platforms, or custom applications.
-After configuration, users can inspect metadata, run controlled SQL queries,
or start database governance tasks through natural language in the client.
+Client integration connects ShardingSphere-MCP to MCP-capable AI applications,
IDE extensions, or agent platforms.
+After configuration, users can inspect metadata, run controlled SQL queries,
or start database governance tasks through natural language in the application.
Use client integration when:
-- An MCP-capable client, IDE extension, or agent platform needs to connect to
ShardingSphere.
+- An AI application, IDE extension, or agent platform needs to connect to
ShardingSphere.
- ShardingSphere metadata should be used for query assistance, structure
understanding, diagnostics, or governance planning.
- A team needs a unified controlled database access path.
-- A custom agent platform needs ShardingSphere metadata, safe SQL, and
governance plugin capabilities.
+- An AI application needs ShardingSphere metadata, controlled SQL, and rule
change capabilities.
See [Capability Catalog](../capabilities/) for supported tasks and usage
boundaries.
-## Choose a transport
+## Choose a Transport
-- HTTP is suitable when the MCP Server is started independently and clients
use a fixed endpoint.
-- STDIO is suitable when a local client starts ShardingSphere-MCP as a child
process.
+- HTTP 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
+## HTTP Configuration
-Add the following snippet to the MCP client's server configuration. The exact
file location depends on the client.
+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
@@ -35,11 +35,11 @@ Add the following snippet to the MCP client's server
configuration. The exact fi
}
```
-The exact configuration file location and field names may differ by client.
Follow the client's own documentation.
+Configuration file locations and field names may differ between AI
applications. Follow the documentation of the application you use.
-## STDIO configuration
+## STDIO Configuration
-Add the following snippet to the MCP client's server configuration. The exact
file location depends on the client.
+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
@@ -53,17 +53,16 @@ Add the following snippet to the MCP client's server
configuration. The exact fi
}
```
-STDIO mode is for local MCP clients that launch ShardingSphere-MCP as a child
process.
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 client configuration should point to the
packaged startup script and STDIO config file.
+- `command` and `args` in the configuration should point to the packaged
startup script and STDIO config file.
-## Using the integration
+## Using the Integration
-After the client is configured with the MCP Server, users describe tasks
directly in the client conversation.
+After the AI application is configured with the MCP Server, users describe
tasks directly in the conversation.
Examples:
@@ -72,5 +71,5 @@ Examples:
- Run a read-only query and limit the result to 100 rows.
- Plan a data encryption or data masking rule and preview it without execution.
-If the client provides a tool approval UI, pay special attention to
side-effecting calls such as SQL execution, rule changes, and plugin workflow
execution.
-For custom clients or protocol debugging, use the [Capability
Catalog](../capabilities/) to confirm available capabilities.
+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/).
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 c2eaadc5505..af16c453c1c 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
@@ -39,7 +39,7 @@ transport:
## 数据库配置
`runtimeDatabases` 定义 MCP Server 可以连接并对外暴露的数据库。
-每个条目的 key 是 MCP 调用中使用的数据库名称，通常对应 ShardingSphere-Proxy 暴露的逻辑库。
+每个条目的 key 是用户在自然语言任务中引用的数据库名称，通常对应 ShardingSphere-Proxy 暴露的逻辑库。
```yaml
runtimeDatabases:
@@ -66,8 +66,8 @@ runtimeDatabases:
注意事项：
-- 连接 ShardingSphere-Proxy 时，MCP 资源暴露的是 ShardingSphere 逻辑库，不是底层物理存储单元。
-- 连接真实数据库时，MCP 资源反映该 JDBC 目标的元数据，不代表 ShardingSphere 规则状态。
+- 连接 ShardingSphere-Proxy 时，用户看到的是 ShardingSphere 逻辑库，不是底层物理存储单元。
+- 连接真实数据库时，用户看到的是该 JDBC 目标的元数据，不代表 ShardingSphere 规则状态。
- Schema、table、view、index 和 sequence 等元数据依赖目标数据库的 JDBC 元数据；Proxy
和真实数据库的可见结果可能不同。
- 如果目标 JDBC 驱动没有随发行包提供，请把驱动 jar 放入 `plugins/`。
@@ -82,14 +82,14 @@ runtimeDatabases:
- 读取 ShardingSphere 逻辑库、逻辑表和逻辑列元数据。
- 查询 Proxy 可见的加密、脱敏算法插件。
- 查询、规划、应用和校验加密或脱敏规则。
-- 通过 Proxy 执行逻辑 SQL 和工作流生成的 DistSQL。
+- 通过 Proxy 执行逻辑 SQL 和规则变更生成的待执行语句。
该模式受 Proxy 能力限制：
- JDBC 元数据、`information_schema`、索引、sequence 和列类型信息以 Proxy
暴露结果为准，不等同于完整底层物理库元数据。
- 物理列、物理索引和多存储节点一致性不作为 MCP 自动确认的稳定契约。
-- 可用 DistSQL、规则类型和算法插件取决于 Proxy 版本、已安装插件和当前账号权限。
-- 物理 DDL 产物应先审查；只有 Proxy 能安全路由并执行时才适合自动应用。
+- 可用规则变更语句、规则类型和算法插件取决于 Proxy 版本、已安装插件和当前账号权限。
+- 物理变更语句应先审查；只有 Proxy 能安全路由并执行时才适合自动应用。
### 连接真实数据库
@@ -103,7 +103,7 @@ runtimeDatabases:
- 不能发现 Proxy 中可见的加密或脱敏算法插件。
- 不能查询、规划、应用或校验 ShardingSphere 加密、脱敏规则。
-- 不能使用依赖 DistSQL 的工作流能力；真实数据库通常不识别 ShardingSphere DistSQL。
+- 不能使用依赖 ShardingSphere 规则变更语句的能力；真实数据库通常不识别 ShardingSphere 规则变更语句。
## 插件目录
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 84bd8a08cf7..933b7fc27ae 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
@@ -38,8 +38,8 @@ transport:
## Database configuration
-`runtimeDatabases` defines the databases that the MCP Server can connect to
and expose through MCP.
-Each entry key is the database name used in MCP calls. It usually maps to a
logical database exposed by ShardingSphere-Proxy.
+`runtimeDatabases` defines the databases that the MCP Server can connect to
and expose to users.
+Each entry key is the database name that users reference in natural-language
tasks. It usually maps to a logical database exposed by ShardingSphere-Proxy.
```yaml
runtimeDatabases:
@@ -66,8 +66,8 @@ Legend:
Notes:
-- When the target is ShardingSphere-Proxy, MCP resources expose ShardingSphere
logical databases, not physical storage units.
-- When the target is a physical database, MCP resources reflect metadata from
that JDBC target and do not represent ShardingSphere rule state.
+- When the target is ShardingSphere-Proxy, users see ShardingSphere logical
databases, not physical storage units.
+- When the target is a physical database, users see metadata from that JDBC
target, not ShardingSphere rule state.
- 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/`.
@@ -82,14 +82,14 @@ This is the recommended target when using ShardingSphere
rule capabilities. In t
- 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 workflow-generated DistSQL through Proxy.
+- 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 DistSQL statements, rule types, and algorithm plugins depend on
the Proxy version, installed plugins, and current account privileges.
-- Physical DDL artifacts should be reviewed first. They are suitable for
automatic execution only when Proxy can route and execute them safely.
+- 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.
### Connecting to a physical database
@@ -103,7 +103,7 @@ This mode does not provide ShardingSphere rule capabilities:
- 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 workflows that depend on DistSQL. Physical databases usually
do not understand ShardingSphere DistSQL.
+- It cannot use capabilities that depend on ShardingSphere rule change
statements. Physical databases usually do not understand those statements.
## Plugin directory
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 13e0fde8938..0889b052b18 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
@@ -57,7 +57,7 @@ docker run --rm -p 18088:18088 \
根据目标能力边界配置 `runtimeDatabases`：
-- 使用 ShardingSphere 规则能力或功能插件工作流时，指向用户已准备好的 ShardingSphere-Proxy 逻辑库。
+- 使用 ShardingSphere 规则能力或规则变更流程时，指向用户已准备好的 ShardingSphere-Proxy 逻辑库。
- 仅使用通用 JDBC 元数据、元数据搜索和受控 SQL 能力时，可以指向任意可连接的 JDBC 数据库。
## 安全部署建议
@@ -80,4 +80,4 @@ HTTP 绑定建议：
## 日志
- HTTP 模式：查看启动终端和 `logs/mcp.log`。
-- STDIO 模式：stdout 专用于 MCP 协议帧，诊断信息查看 stderr 或 `logs/mcp.log`。
+- STDIO 模式：不要把标准输出作为日志查看入口，诊断信息查看 stderr 或 `logs/mcp.log`。
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 7191fb50140..a410c4d32a5 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
@@ -57,7 +57,7 @@ docker run --rm -p 18088:18088 \
Configure `runtimeDatabases` according to the target capability boundary:
-- Point it to a ShardingSphere-Proxy logical database when using
ShardingSphere rule capabilities or feature plugin workflows.
+- Point it to a ShardingSphere-Proxy logical database when using
ShardingSphere rule capabilities or the rule change flow.
- Point it to any reachable JDBC database only for general JDBC metadata,
metadata search, and controlled SQL capabilities.
## Secure deployment
@@ -80,4 +80,4 @@ HTTP binding recommendations:
## Logs
- HTTP mode: inspect the startup terminal and `logs/mcp.log`.
-- STDIO mode: stdout is reserved for MCP protocol frames; inspect stderr or
`logs/mcp.log` for diagnostics.
+- STDIO mode: do not use stdout as a log inspection entry; inspect stderr or
`logs/mcp.log` for diagnostics.
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
new file mode 100644
index 00000000000..899b1b4ee5b
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
@@ -0,0 +1,139 @@
++++
+title = "开发者附录"
+weight = 9
++++
+
+本页面向需要自研 MCP 集成、调试协议请求或定位客户端适配问题的开发者。
+普通用户通常不需要阅读本页，可直接参考[快速开始](../quick-start/)、[客户端集成](../client-integration/)和[能力清单](../capabilities/)。
+
+## 协议能力发现
+
+| 入口 | 返回内容 | 适用场景 |
+| --- | --- | --- |
+| `tools/list` | 当前 MCP Server 暴露的工具。 | 自研客户端构建可调用动作清单。 |
+| `resources/list` | 当前 MCP Server 暴露的静态资源。 | 自研客户端读取固定上下文。 |
+| `resources/templates/list` | 当前 MCP Server 暴露的资源模板。 |
自研客户端按数据库、schema、表等参数读取上下文。 |
+| `prompts/list` | 当前 MCP Server 暴露的提示。 | 自研客户端读取任务引导模板。 |
+| `completion/complete` | 指定参数的补全候选值。 | 自研客户端为数据库、schema、表、列等名称提供补全。 |
+| `shardingsphere://capabilities` | 运行时数据库、连接目标、功能插件和副作用边界。 | 判断当前 MCP Server
可用于哪些数据库任务。 |
+| `shardingsphere://databases/{database}/capabilities` | 指定运行时数据库的
SQL、事务、schema 和元数据对象能力。 | 判断某个数据库的可用操作和限制。 |
+
+## 资源
+
+| 资源 URI 或模板 | 用途 |
+| --- | --- |
+| `shardingsphere://capabilities` | 查看 MCP Server 的可用任务和副作用提示。 |
+| `shardingsphere://runtime` | 查看当前传输方式、运行状态和已配置运行时数据库摘要。 |
+| `shardingsphere://databases` | 列出当前 MCP Server 可以访问的运行时数据库；连接 Proxy 时对应
ShardingSphere 逻辑库。 |
+| `shardingsphere://databases/{database}` | 读取一个运行时数据库的详情和元数据摘要。 |
+| `shardingsphere://databases/{database}/capabilities` | 读取一个运行时数据库的
SQL、事务、schema 和元数据对象能力。 |
+| `shardingsphere://databases/{database}/schemas` | 列出一个运行时数据库中的 schema 或
namespace。 |
+| `shardingsphere://databases/{database}/schemas/{schema}` | 读取一个 schema 或
namespace 的详情。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | 列出一个
schema 中的 sequence。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
读取一个 sequence 的详情。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` | 列出一个
schema 中的表。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
读取一个表的详情。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| 列出一个表的列。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| 读取一个表列的详情。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| 列出一个表的索引。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| 读取一个表索引的详情。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/views` | 列出一个 schema
中的视图。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` |
读取一个视图的详情。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
列出一个视图的列。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| 读取一个视图列的详情。 |
+| `shardingsphere://workflows/{plan_id}` | 查看当前治理变更计划、补问信息、变更产物和下一步动作。 |
+
+## 工具
+
+| 工具 | 用途 | 副作用 |
+| --- | --- | --- |
+| `database_gateway_search_metadata` | 按名称片段和对象类型搜索运行时数据库元数据，并返回后续资源读取提示。 | 无。
|
+| `database_gateway_validate_proxy_connectivity` |
校验运行时数据库配置是否可用，用于接入失败时定位连接问题。 | 无。 |
+| `database_gateway_execute_query` | 执行一个已判定为查询类的 `SELECT` 或 `EXPLAIN
ANALYZE`。 | 无；拒绝 DML、DDL、DCL、事务控制、savepoint 和其他有副作用 SQL。 |
+| `database_gateway_execute_update` | 预览或执行一个可能修改数据、元数据、规则或事务状态的 SQL。 |
有；应先预览并确认。 |
+| `database_gateway_apply_workflow` | 预览、执行或导出功能插件生成的治理变更计划。 |
取决于执行方式；预览和人工执行包不修改运行时状态。 |
+| `database_gateway_validate_workflow` | 规则变更执行后，根据可见元数据和生成产物校验结果。 | 无。 |
+
+功能插件提供的额外工具见对应插件页面。
+
+## 提示
+
+| 提示 | 用途 |
+| --- | --- |
+| `inspect_metadata` | 引导元数据查看任务先读取数据库元数据，再选择搜索工具或详情资源。 |
+| `safe_sql_execution` | 引导 SQL 执行任务区分只读查询和有副作用 SQL。 |
+| `recover_workflow` | 引导规则变更失败后恢复或重新规划。 |
+
+## 补全目标
+
+### 资源补全目标
+
+| 目标 | 补全参数 |
+| --- | --- |
+| `shardingsphere://databases/{database}` | `database` |
+| `shardingsphere://databases/{database}/schemas` | `database` |
+| `shardingsphere://databases/{database}/schemas/{schema}` |
`database`、`schema` |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` |
`database`、`schema` |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
`database`、`schema`、`table` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| `database`、`schema`、`table` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| `database`、`schema`、`table`、`column` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| `database`、`schema`、`table` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| `database`、`schema`、`table`、`index` |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` |
`database`、`schema` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
`database`、`schema`、`sequence` |
+| `shardingsphere://workflows/{plan_id}` | `plan_id` |
+
+### 提示补全目标
+
+| 目标 | 补全参数 |
+| --- | --- |
+| `inspect_metadata` | `database`、`schema` |
+| `safe_sql_execution` | `database`、`schema` |
+| `recover_workflow` | `plan_id` |
+
+## HTTP 调试示例
+
+下面示例仅用于开发者调试 HTTP 传输，不是普通使用流程。
+
+初始化会话：
+
+```bash
+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":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
+```
+
+读取数据库列表：
+
+```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: <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"}}'
+```
+
+调用元数据搜索工具：
+
+```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: <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"]
+ }
+ }
+ }'
+```
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
new file mode 100644
index 00000000000..dc789d84b04
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
@@ -0,0 +1,139 @@
++++
+title = "Developer 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.
+
+## Protocol Capability Discovery
+
+| Entry | Returned content | Usage scenario |
+| --- | --- | --- |
+| `tools/list` | Tools exposed by the current MCP Server. | Build the callable
action catalog for a custom client. |
+| `resources/list` | Static resources exposed by the current MCP Server. |
Read fixed context from a custom client. |
+| `resources/templates/list` | Resource templates exposed by the current MCP
Server. | Read context by database, schema, table, and other parameters. |
+| `prompts/list` | Prompts exposed by the current MCP Server. | Read task
guidance templates from a custom client. |
+| `completion/complete` | Completion candidates for a specified parameter. |
Provide completion for database, schema, table, column, and other names. |
+| `shardingsphere://capabilities` | Runtime databases, connection targets,
feature plugins, and side-effect boundaries. | Determine which database tasks
the current MCP Server supports. |
+| `shardingsphere://databases/{database}/capabilities` | SQL, transaction,
schema, and metadata-object capabilities of the specified runtime database. |
Determine available operations and limits for one database. |
+
+## Resources
+
+| Resource URI or template | Purpose |
+| --- | --- |
+| `shardingsphere://capabilities` | Reads available tasks and side-effect
notes for the MCP Server. |
+| `shardingsphere://runtime` | Reads the current transport, runtime status,
and configured runtime database summary. |
+| `shardingsphere://databases` | Lists runtime databases reachable by the
current MCP Server. When connected to Proxy, they correspond to ShardingSphere
logical databases. |
+| `shardingsphere://databases/{database}` | Reads one runtime database and its
metadata summary. |
+| `shardingsphere://databases/{database}/capabilities` | Reads SQL,
transaction, schema, and metadata-object capabilities for one runtime database.
|
+| `shardingsphere://databases/{database}/schemas` | Lists schemas or
namespaces inside one runtime database. |
+| `shardingsphere://databases/{database}/schemas/{schema}` | Reads one schema
or namespace. |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | Lists
sequences in one schema. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
Reads one sequence. |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` | Lists
tables in one schema. |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
Reads one table. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| Lists columns for one table. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| Reads one table column. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| Lists indexes for one table. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| Reads one table index. |
+| `shardingsphere://databases/{database}/schemas/{schema}/views` | Lists views
in one schema. |
+| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` |
Reads one view. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
Lists columns for one view. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| Reads one view column. |
+| `shardingsphere://workflows/{plan_id}` | Reads the current governance change
plan, clarification questions, artifacts, and next actions. |
+
+## Tools
+
+| Tool | Purpose | Side effect |
+| --- | --- | --- |
+| `database_gateway_search_metadata` | Search runtime database metadata by
name fragment and object type, and return resource hints for follow-up reads. |
None. |
+| `database_gateway_validate_proxy_connectivity` | Validate whether runtime
database configuration is reachable, mainly for diagnosing integration
failures. | None. |
+| `database_gateway_execute_query` | Execute a statement classified as query,
such as `SELECT` or `EXPLAIN ANALYZE`. | None. Rejects DML, DDL, DCL,
transaction control, savepoint, and other side-effecting SQL. |
+| `database_gateway_execute_update` | Preview or execute SQL that may change
data, metadata, rules, or transaction state. | Yes. Preview and confirmation
are recommended. |
+| `database_gateway_apply_workflow` | Preview, execute, or export a governance
change plan created by a feature plugin. | Depends on the execution choice.
Preview and manual packages do not change runtime state. |
+| `database_gateway_validate_workflow` | After rule change execution, validate
the result against visible metadata and generated artifacts. | None. |
+
+Additional tools provided by feature plugins are documented on the
corresponding plugin pages.
+
+## Prompts
+
+| Prompt | Purpose |
+| --- | --- |
+| `inspect_metadata` | Guides metadata inspection tasks to read database
metadata before choosing a search tool or detail resource. |
+| `safe_sql_execution` | Guides SQL execution tasks to distinguish read-only
queries from side-effecting SQL. |
+| `recover_workflow` | Guides recovery or re-planning after rule change
failure. |
+
+## Completion Targets
+
+### Resource Completion Targets
+
+| Target | Completion parameters |
+| --- | --- |
+| `shardingsphere://databases/{database}` | `database` |
+| `shardingsphere://databases/{database}/schemas` | `database` |
+| `shardingsphere://databases/{database}/schemas/{schema}` | `database`,
`schema` |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` |
`database`, `schema` |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
`database`, `schema`, `table` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| `database`, `schema`, `table` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| `database`, `schema`, `table`, `column` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| `database`, `schema`, `table` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| `database`, `schema`, `table`, `index` |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` |
`database`, `schema` |
+|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
`database`, `schema`, `sequence` |
+| `shardingsphere://workflows/{plan_id}` | `plan_id` |
+
+### Prompt Completion Targets
+
+| Target | Completion parameters |
+| --- | --- |
+| `inspect_metadata` | `database`, `schema` |
+| `safe_sql_execution` | `database`, `schema` |
+| `recover_workflow` | `plan_id` |
+
+## HTTP Debugging Examples
+
+The following examples are for developers debugging HTTP transport. They are
not the normal usage flow.
+
+Initialize a session:
+
+```bash
+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":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
+```
+
+Read the database list:
+
+```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: <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"}}'
+```
+
+Call the metadata search tool:
+
+```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: <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"]
+ }
+ }
+ }'
+```
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 4ab54462193..f4a190809a0 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/_index.cn.md
@@ -5,12 +5,12 @@ chapter = true
+++
ShardingSphere-MCP 通过功能插件扩展领域能力。
-功能插件如果需要多步骤治理变更，会使用[插件工作流](plugin-workflow/)完成需求确认、预览、执行和校验。
+功能插件如果需要多步骤治理变更，会通过[规则变更流程](plugin-workflow/)完成需求确认、预览、执行和校验。
发行包默认包含以下官方 MCP 功能插件：
-- 数据加密：规划、执行和校验数据加密规则。
-- 数据脱敏：规划、执行和校验数据脱敏规则。
+- 数据加密：规划、审查、执行和校验数据加密规则。
+- 数据脱敏：规划、审查、执行和校验数据脱敏规则。
新增或第三方功能插件可以通过 `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 efc80d6aa8a..8eae02ee807 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/_index.en.md
@@ -5,12 +5,12 @@ chapter = true
+++
ShardingSphere-MCP extends domain capabilities through feature plugins.
-When a feature plugin needs a multi-step governance change, it uses [Plugin
Workflows](plugin-workflow/) for requirement confirmation, preview, apply, and
validation.
+When a feature plugin needs a multi-step governance change, it uses the [Rule
Change Flow](plugin-workflow/) for requirement confirmation, preview, apply,
and validation.
The packaged distribution includes these official MCP feature plugins:
-- Data Encryption: plan, apply, and validate data encryption rules.
-- Data Masking: plan, apply, and validate data masking rules.
+- 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.
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 ba7f6b07a1d..abf2a1e9aa6 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
@@ -10,7 +10,7 @@ weight = 2
- 当前版本只支持连接 ShardingSphere-Proxy 暴露的逻辑库。
- `runtimeDatabases` 应指向 Proxy 逻辑库，而不是底层物理存储库。
-- 直连真实数据库时，本功能不适用；真实数据库通常不识别 ShardingSphere 加密 DistSQL，也不能暴露 Proxy
中可见的加密算法插件和规则状态。
+- 直连真实数据库时，本功能不适用；真实数据库通常不识别 ShardingSphere 加密规则变更语句，也不能暴露 Proxy
中可见的加密算法插件和规则状态。
- 目标逻辑表和逻辑列应能通过 Proxy 暴露的 JDBC 元数据发现；这些信息不保证等同于底层物理库的完整元数据。
## 通过自然语言使用
@@ -24,7 +24,7 @@ weight = 2
- 使用 AES 算法继续刚才的计划，密钥通过受保护渠道提供。
- 确认并执行刚才的加密规则计划，然后校验结果。
-用户需要审查计划中的 DistSQL、DDL、索引建议和副作用范围，再批准有副作用的执行。
+用户需要审查计划中的待执行语句、物理列、索引建议和副作用范围，再批准有副作用的执行。
## 提出加密需求
@@ -42,17 +42,17 @@ weight = 2
## 创建、修改和删除规则
-| 操作 | 自然语言示例 | 计划内容 |
+| 操作 | 自然语言示例 | 需要审查的内容 |
| --- | --- | --- |
-| 创建 | “为 `orders.status` 规划可逆加密，需要支持等值查询，先预览不要执行。” | 生成新增规则
DistSQL，并在需要时生成物理派生列 DDL 和索引建议。 |
-| 修改 | “把刚才的加密计划改成 AES 算法，并继续预览。” | 生成保留同表其他列规则的修改规则 DistSQL，并按需更新 DDL 或索引建议。 |
-| 删除 | “删除 `orders.status` 的加密规则，先预览影响范围。” | 生成删除目标列规则的
DistSQL；如同表还有其他加密列，会保留其他列规则。 |
+| 创建 | “为 `orders.status` 规划可逆加密，需要支持等值查询，先预览不要执行。” | 新增加密规则、可能新增的物理派生列和索引建议。 |
+| 修改 | “把刚才的加密计划改成 AES 算法，并继续预览。” | 修改后的加密规则、同表其他加密列是否保留，以及物理变更建议。 |
+| 删除 | “删除 `orders.status` 的加密规则，先预览影响范围。” |
目标列规则是否删除、同表其他加密列是否保留，以及需要人工清理的物理对象。 |
## 审查加密计划
计划生成后，应重点审查：
-- DistSQL 是否符合创建、修改或删除加密规则的预期。
+- 待执行语句是否符合创建、修改或删除加密规则的预期。
- 是否需要新增物理派生列。
- 是否生成索引建议，以及索引是否适合当前物理库表结构。
- 密钥、凭证等敏感参数是否只以占位符或受保护方式传递。
@@ -64,22 +64,22 @@ weight = 2
MCP 会根据逻辑列、用户意图和已有规则生成派生列建议。
- `*_cipher` 用于保存密文，是加密规则的默认派生列。
-- 如果需要等值查询，会生成 `*_assisted_query`，并在允许索引 DDL 时生成相应索引计划。
+- 如果需要等值查询，会生成 `*_assisted_query`，并在允许生成索引建议时返回相应索引计划。
- 如果需要模糊查询，会生成 `*_like_query`，用于支持 LIKE 查询场景。
- 如果默认列名冲突，系统会追加数字后缀，并在计划中返回最终命名。
## 预览、执行和校验
-建议先预览，确认 DistSQL、DDL、索引计划和副作用范围后再执行。
+建议先预览，确认待执行语句、物理列、索引建议和副作用范围后再执行。
| 阶段 | 自然语言示例 | 用户关注点 |
| --- | --- | --- |
-| 预览 | “先预览刚才的加密规则计划，不要执行。” | 查看将要执行的 DistSQL、DDL 和索引建议。 |
+| 预览 | “先预览刚才的加密规则计划，不要执行。” | 查看将要执行的语句、物理列和索引建议。 |
| 执行 | “确认执行刚才的计划。” | 确认有副作用的变更已经过审查。 |
| 人工执行 | “导出人工执行包，不要自动执行。” | 由运维人员在受控环境审查和执行。 |
| 校验 | “校验刚才的加密规则是否生效。” | 查看规则状态、逻辑元数据、物理列建议和 SQL 可执行性。 |
-插件变更的通用审查流程见[插件工作流](../plugin-workflow/)。
+规则变更的通用审查流程见[规则变更流程](../plugin-workflow/)。
## 限制
@@ -97,7 +97,7 @@ MCP 会根据逻辑列、用户意图和已有规则生成派生列建议。
### Proxy 可见元数据边界
- MCP 根据 Proxy 暴露的逻辑元数据生成派生列、索引和列类型建议；它不会直接检查每个物理库。
-- 执行前应结合真实物理库表结构审查生成的 DDL。
+- 执行前应结合真实物理库表结构审查生成的物理变更语句。
### ShardingSphere 功能边界
@@ -105,4 +105,4 @@ MCP 会根据逻辑列、用户意图和已有规则生成派生列建议。
### SQL 生成边界
-- MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 标识符。为保证生成的 SQL 或 DistSQL
可审查，标识符内容不能包含反引号、NUL、回车或换行。
+- 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 5fd6b3080ac..855615d9764 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
@@ -10,7 +10,7 @@ Actual encryption capability is provided by
ShardingSphere-Proxy and its encrypt
- The current version supports logical databases exposed by
ShardingSphere-Proxy only.
- `runtimeDatabases` should point to Proxy logical databases, not physical
storage databases.
-- This feature does not apply to direct physical database connections. A
physical database usually does not understand ShardingSphere encryption DistSQL
and cannot expose Proxy-visible encryption algorithm plugins or rule state.
+- This feature does not apply to direct physical database connections. A
physical database usually does not understand ShardingSphere encryption rule
change statements and cannot expose Proxy-visible encryption algorithm plugins
or rule state.
- The target logical table and column should be discoverable through JDBC
metadata exposed by Proxy. This metadata should not be treated as a complete
physical database catalog.
## Use through natural language
@@ -24,7 +24,7 @@ Examples:
- Continue the previous plan with the AES algorithm and provide the key
through a protected channel.
- Confirm and execute the previous encryption rule plan, then validate the
result.
-Users should review DistSQL, DDL, index suggestions, and side-effect scope
before approving any side-effecting execution.
+Users should review statements, physical columns, index suggestions, and
side-effect scope before approving any side-effecting execution.
## Describe an encryption requirement
@@ -42,17 +42,17 @@ When using natural language, include the following
information when possible:
## Create, alter, and drop rules
-| Operation | Natural language example | Plan content |
+| Operation | Natural language example | Content to review |
| --- | --- | --- |
-| Create | "Plan reversible encryption for `orders.status`, support equality
queries, and preview first." | Generates new rule DistSQL, and physical
derived-column DDL or index suggestions when needed. |
-| Alter | "Change the previous encryption plan to use AES, then preview it
again." | Generates alter-rule DistSQL that keeps sibling column rules on the
same table and updates DDL or index suggestions when needed. |
-| Drop | "Drop the encryption rule for `orders.status` and preview the impact
first." | Generates DistSQL to drop the target column rule. Sibling encrypted
columns on the same table are preserved. |
+| Create | "Plan reversible encryption for `orders.status`, support equality
queries, and preview first." | The new encryption rule, possible physical
derived columns, and index suggestions. |
+| Alter | "Change the previous encryption plan to use AES, then preview it
again." | The altered encryption rule, whether sibling encrypted columns are
preserved, and physical change suggestions. |
+| Drop | "Drop the encryption rule for `orders.status` and preview the impact
first." | Whether the target column rule is dropped, whether sibling encrypted
columns are preserved, and which physical objects need manual cleanup. |
## Review the encryption plan
After a plan is generated, review:
-- Whether DistSQL matches the expected create, alter, or drop operation.
+- Whether the statements match the expected create, alter, or drop operation.
- Whether physical derived columns are required.
- Whether index suggestions are generated and suitable for the current
physical table structure.
- Whether keys, credentials, or other sensitive parameters are passed only
through placeholders or protected channels.
@@ -64,22 +64,22 @@ Encryption rules may need physical derived columns to store
ciphertext or suppor
MCP creates derived-column suggestions from the logical column, user intent,
and existing rules.
- `*_cipher` stores ciphertext and is the default derived column for
encryption rules.
-- If equality query is required, `*_assisted_query` is generated. Its index
plan is generated when index DDL is allowed.
+- If equality query is required, `*_assisted_query` is generated. Its index
plan is returned when index suggestions are allowed.
- If LIKE query is required, `*_like_query` is generated for LIKE query
scenarios.
- If a default column name conflicts, the system appends a numeric suffix and
returns the final name in the plan.
## Preview, apply, and validate
-Preview first, then review DistSQL, DDL, index plans, and side-effect scope
before execution.
+Preview first, then review statements, physical columns, index suggestions,
and side-effect scope before execution.
| Phase | Natural language example | User focus |
| --- | --- | --- |
-| Preview | "Preview the previous encryption rule plan without executing it."
| Inspect DistSQL, DDL, and index suggestions before execution. |
+| Preview | "Preview the previous encryption rule plan without executing it."
| Inspect statements, physical columns, and index suggestions before execution.
|
| Execute | "Confirm and execute the previous plan." | Confirm that the
side-effecting change has been reviewed. |
| Manual execution | "Export a manual execution package without automatic
execution." | Let operators review and execute in a controlled environment. |
| Validate | "Validate whether the previous encryption rule has taken effect."
| Check rule state, logical metadata, physical column suggestions, and SQL
executability. |
-For the general review flow of plugin changes, see [Plugin
Workflows](../plugin-workflow/).
+For the general review flow of rule changes, see [Rule Change
Flow](../plugin-workflow/).
## Limitations
@@ -97,7 +97,7 @@ For the general review flow of plugin changes, see [Plugin
Workflows](../plugin-
### Proxy-visible metadata boundaries
- MCP generates derived-column, index, and column-type suggestions from
logical metadata exposed by Proxy. It does not inspect every physical database
directly.
-- Review generated DDL against the real physical table structure before
applying it.
+- Review generated physical change statements against the real physical table
structure before applying them.
### ShardingSphere feature boundaries
@@ -105,4 +105,4 @@ For the general review flow of plugin changes, see [Plugin
Workflows](../plugin-
### SQL generation boundaries
-- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode
identifiers. To keep generated SQL or DistSQL reviewable, identifier content
must not contain backticks, NUL, carriage returns, or line feeds.
+- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode
identifiers. To keep generated SQL or rule change statements reviewable,
identifier content must not contain backticks, NUL, carriage returns, or line
feeds.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
index bf89b3fe408..a77e8c64116 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
@@ -10,7 +10,7 @@ weight = 3
- 当前版本只支持连接 ShardingSphere-Proxy 暴露的逻辑库。
- `runtimeDatabases` 应指向 Proxy 逻辑库，而不是底层物理存储库。
-- 直连真实数据库时，本功能不适用；真实数据库通常不识别 ShardingSphere 脱敏 DistSQL，也不能暴露 Proxy
中可见的脱敏算法插件和规则状态。
+- 直连真实数据库时，本功能不适用；真实数据库通常不识别 ShardingSphere 脱敏规则变更语句，也不能暴露 Proxy
中可见的脱敏算法插件和规则状态。
- 目标逻辑表和逻辑列应能通过 Proxy 暴露的 JDBC 元数据发现；这些信息不保证等同于底层物理库的完整元数据。
## 通过自然语言使用
@@ -24,7 +24,7 @@ weight = 3
- 调整刚才的计划，把替换字符改成 `*`。
- 确认并执行刚才的脱敏规则计划，然后校验结果。
-用户需要审查计划中的 DistSQL 和副作用范围，再批准有副作用的执行。
+用户需要审查计划中的待执行语句和副作用范围，再批准有副作用的执行。
## 提出脱敏需求
@@ -41,33 +41,33 @@ weight = 3
## 创建、修改和删除规则
-| 操作 | 自然语言示例 | 计划内容 |
+| 操作 | 自然语言示例 | 需要审查的内容 |
| --- | --- | --- |
-| 创建 | “为 `orders.phone` 规划手机号脱敏，先预览不要执行。” | 生成新增规则 DistSQL。 |
-| 修改 | “把刚才的脱敏规则改成保留前 3 后 4。” | 生成保留同表其他列规则的修改规则 DistSQL。 |
-| 删除 | “删除 `orders.phone` 的脱敏规则，先预览影响范围。” | 生成删除目标列规则的
DistSQL；如同表还有其他脱敏列，会保留其他列规则。 |
+| 创建 | “为 `orders.phone` 规划手机号脱敏，先预览不要执行。” | 新增脱敏规则、脱敏算法和参数。 |
+| 修改 | “把刚才的脱敏规则改成保留前 3 后 4。” | 修改后的脱敏规则，以及同表其他脱敏列是否保留。 |
+| 删除 | “删除 `orders.phone` 的脱敏规则，先预览影响范围。” | 目标列规则是否删除，以及同表其他脱敏列是否保留。 |
## 审查脱敏计划
计划生成后，应重点审查：
-- DistSQL 是否符合创建、修改或删除脱敏规则的预期。
+- 待执行语句是否符合创建、修改或删除脱敏规则的预期。
- 脱敏算法和参数是否符合业务合规要求。
- 删除规则后，通过 Proxy 查询该列时是否不再应用该脱敏规则。
- 是否会影响运行时规则或已有业务 SQL。
## 执行与校验
-建议先预览，确认 DistSQL 和副作用范围后再执行。
+建议先预览，确认待执行语句和副作用范围后再执行。
| 阶段 | 自然语言示例 | 用户关注点 |
| --- | --- | --- |
-| 预览 | “先预览刚才的脱敏规则计划，不要执行。” | 查看将要执行的 DistSQL 和副作用范围。 |
+| 预览 | “先预览刚才的脱敏规则计划，不要执行。” | 查看将要执行的语句和副作用范围。 |
| 执行 | “确认执行刚才的计划。” | 确认有副作用的变更已经过审查。 |
| 人工执行 | “导出人工执行包，不要自动执行。” | 由运维人员在受控环境审查和执行。 |
| 校验 | “校验刚才的脱敏规则是否生效。” | 查看规则状态、逻辑元数据和 SQL 可执行性。 |
-插件变更的通用审查流程见[插件工作流](../plugin-workflow/)。
+规则变更的通用审查流程见[规则变更流程](../plugin-workflow/)。
## 限制
@@ -89,4 +89,4 @@ weight = 3
### SQL 生成边界
-- MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 标识符。为保证生成的 SQL 或 DistSQL
可审查，标识符内容不能包含反引号、NUL、回车或换行。
+- 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 9e1dcb8ede4..0a14eb40225 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
@@ -10,7 +10,7 @@ Mask rules apply directly to logical columns and do not
generate physical derive
- The current version supports logical databases exposed by
ShardingSphere-Proxy only.
- `runtimeDatabases` should point to Proxy logical databases, not physical
storage databases.
-- This feature does not apply to direct physical database connections. A
physical database usually does not understand ShardingSphere masking DistSQL
and cannot expose Proxy-visible masking algorithm plugins or rule state.
+- This feature does not apply to direct physical database connections. A
physical database usually does not understand ShardingSphere masking rule
change statements and cannot expose Proxy-visible masking algorithm plugins or
rule state.
- The target logical table and column should be discoverable through JDBC
metadata exposed by Proxy. This metadata should not be treated as a complete
physical database catalog.
## Use through natural language
@@ -24,7 +24,7 @@ Examples:
- Adjust the previous plan to use `*` as the replacement character.
- Confirm and execute the previous masking rule plan, then validate the result.
-Users should review DistSQL and side-effect scope before approving any
side-effecting execution.
+Users should review statements and side-effect scope before approving any
side-effecting execution.
## Describe a masking requirement
@@ -41,33 +41,33 @@ When using natural language, include the following
information when possible:
## Create, alter, and drop rules
-| Operation | Natural language example | Plan content |
+| Operation | Natural language example | Content to review |
| --- | --- | --- |
-| Create | "Plan phone-number masking for `orders.phone` and preview it
without execution." | Generates DistSQL for adding the rule. |
-| Alter | "Change the previous masking rule to keep the first 3 and last 4
characters." | Generates DistSQL that preserves sibling column rules on the
same table. |
-| Drop | "Drop the masking rule for `orders.phone` and preview the impact
first." | Generates DistSQL to drop the target column rule. Sibling masking
columns on the same table are preserved. |
+| Create | "Plan phone-number masking for `orders.phone` and preview it
without execution." | The new masking rule, masking algorithm, and properties. |
+| Alter | "Change the previous masking rule to keep the first 3 and last 4
characters." | The altered masking rule and whether sibling masking columns are
preserved. |
+| Drop | "Drop the masking rule for `orders.phone` and preview the impact
first." | Whether the target column rule is dropped and whether sibling masking
columns are preserved. |
## Review the masking plan
After a plan is generated, review:
-- Whether DistSQL matches the expected create, alter, or drop operation.
+- Whether the statements match the expected create, alter, or drop operation.
- Whether the masking algorithm and properties satisfy business compliance
requirements.
- Whether queries through Proxy no longer apply masking to the column after
dropping a rule.
- Whether runtime rules or existing business SQL may be affected.
## Apply and validate
-Preview first, then review DistSQL and side-effect scope before execution.
+Preview first, then review statements and side-effect scope before execution.
| Phase | Natural language example | User focus |
| --- | --- | --- |
-| Preview | "Preview the previous masking rule plan without executing it." |
Inspect DistSQL and side-effect scope before execution. |
+| Preview | "Preview the previous masking rule plan without executing it." |
Inspect statements and side-effect scope before execution. |
| Execute | "Confirm and execute the previous plan." | Confirm that the
side-effecting change has been reviewed. |
| Manual execution | "Export a manual execution package without automatic
execution." | Let operators review and execute in a controlled environment. |
| Validate | "Validate whether the previous masking rule has taken effect." |
Check rule state, logical metadata, and SQL executability. |
-For the general review flow of plugin changes, see [Plugin
Workflows](../plugin-workflow/).
+For the general review flow of rule changes, see [Rule Change
Flow](../plugin-workflow/).
## Limitations
@@ -89,4 +89,4 @@ For the general review flow of plugin changes, see [Plugin
Workflows](../plugin-
### SQL generation boundaries
-- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode
identifiers. To keep generated SQL or DistSQL reviewable, identifier content
must not contain backticks, NUL, carriage returns, or line feeds.
+- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode
identifiers. To keep generated SQL or rule change statements reviewable,
identifier 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 22bab1be90c..54b122c025e 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.cn.md
@@ -1,15 +1,15 @@
+++
-title = "插件工作流"
+title = "规则变更流程"
weight = 1
+++
-插件工作流用于功能插件生成可审查的数据库治理变更时，引导用户完成需求确认、预览、执行和校验。
-它不是一个独立业务功能；用户通常会在数据加密、数据脱敏等插件任务中进入这个流程。
+规则变更流程用于数据加密、数据脱敏等功能生成可审查的数据库治理变更时，引导用户完成需求确认、预览、执行和校验。
+它不是一个独立业务功能；用户通常会在具体的数据加密或数据脱敏任务中进入这个流程。
## 适用场景
- 创建、修改或删除 ShardingSphere 规则。
-- 变更前需要查看将要执行的 DistSQL、DDL 或索引建议。
+- 变更前需要查看将要执行的语句、物理列或索引建议。
- 不希望自动执行，希望导出人工执行包。
- 执行后需要确认规则状态、逻辑元数据和 SQL 可执行性。
@@ -19,7 +19,7 @@ weight = 1
| --- | --- | --- |
| 描述需求 | 说明要变更的逻辑库、表、列和治理目标。 | 信息越明确，生成的计划越稳定。 |
| 补充信息 | 根据提示补齐算法、参数、密钥占位符或执行偏好。 | 敏感值应通过受保护渠道提供。 |
-| 审查计划 | 查看生成的 DistSQL、DDL、索引建议和影响范围。 | 确认是否符合业务预期。 |
+| 审查计划 | 查看生成的待执行语句、物理列或索引建议和影响范围。 | 确认是否符合业务预期。 |
| 预览变更 | 要求先预览，不修改运行时状态。 | 检查将执行的语句和副作用。 |
| 执行变更 | 确认自动执行，或导出人工执行包后由运维执行。 | 有副作用的变更必须经过确认。 |
| 校验结果 | 执行后查看规则状态、元数据和 SQL 可执行性。 | 确认变更是否生效。 |
@@ -28,13 +28,13 @@ weight = 1
| 执行方式 | 是否修改运行时状态 | 适用场景 |
| --- | --- | --- |
-| 只预览 | 否 | 先查看变更产物和副作用范围。 |
+| 只预览 | 否 | 先查看变更内容和副作用范围。 |
| 审查后执行 | 是 | 用户确认后，由 MCP Server 执行变更。 |
| 人工执行包 | 否 | 不自动执行，返回可由运维人员审查和执行的语句。 |
## 敏感输入
-插件可能需要密钥或凭证等敏感字段。
+规则变更可能需要密钥或凭证等敏感字段。
这些值不应写入普通文档、聊天记录或日志。
推荐处理方式：
@@ -44,12 +44,12 @@ weight = 1
- 在受控环境中替换占位符并执行。
ShardingSphere-MCP 不直接读取密钥管理系统。
-使用人工执行包时，可以在 DistSQL 中保留占位符，由执行人员在受控环境替换。
+使用人工执行包时，可以在待执行语句中保留占位符，由执行人员在受控环境替换。
## 审查重点
-- DistSQL 是否符合预期规则变更。
-- DDL 或索引建议是否适合当前物理库表结构。
+- 待执行语句是否符合预期规则变更。
+- 物理列或索引建议是否适合当前物理库表结构。
- 是否会修改运行时规则、元数据或数据。
- 是否需要人工执行、备份、回滚预案或业务审批。
- 校验结果是否覆盖规则状态、逻辑元数据和 SQL 可执行性。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
index e9d26808127..205ef348ebd 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/plugin-workflow.en.md
@@ -1,40 +1,40 @@
+++
-title = "Plugin Workflows"
+title = "Rule Change Flow"
weight = 1
+++
-Plugin workflows guide users through requirement confirmation, preview, apply,
and validation when a feature plugin creates a reviewable database governance
change.
-They are not standalone business features. Users usually enter this flow from
feature tasks such as data encryption or data masking.
+The rule change flow guides users through requirement confirmation, preview,
apply, and validation when features such as data encryption or data masking
create reviewable database governance changes.
+It is not a standalone business feature. Users usually enter this flow from a
concrete data encryption or data masking task.
-## When to use
+## When to Use
- Create, alter, or drop ShardingSphere rules.
-- Review DistSQL, DDL, or index suggestions before a change.
+- Review statements, physical columns, or index suggestions before a change.
- Export a manual execution package instead of applying changes automatically.
- Validate rule state, logical metadata, and SQL executability after execution.
-## Basic flow
+## Basic Flow
| Phase | User action | Focus |
| --- | --- | --- |
| Describe the requirement | Provide the logical database, table, column, and
governance goal. | Clear input makes the generated plan more stable. |
| Provide missing information | Add algorithm choices, parameters, secret
placeholders, or execution preferences when asked. | Sensitive values should be
provided through protected channels. |
-| Review the plan | Review generated DistSQL, DDL, index suggestions, and
impact scope. | Confirm that the plan matches business expectations. |
+| Review the plan | Review generated statements, physical columns or index
suggestions, and impact scope. | Confirm that the plan matches business
expectations. |
| Preview the change | Ask to preview first without changing runtime state. |
Check statements and side effects before execution. |
| Apply the change | Confirm automatic execution, or export a manual package
for operators. | Side-effecting changes must be confirmed. |
| Validate the result | Inspect rule state, metadata, and SQL executability
after execution. | Confirm that the change has taken effect. |
-## Execution choices
+## Execution Choices
| Choice | Changes runtime state | Use case |
| --- | --- | --- |
-| Preview only | No | Inspect change artifacts and side-effect scope first. |
+| 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. |
-## Sensitive inputs
+## Sensitive Inputs
-Plugins may require sensitive fields such as keys or credentials.
+Rule changes may require sensitive fields such as keys or credentials.
These values should not be written into ordinary documents, chat records, or
logs.
Recommended handling:
@@ -44,12 +44,12 @@ Recommended handling:
- Replace placeholders and execute in a controlled environment.
ShardingSphere-MCP does not read secret managers directly.
-When using a manual package, placeholders can remain in DistSQL and be
replaced by the operator in a controlled environment.
+When using a manual package, placeholders can remain in the statements and be
replaced by the operator in a controlled environment.
-## Review checklist
+## Review Checklist
-- Whether DistSQL matches the expected rule change.
-- Whether DDL or index suggestions fit the current physical table structure.
+- Whether the statements match the expected rule change.
+- Whether physical column or index suggestions fit the current physical table
structure.
- Whether runtime rules, metadata, or data may be changed.
- Whether manual execution, backup, rollback planning, or business approval is
required.
- Whether validation covers rule state, logical metadata, and SQL
executability.
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 cf65fc7da5e..fe1b4c6749a 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
@@ -3,13 +3,13 @@ title = "快速开始"
weight = 1
+++
-本页演示如何从源码构建 ShardingSphere-MCP，连接一个用户已准备好的 ShardingSphere-Proxy 逻辑库，并通过 HTTP
验证元数据读取和只读 SQL 查询。
+本页演示如何从源码构建 ShardingSphere-MCP，连接一个用户已准备好的 ShardingSphere-Proxy 逻辑库，并在 AI
应用中通过自然语言验证基础数据库任务。
## 前置条件
- `JAVA_HOME` 或 `PATH` 中可用的 JDK 21。
- 一个可通过 JDBC 访问的 ShardingSphere-Proxy 逻辑库。
-- `curl`，用于发送 HTTP 请求。
+- 一个支持 MCP 的 AI 应用、IDE 插件或 Agent 平台。
## 构建发行包
@@ -64,133 +64,42 @@ 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`。
Unix-like 示例会在当前终端后台启动 MCP Server，并把进程号保存到 `MCP_PID`，方便最后停止服务。
-## 初始化 MCP 会话
+## 接入 AI 应用
-```bash
-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":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
-```
-
-预期结果：
-
-- 响应头包含 `MCP-Session-Id`。
-- 响应头包含 `MCP-Protocol-Version`。
-
-通知服务端客户端已完成初始化：
-
-```bash
-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":{}}'
-```
+在 AI 应用、IDE 插件或 Agent 平台中配置 HTTP MCP Server 地址：
-预期结果：
-
-- 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: <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"}}'
-```
-
-预期结果：
-
-- 响应类型是 `text/event-stream`。
-- JSON 负载位于 `data:` 行。
-- 返回内容包含 `<logic-database>` 对应的逻辑库名称。
-
-## 搜索元数据
-
-```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: <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"]
- }
+```json
+{
+ "mcpServers": {
+ "shardingsphere": {
+ "url": "http://127.0.0.1:18088/mcp";
}
- }'
+ }
+}
```
-预期结果：
-
-- JSON 负载包含匹配到的表或视图。
-- 结果项可包含后续读取用的资源提示。
+不同 AI 应用的配置文件位置和字段名称可能不同，请以客户端自身文档为准。
+更多 HTTP 和 STDIO 配置方式见[客户端集成](../client-integration/)。
-## 执行只读查询
+## 通过自然语言验证
-```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: <MCP-Session-Id value>' \
- -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
- --data '{
- "jsonrpc":"2.0",
- "id":"tool-2",
- "method":"tools/call",
- "params":{
- "name":"database_gateway_execute_query",
- "arguments":{
- "database":"<logic-database>",
- "sql":"SELECT * FROM <table-name> LIMIT 10",
- "max_rows":10
- }
- }
- }'
-```
+配置完成后，在 AI 应用中输入以下任务验证 ShardingSphere-MCP 是否可以访问目标逻辑库：
-预期结果：
+- “查看 `<logic-database>` 中有哪些表。”
+- “查看 `<table-name>` 的字段和索引。”
+- “查询 `<table-name>` 前 10 行。”
-- `result_kind` 为 `result_set`。
-- `statement_class` 为 `query`。
-- 负载包含 `columns`、`rows` 或 `row_objects`。
+如果可以返回逻辑库、表结构或查询结果，说明 MCP Server 已经可以通过 AI 应用访问目标 ShardingSphere-Proxy 逻辑库。
+如果 AI 应用无法连接或看不到逻辑库，请查看[常见问题](../troubleshooting/)。
-## 关闭会话并停止服务
+## 关闭服务
Unix-like 系统：
```bash
-curl -sS -D - -o /dev/null \
- -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>'
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`。
+在 `ShardingSphere MCP` 启动窗口按 `Ctrl+C`，或直接关闭该窗口。
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 d755d4239fe..29e81361815 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
@@ -3,17 +3,17 @@ title = "Quick Start"
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.
+This page shows how to build ShardingSphere-MCP from source, connect it to a
user-prepared ShardingSphere-Proxy logical database, and verify basic database
tasks through natural language in an AI application.
## Prerequisites
- JDK 21 available from `JAVA_HOME` or `PATH`.
- A ShardingSphere-Proxy logical database reachable through JDBC.
-- `curl` for HTTP requests.
+- An AI application, IDE extension, or agent platform that supports MCP.
-## Build the distribution
+## Build the Distribution
-Run from the repository root:
+Run the following command from the repository root:
```bash
./mvnw -pl distribution/mcp -am -DskipTests package
@@ -30,7 +30,7 @@ Expected result:
- The current directory contains `bin/`, `conf/`, and `lib/`.
- Replace `${version}` with the built distribution version, such as
`5.5.4-SNAPSHOT`.
-## Configure the database
+## Configure the Database
Edit `conf/mcp-http.yaml` and point `runtimeDatabases` to an existing
ShardingSphere-Proxy logical database:
@@ -45,7 +45,7 @@ runtimeDatabases:
```
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.
+If the target database driver is not provided with the distribution, put the
corresponding JDBC driver jar under `plugins/` before startup.
## Start the HTTP MCP Server
@@ -62,135 +62,44 @@ 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 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.
+The Unix-like example starts the MCP Server in the background and saves the
process ID in `MCP_PID` for shutdown.
-## Initialize an MCP session
+## Connect an AI Application
-```bash
-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":{"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`.
-
-Notify the server that the client has completed initialization:
-
-```bash
-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":{}}'
-```
+Configure the HTTP MCP Server address in the AI application, IDE extension, or
agent platform:
-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: <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"}}'
-```
-
-Expected result:
-
-- The response type is `text/event-stream`.
-- The JSON payload is in the `data:` line.
-- The payload contains the logical database name that replaces
`<logic-database>`.
-
-## Search metadata
-
-```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: <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"]
- }
+```json
+{
+ "mcpServers": {
+ "shardingsphere": {
+ "url": "http://127.0.0.1:18088/mcp";
}
- }'
+ }
+}
```
-Expected result:
-
-- The JSON payload contains matched tables or views.
-- Each result item may include resource hints for follow-up reads.
+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/).
-## Execute a read-only query
+## Verify through Natural Language
-```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: <MCP-Session-Id value>' \
- -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
- --data '{
- "jsonrpc":"2.0",
- "id":"tool-2",
- "method":"tools/call",
- "params":{
- "name":"database_gateway_execute_query",
- "arguments":{
- "database":"<logic-database>",
- "sql":"SELECT * FROM <table-name> LIMIT 10",
- "max_rows":10
- }
- }
- }'
-```
+After configuration, enter the following tasks in the AI application to verify
that ShardingSphere-MCP can access the target logical database:
-Expected result:
+- "Show tables in `<logic-database>`."
+- "Show columns and indexes for `<table-name>`."
+- "Query the first 10 rows from `<table-name>`."
-- `result_kind` is `result_set`.
-- `statement_class` is `query`.
-- The payload contains `columns`, `rows`, or `row_objects`.
+If the application returns the logical database, table structure, or query
results, the MCP Server can access the target ShardingSphere-Proxy logical
database through the AI application.
+If the AI application cannot connect or cannot see the logical database, see
[Troubleshooting](../troubleshooting/).
-## Close the session and stop the server
+## Stop the Service
Unix-like systems:
```bash
-curl -sS -D - -o /dev/null \
- -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>'
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`.
+Press `Ctrl+C` in the `ShardingSphere MCP` startup window, or close the window
directly.
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 760d8a51c80..51ef62d4d4c 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -3,30 +3,31 @@ title = "常见问题"
weight = 7
+++
-本页按现象整理 MCP Server、传输方式、会话、SQL 工具和工作流机制的排查方法。
+本页按用户侧现象整理 ShardingSphere-MCP、AI 应用集成、数据库连接、元数据查看、SQL 执行和规则变更的排查方法。
功能插件的业务规则问题请查看对应功能插件文档。
## 排查索引
| 现象 | 可能原因 | 处理方式 |
| --- | --- | --- |
-| 启动失败 | JDK、配置路径、YAML 字段或必填字段不正确。 | 查看终端错误和 `logs/mcp.log`。 |
-| HTTP 无法连接 | 端口、端点路径、传输方式或绑定地址不正确。 | 检查 `port`、`endpointPath`、`bindHost` 和客户端
URL。 |
-| HTTP 返回 403 | 请求 `Origin` 与绑定地址安全策略不匹配。 | 本机调试用回环地址；远程访问走受控网关；详细原因看服务端日志。 |
-| 会话请求失败 | 未初始化、缺少会话头，或复用已关闭会话。 | 先调用 `initialize`，后续请求持续携带响应头。 |
-| STDIO 没有响应 | 被当成人工交互 Shell，或客户端未按 MCP stdio 协议发送 JSON-RPC。 | 由 MCP
客户端拉起进程；诊断信息看 stderr 或日志。 |
-| 逻辑库或元数据为空 | 未配置逻辑库、逻辑库名称不正确、连接失败、权限不足，或目标范围确实为空。 |
先查看运行时状态，确认数据库配置、逻辑库名称、连接错误分类和账号权限。 |
+| MCP Server 启动失败 | JDK、配置路径、YAML 字段或必填字段不正确。 | 查看启动终端和
`logs/mcp.log`，确认配置文件路径和必填字段。 |
+| AI 应用无法连接 ShardingSphere-MCP | 端口、端点路径、传输方式、绑定地址或客户端配置不正确。 | 检查
`port`、`endpointPath`、`bindHost` 和 AI 应用中的 MCP Server 地址。 |
+| 远程访问 HTTP 服务失败 | HTTP 绑定地址、安全策略或网关配置不正确。 |
本机调试用回环地址；远程访问放在受控网关或反向代理后面；详细原因看服务端日志。 |
+| STDIO 模式没有响应 | 用户直接把 STDIO 当成命令行交互入口，或 AI 应用没有正确拉起进程。 | 由 AI 应用拉起
ShardingSphere-MCP；诊断信息看 stderr 或 `logs/mcp.log`。 |
+| 看不到逻辑库 | 未配置逻辑库、逻辑库名称不正确、连接失败、权限不足，或目标范围确实为空。 | 确认
`runtimeDatabases`、逻辑库名称、连接错误分类和账号权限。 |
+| 查不到表、列或索引 | 连接目标不同、schema 不正确、账号权限不足，或 Proxy 暴露的逻辑元数据与底层物理库不同。 | 先确认连接的是
ShardingSphere-Proxy 还是普通数据库，再检查 schema、账号权限和 Proxy 可见元数据。 |
| JDBC 驱动错误 | 驱动不在类路径，或 `driverClassName` 不正确。 | 把驱动 jar 放入 `plugins/`，并确认
`driverClassName` 非空且类名正确。 |
-| SQL 工具调用失败 | 工具选错、多语句被拒绝或参数超限。 | 查询用 `execute_query`；有副作用 SQL 用
`execute_update` 并先预览。 |
-| 工作流失败 | `plan_id`、会话、执行模式或人工执行步骤不正确。 | 同一会话内复用 `plan_id`；先预览；人工执行后再校验。 |
-| 敏感输入无法传递 | 补问要求密钥或凭证。 | 通过客户端、密钥管理系统或运维控制通道取得真实值，再在受保护调用或人工执行环节传入。 |
+| 只读查询失败 | SQL 语法、目标表名、schema、权限或返回行数限制不正确。 | 先让 AI 应用查看表结构，再执行只读查询，并限制返回行数。 |
+| 有副作用 SQL 无法执行 | SQL 类型有副作用，或未先预览和确认。 | 先要求预览变更 SQL，审查影响范围后再确认执行。 |
+| 加密或脱敏计划无法生成 | 连接目标不是 Proxy、目标列不可见、算法不可用，或缺少必要参数。 | 确认 `runtimeDatabases` 指向
Proxy 逻辑库，并补充逻辑库、表、列、算法和参数。 |
+| 规则变更执行后校验不通过 | 规则未成功执行、权限不足、元数据未刷新，或人工执行包未完成执行。 |
查看规则变更计划、执行结果和日志；人工执行后再发起校验。 |
+| 敏感输入无法传递 | 规则变更需要密钥或凭证。 | 通过客户端、密钥管理系统或运维控制通道取得真实值，再在受保护调用或人工执行环节传入。 |
补充说明：
- `username` 和 `driverClassName` 必须显式写出且不能为空；无密码账号可以省略 `password` 或写 `""`。
-- `MCP-Session-Id` 和 `MCP-Protocol-Version` 来自 `initialize` 响应头，关闭会话后不能复用。
-- 使用 `manual-only` 后，应先人工执行返回的 SQL 或 DistSQL，再调用校验工具。
- 人工执行包中的密钥占位符应由执行人员在受控环境替换。
+- 开发者需要排查协议请求时，可参考[开发者附录](../developer-appendix/)。
## 连接错误分类
@@ -43,34 +44,22 @@ weight = 7
| `connection_failed` | 连接失败，但无法归类为更具体的原因。 |
| `database_not_visible` | 指定逻辑库对当前连接不可见。 |
-## SQL 工具选择
+## SQL 执行建议
-| SQL 类型 | 工具 | 建议 |
-| --- | --- | --- |
-| `SELECT` | `database_gateway_execute_query` | 用于只读查询。 |
-| `EXPLAIN ANALYZE` | `database_gateway_execute_query` | 仅在目标逻辑库能力允许时使用。 |
-| DML、DDL、DCL、事务控制、savepoint | `database_gateway_execute_update` | 先用
`execution_mode=preview` 查看副作用，再决定是否执行。 |
-
-`database_gateway_execute_update` 的预览参数：
-
-```json
-{"execution_mode":"preview"}
-```
-
-确认后执行：
-
-```json
-{"execution_mode":"execute"}
-```
+| SQL 类型 | 建议 |
+| --- | --- |
+| `SELECT` | 用于只读查询，建议限制返回行数。 |
+| `EXPLAIN ANALYZE` | 仅在目标逻辑库能力允许时使用。 |
+| DML、DDL、DCL、事务控制、savepoint | 先预览并审查副作用，再决定是否执行。 |
-## 诊断信息
+## 提供给管理员或排障人员的信息
报告问题时建议提供：
- 启动命令。
- MCP 配置文件，注意移除密码、密钥和令牌。
- 传输方式和端点。
-- 是否已完成 `initialize`，不要公开真实 `MCP-Session-Id`。
-- 工具或资源请求体。
+- AI 应用中的 MCP Server 配置摘要。
+- 用户输入的自然语言任务。
- 错误响应内容，包含错误分类和提示信息。
- `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 4514e042d4d..b4f745c6733 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -3,30 +3,31 @@ title = "Troubleshooting"
weight = 7
+++
-This page organizes troubleshooting by symptom for the MCP Server, transport,
sessions, SQL tools, and workflow mechanism.
+This page organizes troubleshooting by user-visible symptoms for
ShardingSphere-MCP, AI application integration, database connectivity, metadata
inspection, SQL execution, and rule changes.
For feature-specific business rule issues, see the corresponding feature
plugin documentation.
-## Troubleshooting index
+## Troubleshooting Index
| Symptom | Possible cause | Action |
| --- | --- | --- |
-| Startup failure | JDK, config path, YAML field, or required field is wrong.
| Inspect terminal output and `logs/mcp.log`. |
-| HTTP connection failure | Port, endpoint path, transport type, or bind
address is wrong. | Check `port`, `endpointPath`, `bindHost`, and client URL. |
-| HTTP 403 response | Request `Origin` does not match the bind-address policy.
| Use loopback locally; use a controlled gateway for remote access; inspect
server logs for the safe reason category. |
-| Session request failure | Session was not initialized, headers are missing,
or a closed session is reused. | Call `initialize` first and keep sending the
response headers. |
-| No response in STDIO mode | STDIO is used as a shell, or the client does not
send JSON-RPC over MCP stdio. | Let an MCP client launch the process; read
stderr or logs for diagnostics. |
-| Logical database or metadata is empty | No logical database is configured,
the logical database name is wrong, connection failed, permission is
insufficient, or the target scope is empty. | Check runtime status, then verify
database configuration, logical database name, connection failure category, and
account privileges. |
-| JDBC driver error | Driver is not on classpath, or `driverClassName` is
wrong. | Put the driver jar under `plugins/`, and keep `driverClassName`
non-empty and correct. |
-| SQL tool call failure | Wrong tool, multiple statements, or argument out of
range. | Use `execute_query` for queries; use `execute_update` with preview for
side effects. |
-| Workflow failure | `plan_id`, session, execution mode, or manual step is
wrong. | Reuse `plan_id` in one session; preview first; validate after manual
execution. |
-| Secret input cannot be passed safely | A clarification asks for a key or
credential. | Resolve the value through the client, a key management system, or
an operations control channel, then pass it through a protected call or manual
execution step. |
+| MCP Server startup failure | JDK, config path, YAML field, or required field
is wrong. | Inspect the startup terminal and `logs/mcp.log`; confirm the
configuration file path and required fields. |
+| The AI application cannot connect to ShardingSphere-MCP | Port, endpoint
path, transport type, bind address, or client configuration is wrong. | Check
`port`, `endpointPath`, `bindHost`, and the MCP Server address configured in
the AI application. |
+| Remote HTTP access fails | HTTP bind address, security policy, or gateway
configuration is wrong. | Use loopback locally; place remote access behind a
controlled gateway or reverse proxy; inspect server logs for details. |
+| No response in STDIO mode | STDIO is used as an interactive command-line
entry, or the AI application does not launch the process correctly. | Let the
AI application launch ShardingSphere-MCP; inspect stderr or `logs/mcp.log` for
diagnostics. |
+| Logical databases are not visible | No logical database is configured, the
logical database name is wrong, connection failed, permission is insufficient,
or the target scope is empty. | Verify `runtimeDatabases`, logical database
names, connection failure category, and account privileges. |
+| Tables, columns, or indexes cannot be found | The connection target is
different, schema is wrong, account privileges are insufficient, or
Proxy-visible logical metadata differs from the physical database. | Confirm
whether the target is ShardingSphere-Proxy or a regular database, then check
schema, account privileges, and Proxy-visible metadata. |
+| JDBC driver error | Driver is not on the classpath, or `driverClassName` is
wrong. | Put the driver jar under `plugins/`, and keep `driverClassName`
non-empty and correct. |
+| Read-only query fails | SQL syntax, target table name, schema, privilege, or
row limit is wrong. | Ask the AI application to inspect table structure first,
then run a read-only query with a row limit. |
+| Side-effecting SQL cannot be executed | The SQL has side effects, or it was
not previewed and confirmed first. | Preview the change SQL first, review the
impact, then confirm execution. |
+| Encryption or masking plan cannot be generated | The target is not Proxy,
the target column is not visible, the algorithm is unavailable, or required
parameters are missing. | Ensure that `runtimeDatabases` points to a Proxy
logical database, then provide logical database, table, column, algorithm, and
parameters. |
+| Validation fails after a rule change | The rule was not applied
successfully, permission is insufficient, metadata is not refreshed, or a
manual package was not executed. | Inspect the rule change plan, execution
result, and logs; validate again after manual execution is completed. |
+| Secret input cannot be passed safely | A rule change needs a key or
credential. | Resolve the value through the client, a key management system, or
an operations control channel, then pass it through a protected call or manual
execution step. |
Additional notes:
- `username` and `driverClassName` must be declared explicitly and cannot be
empty; a no-password account can omit `password` or use `""`.
-- `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.
+- For protocol request debugging, see the [Developer
Appendix](../developer-appendix/).
## Connection Failure Categories
@@ -43,34 +44,22 @@ 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 tool selection
+## SQL Execution Recommendations
-| 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. |
-
-Preview parameter for `database_gateway_execute_update`:
-
-```json
-{"execution_mode":"preview"}
-```
-
-Execute after review:
-
-```json
-{"execution_mode":"execute"}
-```
+| SQL type | 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. |
-## Diagnostics
+## Information for Administrators or Troubleshooters
When reporting an issue, provide:
- Startup command.
- MCP configuration file, with passwords, keys, and tokens removed.
- Transport type and endpoint.
-- Whether `initialize` has completed. Do not publish a real `MCP-Session-Id`.
-- Tool or resource request body.
+- MCP Server configuration summary from the AI application.
+- The natural-language task entered by the user.
- Error response content, including the failure category and guidance.
- Relevant errors from `logs/mcp.log`.
