Openapi Analyzer MCP

🚀 OpenAPI Analyzer MCP Server

強力なモデルコンテキストプロトコル (MCP) サーバーで、Claude Desktopや他のLLMクライアントを使ってOpenAPI仕様を分析できます。このサーバーは、APIの構造、エンドポイント、スキーマに関する自然言語クエリを可能にし、複数のOpenAPI仕様間の不一致を特定するのに役立ちます。

🚀 クイックスタート

このOpenAPI Analyzer MCP Serverを使用して、OpenAPI仕様の分析を始めましょう。まずはインストールと設定を行い、その後自然言語でクエリを実行できます。

✨ 主な機能

🎯 スマートディスカバリーシステム

• 📡 APIレジストリサポート：apis.jsonレジストリからAPIを自動的に検出します（30以上のAPIをサポート）
• 🔗 URLベースの読み込み：個々のURLから仕様を読み込み、自動的にフォールバックします
• 📁 ローカルファイルサポート：複数のフォーマットをサポートする従来のフォルダベースの仕様読み込み
• 🔄 優先順位システム：ディスカバリーURL → 個々のURL → ローカルフォルダ（インテリジェントなフォールバック）

🔍 高度な分析

• 📊 一括分析：90以上のOpenAPI仕様ファイルを同時に読み込み、分析します
• 🔍 スマート検索：自然言語クエリを使って、すべてのAPIのエンドポイントを検索します
• 📈 包括的な統計：APIエコシステムに関する詳細な統計を生成します
• 🔧 不一致検出：認証スキームや命名規則の不一致を特定します
• 📋 スキーマ比較：異なるAPI間で同じ名前のスキーマを比較します
• ⚡ 高速クエリ：メモリ内インデックスを使用して、瞬時に応答します

🌐 汎用互換性

• 複数フォーマットサポート：JSON、YAML、YML仕様をサポート
• バージョンサポート：OpenAPI 2.0、3.0、3.1仕様をサポート
• リモートとローカル対応：URL、APIレジストリ、ローカルファイルで動作します
• ソース追跡：各API仕様がどこから読み込まれたかを正確に知ることができます

📦 インストール

オプション1: npmからインストール

npm install openapi-analyzer-mcp

オプション2: ソースからビルド

git clone https://github.com/sureshkumars/openapi-analyzer-mcp.git
cd openapi-analyzer-mcp
npm install
npm run build

📚 ドキュメント

⚙️ 設定

🎯 スマートディスカバリーオプション

OpenAPI Analyzerは、インテリジェントな優先順位のフォールバックを持つ3つのディスカバリー方法をサポートしています。

1. 🏆 優先度1: APIレジストリ (OPENAPI_DISCOVERY_URL)
2. 🥈 優先度2: 個々のURL (OPENAPI_SPEC_URLS)
3. 🥉 優先度3: ローカルフォルダ (OPENAPI_SPECS_FOLDER)

Claude Desktopのセットアップ

設定ファイルを見つける:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

設定例

🌟 オプション1: APIレジストリディスカバリー（推奨）

集中管理されたAPIレジストリを持つ企業に最適です。

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.company.com/apis.json"
      }
    }
  }
}

🔗 オプション2: 個々のAPI URL

直接のURLから特定のAPIを読み込みます。

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx", 
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPEC_URLS": "https://api.example.com/v1/openapi.yaml,https://api.example.com/v2/openapi.yaml,https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

📁 オプション3: ローカルフォルダ

ローカルの仕様ファイルに対する従来のアプローチです。

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPECS_FOLDER": "/absolute/path/to/your/openapi-specs"
      }
    }
  }
}

🔄 オプション4: フォールバック付きのマルチソース

最大の柔軟性を持ち、すべての方法を試してインテリジェントにフォールバックします。

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.company.com/apis.json",
        "OPENAPI_SPEC_URLS": "https://legacy-api.com/spec.yaml,https://external-api.com/spec.json",
        "OPENAPI_SPECS_FOLDER": "/path/to/local/specs"
      }
    }
  }
}

🏢 実世界の例

APIレジストリを持つ企業:

{
  "mcpServers": {
    "company-apis": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://api.company.com/registry/apis.json"
      }
    }
  }
}

複数のAPIソース:

{
  "mcpServers": {
    "multi-apis": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_SPEC_URLS": "https://petstore.swagger.io/v2/swagger.json,https://api.example.com/v1/openapi.yaml"
      }
    }
  }
}

🔧 環境変数

⚠️ 重要な注意事項:

• 少なくとも1つの環境変数を設定する必要があります
• システムは優先順位でソースを試し、最初に成功したところで停止します
• OPENAPI_SPECS_FOLDERには常に絶対パスを使用してください
• すべてのソースに対してJSON、YAML、YMLフォーマットをサポートします

🎯 使用方法

設定が完了したら、Claude Desktopで自然言語を使ってOpenAPI仕様と対話できます。

🚀 スマートディスカバリークエリ

APIレジストリディスカバリー

"会社のレジストリからすべてのAPIを読み込み、概要を表示してください"
"設定されたレジストリからAPIを検出し、認証パターンを分析してください"
"私たちのAPIレジストリに利用可能なAPIは何ですか？"
"私の仕様がどこから読み込まれたかを表示してください"

クロスAPI分析

"すべてのOpenAPI仕様を読み込み、包括的な要約を提供してください"
"私が持っているAPIの数とエンドポイントの総数はいくつですか？"
"すべての読み込まれたAPI間で認証スキームを比較してください"
"同じスキーマの異なるバージョンを使用しているAPIはどれですか？"

検索とディスカバリー

"すべてのAPIでユーザー作成用のすべてのPOSTエンドポイントを表示してください"
"すべての読み込まれたAPIで認証に関連するすべてのエンドポイントを見つけてください"
"ページネーションパラメータを持つAPIはどれですか？"
"ファイルアップロードを処理するエンドポイントを検索してください"
"「User」スキーマを使用しているすべてのAPIを見つけてください"

分析と比較

"私のAPI全体で使用されている認証スキームは何ですか？"
"命名規則が不一致なAPIはどれですか？"
"異なるAPI間でUserスキーマを比較してください"
"まだバージョン1.0を使用しているAPIを表示してください"

統計と洞察

"私のAPIエコシステムに関する包括的な統計を生成してください"
"最も一般的に使用されているHTTPメソッドは何ですか？"
"最も一般的なパスパターンは何ですか？"
"私のAPI全体でのバージョン分布を表示してください"

🔧 利用可能なツール

MCPサーバーは、プログラムからアクセスできる以下のツールを提供します。

📁 プロジェクト構造

openapi-analyzer-mcp/
├── src/
│   └── index.ts          # メインサーバーの実装
├── tests/               # 包括的なテストスイート
│   ├── analyzer.test.ts # コア機能のテスト
│   ├── server.test.ts   # MCPサーバーのテスト  
│   ├── validation.test.ts # 環境のテスト
│   ├── setup.ts         # テストの設定
│   └── fixtures/        # テストデータファイル
├── dist/                # コンパイルされたJavaScript
├── coverage/            # テストカバレッジレポート
├── examples/            # 設定例
│   ├── claude_desktop_config.json
│   └── sample-openapi.json
├── vitest.config.ts     # テストの設定
├── package.json
├── tsconfig.json
└── README.md

注: このリポジトリにopenapi-specsフォルダは必要ありません。OPENAPI_SPECS_FOLDERを実際のOpenAPIファイルのある場所に指定してください。

🔍 出力例

🎯 スマートディスカバリー結果

読み込みソース情報

[
  {
    "type": "discovery",
    "url": "https://api.company.com/registry/apis.json",
    "count": 12,
    "metadata": {
      "name": "Company APIs",
      "description": "Collection of company API specifications",
      "total_apis": 12
    }
  }
]

レジストリディスカバリー成功

{
  "totalApis": 12,
  "totalEndpoints": 247,
  "loadedFrom": "API Registry",
  "discoveryUrl": "https://api.company.com/registry/apis.json",
  "apis": [
    {
      "filename": "User Management API",
      "title": "User Management API", 
      "version": "2.1.0",
      "endpointCount": 18,
      "source": "https://docs.company.com/user-api.yaml"
    },
    {
      "filename": "Product Catalog API",
      "title": "Product Catalog API",
      "version": "1.5.0", 
      "endpointCount": 32,
      "source": "https://docs.company.com/product-api.yaml"
    }
  ]
}

📊 API統計

{
  "totalApis": 12,
  "totalEndpoints": 247,
  "methodCounts": {
    "GET": 98,
    "POST": 67,
    "PUT": 45,
    "DELETE": 37
  },
  "versions": {
    "1.0.0": 8,
    "2.0.0": 3,
    "3.1.0": 1
  },
  "commonPaths": {
    "/api/v1/users/{id}": 8,
    "/api/v1/orders": 6,
    "/health": 12
  }
}

検索結果

[
  {
    "filename": "user-api.json",
    "api_title": "User Management API",
    "path": "/api/v1/users",
    "method": "POST",
    "summary": "Create a new user",
    "operationId": "createUser"
  },
  {
    "filename": "admin-api.json", 
    "api_title": "Admin API",
    "path": "/admin/users",
    "method": "POST",
    "summary": "Create user account",
    "operationId": "adminCreateUser"
  }
]

🏗️ 独自のAPIレジストリの作成

独自のapis.jsonレジストリを設定したいですか？以下の方法を参照してください。

標準のAPIs.json形式

https://your-domain.com/apis.jsonにファイルを作成します。

{
  "name": "Your Company APIs",
  "description": "Collection of all our API specifications",
  "url": "https://your-domain.com",
  "apis": [
    {
      "name": "User API",
      "baseURL": "https://api.your-domain.com/users",
      "properties": [
        {
          "type": "Swagger",
          "url": "https://docs.your-domain.com/user-api.yaml"
        }
      ]
    },
    {
      "name": "Orders API", 
      "baseURL": "https://api.your-domain.com/orders",
      "properties": [
        {
          "type": "OpenAPI",
          "url": "https://docs.your-domain.com/orders-api.json"
        }
      ]
    }
  ]
}

カスタムレジストリ形式

または、よりシンプルなカスタム形式を使用することもできます。

{
  "name": "Your Company APIs",
  "description": "Our API registry",
  "apis": [
    {
      "name": "User API",
      "version": "v2",
      "spec_url": "https://docs.your-domain.com/user-api.yaml",
      "docs_url": "https://docs.your-domain.com/user-api",
      "status": "stable",
      "tags": ["auth", "users"]
    }
  ]
}

🚨 トラブルシューティング

Claude Desktopにツールが表示されない場合

1. 環境変数が設定されていることを確認する - 少なくとも1つのソースを構成する必要があります
2. URLがアクセス可能であることを確認する - ディスカバリーURLと仕様URLを手動でテストしてください
3. 設定変更後にClaude Desktopを完全に再起動する
4. リモートAPIレジストリのネットワーク接続を確認する
5. ファイル形式を確認する - JSON、YAML、YMLをサポートしています

一般的なエラーメッセージ

スマートディスカバリーエラー

• "❌ Error: No OpenAPI source configured"：OPENAPI_DISCOVERY_URL、OPENAPI_SPEC_URLS、またはOPENAPI_SPECS_FOLDERの少なくとも1つを設定してください
• "⚠️ Warning: Failed to load from discovery URL"：レジストリURLがアクセス可能で、有効なJSONを返すことを確認してください
• "Invalid registry format: missing apis array"：あなたのAPIs.jsonファイルにはapis配列が必要です
• "No OpenAPI spec URL found"：APIエントリにはspec_urlまたはOpenAPI/Swaggerタイプのpropertiesが必要です

従来のエラー

• "❌ Error: OPENAPI_SPECS_FOLDER does not exist"：指定されたディレクトリが存在しません
• "❌ Error: OPENAPI_SPECS_FOLDER is not a directory"：パスがファイルを指しており、ディレクトリではありません
• "❌ Error: No read permission for OPENAPI_SPECS_FOLDER"：フォルダの権限を確認してください
• "⚠️ Warning: No OpenAPI specification files found"：ディレクトリは存在するが、サポートされているファイルが含まれていません
• "⚠️ Skipping [file]: Invalid format"：ファイルが有効なJSON/YAMLではないか、不正なOpenAPI仕様です

デバッグモード

詳細なログを表示するには、NODE_ENV=developmentを設定します。

{
  "mcpServers": {
    "openapi-analyzer": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "OPENAPI_SPECS_FOLDER": "/path/to/specs",
        "NODE_ENV": "development"
      }
    }
  }
}

🤝 コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。大きな変更の場合は、まず変更したい内容について議論するためのイシューを作成してください。

開発環境のセットアップ

git clone https://github.com/sureshkumars/openapi-analyzer-mcp.git
cd openapi-analyzer-mcp
npm install
npm run build
npm run dev  # 開発モードで起動

テストの実行

このプロジェクトには、すべての機能をカバーする46以上のテストを含む包括的なテストスイートが含まれています。

# すべてのテストを実行
npm test

# ファイル変更時に再実行するウォッチモードでテストを実行
npm run test:watch

# カバレッジレポート付きでテストを実行
npm run test:coverage

テストカバレッジ

テストスイートは、100%のテスト成功率で広範なカバレッジを提供します。

• ✅ 46のテストが合格し、66.79%のステートメントカバレッジと100%の関数カバレッジ
• 単体テスト：OpenAPIAnalyzerクラスのテスト（30のテスト） - すべての読み込み方法と分析機能をカバー
• 統合テスト：MCPサーバー構成のテスト（8のテスト） - すべてのツールとエクスポートを検証
• バリデーションテスト：環境設定とエラーハンドリングのテスト（8のテスト） - すべてのディスカバリー方法をテスト

v1.2.0の新機能:

• ✅ スマートディスカバリーテスト - URL読み込み、APIレジストリ解析、フォールバックメカニズム
• ✅ コンストラクタベースのテスト - 環境変数なしで柔軟なテスト構成
• ✅ リモート仕様のモッキング - HTTPベースの仕様読み込みの完全なカバレッジ
• ✅ 下位互換性 - すべての既存の機能が維持されます

テスト構造

tests/
├── analyzer.test.ts      # コアOpenAPIAnalyzer機能のテスト
├── server.test.ts        # MCPサーバー構成のテスト
├── validation.test.ts    # 環境バリデーションのテスト
├── setup.ts             # テストの設定
└── fixtures/            # サンプルテストデータ
    ├── sample-api.json
    ├── another-api.json
    └── invalid-api.json

テスト対象

• ✅ OpenAPI仕様の読み込み（有効/無効なファイル、JSON解析）
• ✅ 検索機能（パス、メソッド、概要、操作IDでの検索）
• ✅ 統計生成（メソッドカウント、バージョン、共通パス）
• ✅ スキーマ比較（クロスAPIスキーマ分析）
• ✅ 不一致検出（認証スキーム）
• ✅ エラーハンドリング（環境変数の欠落、ファイル権限）
• ✅ エッジケース（空のディレクトリ、不正なJSON）

テスト技術

• Vitest - TypeScriptサポートのある高速なテストフレームワーク
• 包括的なモッキング - ファイルシステム操作とコンソール出力
• 型安全性 - 適切なインターフェースを持つ完全なTypeScript統合

🆕 変更履歴

バージョン1.2.0 - スマートディスカバリーシステム

リリース日: 2025年9月

🎯 主要機能

• 🚀 スマートディスカバリーシステム：優先度ベースのフォールバックを備えた革新的なAPIディスカバリー
• 📡 APIレジストリサポート：apis.json形式とカスタムレジストリの完全サポート
• 🔗 URLベースの読み込み：個々のURLから直接仕様を読み込む
• 🔄 インテリジェントなフォールバック：ディスカバリーURL → 個々のURL → ローカルフォルダの優先順位システム
• 🏷️ ソース追跡：新しいget_load_sourcesツールで仕様がどこから読み込まれたかを表示

✨ 実世界での統合

• 🏢 本番環境対応：さまざまなレジストリからの30以上の本番APIで正常にテストされています
• 📊 一括処理：レジストリから90以上のAPIを数秒で読み込む
• 🌐 汎用フォーマットサポート：任意のソース（リモートまたはローカル）からのJSON、YAML、YML

🧪 強化されたテスト

• ✅ 46のテストが合格し、成功率100%
• 📈 改善されたカバレッジ：66.79%のステートメントカバレッジ、100%の関数カバレッジ
• 🔧 コンストラクタベースのテスト：柔軟なテスト構成
• 🔗 リモート仕様のモッキング：HTTPベースの読み込みテストの完全なカバレッジ

🔧 開発者体験

• ⚡ 破壊的変更なし：完全な下位互換性が維持されています
• 📚 包括的なドキュメント：実世界の例で更新されています
• 🏗️ レジストリセットアップガイド：独自のAPIs.jsonレジストリを作成するための手順
• 🚨 強化されたエラーハンドリング：より良いエラーメッセージとグレースフルなフォールバック

バージョン1.1.0 - YAMLサポートと強化された分析

• @apidevtools/swagger-parserを使用してYAML/YMLフォーマットのサポートを追加
• スキーマ比較と不一致検出を強化
• エラーハンドリングとバリデーションを改善

バージョン1.0.0 - 初期リリース

• コアのOpenAPI分析機能
• ローカルフォルダベースの仕様読み込み
• 6つのコアツールを備えたMCPサーバーの実装

📄 ライセンス

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

🙏 謝辞

• Model Context Protocol SDKを使用して構築されています
• OpenAPI Initiativeによって定義されたOpenAPI仕様をサポートしています
• Claude Desktopや他のMCPクライアントと互換性があります

API開発者やドキュメントチームのために愛情を込めて作られました

このツールが役に立った場合は、GitHubで⭐を付けることを検討してください！