AI导哈

服务端聚合代理工具

MCP Java SDK实现的服务端聚合与代理调用工具，支持远程MCP工具和本地API工具的聚合调用，适用于需要统一管理和代理多种工具的场景。

  • by AiKrai001
  • Kotlin
  • 本地部署
  • 更新于
在 GitHub 查看 AiKrai001/mcp-aggregator

使用说明

MCP 聚合器使用说明

MCP Java SDK（io.modelcontextprotocol.sdk:mcp）实现 MCP 服务端聚合与代理调用能力。本文档说明运行方式、配置要点、权限与过滤机制、调用示例及故障排查。

简易MCP聚合 （使用codex编写）

项目概述

  • MCP 端点：/mcp（Streamable HTTP）
  • 聚合两类工具：
    • 远程 MCP 工具（STDIO / SSE / Streamable HTTP）：通过上游客户端采集工具列表并代理调用
    • 本地 API 工具（VIRTUAL）：从数据库维护的 HTTP API 定义生成 MCP 工具并转发请求
  • 权限控制：基于访问令牌 Token 进行会话级工具过滤（列表过滤 + 调用兜底）

运行环境

  • JDK：21
  • 构建：Gradle 8.x
  • 数据库：默认 H2（./db/demo），可外置数据库通过 Spring 配置覆盖
  • 端口：server.port（默认 18080）

快速开始

# 构建
gradle build -x test

# 开发运行
gradle bootRun

# 生产运行
java -jar build/libs/*-SNAPSHOT.jar
  • MCP 端点：http://localhost:18080/mcp
  • H2 控制台（默认开启）：/h2-console

上游 MCP 服务配置

支持三种类型：

  • STDIO：配置 command + arguments（可选 environment）
  • SSE：配置 baseUrl + endpoint（连接前预检 text/event-stream）
  • Streamable HTTP：配置 baseUrl + endpoint

同步工具：

  • 创建/更新服务会触发工具刷新
  • 也可通过“同步工具”操作主动刷新（参考 Controller/Service）

本地 API 工具（VIRTUAL）

  • 在数据库维护 HTTP API 定义（URL、PATH、METHOD、HEADERS、超时、输入 Schema）
  • 将 API 工具绑定到 VIRTUAL 类型服务，自动生成同名 MCP 工具并由服务端执行 HTTP 请求

相关数据与服务：

  • API 工具仓储：src/main/kotlin/com/app/repository/mcp/ApiToolRepository.kt:1
  • API 工具业务：src/main/kotlin/com/app/service/mcp/ApiToolService.kt:1
  • VIRTUAL 工具生成/同步：src/main/kotlin/com/app/service/mcp/VirtualToolRegistry.kt:1

命名空间与重名规避

  • 为避免不同上游工具重名，远程 MCP 工具注册时使用“展示名”：<prefix>.<toolName>
  • 服务的 prefix 为空时，沿用原始工具名
  • 调用远端时仍使用原始工具名（仅注册展示名加前缀）

权限与工具过滤

请求头：

  • Authorization: Bearer <token>

工具刷新机制

  • 创建/更新 MCP 服务、绑定/解绑 API 工具、远程工具列表同步成功后 → 自动触发注册集刷新
  • 刷新策略：计算差异 → addTool/removeTool → notifyToolsListChanged() 通知客户端刷新
  • 刷新入口：src/main/kotlin/com/app/mcp/McpAggregator.kt:52

JSON-RPC 调用示例

tools/list：

POST http://localhost:18080/mcp
Content-Type: application/json
Authorization: Bearer <token>

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list",
  "params": {}
}

tools/call：

POST http://localhost:18080/mcp
Content-Type: application/json
Authorization: Bearer <token>

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "<前缀.工具名>",
    "arguments": {
      "k": "v"
    }
  }
}

故障排查

  • 远程工具未出现：
    • 检查服务是否启用、类型是否正确
    • SSE 端点需返回 text/event-stream（预检失败会在日志中提示）
    • 是否配置了 prefix 导致展示名变化
  • 调用被拒：
    • Token 是否包含该“展示名”的授权（当服务有 prefix 时应为 <prefix>.<name>）
  • 列表未过滤：
    • 是否带了有效 Token
    • 查看 McpAccessTokenFilter 日志是否建立上下文

变更记录

  • 替换 Spring AI → 纯 MCP Java SDK
  • 移除：Spring AI 相关依赖与工具回调 Provider
  • 新增：McpServletConfig、McpAggregator（服务端直接注册工具并代理调用）
  • 加强：基于前缀的命名空间、会话级列表过滤与调用兜底

如需进一步将权限注入迁移到 MCP 传输上下文（替代 ThreadLocal），或增加示例脚本（Postman / HTTPie），请在 Issue 或任务中说明。

相关 MCP