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 f315a1dc7ed Refine ShardingSphere-MCP client integration docs (#38786)
f315a1dc7ed is described below
commit f315a1dc7ed09d3e21e6c98c4aeeb9fa378c3462
Author: Liang Zhang <[email protected]>
AuthorDate: Wed Jun 3 16:43:04 2026 +0800
Refine ShardingSphere-MCP client integration docs (#38786)
Rework ShardingSphere-MCP documentation around user-facing database tasks
and natural-language usage.
Replace vague homepage setup wording with concrete database connection
prerequisites, simplify quick start by removing generic shutdown steps, and
normalize Chinese terminology for schema, namespace, and sequence in user
docs.
Move client integration into a section page, add Codex and Claude Code
integration examples, and clarify encryption and masking object-name
handling boundaries in both Chinese and English docs.
---
.../user-manual/shardingsphere-mcp/_index.cn.md | 4 +-
.../user-manual/shardingsphere-mcp/_index.en.md | 4 +-
.../shardingsphere-mcp/capabilities.cn.md | 10 +--
.../_index.cn.md} | 6 ++
.../_index.en.md} | 6 ++
.../client-integration/claude-code.cn.md | 78 ++++++++++++++++++++++
.../client-integration/claude-code.en.md | 78 ++++++++++++++++++++++
.../client-integration/codex.cn.md | 50 ++++++++++++++
.../client-integration/codex.en.md | 50 ++++++++++++++
.../shardingsphere-mcp/configuration.cn.md | 6 +-
.../shardingsphere-mcp/developer-appendix.cn.md | 20 +++---
.../shardingsphere-mcp/features/encrypt.cn.md | 6 +-
.../shardingsphere-mcp/features/encrypt.en.md | 4 +-
.../shardingsphere-mcp/features/mask.cn.md | 6 +-
.../shardingsphere-mcp/features/mask.en.md | 4 +-
.../shardingsphere-mcp/quick-start.cn.md | 15 +----
.../shardingsphere-mcp/quick-start.en.md | 15 +----
.../shardingsphere-mcp/troubleshooting.cn.md | 4 +-
18 files changed, 304 insertions(+), 62 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 dfe28604cb6..cef771b19b3 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
@@ -11,7 +11,7 @@ MCP 是连接 AI 应用与外部数据源和工具的开放协议，协议说明
AI 应用开发者可以将 ShardingSphere-MCP 作为受控数据库访问能力接入应用。
接入后，用户可以通过自然语言查看数据库结构、执行受控查询，并规划需要审查的 ShardingSphere 规则变更。
-ShardingSphere-MCP 的配置以数据库为核心：先配置可以连接的 ShardingSphere 逻辑库或普通数据库，再在 AI 应用中完成集成。
+使用前需要准备可连接的数据库，并在 `runtimeDatabases` 中配置连接信息；如果需要使用数据加密、数据脱敏等规则变更能力，连接目标应为
ShardingSphere-Proxy 逻辑库。
## 面向 AI 应用的数据库访问
@@ -33,7 +33,7 @@ ShardingSphere-MCP 面向支持 MCP 的 AI 应用、IDE 插件和 Agent 平台
- 快速开始：构建发行包，配置一个可连接的逻辑库，启动 MCP Server，并在 AI 应用中验证自然语言任务。
- 能力清单：说明用户可以通过自然语言完成的数据库任务和使用边界。
- 配置说明：说明传输方式、`runtimeDatabases`、插件目录和启动参数。
-- 客户端集成：说明如何通过 HTTP 或 STDIO 把 MCP Server 接入 AI 应用，以及集成后的使用方式。
+- 客户端集成：说明如何通过 HTTP 或 STDIO 把 MCP Server 接入 AI 应用，并提供 Codex 和 Claude Code 示例。
- 部署说明：说明发行包、OCI 镜像和安全部署建议。
- 常见问题：排查 MCP Server、连接、配置、元数据和 SQL 执行的通用问题。
- 功能插件：说明官方 MCP 功能插件能力，以及插件变更的审查、执行和校验流程。
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 90daa6c249e..4b784b28a15 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
@@ -11,7 +11,7 @@ MCP is an open protocol for connecting AI applications to
external data sources
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.
-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.
+Before use, prepare a reachable database and configure its connection
information in `runtimeDatabases`. If data encryption, data masking, or other
rule change capabilities are required, the connection target should be a
ShardingSphere-Proxy logical database.
## Database Access for AI Applications
@@ -33,7 +33,7 @@ Tasks with side effects should create or preview a plan
first, then run only aft
- 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 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, with Codex and Claude Code examples.
- Deployment: deploy the binary distribution and OCI image safely.
- Troubleshooting: diagnose common MCP Server, connection, configuration,
metadata, and SQL execution issues.
- Feature Plugins: use official MCP feature plugins and understand how to
review, apply, and validate plugin changes.
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 53d9b248f99..790e723b41f 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
@@ -14,7 +14,7 @@ weight = 2
可用任务包括：
-- 查看逻辑库、schema、表、视图、列、索引和 sequence。
+- 查看逻辑库、模式、表、视图、列、索引和序列。
- 搜索表、视图、列、索引等元数据对象。
- 执行只读 SQL 查询。
- 预览可能修改数据、元数据或规则的 SQL。
@@ -32,7 +32,7 @@ weight = 2
可用任务包括：
-- 查看数据库、schema、表、视图、列、索引和 sequence。
+- 查看数据库、模式、表、视图、列、索引和序列。
- 搜索元数据对象。
- 执行只读 SQL 查询。
- 在明确授权后预览或执行普通 DML、DDL、DCL。
@@ -48,11 +48,11 @@ weight = 2
| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
| --- | --- | --- | --- |
| 查看可访问的数据库 | “列出当前可以访问的逻辑库。” | Proxy 或普通数据库 | 确认数据库名称是否和配置一致。 |
-| 查看 schema 或 namespace | “查看 `<logic-database>` 中有哪些 schema。” | Proxy 或普通数据库
| 多 schema 数据库应先确认目标 schema。 |
-| 查看表或视图 | “列出 `<schema-name>` 中的表和视图。” | Proxy 或普通数据库 | Proxy 连接展示的是逻辑对象。 |
+| 查看模式或命名空间 | “查看 `<logic-database>` 中有哪些模式。” | Proxy 或普通数据库 | 多模式数据库应先确认目标模式。
|
+| 查看表或视图 | “列出目标模式中的表和视图。” | Proxy 或普通数据库 | Proxy 连接展示的是逻辑对象。 |
| 查看列信息 | “查看 `<table-name>` 有哪些列，以及列类型是什么。” | Proxy 或普通数据库 | 列类型以连接目标可见元数据为准。
|
| 查看索引 | “查看 `<table-name>` 的索引。” | Proxy 或普通数据库 | Proxy
连接下索引信息可能不同于底层物理库完整结构。 |
-| 查看 sequence | “列出 `<schema-name>` 中的 sequence。” | Proxy 或普通数据库 | 仅在连接目标支持
sequence 元数据时可用。 |
+| 查看序列 | “列出目标模式中的序列。” | Proxy 或普通数据库 | 仅在连接目标支持序列元数据时可用。 |
## 元数据搜索
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
similarity index 89%
rename from
docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
rename to
docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
index b44dbf3a241..b65dc8b2831 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
@@ -15,6 +15,11 @@ weight = 4
可完成的任务和使用边界见[能力清单](../capabilities/)。
+## 典型客户端
+
+- [Codex](./codex/)：适合在 Codex CLI 或 IDE 扩展中使用 ShardingSphere-MCP。
+- [Claude Code](./claude-code/)：适合在 Claude Code 项目或用户配置中使用 ShardingSphere-MCP。
+
## 选择传输方式
- HTTP 适合 MCP Server 独立启动，AI 应用通过固定端点访问的场景。
@@ -36,6 +41,7 @@ weight = 4
```
不同 AI 应用的配置文件位置和字段名称可能不同，请以应用自身文档为准。
+Codex 和 Claude Code 的配置示例见本章对应子页面。
## STDIO 配置
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
similarity index 91%
rename from
docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
rename to
docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
index a17ca4744ff..4121464db33 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
@@ -15,6 +15,11 @@ Use client integration when:
See [Capability Catalog](../capabilities/) for supported tasks and usage
boundaries.
+## Typical Clients
+
+- [Codex](./codex/): use ShardingSphere-MCP in Codex CLI or IDE extension.
+- [Claude Code](./claude-code/): use ShardingSphere-MCP in Claude Code project
or user configuration.
+
## Choose a Transport
- HTTP is suitable when the MCP Server is started independently and AI
applications use a fixed endpoint.
@@ -36,6 +41,7 @@ Add the following snippet to the AI application's MCP Server
configuration. The
```
Configuration file locations and field names may differ between AI
applications. Follow the documentation of the application you use.
+For Codex and Claude Code examples, see the corresponding pages in this
section.
## STDIO Configuration
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.cn.md
new file mode 100644
index 00000000000..3898d9c1874
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.cn.md
@@ -0,0 +1,78 @@
++++
+title = "Claude Code"
+weight = 2
++++
+
+本页说明如何在 Claude Code 中接入已经启动的 ShardingSphere-MCP HTTP Server，或由 Claude Code
拉起本地 STDIO MCP Server。
+
+## 前置条件
+
+- 已按[快速开始](../../quick-start/)准备 ShardingSphere-MCP 发行包和数据库配置。
+- Claude Code CLI 可用。
+- 使用 HTTP 方式时，Claude Code 所在环境可以访问 `http://127.0.0.1:18088/mcp`，或访问你实际配置的 MCP
Server 地址。
+
+## 添加 HTTP MCP Server
+
+在使用 Claude Code 的项目目录中执行：
+
+```bash
+claude mcp add --transport http shardingsphere http://127.0.0.1:18088/mcp
+```
+
+查看是否添加成功：
+
+```bash
+claude mcp list
+```
+
+在 Claude Code 中运行：
+
+```text
+/mcp
+```
+
+如果希望当前用户的所有 Claude Code 项目都可使用该 MCP Server，可以使用用户级配置：
+
+```bash
+claude mcp add --transport http --scope user shardingsphere
http://127.0.0.1:18088/mcp
+```
+
+也可以在项目根目录创建 `.mcp.json`：
+
+```json
+{
+ "mcpServers": {
+ "shardingsphere": {
+ "type": "http",
+ "url": "http://127.0.0.1:18088/mcp";
+ }
+ }
+}
+```
+
+## 使用 STDIO MCP Server
+
+如果希望 Claude Code 在本地拉起 ShardingSphere-MCP 进程，可以使用 STDIO：
+
+```bash
+claude mcp add --transport stdio shardingsphere -- \
+ /path/to/apache-shardingsphere-mcp/bin/start.sh \
+ /path/to/apache-shardingsphere-mcp/conf/mcp-stdio.yaml
+```
+
+将 `/path/to/apache-shardingsphere-mcp` 替换为实际发行包目录。
+
+## 使用方式
+
+在 Claude Code 中直接描述数据库任务，例如：
+
+- 查看 `<logic-database>` 中有哪些表。
+- 查看 `orders` 表的列和索引。
+- 查询 `orders` 表前 10 行。
+- 为 `orders.status` 规划可逆加密，先预览不要执行。
+
+涉及 SQL 执行或规则变更时，应先审查预览内容，再确认执行。
+
+## 参考
+
+- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.en.md
new file mode 100644
index 00000000000..70c2f0d6756
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.en.md
@@ -0,0 +1,78 @@
++++
+title = "Claude Code"
+weight = 2
++++
+
+This page explains how to connect Claude Code to an already running
ShardingSphere-MCP HTTP Server, or let Claude Code start a local STDIO MCP
Server.
+
+## Prerequisites
+
+- Prepare the ShardingSphere-MCP distribution and database configuration by
following [Quick Start](../../quick-start/).
+- Claude Code CLI is available.
+- For HTTP transport, the Claude Code environment can reach
`http://127.0.0.1:18088/mcp`, or the actual MCP Server address you configured.
+
+## Add an HTTP MCP Server
+
+Run the following command from the project where you use Claude Code:
+
+```bash
+claude mcp add --transport http shardingsphere http://127.0.0.1:18088/mcp
+```
+
+Verify that it has been added:
+
+```bash
+claude mcp list
+```
+
+Run the following command in Claude Code:
+
+```text
+/mcp
+```
+
+To make the MCP Server available across all Claude Code projects for the
current user, use user scope:
+
+```bash
+claude mcp add --transport http --scope user shardingsphere
http://127.0.0.1:18088/mcp
+```
+
+You can also create `.mcp.json` in the project root:
+
+```json
+{
+ "mcpServers": {
+ "shardingsphere": {
+ "type": "http",
+ "url": "http://127.0.0.1:18088/mcp";
+ }
+ }
+}
+```
+
+## Use the STDIO MCP Server
+
+If you want Claude Code to start ShardingSphere-MCP as a local process, use
STDIO:
+
+```bash
+claude mcp add --transport stdio shardingsphere -- \
+ /path/to/apache-shardingsphere-mcp/bin/start.sh \
+ /path/to/apache-shardingsphere-mcp/conf/mcp-stdio.yaml
+```
+
+Replace `/path/to/apache-shardingsphere-mcp` with the actual distribution
directory.
+
+## Usage
+
+Describe database tasks directly in Claude Code, for example:
+
+- Show the tables in `<logic-database>`.
+- Show columns and indexes for the `orders` table.
+- Query the first 10 rows from the `orders` table.
+- Plan reversible encryption for `orders.status` and preview it without
execution.
+
+When SQL execution or rule changes are involved, review the preview content
before confirming execution.
+
+## Reference
+
+- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.cn.md
new file mode 100644
index 00000000000..854ca95e91a
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.cn.md
@@ -0,0 +1,50 @@
++++
+title = "Codex"
+weight = 1
++++
+
+本页说明如何在 Codex 中接入已经启动的 ShardingSphere-MCP HTTP Server。
+
+## 前置条件
+
+- 已按[快速开始](../../quick-start/)启动 HTTP MCP Server。
+- Codex CLI 或 Codex IDE 扩展可用。
+- Codex 所在环境可以访问 `http://127.0.0.1:18088/mcp`，或访问你实际配置的 MCP Server 地址。
+
+## 添加 MCP Server
+
+使用 Codex CLI 添加 ShardingSphere-MCP：
+
+```bash
+codex mcp add shardingsphere --url http://127.0.0.1:18088/mcp
+```
+
+查看是否添加成功：
+
+```bash
+codex mcp list
+```
+
+也可以直接写入 `~/.codex/config.toml`：
+
+```toml
+[mcp_servers.shardingsphere]
+url = "http://127.0.0.1:18088/mcp";
+```
+
+如果 MCP Server 地址不是默认值，请把 URL 替换为实际地址。
+
+## 使用方式
+
+在 Codex 会话中直接描述数据库任务，例如：
+
+- 查看 `<logic-database>` 中有哪些表。
+- 查看 `orders` 表的列和索引。
+- 查询 `orders` 表前 10 行。
+- 为 `orders.phone` 规划脱敏规则，先预览不要执行。
+
+涉及 SQL 执行或规则变更时，应先审查预览内容，再确认执行。
+
+## 参考
+
+- [OpenAI Docs MCP](https://developers.openai.com/learn/docs-mcp)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.en.md
new file mode 100644
index 00000000000..e82f04ca645
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.en.md
@@ -0,0 +1,50 @@
++++
+title = "Codex"
+weight = 1
++++
+
+This page explains how to connect Codex to an already running
ShardingSphere-MCP HTTP Server.
+
+## Prerequisites
+
+- Start the HTTP MCP Server by following [Quick Start](../../quick-start/).
+- Codex CLI or the Codex IDE extension is available.
+- The Codex environment can reach `http://127.0.0.1:18088/mcp`, or the actual
MCP Server address you configured.
+
+## Add the MCP Server
+
+Use Codex CLI to add ShardingSphere-MCP:
+
+```bash
+codex mcp add shardingsphere --url http://127.0.0.1:18088/mcp
+```
+
+Verify that it has been added:
+
+```bash
+codex mcp list
+```
+
+Alternatively, write the configuration directly to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.shardingsphere]
+url = "http://127.0.0.1:18088/mcp";
+```
+
+If the MCP Server address is not the default value, replace the URL with the
actual address.
+
+## Usage
+
+Describe database tasks directly in a Codex session, for example:
+
+- Show the tables in `<logic-database>`.
+- Show columns and indexes for the `orders` table.
+- Query the first 10 rows from the `orders` table.
+- Plan a masking rule for `orders.phone` and preview it without execution.
+
+When SQL execution or rule changes are involved, review the preview content
before confirming execution.
+
+## Reference
+
+- [OpenAI Docs MCP](https://developers.openai.com/learn/docs-mcp)
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 af16c453c1c..cf76088079d 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
@@ -68,7 +68,7 @@ runtimeDatabases:
- 连接 ShardingSphere-Proxy 时，用户看到的是 ShardingSphere 逻辑库，不是底层物理存储单元。
- 连接真实数据库时，用户看到的是该 JDBC 目标的元数据，不代表 ShardingSphere 规则状态。
-- Schema、table、view、index 和 sequence 等元数据依赖目标数据库的 JDBC 元数据；Proxy
和真实数据库的可见结果可能不同。
+- 模式、表、视图、索引和序列等元数据依赖目标数据库的 JDBC 元数据；Proxy 和真实数据库的可见结果可能不同。
- 如果目标 JDBC 驱动没有随发行包提供，请把驱动 jar 放入 `plugins/`。
## 连接目标与能力边界
@@ -86,7 +86,7 @@ runtimeDatabases:
该模式受 Proxy 能力限制：
-- JDBC 元数据、`information_schema`、索引、sequence 和列类型信息以 Proxy
暴露结果为准，不等同于完整底层物理库元数据。
+- JDBC 元数据、`information_schema`、索引、序列和列类型信息以 Proxy 暴露结果为准，不等同于完整底层物理库元数据。
- 物理列、物理索引和多存储节点一致性不作为 MCP 自动确认的稳定契约。
- 可用规则变更语句、规则类型和算法插件取决于 Proxy 版本、已安装插件和当前账号权限。
- 物理变更语句应先审查；只有 Proxy 能安全路由并执行时才适合自动应用。
@@ -95,7 +95,7 @@ runtimeDatabases:
该模式只适合把 MCP 作为通用 JDBC 元数据和 SQL 入口使用，适合以下能力：
-- 浏览 database、schema、table、view、column、index 和 sequence 等 JDBC 元数据。
+- 浏览数据库、模式、表、视图、列、索引和序列等 JDBC 元数据。
- 搜索元数据。
- 执行通用只读查询，或在明确授权后执行普通 DML、DDL、DCL。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
index 899b1b4ee5b..b7f87017851 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
@@ -12,11 +12,11 @@ weight = 9
| --- | --- | --- |
| `tools/list` | 当前 MCP Server 暴露的工具。 | 自研客户端构建可调用动作清单。 |
| `resources/list` | 当前 MCP Server 暴露的静态资源。 | 自研客户端读取固定上下文。 |
-| `resources/templates/list` | 当前 MCP Server 暴露的资源模板。 |
自研客户端按数据库、schema、表等参数读取上下文。 |
+| `resources/templates/list` | 当前 MCP Server 暴露的资源模板。 |
自研客户端按数据库、模式、表等参数读取上下文。 |
| `prompts/list` | 当前 MCP Server 暴露的提示。 | 自研客户端读取任务引导模板。 |
-| `completion/complete` | 指定参数的补全候选值。 | 自研客户端为数据库、schema、表、列等名称提供补全。 |
+| `completion/complete` | 指定参数的补全候选值。 | 自研客户端为数据库、模式、表、列等名称提供补全。 |
| `shardingsphere://capabilities` | 运行时数据库、连接目标、功能插件和副作用边界。 | 判断当前 MCP Server
可用于哪些数据库任务。 |
-| `shardingsphere://databases/{database}/capabilities` | 指定运行时数据库的
SQL、事务、schema 和元数据对象能力。 | 判断某个数据库的可用操作和限制。 |
+| `shardingsphere://databases/{database}/capabilities` | 指定运行时数据库的
SQL、事务、模式和元数据对象能力。 | 判断某个数据库的可用操作和限制。 |
## 资源
@@ -26,18 +26,18 @@ weight = 9
| `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}/capabilities` | 读取一个运行时数据库的
SQL、事务、模式和元数据对象能力。 |
+| `shardingsphere://databases/{database}/schemas` | 列出一个运行时数据库中的模式或命名空间。 |
+| `shardingsphere://databases/{database}/schemas/{schema}` | 读取一个模式或命名空间的详情。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/sequences` |
列出一个模式中的序列。 |
+|
`shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}` |
读取一个序列的详情。 |
+| `shardingsphere://databases/{database}/schemas/{schema}/tables` | 列出一个模式中的表。
|
| `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` | 列出一个模式中的视图。
|
| `shardingsphere://databases/{database}/schemas/{schema}/views/{view}` |
读取一个视图的详情。 |
|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns` |
列出一个视图的列。 |
|
`shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}`
| 读取一个视图列的详情。 |
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 abf2a1e9aa6..5a2ea658030 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
@@ -33,7 +33,7 @@ weight = 2
| 信息 | 说明 | 示例 |
| --- | --- | --- |
| 逻辑库、表和列 | 指定要配置加密规则的 ShardingSphere-Proxy 逻辑对象。 | “为
`<logic-database>.orders.status` 配置加密。” |
-| schema 或 namespace | 多 schema 逻辑库建议说明。 | “schema 是 `public`。” |
+| 模式或命名空间 | 多模式逻辑库建议说明。 | “模式是 `public`。” |
| 操作类型 | 创建、修改或删除加密规则。 | “新增加密规则”或“删除这个列的加密规则”。 |
| 加密目标 | 说明是否需要可逆加密、等值查询或模糊查询。 | “需要可逆加密，并支持等值查询。” |
| 算法偏好 | 可以指定算法，也可以要求 MCP 根据可用算法推荐。 | “优先使用 AES。” |
@@ -103,6 +103,6 @@ MCP 会根据逻辑列、用户意图和已有规则生成派生列建议。
- 不处理已有数据迁移或回填。
-### SQL 生成边界
+### 对象名处理边界
-- MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 标识符。为保证生成的 SQL
或规则变更语句可审查，标识符内容不能包含反引号、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 855615d9764..7a8763f96c6 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
@@ -103,6 +103,6 @@ For the general review flow of rule changes, see [Rule
Change Flow](../plugin-wo
- Existing data migration or backfill is not handled.
-### SQL generation boundaries
+### Identifier handling boundaries
-- 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.
+- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode object
names. To keep generated SQL or rule change statements reviewable, object name
content must not contain backticks, NUL, carriage returns, or line feeds.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
index a77e8c64116..d017febcbf8 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
@@ -33,7 +33,7 @@ weight = 3
| 信息 | 说明 | 示例 |
| --- | --- | --- |
| 逻辑库、表和列 | 指定要配置脱敏规则的 ShardingSphere-Proxy 逻辑对象。 | “为
`<logic-database>.orders.phone` 配置脱敏。” |
-| schema 或 namespace | 多 schema 逻辑库建议说明。 | “schema 是 `public`。” |
+| 模式或命名空间 | 多模式逻辑库建议说明。 | “模式是 `public`。” |
| 操作类型 | 创建、修改或删除脱敏规则。 | “新增脱敏规则”或“删除这个列的脱敏规则”。 |
| 脱敏目标 | 说明保留位数、替换字符或其他脱敏效果。 | “手机号保留前 3 后 4，中间用 `*` 替换。” |
| 算法偏好 | 可以指定算法，也可以要求 MCP 根据可用算法推荐。 | “优先使用 keep-first-n-last-m 算法。” |
@@ -87,6 +87,6 @@ weight = 3
- 逻辑列和规则校验以 Proxy 可见信息为准。
- 直连真实数据库只能执行普通 SQL，不代表脱敏规则状态。
-### SQL 生成边界
+### 对象名处理边界
-- MCP 会处理带引号、大小写敏感、关键字、空格和 Unicode 标识符。为保证生成的 SQL
或规则变更语句可审查，标识符内容不能包含反引号、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 0a14eb40225..33ddd4be7a6 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
@@ -87,6 +87,6 @@ For the general review flow of rule changes, see [Rule Change
Flow](../plugin-wo
- Logical column and rule validation are based on what Proxy exposes.
- Direct physical database connections can execute ordinary SQL only and do
not represent masking rule state.
-### SQL generation boundaries
+### Identifier handling boundaries
-- 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.
+- MCP handles quoted, case-sensitive, keyword, whitespace, and Unicode object
names. To keep generated SQL or rule change statements reviewable, object name
content must not contain backticks, NUL, carriage returns, or line feeds.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/quick-start.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/quick-start.cn.md
index fe1b4c6749a..eb00151845d 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,7 +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 &
```
Windows：
@@ -62,7 +62,6 @@ 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`，方便最后停止服务。
## 接入 AI 应用
@@ -91,15 +90,3 @@ Unix-like 示例会在当前终端后台启动 MCP Server，并把进程号保
如果可以返回逻辑库、表结构或查询结果，说明 MCP Server 已经可以通过 AI 应用访问目标 ShardingSphere-Proxy 逻辑库。
如果 AI 应用无法连接或看不到逻辑库，请查看[常见问题](../troubleshooting/)。
-
-## 关闭服务
-
-Unix-like 系统：
-
-```bash
-kill "${MCP_PID}"
-```
-
-Windows：
-
-在 `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 29e81361815..3107852d2e1 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,7 +52,7 @@ If the target database driver is not provided with the
distribution, put the cor
Unix-like systems:
```bash
-bin/start.sh > logs/mcp-http.log 2>&1 & MCP_PID=$!
+bin/start.sh > logs/mcp-http.log 2>&1 &
```
Windows:
@@ -62,7 +62,6 @@ 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 saves the
process ID in `MCP_PID` for shutdown.
## Connect an AI Application
@@ -91,15 +90,3 @@ After configuration, enter the following tasks in the AI
application to verify t
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/).
-
-## Stop the Service
-
-Unix-like systems:
-
-```bash
-kill "${MCP_PID}"
-```
-
-Windows:
-
-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 51ef62d4d4c..c03c2122c99 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -15,9 +15,9 @@ weight = 7
| 远程访问 HTTP 服务失败 | HTTP 绑定地址、安全策略或网关配置不正确。 |
本机调试用回环地址；远程访问放在受控网关或反向代理后面；详细原因看服务端日志。 |
| STDIO 模式没有响应 | 用户直接把 STDIO 当成命令行交互入口，或 AI 应用没有正确拉起进程。 | 由 AI 应用拉起
ShardingSphere-MCP；诊断信息看 stderr 或 `logs/mcp.log`。 |
| 看不到逻辑库 | 未配置逻辑库、逻辑库名称不正确、连接失败、权限不足，或目标范围确实为空。 | 确认
`runtimeDatabases`、逻辑库名称、连接错误分类和账号权限。 |
-| 查不到表、列或索引 | 连接目标不同、schema 不正确、账号权限不足，或 Proxy 暴露的逻辑元数据与底层物理库不同。 | 先确认连接的是
ShardingSphere-Proxy 还是普通数据库，再检查 schema、账号权限和 Proxy 可见元数据。 |
+| 查不到表、列或索引 | 连接目标不同、模式不正确、账号权限不足，或 Proxy 暴露的逻辑元数据与底层物理库不同。 | 先确认连接的是
ShardingSphere-Proxy 还是普通数据库，再检查模式、账号权限和 Proxy 可见元数据。 |
| JDBC 驱动错误 | 驱动不在类路径，或 `driverClassName` 不正确。 | 把驱动 jar 放入 `plugins/`，并确认
`driverClassName` 非空且类名正确。 |
-| 只读查询失败 | SQL 语法、目标表名、schema、权限或返回行数限制不正确。 | 先让 AI 应用查看表结构，再执行只读查询，并限制返回行数。 |
+| 只读查询失败 | SQL 语法、目标表名、模式、权限或返回行数限制不正确。 | 先让 AI 应用查看表结构，再执行只读查询，并限制返回行数。 |
| 有副作用 SQL 无法执行 | SQL 类型有副作用，或未先预览和确认。 | 先要求预览变更 SQL，审查影响范围后再确认执行。 |
| 加密或脱敏计划无法生成 | 连接目标不是 Proxy、目标列不可见、算法不可用，或缺少必要参数。 | 确认 `runtimeDatabases` 指向
Proxy 逻辑库，并补充逻辑库、表、列、算法和参数。 |
| 规则变更执行后校验不通过 | 规则未成功执行、权限不足、元数据未刷新，或人工执行包未完成执行。 |
查看规则变更计划、执行结果和日志；人工执行后再发起校验。 |
