@reapi/mcp-openapi

@reapi/mcp-openapi

LLM を活用した IDE 連携を可能にするため、複数の OpenAPI 仕様を読み込み、提供する Model Context Protocol（MCP）サーバーです。このサーバーは、OpenAPI 仕様と Cursor などの LLM を活用した開発ツールやその他のコードエディターとの橋渡しをします。

特長

• ディレクトリから複数の OpenAPI 仕様を読み込みます
• MCP プロトコルを通じて API の操作とスキーマを公開します
• LLM が IDE 内で API を直接理解し、操作できるようにします
• 完全な API コンテキストを提供するため、参照解除済みのスキーマをサポートします
• 利用可能なすべての API のカタログを管理します

ReAPI が提供

このオープンソースの MCP サーバーは、API の設計とテストをシンプルにする次世代の API プラットフォーム、ReAPI の支援を受けています。このサーバーは開発向けのローカルな OpenAPI 連携を提供し、ReAPI は次の 2 つの強力なモジュールを提供します。

🎨 API CMS

• 直感的なノーコードエディターで API を設計
• OpenAPI 仕様を自動で生成、公開
• チームメンバーとリアルタイムで共同作業
• バージョン管理と変更管理

🧪 API Testing

• 開発者にとって最も使いやすいノーコード API テストソリューション
• 直感的なインターフェースでテストケースを作成、管理
• 強力なアサーションと検証機能
• サーバーレスのクラウドテスト実行ツール
• QA チームにも開発者にも最適
• CI/CD 連携に対応

reapi.com で ReAPI を無料でお試しいただき、API 開発の未来をご体験ください。

Cursor の設定

MCP OpenAPI サーバーを Cursor IDE と連携するには、設定場所を 2 つの選択肢から選べます。

オプション 1：プロジェクト固有の設定（推奨）

プロジェクトディレクトリに .cursor/mcp.json ファイルを作成します。この方法を推奨します。プロジェクトごとに異なる仕様のセットを管理できます。

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "./specs"],
      "env": {}
    }
  }
}

ヒント：./specs のような相対パスを使うと、設定の移植性が高まり、チームメンバーと共有しやすくなります。

注：新機能や改善を頻繁に提供しているため、@latest タグの使用をおすすめします。

重要：プロジェクト固有の設定を使うと、LLM のコンテキスト上限を管理しやすくなります。すべての仕様を単一のフォルダーに配置すると、メタデータの合計が LLM のコンテキストウィンドウを超え、エラーが発生する可能性があります。仕様をプロジェクトごとに整理すると、コンテキストサイズを管理しやすくなります。

オプション 2：グローバル設定

ホームディレクトリに ~/.cursor/mcp.json を作成または編集すると、すべてのプロジェクトでサーバーを利用できるようになります。

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "/path/to/your/specs"],
      "env": {}
    }
  }
}

Cursor の設定で有効にする

設定を追加した後、次の手順に従います。

1. Cursor IDE を開きます
2. Settings > Cursor Settings > MCP に移動します
3. @reapi/mcp-openapi サーバーを有効にします
4. サーバーの横にある更新アイコンをクリックして変更を適用します

注：デフォルトでは、Cursor は MCP ツールを実行するたびに確認を求めます。確認なしで自動実行を許可するには、Cursor の設定で Yolo モード を有効にします。

これでサーバーを使用する準備が整いました。ディレクトリに新しい OpenAPI 仕様を追加した場合は、次の手順でカタログを更新できます。

1. Cursor のチャットパネルを開きます
2. 次のプロンプトのいずれかを入力します。

   "Please refresh the API catalog"
   "Reload the OpenAPI specifications"
   

OpenAPI 仕様の要件

1. OpenAPI 3.x の仕様ファイルを対象ディレクトリに配置します。

   • JSON と YAML の両方の形式に対応しています
   • ファイルの拡張子は .json、.yaml、または .yml にしてください
   • スキャナーがすべての仕様ファイルを自動的に検出して処理します

2. 仕様 ID の設定：

   • デフォルトでは、拡張子を除いたファイル名が仕様 ID として使用されます
   • カスタム ID を指定するには、OpenAPI の info オブジェクトに x-spec-id を追加します。

   openapi: 3.0.0
   info:
     title: My API
     version: 1.0.0
     x-spec-id: my-custom-api-id  # Custom specification ID
   

   重要：複数の仕様ファイルで次の項目がある場合、カスタムの x-spec-id を設定することが重要です。

   • エンドポイントのパスが類似または同一
   • スキーマ名が同じ
   • operation ID が重複

   仕様 ID は、これらの類似したリソースを区別し、名前の競合を防ぐのに役立ちます。例：

   # user-service.yaml
   info:
     x-spec-id: user-service
   paths:
     /users:
       get: ...
   
   # admin-service.yaml
   info:
     x-spec-id: admin-service
   paths:
     /users:
       get: ...
   

   これで、これらのエンドポイントを user-service/users と admin-service/users として個別に参照できます。

仕組み

1. サーバーが指定されたディレクトリをスキャンし、OpenAPI 仕様ファイルを検索します
2. 仕様を処理して参照を解決し、完全なコンテキストを作成します
3. すべての API オペレーションとスキーマのカタログを作成し、維持します
4. この情報を MCP プロトコルを通じて公開します
5. IDE 連携は、この情報を次の用途に利用できます。
   • LLM に API のコンテキストを提供する
   • インテリジェントなコード補完を有効にする
   • API の統合を支援する
   • API を考慮したコードスニペットを生成する

ツール

1. refresh-api-catalog

   • API カタログを更新します
   • 戻り値：カタログの更新が完了したことを示すメッセージ

2. get-api-catalog

   • API カタログを取得します。カタログには、すべての OpenAPI 仕様、そのオペレーション、およびスキーマに関するメタデータが含まれます
   • 戻り値：すべての仕様、オペレーション、スキーマを含む完全な API カタログ

3. search-api-operations

   • 仕様全体からオペレーションを検索します
   • 入力：
     • query （文字列）：検索クエリ
     • specId （任意の文字列）：検索対象とする特定の API 仕様 ID
   • 戻り値：API カタログ内で一致したオペレーション

4. search-api-schemas

   • 仕様全体からスキーマを検索します
   • 入力：
     • query （文字列）：検索クエリ
     • specId （任意の文字列）：検索対象とする特定の API 仕様 ID
   • 戻り値：API カタログ内で一致したスキーマ

5. load-api-operation-by-operationId

   • operationId を指定してオペレーションを読み込みます
   • 入力：
     • specId （文字列）：API 仕様 ID
     • operationId （文字列）：読み込むオペレーション ID
   • 戻り値：オペレーションの完全な詳細

6. load-api-operation-by-path-and-method

   • パスとメソッドを指定してオペレーションを読み込みます
   • 入力：
     • specId （文字列）：API 仕様 ID
     • path （文字列）：API エンドポイントのパス
     • method （文字列）：HTTP メソッド
   • 戻り値：オペレーションの完全な詳細

7. load-api-schema-by-schemaName

   • schemaName を指定してスキーマを読み込みます
   • 入力：
     • specId （文字列）：API 仕様 ID
     • schemaName （文字列）：読み込むスキーマの名前
   • 戻り値：スキーマの完全な詳細

ロードマップ

1. セマンティック検索

   • API オペレーションとスキーマを自然言語で検索できるようにします
   • セマンティックな理解によって検索精度を高めます

2. リモート仕様の同期

   • リモートソースから OpenAPI 仕様を同期できるようにします

3. コードテンプレート

   • MCP プロトコルを通じてコードテンプレートを公開します
   • LLM によるコード生成のための参照パターンを提供します

4. コミュニティからの貢献

   • 機能リクエストやバグ報告を送信します
   • サーバーの改善に貢献します

Cursor のプロンプト例

Cursor IDE で API を操作する際に使えるプロンプトの例を紹介します。

1. 利用可能な API の調査

   "Show me all available APIs in the catalog with their operations"
   "List all API specifications and their endpoints"
   

2. API 操作の詳細

   "Show me the details of the create pet API endpoint"
   "What are the required parameters for creating a new pet?"
   "Explain the response schema for the pet creation endpoint"
   

3. スキーマとモックデータ

   "Generate mock data for the Pet schema"
   "Create a valid request payload for the create pet endpoint"
   "Show me examples of valid pet objects based on the schema"
   

4. コード生成

   "Generate an Axios client for the create pet API"
   "Create a TypeScript interface for the Pet schema"
   "Write a React hook that calls the create pet endpoint"
   

5. API 統合の支援

   "Help me implement error handling for the pet API endpoints"
   "Generate unit tests for the pet API client"
   "Create a service class that encapsulates all pet-related API calls"
   

6. ドキュメントと使い方

   "Show me example usage of the pet API with curl"
   "Generate JSDoc comments for the pet API client methods"
   "Create a README section explaining the pet API integration"
   

7. 検証と型

   "Generate Zod validation schema for the Pet model"
   "Create TypeScript types for all pet-related API responses"
   "Help me implement request payload validation for the pet endpoints"
   

8. API の検索と発見

   "Find all endpoints related to pet management"
   "Show me all APIs that accept file uploads"
   "List all endpoints that return paginated responses"
   

これらのプロンプトは、API 開発において MCP サーバーの機能を活用する方法を示しています。必要に応じて自由に調整したり、より複雑なタスクに合わせて組み合わせたりしてください。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。