スワガーMCP

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

特徴

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

前提条件

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

インストール

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

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

依存関係をインストールします:

npm install

.env.exampleファイルに基づいて.envファイルを作成します。

cp .env.example .env

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

構成

アプリケーションを構成するには、 .envファイルを編集します。

PORT : サーバーが実行されるポート (デフォルト: 3000)
NODE_ENV : 環境（開発、本番、テスト）
LOG_LEVEL : ログレベル（情報、エラー、デバッグ）

使用法

アプリケーションの構築

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

npm run build

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

MCP サーバーとして実行

Cursor や他のアプリケーションとの統合のために MCP サーバーとして実行するには:

node build/index.js

MCPインスペクターの使用

デバッグのために MCP インスペクタを実行するには:

npm run inspector

カーソルに追加

この MCP サーバーをカーソルに追加するには:

カーソル設定 > 機能 > MCP を開く
「+新しいMCPサーバーを追加」をクリックします
サーバーの名前を入力します（例：「Swagger MCP」）
トランスポートタイプとして「stdio」を選択します
サーバーを実行するコマンドを入力します: node path/to/swagger-mcp/build/index.js必要に応じて、上記のようにコマンドライン引数を追加します。
「追加」をクリック

Swagger MCP ツールが Composer の Cursor Agent で使用できるようになります。

利用可能な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 ファイルを見つける方法を伝えてください。これにより、ファイルがダウンロードされ、ハッシュされたファイル名でローカルに保存されます。このファイル名は、現在のソリューションのルートにある.swagger-mcp設定ファイルに自動的に追加されます。

自動生成された .swagger-mcp 構成ファイル

SWAGGER_FILENAME = TheFilenameOfTheLocallyStoredSwaggerFile

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

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

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

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

主な改善点

完全なスキーマ情報: ジェネレーターには、ネストされたオブジェクトを含むすべてのモデルの完全なスキーマ情報が inputSchema に直接含まれるようになりました。
パラメータ名の命名の改善: パラメータ名がより意味的になり、ドットなどの問題のある文字が避けられるようになりました (例: taskRequestではなくtask.Request )。
セマンティックツール名: ツール名はより説明的になり、HTTP メソッドとリソースパスに基づく一貫した命名規則に従うようになりました。
YAML Swagger ファイルのサポート: ジェネレーターは、JSON と YAML Swagger 定義ファイルの両方をサポートするようになりました。
改善されたドキュメント: 生成されたツール定義には、すべてのパラメーターとプロパティの包括的な説明が含まれます。
外部依存関係なし: 生成されたコードは外部モデルファイルをインポートする必要がないため、より自己完結的で使いやすくなります。
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 アシスタントにプロジェクトに新しいエンドポイントを追加するように依頼する場合、「新しいエンドポイントの追加」プロンプトを参照して、アシスタントが正しい順序で正しいプロセスを実行していることを確認できます。

Integrations