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 159c9e657e8 Refine MCP documentation examples (#39025)
159c9e657e8 is described below
commit 159c9e657e8d941d8b8441a9fd1848c91efea452
Author: Liang Zhang <[email protected]>
AuthorDate: Tue Jul 7 13:44:24 2026 +0800
Refine MCP documentation examples (#39025)
- Replace template-style MCP docs placeholders with concrete sample values
- Use runtime environment variables for remote MCP endpoints instead of
fake domains
- Keep secret placeholder guidance while renaming YAML rejection test inputs
---
.../user-manual/shardingsphere-mcp/_index.cn.md | 8 +--
.../user-manual/shardingsphere-mcp/_index.en.md | 8 +--
.../shardingsphere-mcp/capabilities.cn.md | 14 +++---
.../shardingsphere-mcp/capabilities.en.md | 14 +++---
.../client-integration/_index.cn.md | 4 +-
.../client-integration/_index.en.md | 4 +-
.../anthropic-mcp-connector.cn.md | 57 +++++++++++-----------
.../anthropic-mcp-connector.en.md | 57 +++++++++++-----------
.../chatgpt-developer-mode.cn.md | 2 +-
.../chatgpt-developer-mode.en.md | 2 +-
.../client-integration/claude-code.cn.md | 2 +-
.../client-integration/claude-code.en.md | 2 +-
.../client-integration/codex.cn.md | 2 +-
.../client-integration/codex.en.md | 2 +-
.../client-integration/openai-responses-api.cn.md | 8 ++-
.../client-integration/openai-responses-api.en.md | 8 ++-
.../shardingsphere-mcp/configuration.cn.md | 10 ++--
.../shardingsphere-mcp/configuration.en.md | 10 ++--
.../shardingsphere-mcp/deployment.cn.md | 18 +++----
.../shardingsphere-mcp/deployment.en.md | 18 +++----
.../shardingsphere-mcp/developer-appendix.cn.md | 12 ++---
.../shardingsphere-mcp/developer-appendix.en.md | 12 ++---
.../shardingsphere-mcp/features/broadcast.cn.md | 2 +-
.../shardingsphere-mcp/features/broadcast.en.md | 2 +-
.../shardingsphere-mcp/features/encrypt.cn.md | 6 +--
.../shardingsphere-mcp/features/encrypt.en.md | 6 +--
.../shardingsphere-mcp/features/mask.cn.md | 6 +--
.../shardingsphere-mcp/features/mask.en.md | 6 +--
.../features/readwrite-splitting.cn.md | 2 +-
.../features/readwrite-splitting.en.md | 2 +-
.../shardingsphere-mcp/features/shadow.cn.md | 2 +-
.../shardingsphere-mcp/features/shadow.en.md | 2 +-
.../shardingsphere-mcp/features/sharding.cn.md | 2 +-
.../shardingsphere-mcp/features/sharding.en.md | 2 +-
.../shardingsphere-mcp/quick-start.cn.md | 16 +++---
.../shardingsphere-mcp/quick-start.en.md | 16 +++---
.../YamlMCPLaunchConfigurationSwapperTest.java | 8 +--
37 files changed, 180 insertions(+), 174 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 86e3ce4951b..421f5ea9da8 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
@@ -20,10 +20,10 @@ ShardingSphere-MCP 面向支持 MCP 的 AI 应用、IDE 插件和 Agent 平台
常见任务示例：
-- 查看 `<logic-database>` 中有哪些表。
-- 查询 `<table-name>` 的字段、索引和表结构。
-- 检查 `<table-name>` 当前是否已有加密或脱敏规则。
-- 为 `<table-name>.<column-name>` 规划脱敏规则，先预览不要执行。
+- 查看 `logic_db` 中有哪些表。
+- 查询 `orders` 的字段、索引和表结构。
+- 检查 `orders` 当前是否已有加密或脱敏规则。
+- 为 `orders.phone` 规划脱敏规则，先预览不要执行。
- 确认刚才的治理变更计划，并校验执行结果。
有副作用的任务应先生成或预览计划，由用户审查变更内容后再执行。
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 1c8a11738ee..ea9c848d5d5 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
@@ -20,10 +20,10 @@ After MCP integration, users can describe database tasks in
natural language in
Common task examples:
-- Show the tables in `<logic-database>`.
-- Inspect columns, indexes, and structure for `<table-name>`.
-- Check whether `<table-name>` already has encryption or masking rules.
-- Plan a masking rule for `<table-name>.<column-name>` and preview it without
execution.
+- Show the tables in `logic_db`.
+- Inspect columns, indexes, and structure for `orders`.
+- Check whether `orders` already has encryption or masking rules.
+- Plan a masking rule for `orders.phone` and preview it without execution.
- Confirm the previous governance change plan and validate the result.
Tasks with side effects should create or preview a plan first, then run only
after the user reviews the 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 c13f4f33805..f2be8ba01b0 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
@@ -48,13 +48,13 @@ weight = 2
| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
| --- | --- | --- | --- |
| 查看可访问的数据库 | “列出当前可以访问的数据库。” | Proxy 或数据库直连 | 确认数据库名称是否和配置一致。 |
-| 查看模式或命名空间 | “查看 `<database-name>` 中有哪些模式。” | Proxy 或数据库直连 | 多模式数据库应先确认目标模式。 |
-| 查看表或视图 | “列出目标模式中的表和视图。” | Proxy 或数据库直连 | Proxy 连接展示的是逻辑对象。 |
-| 查看列信息 | “查看 `<table-name>` 有哪些列，以及列类型是什么。” | Proxy 或数据库直连 | 列类型以连接目标可见元数据为准。
|
-| 查看索引 | “查看 `<table-name>` 的索引。” | Proxy 或数据库直连 | Proxy
连接下索引信息可能不同于底层物理库完整结构。 |
-| 查看序列 | “列出目标模式中的序列。” | Proxy 或数据库直连 | 仅在连接目标支持序列元数据时可用。 |
-| 查看存储单元 | “列出 `<database-name>` 的存储单元。” | 仅 Proxy | 基于 `SHOW STORAGE UNITS
FROM <database-name>`；敏感连接属性会被脱敏或省略。 |
-| 查看存储单元使用情况 | “哪些规则正在使用存储单元 `write_ds`？” | 仅 Proxy | 基于 `SHOW RULES USED
STORAGE UNIT <storage-unit> FROM <database-name>`。 |
+| 查看模式或命名空间 | “查看 `logic_db` 中有哪些模式。” | Proxy 或数据库直连 | 多模式数据库应先确认目标模式。 |
+| 查看表或视图 | “列出 `public` 中的表和视图。” | Proxy 或数据库直连 | Proxy 连接展示的是逻辑对象。 |
+| 查看列信息 | “查看 `orders` 有哪些列，以及列类型是什么。” | Proxy 或数据库直连 | 列类型以连接目标可见元数据为准。 |
+| 查看索引 | “查看 `orders` 的索引。” | Proxy 或数据库直连 | Proxy 连接下索引信息可能不同于底层物理库完整结构。 |
+| 查看序列 | “列出 `public` 中的序列。” | Proxy 或数据库直连 | 仅在连接目标支持序列元数据时可用。 |
+| 查看存储单元 | “列出 `logic_db` 的存储单元。” | 仅 Proxy | 基于 `SHOW STORAGE UNITS FROM
logic_db`；敏感连接属性会被脱敏或省略。 |
+| 查看存储单元使用情况 | “哪些规则正在使用存储单元 `write_ds`？” | 仅 Proxy | 基于 `SHOW RULES USED
STORAGE UNIT write_ds FROM logic_db`。 |
| 查看单表映射 | “单表 `t_user` 在哪个存储单元？” | 仅 Proxy | 基于 `SHOW SINGLE TABLE` 和 `SHOW
SINGLE TABLES`；新增单表默认位置可读取默认单表存储单元资源。 |
## 元数据搜索
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 0702c3b7fe3..f6c2c640aef 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
@@ -48,13 +48,13 @@ Usage boundaries:
| Task | Natural language example | Connection target | User focus |
| --- | --- | --- | --- |
| List accessible databases | "List the databases that can be accessed." |
Proxy or direct database connection | Confirm that database names match the
configuration. |
-| Inspect schemas or namespaces | "Show schemas in `<database-name>`." | Proxy
or direct database connection | For multi-schema databases, confirm the target
schema first. |
-| Inspect tables or views | "List tables and views in `<schema-name>`." |
Proxy or direct database connection | Proxy connections show logical objects. |
-| Inspect columns | "Show columns and column types for `<table-name>`." |
Proxy or direct database connection | Column types follow metadata visible from
the connection target. |
-| Inspect indexes | "Show indexes for `<table-name>`." | Proxy or direct
database connection | With Proxy connections, index information may differ from
the full physical database structure. |
-| Inspect sequences | "List sequences in `<schema-name>`." | Proxy or direct
database connection | Available only when the connection target exposes
sequence metadata. |
-| Inspect storage units | "List storage units in `<database-name>`." | Proxy
only | Backed by `SHOW STORAGE UNITS FROM <database-name>`; sensitive
connection properties are redacted or omitted. |
-| Inspect storage unit usage | "Which rules use storage unit `write_ds`?" |
Proxy only | Backed by `SHOW RULES USED STORAGE UNIT <storage-unit> FROM
<database-name>`. |
+| Inspect schemas or namespaces | "Show schemas in `logic_db`." | Proxy or
direct database connection | For multi-schema databases, confirm the target
schema first. |
+| Inspect tables or views | "List tables and views in `public`." | Proxy or
direct database connection | Proxy connections show logical objects. |
+| Inspect columns | "Show columns and column types for `orders`." | Proxy or
direct database connection | Column types follow metadata visible from the
connection target. |
+| Inspect indexes | "Show indexes for `orders`." | Proxy or direct database
connection | With Proxy connections, index information may differ from the full
physical database structure. |
+| Inspect sequences | "List sequences in `public`." | Proxy or direct database
connection | Available only when the connection target exposes sequence
metadata. |
+| Inspect storage units | "List storage units in `logic_db`." | Proxy only |
Backed by `SHOW STORAGE UNITS FROM logic_db`; sensitive connection properties
are redacted or omitted. |
+| Inspect storage unit usage | "Which rules use storage unit `write_ds`?" |
Proxy only | Backed by `SHOW RULES USED STORAGE UNIT write_ds FROM logic_db`. |
| Inspect single tables | "Which storage unit contains single table `t_user`?"
| Proxy only | Backed by `SHOW SINGLE TABLE` and `SHOW SINGLE TABLES`; use the
default single table storage unit resource for new single tables. |
## Metadata Search
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
index 8799cd4b2a6..c47e9c3b20d 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
@@ -36,8 +36,8 @@ weight = 4
完成配置后，用户可以在对话中直接描述任务，例如：
-- 查看 `<logic-database>` 中有哪些表。
-- 查询 `<table-name>` 的字段和索引。
+- 查看 `logic_db` 中有哪些表。
+- 查询 `orders` 的字段和索引。
- 执行一条只读查询，并限制返回 100 行。
- 调用 `database_gateway_validate_runtime_database` 对已经配置的 runtime database
进行接入前校验。
- 规划一个数据加密或数据脱敏规则，先预览不要执行。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
index 6bd651596c9..2ce1b98bfd7 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
@@ -36,8 +36,8 @@ Local examples such as `http://127.0.0.1:18088/mcp` are only
suitable for local
After configuration, users describe tasks directly in the conversation.
Examples:
-- Show the tables in `<logic-database>`.
-- Inspect columns and indexes for `<table-name>`.
+- Show the tables in `logic_db`.
+- Inspect columns and indexes for `orders`.
- Run a read-only query and limit the result to 100 rows.
- Call `database_gateway_validate_runtime_database` for a configured runtime
database.
- Plan a data encryption or data masking rule and preview it without execution.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.cn.md
index 205eca6903c..cd5137fdf26 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.cn.md
@@ -27,6 +27,7 @@ weight = 5
### 配置接入
+先将 `SHARDINGSPHERE_MCP_REMOTE_URL` 设置为受信网关对外发布的受保护远程 endpoint。
在 Messages API 请求中，先用 `mcp_servers` 声明 ShardingSphere-MCP，再在 `tools`
数组里添加与之对应的 `mcp_toolset`。最小示例如下：
```bash
@@ -35,36 +36,34 @@ curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
- -d '{
- "model": "claude-sonnet-4-5",
- "max_tokens": 1024,
- "messages": [
- {
- "role": "user",
- "content": "Use ShardingSphere-MCP to inspect the tables in the logic
database."
- }
- ],
- "mcp_servers": [
- {
- "type": "url",
- "url": "https://example.com/mcp";,
- "name": "shardingsphere"
- }
- ],
- "tools": [
- {
- "type": "mcp_toolset",
- "mcp_server_name": "shardingsphere"
- }
- ]
- }'
+ -d @- <<EOF
+{
+ "model": "claude-sonnet-4-5",
+ "max_tokens": 1024,
+ "messages": [
+ {
+ "role": "user",
+ "content": "Use ShardingSphere-MCP to inspect the tables in the logic
database."
+ }
+ ],
+ "mcp_servers": [
+ {
+ "type": "url",
+ "url": "${SHARDINGSPHERE_MCP_REMOTE_URL}",
+ "name": "shardingsphere"
+ }
+ ],
+ "tools": [
+ {
+ "type": "mcp_toolset",
+ "mcp_server_name": "shardingsphere"
+ }
+ ]
+}
+EOF
```
-如果受保护的远程 endpoint 或网关使用 OAuth 或 Bearer 认证，可以在 `mcp_servers` 条目中增加：
-
-```json
-"authorization_token": "YOUR_TOKEN"
-```
+如果受保护的远程 endpoint 或网关使用 OAuth 或 Bearer 认证，应从受保护来源读取令牌，并在创建请求时向 `mcp_servers`
条目增加 `authorization_token`。
如果只想暴露一部分工具，可以在 `mcp_toolset` 中使用 `default_config` 和 `configs` 做 allowlist 或
denylist。例如，把默认值设为禁用，再显式启用少量工具：
@@ -95,7 +94,7 @@ curl https://api.anthropic.com/v1/messages \
调用成功：
- 在 Claude 会话中执行一条最小验证任务，例如：
- - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `logic_db` 中有哪些表。
- 查看 `orders` 表的列和索引。
- 对已经配置的 runtime database 调用 `database_gateway_validate_runtime_database`。
- 如果 Claude 能返回来自 ShardingSphere-MCP 的工具结果，说明接入已经生效。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.en.md
index 6c68cfaaf6e..11d845d9861 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.en.md
@@ -27,6 +27,7 @@ This page explains how to connect an already running
ShardingSphere-MCP HTTP Ser
### Configure the integration
+Set `SHARDINGSPHERE_MCP_REMOTE_URL` to the secured remote endpoint published
by the trusted gateway.
In a Messages API request, declare ShardingSphere-MCP in `mcp_servers` first,
then add the matching `mcp_toolset` in the `tools` array. A minimal example is:
```bash
@@ -35,36 +36,34 @@ curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
- -d '{
- "model": "claude-sonnet-4-5",
- "max_tokens": 1024,
- "messages": [
- {
- "role": "user",
- "content": "Use ShardingSphere-MCP to inspect the tables in the logic
database."
- }
- ],
- "mcp_servers": [
- {
- "type": "url",
- "url": "https://example.com/mcp";,
- "name": "shardingsphere"
- }
- ],
- "tools": [
- {
- "type": "mcp_toolset",
- "mcp_server_name": "shardingsphere"
- }
- ]
- }'
+ -d @- <<EOF
+{
+ "model": "claude-sonnet-4-5",
+ "max_tokens": 1024,
+ "messages": [
+ {
+ "role": "user",
+ "content": "Use ShardingSphere-MCP to inspect the tables in the logic
database."
+ }
+ ],
+ "mcp_servers": [
+ {
+ "type": "url",
+ "url": "${SHARDINGSPHERE_MCP_REMOTE_URL}",
+ "name": "shardingsphere"
+ }
+ ],
+ "tools": [
+ {
+ "type": "mcp_toolset",
+ "mcp_server_name": "shardingsphere"
+ }
+ ]
+}
+EOF
```
-If the secured remote endpoint or gateway requires OAuth or Bearer
authentication, add this field to the `mcp_servers` entry:
-
-```json
-"authorization_token": "YOUR_TOKEN"
-```
+If the secured remote endpoint or gateway requires OAuth or Bearer
authentication, read the token from a protected source and add
`authorization_token` to the `mcp_servers` entry at request creation time.
To expose only a subset of tools, use `default_config` and `configs` in the
`mcp_toolset` as an allowlist or denylist. For example, disable everything by
default and enable only a small subset:
@@ -95,7 +94,7 @@ Recognition succeeds when:
Invocation succeeds when:
- In a Claude conversation, run a minimal validation task such as:
- - Show the tables in `<logic-database>`.
+ - Show the tables in `logic_db`.
- Show columns and indexes for the `orders` table.
- Call `database_gateway_validate_runtime_database` for a configured runtime
database.
- If Claude returns tool results from ShardingSphere-MCP, the integration is
working.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.cn.md
index e6cb1242ed5..7ee97e9fdaf 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.cn.md
@@ -45,7 +45,7 @@ weight = 4
调用成功：
- 先执行一条最小验证任务，例如：
- - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `logic_db` 中有哪些表。
- 查看 `orders` 表的列和索引。
- 对已经配置的 runtime database 调用 `database_gateway_validate_runtime_database`。
- 如果 ChatGPT 能识别到对应 app，并能按预期调用导入工具，说明接入已经生效。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.en.md
index 9cbf57cb100..81b30a0247f 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.en.md
@@ -45,7 +45,7 @@ Recognition succeeds when:
Invocation succeeds when:
- Start with a minimal validation task such as:
- - Show the tables in `<logic-database>`.
+ - Show the tables in `logic_db`.
- Show columns and indexes for the `orders` table.
- Call `database_gateway_validate_runtime_database` for a configured runtime
database.
- If ChatGPT recognizes the app and can invoke its imported tools, the
integration is working.
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
index 80287793161..9ee648a1da0 100644
---
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
@@ -75,7 +75,7 @@ claude mcp add --transport stdio shardingsphere -- \
调用成功：
- 在 Claude Code 对话中执行一条最小验证任务，例如：
- - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `logic_db` 中有哪些表。
- 查看 `orders` 表的列和索引。
- 对已经配置的 runtime database 执行 `database_gateway_validate_runtime_database`。
- 如果工具已被列出并能返回查询结果，说明接入已经生效。
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
index 150f775244a..5d56827bb86 100644
---
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
@@ -75,7 +75,7 @@ Recognition succeeds when:
Invocation succeeds when:
- In a Claude Code conversation, run a minimal validation task such as:
- - Show the tables in `<logic-database>`.
+ - Show the tables in `logic_db`.
- Show columns and indexes for the `orders` table.
- Run `database_gateway_validate_runtime_database` against a configured
runtime database.
- If the tools are listed and the validation query succeeds, the integration
is working.
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
index a1ca14ef8dc..0c08ba28693 100644
---
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
@@ -51,7 +51,7 @@ url = "http://127.0.0.1:18088/mcp";
调用成功：
- 在 Codex 会话中执行一条最小验证任务，例如：
- - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `logic_db` 中有哪些表。
- 查看 `orders` 表的列和索引。
- 对已经配置的 runtime database 执行 `database_gateway_validate_runtime_database`。
- 如果工具列表和查询结果可返回，说明接入已经生效。
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
index 8fe128b44f1..587f7031991 100644
---
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
@@ -51,7 +51,7 @@ Recognition succeeds when:
Invocation succeeds when:
- In a Codex session, run a minimal validation task such as:
- - Show the tables in `<logic-database>`.
+ - Show the tables in `logic_db`.
- Show columns and indexes for the `orders` table.
- Run `database_gateway_validate_runtime_database` against a configured
runtime database.
- If the tool list and query results are returned, the integration is working.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.cn.md
index 29685bfb571..b4a6ebf124a 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.cn.md
@@ -29,6 +29,8 @@ weight = 3
在 Responses API 请求中，把 ShardingSphere-MCP 作为 `tools` 中的一个 `mcp` 工具传入。最小示例如下：
```python
+import os
+
from openai import OpenAI
client = OpenAI()
@@ -39,7 +41,7 @@ response = client.responses.create(
{
"type": "mcp",
"server_label": "shardingsphere",
- "server_url": "https://example.com/mcp";,
+ "server_url": os.environ["SHARDINGSPHERE_MCP_REMOTE_URL"],
"allowed_tools": [
"database_gateway_search_metadata",
"database_gateway_validate_runtime_database",
@@ -50,6 +52,8 @@ response = client.responses.create(
)
```
+运行请求前，先将 `SHARDINGSPHERE_MCP_REMOTE_URL` 设置为受信网关对外发布的受保护远程 endpoint。
+
配置时建议关注这些字段：
- `server_label`：当前 MCP Server 的标识名称，后续工具调用和审批事件会引用这个名称。
@@ -69,7 +73,7 @@ response = client.responses.create(
调用成功：
- 可以先用一条最小验证请求确认导入与调用链路，例如：
- - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `logic_db` 中有哪些表。
- 查看 `orders` 表的列和索引。
- 对已经配置的 runtime database 调用 `database_gateway_validate_runtime_database`。
- 当 `mcp_list_tools`、审批流程或最终查询结果按预期返回时，说明接入已经生效。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.en.md
index 60b50eb5c2d..b5d7120e8c3 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.en.md
@@ -29,6 +29,8 @@ This page explains how to connect an already running
ShardingSphere-MCP HTTP Ser
Pass ShardingSphere-MCP as an `mcp` tool in the `tools` array of a Responses
API request. A minimal example is:
```python
+import os
+
from openai import OpenAI
client = OpenAI()
@@ -39,7 +41,7 @@ response = client.responses.create(
{
"type": "mcp",
"server_label": "shardingsphere",
- "server_url": "https://example.com/mcp";,
+ "server_url": os.environ["SHARDINGSPHERE_MCP_REMOTE_URL"],
"allowed_tools": [
"database_gateway_search_metadata",
"database_gateway_validate_runtime_database",
@@ -50,6 +52,8 @@ response = client.responses.create(
)
```
+Set `SHARDINGSPHERE_MCP_REMOTE_URL` to the secured remote endpoint published
by the trusted gateway before running the request.
+
Pay attention to these fields:
- `server_label`: the label used to identify this MCP server in tool calls and
approval events.
@@ -69,7 +73,7 @@ Recognition succeeds when:
Invocation succeeds when:
- Start with a minimal validation request such as:
- - Show the tables in `<logic-database>`.
+ - Show the tables in `logic_db`.
- Show columns and indexes for the `orders` table.
- Call `database_gateway_validate_runtime_database` for a configured runtime
database.
- When `mcp_list_tools`, approval flow events, or final query results appear
as expected, the integration is working.
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 e549d1aac53..1b0102804ff 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
@@ -68,10 +68,10 @@ MCP Server 会从 `jdbcUrl` 解析数据库类型；请使用与该 JDBC URL 匹
```yaml
runtimeDatabases:
- "<logic-database>":
- jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
- username: "<proxy-username>"
- password: "<proxy-password>"
+ "logic_db":
+ jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db"
+ username: "root"
+ password: ""
driverClassName: "com.mysql.cj.jdbc.Driver"
```
@@ -93,7 +93,7 @@ runtimeDatabases:
- 数据库直连时，用户看到的是目标数据库自身的元数据，不代表 ShardingSphere 规则状态。
- 模式、表、视图、索引和序列等元数据依赖连接目标的 JDBC 元数据；Proxy 和数据库直连的可见结果可能不同。
- 如果目标 JDBC 驱动没有随发行包提供，请把驱动 jar 放入 `plugins/`。
-- `<logic-database>` 等占位值只能用于示例。运行时 YAML 文件会拒绝未替换的占位符。
+- `logic_db` 和 `127.0.0.1:3307` 等示例值只用于说明。运行时 YAML 文件会拒绝未替换的尖括号占位符语法。
## 敏感值占位符
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 71b7ba4d1f1..815da3d2506 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
@@ -68,10 +68,10 @@ The MCP Server resolves the database type from `jdbcUrl`;
use a JDBC driver clas
```yaml
runtimeDatabases:
- "<logic-database>":
- jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
- username: "<proxy-username>"
- password: "<proxy-password>"
+ "logic_db":
+ jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db"
+ username: "root"
+ password: ""
driverClassName: "com.mysql.cj.jdbc.Driver"
```
@@ -93,7 +93,7 @@ Notes:
- With a direct database connection, users see metadata from the target
database itself, not ShardingSphere rule state.
- Schema, table, view, index, and sequence metadata depends on JDBC metadata
from the connection target. Proxy-visible metadata and direct-connection
metadata may differ.
- If the target JDBC driver is not packaged, copy the driver jar under
`plugins/`.
-- Keep placeholder values such as `<logic-database>` in examples only. Runtime
YAML files reject unresolved placeholders.
+- The sample values such as `logic_db` and `127.0.0.1:3307` are examples only.
Runtime YAML files reject unresolved angle-bracket placeholder syntax.
## Secret Placeholders
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 ec7292a9f6b..c7f438cdc3c 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
@@ -25,10 +25,10 @@ ShardingSphere-MCP 可以通过源码构建的独立发行包运行，也可以
官方 MCP Registry 元数据位于 `mcp/server.json`。
公开 server name 是 `io.github.apache/shardingsphere-mcp`。
-OCI image 形态是：
+OCI image 示例引用是：
```text
-ghcr.io/apache/shardingsphere-mcp:<version>
+ghcr.io/apache/shardingsphere-mcp:5.5.4
```
OCI 镜像可以使用内置 `conf/mcp-http-docker.yaml` 配置和空的 `runtimeDatabases` 启动。
@@ -44,10 +44,10 @@ transport:
endpointPath: /mcp
runtimeDatabases:
- "<logic-database>":
- jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
- username: "<proxy-username>"
- password: "<proxy-password>"
+ "logic_db":
+ jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db"
+ username: "root"
+ password: ""
driverClassName: "com.mysql.cj.jdbc.Driver"
```
@@ -120,7 +120,7 @@ Nginx 示例：
```nginx
server {
listen 443 ssl http2;
- server_name mcp.example.com;
+ server_name _;
ssl_certificate /etc/nginx/certs/mcp.crt;
ssl_certificate_key /etc/nginx/certs/mcp.key;
@@ -194,7 +194,7 @@ location /mcp {
1. 服务进程与端点可达
- - HTTP 模式确认进程已启动、端口已监听，并且 `http://<bind-host>:<port><endpointPath>`
与客户端配置一致。
+ - HTTP 模式确认进程已启动、端口已监听，并且 `http://127.0.0.1:18088/mcp` 与客户端配置一致。
- STDIO 模式确认由 AI 应用正确拉起 MCP 进程，不把标准输入输出当作交互式 shell 使用。
2. MCP 协议已就绪
@@ -205,7 +205,7 @@ location /mcp {
3. 运行时数据库已就绪
- 读取 `shardingsphere://runtime`，确认 transport、runtime 数据库摘要和运行状态可见。
- - 调用 `database_gateway_validate_runtime_database`，或在 AI 应用中执行“查看
`<logic-database>` 中有哪些表”这类最小任务，确认当前 `runtimeDatabases` 对应的逻辑库可用。
+ - 调用 `database_gateway_validate_runtime_database`，或在 AI 应用中执行“查看 `logic_db`
中有哪些表”这类最小任务，确认当前 `runtimeDatabases` 对应的逻辑库可用。
- 仅有 MCP Server 进程启动并不表示目标运行时数据库已经可用；连接失败、权限不足或逻辑库不可见仍会阻断后续任务。
## 基础可观测入口
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 7fef7281534..8ec2ac51a97 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
@@ -25,10 +25,10 @@ The distribution directory contains:
Official MCP Registry metadata lives in `mcp/server.json`.
The published server name is `io.github.apache/shardingsphere-mcp`.
-The OCI image shape is:
+An example OCI image reference is:
```text
-ghcr.io/apache/shardingsphere-mcp:<version>
+ghcr.io/apache/shardingsphere-mcp:5.5.4
```
The OCI image can start with its built-in `conf/mcp-http-docker.yaml`
configuration and an empty `runtimeDatabases` map.
@@ -44,10 +44,10 @@ transport:
endpointPath: /mcp
runtimeDatabases:
- "<logic-database>":
- jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
- username: "<proxy-username>"
- password: "<proxy-password>"
+ "logic_db":
+ jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db"
+ username: "root"
+ password: ""
driverClassName: "com.mysql.cj.jdbc.Driver"
```
@@ -120,7 +120,7 @@ Nginx example:
```nginx
server {
listen 443 ssl http2;
- server_name mcp.example.com;
+ server_name _;
ssl_certificate /etc/nginx/certs/mcp.crt;
ssl_certificate_key /etc/nginx/certs/mcp.key;
@@ -194,7 +194,7 @@ After deployment, verify that ShardingSphere-MCP is truly
usable instead of stop
1. Service process and endpoint are reachable
- - In HTTP mode, confirm that the process has started, the port is
listening, and `http://<bind-host>:<port><endpointPath>` matches the client
configuration.
+ - In HTTP mode, confirm that the process has started, the port is
listening, and `http://127.0.0.1:18088/mcp` matches the client configuration.
- In STDIO mode, confirm that the AI application launches the MCP process
correctly and does not treat stdin/stdout as an interactive shell.
2. MCP protocol is ready
@@ -205,7 +205,7 @@ After deployment, verify that ShardingSphere-MCP is truly
usable instead of stop
3. Runtime databases are ready
- Read `shardingsphere://runtime` and confirm that the transport, runtime
database summary, and readiness details are visible.
- - Call `database_gateway_validate_runtime_database`, or run a minimal task
such as “Show tables in `<logic-database>`” from the AI application to confirm
that the configured runtime database is usable.
+ - Call `database_gateway_validate_runtime_database`, or run a minimal task
such as “Show tables in `logic_db`” from the AI application to confirm that the
configured runtime database is usable.
- A running MCP Server process alone does not mean that the target runtime
database is ready. Connectivity failures, insufficient privileges, or invisible
logical databases can still block tasks.
## Basic Observability Entrypoints
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 70e94741cd9..27a25b746ca 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
@@ -146,8 +146,8 @@ curl -i -sS http://127.0.0.1:18088/mcp \
curl -sS http://127.0.0.1:18088/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
- -H 'MCP-Session-Id: <MCP-Session-Id value>' \
- -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
+ -H 'MCP-Session-Id: demo-session-id' \
+ -H 'MCP-Protocol-Version: 2025-11-25' \
--data
'{"jsonrpc":"2.0","id":"resource-1","method":"resources/read","params":{"uri":"shardingsphere://databases"}}'
```
@@ -157,8 +157,8 @@ curl -sS http://127.0.0.1:18088/mcp \
curl -sS http://127.0.0.1:18088/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
- -H 'MCP-Session-Id: <MCP-Session-Id value>' \
- -H 'MCP-Protocol-Version: <MCP-Protocol-Version value>' \
+ -H 'MCP-Session-Id: demo-session-id' \
+ -H 'MCP-Protocol-Version: 2025-11-25' \
--data '{
"jsonrpc":"2.0",
"id":"tool-1",
@@ -166,8 +166,8 @@ curl -sS http://127.0.0.1:18088/mcp \
"params":{
"name":"database_gateway_search_metadata",
"arguments":{
- "database":"<logic-database>",
- "query":"<metadata-keyword>",
+ "database":"logic_db",
+ "query":"orders",
"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
index 8bb1ad9960b..3a8cf7f7faa 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
@@ -146,8 +146,8 @@ Read the database list:
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>' \
+ -H 'MCP-Session-Id: demo-session-id' \
+ -H 'MCP-Protocol-Version: 2025-11-25' \
--data
'{"jsonrpc":"2.0","id":"resource-1","method":"resources/read","params":{"uri":"shardingsphere://databases"}}'
```
@@ -157,8 +157,8 @@ Call the metadata search tool:
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>' \
+ -H 'MCP-Session-Id: demo-session-id' \
+ -H 'MCP-Protocol-Version: 2025-11-25' \
--data '{
"jsonrpc":"2.0",
"id":"tool-1",
@@ -166,8 +166,8 @@ curl -sS http://127.0.0.1:18088/mcp \
"params":{
"name":"database_gateway_search_metadata",
"arguments":{
- "database":"<logic-database>",
- "query":"<metadata-keyword>",
+ "database":"logic_db",
+ "query":"orders",
"object_types":["table","view"]
}
}
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/broadcast.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/broadcast.cn.md
index 286470012a3..94af39bfabe 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/broadcast.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/broadcast.cn.md
@@ -14,7 +14,7 @@ weight = 4
## 自然语言示例
-- 查看 `<logic-database>` 当前有哪些广播表规则。
+- 查看 `logic_db` 当前有哪些广播表规则。
- 为 `config_region` 和 `config_feature` 规划广播表规则，先预览不要执行。
- 删除 `config_region` 的广播表规则，并校验结果。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/broadcast.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/broadcast.en.md
index 33cd96dcf3c..2fa38bb023e 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/broadcast.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/broadcast.en.md
@@ -14,7 +14,7 @@ It generates broadcast rule DistSQL only. It does not
generate physical table DD
## Natural language examples
-- List current broadcast table rules in `<logic-database>`.
+- List current broadcast table rules in `logic_db`.
- Plan a broadcast rule for `config_region` and `config_feature`, then preview
it without execution.
- Drop the broadcast rule for `config_region` and validate the result.
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 fe36f7fba7b..9ed9c076caa 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
@@ -20,9 +20,9 @@ weight = 2
示例：
-- 检查 `<logic-database>.orders.status` 当前是否已有加密规则。
+- 检查 `logic_db.orders.status` 当前是否已有加密规则。
- 列出当前 Proxy 可用的数据加密算法。
-- 为 `<logic-database>.orders.status` 规划可逆加密，需要支持等值查询，先预览不要执行。
+- 为 `logic_db.orders.status` 规划可逆加密，需要支持等值查询，先预览不要执行。
- 使用 AES 算法继续刚才的计划，密钥通过受保护渠道提供。
- 确认并执行刚才的加密规则计划，然后校验结果。
@@ -34,7 +34,7 @@ weight = 2
| 信息 | 说明 | 示例
|
|---------|---------------------------------------|--------------------------------------------|
-| 逻辑库、表和列 | 指定要配置加密规则的 ShardingSphere-Proxy 逻辑对象。 | “为
`<logic-database>.orders.status` 配置加密。” |
+| 逻辑库、表和列 | 指定要配置加密规则的 ShardingSphere-Proxy 逻辑对象。 | “为
`logic_db.orders.status` 配置加密。” |
| 模式或命名空间 | 多模式逻辑库建议说明。 | “模式是 `public`。”
|
| 操作类型 | 创建、修改或删除加密规则。 | “新增加密规则”或“删除这个列的加密规则”。
|
| 加密目标 | 说明是否需要可逆加密、等值查询或模糊查询。 | “需要可逆加密，并支持等值查询。”
|
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 30ab840bf6e..c6d75ea0867 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
@@ -20,9 +20,9 @@ Users describe the encryption goal in an AI application that
integrates Sharding
Examples:
-- Check whether `<logic-database>.orders.status` already has an encryption
rule.
+- Check whether `logic_db.orders.status` already has an encryption rule.
- List data encryption algorithms available from the current Proxy.
-- Plan reversible encryption for `<logic-database>.orders.status` with
equality query support, and preview it without execution.
+- Plan reversible encryption for `logic_db.orders.status` with equality query
support, and preview it without execution.
- 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.
@@ -34,7 +34,7 @@ When using natural language, include the following
information when possible:
| Information | Description
| Example
|
|-------------------------------------|--------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
-| Logical database, table, and column | Specify the ShardingSphere-Proxy
logical object to configure. |
"Configure encryption for `<logic-database>.orders.status`."
|
+| Logical database, table, and column | Specify the ShardingSphere-Proxy
logical object to configure. |
"Configure encryption for `logic_db.orders.status`." |
| Schema or namespace | Recommended for multi-schema logical
databases. | "The schema
is `public`." |
| Operation type | Create, alter, or drop an encryption
rule. | "Create an
encryption rule" or "drop the encryption rule for this column." |
| Encryption goal | Describe whether reversible
encryption, equality query, or LIKE query is required. |
"Use reversible encryption and support equality queries."
|
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 1fb38dff8f4..97038f2cfcc 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
@@ -19,9 +19,9 @@ weight = 3
示例：
-- 检查 `<logic-database>.orders.phone` 当前是否已有脱敏规则。
+- 检查 `logic_db.orders.phone` 当前是否已有脱敏规则。
- 列出当前 Proxy 可用的数据脱敏算法。
-- 为 `<logic-database>.orders.phone` 规划手机号脱敏，保留前 3 后 4，先预览不要执行。
+- 为 `logic_db.orders.phone` 规划手机号脱敏，保留前 3 后 4，先预览不要执行。
- 调整刚才的计划，把替换字符改成 `*`。
- 确认并执行刚才的脱敏规则计划，然后校验结果。
@@ -33,7 +33,7 @@ weight = 3
| 信息 | 说明 | 示例
|
|---------|---------------------------------------|--------------------------------------------------------|
-| 逻辑库、表和列 | 指定要配置脱敏规则的 ShardingSphere-Proxy 逻辑对象。 | “为
`<logic-database>.orders.phone` 配置脱敏。” |
+| 逻辑库、表和列 | 指定要配置脱敏规则的 ShardingSphere-Proxy 逻辑对象。 | “为 `logic_db.orders.phone`
配置脱敏。” |
| 模式或命名空间 | 多模式逻辑库建议说明。 | “模式是 `public`。”
|
| 操作类型 | 创建、修改或删除脱敏规则。 | “新增脱敏规则”或“删除这个列的脱敏规则”。
|
| 脱敏目标 | 说明保留位数、替换字符或其他脱敏效果。 | “手机号保留前 3 后 4，中间用 `*` 替换。”
|
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 02459b23a41..5c6e16776b6 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
@@ -19,9 +19,9 @@ Users describe the masking goal in an AI application that
integrates ShardingSph
Examples:
-- Check whether `<logic-database>.orders.phone` already has a masking rule.
+- Check whether `logic_db.orders.phone` already has a masking rule.
- List data masking algorithms available from the current Proxy.
-- Plan phone-number masking for `<logic-database>.orders.phone`, keep the
first 3 and last 4 characters, and preview it without execution.
+- Plan phone-number masking for `logic_db.orders.phone`, keep the first 3 and
last 4 characters, and preview it without execution.
- Adjust the previous plan to use `*` as the replacement character.
- Confirm and execute the previous masking rule plan, then validate the result.
@@ -33,7 +33,7 @@ When using natural language, include the following
information when possible:
| Information | Description
| Example
|
|-------------------------------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
-| Logical database, table, and column | Specify the ShardingSphere-Proxy
logical object to configure. | "Configure masking for
`<logic-database>.orders.phone`."
|
+| Logical database, table, and column | Specify the ShardingSphere-Proxy
logical object to configure. | "Configure masking for
`logic_db.orders.phone`."
|
| Schema or namespace | Recommended for multi-schema logical
databases. | "The schema is `public`."
|
| Operation type | Create, alter, or drop a masking rule.
| "Create a masking rule" or
"drop the masking rule for this column."
|
| Masking goal | Describe retained characters,
replacement characters, or other masking effects. | "Keep the first 3 and
last 4 phone-number characters, and replace the middle part with `*`."
|
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/readwrite-splitting.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/readwrite-splitting.cn.md
index 364b8b160b1..b6c468e7161 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/readwrite-splitting.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/readwrite-splitting.cn.md
@@ -14,7 +14,7 @@ weight = 5
## 自然语言示例
-- 查看 `<logic-database>` 的读写分离规则和负载均衡算法插件。
+- 查看 `logic_db` 的读写分离规则和负载均衡算法插件。
- 规划名为 `rw_ds` 的读写分离规则，写存储单元是 `write_ds`，读存储单元是 `read_ds_0, read_ds_1`。
- 禁用规则 `rw_ds` 中的读存储单元 `read_ds_1`，然后校验状态。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/readwrite-splitting.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/readwrite-splitting.en.md
index 9bd62758577..d1a88e6a483 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/readwrite-splitting.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/readwrite-splitting.en.md
@@ -14,7 +14,7 @@ It generates readwrite-splitting DistSQL only. It does not
generate storage unit
## Natural language examples
-- List readwrite-splitting rules and load-balance algorithm plugins in
`<logic-database>`.
+- List readwrite-splitting rules and load-balance algorithm plugins in
`logic_db`.
- Plan a readwrite-splitting rule named `rw_ds` with write storage unit
`write_ds` and read storage units `read_ds_0, read_ds_1`.
- Disable read storage unit `read_ds_1` for rule `rw_ds`, then validate the
status.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/shadow.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/shadow.cn.md
index 15784ea2f3a..2546d1d746c 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/shadow.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/shadow.cn.md
@@ -14,7 +14,7 @@ weight = 6
## 自然语言示例
-- 查看 `<logic-database>` 已配置的影子规则和影子算法插件。
+- 查看 `logic_db` 已配置的影子规则和影子算法插件。
- 为表 `t_order` 规划影子规则，源存储单元是 `ds_0`，影子存储单元是 `ds_shadow`，算法使用列匹配策略。
- 只有在 Proxy 可见状态证明 `shadow_by_user_id` 未被使用时，才删除这个影子算法。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/shadow.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/shadow.en.md
index aba51321145..b18da7561fb 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/shadow.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/shadow.en.md
@@ -14,7 +14,7 @@ It generates shadow rule DistSQL only. It does not create
shadow databases or ph
## Natural language examples
-- List configured shadow rules and shadow algorithm plugins in
`<logic-database>`.
+- List configured shadow rules and shadow algorithm plugins in `logic_db`.
- Plan a shadow rule for table `t_order` using source storage unit `ds_0`,
shadow storage unit `ds_shadow`, and a column-match algorithm.
- Drop unused shadow algorithm `shadow_by_user_id` only if Proxy-visible state
proves it is unused.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/sharding.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/sharding.cn.md
index 472f77be6a8..9dfe42d4084 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/sharding.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/sharding.cn.md
@@ -14,7 +14,7 @@ weight = 7
## 自然语言示例
-- 查看 `<logic-database>` 的分片表规则、表节点、算法、键生成器、审计器和未使用组件。
+- 查看 `logic_db` 的分片表规则、表节点、算法、键生成器、审计器和未使用组件。
- 为 `t_order` 规划分片表规则，使用明确的数据节点和标准分片策略。
- 规划默认表分片策略，使用算法 `t_order_inline`。
- 只有在 Proxy 可见状态证明 `t_order_inline` 未被使用时，才删除这个分片算法。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/sharding.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/sharding.en.md
index 8222e5c0dd9..8c27db05fb5 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/sharding.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/sharding.en.md
@@ -14,7 +14,7 @@ It generates sharding rule DistSQL only. It does not generate
physical DDL, inde
## Natural language examples
-- List sharding table rules, table nodes, algorithms, key generators,
auditors, and unused components in `<logic-database>`.
+- List sharding table rules, table nodes, algorithms, key generators,
auditors, and unused components in `logic_db`.
- Plan a sharding table rule for `t_order` with explicit data nodes and a
standard sharding strategy.
- Plan a default table sharding strategy using algorithm `t_order_inline`.
- Drop unused sharding algorithm `t_order_inline` only if Proxy-visible state
proves it is unused.
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 766a66f7878..0f4b825adce 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
@@ -36,14 +36,14 @@ cd
distribution/mcp/target/apache-shardingsphere-mcp-${version}
```yaml
runtimeDatabases:
- "<logic-database>":
- jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
- username: "<proxy-username>"
- password: "<proxy-password>"
+ "logic_db":
+ jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db"
+ username: "root"
+ password: ""
driverClassName: "com.mysql.cj.jdbc.Driver"
```
-将 `<logic-database>`、`<proxy-host>`、`<proxy-port>`、`<proxy-username>` 和
`<proxy-password>` 替换为 ShardingSphere-Proxy 的实际连接信息。
+根据 ShardingSphere-Proxy 的实际连接信息调整 `logic_db`、`127.0.0.1`、`3307`、`root` 和空密码。
MCP Server 会从 `jdbcUrl` 解析数据库类型。
如果目标数据库驱动没有随发行包提供，请在启动前把对应 JDBC 驱动 jar 放入 `plugins/`。
@@ -78,9 +78,9 @@ start "ShardingSphere MCP" cmd /c "bin\start.bat >
logs\mcp-http.log 2>&1"
配置完成后，在 AI 应用中输入以下任务验证 ShardingSphere-MCP 是否可以访问目标逻辑库：
-- “查看 `<logic-database>` 中有哪些表。”
-- “查看 `<table-name>` 的字段和索引。”
-- “查询 `<table-name>` 前 10 行。”
+- “查看 `logic_db` 中有哪些表。”
+- “查看 `orders` 的字段和索引。”
+- “查询 `orders` 前 10 行。”
如果可以返回逻辑库、表结构或查询结果，说明 MCP Server 已经可以通过 AI 应用访问目标 ShardingSphere-Proxy 逻辑库。
进一步的部署方式、健康检查和基础可观测入口，请参考[部署说明](../deployment/)。
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 d1fdd49c89d..40d446736a7 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
@@ -36,14 +36,14 @@ Edit `conf/mcp-http.yaml` and point `runtimeDatabases` to
an existing ShardingSp
```yaml
runtimeDatabases:
- "<logic-database>":
- jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
- username: "<proxy-username>"
- password: "<proxy-password>"
+ "logic_db":
+ jdbcUrl: "jdbc:mysql://127.0.0.1:3307/logic_db"
+ username: "root"
+ password: ""
driverClassName: "com.mysql.cj.jdbc.Driver"
```
-Replace `<logic-database>`, `<proxy-host>`, `<proxy-port>`,
`<proxy-username>`, and `<proxy-password>` with the actual ShardingSphere-Proxy
connection information.
+Adjust `logic_db`, `127.0.0.1`, `3307`, `root`, and the empty password
according to the actual ShardingSphere-Proxy connection information.
The MCP Server resolves the database type from `jdbcUrl`.
If the target database driver is not provided with the distribution, put the
corresponding JDBC driver jar under `plugins/` before startup.
@@ -78,9 +78,9 @@ For other clients, follow their own documentation and use the
ShardingSphere-MCP
After configuration, enter the following tasks in the AI application to verify
that ShardingSphere-MCP can access the target logical database:
-- "Show tables in `<logic-database>`."
-- "Show columns and indexes for `<table-name>`."
-- "Query the first 10 rows from `<table-name>`."
+- "Show tables in `logic_db`."
+- "Show columns and indexes for `orders`."
+- "Query the first 10 rows from `orders`."
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.
For deployment choices, health checks, and basic observability entrypoints,
see [Deployment](../deployment/).
diff --git
a/mcp/bootstrap/src/test/java/org/apache/shardingsphere/mcp/bootstrap/config/yaml/swapper/YamlMCPLaunchConfigurationSwapperTest.java
b/mcp/bootstrap/src/test/java/org/apache/shardingsphere/mcp/bootstrap/config/yaml/swapper/YamlMCPLaunchConfigurationSwapperTest.java
index 98d240b6d8c..7b2683c53ba 100644
---
a/mcp/bootstrap/src/test/java/org/apache/shardingsphere/mcp/bootstrap/config/yaml/swapper/YamlMCPLaunchConfigurationSwapperTest.java
+++
b/mcp/bootstrap/src/test/java/org/apache/shardingsphere/mcp/bootstrap/config/yaml/swapper/YamlMCPLaunchConfigurationSwapperTest.java
@@ -236,13 +236,13 @@ class YamlMCPLaunchConfigurationSwapperTest {
String yamlContent = "transport:\n"
+ " type: STDIO\n"
+ "runtimeDatabases:\n"
- + " <logic-database>:\n"
+ + " <unresolved-database>:\n"
+ " jdbcUrl: jdbc:mysql://localhost:3306/logic_db\n"
+ " username: demo\n"
+ " password: ''\n"
+ " driverClassName: com.mysql.cj.jdbc.Driver\n";
IllegalArgumentException actual =
assertThrows(IllegalArgumentException.class, () ->
swapper.swapToObject(YamlEngine.unmarshal(yamlContent,
YamlMCPLaunchConfiguration.class)));
- assertThat(actual.getMessage(), is("MCP launch configuration property
`runtimeDatabases` contains placeholder database name `<logic-database>`."));
+ assertThat(actual.getMessage(), is("MCP launch configuration property
`runtimeDatabases` contains placeholder database name
`<unresolved-database>`."));
}
@Test
@@ -251,7 +251,7 @@ class YamlMCPLaunchConfigurationSwapperTest {
+ " type: STDIO\n"
+ "runtimeDatabases:\n"
+ " logic_db:\n"
- + " jdbcUrl: jdbc:mysql://<proxy-host>:3306/logic_db\n"
+ + " jdbcUrl: jdbc:mysql://<unresolved-host>:3306/logic_db\n"
+ " username: demo\n"
+ " password: ''\n"
+ " driverClassName: com.mysql.cj.jdbc.Driver\n";
@@ -267,7 +267,7 @@ class YamlMCPLaunchConfigurationSwapperTest {
+ " logic_db:\n"
+ " jdbcUrl: jdbc:mysql://localhost:3306/logic_db\n"
+ " username: demo\n"
- + " password: <proxy-password>\n"
+ + " password: <unresolved-password>\n"
+ " driverClassName: com.mysql.cj.jdbc.Driver\n";
IllegalArgumentException actual =
assertThrows(IllegalArgumentException.class, () ->
swapper.swapToObject(YamlEngine.unmarshal(yamlContent,
YamlMCPLaunchConfiguration.class)));
assertThat(actual.getMessage(), is("MCP launch configuration property
`runtimeDatabases` contains placeholder database `logic_db` property
`password`."));
