MCP OpenAPI Explorer

MCP OpenAPI Explorer

OpenAPI 仕様を分析し、API との連携に関するコンテキストを提供する Model Context Protocol（MCP）サーバーです。

特長

• GitHub、ローカルファイル、HTTP URL など、さまざまなソースから OpenAPI 仕様を読み込みます
• API エンドポイントを解析し、包括的なコンテキストを提供します
• stdin/stdout 経由で Model Context Protocol（MCP）をサポートします
• LLM に API 連携に関するインテリジェントなコンテキストを提供します
• JSON と YAML の両方の OpenAPI 仕様をサポートします
• Cobra CLI を使用しており、コマンドラインから簡単に利用できます
• Zap による構造化ログを使用します

はじめに

前提条件

• Go 1.24.2 以降
• Docker（任意）

インストール

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

git clone https://github.com/krypticlabs/mcp-openapi-explorer.git
cd mcp-openapi-explorer

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

go mod download

3. ビルドします：

go build

設定

MCP OpenAPI Explorer は YAML 設定ファイルを使って設定できます。次のコマンドでデフォルトの設定ファイルを出力できます：

./mcp-openapi-explorer config export config.yaml

その後、必要に応じて設定ファイルを編集し、次のコマンドでサーバーを実行します：

./mcp-openapi-explorer --config config.yaml serve

GitHub トークンの作成

プライベートな GitHub リポジトリにアクセスする場合や、GitHub から OpenAPI 仕様を読み込む際にレート制限を回避する場合は、GitHub トークンが必要です：

1. GitHub Settings に移動します
2. 左側のサイドバーから Developer settings を選択します
3. Personal access tokens → Fine-grained tokens を選択します
4. Generate new token → Generate new token をクリックします
5. トークンにわかりやすい名前と説明を付けます
6. リポジトリアクセス：only select repositories
   • 次に、この PAT にアクセスを許可するリポジトリを選択します
7. 権限：
   • 必要な権限は contents 権限のみで、アクセスは読み取り専用です
8. Generate token をクリックします
9. トークンをコピーします（再表示できないためご注意ください！）

このトークンを設定ファイルに追加するか、環境変数 MCP_OPENAPI_GITHUB_TOKEN で指定します。

MCP クライアントの設定

MCP クライアントの設定に MCP OpenAPI Explorer を追加すると、MCP クライアントと連携できます。これにより、クライアントが MCP サーバーを自動的に起動して通信できるようになります。

バイナリのダウンロード

GitHub Releases ページから、お使いのプラットフォームに適したバイナリをダウンロードします。

MCP クライアントの設定

MCP クライアントの設定ファイル（通常は ~/.mcp/config.json など）に MCP OpenAPI Explorer を追加します：

{
  "mcpServers": {
    "openapi-explorer": {
      "command": "/path/to/mcp-openapi-explorer",
      "args": ["serve", "--config", "~/.mcp-openapi.yaml"]
    }
  }
}

/path/to/mcp-openapi-explorer を、お使いのシステム上の実際のバイナリのパスに置き換えてください。environment セクションは任意で、MCP サーバーの環境変数の設定に使用できます。

MCP の使用方法

MCP サーバーは stdin/stdout 経由で動作します。これは LLM との連携に推奨される方法です。ネットワーク関連の複雑さを避けられ、さまざまな LLM 連携で適切に動作します。

サーバーの起動

./mcp-openapi-explorer serve

オプション：

• -v, --verbose - 詳細な出力を有効にします
• -c, --config string - 設定ファイルのパス

GitHub リポジトリのサポート

トークンを使うと、プライベートなリポジトリも含め、GitHub リポジトリから OpenAPI 仕様を直接読み込めます：

specs:
  - "@github.com/yourOrg/yourRepo/blob/main/pathToSpec.json|yaml"

利用可能な MCP ツール

MCP サーバーは次のツールを公開します：

get_api_info

読み込んだ OpenAPI 仕様から、API エンドポイントに関する包括的な情報を取得します。

パラメーター：

• query（文字列、必須）：API エンドポイントに関する質問（例：「新しいユーザーを作成するにはどうすればよいですか？」「ペット管理で利用できるエンドポイントは何ですか？」）

load_api_spec

URL またはファイルパスから OpenAPI 仕様を読み込みます。

パラメーター：

• url（string、必須）：OpenAPI 仕様の URL またはファイルパス。以下に対応しています：
  • HTTP/HTTPS の URL（例：'https://petstore3.swagger.io/api/v3/openapi.json'）
  • '@' プレフィックス付きの GitHub URL（例：'@github.com/org/repo/blob/main/api.yaml'）
  • ローカルのファイルパス（例：'file:///path/to/spec.json' または '/path/to/spec.json'）
  • JSON と YAML の両方の形式に対応しています

設定ファイルを指定して新しい API 仕様を読み込むと、永続化のため、その仕様の URL が設定ファイルの specs リストに自動的に追加されます。

list_api_specs

読み込み済みの OpenAPI 仕様をすべて一覧表示します。

delete_api_spec

読み込み済みの OpenAPI 仕様を削除します。

パラメーター：

• spec_id（string、必須）：削除する API 仕様の ID です（利用可能な仕様を確認するには list_api_specs を使用してください）

設定ファイルを指定して API 仕様を削除すると、永続化のため、その仕様の URL が設定ファイルの specs リストから自動的に削除されます。

refresh_api_spec

ソースから再ダウンロードして、1 つ以上の OpenAPI 仕様を更新します。

パラメーター：

• spec_id（string、省略可）：更新する API 仕様の ID です。指定しない場合、読み込み済みの仕様がすべて更新されます。

API エンドポイントに関する情報を取得する

echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_api_info","arguments":{"query":"How do I find pets by status?"}}}' | ./mcp-openapi-explorer serve

読み込み済みの OpenAPI 仕様を削除する

echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"delete_api_spec","arguments":{"spec_id":"Swagger Petstore - OpenAPI 3.0"}}}' | ./mcp-openapi-explorer serve

読み込み済みの OpenAPI 仕様をすべて更新する

echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"refresh_api_spec","arguments":{}}}' | ./mcp-openapi-explorer serve

特定の OpenAPI 仕様を更新する

echo '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"refresh_api_spec","arguments":{"spec_id":"Swagger Petstore - OpenAPI 3.0"}}}' | ./mcp-openapi-explorer serve

仕組み

1. ユーザーが OpenAPI 仕様をサーバーに読み込みます（設定ファイルで設定します）
2. サーバーがこれらの仕様を解析して保存します（JSON と YAML の両方の形式に対応しています）
3. ユーザーが API エンドポイントについて質問すると、サーバーは利用可能なすべてのエンドポイントに関する包括的なコンテキストを提供します
4. LLM はこのコンテキストを使用して、ユーザーの質問に正確に回答します

Docker

docker build -t mcp-openapi-explorer .

# Run the server with input from stdin
docker run -i mcp-openapi-explorer serve < your-jsonrpc-request.json

# Run the server with a configuration file
docker run -i -v $(pwd)/config.yaml:/app/config.yaml mcp-openapi-explorer --config /app/config.yaml serve

ライセンス

MIT