You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by zh...@apache.org on 2026/06/16 20:15:51 UTC
(shardingsphere) branch master updated: Update MCP troubleshooting follow-up items (#38856)
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 <zh...@apache.org>
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