Mcp Starwars

SWAPI Star Wars API 用の MCP サーバーです。 このプロジェクトの主な目的は、MCP サーバーを使って API とやり取りする方法を紹介することです。

注記：この MCP サーバーが使用するデータはすべて、SWAPI のドキュメント](https://swapi.dev)から取得されます。

🔧 機能

• Star Wars キャラクターの一覧表示：検索フィルター（任意）と自動ページネーションでキャラクターデータを取得します
• 惑星、映画、種族、ビークル、宇宙船の一覧表示：検索機能を使って、Star Wars のすべてのエンティティコレクションにアクセスします
• ID によるエンティティ詳細の取得：特定のキャラクター、惑星、映画、種族、ビークル、宇宙船の詳細情報を取得します
• 自動ページネーション：1 回の API 呼び出しで、すべてのページのデータをシームレスに取得します
• 組み込みキャッシュ：API レスポンスをインテリジェントにキャッシュして、パフォーマンスを最適化します
• キャッシュ管理：キャッシュをクリアし、キャッシュ統計を確認してパフォーマンスを監視できます
• ツールベースの MCP 統合：このサーバーを Model Context Protocol（MCP）ツール（VS Code、Claude など）に登録できます

🧰 ツール

1. get_people 🧑‍🤝‍🧑

• 説明：自動ページネーションと任意の検索機能を使って、Star Wars キャラクターの一覧を取得します
• 入力：
  • page（任意の number）：取得するページ番号（デフォルトは 1）
  • search（任意の string）：検索する名前または名前の一部
  • fetchAllPages（任意の boolean）：結果の全ページを自動取得するかどうか（デフォルトは true）
• 戻り値：名前、身体的特徴、出身星、関連エンティティを含む、Star Wars キャラクターデータのコレクション

2. get_person_by_id 👤

• 説明：ID を指定して、特定の Star Wars キャラクターの詳細を取得します
• 入力：
  • id（文字列または数値）：キャラクターの一意の識別子
• 戻り値：名前、身体的特徴、故郷の惑星、関連エンティティを含む、指定したキャラクターの完全なデータ

3. get_planets 🪐

• 説明：ページネーションを自動処理し、検索にも対応して Star Wars の惑星を一覧表示します
• 入力：
  • page（任意の数値）：取得するページ番号（デフォルトは 1）
  • search（任意の文字列）：検索する惑星名または名前の一部
  • fetchAllPages（任意のブール値）：結果の全ページを自動取得するかどうか（デフォルトは true）
• 戻り値：気候、地形、人口、関連エンティティを含む Star Wars の惑星データのコレクション

4. get_planet_by_id 🌍

• 説明：ID を指定して、特定の Star Wars の惑星の詳細を取得します
• 入力：
  • id（文字列または数値）：惑星の一意の識別子
• 戻り値：気候、地形、人口、関連エンティティを含む、指定した惑星の完全なデータ

5. get_films 🎬

• 説明：ページネーションを自動処理し、検索にも対応して Star Wars の映画を一覧表示します
• 入力：
  • page（任意の数値）：取得するページ番号（デフォルトは 1）
  • search（任意の文字列）：検索する映画のタイトルまたはタイトルの一部
  • fetchAllPages（任意のブール値）：結果の全ページを自動取得するかどうか（デフォルトは true）
• 戻り値：タイトル、エピソード ID、監督、関連エンティティを含む Star Wars 映画データのコレクション

6. get_film_by_id 📽️

• 説明：ID を指定して、特定の Star Wars 映画の詳細を取得します
• 入力：
  • id（文字列または数値）：映画の一意の識別子
• 戻り値：タイトル、エピソード ID、監督、関連エンティティを含む、指定した映画の完全なデータ

7. get_species_list 👽

• 説明：ページネーションを自動処理し、検索にも対応して Star Wars の種族を一覧表示します
• 入力：
  • page（任意の数値）：取得するページ番号（デフォルトは 1）
  • search（任意の文字列）：検索する種族名または名前の一部
  • fetchAllPages（任意のブール値）：結果の全ページを自動取得するかどうか（デフォルトは true）
• 戻り値：分類、身体的特徴、関連エンティティを含む Star Wars の種族データのコレクション

8. get_species_by_id 🧬

• 説明：ID を指定して、特定の Star Wars の種族の詳細を取得します
• 入力：
  • id（文字列または数値）：種族の一意の識別子
• 戻り値：分類、身体的特徴、関連エンティティを含む、指定した種族の完全なデータ

9. get_vehicles 🚗

• 説明：ページネーションを自動処理し、検索にも対応して Star Wars のビークルを一覧表示します
• 入力：
  • page（任意の数値）：取得するページ番号（デフォルトは 1）
  • search（任意の文字列）：検索するビークル名または名前の一部
  • fetchAllPages（任意のブール値）：結果の全ページを自動取得するかどうか（デフォルトは true）
• 戻り値：モデル、メーカー、仕様を含む Star Wars のビークルデータのコレクション

10. get_vehicle_by_id 🚙

• 説明：ID を指定して、特定の Star Wars のビークルの詳細を取得します
• 入力：
  • id（文字列または数値）：ビークルの一意の識別子
• 戻り値：モデル、メーカー、仕様を含む、指定したビークルの完全なデータ

11. get_starships 🚀

• 説明：ページネーションを自動処理し、検索にも対応して Star Wars の宇宙船を一覧表示します
• 入力：
  • page（任意の数値）：取得するページ番号（デフォルトは 1）
  • search（任意の文字列）：検索する宇宙船名または名前の一部
  • fetchAllPages（任意のブール値）：結果の全ページを自動取得するかどうか（デフォルトは true）
• 戻り値：モデル、メーカー、仕様を含む Star Wars の宇宙船データのコレクション

12. get_starship_by_id 🛸

• 説明：ID を指定して、特定のスター・ウォーズの宇宙船の詳細を取得します
• 入力：
  • id（文字列または数値）：宇宙船を一意に識別する ID
• 戻り値：モデル、製造元、仕様など、要求された宇宙船の完全なデータ

13. clear_cache 🧹

• 説明：スター・ウォーズ API のキャッシュを（一部またはすべて）クリアします
• 入力：
  • endpoint（省略可能な文字列）：キャッシュからクリアする特定のエンドポイントです。すべてクリアする場合は空のままにします。
• 戻り値：クリアされたキャッシュを示す確認メッセージ

14. get_cache_stats 📊

• 説明：スター・ウォーズ API のキャッシュ使用状況に関する統計情報を取得します
• 入力：なし
• 戻り値：キャッシュのヒット／ミス統計、サイズ、パフォーマンス指標

🛠️ セットアップ

VS Code に簡単インストール

最も簡単にインストールするには、この README の上部にある VS Code のインストールボタンのいずれかをクリックしてください。

VS Code への手動インストール

コマンドラインを使用する

以下のコマンドを使用して、Star Wars MCP サーバーを手動でインストールできます。

VS Code Stable の場合：

code --add-mcp '{"name":"starwars","command":"npx","args":["-y","@johnpapa/mcp-starwars"],"env":{}}'

VS Code Insiders の場合：

code-insiders --add-mcp '{"name":"starwars","command":"npx","args":["-y","@johnpapa/mcp-starwars"],"env":{}}'

VS Code の設定を使用する

1. VS Code の設定を開きます（ファイル > ユーザー設定 > 設定）
2. 右上隅にある「Open Settings (JSON)」アイコンをクリックします
3. 以下の設定を settings.json ファイルに追加します。

"mcp": {
  "servers": {
    "starwars": {
      "command": "npx",
      "args": ["-y", "@johnpapa/mcp-starwars"],
      "env": {}
    }
  }
},
"chat.mcp.discovery.enabled": true

Smithery からインストールする

Smithery を使用して、Star Wars MCP Server を Claude Desktop に自動インストールするには：

npx -y @smithery/cli install @johnpapa/mcp-starwars --client claude

MCP Inspector を使用して MCP サーバーをローカルで実行する

サーバーをテストするために MCP Inspector をローカルで実行する場合は、以下の手順に従ってください。

1. このリポジトリをクローンします。

   git clone https://github.com/johnpapa/-mcp-starwars
   

2. 必要な依存関係をインストールし、プロジェクトをビルドします。

   npm install
   npm run build
   

3. （省略可能）MCP Inspector を使用してサーバーを試すには、以下のコマンドを実行します。

   # Start the MCP Inspector
   npx @modelcontextprotocol/inspector node build/index.js
   

   コンソールに表示された MCP Inspector の URL をブラウザーで開きます。Arguments を dist/index.js に変更し、Connect を選択します。List Tools を選択すると、利用可能なツールが表示されます。

VS Code Insiders で GitHub Copilot にホストされた MCP サーバーを実行する

注：Claude Desktop ですでに MCP サーバーを有効にしている場合は、VS Code の設定に chat.mcp.discovery.enabled: true を追加すると、既存の MCP サーバーリストが検出されます。

MCP サーバーを特定のリポジトリに関連付ける場合は、次の内容で .vscode/mcp.json ファイルを作成します。

{
  "inputs": [],
  "servers": {
    "mcp-starwars": {
      "command": "npx",
      // "command": "node",
      "args": [
        "-y",
        "@johnpapa/mcp-starwars"
        // "_git/mcp-starwars/dist/index.js"
      ],
      "env": {}
    }
  }
}

MCP サーバーをすべてのリポジトリに関連付ける場合は、以下を VS Code のユーザー設定 JSON に追加します。

"mcp": {
  "servers": {
    "mcp-starwars": {
      "command": "npx",
      // "command": "node",
      "args": [
        "-y",
        "@johnpapa/mcp-starwars"
        // "/Users/papa/_git/mcp-starwars/dist/index.js"
        // "_git/mcp-starwars/dist/index.js"
      ],
      "env": {}
    }
  }
}
"chat.mcp.discovery.enabled": true,

GitHub Copilot でツールを使用する

1. MCP サーバーが検出可能になったら、GitHub Copilot を開き、Chat や Edits ではなく Agent モードを選択します。

2. Copilot チャットのテキストフィールドにある「更新」ボタンを選択して、サーバーリストを更新します。

3. 「🛠️」ボタンを選択すると、このリポジトリのツールを含む、使用可能なすべてのツールが表示されます。

4. 以下のように、ツールのいずれかが自然に呼び出されるような質問をチャットに入力します。

   How do I set my VS Code accent colors?
   

   注：「Sorry, the response was filtered by the Responsible AI Service. Please rephrase your prompt and try again.」と表示された場合は、もう一度実行するか、プロンプトの表現を変えてみてください。