本页按用户侧现象整理 ShardingSphere-MCP、AI 应用集成、数据库连接、元数据查看、查询和规则变更的排查方法。 功能插件的规则规划、执行和校验问题，请查看对应功能插件文档。 排查时先区分外部环境和 MCP 保护机制：数据库服务、账号权限、网关转发和 AI 应用配置需要在对应系统处理；MCP 会通过错误分类和运行时保护信息帮助定位问题。 如果尚未完成部署后的基础检查，请先参考部署说明中的健康检查和基础可观测入口，再继续按本页症状定位。
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| MCP Server 启动失败 | Java 版本、配置文件路径、发行包目录或 YAML 必填字段不正确。 | 查看启动终端和 logs/mcp.log；确认使用 Java 21 及以上版本，配置文件存在，发行包 lib/ 目录完整，并且 runtimeDatabases 至少配置一项运行时数据库。 |
| 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 或写 ""。runtimeDatabases 是启动必填项，至少需要配置一项运行时数据库。当运行时数据库或 ShardingSphere-Proxy 连接失败时，MCP 响应会返回连接错误分类，用于帮助定位问题。分类只描述失败原因，不暴露 JDBC URL、密码、环境变量或堆栈信息。
| 分类 | 含义 |
|---|---|
missing_jdbc_driver |
未找到配置的 JDBC 驱动。 |
authentication_failed |
用户名或密码认证失败。 |
authorization_failed |
当前账号没有访问目标数据库或元数据的权限。 |
connection_timeout |
连接超时，通常需要检查地址、端口、网络或超时设置。 |
invalid_configuration |
运行时数据库配置不完整或不一致。 |
database_unavailable |
目标数据库或 ShardingSphere-Proxy 当前不可用。 |
connection_failed |
连接失败，但无法归类为更具体的原因。 |
database_not_visible |
指定数据库或逻辑库对当前连接不可见。 |
| 保护项 | 含义 | 处理方式 |
|---|---|---|
| 查询返回行数 | 默认最多返回 100 行，单次最多请求 5000 行。 | 查询结果被截断时，缩小查询条件、减少返回列或降低返回行数。 |
| 查询超时 | 单次查询最大可请求 300000 毫秒超时。 | 超时后缩小查询范围，或在合理范围内调整超时时间。 |
| 工具调用次数 | 当前 MCP 会话达到工具调用次数保护限制时，会返回 tool_call_limit_exceeded。 |
结束当前会话并重新创建 MCP 会话。 |
| 副作用执行 | 修改数据、结构、规则、权限或事务状态前需要预览和确认。 | 先审查预览内容，再决定是否执行。 |
报告问题时建议提供：
logs/mcp.log 中相关错误。