Openapi Search MCP

🚀 OpenAPI Search MCP Server

このプロジェクトは、Anthropic社のAIコーディングアシスタントであるClaude Codeの支援を受けて構築されました。

---

概要

OpenAPI Search MCP Serverは、AIアシスタントやその他のMCPクライアントがOpenAPI/Swaggerドキュメントに簡単にアクセスできるようにする専用のMCPサーバーです。複数の形式のAPI仕様を読み込み、検索、クエリするための10の強力なツールを提供します。

なぜこれを使うのか？

• AIに友好的なAPIドキュメント：ClaudeのようなAIアシスタントがOpenAPI仕様をクエリできるようにします。
• インテリジェントな検索：パス、メソッド、タグ、キーワードを横断した多条件検索が可能です。
• 高速なルックアップ：O(1)のoperationIdクエリを実現する事前構築されたインデックスがあります。
• 形式の柔軟性：JSONとYAML形式を自動検出します。
• モジュール化されたアーキテクチャ：Pythonのベストプラクティスに従った、クリーンで保守性の高いコードベースです。

---

✨ 主な機能

• 🔄 URLからの読み込み - HTTP/HTTPSエンドポイントからOpenAPIドキュメントを取得します。
• 💾 メモリ内ストレージ - 構造化されたドキュメントストレージによる高速アクセスが可能です。
• 🔍 10のクエリツール - 包括的なAPI探索機能があります。
• 📚 複数形式のサポート - JSONとYAMLを自動検出してサポートします。
• 🚀 バージョンサポート - OpenAPI 3.0.x、3.1.x、およびSwagger 2.0をサポートします。
• 🏗️ レイヤードアーキテクチャ - 依存性注入を用いたモジュール化された設計です。
• ⚡ 高速インデックス作成 - 事前構築されたoperationIdとタグのインデックスがあります。
• 🔐 認証の検出 - セキュリティスキームと要件を抽出します。
• 🏷️ タグベースのナビゲーション - 機能カテゴリ別にAPIを閲覧できます。
• 🎯 正確な検索 - キーワード、メソッド、タグ、またはそれらの組み合わせでフィルタリングできます。

---

🚀 クイックスタート

# 1. conda環境を作成する
conda create -n openapi-search-mcp python=3.12 -y
conda activate openapi-search-mcp

# 2. 依存関係をインストールする
pip install -r requirements.txt

# 3. サーバーを起動する
python main.py

以上で完了です！サーバーが起動し、MCP接続を受け付ける準備ができました。

---

📦 インストール

前提条件

• Python 3.12以上
• Conda（推奨）またはvenv

ステップ1: リポジトリをクローンする

git clone https://github.com/Sheepion/openapi-search-mcp.git
cd openapi-search-mcp

ステップ2: 仮想環境を作成する

Condaを使用する場合（推奨）:

conda create -n openapi-search-mcp python=3.12 -y
conda activate openapi-search-mcp

venvを使用する場合:

python3.12 -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

ステップ3: 依存関係をインストールする

pip install -r requirements.txt

依存関係

• FastMCP (>=0.2.0) - MCPサーバーフレームワーク
• httpx (>=0.27.0) - ドキュメントを取得するための非同期HTTPクライアント
• PyYAML (>=6.0) - YAML解析サポート
• Pydantic (>=2.0.0) - 型安全なデータモデル

---

Dockerデプロイメント

迅速かつ分離されたデプロイメントを行うには、Dockerを使用できます。

前提条件

• Dockerがインストールされていること (Dockerの入手)
• Docker Compose（オプション、Docker Desktopに含まれています）

オプション1: Docker Composeを使用する（推奨）

最も簡単なデプロイ方法です。

# リポジトリをクローンする
git clone https://github.com/Sheepion/openapi-search-mcp.git
cd openapi-search-mcp

# コンテナをビルドして起動する
docker-compose up -d

# ログを表示する
docker-compose logs -f

# コンテナを停止する
docker-compose down

サーバーはhttp://localhost:8848で利用可能になります。

オプション2: 直接Dockerを使用する

手動でビルドして実行します。

# イメージをビルドする
docker build -t openapi-search-mcp:latest .

# コンテナを実行する
docker run -d \
  --name openapi-search-mcp \
  -p 8848:8848 \
  --restart unless-stopped \
  openapi-search-mcp:latest

# ログを表示する
docker logs -f openapi-search-mcp

# 停止して削除する
docker stop openapi-search-mcp
docker rm openapi-search-mcp

Dockerの設定

Dockerのセットアップには以下が含まれます。

• ベースイメージ: python:3.12-slim（軽量）
• ポート: 8848（環境変数で設定可能）
• ヘルスチェック: 自動ヘルスモニタリング
• リソース制限: docker-compose.ymlで設定可能
• ロギング: ローテーション付きのJSONファイルドライバー

環境変数

環境変数を設定することで、デプロイをカスタマイズできます。

environment:
  - DEFAULT_HTTP_PORT=8848  # サーバーポートを変更する
  - PYTHONUNBUFFERED=1      # リアルタイムログを有効にする

Claude Desktopからのアクセス

Dockerを使用する場合、Claude Desktopの設定を更新してHTTPエンドポイントを指定します。

{
  "mcpServers": {
    "openapi-search": {
      "url": "http://localhost:8848"
    }
  }
}

---

設定

Claude Desktopとの統合

このMCPサーバーをClaude Desktopと一緒に使用するには、以下の設定を追加します。

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

オプション1: Condaを使用する場合

{
  "mcpServers": {
    "openapi-search": {
      "command": "conda",
      "args": [
        "run",
        "-n",
        "openapi-search-mcp",
        "python",
        "/absolute/path/to/openapi-search-mcp/main.py"
      ]
    }
  }
}

オプション2: 直接のPythonパスを使用する場合

{
  "mcpServers": {
    "openapi-search": {
      "command": "/path/to/conda/envs/openapi-search-mcp/bin/python",
      "args": [
        "/absolute/path/to/openapi-search-mcp/main.py"
      ]
    }
  }
}

STDIOモードとHTTPモードの切り替え

main.pyの57行目を編集します。

# STDIOモード（Claude Desktop用）
mcp.run()

# カスタムポートでのHTTPモード
mcp.run(transport="streamable-http", port=8848)

---

💻 使用方法

利用可能なツール

サーバーは、包括的なAPI探索のための10のMCPツールを提供します。

1. load_openapi

URLからOpenAPIドキュメントを読み込んで保存します。

パラメーター:

• name (文字列、必須) - API名
• url (文字列、必須) - OpenAPIドキュメントのURL

例:

{
  "name": "petstore",
  "url": "https://petstore.swagger.io/v2/swagger.json"
}

レスポンス:

{
  "status": "success",
  "message": "API 'petstore' が正常に読み込まれました",
  "info": {
    "paths_count": 14,
    "tags_count": 3
  }
}

---

2. list_apis

読み込まれたすべてのAPIの基本情報をリストします。

パラメーター: なし

レスポンス:

{
  "count": 2,
  "apis": [
    {
      "name": "petstore",
      "title": "Swagger Petstore",
      "version": "1.0.0",
      "paths_count": 14
    }
  ]
}

---

3. get_path_details

特定のAPIパスの完全なドキュメントを取得します。

パラメーター:

• name (文字列、必須) - API名
• path (文字列、必須) - APIパス、例: /users/{userId}

例:

{
  "name": "petstore",
  "path": "/pet/{petId}"
}

レスポンス:

{
  "name": "petstore",
  "path": "/pet/{petId}",
  "details": {
    "summary": "IDでペットを検索する",
    "parameters": [...],
    "responses": {...}
  }
}

---

4. get_operation_by_id

特定のoperationIdに関連付けられた操作の詳細を取得します。

パラメーター:

• name (文字列、必須) - API名
• operation_id (文字列、必須) - operationId、例: getUserById

例:

{
  "name": "petstore",
  "operation_id": "getPetById"
}

レスポンス:

{
  "operation_id": "getPetById",
  "path": "/pet/{petId}",
  "method": "get",
  "details": {
    "summary": "IDでペットを検索する",
    "parameters": [...],
    "responses": {...}
  }
}

---

5. search_endpoints

キーワード、メソッド、タグ、またはそれらの組み合わせでエンドポイントを検索します。

パラメーター:

• name (文字列、必須) - API名
• keyword (文字列、オプション) - パス、概要、説明内で検索する
• method (文字列、オプション) - HTTPメソッドフィルター（GET、POSTなど）
• tag (文字列、オプション) - タグフィルター

例:

{
  "name": "petstore",
  "keyword": "pet",
  "method": "GET"
}

レスポンス:

{
  "count": 3,
  "results": [
    {
      "path": "/pet/{petId}",
      "method": "get",
      "operationId": "getPetById",
      "summary": "IDでペットを検索する"
    }
  ]
}

---

6. list_tags

API内のすべてのタグをリストします。

パラメーター:

• name (文字列、必須) - API名

レスポンス:

{
  "count": 3,
  "tags": [
    {
      "name": "pet",
      "description": "ペットに関するすべての情報"
    }
  ]
}

---

7. get_endpoints_by_tag

特定のタグを持つすべてのエンドポイントの概要を取得します。

パラメーター:

• name (文字列、必須) - API名
• tag (文字列、必須) - タグ名

例:

{
  "name": "petstore",
  "tag": "pet"
}

レスポンス:

{
  "tag": "pet",
  "count": 8,
  "endpoints": [
    {
      "path": "/pet",
      "method": "post",
      "operationId": "addPet",
      "summary": "新しいペットを追加する"
    }
  ]
}

---

8. get_schema_details

components/schemasからデータモデル定義を取得します。

パラメーター:

• name (文字列、必須) - API名
• schema_name (文字列、必須) - スキーマ名、例: User, Pet

例:

{
  "name": "petstore",
  "schema_name": "Pet"
}

レスポンス:

{
  "schema_name": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["name"]
}

---

9. get_auth_info

認証設定を取得します。

パラメーター:

• name (文字列、必須) - API名

レスポンス:

{
  "security_schemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "global_security": [
    {"bearerAuth": []}
  ]
}

---

典型的なワークフロー

ワークフロー1: 新しいAPIの探索

# ステップ1: APIを読み込む
load_openapi(name="petstore", url="https://petstore.swagger.io/v2/swagger.json")

# ステップ2: 存在するタグ/カテゴリを確認する
list_tags(name="petstore")

# ステップ3: カテゴリ内のエンドポイントを探索する
get_endpoints_by_tag(name="petstore", tag="pet")

# ステップ4: 特定のエンドポイントの詳細情報を取得する
get_path_details(name="petstore", path="/pet/{petId}")

# ステップ5: データモデルを確認する
get_schema_details(name="petstore", schema_name="Pet")

ワークフロー2: 特定の機能の検索

# ユーザー関連のPOSTエンドポイントを検索する
search_endpoints(name="api", keyword="user", method="POST")

# operationIdでのクイックルックアップ
get_operation_by_id(name="api", operation_id="createUser")

# 完全なパスの詳細を取得する
get_path_details(name="api", path="/users")

ワークフロー3: 認証の理解

# 必要な認証方法を確認する
get_auth_info(name="api")

---

アーキテクチャ

OpenAPI Search MCPは、エンタープライズパターンに触発されたクリーンなレイヤードアーキテクチャに従っています。

┌─────────────────────────────────────┐
│         main.py (Entry)             │  → アプリケーションの初期化
├─────────────────────────────────────┤
│    Tools Layer (src/tools/)         │  → MCPツールの定義
├─────────────────────────────────────┤
│   Services Layer (src/services/)    │  → ビジネスロジック
├─────────────────────────────────────┤
│  Storage Layer (src/storage.py)     │  → データアクセス
├─────────────────────────────────────┤
│ Loaders/Indexers (src/loaders/,     │  → ユーティリティ
│                   src/indexers/)    │
├─────────────────────────────────────┤
│  Models (src/models/)               │  → データ構造
├─────────────────────────────────────┤
│  Config (src/config.py)             │  → 定数
└─────────────────────────────────────┘

主要な設計原則

1. 関心事の分離 - 各レイヤーは単一の責任を持っています。
2. 依存性注入 - サービスはコンストラクタを介して依存関係を受け取ります。
3. 型安全性 - 全体でPydanticモデルを使用しています。
4. インターフェース指向 - レイヤー間に明確な契約があります。
5. テスト可能性 - 各レイヤーは独立してユニットテストできます。

レイヤーの説明

• Config Layer - 集中管理された定数とエラーメッセージ
• Models Layer - 検証付きの型安全なデータ構造
• Storage Layer - 一貫したエラーハンドリングを持つメモリ内ドキュメントストレージ
• Loaders Layer - HTTPフェッチと形式検出（JSON/YAML）
• Indexers Layer - 高速ルックアップのための逆インデックスの構築
• Services Layer - ビジネスロジック（5つのサービス: API、Path、Schema、Search、Tag）
• Tools Layer - MCPツールの登録（3つのモジュール）
• Entry Layer - 依存関係のワイヤリングを伴うアプリケーションの初期化

---

プロジェクト構造

openapi-search-mcp/
├── main.py                          # エントリポイント (~50行)
├── requirements.txt                 # Pythonの依存関係
├── README.md                        # このファイル
├── README.zh.md                     # 中国語のドキュメント
├── CLAUDE.md                        # Claude Codeのガイダンス
├── DESIGN.md                        # 詳細な設計ドキュメント
├── src/                             # ソースコード
│   ├── config.py                   # 設定定数
│   ├── storage.py                  # データストレージレイヤー
│   ├── models/                     # データモデル
│   │   └── openapi_document.py    # Pydanticモデル
│   ├── loaders/                    # ドキュメントローダー
│   │   └── openapi_loader.py      # URL読み込みと形式検出
│   ├── indexers/                   # インデックスビルダー
│   │   └── operation_indexer.py   # operationIdとタグのインデックス作成
│   ├── services/                   # ビジネスロジック
│   │   ├── api_service.py         # APIの読み込みとリスト表示
│   │   ├── path_service.py        # パスクエリ
│   │   ├── schema_service.py      # スキーマと認証クエリ
│   │   ├── search_service.py      # エンドポイント検索
│   │   └── tag_service.py         # タグクエリ
│   └── tools/                      # MCPツールの定義
│       ├── loading_tools.py       # load_openapi, list_apis
│       ├── query_tools.py         # パス、操作、スキーマクエリ
│       └── search_tools.py        # 検索、タグクエリ
└── tests/                          # テストファイル

---

テクノロジースタック

技術	バージョン	目的
Python	3.12+	ランタイム環境
FastMCP	>=0.2.0	MCPサーバーフレームワーク
httpx	>=0.27.0	ドキュメントを取得するための非同期HTTPクライアント
PyYAML	>=6.0	YAML形式の解析
Pydantic	>=2.0.0	型安全なデータモデルと検証

---

サポートされるOpenAPIバージョン

• ✅ OpenAPI 3.0.x
• ✅ OpenAPI 3.1.x
• ✅ Swagger 2.0

JSONとYAMLの両方の形式が自動検出され、サポートされます。

---

FAQ

ローカルのOpenAPIファイルを読み込むにはどうすればいいですか？

現在はURLからの読み込みのみサポートされています。以下の方法があります。

1. ローカルファイルサーバーを使用する: python -m http.server 8000
2. 以下のURLでアクセスする: http://localhost:8000/openapi.json

将来のバージョンでは、直接のファイルパスの読み込みをサポートする予定です。

サーバーを再起動したときにドキュメントは保持されますか？

いいえ、ドキュメントはメモリ内にのみ保存されます。サーバーを再起動した後は、OpenAPIドキュメントを再読み込みする必要があります。この設計は、永続性よりもシンプルさと速度を優先しています。

STDIOモードとHTTPモードを切り替えるにはどうすればいいですか？

main.pyの57行目を編集します。

# STDIOモード（Claude Desktop用）
mcp.run()

# HTTPモード（スタンドアロンサーバー）
mcp.run(transport="streamable-http", port=8848)

同じAPIの複数のバージョンを読み込むことはできますか？

はい、異なる名前を使用すれば可能です。

load_openapi(name="petstore-v1", url="...")
load_openapi(name="petstore-v2", url="...")

既存の名前でAPIを読み込んだ場合、何が起こりますか？

新しいドキュメントが既存のものを上書きします。サーバーは警告メッセージをログに記録します。

---

開発

テストの実行

pytest tests/

コード構造

詳細なアーキテクチャドキュメントと開発ガイドラインについては、CLAUDE.mdを参照してください。

コントリビューション

コントリビューションは歓迎されます！以下の手順を踏んでください。

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 変更を加える
4. テストを追加する
5. プルリクエストを送信する

---

📄 ライセンス

MITライセンス - 詳細についてはLICENSEを参照してください。

---

謝辞

このプロジェクトは、Anthropic社のAIコーディングアシスタントであるClaude Codeの支援を受けて開発されました。 Claude Codeは以下の点で役立ちました。

• アーキテクチャの設計とモノリシックからレイヤード構造へのリファクタリング
• 依存性注入を用いたサービスレイヤーの実装
• ドキュメントとコードの整理
• Pythonエンタープライズ開発のベストプラクティス

このプロジェクトは、ソフトウェア開発における人間とAIの協力の力を示しています。

---

リンク

• FastMCPドキュメント
• OpenAPI仕様
• モデルコンテキストプロトコル

---

Claude Codeで構築 • OpenAPI Search MCP Server • MITライセンス