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 56e7caf3295 Refine ShardingSphere-MCP troubleshooting docs (#38798)
56e7caf3295 is described below
commit 56e7caf32956fbdd3af50ad21fa02a75d2e1c126
Author: Liang Zhang <[email protected]>
AuthorDate: Thu Jun 4 14:27:33 2026 +0800
Refine ShardingSphere-MCP troubleshooting docs (#38798)
* reorganize troubleshooting index into user-facing issue lists
* consolidate duplicated HTTP and runtime protection entries
* clarify connection failure categories and runtime protection behavior
* document follow-up code improvements for MCP diagnostics
---
.../shardingsphere-mcp/troubleshooting.cn.md | 61 ++++++++++++----------
.../shardingsphere-mcp/troubleshooting.en.md | 61 ++++++++++++----------
2 files changed, 64 insertions(+), 58 deletions(-)
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 6f115b273f5..ae6101c8ef9 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -4,33 +4,30 @@ weight = 7
+++
本页按用户侧现象整理 ShardingSphere-MCP、AI 应用集成、数据库连接、元数据查看、查询和规则变更的排查方法。
-功能插件的业务规则问题请查看对应功能插件文档。
+功能插件的规则规划、执行和校验问题，请查看对应功能插件文档。
+排查时先区分外部环境和 MCP 保护机制：数据库服务、账号权限、网关转发和 AI 应用配置需要在对应系统处理；MCP
会通过错误分类和运行时保护信息帮助定位问题。
-## 排查索引
+## 问题列表
| 现象 | 可能原因 | 处理方式 |
| --- | --- | --- |
-| MCP Server 启动失败 | JDK、配置路径、YAML 字段或必填字段不正确。 | 查看启动终端和
`logs/mcp.log`，确认配置文件路径和必填字段。 |
-| AI 应用无法连接 ShardingSphere-MCP | 端口、端点路径、传输方式、绑定地址或客户端配置不正确。 | 检查
`port`、`endpointPath`、`bindHost` 和 AI 应用中的 MCP Server 地址。 |
-| 远程访问 HTTP 服务失败 | HTTP 绑定地址、安全策略、Origin 请求头或网关配置不正确。 |
本机调试用回环地址；远程访问放在受控网关或反向代理后面；详细原因看服务端日志。 |
-| HTTP 请求被拒绝 | 请求携带的 Origin 请求头不符合 HTTP 传输安全策略，或同一 MCP 会话中的可信归属请求头不一致。 | 检查
`bindHost`、客户端访问方式、网关请求头转发策略和会话归属配置。 |
-| STDIO 模式没有响应 | 用户直接把 STDIO 当成命令行交互入口，或 AI 应用没有正确拉起进程。 | 由 AI 应用拉起
ShardingSphere-MCP；诊断信息看 stderr 或 `logs/mcp.log`。 |
-| 看不到逻辑库 | 未配置逻辑库、逻辑库名称不正确、连接失败、权限不足，或目标范围确实为空。 | 确认
`runtimeDatabases`、逻辑库名称、连接错误分类和账号权限。 |
-| 查不到表、列或索引 | 连接目标不同、模式不正确、账号权限不足，或 Proxy 暴露的逻辑元数据与底层物理库不同。 | 先确认连接的是
ShardingSphere-Proxy 还是数据库直连，再检查模式、账号权限和 Proxy 可见元数据。 |
-| JDBC 驱动错误 | 驱动不在类路径，或 `driverClassName` 不正确。 | 把驱动 jar 放入 `plugins/`，并确认
`driverClassName` 非空且类名正确。 |
-| 只读查询失败 | SQL 语法、目标表名、模式、权限、返回行数或超时限制不正确。 | 先让 AI 应用查看表结构，再执行只读查询，并限制返回行数。 |
-| 查询结果被截断 | 查询结果超过返回行数限制。 | 缩小查询条件、减少返回列或降低返回行数。 |
-| 当前会话无法继续调用工具 | MCP 会话达到工具调用次数保护限制。 | 结束当前会话并重新创建 MCP 会话。 |
-| 有副作用 SQL 无法执行 | SQL 类型有副作用，或未先预览和确认。 | 先要求预览变更 SQL，审查影响范围后再确认执行。 |
-| 加密或脱敏计划无法生成 | 连接目标不是 Proxy、目标列不可见、算法不可用，或缺少必要参数。 | 确认 `runtimeDatabases` 指向
Proxy 逻辑库，并补充逻辑库、表、列、算法和参数。 |
-| 规则变更执行后校验不通过 | 规则未成功执行、权限不足、元数据未刷新，或人工执行包未完成执行。 |
查看规则变更计划、执行结果和日志；人工执行后再发起校验。 |
-| 敏感输入无法传递 | 规则变更需要密钥或凭证。 | 通过客户端、密钥管理系统或运维控制通道取得真实值，再在受保护调用或人工执行环节传入。 |
+| MCP Server 启动失败 | Java 版本、配置文件路径、发行包目录或 YAML 必填字段不正确。 | 查看启动终端和
`logs/mcp.log`；确认使用 Java 21 及以上版本，配置文件存在，发行包 `lib/` 目录完整。 |
+| AI 应用无法连接 ShardingSphere-MCP | 传输方式、端口、端点路径、绑定地址或 AI 应用中的 MCP Server 配置不一致。
| 检查 `transport.type`、`port`、`endpointPath`、`bindHost`，并确认 AI 应用使用相同的连接地址。 |
+| HTTP 远程访问失败或请求被拒绝 | HTTP 绑定地址、Origin 请求头、反向代理、网关转发或会话归属配置不符合安全策略。 |
本机调试使用回环地址；远程访问放在受控网关或反向代理后面；检查网关是否转发了期望的请求头；详细原因看服务端日志。 |
+| STDIO 模式没有响应 | STDIO 被当作命令行交互入口，或 AI 应用没有正确拉起 MCP 进程。 | 由 AI 应用拉起
ShardingSphere-MCP；诊断信息看 stderr 或 `logs/mcp.log`。 |
+| 看不到数据库或逻辑库 | `runtimeDatabases` 未配置、名称不正确、连接失败、权限不足，或目标范围确实为空。 |
读取当前可见数据库；如果返回连接错误分类，按下方连接错误分类处理；确认账号拥有元数据读取权限。 |
+| 查不到表、列或索引 | 连接目标不同、模式或命名空间不正确、账号权限不足，或 Proxy 可见逻辑元数据与底层物理库不同。 | 先确认连接的是
ShardingSphere-Proxy 还是数据库直连，再检查模式、命名空间、账号权限和 Proxy 可见元数据。 |
+| 查询被拒绝 | SQL 不属于只读查询，或包含锁定读、修改数据、修改结构、修改权限、事务控制等副作用。 |
只读任务使用查询语句；涉及副作用的任务先要求预览变更，再确认是否执行。 |
+| 查询执行失败或结果被截断 | SQL 语法、目标对象、权限、返回行数或超时限制不正确。 |
先查看表结构；缩小查询条件、减少返回列、降低返回行数；必要时调整超时时间。 |
+| 副作用 SQL 无法执行 | 修改类 SQL 未经过预览和确认，或当前账号没有执行权限。 | 先预览变更
SQL，审查影响范围，再确认执行；权限问题需要管理员处理。 |
+| 规则变更计划或校验失败 | 连接目标不是
ShardingSphere-Proxy、目标列不可见、算法不可用、参数不足、规则未执行成功，或人工执行包尚未完成。 | 确认
`runtimeDatabases` 指向 Proxy 逻辑库；按功能插件文档补充规则目标、算法和参数；人工执行后再校验。 |
补充说明：
- `username` 和 `driverClassName` 必须显式写出且不能为空；无密码账号可以省略 `password` 或写 `""`。
- 查询默认最多返回 100 行，单次查询最多可请求 5000 行；查询超时最大可请求 300000 毫秒。
- 人工执行包中的密钥占位符应由执行人员在受控环境替换。
+- ShardingSphere-MCP 不直接读取密钥管理系统；如果规则变更需要密钥或凭证，应通过 AI 应用、运维流程或受保护的执行环境传递。
- 开发者需要排查协议请求时，可参考[自研集成附录](../developer-appendix/)。
## 连接错误分类
@@ -46,22 +43,28 @@ weight = 7
| `invalid_configuration` | 运行时数据库配置不完整或不一致。 |
| `database_unavailable` | 目标数据库或 ShardingSphere-Proxy 当前不可用。 |
| `connection_failed` | 连接失败，但无法归类为更具体的原因。 |
-| `database_not_visible` | 指定逻辑库对当前连接不可见。 |
+| `database_not_visible` | 指定数据库或逻辑库对当前连接不可见。 |
-## 运行时保护分类
+## 运行时保护
-| 分类 | 含义 |
-| --- | --- |
-| `tool_call_limit_exceeded` | 当前 MCP 会话达到工具调用次数保护限制。 |
+| 保护项 | 含义 | 处理方式 |
+| --- | --- | --- |
+| 查询返回行数 | 默认最多返回 100 行，单次最多请求 5000 行。 | 查询结果被截断时，缩小查询条件、减少返回列或降低返回行数。 |
+| 查询超时 | 单次查询最大可请求 300000 毫秒超时。 | 超时后缩小查询范围，或在合理范围内调整超时时间。 |
+| 工具调用次数 | 当前 MCP 会话达到工具调用次数保护限制时，会返回 `tool_call_limit_exceeded`。 |
结束当前会话并重新创建 MCP 会话。 |
+| 副作用执行 | 修改数据、结构、规则、权限或事务状态前需要预览和确认。 | 先审查预览内容，再决定是否执行。 |
-## 查询与变更建议
+## 后续代码改进项
-| 场景 | 建议 |
-| --- | --- |
-| 查询数据 | 建议限制返回行数。 |
-| 查询结果被截断 | 缩小查询条件、减少返回列或降低返回行数。 |
-| 分析 SQL 执行计划 | 仅在目标逻辑库能力允许时使用。 |
-| 修改数据、结构、规则或事务状态 | 先预览并审查副作用，再决定是否执行。 |
+以下内容记录当前文档已明确但仍需要后续源码演进的点。代码完成前，用户仍以现有工具名、错误分类和运行时行为为准。
+
+| 改进项 | 原因 | 建议 |
+| --- | --- | --- |
+| 连接预检工具命名 | 现有工具名 `database_gateway_validate_proxy_connectivity` 容易让用户误以为只能校验
Proxy，但实际校验的是已配置的运行时数据库连接。 | 后续改为更中性的名称，例如
`database_gateway_validate_runtime_database` 或
`database_gateway_validate_connectivity`，并同步调整描述符、测试和文档。 |
+| 运行状态中的错误分类 | 连接错误分类包含 `database_not_visible`，但运行状态资源的安全分类列表尚未完全对齐。 |
后续在运行状态资源中补齐该分类，保证排障分类和运行时状态一致。 |
+| HTTP 安全错误分类 | Origin 请求头和会话归属不一致时，目前主要通过 HTTP 状态码和日志定位。 | 后续增加稳定、非敏感的错误分类，例如
`origin_not_allowed` 和 `session_attribution_mismatch`，方便 AI 应用和管理员按错误码排查。 |
+| 空 `runtimeDatabases` 提示 | 未配置运行时数据库时 Server 可以启动，但元数据和 SQL 能力不可用。 |
后续在启动日志或运行状态中给出更明显的配置缺失提示。 |
+| 敏感值引用机制 | 规则变更可能需要密钥或凭证，目前由外部受控通道传递。 | 后续如需内置支持，应设计密钥引用或解析机制，而不是让 MCP Server
直接暴露敏感值。 |
## 提供给管理员或排障人员的信息
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
index 3d070bc7865..bd16f696ccf 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -4,33 +4,30 @@ weight = 7
+++
This page organizes troubleshooting by user-visible symptoms for
ShardingSphere-MCP, AI application integration, database connectivity, metadata
inspection, queries, and rule changes.
-For feature-specific business rule issues, see the corresponding feature
plugin documentation.
+For feature-specific rule planning, execution, and validation issues, see the
corresponding feature plugin documentation.
+When troubleshooting, distinguish external environment issues from MCP
protection behavior. Database service availability, account privileges, gateway
forwarding, and AI application configuration must be fixed in their own
systems. MCP provides failure categories and runtime protection details to help
locate the issue.
-## Troubleshooting Index
+## Issue List
| Symptom | Possible cause | Action |
| --- | --- | --- |
-| MCP Server startup failure | JDK, config path, YAML field, or required field
is wrong. | Inspect the startup terminal and `logs/mcp.log`; confirm the
configuration file path and required fields. |
-| The AI application cannot connect to ShardingSphere-MCP | Port, endpoint
path, transport type, bind address, or client configuration is wrong. | Check
`port`, `endpointPath`, `bindHost`, and the MCP Server address configured in
the AI application. |
-| Remote HTTP access fails | HTTP bind address, security policy, Origin
header, or gateway configuration is wrong. | Use loopback locally; place remote
access behind a controlled gateway or reverse proxy; inspect server logs for
details. |
-| HTTP request is rejected | The request carries an Origin header that does
not satisfy the HTTP transport security policy, or trusted attribution headers
are inconsistent within the same MCP session. | Check `bindHost`, client access
mode, gateway header forwarding, and session attribution configuration. |
-| No response in STDIO mode | STDIO is used as an interactive command-line
entry, or the AI application does not launch the process correctly. | Let the
AI application launch ShardingSphere-MCP; inspect stderr or `logs/mcp.log` for
diagnostics. |
-| Logical databases are not visible | No logical database is configured, the
logical database name is wrong, connection failed, permission is insufficient,
or the target scope is empty. | Verify `runtimeDatabases`, logical database
names, connection failure category, and account privileges. |
-| Tables, columns, or indexes cannot be found | The connection target is
different, schema is wrong, account privileges are insufficient, or
Proxy-visible logical metadata differs from the underlying physical database. |
Confirm whether the target is ShardingSphere-Proxy or a direct database
connection, then check schema, account privileges, and Proxy-visible metadata. |
-| JDBC driver error | Driver is not on the classpath, or `driverClassName` is
wrong. | Put the driver jar under `plugins/`, and keep `driverClassName`
non-empty and correct. |
-| Read-only query fails | SQL syntax, target table name, schema, privilege,
row limit, or timeout limit is wrong. | Ask the AI application to inspect table
structure first, then run a read-only query with a row limit. |
-| Query result is truncated | The query result exceeds the returned row limit.
| Narrow the predicate, reduce the projection, or request fewer rows. |
-| Current session cannot continue calling tools | The MCP session has reached
the tool-call protection limit. | Close the current session and create a new
MCP session. |
-| Side-effecting SQL cannot be executed | The SQL has side effects, or it was
not previewed and confirmed first. | Preview the change SQL first, review the
impact, then confirm execution. |
-| Encryption or masking plan cannot be generated | The target is not Proxy,
the target column is not visible, the algorithm is unavailable, or required
parameters are missing. | Ensure that `runtimeDatabases` points to a Proxy
logical database, then provide logical database, table, column, algorithm, and
parameters. |
-| Validation fails after a rule change | The rule was not applied
successfully, permission is insufficient, metadata is not refreshed, or a
manual package was not executed. | Inspect the rule change plan, execution
result, and logs; validate again after manual execution is completed. |
-| Secret input cannot be passed safely | A rule change needs a key or
credential. | Resolve the value through the client, a key management system, or
an operations control channel, then pass it through a protected call or manual
execution step. |
+| MCP Server startup failure | Java version, config file path, distribution
directory, or required YAML field is wrong. | Inspect the startup terminal and
`logs/mcp.log`; use Java 21 or later, confirm that the config file exists, and
ensure that the distribution `lib/` directory is complete. |
+| The AI application cannot connect to ShardingSphere-MCP | Transport type,
port, endpoint path, bind address, or the MCP Server configuration in the AI
application is inconsistent. | Check `transport.type`, `port`, `endpointPath`,
`bindHost`, and the address configured in the AI application. |
+| Remote HTTP access fails or the HTTP request is rejected | HTTP bind
address, Origin header, reverse proxy, gateway forwarding, or session
attribution configuration does not satisfy the security policy. | Use loopback
for local debugging; place remote access behind a controlled gateway or reverse
proxy; check whether the gateway forwards the expected headers; inspect server
logs for details. |
+| No response in STDIO mode | STDIO is used as an interactive command-line
entry, or the AI application does not launch the MCP process correctly. | Let
the AI application launch ShardingSphere-MCP; inspect stderr or `logs/mcp.log`
for diagnostics. |
+| Databases or logical databases are not visible | `runtimeDatabases` is not
configured, the name is wrong, connection failed, privileges are insufficient,
or the target scope is empty. | Read the currently visible databases; if a
connection failure category is returned, follow the connection failure table
below; confirm that the account can read metadata. |
+| Tables, columns, or indexes cannot be found | The connection target is
different, schema or namespace is wrong, account privileges are insufficient,
or Proxy-visible logical metadata differs from the underlying physical
database. | Confirm whether the target is ShardingSphere-Proxy or a direct
database connection, then check schema, namespace, account privileges, and
Proxy-visible metadata. |
+| Query is rejected | The SQL is not read-only, or it contains locking reads,
data changes, schema changes, privilege changes, or transaction control. | Use
query statements for read-only tasks. For side-effecting tasks, preview the
change first and then decide whether to execute it. |
+| Query execution fails or the result is truncated | SQL syntax, target
object, privilege, row limit, or timeout limit is wrong. | Inspect table
structure first; narrow the predicate, reduce the projection, request fewer
rows, or adjust timeout within the supported range. |
+| Side-effecting SQL cannot be executed | The change SQL was not previewed and
confirmed, or the current account lacks execution privileges. | Preview the
change SQL, review the impact, and then confirm execution; privilege issues
require administrator action. |
+| Rule change planning or validation fails | The target is not
ShardingSphere-Proxy, the target column is not visible, the algorithm is
unavailable, required parameters are missing, the rule was not applied
successfully, or a manual package has not been executed. | Ensure that
`runtimeDatabases` points to a Proxy logical database; provide the rule target,
algorithm, and parameters according to the feature plugin documentation;
validate again after manual execution is completed. |
Additional notes:
- `username` and `driverClassName` must be declared explicitly and cannot be
empty; a no-password account can omit `password` or use `""`.
- Queries return at most 100 rows by default. A single query can request at
most 5000 rows, and the maximum requested query timeout is 300000 milliseconds.
- Secret placeholders in manual packages should be replaced by operators in a
controlled environment.
+- ShardingSphere-MCP does not read key management systems directly. If a rule
change needs keys or credentials, pass them through the AI application,
operations workflow, or protected execution environment.
- For protocol request debugging, see the [Custom Integration
Appendix](../developer-appendix/).
## Connection Failure Categories
@@ -46,22 +43,28 @@ When a runtime database or ShardingSphere-Proxy connection
fails, MCP responses
| `invalid_configuration` | Runtime database configuration is incomplete or
inconsistent. |
| `database_unavailable` | The target database or ShardingSphere-Proxy is
currently unavailable. |
| `connection_failed` | The connection failed, but cannot be classified into a
more specific cause. |
-| `database_not_visible` | The specified logical database is not visible to
the current connection. |
+| `database_not_visible` | The specified database or logical database is not
visible to the current connection. |
-## Runtime Protection Categories
+## Runtime Protection
-| Category | Meaning |
-| --- | --- |
-| `tool_call_limit_exceeded` | The current MCP session has reached the
tool-call protection limit. |
+| Protection | Meaning | Action |
+| --- | --- | --- |
+| Query row limit | Queries return at most 100 rows by default, and one query
can request at most 5000 rows. | When a result is truncated, narrow the
predicate, reduce the projection, or request fewer rows. |
+| Query timeout | One query can request at most 300000 milliseconds as the
timeout. | After a timeout, narrow the query scope or adjust timeout within the
supported range. |
+| Tool-call quota | When the current MCP session reaches the tool-call
protection limit, MCP returns `tool_call_limit_exceeded`. | Close the current
session and create a new MCP session. |
+| Side-effect execution | Data, schema, rule, privilege, or transaction-state
changes require preview and confirmation before execution. | Review the preview
before deciding whether to execute. |
-## Query and Change Recommendations
+## Future Code Improvements
-| Scenario | Recommendation |
-| --- | --- |
-| Query data | Limit returned rows. |
-| Truncated query result | Narrow the predicate, reduce the projection, or
request fewer rows. |
-| Analyze an SQL execution plan | Use only when the target logical database
capability allows it. |
-| Change data, structure, rules, or transaction state | Preview and review
side effects before deciding whether to execute. |
+The following items are documented as known follow-up code improvements. Until
the code changes are completed, users should rely on the current tool names,
error categories, and runtime behavior.
+
+| Improvement | Reason | Recommendation |
+| --- | --- | --- |
+| Connectivity validation tool name | The current tool name
`database_gateway_validate_proxy_connectivity` can imply that only Proxy is
validated, but the tool actually validates a configured runtime database
connection. | Rename it to a more neutral name, such as
`database_gateway_validate_runtime_database` or
`database_gateway_validate_connectivity`, and update descriptors, tests, and
documentation together. |
+| Error categories in runtime status | The connection failure categories
include `database_not_visible`, but the safe category list in the runtime
status resource is not fully aligned. | Add this category to the runtime status
resource so troubleshooting categories and runtime status stay consistent. |
+| HTTP security error categories | Origin header and session attribution
failures are currently located mainly through HTTP status codes and logs. | Add
stable, non-sensitive error categories such as `origin_not_allowed` and
`session_attribution_mismatch`, so AI applications and administrators can
troubleshoot by category. |
+| Empty `runtimeDatabases` guidance | The Server can start without configured
runtime databases, but metadata and SQL capabilities are unavailable. | Add a
clearer warning in startup logs or runtime status when no runtime database is
configured. |
+| Secret reference mechanism | Rule changes may require keys or credentials,
which are currently passed through external protected channels. | If built-in
support is required later, design a secret reference or resolver mechanism
instead of exposing sensitive values through the MCP Server. |
## Information for Administrators or Troubleshooters
