OpenAPI MCP Server

OpenAPI MCP サーバー

これは openapi-mcp-server の v2 より前のバージョンをフォークしたものです。今後の利用に備えたバックアップ／フェイルセーフを主な目的としています。

Claude Desktop を通じて、OpenAPI（v3.1）準拠のあらゆる API を操作できます！

このツールは、OpenAPI v3.1 仕様を持つあらゆる API のプロキシとして動作する Model Context Protocol（MCP） サーバーを作成します。これにより、Claude Desktop を使ってローカルおよびリモートサーバーの API を簡単に操作できます。

Claude がクラッシュしたり、仕様が機能しなかったりする場合は、仕様クリーナーアプリに通してください。OpenAPI スキーマを整理し、LLM が読み取りやすくします。

何ができるのですか？

このプロキシは OpenAPI エンドポイントを Claude のツールに自動変換し、Claude が次のことをできるようにします。

1. 利用可能な API エンドポイントを見つけ、その目的を理解する
2. 必須パラメーターとその型を把握する
3. ユーザーに代わって API を呼び出す
4. 応答を適切に処理する

たとえば、次のエンドポイントを持つ Petstore API があるとします。

/pets/{petId}:
  get:
    operationId: getPetById
    summary: Returns a pet by ID
    parameters:
      - name: petId
        in: path
        description: ID of pet to return
        required: true
        schema:
          type: integer

Claude には、これを使用可能なツールとして認識させることができます。

その後、次のような自然な質問を Claude にできます。

• 「ペット ID 123 の詳細を取得してくれますか？」
• 「ID 456 のペットの状態はどうなっていますか？」

Claude は文脈を理解し、適切な API 呼び出しを行います。

ファイルアップロードのサポート

このプロキシは、multipart/form-data を受け付ける API のファイルアップロードに対応しています。エンドポイントがファイルアップロードを受け付ける場合（OpenAPI 仕様で type: string, format: binary と指定されている場合）、ローカルファイルのパスを指定すると、プロキシがファイルの読み込みとアップロードを処理します。

使用例

1. プロフィール画像のアップロード

/users/{userId}/avatar:
  post:
    summary: Upload a user's profile picture
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              avatar:
                type: string
                format: binary
                description: Profile picture (JPEG/PNG)
              cropInfo:
                type: object
                properties:
                  x: { type: number }
                  y: { type: number }
                  width: { type: number }
                  height: { type: number }

Claude には次のように依頼できます。

• 「~/Pictures/profile.jpg にある新しいプロフィール画像をアップロードして」
• 「~/Downloads/photo.png を使ってアバターを更新し、200x200 にトリミングして」

2. ドキュメントの処理

/documents:
  post:
    summary: Upload documents for processing
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              document:
                type: string
                format: binary
                description: PDF or Word document
              language:
                type: string
                enum: [en, es, fr]
                description: Document language
              processOCR:
                type: boolean
                description: Whether to extract text using OCR

自然言語での指示：

• 「~/Documents/contract.pdf にあるドキュメントを、OCR を有効にして英語で処理して」
• 「~/Downloads/report.docx をアップロードして、言語をフランス語に設定して」

3. 複数ファイルの一括アップロード

/batch-upload:
  post:
    summary: Upload multiple files in one request
    requestBody:
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              files:
                type: array
                items:
                  type: string
                  format: binary
              tags:
                type: array
                items:
                  type: string

次のように依頼できます。

• 「/data1.csv、/data2.csv、~/data3.csv の3つのファイルを、タグ 'monthly-report' を付けてアップロードして」
• 「~/exports/ 内のファイルを、タグ 'raw-data'、'june-2023' を付けて処理して」

重要な考慮事項

1. セキュリティ

   • ファイルパスは現在の作業ディレクトリを基準に解決されます
   • 読み取り権限のあるファイルにのみアクセスできます
   • 機密ファイル（~/.ssh/id_rsa など）へのアクセスには、ユーザーの明示的な確認が必要です
   • ファイルの内容は、実際に API リクエストを行うときにのみ読み込まれます

2. パフォーマンス

   • 大きなファイルはディスクから API に直接ストリーミングされます
   • 大容量ファイル向けにメモリ使用量が最適化されています
   • 大容量ファイルのアップロードでは進捗を確認できます

3. 制限事項

   • 最大ファイルサイズは対象の API によって決まります
   • 対応しているのはローカルファイルのみです（リモート URL は対象外です）
   • API によっては、一部のファイル形式が制限される場合があります

はじめに

1. Claude Desktop を設定する： claude_desktop_config.json に次の内容を追加します。

   {
     "mcpServers": {
       "petstore-api": {
         "command": "npx",
         "args": ["openapi-mcp-server", "/abs/path/to/petstore-openapi.json"]
       }
     }
   }
   

2. Claude Desktop を再起動して、API の操作を始めましょう！

例

このリポジトリには、OpenAPI MCP サーバーのテストに利用できる Petstore API サーバーの完全な例が含まれています。このサンプルサーバーは、ペットを管理する基本的な CRUD API を実装しているため、このツールの使い方を学ぶのに最適です。

サンプルサーバーの実行手順については、examples/README.md を参照してください。

CLI ツール

このリポジトリには、OpenAPI エンドポイントをテストするためのコマンドラインツールが含まれています。

# List all available methods
pnpm tsx examples/cli/openapi-client.ts http://localhost:3000/openapi.json list

# Call a specific method
pnpm tsx examples/cli/openapi-client.ts http://localhost:3000/openapi.json call API-getPetById '{"id": 1}'

この CLI ツールでは、OpenAPIToMCPConverter クラスと HttpClient クラスの両方を使って、OpenAPI 準拠サーバーとプログラムからやり取りする方法を紹介しています。

ユースケース

1. ローカル開発

   • 自然な会話で API をテストできます
   • コードを書かずにエンドポイントをデバッグできます
   • API の機能を対話形式で確認できます

2. API 統合

   • サードパーティの API をすばやくテストできます
   • コードを書く前に統合をプロトタイプできます
   • 会話を通じて新しい API を学べます

3. ドキュメント

   • API エンドポイントについて質問できます
   • エンドポイントの使用例を確認できます
   • エラー条件を理解できます

制限事項

• 現在、OpenAPI v3.1 の仕様のみをサポートしています
• レスポンス処理は JSON／テキスト形式のレスポンスに最適化されています
• ファイルのアップロードはローカルファイルのみをサポートしています（リモート URL は不可）
• ストリーミングレスポンスはまだ実装されていません

開発

未完了のタスクは TODO.md に記載されています。

基本事項：

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

# Link the project to your global node_modules so that npx works
npm link

# Now start claude desktop to use

# After making changes run build again before restarting claude desktop
pnpm build

# Now restart claude desktop to run with latest changes

OpenAPIToMCPConverter をプログラムから使用する

OpenAPI の仕様をプログラムから MCP ツールに変換するには、OpenAPIToMCPConverter クラスを使用できます。

import { OpenAPIToMCPConverter } from 'openapi-mcp-server'

// Initialize the converter with your OpenAPI spec
const converter = new OpenAPIToMCPConverter(openApiSpec)

// Convert to OpenAI tools format
const openAiTools = await converter.convertToOpenAITools()

// Convert to Anthropic tools format
const anthropicTools = await converter.convertToAnthropicTools()

// Convert to MCP tools format
const { tools, openApiLookup } = converter.convertToMCPTools()

コンバーターは複数のツール形式をサポートしているため、さまざまな LLM プロバイダーと簡単に統合できます。変換されたツールは、OpenAPI の仕様に含まれるすべての型情報と説明を保持するため、正確なパラメーター検証と役立つドキュメントを提供できます。

プログラムから API を呼び出す

LLM を介さずに API を直接呼び出すには、HttpClient クラスを使用できます。

import { HttpClient, OpenAPIToMCPConverter } from 'openapi-mcp-server'

// Initialize the converter and client
const converter = new OpenAPIToMCPConverter(openApiSpec)
const httpClient = new HttpClient({ baseUrl: 'https://api.example.com' }, openApiSpec)

// Get operation details from the converter
const { openApiLookup } = converter.convertToMCPTools()
const operation = openApiLookup['API-getPetById']

// Make the API call
const response = await httpClient.executeOperation(operation, {
  petId: 123
})

HttpClient は以下を処理します。

• パラメーターの検証
• URL パスパラメーターの置換
• クエリ文字列の整形
• リクエストボディの整形
• ファイルのアップロード（multipart/form-data）
• エラー処理

ライセンス

MIT

---

自然言語を通じて API をより利用しやすくするために、❤️ を込めて作られました。