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 3cfde6a2596 Update MCP troubleshooting follow-up items (#38856)
3cfde6a2596 is described below
commit 3cfde6a259663ee2727d5f987bf183f0ee1fb855
Author: Liang Zhang <[email protected]>
AuthorDate: Wed Jun 17 04:15:44 2026 +0800
Update MCP troubleshooting follow-up items (#38856)
Remove the resolved empty runtimeDatabases startup policy item from the
ShardingSphere-MCP troubleshooting follow-up code improvement list.
Keep the remaining unresolved improvement items unchanged.
---
.../shardingsphere-mcp/troubleshooting.cn.md | 17 ++++++++---------
.../shardingsphere-mcp/troubleshooting.en.md | 17 ++++++++---------
2 files changed, 16 insertions(+), 18 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 d375dc3718d..a395eb2a266 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -60,15 +60,14 @@ weight = 7
以下内容记录当前文档已明确但仍需要后续源码演进的点。代码完成前，用户仍以现有工具名、错误分类和运行时行为为准。
-| 改进项 | 原因
| 建议
|
-|---------------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
-| 连接预检工具命名 | 现有工具名
`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` 启动策略 | 当前启动配置要求 `runtimeDatabases` 非空，缺失或为空会导致启动校验失败。
| 如果后续希望支持先启动 Server 再补充运行时数据库，需要调整
YAML 校验、运行状态、启动日志和文档；如果仍要求非空，则保持当前启动失败行为，并继续让错误信息指向配置修正。
|
-| 查询失败错误分类 | 查询失败可能来自 SQL
语法、对象不存在、权限不足、连接中断或超时，目前用户仍需要结合错误响应和日志判断。
| 后续为查询执行失败补充稳定、非敏感的分类和处理建议，例如语法错误、对象不可见、权限不足和执行超时，并避免暴露原始连接信息或堆栈。
|
-| 元数据不可见错误分类 | 看不到数据库、模式、表、列或索引时，用户需要从配置、权限和连接目标中自行排查。
|
后续在元数据读取和搜索结果中返回更细的可见性分类，例如数据库不可见、模式不可见、对象不可见或权限不足，并给出下一步检查项。
|
-| 敏感值引用机制 | 规则变更可能需要密钥或凭证，目前由外部受控通道传递。
| 后续如需内置支持，应设计密钥引用或解析机制，而不是让 MCP
Server 直接暴露敏感值。
|
+| 改进项 | 原因
| 建议
|
+|-------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| 连接预检工具命名 | 现有工具名 `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 应用和管理员按错误码排查。 |
+| 查询失败错误分类 | 查询失败可能来自 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 3c2d12a4ad6..cae0e36f793 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -60,15 +60,14 @@ When a runtime database or ShardingSphere-Proxy connection
fails, MCP responses
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` startup policy | The current launch configuration
requires `runtimeDatabases` to be non-empty. A missing or empty value fails
startup validation.
| If startup without runtime databases should be supported
later, adjust YAML validation, runtime status, startup logs, and documentation
together. If the non-empty requirement remains, keep startup failure behavior
and continue directing use [...]
-| Query failure error categories | Query failures can come from SQL
syntax, invisible objects, insufficient privileges, interrupted connections, or
timeout. Users currently need to combine the error response with logs to
identify the cause. | Add stable, non-sensitive categories and actions for
query execution failures, such as syntax error, object not visible,
insufficient privileges, and execution timeout, without exposing raw connection
details or stack traces. [...]
-| Metadata visibility error categories | When databases, schemas, tables,
columns, or indexes are not visible, users need to inspect configuration,
privileges, and connection target manually.
| Return finer-grained visibility categories from metadata
read and search results, such as database not visible, schema not visible,
object not visible, or insufficient privileges, with the next checks to
perform. [...]
-| 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.
[...]
+| 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.
|
+| Query failure error categories | Query failures can come from SQL
syntax, invisible objects, insufficient privileges, interrupted connections, or
timeout. Users currently need to combine the error response with logs to
identify the cause. | Add stable, non-sensitive categories and actions for
query execution failures, such as syntax error, object not visible,
insufficient privileges, and execution timeout, without exposing raw connection
details or stack traces. |
+| Metadata visibility error categories | When databases, schemas, tables,
columns, or indexes are not visible, users need to inspect configuration,
privileges, and connection target manually.
| Return finer-grained visibility categories from metadata
read and search results, such as database not visible, schema not visible,
object not visible, or insufficient privileges, with the next checks to
perform. |
+| 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
