OpenAPI Mcp Server

OpenAPI MCP サーバー

このアプリケーションは、OpenAPI スキーマに基づいて、あらゆる REST API を MCP（Model Context Protocol）サーバーとして公開します。OpenAPI 3.0+ を幅広くサポートし、OpenAPI のオペレーションから MCP ツールを自動生成します。

機能

• OpenAPI 3.0+ の完全サポート：JSON および YAML 形式のスキーマを解析します
• 高度なスキーマ処理：$ref の完全な解決、合成スキーマ（oneOf、anyOf、allOf）に対応
• 豊富なツール生成：詳細な説明、検証、メタデータを含む MCP ツールを自動生成します
• 複数のコンテンツタイプ：JSON、XML、フォームデータ、マルチパートアップロードに対応
• パラメーター処理：型変換と検証を備えたパス、クエリ、ヘッダーのパラメーターに対応
• 認証：HTTP Basic 認証およびカスタムヘッダーに対応
• 強化されたエラー処理：リクエストのコンテキストを含む詳細なエラーメッセージ
• 型安全性：包括的な検証を備えた TypeScript による完全な実装
• テスト：カバレッジ 90% 以上の広範なテストスイート

インストール

npm install
npm run build

使用方法

npm start -- --schema <path-to-openapi-schema> [options]

オプション

• -s, --schema <path> - OpenAPI スキーマファイル（JSON または YAML）へのパス ［必須］
• -b, --base-url <url> - スキーマのベース URL を上書きします
• -h, --headers <headers> - JSON 文字列で指定する追加ヘッダー
• -u, --username <username> - Basic 認証用のユーザー名
• -p, --password <password> - Basic 認証用のパスワード

例

# Basic usage with a local schema file
npm start -- --schema ./api-schema.yaml

# Override base URL
npm start -- --schema ./api-schema.json --base-url https://api.example.com

# Add authentication headers
npm start -- --schema ./api-schema.yaml --headers '{"Authorization": "Bearer your-token"}'

# Use basic authentication
npm start -- --schema ./api-schema.yaml --username myuser --password mypass

# Combine basic auth with custom base URL
npm start -- --schema ./api-schema.yaml --base-url https://api.example.com --username admin --password secret123

認証

HTTP Basic 認証

コマンドライン引数でユーザー名とパスワードを指定すると、サーバーで HTTP Basic 認証を使用できます。

npm start -- --schema ./api-schema.yaml --username myuser --password mypassword

Basic 認証の資格情報を指定する場合：

• ユーザー名とパスワードの両方を指定する必要があります（片方のみは指定できません）
• 資格情報は Base64 エンコードされ、Authorization: Basic <encoded> ヘッダーで送信されます
• すべての API リクエストに認証ヘッダーが自動的に含まれます

追加ヘッダー

--headers オプションを使用すると、追加ヘッダー（カスタム認証を含む）も指定できます。

npm start -- --schema ./api-schema.yaml --headers '{"Authorization": "Bearer token", "X-API-Key": "key123"}'

注：Basic 認証（--username/--password）と追加ヘッダーは併用できます。両方に Authorization ヘッダーが含まれている場合は、追加ヘッダーが優先されます。

Claude Desktop への追加

この MCP サーバーを Claude Desktop で使用するには、Claude Desktop の設定ファイルに追加する必要があります。

設定ファイルの場所

設定ファイルは次の場所にあります。

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

設定手順

1. サーバーをビルドします（まだの場合）：

   npm install
   npm run build
   

2. 上記の場所にある Claude Desktop の設定ファイルを開くか、新規作成します。

3. MCP サーバーの設定を追加します：

   {
     "mcpServers": {
       "openapi-server": {
         "command": "node",
         "args": [
           "/path/to/your/openapi-mcp-server/dist/index.js",
           "--schema",
           "/path/to/your/openapi-schema.yaml"
         ]
       }
     }
   }
   

4. パスを実際のパスに置き換えます：

   • /path/to/your/openapi-mcp-server/ を、このプロジェクトをクローンまたはダウンロードした場所のフルパスに置き換えます
   • /path/to/your/openapi-schema.yaml を、OpenAPI スキーマファイルのフルパスに置き換えます

設定例

認証方式別の設定例を示します。

Basic 認証

{
  "mcpServers": {
    "secure-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/openapi-mcp-server/api-schema.yaml",
        "--username",
        "apiuser",
        "--password",
        "secret123"
      ]
    }
  }
}

Bearer トークン認証

{
  "mcpServers": {
    "xmpt-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/openapi-mcp-server/schema.yaml",
        "--base-url",
        "https://api.your.service",
        "--headers",
        "{\"Authorization\": \"Bearer your-api-token\"}"
      ]
    }
  }
}

複数 API の設定

{
  "mcpServers": {
    "secure-api": {
      "command": "node",
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/schemas/secure-api.yaml",
        "--username",
        "admin",
        "--password",
        "password123"
      ]
    },
    "public-api": {
      "command": "node", 
      "args": [
        "/Users/username/projects/openapi-mcp-server/dist/index.js",
        "--schema",
        "/Users/username/projects/schemas/public-api.json"
      ]
    }
  }
}

設定オプション

Claude Desktop にサーバーを追加する際は、同じコマンドラインオプションをすべて使用できます。

• --schema <path> - OpenAPI スキーマファイルへのパス（必須）
• --base-url <url> - スキーマのベース URL を上書きします
• --headers <json> - JSON 文字列で認証ヘッダーなどを追加します
• --username <username> - Basic 認証用のユーザー名
• --password <password> - Basic 認証用のパスワード

Claude Desktop の再起動

設定ファイルを変更した後、変更を反映するために Claude Desktop を再起動してください。

検証

設定して再起動すると、Claude との会話で API ツールを使用できるようになります。ツールは OpenAPI スキーマに基づいて自動的に生成され、設定済みの認証情報が含まれます。

仕組み

1. スキーマの読み込み：JSON または YAML ファイルから OpenAPI 3.0 以降のスキーマを読み込み、検証します
2. ツールの生成：各 API 操作に対して MCP ツールを自動的に作成します
3. 認証の設定：認証情報が指定されている場合、HTTP Basic 認証を設定します
4. パラメーターのマッピング：OpenAPI パラメーターを MCP ツールの入力スキーマにマッピングします
5. リクエストの実行：指定されたパラメーターと認証情報を使用して HTTP リクエストを実行します
6. レスポンスの処理：ステータス、ヘッダー、データを含む整形済みレスポンスを返します

サポートされている OpenAPI の機能

• ✅ 完全なパラメーターサポート：パス、クエリ、ヘッダーのパラメーターを検証付きでサポートします
• ✅ すべてのコンテンツタイプ：JSON、XML、フォーム URL エンコード、マルチパート／フォームデータなど
• ✅ 高度なスキーマ機能：$ref の解決、oneOf／anyOf／allOf の合成、ネストされたオブジェクト
• ✅ 型検証：形式（email、uuid など）をサポートする完全な JSON Schema 検証
• ✅ 認証：HTTP Basic 認証とカスタムヘッダーをサポートします
• ✅ 詳細な説明：ツールの説明に要約、タグ、レスポンスコードが含まれます
• ✅ エラー処理：リクエストのコンテキストを含む詳細なエラーメッセージ
• ✅ 型変換：パラメーターの型を自動的に変換します（文字列から数値／ブール値／配列へ）
• ✅ スキーマの正規化：不足している operationId とレスポンスを自動生成します
• ✅ 複数の HTTP メソッド：GET、POST、PUT、PATCH、DELETE、OPTIONS、HEAD

改善点

この拡張版では、基本的な実装に比べて大幅な改善が加えられています。

スキーマ処理

• 完全な $ref の解決：ネストされた参照や循環参照を含む、すべての参照タイプをサポートします
• 合成スキーマ：oneOf、anyOf、allOf を完全にサポートし、説明的なエラーメッセージを提供します
• 検証制約：最小値／最大値、文字列の長さ、パターン、列挙型に対応し、説明を強化しました
• 形式のサポート：組み込みの形式検証（email、uuid、date-time など）

ツールの生成

• 詳細な説明：要約、説明、タグ、レスポンス情報を組み合わせます
• 拡張されたメタデータ：ツール実行時のコンテキストを改善するため、操作のメタデータを保存します
• コンテンツタイプの検出：コンテンツタイプの優先順位をインテリジェントに設定します（JSON > XML > その他）
• パラメーター検証：詳細なエラーメッセージを含む包括的な検証を行います

API クライアント

• 型変換：文字列の入力を適切な型に自動変換します
• コンテンツタイプの処理：コンテンツタイプをスマートに検出し、本文を処理します
• エラーの拡充：リクエスト URL、メソッド、レスポンスデータを含む詳細なエラーメッセージを提供します
• パラメーター処理：高度なパラメーター検証と型の強制変換を行います

テストと品質

• 包括的なテストスイート：統合テストを含み、90% 以上のテストカバレッジを達成しています
• TypeScript：コードベース全体で完全な型安全性を確保しています
• ESLint の設定：コード品質を徹底します
• Jest の設定：カバレッジレポートに対応した最新のテスト環境を構成します

セキュリティに関する考慮事項

• コマンドラインの認証情報：Basic 認証を使用する場合、認証情報はコマンドライン引数として渡されるため、システムのプロセス一覧から見える可能性があります
• Base64 エンコード：HTTP Basic 認証では、標準仕様に従い、暗号化ではなく Base64 エンコードが使用されます
• HTTPS の推奨：認証情報を送信する際は、必ず HTTPS エンドポイントを使用してください
• 環境変数：本番環境で機密性の高い認証情報を扱う場合は、環境変数の使用を検討してください

開発

# Install dependencies
npm install

# Development mode with auto-reload
npm run dev -- --schema ./example-schema.yaml

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint the code
npm run lint

# Fix linting issues
npm run lint:fix

テスト

このプロジェクトには、以下を網羅する包括的なテストが含まれています。

• ユニットテスト：スキーマの読み込み、ツールの生成、API クライアントを対象とした個々のコンポーネントのテスト
• 統合テスト：複雑な OpenAPI スキーマを使用したエンドツーエンドのワークフローテスト
• エッジケース：エラー処理、循環参照、不正なスキーマ
• 型安全性：厳格な型チェックによる TypeScript の完全なカバレッジ

次のコマンドでテストを実行します。

npm test                 # Run all tests
npm run test:watch       # Run tests in watch mode  
npm run test:coverage    # Generate coverage report

アーキテクチャ

強化された実装は、以下の主要コンポーネントで構成されています。

• SchemaLoader：包括的なエラー報告を備えた OpenAPI スキーマの検証と正規化
• ToolGenerator：豊富なメタデータと検証機能を備え、OpenAPI オペレーションを MCP ツールに変換
• APIClient：自動型変換と詳細なエラー処理を備えた HTTP リクエストの実行
• Server：ツールのメタデータ統合機能を備えた MCP サーバーの実装

ライセンス

MIT