Swagger MCP Server

Swagger MCP サーバー

Swagger/OpenAPI 仕様を取り込み、Model Context Protocol（MCP）を通じて提供するサーバーです。

機能

• Swagger/OpenAPI 仕様を読み込みます
• 複数の認証方式をサポートします：
  • Basic 認証
  • Bearer トークン
  • API キー（ヘッダーまたはクエリ）
  • OAuth2
• API エンドポイントから MCP ツールを自動生成します
• リアルタイム通信のための Server-Sent Events（SSE）をサポートします
• TypeScript をサポートします

セキュリティ

これは個人用サーバーです！！ パブリックインターネットに公開しないでください。 基盤となる API で認証が必要な場合は、MCP サーバーをパブリックインターネットに公開しないでください。

TODO

• シークレット — MCP サーバーが、ユーザーのシークレットを使って API リクエストを認証できるようにする必要があります
• 包括的なテストスイート

前提条件

• Node.js（v18 以降）
• Yarn パッケージマネージャー
• TypeScript

インストール

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

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

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

yarn install

3. サンプルをもとに .env ファイルを作成します：

cp .env.example .env

4. Swagger/OpenAPI 仕様を設定します：

   • プロジェクト内に Swagger ファイルを配置します（例：swagger.json）
   • または、Swagger 仕様の URL を指定します

5. config.json の設定をサーバー設定に合わせて更新します：

{
  "server": {
    "host": "localhost",
    "port": 3000
  },
  "swagger": {
    "url": "url-or-path/to/your/swagger.json",
    "apiBaseUrl": "https://api.example.com",  // Fallback if not specified in Swagger
    "defaultAuth": {  // Fallback if not specified in Swagger
      "type": "apiKey",
      "apiKey": "your-api-key",
      "apiKeyName": "api_key",
      "apiKeyIn": "header"
    }
  }
}

注：サーバーは、設定ファイルより Swagger 仕様の設定を優先します：

• Swagger ファイルに servers 配列が含まれている場合、最初のサーバー URL がベース URL として使用されます
• Swagger ファイルでセキュリティスキームが定義されている場合、認証に使用されます
• Swagger ファイルに設定が指定されていない場合は、設定ファイルの値がフォールバックとして使用されます

使い方

1. 開発サーバーを起動します：

yarn dev

2. 本番環境向けにビルドします：

yarn build

3. 本番サーバーを起動します：

yarn start

API エンドポイント

• GET /health - サーバーの稼働状況を確認します
• GET /sse - Server-Sent Events 接続を確立します
• POST /messages - MCP サーバーにメッセージを送信します

テスト

テストスイートを実行します：

# Run tests once
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage report
yarn test:coverage

認証

このサーバーは、さまざまな認証方式をサポートしています。Swagger ファイルに指定されていない場合のフォールバックとして、config.json ファイルで設定してください。

Basic 認証

{
  "defaultAuth": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

Bearer トークン

{
  "defaultAuth": {
    "type": "bearer",
    "token": "your-bearer-token"
  }
}

API キー

{
  "defaultAuth": {
    "type": "apiKey",
    "apiKey": "your-api-key",
    "apiKeyName": "X-API-Key",
    "apiKeyIn": "header"
  }
}

OAuth2

{
  "defaultAuth": {
    "type": "oauth2",
    "token": "your-oauth-token"
  }
}

開発

1. 開発サーバーを起動します：

yarn dev

ライセンス

このプロジェクトは Apache 2.0 License のもとでライセンスされています。

環境変数

• PORT：サーバーのポート（デフォルト：3000）
• API_USERNAME：API 認証用のユーザー名（フォールバック）
• API_PASSWORD：API 認証用のパスワード（フォールバック）
• API_TOKEN：認証用の API トークン（フォールバック）
• DEFAULT_API_BASE_URL：API エンドポイントのデフォルトのベース URL（フォールバック）
• DEFAULT_SWAGGER_URL：デフォルトの Swagger 仕様 URL