nasa-images

NASA Images MCP サーバー

MCP サーバーを使用してNASAの画像ライブラリを検索し、インタラクティブなUIに画像を表示するプロジェクトです。

🌟 特徴：

• 2種類のトランスポートに対応：stdioとStreamable HTTPの両方のトランスポートに対応しています
• 画像検索：NASA Images APIを使用してキーワードで検索します
• インタラクティブなUI：MCP Apps Patternを使用した美しい画像ビューアーです
• 画像の表示：検索結果を順番に表示します
• セッション管理：ステートフルなセッション管理を行います

要件

• Node.js 18以降
• npmまたはyarn
• NASA APIキー（nasa.gov/apiで無料取得できます）

インストール

1. リポジトリをクローンします：

cd nasa-images-mcp-server

2. 依存関係をインストールします：

npm install

3. 環境変数を設定します：

cp .env.example .env

.envファイルを編集して、NASA APIキーを設定します：

NASA_API_KEY=your_api_key_here
PORT=3000

4. ビルドします：

npm run build

NASA APIキーの取得

1. https://api.nasa.gov/にアクセスします
2. フォームに名前とメールアドレスを入力します
3. APIキーがすぐにメールで送信されます
4. .envファイルに追加します

レート制限：

• DEMO_KEY：1時間あたり30リクエスト、1日あたり50リクエスト
• 登録済みキー：1時間あたり1000リクエスト

使用方法

stdioモード（Claude DesktopなどのMCPクライアントに推奨）

stdioモードでは、サーバーはstdin/stdoutを介して通信し、HTTPサーバーは起動しません。ログはstderrに書き込まれます。

npxで実行（インストール不要）

npx @kaitoy/nasa-images-mcp-server --stdio

ローカルビルドから実行

stdioトランスポートを使用するには、--stdioフラグを渡します：

node build/index.js --stdio

Claude Desktopの設定

npxを使用する場合（推奨）：

{
  "mcpServers": {
    "nasa-images": {
      "command": "npx",
      "args": ["-y", "@kaitoy/nasa-images-mcp-server", "--stdio"],
      "env": {
        "NASA_API_KEY": "your_api_key_here"
      }
    }
  }
}

ローカルビルドを使用する場合：

{
  "mcpServers": {
    "nasa-images": {
      "command": "node",
      "args": ["/path/to/nasa-images-mcp-server/build/index.js", "--stdio"],
      "env": {
        "NASA_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTPサーバーモード

npm start

サーバーはhttp://localhost:3000で起動します。

別のポートで起動する

PORT=3001 npm start

トランスポートについて

stdioトランスポート

サーバーをサブプロセスとして起動するローカルMCPクライアント（例：Claude Desktop）に適しています。

• stdin/stdoutを介して通信します
• 1プロセスにつき1セッションです
• ネットワーク設定は不要です

Streamable HTTPトランスポート

最新のMCP HTTPトランスポートプロトコルで、リモートまたは複数クライアントの利用に適しています。

主な特徴：

• ✅ ステートフルセッション：クライアントごとに一意のセッションIDを発行します
• ✅ SSE対応：Server-Sent Eventsを介したサーバーからのプッシュ通知に対応しています
• ✅ HTTP上のJSON-RPC：標準的なHTTPリクエスト／レスポンスを介して通信します
• ✅ セッション管理：セッションのライフサイクルを自動で管理します

MCPクライアントとの連携

MCP Inspectorへの接続（HTTPモード）

MCP Inspectorを使用してサーバーをテストできます：

npx @modelcontextprotocol/inspector http://localhost:3000/mcp

MCP Inspectorへの接続（stdioモード）

npx @modelcontextprotocol/inspector node /path/to/nasa-images-mcp-server/build/index.js --stdio

カスタムMCPクライアントでの使用

カスタムクライアントから接続する手順：

1. 初期化リクエスト（POST /mcp）：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      }
    }
  }'

レスポンスヘッダーにmcp-session-idが含まれます。

2. 以降のリクエスト：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <your-session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

3. SSEストリーム（GET /mcp）：

curl -X GET "http://localhost:3000/mcp" \
  -H "mcp-session-id: <your-session-id>" \
  -H "Accept: text/event-stream"

エンドポイント

エンドポイント	メソッド	説明
/	GET	サーバー情報とエンドポイント一覧
/health	GET	ヘルスチェック（アクティブなセッション数を含む）
/mcp	POST	JSON-RPCリクエスト（初期化、ツール呼び出しなど）
/mcp	GET	SSEストリーム（サーバー通知用）
/mcp	DELETE	セッションを終了

利用可能なツール

1. search_nasa_images

NASAの画像ライブラリを検索します。

パラメーター：

• query（string、必須）：検索クエリ（例：「apollo 11」、「mars rover」）

使用例（JSON-RPC）：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_nasa_images",
    "arguments": {
      "query": "apollo 11 moon landing"
    }
  }
}

2. get_next_image

現在の検索結果から次の画像を表示します。

パラメーター： なし

使用例（JSON-RPC）：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_next_image",
    "arguments": {}
  }
}

利用可能なリソース

nasa-image://current

現在表示中の画像のURLを取得します。

MIMEタイプ： text/uri-list

ui://nasa-images/viewer

画像ビューアー用のHTML UIリソースです。

MIMEタイプ： text/html;profile=mcp-app

アーキテクチャ

stdioモード

┌─────────────────────────────────────────────┐
│     MCP Client (Claude Desktop, etc.)       │
│                   ↕ stdin/stdout            │
└───────────────────┼─────────────────────────┘
                    │
┌───────────────────┼─────────────────────────┐
│  NASA Images MCP Server                     │
│  ┌────────────────┴──────────────────────┐  │
│  │  StdioServerTransport                 │  │
│  └───────────────────────────────────────┘  │
│  ┌───────────────────────────────────────┐  │
│  │  McpServer (MCP Apps Pattern)         │  │
│  │  - registerAppTool(search_nasa...)    │  │
│  │  - registerAppTool(get_next_image)    │  │
│  │  - registerAppResource(viewer UI)     │  │
│  │  - registerResource(image URL)        │  │
│  └───────────────────────────────────────┘  │
│  ┌───────────────────────────────────────┐  │
│  │  Session Manager                      │  │
│  │  - Manage search state per user       │  │
│  └───────────────────────────────────────┘  │
│  ┌───────────────────────────────────────┐  │
│  │  NASA API Client                      │  │
│  │  - Image search                       │  │
│  │  - Image URL retrieval                │  │
│  └───────────────────────────────────────┘  │
└───────────────────┼─────────────────────────┘
                    │ HTTPS
┌───────────────────┼─────────────────────────┐
│         NASA Images API                     │
│  https://images-api.nasa.gov/search         │
└─────────────────────────────────────────────┘

HTTPモード

┌─────────────────────────────────────────────┐
│     MCP Client (Inspector, Custom App)      │
│                                             │
│  ┌────────────────────────────────────────┐ │
│  │  HTTP Client                           │ │
│  │  - POST /mcp (JSON-RPC requests)       │ │
│  │  - GET /mcp (SSE stream)               │ │
│  └────────────────────────────────────────┘ │
│                   ↕                         │
└───────────────────┼─────────────────────────┘
                    │ HTTP/SSE
┌───────────────────┼─────────────────────────┐
│  NASA Images MCP Server (Express)           │
│  ┌────────────────┴──────────────────────┐  │
│  │  StreamableHTTPServerTransport        │  │
│  │  - Session management                 │  │
│  │  - JSON-RPC over HTTP                 │  │
│  │  - SSE for notifications              │  │
│  └───────────────────────────────────────┘  │
│  ┌───────────────────────────────────────┐  │
│  │  McpServer (MCP Apps Pattern)         │  │
│  │  - registerAppTool(search_nasa...)    │  │
│  │  - registerAppTool(get_next_image)    │  │
│  │  - registerAppResource(viewer UI)     │  │
│  │  - registerResource(image URL)        │  │
│  └───────────────────────────────────────┘  │
│  ┌───────────────────────────────────────┐  │
│  │  Session Manager                      │  │
│  │  - Manage search state per user       │  │
│  └───────────────────────────────────────┘  │
│  ┌───────────────────────────────────────┐  │
│  │  NASA API Client                      │  │
│  │  - Image search                       │  │
│  │  - Image URL retrieval                │  │
│  └───────────────────────────────────────┘  │
└───────────────────┼─────────────────────────┘
                    │ HTTPS
┌───────────────────┼─────────────────────────┐
│         NASA Images API                     │
│  https://images-api.nasa.gov/search         │
└─────────────────────────────────────────────┘

主なコンポーネント

• src/index.ts：Express サーバーとトランスポート管理
• src/mcp-server.ts：MCP サーバーのロジック（ツールとリソースの登録）
• src/session-manager.ts：セッション管理（検索状態の永続化）
• src/nasa-api.ts：NASA API クライアント
• src/types.ts：TypeScript の型定義

開発

ウォッチモード

npm run watch

ファイルが変更されると自動的に再ビルドします。

開発モード

npm run dev

ビルド後、すぐにサーバーを起動します。

トラブルシューティング

ポートがすでに使用されている

Error: listen EADDRINUSE: address already in use

解決方法：別のポートを指定します：

PORT=3001 npm start

「Cannot find module」エラー

次を実行してください：

npm run build

TypeScript をコンパイルします。

API のレート制限エラー

• DEMO_KEY を使用している場合は、api.nasa.gov で独自の API キーを取得してください
• 1 時間あたり 30 リクエストに制限されています

「Not Acceptable」エラー

クライアントは次の両方の MIME タイプを受け入れる必要があります：

• application/json
• text/event-stream

curl -H "Accept: application/json, text/event-stream" ...

セッションが見つからない

初期化リクエストの後に返される mcp-session-id ヘッダーを保存し、以降のリクエストでは mcp-session-id ヘッダーとして送信してください。

セキュリティに関する注意事項

• このサーバーでは CORS が有効になっています（開発用）
• 本番環境では、適切な CORS 設定とレート制限を実装してください
• NASA API キーは環境変数で管理し、ハードコードしないでください

ライセンス

MIT

参考資料

• Model Context Protocol の仕様
• MCP TypeScript SDK
• MCP Apps 拡張機能
• Streamable HTTP トランスポート
• NASA Images API
• NASA Open APIs

コントリビューション

プルリクエストを歓迎します！バグ報告や機能リクエストは Issue から受け付けています。

サポート

問題が発生した場合は、Issue を作成するか、NASA API のサポートページを参照してください。