谷雨开源 SaaS 平台（G2rain）
本文档由 g2rain-mcp-registry 的 README.md 自动同步生成。

G2Rain

# g2rain-mcp-registry

下一代AI软件开发范式，AI原生Agent平台，开源的企业级SaaS底座。

谷雨 Agent 平台的 MCP 工具边界。它维护外部服务与工具资料，解析工具输入 schema，并在 /mcp 上为 Agent Runtime 提供工具发现与调用代理。

官网 (opens new window) · Issues (opens new window) · Discussions (opens new window)

# 平台定位

MCP Registry 负责工具能力的目录、协议适配与下游调用边界。Agent Studio 在 Agent/Skill 中选择工具，Agent Runtime 使用 MCP 协议发现和调用工具；模型访问由 Model Nexus 独立负责。

# 功能概览

能力 说明
服务与工具资料 管理 MCP 外部服务和工具档案。
工具发现 通过 /mcp 处理 tools/list，按可用工具资料返回定义。
工具调用代理 通过 tools/call 组装请求上下文和输入 schema，调用下游服务并映射结果或错误。
主体上下文转发 在可信边界内向下游工具传递必要的主体上下文。

# 核心流程

flowchart LR
  Runtime[Agent Runtime] -->|tools/list / tools/call| Registry[MCP Registry]
  Registry --> DB[(工具资料)]
  Registry --> Downstream[下游工具服务]
  1. 管理端维护 MCP 外部服务与工具资料。
  2. Runtime 通过 /mcp 请求工具目录，Registry 返回可发现的工具定义。
  3. Runtime 调用工具时，Registry 解析 schema、组装可信上下文、访问下游服务并返回 MCP 结果。

# 工程结构

模块 说明
g2rain-mcp-registry-api 提供工具元数据、查询条件及 API 契约。
g2rain-mcp-registry-biz 实现资料管理、schema、请求上下文、工具列表与调用处理器。
g2rain-mcp-registry-startup 组装 Spring Boot 与 MCP Server。

模块依赖方向固定为：startup → biz → api。

# 本地启动

前置条件：JDK 25、Maven，以及可用的 MySQL、Redis 和本地联调所需的下游 MCP 服务。默认 profile 为 nacos；如需本地联调，使用 dev 并在本机安全地提供配置。

mvn -pl g2rain-mcp-registry-startup -am spring-boot:run "-Dspring-boot.run.profiles=dev"

端口由 SERVER_PORT 环境变量控制，未设置时为 8080。共享环境应通过 Nacos 和环境变量管理服务地址与凭据，禁止将真实凭据写入版本库。

# 接口与配置

入口/配置 用途
/mcp MCP HTTP 端点，处理工具发现和工具调用。
/mcp_external_service 查询、保存和删除 MCP 外部服务资料。
/mcp_tool_profile 查询、保存和删除 MCP 工具资料。
SERVER_PORT HTTP 端口，默认 8080。
SPRING_PROFILES_ACTIVE 默认 nacos；本地可显式使用 dev。
NACOS_SERVER_ADDR Nacos 注册与配置中心地址。

当前配置声明 STATELESS MCP 协议，而部分源码注释描述 STREAMABLE 分支；实际协议和会话语义应以集成测试验证结果为准。

# 构建与验证

目标 命令 说明
构建与验证 mvn clean verify 执行 Maven 验证生命周期。
启动服务 mvn -pl g2rain-mcp-registry-startup -am spring-boot:run -Dspring-boot.run.profiles=dev 本地联调使用独立开发环境。
构建本地镜像 ./build.sh <tag> 使用 Jib 构建 g2rain/g2rain-mcp-registry:<tag>。

# 协作关系

  • Agent Studio 负责在 Agent 配置中选择和组合工具能力。
  • Agent Runtime 从注册中心获取 MCP 工具，并在任务执行期间调用。
  • Model Nexus 与本模块相互独立：前者提供模型能力，后者提供工具能力。

# 安全与运维

  • 下游 URL、凭据、Token、工具参数和结果可能包含敏感信息，只可由受控配置提供并在日志中脱敏。
  • 写工具需要明确授权、幂等、确认与审计；不得以“内网服务”替代访问控制。
  • 上线前验证 /mcp 路由、协议模式、工具 schema、主体上下文转发、超时、错误映射和下游健康状态。

# 文档与贡献

欢迎通过 Issue、文档改进、功能建议和 Pull Request 参与贡献。提交前请执行 mvn clean verify，并同步协议、schema、配置、安全和架构文档。

← g2rain-basis →