MCP Mediator – Automatic MCP Server Generation

MCP Mediator – 自动生成 MCP 服务

一个基于 Java 实现的 Model Context Protocol（MCP）中介，可根据现有源代码、服务类、辅助方法和外部 MCP 工具自动生成 MCP 服务。MCP Mediator 将这些不同的组件整合为统一的 MCP 服务，通过单一入口简化 MCP 客户端与服务之间的通信。

无需手动维护多个 MCP 服务，这款工具简化了 MCP 生态系统中的集成与执行，并能够在不修改现有代码库和工具的情况下生成 MCP 服务，从而让它们兼容 MCP。

概述

MCP Mediator 实现了 Model Context Protocol 规范，提供了一个功能强大的框架，用于：

• 处理 MCP 请求和响应
• 管理工具执行
• 支持各种传输机制
• 集成 Spring Framework 和 Spring Boot

如需了解更多信息，请访问项目 Wiki：MCP Mediator Wiki。 Wiki 页面结构如下：

• 快速入门
• 基本用法
• 配置
• 组件

功能

:white_check_mark: 已完成：

• 支持 stdio/sse 传输
• 可扩展的请求处理系统
• 可配置的服务能力
• 支持多种工具实现
• 支持代理多个 MCP 服务
• 根据现有方法和服务自动生成 MCP 服务工具

:hourglass_flowing_sand: 正在进行：

• 集成 Spring Framework 和 Spring Boot（已完成）
• 全面的错误处理（已完成）
• Docker 实现（已完成）
• Dropbox 实现（已完成）

:baby_bottle: 计划中：

• 为现有 Spring Controllers 生成 MCP 服务，并在 MCP 客户端与控制器之间中介请求（已完成）
• 为现有 OpenAPI 规范生成 MCP 服务，并为 API 生成 MCP Tool，然后转发请求（已完成）

模块

• mcp-mediator-api：核心 API 接口和契约
• mcp-mediator-core：核心实现和通用功能
• mcp-mediator-commons：可复用组件，让实现更加轻松
• mcp-mediator-example：展示如何使用和扩展中介框架的示例
• mcp-mediator-spring：Spring Framework 和 Spring AI 集成
• mcp-mediator-spring-boot-starter：Spring Boot autoconfiguration，用于为可用端点自动生成 MCP 服务
• 各种服务的实现模块：
  • mcp-mediator-implementation-docker：Docker 服务集成了解更多
  • mcp-mediator-implementation-dropbox：Dropbox 服务集成（进行中）
  • mcp-mediator-implementation-query：使用公共 API 的查询服务：所有 Query MCP 服务列表

快速入门

前提条件

• Java 17 或更高版本
• Maven 3.6 或更高版本
• Spring Boot 3.2.2 或更高版本（用于 Spring Boot 集成）

所有示例均位于 mcp-mediator-exmple 模块中。目前仍在持续开发，后续会添加更多示例。

默认 MCP Mediator

要使用 STDIO 传输创建 MCP Mediator：

DefaultMcpMediator mediator = new DefaultMcpMediator(McpMediatorConfigurationBuilder.builder()
          .createDefault()
          .serverName(MY_EXAMPLE_MCP_SERVER_STDIO)
          .build());
mediator.registerHandler(new WikipediaQueryRequestHandler());
mediator.initialize();

要将示例作为 Claude Desktop MCP 服务运行：

{
  "mcpServers": {
    "my_java_mcp_server": {
      "command": "[path to]/run.sh",
      "args": [
        "DefaultMcpMediatorStdioExample"
      ]
    }
  }
}

此配置会将 DefaultMcpMediatorStdioExample 作为 STDIO MCP 服务运行。 请确保将 run.sh 设为可执行文件，并将 mvn 命令添加到路径中。

 ./run.sh ClassName [arg1 arg2 ...]

此 Mediator 会运行一个带有处理程序的 STDIO MCP 服务，并将 MCP 客户端（例如 Claude Desktop）的请求委托给 已注册的处理程序。

将现有代码转换为 MCP 服务

使用 @McpService 将现有代码、服务、辅助类或方法自动转换为 MCP 服务：

DefaultMcpMediator mediator = new DefaultMcpMediator(McpMediatorConfigurationBuilder.builder()
                .createDefault()
                .serverName(MY_EXAMPLE_MCP_SERVER_STDIO)
                .serverVersion("1.0.0.0")
                .build());
// DockerClientService is an existing service class to interact with the installed Docker Client
        mediator.registerHandler(McpServiceFactory.create(new DockerClientService(dockerClient))
                .createForNonAnnotatedMethods(false)
                .build());
        mediator.initialize();

DockerClientService：

@McpService(name = "docker_mcp_server",  description = "provides common docker command as mcp tools")
public class DockerClientService {

    DockerClient internalClient;

    @McpTool(name = "docker_start_container",
            description = "start an existing docker container using its containerId! containerId is required and " +
                    "can't be null or empty! if successful, returns true.")
    public boolean startContainerCmd(@NonNull String containerId) {
        internalClient.startContainerCmd(containerId)
                .exec();
        return true;
    }
    // ...
}

查看 mcp-mediator-implementation-docker 了解更多详情。

代理 MCP Mediator

要创建代理服务：

 // as an example ~/sdk/jdk/jdk-17.0.14+7/Contents/Home/bin/java
String command = args[0];
// e.g., -jar ~/mcp-mediator-example.jar
List<String> remoteServerArgs = List.of(Arrays.copyOfRange(args, 1, args.length));

ProxyMcpMediator mediator = new ProxyMcpMediator(McpMediatorConfigurationBuilder.builder()
       .creatProxy()
       .serializer(new ObjectMapper())
       .tools(true)
       .addRemoteServer(McpMediatorProxyConfiguration.McpMediatorRemoteMcpServerConfiguration.builder()
               .remoteTransportType(McpTransportType.STDIO)
               .remoteServerAddress(command)
               .remoteServerArgs(remoteServerArgs)
               .build())
       .serverName(MY_EXAMPLE_MCP_SERVER_STDIO)
       .serverVersion("1.0.0.0")
       .build());

mediator.initialize();

此 Mediator 会创建一个代理 MCP 服务，连接到所有给定的远程服务，并充当客户端与远程服务之间的代理。Mediator 会在初始化过程中向客户端公布所有可用的 Tools。它也可以像 DefaultMcpMediator 一样，通过 ProxyMcpMediator#registerHandler() 注册请求处理程序来扩展。

已实现的查询 MCP 服务

查询 MCP 服务会接收用户的查询，并搜索相关来源以查找与输入查询相关的内容。所有查询都属于 mcp-mediator-implementation-query 模块，并使用 MCP Mediator 请求处理程序定义。 目前已实现以下查询：

• Wikipedia MCP 服务：使用输入查询搜索 Wikipedia
• Stackoverflow MCP 服务：搜索 Stackoverflow 网站
• GitHub MCP 服务：搜索 GitHub 项目

参与贡献

欢迎贡献！请随时提交 Pull Request。请先阅读此文！

许可证

本项目采用 GPL3 许可证授权——详情请参阅 LICENSE 文件。

安全与授权

MCP Mediator 原生支持与授权框架集成，包括 Spring Security。 由于 MCP 请求（尤其是通过 STDIO 传输的请求）完全依赖 JSON 负载，你可以使用 McpMediatorInterceptor 从参数负载中提取令牌，并将其传递到安全上下文中。

我们为此提供了两个专用模块：

• mcp-mediator-security：为非 Spring 项目提供通用安全上下文和线程传递功能。
• mcp-mediator-spring-security：将 Mediator 无缝接入 Spring Security 原生的 SecurityContextHolder。

如需完整的实现详情和代码示例，请查看 Wiki 中的 安全集成指南，或参考 mcp-mediator-example 模块中的 GenericSecurityExample 和 SpringSecurityExample。

可观测性与错误处理示例

mcp-mediator-example 模块包含专门的示例，演示如何全面为 Mediator 添加检测能力：

• ObservabilityExample：演示如何以编程方式注入 OpenTelemetry 实例以导出跟踪数据（通过 OTLP 导出到 Datadog，或使用 LoggingSpanExporter 输出标准 SLF4J 日志）。
• CustomErrorHandlerExample：演示如何自定义 McpMediatorExceptionHandler，以拦截执行错误、通过 SLF4J 日志记录器处理错误，并向客户端返回安全且经过混淆处理的回退字符串，而不暴露内部 Java 堆栈跟踪。