Swagger MCP Bridge

Swagger MCP Bridge

SpringDoc を利用したあらゆる Spring Boot API を、本番環境に対応した MCP ゲートウェイに変換します。

Swagger MCP Bridge は OpenAPI の操作を検出して安全な MCP ツールとして公開し、API の検出、検証、レスポンスの整形、複数ステップのワークフローオーケストレーションを実現するスマートなゲートウェイ層を追加します。

名前と座標

このリポジトリでは、各エコシステムで自然に読めるよう、公開される名称を意図的に分けています。

対象	名前
プロジェクト／ドキュメント	Swagger MCP Bridge
Maven 依存関係	io.github.neo1228:openapi-mcp-spring-boot-starter
公式 MCP Registry サーバー	io.github.Neo1228/swagger-mcp-bridge
実行可能なサンプルイメージ	ghcr.io/neo1228/swagger-mcp-bridge-example:<version>
Spring 設定プレフィックス	swagger.mcp.*

プロジェクト名では従来のブリッジのブランドを維持しつつ、Maven アーティファクトには Java の利用者に適した、中立的な OpenAPI／Spring Boot スターターの座標を使用しています。レジストリサーバーと GHCR イメージは、MCP ディレクトリで使用する、パッケージ化された実行可能なサンプルを示します。

Swagger MCP Bridge を選ぶ理由

多くの MCP API ブリッジは、薄いツールラッパーにとどまります。Swagger MCP Bridge は実行時ゲートウェイとして設計されており、契約、ガードレール、運用の可視性を維持しながら、既存の Spring コントローラーを LLM クライアントに公開します。

提供機能

• 実行中の Spring アプリから SpringDoc OpenAPI の操作をボイラープレートなしで検出
• 検出した API 操作を MCP ツールとして自動登録
• スマートコンテキストゲートウェイツール：meta_get_api_capabilities、meta_validate_api_call、meta_discover_api_tools、meta_describe_api_tool、meta_list_api_groups、meta_plan_api_workflow、meta_invoke_api_workflow、meta_invoke_api_by_intent
• 機能の確認、事前検証、グループごとの探索、ドライラン計画、順次実行を実現する API カタログとワークフロー層
• OpenAPI の制約から生成される豊富な MCP 入力スキーマ：必須フィールド、列挙型、数値／文字列／オブジェクトの制限、例、非推奨のヒント
• JSONPath による射影と要約制御を備えたレスポンス整形
• 実行時のガードレール：必須引数の検証、未解決のパステンプレートの保護、安全な _headers のフィルタリング
• INVALID_ARGUMENT、SECURITY_DENIED、WORKFLOW_ERROR、HTTP_DISPATCH_FAILED などの安定したコードを含む、構造化された MCP エラーレスポンス
• Java 17 バイトコード。CI では Java 17、21、25 をカバー
• Java 21 以降のランタイムでは仮想スレッドによる HTTP ディスパッチを任意で利用可能。Java 17 ではプラットフォームスレッドに自動フォールバック
• 危険な操作に対する本番環境向けガードレール：_confirm、ブロック対象パス、ロールチェック、監査ログ、構造化されたクライアントエラー

アーキテクチャ

graph TD
    User([User / LLM Client]) <--> MCP[MCP Client / Claude Desktop]
    MCP <--> Bridge[Swagger MCP Bridge /starter/]
    Bridge --> Catalog[Operation Catalog /groups + contracts/]
    Bridge --> Workflow[Workflow Orchestrator /plan + dry-run + execute/]
    Bridge <--> Docs[SpringDoc OpenAPI /v3/api-docs]
    Bridge <--> API[Your Spring Controller /hello]

クイックスタート

1. Spring Boot アプリを作成する

以下を使用します。

• Java 17+
• Spring Boot 3.5.x
• Spring Web

2. 依存関係を追加する

Gradle（build.gradle.kts）：

plugins {
    id("org.springframework.boot") version "3.5.14"
    id("io.spring.dependency-management") version "1.1.7"
    java
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-api:2.8.17")
    implementation("io.github.neo1228:openapi-mcp-spring-boot-starter:<version>")
}

Maven アーティファクトでは、Swagger ブランドではなく中立的な OpenAPI 名を意図的に使用しています。

io.github.neo1228:openapi-mcp-spring-boot-starter

Maven（pom.xml）：

<properties>
  <openapi-mcp.version>0.1.0-SNAPSHOT</openapi-mcp.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.8.17</version>
  </dependency>
  <dependency>
    <groupId>io.github.neo1228</groupId>
    <artifactId>openapi-mcp-spring-boot-starter</artifactId>
    <version>${openapi-mcp.version}</version>
  </dependency>
</dependencies>

リモートのアーティファクトリポジトリから利用する場合は、リリースバージョン（例：0.1.0）を使用してください。

3. コントローラーを 1 つ追加する

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class HelloController {

    @Operation(operationId = "getHello", summary = "Get greeting message")
    @GetMapping("/hello")
    public Map<String, Object> hello(@RequestParam(defaultValue = "world") String name) {
        return Map.of("message", "Hello " + name);
    }
}

4. 設定を追加する（application.yml）

spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE_HTTP
        streamable-http:
          mcp-endpoint: /mcp

swagger:
  mcp:
    enabled: true
    api-docs-path: /v3/api-docs
    tool-name-prefix: api_

5. 実行と検証

1. アプリを起動します：./gradlew bootRun または ./mvnw spring-boot:run
2. OpenAPI を確認します：http://localhost:8080/v3/api-docs
3. MCP エンドポイントを確認します：http://localhost:8080/mcp
4. MCP クライアントから接続します

生成されるツール名は <tool-name-prefix><operation-id> の形式です（例：api_gethello）。

MCP クライアントのワークフロー

このスターターは、直接呼び出せる API ツールとメタツールレイヤーを公開しているため、一般的な MCP クライアントでも、ツール名を事前に推測することなく大規模な API を利用できます。

1. meta_get_api_capabilities は、API カタログの統計情報、利用可能なゲートウェイツール、オーケストレーション機能、安全ポリシー、レスポンス制御を返します。
2. meta_list_api_groups は、公開されている API カタログを OpenAPI のタグ／グループ別に要約します。
3. meta_discover_api_tools は、自然言語によるリクエストに関連する操作を検索します。
4. meta_describe_api_tool は、選択したツールのメソッド／パス、パラメーター、必須引数、リクエストボディのスキーマ、リスクフラグ、完全な MCP 入力スキーマを返します。
5. meta_validate_api_call は、HTTP をディスパッチせずに、生成された API ツール呼び出しを 1 件検証します。必須引数、リスクのある操作の確認、ディスパッチのプレビューも含まれます。
6. meta_plan_api_workflow は、ワークフローの目標を、コントラクトとリスクフラグを含む決定論的な候補ステッププランに変換します。
7. meta_invoke_api_workflow は、生成された複数の API ツールを順番にドライランまたは実行します。
8. meta_invoke_api_by_intent は、クライアントに十分な引数がすでにある場合に、最適な操作を選択して呼び出します。

設定された tool-name-prefix は引き続き適用されるため、デフォルトで生成される名前は api_meta_get_api_capabilities、api_meta_validate_api_call、api_meta_list_api_groups、api_meta_discover_api_tools、api_meta_describe_api_tool、api_meta_plan_api_workflow、api_meta_invoke_api_workflow、api_meta_invoke_api_by_intent です。

ツール呼び出しが拒否された場合、テキストコンテンツは人が読みやすい形式のままで、structuredContent.error にクライアント向けの安定した機械可読コントラクトが示されます。

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Missing required argument(s): path parameter: orderId",
    "status": 400,
    "retryable": false,
    "details": { "toolName": "api_getorder" }
  }
}

推奨されるクライアントの手順：

1. api_meta_get_api_capabilities を 1 回呼び出し、ゲートウェイ機能と安全ポリシーを確認します。
2. api_meta_discover_api_tools または api_meta_list_api_groups を使用して、候補となる操作を見つけます。
3. 正確な引数スキーマを確認するには、api_meta_describe_api_tool を使用します。
4. リスクのある呼び出しや生成された呼び出しの前に、api_meta_validate_api_call を使用します。
5. 複数のステップからなる作業では、api_meta_plan_api_workflow を呼び出してから、dryRun=true で api_meta_invoke_api_workflow を呼び出します。検証に問題がない場合に限り、dryRun=false で実行します。

ワークフローの実行は、デフォルトで安全になるよう設計されています。

• meta_validate_api_call と meta_invoke_api_workflow のドライランでは、HTTP をディスパッチする前に、ツール名、引数、必須フィールド、ディスパッチパス、リスクフラグを検証します。
• ワークフローのステップは { "id": "...", "toolName": "...", "arguments": { ... } } の形式です。
• 後続のステップでは、JSONPath による補間を使って、前のステップの構造化された結果を参照できます：${create:$.order.id}。
• 引数全体がテンプレートの場合は、解決された生の値がそのまま渡されます。テンプレートがより長い文字列の一部に含まれる場合は、その値は文字列に変換されます。
• メタツールの再帰的なオーケストレーションはブロックされます。ワークフローのステップから呼び出せるのは、生成された API 操作ツールのみです。
• リスクのある HTTP メソッドでは、ワークフロー内でも設定済みの _confirm トークンが引き続き必要です。

検証ペイロードの例：

{
  "toolName": "api_getorder",
  "arguments": {
    "orderId": "order-1"
  }
}

ワークフローペイロードの例：

{
  "dryRun": false,
  "steps": [
    {
      "id": "create",
      "toolName": "api_createorder",
      "arguments": {
        "body": { "id": "order-1", "item": "shoe" },
        "_confirm": "CONFIRM"
      }
    },
    {
      "id": "read",
      "toolName": "api_getorder",
      "arguments": {
        "orderId": "${create:$.order.id}"
      }
    }
  ]
}

大規模な API では、swagger.mcp.smart-context.gateway-only=true を設定すると、すべての操作をトップレベルの MCP ツールとして登録する代わりに、このゲートウェイ／メタレイヤーのみを公開できます。

ローカル開発環境へのインストール

アーティファクトがまだリモートレジストリに公開されていない場合：

1. ビルドしてローカル Maven キャッシュに公開します：
   • ./gradlew publishToMavenLocal
2. 利用側のアプリで：
   • リポジトリに mavenLocal() を追加します
   • バージョン 0.1.0-SNAPSHOT（または選択したローカルバージョン）を使用します

主要な設定

• swagger.mcp.enabled：ブリッジを有効／無効にします（デフォルトは true）
• swagger.mcp.api-docs-path：OpenAPI ドキュメントのパス（デフォルトは /v3/api-docs）
• swagger.mcp.tool-name-prefix：ツール名のプレフィックス（デフォルトは api_）
• swagger.mcp.smart-context.gateway-only：メタツールのみを公開します
• swagger.mcp.execution.virtual-threads-enabled：現在のランタイムがサポートしている場合、仮想スレッドを使用して外部 API 呼び出しを実行します（デフォルトは true。Java 17 では安全にフォールバックします）
• swagger.mcp.execution.allowed-argument-headers：MCP クライアントから渡される動的な _headers の任意の許可リストです
• swagger.mcp.execution.blocked-argument-headers：動的な _headers の拒否リストです。デフォルトでは、Host、Content-Length、Connection、Transfer-Encoding など、ホップバイホップ／トランスポートに影響するヘッダーをブロックします
• swagger.mcp.security.require-confirmation-for-risky-operations：リスクのあるメソッドで _confirm トークンを必須にします

リスクのある HTTP メソッド（POST、PUT、PATCH、DELETE）では、デフォルトのポリシーにより _confirm=CONFIRM が必須です。また、アダプターは HTTP 呼び出しを実行する前に、必須のパス／クエリ／ヘッダー／ボディ引数が欠けていないか検証します。これにより、MCP クライアントには不正な API 呼び出しの代わりに、明確なツールエラーが返されます。

互換性マトリックス

Starter	Java	Spring Boot	springdoc-openapi	Spring AI BOM
0.1.x	17、21、25 でテスト済み。Java 17 バイトコード	3.5.x	2.8.17	1.1.5

Spring Boot 4.x は、0.1.x 系では意図的にサポート対象外です。このリポジトリで新しいメジャー／マイナーの互換性系列がリリースされるまでは、Spring Boot 3.5.x と springdoc-openapi 2.8.x を使用してください。ビルドでは --release 17 を使用するため、アーティファクトは Java 17 でも引き続き利用でき、CI では Java 25 を含む新しいランタイムでの動作も検証されます。

コンシューマープロジェクトの例

Swagger MCP Bridge を使用する最小構成の Spring Boot アプリについては、examples/minimal-webmvc-gradle を参照してください。

この例は、レジストリやマーケットプレイスへの登録用に、実行可能な MCP サーバーイメージとしてビルドすることもできます。

docker build \
  -f examples/minimal-webmvc-gradle/Dockerfile \
  -t ghcr.io/neo1228/swagger-mcp-bridge-example:local \
  .

docker run --rm -p 8080:8080 ghcr.io/neo1228/swagger-mcp-bridge-example:local

起動後の手動スモークテスト：

• OpenAPI：http://localhost:8080/v3/api-docs
• サンプル API：http://localhost:8080/hello?name=Bridge
• MCP Streamable HTTP エンドポイント：http://localhost:8080/mcp
• Smithery／サーバーカードのメタデータ：http://localhost:8080/.well-known/mcp/server-card.json
• MCP Registry のサーバーメタデータ：http://localhost:8080/.well-known/mcp/server.json

エージェント／マーケットプレイスへのインストールガイド

• エージェントのインストール手順：llms-install.md
• マーケットプレイス対応ガイド：docs/marketplace-readiness.md
• マーケットプレイスのロゴ：docs/assets/swagger-mcp-bridge-logo.png

レジストリおよびリリースへの対応

• Maven Central リリースバンドルのワークフロー：.github/workflows/release-central.yml
• GHCR のサンプルサーバーイメージのワークフロー：.github/workflows/publish-example-server.yml
• MCP Registry メタデータ：registry/server.json
• 静的ディスカバリーメタデータ：examples/minimal-webmvc-gradle/src/main/resources/static/.well-known/mcp/
• メタデータ検証スクリプト：scripts/verify-marketplace-metadata.sh
• Central バンドルのヘルパー：scripts/build-central-bundle.sh

公式 MCP Registry は Docker／OCI メタデータを受け付けます。そのため、公開されるサンプルイメージには必須の io.modelcontextprotocol.server.name=io.github.Neo1228/swagger-mcp-bridge ラベルが付与され、登録元として registry/server.json が使用されます。Starter アーティファクトは、座標 io.github.neo1228:openapi-mcp-spring-boot-starter の通常の Maven 依存関係です。サンプルサーバーが公開 HTTPS /mcp エンドポイントでホストされれば、Smithery の URL 公開にも対応します。それまでは、このリポジトリで必要な静的サーバーカードと、ローカル／Uplink 検証手段を提供しています。

リリースとバージョン管理

• リリース手順：RELEASING.md
• バージョン管理ポリシー：VERSIONING.md
• 変更履歴：CHANGELOG.md

開発

• テストの実行：./gradlew test
• コントリビューションガイド：CONTRIBUTING.md
• セキュリティに関する報告：SECURITY.md

ライセンス

Apache License 2.0（LICENSE）