Star Wars API & MCP server (swapi.build)

SWAPI.build

People、Films、Planets、Species、Starships、Vehicles のデータを提供する、無料のオープンソース Star Wars API です。Quarkus と GraalVM で構築されており、即時起動、最小限のメモリ使用量、そしてすぐに使えるパフォーマンスを実現しています。

オリジナルの SWAPI（Paul Hallett が作成し、Juriy Bura が保守）に着想を得たこのプロジェクトは、決してオフラインにならない Star Wars API が必要だという思いから生まれました。サードパーティ API の停止によってライブデモが動かなくなった経験があれば、このプロジェクトが存在する理由がおわかりでしょう。

クイックスタート

前提条件： Java 25 と Maven（または同梱の Maven Wrapper を使用してください）。

cd swapi-app
./mvnw quarkus:dev

API とフロントエンドは http://localhost:5432 で利用できます。

API エンドポイント

ベースパス：/api

ID は各エンティティの url フィールドに含まれるレコード ID です（映画の場合、1 は A New Hope です）。 成功時のレスポンスは 200 を返し、不明な ID または数値以外の ID には 404 を返します。

GET /api/stats は、過去 24 時間（?period=24h、時間単位）、7 日間（デフォルト、日単位。時間単位の場合は &granularity=hour）、または 30 日間（?period=30d、日単位）のルートごと（例：/api/people/{id} または /mcp）およびグループごと（REST API、MCP、ページ、SEO、その他）の匿名リクエスト数を返します。比較用として、それぞれの期間の直前の期間のデータも含まれます。また、performance にはルートごとおよびグループごとのサーバー応答時間（リクエスト数、平均、最小、最大、標準偏差、ミリ秒単位の概算 p50/p95/p99。ネットワークは除外）が含まれます。これらは IP アドレスやクライアントの詳細を記録せずに集計されます。/stats ページでは、フィルター、トレンドチャート、ランキング、パフォーマンスセクションとともに、同じ数値を確認できます。

すべてのレスポンスは JSON です。例：

curl http://localhost:5432/api/people/1

OpenAPI

API コントラクトの全内容は /openapi.json で提供されます（OpenAPI 3.x。コードから生成されるため、常に同期されています）。ドキュメントページ では、この内容を表示し、すべてのエンドポイントを「試す」ことができます。たとえば、次のようにクライアントを生成できます。

npx @openapitools/openapi-generator-cli generate -i https://swapi.build/openapi.json -g typescript-fetch

MCP サーバー

swapi.build は、Streamable HTTP 経由のリモート MCP サーバーでもあります。Streamable HTTP クライアントであればどれでも利用できます。ステートレスな 2026-07-28 リビジョンでは自己完結型のリクエストを送信し、それ以前のリビジョンでは initialize を通じてセッションをネゴシエートします。どちらも同じエンドポイントで提供されています。レガシーの HTTP+SSE トランスポート（2024-11-05）には対応していません。公式提供の読み取り専用で、認証は不要です。

https://swapi.build/mcp

詳しいセットアップガイド：swapi.build/docs/mcp

resource は PEOPLE、FILMS、PLANETS、SPECIES、STARSHIPS、VEHICLES のいずれかです。 ID は各エンティティの url フィールドにあるレコード ID です（FILMS の場合、1 は A New Hope です）。

キャッシュ： Quarkiverse MCP Server 2.0.0 は、ステートレスなディスカバリーおよびツール一覧のレスポンスに、必須の ttlMs: 0 と cacheScope: "public" フィールドを出力します。 TTL がゼロの場合は直ちに古くなり、正の有効期間は設定されていません。 そのキャッシュヒント はディスカバリー、一覧メソッド、resources/read に適用されますが、tools/call には適用されません。 ここでは Star Wars のデータをツール経由で公開しているため、sw_random を含め、ツール結果のキャッシュは有効になっていません。REST／エッジキャッシュは別の仕組みです。

claude mcp add --transport http swapi-build https://swapi.build/mcp

{
  "mcpServers": {
    "swapi-build": { "type": "http", "url": "https://swapi.build/mcp" }
  }
}

codex mcp add swapi-build --url https://swapi.build/mcp

[mcp_servers.swapi-build]
url = "https://swapi.build/mcp"

{
  "servers": {
    "swapi-build": { "type": "http", "url": "https://swapi.build/mcp" }
  }
}

{
  "mcpServers": {
    "swapi-build": {
      "type": "streamable-http",
      "url": "https://swapi.build/mcp",
      "disabled": false
    }
  }
}

サーバーはアイドル時にゼロまでスケールダウンします。最初の接続試行に失敗した場合は、もう一度お試しください。 ネイティブバイナリは数十ミリ秒で起動しますが、プラットフォームによるコンテナーのプロビジョニングには少し時間がかかることがあります。その後の呼び出しは、クライアントがステートレスかセッションベースかにかかわらず高速です。

ブラウザーでの WebMCP（実験的）

このウェブサイトでは、WebMCP 経由で sw_list、sw_get、sw_search、sw_random を利用できます。 ツール名と引数は、リモート MCP ツールと一致します。リソース名は大文字です。 各ブラウザーツールは表示中のエクスプローラーを更新し、ok、data、resource、path を含む JSON 結果として完全なレコードを返します。 ブラウザーの結果エンベロープは、リモート MCP トランスポートとは異なります。

WebMCP が有効で、document.modelContext API に対応したブラウザーを使用してください。セットアップとデモのガイド では、インスペクター、呼び出し例、キャンセル時の動作について説明しています。API が利用できない場合も、サイトは通常どおり動作します。モデル API キーや AI ランタイムは サイトに組み込まれていません。JavaScript は Quinoa によってバンドルされ、Quarkus ネイティブ実行可能ファイルから配信される場合も含め、ブラウザー内で実行されます。

クライアントの例

• examples/java/langchain4j-mcp-client — 自然言語で質問します。ツールは上記の MCP サーバーから提供されるため、この例ではツールを定義しません。
• examples/java/quarkus-rest-client — 型付きクライアントを使用して、Java から REST API を呼び出します。

プロジェクト構成

swapi-app/
  src/main/
    java/com/eldermoraes/     # Backend (Quarkus + Jakarta REST)
      film/                   # Film model, service, resource
      people/                 # People model, service, resource
      planet/                 # Planet model, service, resource
      specie/                 # Specie model, service, resource
      starship/               # Starship model, service, resource
      vehicle/                # Vehicle model, service, resource
      mcp/                    # MCP server tools (sw_list, sw_get, sw_random, sw_search)
      SWObject.java           # Base model class
      SWService.java          # Service interface
      ApiResource.java        # Root /api endpoint
      ApplicationPath.java    # Jakarta REST base path (/api)
    resources/
      data/                   # Static JSON data files
      application.properties  # Quarkus configuration
    webui/                    # Frontend (TypeScript + Vite)
      src/
        api.ts                # API client with request management
        main.ts               # SPA router
        pages/                # Page renderers (home, resource, docs, mcp, about, privacy, terms)
        json-highlight.ts     # JSON syntax highlighting for result panels
        style.css             # Site styles
        types.ts              # TypeScript interfaces for API resources
        constants.ts          # Shared resource metadata
        utils.ts              # Shared utilities (escapeHtml)
  src/test/
    java/com/eldermoraes/     # Regression suite (REST contracts, MCP tools, forwarded headers)

各バックエンドのドメイン（film、people、planet など）は、同じパターンに従います。

• モデル（例：Film.java）：ネイティブイメージをサポートするための @RegisterForReflection を付けた POJO
• サービス（例：FilmService.java）：起動時に JSON からデータを読み込み、メモリにキャッシュします
• リソース（例：FilmResource.java）：@RunOnVirtualThread を付けた Jakarta REST コントローラー

ビルド

cd swapi-app

# Development mode (live reload)
./mvnw quarkus:dev

# Production JAR
./mvnw package
java -jar target/quarkus-app/quarkus-run.jar

# Native executable (requires GraalVM or container build)
./mvnw package -Dnative
./mvnw package -Dnative -Dquarkus.native.container-build=true

フロントエンドは Maven のビルド中に Quinoa によって自動的にビルドされ、バンドルされます。別途 npm を実行する必要はありません。

デプロイ

アプリは、Oracle Cloud 上のセルフホスト可能なサーバーで、systemd によって管理されるネイティブ（GraalVM/Mandrel）実行ファイルとして動作し、Caddy の背後に配置されます（TLS は Let's Encrypt 経由）。DNS は Cloudflare で管理されており、サーバーを指す DNS のみのレコードが設定されています。GitHub Release を公開すると .github/workflows/native-binary.yml が実行されます。テストスイート、Release に添付するネイティブビルド、手動承認の後、SSH 経由でサーバーにインストールし、本番環境のプローブを実行します。運用手順書は docs/DEPLOY.md です。

技術スタック

• ランタイム： Java 25 と Virtual Threads 上で動作する Quarkus 3.33
• MCP サーバー： Quarkiverse MCP Server — Streamable HTTP、ステートレスおよびセッションベースのクライアント
• シリアライゼーション： Jakarta REST + JSON-B
• ネイティブイメージ： Mandrel ビルダー経由の GraalVM
• フロントエンド： TypeScript + Vite、Quinoa による配信

コントリビューション

プルリクエストをいつでも歓迎します。バグの修正、ドキュメントの改善、新機能の追加など、ぜひ参加して、銀河で最高の Star Wars API をさらに良くしてください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/my-change）
3. テストを含めて変更を加え、テストスイートを実行します：cd swapi-app && ./mvnw test
4. コミットしてプッシュします
5. プルリクエストを作成します

変更履歴とリリース

リリース履歴は CHANGELOG.md にあります。タグ付きリリースは リリースページで確認できます。/openapi.json で配信されるバージョン（info.version）は、常に最新のリリースバージョンです。リリース手順については docs/RELEASE.md に記載されています。

クレジット

• Paul Hallett によるオリジナルの SWAPI。現在は Juriy Bura がメンテナンスしています
• Wookieepedia など、コミュニティ主導の情報源から提供された Star Wars のデータ
• Star Wars のコンテンツおよび画像はすべて Lucasfilm Ltd. と Disney の所有物です。このプロジェクトは Lucasfilm または Disney と提携しておらず、両社から承認も受けていません。

ライセンス

Apache License 2.0 に基づいてライセンスされています。このウェブサイトでは プライバシーポリシーと利用規約も公開しています。