Swagger MCP

🚀 Swagger MCP

Swagger仕様書に接続し、AIがそのサービス用のMCPサーバーを生成するために必要なすべてのモデルを構築するのを支援するMCPサーバーです。

✨ 主な機能

• Swagger仕様書をダウンロードし、ローカルに保存して高速参照を可能にします。
• すべてのエンドポイントとそのHTTPメソッドおよび説明のリストを返します。
• すべてのモデルのリストを返します。
• モデルを返します。
• エンドポイントに接続するためのサービスを返します。
• MCP関数定義を返します。
• 完全なスキーマ情報を含む完全なMCPツール定義を生成します。
• ツールの説明にAI固有の指示を含めます。

📦 インストール

前提条件

• Node.js (v14以上)
• npmまたはyarn

インストール手順

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

git clone https://github.com/readingdancer/swagger-mcp.git
cd swagger-mcp

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

npm install

3. .env.exampleファイルを元に.envファイルを作成します。

cp .env.example .env

4. .envファイルを更新します。

📚 ドキュメント

設定

.envファイルを編集してアプリケーションを設定します。

• PORT: サーバーが実行されるポート (デフォルト: 3000)
• NODE_ENV: 環境 (開発、本番、テスト)
• LOG_LEVEL: ログレベル (info、error、debug)

使用方法

アプリケーションのビルド

アプリケーションをビルドします。

npm run build

これにより、TypeScriptコードがコンパイルされ、MCPサーバーとして使用できる状態になります。

MCPサーバーとして実行

Cursorや他のアプリケーションとの統合のためにMCPサーバーとして実行するには、次のコマンドを実行します。

node build/index.js

MCPインスペクターの使用

デバッグ用にMCPインスペクターを実行するには、次のコマンドを実行します。

npm run inspector

Cursorへの追加

このMCPサーバーをCursorに追加するには、次の手順を実行します。

1. Cursor設定 > 機能 > MCPを開きます。
2. "+ 新しいMCPサーバーを追加"をクリックします。
3. サーバーの名前を入力します (例: "Swagger MCP")。
4. トランスポートタイプとして"stdio"を選択します。
5. サーバーを実行するコマンドを入力します: node path/to/swagger-mcp/build/index.js 必要に応じて、上記のコマンドライン引数を追加します。
6. "追加"をクリックします。

これで、Swagger MCPツールがComposer内のCursorエージェントで使用できるようになります。

利用可能なSwagger MCPツール

MCPサーバーを通じて次のツールが利用可能です。

• getSwaggerDefinition: URLからSwagger定義をダウンロードします。
• listEndpoints: Swagger定義からすべてのエンドポイントをリストします。
• listEndpointModels: 特定のエンドポイントで使用されるすべてのモデルをリストします。
• generateModelCode: モデルのTypeScriptコードを生成します。
• generateEndpointToolCode: MCPツール定義のTypeScriptコードを生成します。

利用可能なSwagger MCPプロンプト

サーバーは、AIアシスタントが一般的なワークフローを実行するのをガイドするMCPプロンプトも提供します。

• add-endpoint: Swagger MCPツールを使用して新しいエンドポイントを追加するためのステップバイステップガイドです。

プロンプトを使用するには、クライアントはプロンプト名と必要に応じて引数を指定してprompts/getリクエストを行うことができます。

{
  "method": "prompts/get",
  "params": {
    "name": "add-endpoint",
    "arguments": {
      "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
      "endpointPath": "/pets/{id}",
      "httpMethod": "GET"
    }
  }
}

このプロンプトは、AIアシスタントが新しいエンドポイントを追加するために必要な正確なプロセスをガイドする一連のメッセージを返します。

新しいプロジェクトのセットアップ

最初にエージェントにSwaggerファイルを取得するように依頼します。SwaggerファイルのURLを指定するか、少なくともそれを見つける方法を指定してください。これにより、ファイルがダウンロードされ、ハッシュ化されたファイル名でローカルに保存されます。このファイル名は、現在のソリューションのルートにある.swagger-mcp設定ファイルに自動的に追加されます。

自動生成される.swagger-mcp設定ファイル

SWAGGER_FILENAME = TheFilenameOfTheLocallyStoredSwaggerFile

このシンプルな設定ファイルは、現在のプロジェクトを特定のSwagger APIに関連付けます。将来的には、より詳細な情報を保存するために使用される可能性があります。

設定が完了すると、MCPはSwagger定義を見つけ、現在のソリューションに関連付けることができるようになります。これにより、作業中のソリューションに関連するプロジェクトとタスクを取得するために必要なAPI呼び出しの数が減少します。

改良されたMCPツールコードジェネレーター

MCPツールコードジェネレーターは、より完全で使いやすいツール定義を提供するように強化されています。

主要な改良点

1. 完全なスキーマ情報: ジェネレーターは、すべてのモデルの完全なスキーマ情報を含め、入力スキーマに直接ネストされたオブジェクトを含めます。
2. より良いパラメータ名: パラメータ名は、より意味的で、ドットなどの問題のある文字を避けるようになりました (例: taskRequest は task.Request の代わりに使用されます)。
3. 意味的なツール名: ツール名は、HTTPメソッドとリソースパスに基づいて、より説明的で一貫した命名規則に従うようになりました。
4. YAML Swaggerファイルのサポート: ジェネレーターは、JSONとYAMLの両方のSwagger定義ファイルをサポートするようになりました。
5. 改良されたドキュメント: 生成されたツール定義には、すべてのパラメータとプロパティの包括的な説明が含まれています。
6. 外部依存関係なし: 生成されたコードは、外部モデルファイルをインポートする必要がなく、より自己完結型で使いやすくなりました。
7. AI固有の指示: ツールの説明には、AIエージェントがツールを効果的に使用する方法を理解するのに役立つ特別な指示が含まれています。

使用例

エンドポイントのMCPツール定義を生成するには、次のコードを使用します。

import generateEndpointToolCode from './services/generateEndpointToolCode.js';

const toolCode = await generateEndpointToolCode({
  path: '/pets',
  method: 'POST',
  swaggerFilePath: './petstore.json',
  singularizeResourceNames: true
});

console.log(toolCode);

これにより、POST /petsエンドポイントの完全なスキーマ情報を含む完全なMCPツール定義が生成されます。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

AIアシスタント用のMCPプロンプト

AIアシスタントがSwagger MCPツールを効果的に使用できるように、一般的なタスクをガイドする一連のプロンプトを作成しました。これらのプロンプトは、新しいエンドポイントの追加や生成されたモデルの使用などのプロセスについてステップバイステップの指示を提供します。

完全なプロンプトのコレクションについては、PROMPTS.mdファイルを参照してください。

例: AIアシスタントにプロジェクトに新しいエンドポイントを追加するように依頼するときは、「新しいエンドポイントの追加」プロンプトを参照して、アシスタントが正しい手順を正しい順序で実行するようにしてください。