MCP Mediator – Automatic MCP Server Generation

MCP Mediator – MCP サーバーの自動生成

既存のソースコード、サービスクラス、ヘルパーメソッド、外部 MCP ツールから MCP サーバーを自動生成する、Java ベースの Model Context Protocol（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：利用可能なエンドポイント用の MCP サーバーを自動生成する Spring Boot autoconfiguration
• さまざまなサービス向けの実装モジュール：
  • 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 サーバーです。すべてのクエリは mcp-mediator-implementation-query モジュールに含まれ、MCP Mediator リクエストハンドラーを使用して定義されています。 現在、以下のクエリが実装されています：

• Wikipedia MCP サーバー：入力されたクエリで Wikipedia を検索します
• Stackoverflow MCP サーバー：Stackoverflow のウェブサイトを検索します
• GitHub MCP サーバー：GitHub のプロジェクトを検索します

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。まずはこちらをお読みください！

ライセンス

このプロジェクトは GPL3 ライセンスの下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

セキュリティと認可

MCP Mediator は、Spring Security を含む認可フレームワークとのネイティブな統合をサポートしています。 MCP リクエスト（特に STDIO 経由のリクエスト）は JSON ペイロードのみに依存するため、McpMediatorInterceptor を使用して引数ペイロードからトークンを抽出し、セキュリティコンテキストに橋渡しできます。

このために、専用のモジュールを2つ用意しています：

• mcp-mediator-security：Spring を使用しないプロジェクト向けの汎用セキュリティコンテキストとスレッド伝播を提供します。
• mcp-mediator-spring-security：Mediator を Spring Security のネイティブな SecurityContextHolder にシームレスに接続します。

実装の詳細とコード例については、Wiki の セキュリティ統合ガイドをご覧いただくか、mcp-mediator-example モジュールの GenericSecurityExample および SpringSecurityExample をご参照ください。

可観測性とエラー処理の例

mcp-mediator-example モジュールには、Mediator を完全に計測する方法を示す専用の例が含まれています：

• ObservabilityExample：OpenTelemetry インスタンスをプログラムで注入し、トレースをエクスポートする方法を示します（Datadog 用の OTLP、または標準的な SLF4J ログ用の LoggingSpanExporter を使用します）。
• CustomErrorHandlerExample：McpMediatorExceptionHandler をカスタマイズして実行エラーを捕捉し、SLF4J ロガーに渡し、内部の Java スタックトレースを公開せずに、安全に難読化されたフォールバック文字列をクライアントに返す方法を示します。