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 b5aa888dbfb Add MCP deployment health and observability guidance
(#38807)
b5aa888dbfb is described below
commit b5aa888dbfb9ca3d1c9c48db3d7b957ee58f2d85
Author: Liang Zhang <[email protected]>
AuthorDate: Thu Jun 4 20:56:22 2026 +0800
Add MCP deployment health and observability guidance (#38807)
Extend the ShardingSphere-MCP deployment guide with post-deployment
health checks and basic observability entrypoints, including MCP
protocol readiness, runtime database readiness, and minimum
troubleshooting evidence.
Also link quick start, troubleshooting, and the MCP manual index to
the updated deployment flow so users can move from startup to health
verification and symptom-based diagnosis more directly.
---
.../user-manual/shardingsphere-mcp/_index.cn.md | 2 +-
.../user-manual/shardingsphere-mcp/_index.en.md | 2 +-
.../shardingsphere-mcp/deployment.cn.md | 42 +++++++++++++++++++++-
.../shardingsphere-mcp/deployment.en.md | 42 +++++++++++++++++++++-
.../shardingsphere-mcp/quick-start.cn.md | 1 +
.../shardingsphere-mcp/quick-start.en.md | 1 +
.../shardingsphere-mcp/troubleshooting.cn.md | 1 +
.../shardingsphere-mcp/troubleshooting.en.md | 1 +
8 files changed, 88 insertions(+), 4 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 7a00f2741dc..17708cbdbae 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.cn.md
@@ -34,7 +34,7 @@ ShardingSphere-MCP 面向支持 MCP 的 AI 应用、IDE 插件和 Agent 平台
- 能力清单：说明用户可以通过自然语言完成的数据库任务和使用边界。
- 配置说明：说明传输方式、`runtimeDatabases`、插件目录和启动参数。
- 客户端集成：说明如何通过 HTTP 或 STDIO 把 MCP Server 接入 AI 应用，并提供 Codex 和 Claude Code 示例。
-- 部署说明：说明发行包、OCI 镜像和安全部署建议。
+- 部署说明：说明发行包、OCI 镜像、安全部署建议、健康检查和基础运行诊断入口。
- 常见问题：排查 MCP Server、连接、配置、元数据、查询和变更的通用问题。
- 功能插件：说明官方 MCP 功能插件能力，以及插件变更的审查、执行和校验流程。
- 规则变更流程：说明规则变更任务的确认、预览、执行和校验流程。
diff --git a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
index 0a9347b2a57..736b8374e4e 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/_index.en.md
@@ -34,7 +34,7 @@ Tasks with side effects should create or preview a plan
first, then run only aft
- Capability Catalog: understand the database tasks and usage boundaries that
users can access through natural language.
- Configuration: configure transport, `runtimeDatabases`, plugin directories,
and launch parameters.
- Client Integration: connect the MCP Server to an AI application through HTTP
or STDIO, with Codex and Claude Code examples.
-- Deployment: deploy the binary distribution and OCI image safely.
+- Deployment: deploy the binary distribution and OCI image safely, then verify
health and basic runtime diagnostics.
- Troubleshooting: diagnose common MCP Server, connection, configuration,
metadata, query, and change issues.
- Feature Plugins: use official MCP feature plugins and understand how to
review, apply, and validate plugin changes.
- Rule Change Flow: understand confirmation, preview, execution, and
validation for rule change tasks.
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 751dd7e6922..b3f0d53b684 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
@@ -94,7 +94,47 @@ HTTP 绑定建议：
- 面向远程客户端暴露时，避免直接裸露 MCP Server。
- 需要把会话和外部用户或调用来源关联时，由受信网关注入会话归属请求头；不要允许客户端直接伪造这些请求头。
-## 日志
+## 健康检查
+
+部署完成后，建议按以下顺序确认 ShardingSphere-MCP 是否真正可用，而不只停留在“HTTP 端口可达”：
+
+1. 服务进程与端点可达
+
+ - HTTP 模式确认进程已启动、端口已监听，并且 `http://<bind-host>:<port><endpointPath>`
与客户端配置一致。
+ - STDIO 模式确认由 AI 应用正确拉起 MCP 进程，不把标准输入输出当作交互式 shell 使用。
+
+2. MCP 协议已就绪
+
+ - 通过 AI 应用确认 MCP Server 已被识别，或按[自研集成附录](../developer-appendix/)中的协议调试示例完成
`initialize` 和能力读取。
+ - 如果只能确认 HTTP 返回，但无法读取 capabilities、resources 或 tools，说明端点可达但协议尚未正确接通。
+
+3. 运行时数据库已就绪
+
+ - 读取 `shardingsphere://runtime`，确认 transport、runtime 数据库摘要和运行状态可见。
+ - 调用 `database_gateway_validate_proxy_connectivity`，或在 AI 应用中执行“查看
`<logic-database>` 中有哪些表”这类最小任务，确认当前 `runtimeDatabases` 对应的逻辑库可用。
+ - 仅有 MCP Server 进程启动并不表示目标运行时数据库已经可用；连接失败、权限不足或逻辑库不可见仍会阻断后续任务。
+
+## 基础可观测入口
+
+### 日志
- HTTP 模式：查看启动终端和 `logs/mcp.log`。
- STDIO 模式：不要把标准输出作为日志查看入口，诊断信息查看 stderr 或 `logs/mcp.log`。
+
+### 运行时状态与保护信息
+
+- `shardingsphere://runtime` 提供当前 transport、runtime 数据库摘要、运行状态和基础诊断信息。
+- 运行时保护信息会反映查询行数限制、查询超时和会话级工具调用保护等边界。
+- 当运行时数据库连接失败时，可结合错误分类和恢复建议定位问题；详细分类说明见[常见问题](../troubleshooting/)。
+
+### 最小排障信息
+
+需要向管理员或排障人员反馈问题时，至少收集以下信息：
+
+- 启动命令或容器运行命令。
+- MCP 配置文件摘要，注意移除密码、密钥和令牌。
+- 传输方式、端点地址和 `runtimeDatabases` 中的目标逻辑库名称。
+- AI 应用中的 MCP Server 配置摘要。
+- 失败任务、错误分类和 `logs/mcp.log` 中相关日志片段。
+
+进一步的症状定位、错误分类和运行时保护说明见[常见问题](../troubleshooting/)；需要直接调试 MCP
协议请求时，见[自研集成附录](../developer-appendix/)。
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 a8aaa3662ec..c3f96cbcf38 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
@@ -94,7 +94,47 @@ HTTP binding recommendations:
- Avoid exposing the MCP Server directly to remote clients.
- When sessions must be associated with external users or request sources, let
a trusted gateway inject session attribution headers. Do not allow clients to
forge these headers directly.
-## Logs
+## Health Checks
+
+After deployment, verify that ShardingSphere-MCP is truly usable instead of
stopping at “the HTTP port is reachable”:
+
+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 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
+
+ - Confirm from the AI application that the MCP Server is recognized, or
follow the protocol debugging examples in the [Custom Integration
Appendix](../developer-appendix/) to complete `initialize` and read
capabilities.
+ - If HTTP responses are reachable but capabilities, resources, or tools
cannot be listed, the endpoint is reachable but the MCP protocol is not yet
wired correctly.
+
+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_proxy_connectivity`, 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.
+ - 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
+
+### Logs
- HTTP mode: inspect the startup terminal and `logs/mcp.log`.
- STDIO mode: do not use stdout as a log inspection entry; inspect stderr or
`logs/mcp.log` for diagnostics.
+
+### Runtime status and protection details
+
+- `shardingsphere://runtime` exposes the current transport, runtime database
summary, readiness details, and basic diagnostics.
+- Runtime protection details show boundaries such as row limits, query timeout
limits, and session-level tool-call protection.
+- When a runtime database connection fails, use the returned failure category
and recovery guidance to locate the issue. See
[Troubleshooting](../troubleshooting/) for the full category list.
+
+### Minimum troubleshooting evidence
+
+When reporting an issue to an operator or troubleshooter, collect at least:
+
+- The startup command or container run command.
+- An MCP configuration summary, with passwords, keys, and tokens removed.
+- The transport type, endpoint address, and target logical database names
configured under `runtimeDatabases`.
+- The MCP Server configuration summary from the AI application.
+- The failed task, returned failure category, and the relevant excerpt from
`logs/mcp.log`.
+
+For symptom-oriented diagnosis, failure categories, and runtime protection
guidance, see [Troubleshooting](../troubleshooting/). For direct MCP protocol
debugging, see the [Custom Integration Appendix](../developer-appendix/).
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 194993a88bc..cfd5a6bb0b6 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
@@ -83,4 +83,5 @@ start "ShardingSphere MCP" cmd /c "bin\start.bat >
logs\mcp-http.log 2>&1"
- “查询 `<table-name>` 前 10 行。”
如果可以返回逻辑库、表结构或查询结果，说明 MCP Server 已经可以通过 AI 应用访问目标 ShardingSphere-Proxy 逻辑库。
+进一步的部署方式、健康检查和基础可观测入口，请参考[部署说明](../deployment/)。
如果 AI 应用无法连接或看不到逻辑库，请查看[常见问题](../troubleshooting/)。
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 42514501e6f..6fd6c96bba3 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
@@ -83,4 +83,5 @@ After configuration, enter the following tasks in the AI
application to verify t
- "Query the first 10 rows from `<table-name>`."
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/).
If the AI application cannot connect or cannot see the logical database, see
[Troubleshooting](../troubleshooting/).
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 41880c146e2..d375dc3718d 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -6,6 +6,7 @@ weight = 7
本页按用户侧现象整理 ShardingSphere-MCP、AI 应用集成、数据库连接、元数据查看、查询和规则变更的排查方法。
功能插件的规则规划、执行和校验问题，请查看对应功能插件文档。
排查时先区分外部环境和 MCP 保护机制：数据库服务、账号权限、网关转发和 AI 应用配置需要在对应系统处理；MCP
会通过错误分类和运行时保护信息帮助定位问题。
+如果尚未完成部署后的基础检查，请先参考[部署说明](../deployment/)中的健康检查和基础可观测入口，再继续按本页症状定位。
## 问题列表
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 9f06e6ea764..3c2d12a4ad6 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -6,6 +6,7 @@ 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 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.
+If you have not completed the basic post-deployment checks yet, start with the
health-check and observability entrypoints in [Deployment](../deployment/)
before using this symptom-oriented page.
## Issue List
