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 d6fdf6e11d7 Refine ShardingSphere MCP user manual (#38755)
d6fdf6e11d7 is described below
commit d6fdf6e11d7f080614e0bf29ab27dacf8b9750dd
Author: Liang Zhang <[email protected]>
AuthorDate: Fri May 29 21:27:34 2026 +0800
Refine ShardingSphere MCP user manual (#38755)
Refine the ShardingSphere MCP documentation in both English and Chinese.
- Clarify capability discovery, resource URI, tool, prompt, and completion
boundaries
- Simplify quick start and configuration descriptions
- Move plugin-specific resource details out of the core capability catalog
- Explain client integration scenarios and transport selection
- Clarify workflow usage as the shared mechanism for feature plugin
governance tasks
---
.../shardingsphere-mcp/capabilities.cn.md | 135 +++++++++++----------
.../shardingsphere-mcp/capabilities.en.md | 135 +++++++++++----------
.../shardingsphere-mcp/client-integration.cn.md | 49 +++++++-
.../shardingsphere-mcp/client-integration.en.md | 49 +++++++-
.../shardingsphere-mcp/configuration.cn.md | 7 +-
.../shardingsphere-mcp/configuration.en.md | 7 +-
.../shardingsphere-mcp/quick-start.cn.md | 3 +-
.../shardingsphere-mcp/quick-start.en.md | 3 +-
.../user-manual/shardingsphere-mcp/workflow.cn.md | 10 +-
.../user-manual/shardingsphere-mcp/workflow.en.md | 14 ++-
10 files changed, 243 insertions(+), 169 deletions(-)
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 a475850683c..1ee5d481ad3 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
@@ -1,21 +1,26 @@
+++
-title = "功能介绍"
+title = "能力清单"
weight = 2
+++
-本页列出 ShardingSphere-MCP 对外暴露的协议能力。
-运行时实际可用能力以 `shardingsphere://capabilities` 以及 MCP 官方列表方法返回值为准。
+本页说明 ShardingSphere-MCP 的核心能力，以及协议方法、资源 URI、工具和提示之间的关系。
+文档用于解释能力语义；客户端应通过 MCP 列表方法和 `shardingsphere://capabilities` 读取当前 MCP Server
实际暴露的内容。
-## 发现入口
+## 能力发现
-| 协议能力 | 用途 |
-| --- | --- |
-| `tools/list` | 发现可调用工具。 |
-| `resources/list` | 发现可直接读取的资源。 |
-| `resources/templates/list` | 发现带参数的资源模板。 |
-| `prompts/list` | 发现可用提示。 |
-| `completion/complete` | 获取资源、提示或参数的补全候选。 |
-| `resources/read` 读取 `shardingsphere://capabilities` | 读取 ShardingSphere
领域能力目录。 |
+下面列出的是 MCP 协议方法和 ShardingSphere-MCP 资源 URI。
+MCP 协议方法不使用 `shardingsphere://` 前缀；这个前缀只用于 ShardingSphere-MCP 资源 URI。
+工具和提示使用名称调用，也不是资源 URI。
+
+| 方法或资源 | 类型 | 用途 |
+| --- | --- | --- |
+| `tools/list` | MCP 协议方法 | 列出可调用工具。 |
+| `resources/list` | MCP 协议方法 | 列出不需要参数即可读取的资源。 |
+| `resources/templates/list` | MCP 协议方法 | 列出带参数的资源 URI 模板；客户端需要先填充模板，再通过
`resources/read` 读取。 |
+| `resources/read` | MCP 协议方法 | 读取一个具体资源 URI；读取
`shardingsphere://capabilities` 可获得 ShardingSphere 领域能力目录。 |
+| `prompts/list` | MCP 协议方法 | 列出可用提示。 |
+| `completion/complete` | MCP 协议方法 | 获取资源、提示或参数的补全候选。 |
+| `shardingsphere://capabilities` | ShardingSphere-MCP 资源 URI | 读取
ShardingSphere 领域能力目录。 |
## 能力可用性说明
@@ -25,41 +30,32 @@ ShardingSphere-MCP 的协议表面是统一的，但运行时可用性取决于
- 连接真实数据库时，通用 JDBC 元数据和 SQL 执行能力可用；ShardingSphere 规则、算法插件和依赖 DistSQL 的工作流不适用。
- 客户端应优先读取 `shardingsphere://runtime` 和
`shardingsphere://databases/{database}/capabilities`
判断当前数据库能力，不应假设所有资源和工具在所有连接目标下等价。
-## 静态资源
-
-| 资源 | 用途 |
-| --- | --- |
-| `shardingsphere://capabilities` | 查看资源、资源模板、工具、提示、补全、工作流关系和副作用提示。 |
-| `shardingsphere://runtime` | 查看当前传输方式、运行状态和已配置运行时数据库摘要。 |
-| `shardingsphere://databases` | 列出当前 MCP Server 可以访问的运行时数据库；连接 Proxy 时对应
ShardingSphere 逻辑库。 |
-| `shardingsphere://features/encrypt/algorithms` | 列出当前 ShardingSphere-Proxy
可见的数据加密算法插件。 |
-| `shardingsphere://features/mask/algorithms` | 列出当前 ShardingSphere-Proxy
可见的数据脱敏算法插件。 |
-
-## 资源模板
+## 资源
-| 资源模板 | 用途 |
-| --- | --- |
-| `shardingsphere://databases/{database}` | 读取一个运行时数据库的详情和元数据摘要。 |
-| `shardingsphere://databases/{database}/capabilities` | 读取一个运行时数据库的
SQL、事务、schema 和元数据对象能力。 |
-| `shardingsphere://databases/{database}/schemas` | 列出一个运行时数据库中的 schema 或
namespace。 |
-| `shardingsphere://databases/{database}/schemas/{schema}` | 读取一个 schema 或
namespace 的详情。 |
-| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | 列出一个
schema 中的 sequence。 |
-|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
读取一个 sequence 的详情。 |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables` | 列出一个
schema 中的表。 |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
读取一个表的详情。 |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| 列出一个表的列。 |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| 读取一个表列的详情。 |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| 列出一个表的索引。 |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| 读取一个表索引的详情。 |
-| `shardingsphere://databases/{database}/schemas/{schema}/views` | 列出一个 schema
中的视图。 |
-| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` |
读取一个视图的详情。 |
-|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
列出一个视图的列。 |
-|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| 读取一个视图列的详情。 |
-| `shardingsphere://workflows/{plan_id}` | 读取当前会话中的工作流计划、补问信息、变更产物和下一步动作。 |
-| `shardingsphere://features/encrypt/databases/{database}/rules` |
列出一个逻辑库中的数据加密规则。 |
-|
`shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules` |
读取一个逻辑表的数据加密规则。 |
-| `shardingsphere://features/mask/databases/{database}/rules` |
列出一个逻辑库中的数据脱敏规则。 |
-| `shardingsphere://features/mask/databases/{database}/tables/{table}/rules` |
读取一个逻辑表的数据脱敏规则。 |
+| 资源 URI 或模板 | 类型 | 用途 |
+| --- | --- | --- |
+| `shardingsphere://capabilities` | 资源 URI | 查看资源
URI、资源模板、工具、提示、补全、工作流关系和副作用提示。 |
+| `shardingsphere://runtime` | 资源 URI | 查看当前传输方式、运行状态和已配置运行时数据库摘要。 |
+| `shardingsphere://databases` | 资源 URI | 列出当前 MCP Server 可以访问的运行时数据库；连接 Proxy
时对应 ShardingSphere 逻辑库。 |
+| `shardingsphere://databases/{database}` | 资源模板 | 读取一个运行时数据库的详情和元数据摘要。 |
+| `shardingsphere://databases/{database}/capabilities` | 资源模板 | 读取一个运行时数据库的
SQL、事务、schema 和元数据对象能力。 |
+| `shardingsphere://databases/{database}/schemas` | 资源模板 | 列出一个运行时数据库中的 schema
或 namespace。 |
+| `shardingsphere://databases/{database}/schemas/{schema}` | 资源模板 | 读取一个
schema 或 namespace 的详情。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | 资源模板 |
列出一个 schema 中的 sequence。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
资源模板 | 读取一个 sequence 的详情。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` | 资源模板 |
列出一个 schema 中的表。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
资源模板 | 读取一个表的详情。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| 资源模板 | 列出一个表的列。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| 资源模板 | 读取一个表列的详情。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| 资源模板 | 列出一个表的索引。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| 资源模板 | 读取一个表索引的详情。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/views` | 资源模板 | 列出一个
schema 中的视图。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` | 资源模板
| 读取一个视图的详情。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
资源模板 | 列出一个视图的列。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| 资源模板 | 读取一个视图列的详情。 |
+| `shardingsphere://workflows/{plan_id}` | 资源模板 |
读取当前会话中的工作流计划、补问信息、变更产物和下一步动作。 |
+
+功能插件提供的资源在对应插件页面说明。
## 工具
@@ -85,24 +81,29 @@ ShardingSphere-MCP 的协议表面是统一的，但运行时可用性取决于
## 补全目标
-| 目标类型 | 目标 | 补全参数 |
-| --- | --- | --- |
-| resource | `shardingsphere://databases/{database}` | `database` |
-| resource | `shardingsphere://databases/{database}/schemas` | `database` |
-| resource | `shardingsphere://databases/{database}/schemas/{schema}` |
`database`、`schema` |
-| resource | `shardingsphere://databases/{database}/schemas/{schema}/tables` |
`database`、`schema` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
`database`、`schema`、`table` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| `database`、`schema`、`table` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| `database`、`schema`、`table`、`column` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| `database`、`schema`、`table` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| `database`、`schema`、`table`、`index` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/sequences` |
`database`、`schema` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
`database`、`schema`、`sequence` |
-| resource | `shardingsphere://workflows/{plan_id}` | `plan_id` |
-| resource | `shardingsphere://features/encrypt/algorithms` |
`algorithm_type`、`assisted_query_algorithm_type`、`like_query_algorithm_type` |
-| resource | `shardingsphere://features/mask/algorithms` | `algorithm_type` |
-| prompt | `inspect_metadata` | `database`、`schema` |
-| prompt | `safe_sql_execution` | `database`、`schema` |
-| prompt | `recover_workflow` | `plan_id` |
-| prompt | `plan_encrypt_rule` |
`database`、`schema`、`table`、`column`、`algorithm_type`、`assisted_query_algorithm_type`、`like_query_algorithm_type`、`plan_id`
|
-| prompt | `plan_mask_rule` |
`database`、`schema`、`table`、`column`、`algorithm_type`、`plan_id` |
+### 资源补全目标
+
+| 目标 | 补全参数 |
+| --- | --- |
+| `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` |
+| `plan_encrypt_rule` |
`database`、`schema`、`table`、`column`、`algorithm_type`、`assisted_query_algorithm_type`、`like_query_algorithm_type`、`plan_id`
|
+| `plan_mask_rule` |
`database`、`schema`、`table`、`column`、`algorithm_type`、`plan_id` |
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
index b3447eb7748..512fab9fdab 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
@@ -1,21 +1,26 @@
+++
-title = "Capabilities"
+title = "Capability Catalog"
weight = 2
+++
-This page lists the protocol capabilities exposed by ShardingSphere-MCP.
-The runtime source of truth is `shardingsphere://capabilities` plus the
official MCP list methods.
+This page explains the core capabilities of ShardingSphere-MCP and how
protocol methods, resource URIs, tools, and prompts relate to each other.
+The documentation explains capability semantics. Clients should use MCP list
methods and `shardingsphere://capabilities` to read what the current MCP Server
actually exposes.
-## Discovery entry points
+## Capability discovery
-| Protocol capability | Purpose |
-| --- | --- |
-| `tools/list` | Discover callable tools. |
-| `resources/list` | Discover directly readable resources. |
-| `resources/templates/list` | Discover parameterized resource templates. |
-| `prompts/list` | Discover available prompts. |
-| `completion/complete` | Get completion candidates for resources, prompts, or
arguments. |
-| `resources/read` with `shardingsphere://capabilities` | Read the
ShardingSphere domain capability catalog. |
+The following entries include MCP protocol methods and ShardingSphere-MCP
resource URIs.
+MCP protocol methods do not use the `shardingsphere://` prefix. That prefix is
used only for ShardingSphere-MCP resource URIs.
+Tools and prompts are invoked by name and are not resource URIs.
+
+| Method or resource | Type | Purpose |
+| --- | --- | --- |
+| `tools/list` | MCP protocol method | Lists callable tools. |
+| `resources/list` | MCP protocol method | Lists resources that can be read
without template arguments. |
+| `resources/templates/list` | MCP protocol method | Lists parameterized
resource URI templates. Clients fill the template before reading it through
`resources/read`. |
+| `resources/read` | MCP protocol method | Reads one concrete resource URI.
Reading `shardingsphere://capabilities` returns the ShardingSphere domain
capability catalog. |
+| `prompts/list` | MCP protocol method | Lists available prompts. |
+| `completion/complete` | MCP protocol method | Gets completion candidates for
resources, prompts, or arguments. |
+| `shardingsphere://capabilities` | ShardingSphere-MCP resource URI | Reads
the ShardingSphere domain capability catalog. |
## Capability Availability
@@ -25,41 +30,32 @@ ShardingSphere-MCP exposes one protocol surface, but
runtime availability depend
- When connected to a physical database, general JDBC metadata and SQL
execution capabilities are available. ShardingSphere rules, algorithm plugins,
and workflows that depend on DistSQL do not apply.
- Clients should read `shardingsphere://runtime` and
`shardingsphere://databases/{database}/capabilities` before assuming that every
resource or tool behaves the same for every connection target.
-## Static resources
-
-| Resource | Purpose |
-| --- | --- |
-| `shardingsphere://capabilities` | Read resources, resource templates, tools,
prompts, completions, workflow relationships, and side-effect notes. |
-| `shardingsphere://runtime` | Read the current transport, runtime status, and
configured runtime database summary. |
-| `shardingsphere://databases` | List runtime databases reachable by the
current MCP Server. When connected to Proxy, they correspond to ShardingSphere
logical databases. |
-| `shardingsphere://features/encrypt/algorithms` | List data encryption
algorithm plugins visible from the current ShardingSphere-Proxy runtime. |
-| `shardingsphere://features/mask/algorithms` | List data masking algorithm
plugins visible from the current ShardingSphere-Proxy runtime. |
-
-## Resource templates
+## Resources
-| Resource template | Purpose |
-| --- | --- |
-| `shardingsphere://databases/{database}` | Read one runtime database and its
metadata summary. |
-| `shardingsphere://databases/{database}/capabilities` | Read SQL,
transaction, schema, and metadata-object capabilities for one runtime database.
|
-| `shardingsphere://databases/{database}/schemas` | List schemas or namespaces
inside one runtime database. |
-| `shardingsphere://databases/{database}/schemas/{schema}` | Read one schema
or namespace. |
-| `shardingsphere://databases/{database}/schemas/{schema}/sequences` | List
sequences in one schema. |
-|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
Read one sequence. |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables` | List
tables in one schema. |
-| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
Read one table. |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| List columns for one table. |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| Read one table column. |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| List indexes for one table. |
-|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| Read one table index. |
-| `shardingsphere://databases/{database}/schemas/{schema}/views` | List views
in one schema. |
-| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` | Read
one view. |
-|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
List columns for one view. |
-|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| Read one view column. |
-| `shardingsphere://workflows/{plan_id}` | Read a current-session workflow
plan, clarification questions, artifacts, and next actions. |
-| `shardingsphere://features/encrypt/databases/{database}/rules` | List data
encryption rules in one logical database. |
-|
`shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules` |
Read data encryption rules for one logical table. |
-| `shardingsphere://features/mask/databases/{database}/rules` | List data
masking rules in one logical database. |
-| `shardingsphere://features/mask/databases/{database}/tables/{table}/rules` |
Read data masking rules for one logical table. |
+| Resource URI or template | Type | Purpose |
+| --- | --- | --- |
+| `shardingsphere://capabilities` | Resource URI | Reads resource URIs,
resource templates, tools, prompts, completions, workflow relationships, and
side-effect notes. |
+| `shardingsphere://runtime` | Resource URI | Reads the current transport,
runtime status, and configured runtime database summary. |
+| `shardingsphere://databases` | Resource URI | Lists runtime databases
reachable by the current MCP Server. When connected to Proxy, they correspond
to ShardingSphere logical databases. |
+| `shardingsphere://databases/{database}` | Resource template | Reads one
runtime database and its metadata summary. |
+| `shardingsphere://databases/{database}/capabilities` | Resource template |
Reads SQL, transaction, schema, and metadata-object capabilities for one
runtime database. |
+| `shardingsphere://databases/{database}/schemas` | Resource template | Lists
schemas or namespaces inside one runtime database. |
+| `shardingsphere://databases/{database}/schemas/{schema}` | Resource template
| Reads one schema or namespace. |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` |
Resource template | Lists sequences in one schema. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
Resource template | Reads one sequence. |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` | Resource
template | Lists tables in one schema. |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
Resource template | Reads one table. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| Resource template | Lists columns for one table. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| Resource template | Reads one table column. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| Resource template | Lists indexes for one table. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| Resource template | Reads one table index. |
+| `shardingsphere://databases/{database}/schemas/{schema}/views` | Resource
template | Lists views in one schema. |
+| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` |
Resource template | Reads one view. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
Resource template | Lists columns for one view. |
+|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| Resource template | Reads one view column. |
+| `shardingsphere://workflows/{plan_id}` | Resource template | Reads a
current-session workflow plan, clarification questions, artifacts, and next
actions. |
+
+Feature plugin resources are documented on the corresponding plugin pages.
## Tools
@@ -85,24 +81,29 @@ ShardingSphere-MCP exposes one protocol surface, but
runtime availability depend
## Completion targets
-| Target type | Target | Completed arguments |
-| --- | --- | --- |
-| resource | `shardingsphere://databases/{database}` | `database` |
-| resource | `shardingsphere://databases/{database}/schemas` | `database` |
-| resource | `shardingsphere://databases/{database}/schemas/{schema}` |
`database`, `schema` |
-| resource | `shardingsphere://databases/{database}/schemas/{schema}/tables` |
`database`, `schema` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}` |
`database`, `schema`, `table` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns`
| `database`, `schema`, `table` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}`
| `database`, `schema`, `table`, `column` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes`
| `database`, `schema`, `table` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}`
| `database`, `schema`, `table`, `index` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/sequences` |
`database`, `schema` |
-| resource |
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
`database`, `schema`, `sequence` |
-| resource | `shardingsphere://workflows/{plan_id}` | `plan_id` |
-| resource | `shardingsphere://features/encrypt/algorithms` |
`algorithm_type`, `assisted_query_algorithm_type`, `like_query_algorithm_type` |
-| resource | `shardingsphere://features/mask/algorithms` | `algorithm_type` |
-| prompt | `inspect_metadata` | `database`, `schema` |
-| prompt | `safe_sql_execution` | `database`, `schema` |
-| prompt | `recover_workflow` | `plan_id` |
-| prompt | `plan_encrypt_rule` | `database`, `schema`, `table`, `column`,
`algorithm_type`, `assisted_query_algorithm_type`, `like_query_algorithm_type`,
`plan_id` |
-| prompt | `plan_mask_rule` | `database`, `schema`, `table`, `column`,
`algorithm_type`, `plan_id` |
+### 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` |
+| `plan_encrypt_rule` | `database`, `schema`, `table`, `column`,
`algorithm_type`, `assisted_query_algorithm_type`, `like_query_algorithm_type`,
`plan_id` |
+| `plan_mask_rule` | `database`, `schema`, `table`, `column`,
`algorithm_type`, `plan_id` |
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
index fe05a12a1f8..f06453ff9f1 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,8 +3,23 @@ title = "客户端集成"
weight = 4
+++
-MCP 客户端可以通过 Streamable HTTP 或 STDIO 连接 ShardingSphere-MCP。
-客户端应优先使用 MCP 官方能力发现方法获取工具、资源、提示和补全列表，再按任务发起调用。
+客户端集成面向把 ShardingSphere-MCP 接入桌面客户端、IDE 插件、Agent 平台或自研 LLM 应用的场景。
+它不是快速开始中 curl 手工验证流程的替代说明。
+它的价值是让客户端负责连接配置、会话头、能力发现、补全和调用编排，用户只关注要完成的元数据或数据库治理任务。
+
+适合使用客户端集成的场景：
+
+- 已有 MCP 客户端，需要把 ShardingSphere 元数据和治理工具暴露给模型。
+- 需要长期复用同一个 MCP Server 配置，而不是每次手写 curl 请求。
+- 需要客户端保存 HTTP 会话头，或通过 STDIO 管理本地 MCP Server 子进程。
+- 需要按任务发现工具、资源、提示和补全目标，避免在客户端硬编码完整能力清单。
+
+如果只是验证 MCP Server 是否可用，使用快速开始中的 curl 示例即可。
+
+## 选择传输方式
+
+- HTTP 适合 MCP Server 独立启动，客户端通过固定端点访问的场景。客户端需要完成会话初始化，并在后续请求中携带会话响应头。
+- STDIO 适合本地 MCP 客户端拉起 ShardingSphere-MCP 子进程的场景。客户端负责进程生命周期，stdout 只传输 MCP
协议帧。
## HTTP 配置
@@ -51,7 +66,7 @@ STDIO 模式下：
## 能力发现
-MCP 官方列表方法用于发现协议层能力；`shardingsphere://capabilities` 用于理解 ShardingSphere 领域能力。
+MCP 列表方法用于发现协议层能力；`shardingsphere://capabilities` 用于理解 ShardingSphere 领域能力。
客户端不需要固定调用顺序，可以按任务需要选择。
| 能力 | 作用 |
@@ -80,11 +95,35 @@ MCP 官方列表方法用于发现协议层能力；`shardingsphere://capabiliti
搜索元数据：
```json
-{"jsonrpc":"2.0","id":"search-1","method":"tools/call","params":{"name":"database_gateway_search_metadata","arguments":{"database":"<logic-database>","query":"<metadata-keyword>","object_types":["table"]}}}
+{
+ "jsonrpc": "2.0",
+ "id": "search-1",
+ "method": "tools/call",
+ "params": {
+ "name": "database_gateway_search_metadata",
+ "arguments": {
+ "database": "<logic-database>",
+ "query": "<metadata-keyword>",
+ "object_types": ["table"]
+ }
+ }
+}
```
执行只读 SQL：
```json
-{"jsonrpc":"2.0","id":"query-1","method":"tools/call","params":{"name":"database_gateway_execute_query","arguments":{"database":"<logic-database>","sql":"SELECT
* FROM <table-name> LIMIT 100","max_rows":100}}}
+{
+ "jsonrpc": "2.0",
+ "id": "query-1",
+ "method": "tools/call",
+ "params": {
+ "name": "database_gateway_execute_query",
+ "arguments": {
+ "database": "<logic-database>",
+ "sql": "SELECT * FROM <table-name> LIMIT 100",
+ "max_rows": 100
+ }
+ }
+}
```
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
index b9610365813..755244bba47 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,8 +3,23 @@ title = "Client Integration"
weight = 4
+++
-MCP clients can connect to ShardingSphere-MCP through Streamable HTTP or STDIO.
-Clients should use official MCP capability discovery methods first, then call
tools, resources, prompts, or completions for the target task.
+Client integration is for desktop clients, IDE extensions, agent platforms, or
custom LLM applications that connect to ShardingSphere-MCP.
+It is not a replacement for the curl-based smoke test in Quick Start.
+Its value is letting the client manage connection configuration, session
headers, capability discovery, completion, and call orchestration while users
focus on metadata or database governance tasks.
+
+Use client integration when:
+
+- An MCP client needs to expose ShardingSphere metadata and governance tools
to a model.
+- The same MCP Server configuration should be reused instead of hand-writing
curl requests.
+- The client needs to keep HTTP session headers or manage a local
ShardingSphere-MCP child process through STDIO.
+- The client needs to discover tools, resources, prompts, and completion
targets per task instead of hardcoding the full capability catalog.
+
+If you only need to verify that the MCP Server is available, use the curl
examples in Quick Start.
+
+## Choose a transport
+
+- HTTP is suitable when the MCP Server is started independently and clients
use a fixed endpoint. The client must initialize the session and keep session
response headers.
+- STDIO is suitable when a local MCP client starts ShardingSphere-MCP as a
child process. The client owns the process lifecycle, and stdout carries only
MCP protocol frames.
## HTTP configuration
@@ -51,7 +66,7 @@ In STDIO mode:
## Capability discovery
-Official MCP list methods discover protocol-level capabilities.
`shardingsphere://capabilities` explains ShardingSphere domain capabilities.
+MCP list methods discover protocol-level capabilities.
`shardingsphere://capabilities` explains ShardingSphere domain capabilities.
Clients do not need a fixed discovery order; call the method or resource that
matches the task.
| Capability | Purpose |
@@ -80,11 +95,35 @@ Read the capability catalog:
Search metadata:
```json
-{"jsonrpc":"2.0","id":"search-1","method":"tools/call","params":{"name":"database_gateway_search_metadata","arguments":{"database":"<logic-database>","query":"<metadata-keyword>","object_types":["table"]}}}
+{
+ "jsonrpc": "2.0",
+ "id": "search-1",
+ "method": "tools/call",
+ "params": {
+ "name": "database_gateway_search_metadata",
+ "arguments": {
+ "database": "<logic-database>",
+ "query": "<metadata-keyword>",
+ "object_types": ["table"]
+ }
+ }
+}
```
Execute read-only SQL:
```json
-{"jsonrpc":"2.0","id":"query-1","method":"tools/call","params":{"name":"database_gateway_execute_query","arguments":{"database":"<logic-database>","sql":"SELECT
* FROM <table-name> LIMIT 100","max_rows":100}}}
+{
+ "jsonrpc": "2.0",
+ "id": "query-1",
+ "method": "tools/call",
+ "params": {
+ "name": "database_gateway_execute_query",
+ "arguments": {
+ "database": "<logic-database>",
+ "sql": "SELECT * FROM <table-name> LIMIT 100",
+ "max_rows": 100
+ }
+ }
+}
```
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
index 98ebd510e01..b678bf67d88 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
@@ -32,15 +32,10 @@ transport:
| --- | --- |
| `transport.type` | 传输方式，支持 `STREAMABLE_HTTP` 和 `STDIO`。 |
| `transport.http` | HTTP 传输配置，只在 `transport.type` 为 `STREAMABLE_HTTP` 时生效。 |
-| `transport.http.bindHost` | HTTP 监听地址，默认值为 `127.0.0.1`。 |
+| `transport.http.bindHost` | HTTP 监听地址，默认值为
`127.0.0.1`。`127.0.0.1`、`localhost`、`::1` 只允许本机访问；`0.0.0.0` 或指定内网 IP
允许对应网络接口访问。 |
| `transport.http.port` | HTTP 监听端口，默认值为 `18088`。 |
| `transport.http.endpointPath` | HTTP 端点路径，默认值为 `/mcp`。 |
-| 监听地址 | 说明 |
-| --- | --- |
-| `127.0.0.1`、`localhost`、`::1` | 只允许本机访问。 |
-| `0.0.0.0` 或指定内网 IP | 允许对应网络接口访问。 |
-
## 数据库配置
`runtimeDatabases` 定义 MCP Server 可以连接并对外暴露的数据库。
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 ec765581a9d..a11854e2622 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
@@ -32,15 +32,10 @@ transport:
| --- | --- |
| `transport.type` | Transport type. Supported values are `STREAMABLE_HTTP`
and `STDIO`. |
| `transport.http` | HTTP transport configuration, used only when
`transport.type` is `STREAMABLE_HTTP`. |
-| `transport.http.bindHost` | HTTP bind host. The default value is
`127.0.0.1`. |
+| `transport.http.bindHost` | HTTP bind host. Defaults to `127.0.0.1`.
Loopback values allow local access only. `0.0.0.0` or an intranet IP allows
access through that interface. |
| `transport.http.port` | HTTP bind port. The default value is `18088`. |
| `transport.http.endpointPath` | HTTP endpoint path. The default value is
`/mcp`. |
-| Bind address | Description |
-| --- | --- |
-| `127.0.0.1`, `localhost`, `::1` | Allows local access only. |
-| `0.0.0.0` or a specific intranet IP | Allows access through the matching
network interface. |
-
## Database configuration
`runtimeDatabases` defines the databases that the MCP Server can connect to
and expose through MCP.
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 cfc68dd0046..6f2aa62e31e 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
@@ -52,8 +52,7 @@ runtimeDatabases:
Unix-like 系统：
```bash
-bin/start.sh > logs/mcp-http.log 2>&1 &
-MCP_PID=$!
+bin/start.sh > logs/mcp-http.log 2>&1 & MCP_PID=$!
```
Windows：
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 e162f6d7c28..7d592dfc267 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
@@ -52,8 +52,7 @@ If the target database driver is not packaged, copy the
corresponding JDBC drive
Unix-like systems:
```bash
-bin/start.sh > logs/mcp-http.log 2>&1 &
-MCP_PID=$!
+bin/start.sh > logs/mcp-http.log 2>&1 & MCP_PID=$!
```
Windows:
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
index 8c7b67f120a..d918639551d 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/workflow.cn.md
@@ -3,11 +3,13 @@ title = "工作流"
weight = 5
+++
-ShardingSphere-MCP 的功能插件可以通过共享工作流机制实现复杂治理任务。
-MCP Server 提供通用工作流机制，插件提供具体业务语义。
+工作流是 ShardingSphere-MCP 处理多步骤治理变更的共享机制。
+当前它主要由功能插件使用：插件负责理解具体业务、生成 `plan_id` 和变更产物。
+MCP Server 负责保存当前会话中的计划，并提供通用的预览、执行、导出和校验工具。
-工作流适合需要规划、审查、执行和校验的多步骤治理变更，例如规划数据加密规则或数据脱敏规则。
-如果只是读取元数据或执行只读 SQL，通常不需要使用工作流。
+用户通常不会为了读取元数据、搜索对象或执行只读 SQL 单独使用工作流。
+只有当插件规划工具返回 `plan_id` 时，才需要继续按照本页完成审查、应用和校验。
+本页独立说明工作流，是因为不同插件共享同一套状态、执行模式和敏感输入处理方式；具体可规划的业务能力仍以各功能插件页面为准。
## 基本阶段
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
index eeabe449e10..d7f0ac4f91b 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/workflow.en.md
@@ -3,11 +3,15 @@ title = "Workflows"
weight = 5
+++
-ShardingSphere-MCP feature plugins can use the shared workflow mechanism to
implement complex governance tasks.
-The MCP Server provides the common workflow mechanism, while each plugin
provides its own business semantics.
-
-Workflows are useful for multi-step governance changes that need planning,
review, execution, and validation, such as planning data encryption or data
masking rules.
-For metadata reads or read-only SQL, workflows are usually unnecessary.
+Workflows are the shared mechanism that ShardingSphere-MCP uses for multi-step
governance changes.
+They are mainly used by feature plugins today.
+A plugin understands the concrete business semantics and creates `plan_id`
plus change artifacts.
+The MCP Server stores the current-session plan and provides common preview,
apply, export, and validation tools.
+
+Users usually do not use workflows just to read metadata, search objects, or
run read-only SQL.
+Follow this page only after a plugin planning tool returns `plan_id`, then
review, apply, and validate that plan.
+This page is separate because multiple plugins share the same state model,
execution modes, and sensitive-input handling.
+The concrete planning capabilities are still documented on the corresponding
feature plugin pages.
## Basic phases
