协议表面 – ShardingSphere

技术参考

MCP

协议表面

ShardingSphere-MCP 的 public surface 由 META-INF/shardingsphere-mcp/mcp-descriptors 下的 descriptors 定义。 MCP runtime 使用这些 descriptors 发布 tools、resources、resource templates、prompts 和 completions。

协议能力

ShardingSphere-MCP 固定使用 MCP Java SDK 1.1.2，并且只暴露 MCP protocol revision 2025-11-25。 SDK 和 protocol revision 是本实现固定的兼容性边界，不作为依赖升级或多版本兼容目标。

已启用：

resources/list
resources/templates/list
resources/read
tools/list
tools/call
prompts/list
prompts/get
completion/complete

未实现或后续范围：

Resource subscriptions。
Resource、tool、prompt list-changed notifications。
ShardingSphere 产品日志通过 notifications/message 输出。
progress。
notifications/cancelled。
task-augmented requests。
固定 MCP Java SDK 1.1.2 边界未暴露的 Tool.execution。

MCP icons 在当前服务中没有消费场景，因此是明确的非目标。

roots 和 sampling 是 client capabilities。 ShardingSphere-MCP 不要求 roots，也不会发送 sampling/createMessage 请求。

Tools

database_gateway_search_metadata

搜索逻辑库 metadata。
可按 database、schema、query、object_types 收窄范围，再通过 offset 和 limit 返回确定性排序的分页结果。
object_types 支持 database、schema、storage_unit、table、view、column、index、sequence。
limit 默认值为 100，范围是 1..100；offset 默认值为 0。当 has_more=true 时，应保持相同搜索范围并使用返回的 next_offset 继续查询。

database_gateway_validate_runtime_database

在正式接入前校验已配置的运行时数据库。
必填输入为 database。
使用管理员已配置的运行时数据库连接信息；JDBC URL、用户名、密码和驱动类名不是工具输入。
返回 status、有序 checks、整体 category 和结构化 recovery 对象。
常见失败分类包括 missing_jdbc_driver、authentication_failed、authorization_failed、connection_timeout、invalid_configuration、database_unavailable、connection_failed 和 database_not_visible。

database_gateway_execute_query

执行一个 classifier 允许的 SELECT。
拒绝 DML、DDL、DCL、事务控制、savepoint 和已知有副作用的查询形态。
max_rows 范围是 0..5000，省略或 0 使用服务端默认值 100。
timeout_ms 范围是 0..300000，0 表示不设置显式 timeout。

database_gateway_execute_explain_query

执行一个模型生成的数据库原生 EXPLAIN，用于诊断一个 classifier 允许的 SELECT。
必须把原始 SELECT 放在 sql，把生成的 EXPLAIN 放在 explain_sql。
拒绝 EXPLAIN ANALYZE、EXPLAIN PLAN FOR、多语句和有副作用 SQL。
max_rows 范围是 0..5000，省略或 0 使用服务端默认值 100。
timeout_ms 范围是 0..300000，0 表示不设置显式 timeout。

database_gateway_execute_update

预览或执行一个支持的有副作用 SQL。
execution_mode=preview 只做分类和副作用范围预览，不会在数据库侧进行试执行。
execution_mode=execute 在 review 后执行 SQL。
多语句和禁用命令会被拒绝。

database_gateway_apply_workflow

对当前 session 中已有的 workflow plan 做 preview、执行或导出。
execution_mode 支持 preview、review-then-execute、manual-only。
approved_steps 只能使用 preview 返回的 approval step。

database_gateway_validate_workflow

校验当前 session 中已有的 workflow plan。
用于 planning review 后或 apply 后确认 runtime 状态。

Feature plugin planning tools：

database_gateway_plan_encrypt_rule
database_gateway_plan_mask_rule
database_gateway_plan_broadcast_rule
database_gateway_plan_readwrite_splitting_rule
database_gateway_plan_readwrite_splitting_status
database_gateway_plan_shadow_rule
database_gateway_plan_default_shadow_algorithm
database_gateway_plan_shadow_algorithm_cleanup
database_gateway_plan_sharding_table_rule
database_gateway_plan_sharding_table_reference_rule
database_gateway_plan_sharding_default_strategy
database_gateway_plan_sharding_key_generator
database_gateway_plan_sharding_key_generate_strategy
database_gateway_plan_sharding_rule_component_cleanup

Resources

Runtime 与能力：

shardingsphere://capabilities
shardingsphere://runtime
shardingsphere://databases
shardingsphere://databases/{database}
shardingsphere://databases/{database}/capabilities
shardingsphere://databases/{database}/storage-units
shardingsphere://databases/{database}/storage-units/{storageUnit}
shardingsphere://databases/{database}/storage-units/{storageUnit}/used-by-rules
shardingsphere://databases/{database}/single-tables
shardingsphere://databases/{database}/single-tables/{table}
shardingsphere://databases/{database}/single-table/default-storage-unit

Metadata：

shardingsphere://databases/{database}/schemas
shardingsphere://databases/{database}/schemas/{schema}
shardingsphere://databases/{database}/schemas/{schema}/tables
shardingsphere://databases/{database}/schemas/{schema}/tables/{table}
shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns
shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/columns/{column}
shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes
shardingsphere://databases/{database}/schemas/{schema}/tables/{table}/indexes/{index}
shardingsphere://databases/{database}/schemas/{schema}/views
shardingsphere://databases/{database}/schemas/{schema}/views/{view}
shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns
shardingsphere://databases/{database}/schemas/{schema}/views/{view}/columns/{column}
shardingsphere://databases/{database}/schemas/{schema}/sequences
shardingsphere://databases/{database}/schemas/{schema}/sequences/{sequence}

Workflow：

shardingsphere://workflows/{plan_id}

Feature resources：

shardingsphere://features/encrypt/algorithms
shardingsphere://features/encrypt/databases/{database}/rules
shardingsphere://features/encrypt/databases/{database}/tables/{table}/rules
shardingsphere://features/mask/algorithms
shardingsphere://features/mask/databases/{database}/rules
shardingsphere://features/mask/databases/{database}/tables/{table}/rules
shardingsphere://features/broadcast/databases/{database}/rules
shardingsphere://features/broadcast/databases/{database}/tables/{table}/rule
shardingsphere://features/broadcast/databases/{database}/rule-count
shardingsphere://features/readwrite-splitting/load-balance-algorithm-plugins
shardingsphere://features/readwrite-splitting/databases/{database}/rules
shardingsphere://features/readwrite-splitting/databases/{database}/rules/{rule}
shardingsphere://features/readwrite-splitting/databases/{database}/status
shardingsphere://features/readwrite-splitting/databases/{database}/rules/{rule}/status
shardingsphere://features/readwrite-splitting/databases/{database}/rule-count
shardingsphere://features/shadow/algorithm-plugins
shardingsphere://features/shadow/databases/{database}/rules
shardingsphere://features/shadow/databases/{database}/rules/{rule}
shardingsphere://features/shadow/databases/{database}/table-rules
shardingsphere://features/shadow/databases/{database}/tables/{table}/rules
shardingsphere://features/shadow/databases/{database}/algorithms
shardingsphere://features/shadow/databases/{database}/default-algorithm
shardingsphere://features/shadow/databases/{database}/rule-count
shardingsphere://features/sharding/algorithm-plugins
shardingsphere://features/sharding/key-generate-algorithm-plugins
shardingsphere://features/sharding/databases/{database}/algorithms
shardingsphere://features/sharding/databases/{database}/table-rules
shardingsphere://features/sharding/databases/{database}/tables/{table}/table-rule
shardingsphere://features/sharding/databases/{database}/table-nodes
shardingsphere://features/sharding/databases/{database}/tables/{table}/nodes
shardingsphere://features/sharding/databases/{database}/table-reference-rules
shardingsphere://features/sharding/databases/{database}/table-reference-rules/{rule}
shardingsphere://features/sharding/databases/{database}/default-strategy
shardingsphere://features/sharding/databases/{database}/key-generators
shardingsphere://features/sharding/databases/{database}/key-generators/{keyGenerator}
shardingsphere://features/sharding/databases/{database}/key-generate-strategies
shardingsphere://features/sharding/databases/{database}/key-generate-strategies/{strategy}
shardingsphere://features/sharding/databases/{database}/auditors
shardingsphere://features/sharding/databases/{database}/unused-algorithms
shardingsphere://features/sharding/databases/{database}/unused-key-generators
shardingsphere://features/sharding/databases/{database}/unused-auditors
shardingsphere://features/sharding/databases/{database}/algorithms/{algorithm}/table-rules
shardingsphere://features/sharding/databases/{database}/key-generators/{keyGenerator}/table-rules
shardingsphere://features/sharding/databases/{database}/auditors/{auditor}/table-rules
shardingsphere://features/sharding/databases/{database}/rule-count

Prompts

inspect_metadata：引导模型读取 metadata，不在用户只要求查看 metadata 时执行 SQL。
safe_sql_execution：引导模型区分 read-only query 和 side-effecting SQL。
recover_workflow：引导模型从失败或过期 workflow 中恢复。
plan_encrypt_rule：引导模型规划 Encrypt feature workflow。
plan_mask_rule：引导模型规划 Mask feature workflow。
plan_broadcast_rule：引导模型规划 Broadcast feature workflow。
plan_readwrite_splitting_rule：引导模型规划 Readwrite-Splitting 规则 workflow。
plan_readwrite_splitting_status：引导模型规划 Readwrite-Splitting 状态 workflow。
plan_shadow_rule：引导模型规划 Shadow 规则 workflow。
plan_default_shadow_algorithm：引导模型规划默认 Shadow 算法 workflow。
plan_shadow_algorithm_cleanup：引导模型规划未使用 Shadow 算法清理 workflow。
plan_sharding_table_rule：引导模型规划 Sharding 表规则 workflow。
plan_sharding_table_reference_rule：引导模型规划 Sharding 绑定规则 workflow。
plan_sharding_default_strategy：引导模型规划默认 Sharding 策略 workflow。
plan_sharding_key_generator：引导模型规划 Sharding 键生成器 workflow。
plan_sharding_key_generate_strategy：引导模型规划 Sharding 键生成策略 workflow。
plan_sharding_rule_component_cleanup：引导模型规划未使用 Sharding 算法、键生成器或审计器清理 workflow。

Completions

Completions 用于补全运行时名称、metadata identifier、算法和当前 session 中的 workflow plan_id。 Client 应在选择不确定的 database、schema、table、column、storage unit、algorithm 或 plan_id 前调用 completion/complete，或读取最近的 MCP resource。当 completion 响应包含 meta next_actions 时，client 应先遵循这些动作，再猜测取值或切换到其他 tool。重试 completion 前，可通过 resources/templates/list 发现最近 resource 所需的 URI 变量，并补齐上下文。

响应与恢复

列表型业务 payload 通常包含：

items
count
continuation_mode
支持偏移量续页时的 has_more 和 next_offset

大结果 payload 会使用：

truncated
total_count
large_result_guidance

可恢复错误 payload 使用 summary、error_id 和结构化 recovery 提示。常见恢复场景包括缺失参数、不支持的 tool/resource、非法枚举、workflow 状态错误和 SQL tool 选错。需要继续操作的模型可见业务 payload 会包含顶层 summary 和唯一的顶层 next_actions。 Workflow 规划、执行、人工执行包导出和校验响应使用这些字段，引导下一次 tool call、用户补问、resource read、completion call 或终止。

JSON-RPC 数字错误码属于 MCP 协议错误契约。