MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

MCP サーバー：スケーラブルな OpenAPI エンドポイントの検出と API リクエストツール

TODO

• 事前ダウンロード済みのモデルがない場合でも、Docker イメージは 2GB あります。事前ダウンロード済みのモデルがある場合は 3.76GB です！！ サイズを小さくするのを手伝ってくれる方、ぜひお願いします。

Configuration

環境変数を使ってカスタマイズできます。GLOBAL_TOOL_PROMPT は重要です！

• OPENAPI_JSON_DOCS_URL：OpenAPI 仕様 JSON の URL（デフォルトは https://api.staging.readymojo.com/openapi.json）
• MCP_API_PREFIX：カスタマイズ可能なツールの名前空間（デフォルトは "any_openapi"）：

  # Creates tools: custom_api_request_schema and custom_make_request
  docker run -e MCP_API_PREFIX=finance ...
  

• GLOBAL_TOOL_PROMPT：すべてのツールの説明の先頭に追加する任意のテキストです。Claude がツールを正確に選択するかどうかを左右するため、非常に重要です。

  # Adds "Access to insights apis for ACME Financial Services abc.com . " to the beginning of all tool descriptions
  docker run -e GLOBAL_TOOL_PROMPT="Access to insights apis for ACME Financial Services abc.com ." ...
  

TL'DR

これを作った理由：数百 KB の Swagger OpenAPI ドキュメントを持つ、プライベート API を提供したいと考えました。

• Claude MCP は、このサイズのファイルを処理するとエラーになります
• 結果を YAML に変換してみましたが、十分に小さくならず、多数のエラーが発生しました。失敗です
• API カテゴリを指定してから、MCP クライアント（Claude Desktop）にグループごとに API ドキュメントを取得させてみました。それでも大きすぎました。失敗です。

最終的に、次の解決策にたどり着きました：

• メモリ内のセマンティック検索を使い、自然言語（「商品を一覧表示」など）で関連する API エンドポイントを検索します
• （1 つのエンドポイントを 1 つのチャンクとして保存する設計のため）完全なエンドポイントのドキュメントを、ミリ秒単位で返します（メモリ内で処理するため）

すごい！ Claude が、すべてのパラメーターを含めて、呼び出す API を把握できるようになりました！

ただし、実際に REST リクエストを送るには、このサーバーに別のツールを作成する必要がありました。「fetch」サーバーがまったく動作せず、その原因をデバッグしたくなかったためです。

https://github.com/user-attachments/assets/484790d2-b5a7-475d-a64d-157e839ad9b0

技術的な特長：

query -> [Embedding] -> FAISS TopK -> OpenAPI docs -> MCP Client (Claude Desktop)
MCP Client -> Construct OpenAPI Request -> Execute Request -> Return Response

Features

• 🧠 リモートの OpenAPI JSON ファイルをソースとして使用します。ローカルファイルシステムへのアクセスや、API の変更時の更新は不要です
• 🔍 最適化された MiniLM-L3 モデル（元の 90MB に対して 43MB）を使ったセマンティック検索
• 🚀 非同期処理に対応した FastAPI ベースのサーバー
• 🧠 OpenAPI 仕様をエンドポイント単位でチャンク化（100KB 以上のドキュメントに対応）し、エンドポイントのコンテキストを損ないません
• ⚡ メモリ内の FAISS ベクトル検索により、エンドポイントを即座に検出

Limitations

• linux/arm/v7 はサポートしていません（Transformer ライブラリのビルドに失敗します）
• 🐢 Docker イメージを使用しない場合、モデルの読み込みに約 15 秒かかるコールドスタートのペナルティがあります
• [Obsolete] 現在の Docker イメージではモデルのダウンロードが無効になっています。huggingface に依存しています。Claude Desktop の起動時にモデルのダウンロードに時間がかかります。huggingface がダウンしていると、サーバーは起動しません。
• 最新の Docker イメージには、事前ダウンロード済みのモデルが組み込まれています。問題が発生した場合は、古いイメージに戻す予定です。

Multi-instance config example

以下は、複数の API セットをより柔軟に使用できるように設計した、複数インスタンスの設定例です：

{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    },
    "healthcare_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.healthcare.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=healthcare",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for Healthcare API services efg.com .",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

この例では：

• サーバーは OpenAPI ドキュメントからベース URL を自動的に抽出します：
  • 金融 API の場合は https://api.finance.com
  • ヘルスケア API の場合は https://api.healthcare.com
• API_REQUEST_BASE_URL 環境変数を使って、ベース URL を任意で上書きできます：

{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e",
        "API_REQUEST_BASE_URL=https://api.finance.staging.com",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Claude Desktop Usage Example

Claude Desktop のプロジェクトプロンプト：

You should get the api spec details from tools financial_api_request_schema

You task is use financial_make_request tool to make the requests to get response. You should follow the api spec to add authorization header:
Authorization: Bearer <xxxxxxxxx>

Note: The base URL will be returned in the api_request_schema response, you don't need to specify it manually.

チャットでは、次のようにできます：

Get prices for all stocks

Installation

Installing via Smithery

Smithery を使って、Claude Desktop 用の Scalable OpenAPI Endpoint Discovery and API Request Tool を自動的にインストールするには：

npx -y @smithery/cli install @baryhuang/mcp-server-any-openapi --client claude

Using pip

pip install mcp-server-any-openapi

Available Tools

サーバーは次のツールを提供します（{prefix} は MCP_API_PREFIX によって決まります）：

{prefix}_api_request_schema

意図に合致する API エンドポイントのスキーマを取得します。パス、メソッド、パラメーター、レスポンス形式など、エンドポイントの詳細を返します。

入力スキーマ：

{
    "query": {
        "type": "string",
        "description": "Describe what you want to do with the API (e.g., 'Get user profile information', 'Create a new job posting')"
    }
}

{prefix}_make_request

複雑な API で簡略化した実装では失敗する場合に、信頼性の高い実行に不可欠です。以下を提供します。

入力スキーマ：

{
    "method": {
        "type": "string",
        "description": "HTTP method (GET, POST, PUT, DELETE, PATCH)",
        "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
    },
    "url": {
        "type": "string",
        "description": "Fully qualified API URL (e.g., https://api.example.com/users/123)"
    },
    "headers": {
        "type": "object",
        "description": "Request headers (optional)",
        "additionalProperties": {
            "type": "string"
        }
    },
    "query_params": {
        "type": "object",
        "description": "Query parameters (optional)",
        "additionalProperties": {
            "type": "string"
        }
    },
    "body": {
        "type": "object",
        "description": "Request body for POST, PUT, PATCH (optional)"
    }
}

レスポンス形式：

{
    "status_code": 200,
    "headers": {
        "content-type": "application/json",
        ...
    },
    "body": {
        // Response data
    }
}

Docker のサポート

マルチアーキテクチャビルド

公式イメージは 3 つのプラットフォームをサポートしています。

# Build and push using buildx
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t buryhuang/mcp-server-any-openapi:latest \
  --push .

柔軟なツール名

MCP_API_PREFIX を使ってツール名を設定できます。

# Produces tools with "finance_api" prefix:
docker run -e MCP_API_PREFIX=finance_ ...

サポート対象プラットフォーム

• linux/amd64
• linux/arm64

オプション 1：ビルド済みイメージを使用（Docker Hub）

docker pull buryhuang/mcp-server-any-openapi:latest

オプション 2：ローカル開発ビルド

docker build -t mcp-server-any-openapi .

コンテナの実行

docker run \
  -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \
  -e MCP_API_PREFIX=finance \
  buryhuang/mcp-server-any-openapi:latest

主なコンポーネント

1. EndpointSearcher：以下を処理する中核クラスです。

   • OpenAPI 仕様の解析
   • セマンティック検索インデックスの作成
   • エンドポイントドキュメントの整形
   • 自然言語クエリの処理

2. サーバーの実装：

   • 非同期 FastAPI サーバー
   • MCP プロトコルのサポート
   • ツールの登録と呼び出し処理

ソースからの実行

python -m mcp_server_any_openapi

Claude Desktop との連携

Claude Desktop の設定で MCP サーバーを構成します。

{
  "mcpServers": {
    "any_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. Pull Request を作成します

ライセンス

このプロジェクトは、LICENSE ファイルに記載された条件に基づいてライセンスされています。

実装に関する補足

• エンドポイント中心の処理：大規模な仕様で問題が生じやすいドキュメント単位の分析とは異なり、個々のエンドポイントを以下の方法でインデックス化します。
  • パスとメソッドを一意の識別子として使用
  • パラメーターを考慮した埋め込み
  • レスポンススキーマのコンテキスト
• 仕様の処理を最適化：以下の方法で、最大 10MB（約 5,000 エンドポイント）の OpenAPI 仕様を処理します。
  • スキーマコンポーネントの遅延読み込み
  • パス項目の並列解析
  • 選択的な埋め込み生成（重複する説明を省略）