复古 护眼 海天 深邃 暗黑 默认

本章面向希望扩展 ShardingSphere-MCP 的开发者。 用户安装和使用请查看用户手册，协议表面请查看技术参考。

模块结构

MCP 子链路按 api + support + features + core + bootstrap 分层组织：

  • mcp/api：public tool/resource handler 契约、descriptor 类型、协议 response 和 MCP 协议异常。
  • mcp/support：database metadata、execution、capability、workflow context、模型、facade、SPI 和复用 helper。
  • mcp/features/encrypt：Encrypt MCP feature。
  • mcp/features/mask：Mask MCP feature。
  • mcp/core：handler 发现、registry、request scope、session、SQL execution trace、metadata discovery 和 runtime context。
  • mcp/bootstrap：基于 MCP Java SDK 的 bootstrap、HTTP/STDIO transport、配置加载和生命周期管理。
  • distribution/mcp：独立打包、启动脚本、配置和 Dockerfile。
  • test/e2e/mcp：端到端契约验证。

mcp/bootstrap 只负责发布聚合后的协议表面，不应硬编码具体 feature 业务。

新增 Feature Plugin

新增 feature 的推荐路径：

  1. 在 mcp/features/<feature> 下创建模块。
  2. 依赖 mcp/api。
  3. 如果需要 database metadata、SQL execution 或 workflow 支持，依赖 mcp/support。
  4. 只有需要 service 级 handler context 时才依赖 mcp/core。
  5. 不依赖 mcp/bootstrap。
  6. 实现 MCPHandlerProvider。
  7. 通过 getToolHandlers() 和 getResourceHandlers() 返回 feature 自己暴露的 handlers。
  8. 如果 feature 拥有 workflow definitions，在同一个 provider 上实现 MCPWorkflowDefinitionProvider。
  9. 在 src/main/resources/META-INF/services/ 注册 org.apache.shardingsphere.mcp.api.MCPHandlerProvider。
  10. 在 META-INF/shardingsphere-mcp/mcp-descriptors 下添加 descriptor。

如果 feature 要作为官方默认能力随发行包提供，还需要：

  • 加入 mcp/features/pom.xml。
  • 加入 distribution/mcp/pom.xml。

如果 feature 是可选插件，构建后把 jar 放入发行包 plugins/ 目录。

Handler 与 Descriptor

对外新增 tool：

  • 实现 MCPToolHandler<T extends MCPHandlerContext>。
  • 声明 context type。
  • 声明 canonical tool name。
  • 在 descriptor 中维护 input schema、output schema、annotations、相关 resources、follow-up tools 和副作用说明。

对外新增 resource：

  • 实现 MCPResourceHandler<T extends MCPHandlerContext>。
  • 声明 context type。
  • 声明 canonical URI template。
  • 在 descriptor 中维护 URI 参数含义、对象范围、MIME type、title、description、annotations 和关系元数据。

运行时代码需要 descriptor 时，应使用 canonical tool name 或 resource URI template，通过 MCPDescriptorCatalogIndex 从 catalog 解析。 不要在 handler 内重复维护 descriptor 字段。

Context 选择

  • service 级 handler 使用 MCPServiceHandlerContext。
  • database metadata 或 execution handler 使用 MCPDatabaseHandlerContext。
  • workflow handler 使用 MCPWorkflowHandlerContext。

命名与唯一性

  • Tool name 和 resource URI pattern 必须全局唯一。
  • 重复 handler 或重复 descriptor 会在启动期校验时被拒绝。
  • Feature URI 使用 shardingsphere://features/<feature>/... 命名空间。
  • 不要和公共 metadata path 混用。

Descriptor 维护原则

Descriptor 应说明模型如何使用协议表面，而不是只重复 tool 名或 URI。

维护时应包含：

  • 清晰的字段描述。
  • JSON schema 约束。
  • 输出结构和示例。
  • 安全 annotations。
  • 副作用范围。
  • 相关 resources。
  • 下一步 actions。
  • completion target。
  • workflow 恢复路径。

Tool annotations 只是客户端提示，不能替代运行时校验、SQL 安全检查、用户审批或服务端授权。