Openapi Navigator

OpenAPI Navigator

OpenAPI 仕様をナビゲートして照会するためのツールを提供する、MCP（Model Context Protocol）サーバーです。このサーバーを使うと、AI エージェントは複雑な JSON/YAML ファイルを手動で解析することなく、OpenAPI 仕様を簡単に探索、検索、理解できます。

機能

• ローカルファイルまたは URL から OpenAPI 仕様を読み込み
• タグで絞り込んでエンドポイントをナビゲート
• パス、概要、オペレーション ID を対象にファジーマッチングでエンドポイントを検索（ページネーション対応）
• スキーマとその定義を探索（ページネーション対応）
• 概要のみの表示 — トークン使用量を減らすために、エンドポイント情報を簡潔に取得
• API インタラクション — エンドポイントのテストに REST API を直接呼び出し
• 複数の仕様に対応 — 複数の OpenAPI 仕様を同時に読み込み、管理
• 高速な検索と参照のためのスマートインデックス
• 参照の保持 — $ref 構造を維持し、解決するタイミングをエージェントが判断可能
• 包括的なデモ環境 — Nanobot と MCP Inspector でインタラクティブにテスト

インストール

OpenAPI Navigator は PyPI で公開されており、uvx（推奨）または pip を使ってインストールできます。

# Using uvx (recommended)
uvx openapi-navigator

# Or install globally with pip
pip install openapi-navigator

使用方法

MCP の設定

MCP クライアントの設定に OpenAPI Navigator を追加します。

Cursor の場合

Cursor の MCP 設定に追加します。

{
  "mcpServers": {
    "openapi-navigator": {
      "command": "uvx",
      "args": ["openapi-navigator"],
      "env": {}
    }
  }
}

Claude Desktop の場合

Claude Desktop の設定ファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "openapi-navigator": {
      "command": "uvx",
      "args": ["openapi-navigator"],
      "env": {}
    }
  }
}

Code の場合

Code の MCP 設定に追加します。

{
  "mcpServers": {
    "openapi-navigator": {
      "command": "uvx",
      "args": ["openapi-navigator"],
      "env": {}
    }
  }
}

利用可能なツール

OpenAPI Navigator では、以下のツールを利用できます。

基本操作

• load_spec - ローカルファイルから OpenAPI 仕様を読み込みます（絶対パスが必要です）
• load_spec_from_url - URL から OpenAPI 仕様を読み込みます
• list_loaded_specs - 現在読み込まれているすべての仕様を一覧表示します
• unload_spec - 仕様をメモリから削除します

エンドポイント操作

• search_endpoints - ページネーションに対応したファジーマッチングでエンドポイントを検索します。すべてのエンドポイントを取得するには、クエリに "" または "a" を指定します
  • パラメーター：spec_id、query、limit（最大 200）、offset（デフォルト 0）
• get_endpoint - パスとメソッドを指定して、特定のエンドポイントの詳細情報を取得します
  • パラメーター：spec_id、path、method、summary_only（ブール値、デフォルト false）

スキーマ操作

• search_schemas - ページネーションに対応したファジーマッチングでスキーマ名を検索します。すべてのスキーマを取得するには、クエリに "" または "a" を指定します
  • パラメーター：spec_id、query、limit（最大 200）、offset（デフォルト 0）
• get_schema - 名前を指定して、特定のスキーマの詳細情報を取得します
• get_spec_metadata - 読み込まれた OpenAPI 仕様の包括的なメタデータを取得します

ヘッダー管理

• set_spec_headers - 認証などのヘッダーを読み込み済みの仕様に設定します。spec_id パラメーターを指定して make_api_request を使うと、ヘッダーが自動的に適用されます。
  • パラメーター：spec_id、headers（オブジェクト、省略可）

API インタラクション

• make_api_request - エンドポイントをテストするために REST API を直接呼び出します
  • パラメーター：url、method（GET/POST/PUT/PATCH/DELETE など）、headers、params、data、timeout、spec_id（省略可）

ツールドキュメント

set_spec_headers

読み込まれた仕様に認証ヘッダーやその他のヘッダーを設定します。spec_id パラメーターを指定して make_api_request を使用すると、ヘッダーが自動的に適用されます。

パラメーター：

• spec_id（string）：読み込まれた仕様の ID
• headers（object、任意）：HTTP ヘッダーの辞書

例：

{
  "spec_id": "my-api",
  "headers": {
    "Authorization": "Bearer secret-token-12345",
    "X-API-Key": "api-key-67890"
  }
}

ユースケース：

// Load your API spec
load_spec_from_url("https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "github-api")

// Mount your auth token once
set_spec_headers("github-api", {"Authorization": "Bearer ghp_your_token"})

// Make requests without repeating auth
make_api_request("https://api.github.com/user", spec_id="github-api")
make_api_request("https://api.github.com/user/repos", spec_id="github-api")

make_api_request

REST API に HTTP リクエストを送信します。

パラメーター：

• url（string）：リクエスト先の完全な URL
• method（string、任意）：HTTP メソッド（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）。デフォルト：「GET」
• headers（object、任意）：HTTP ヘッダーの辞書
• params（object、任意）：URL パラメーターの辞書
• data（string、任意）：文字列形式のリクエスト本文
• timeout（integer、任意）：タイムアウト（秒）。デフォルト：30
• spec_id（string、任意）：この仕様からデフォルトのヘッダーを読み込みます。リクエストのヘッダーが仕様のヘッダーより優先されます。

spec_id を指定した例：

{
  "url": "https://api.example.com/users",
  "spec_id": "my-api",
  "headers": {
    "X-Custom-Header": "custom-value"
  }
}

set_spec_headers("my-api") で設定したヘッダーと X-Custom-Header がマージされます。リクエストのヘッダーが優先されます。

ワークフローの例

1. 仕様を読み込む：

   load_spec("/absolute/path/to/schema.yaml", "my-api")
   

2. ページネーションを使ってすべてのエンドポイントを取得する：

   search_endpoints("my-api", "", 50, 0)  # First 50 endpoints
   search_endpoints("my-api", "", 50, 50) # Next 50 endpoints
   

3. すべてのスキーマを取得する：

   search_schemas("my-api", "")
   

4. 特定のエンドポイントを検索する：

   search_endpoints("my-api", "virtual machine")
   

5. エンドポイントの詳細を取得する（要約表示）：

   get_endpoint("my-api", "/api/virtualization/virtual-machines/", "GET", true)
   

6. エンドポイントの詳細をすべて取得する：

   get_endpoint("my-api", "/api/virtualization/virtual-machines/", "GET", false)
   

7. スキーマの詳細を取得する：

   get_schema("my-api", "VirtualMachine")
   

8. 仕様に認証ヘッダーを設定する：

   set_spec_headers("my-api", {"Authorization": "Bearer secret-token"})
   

9. API エンドポイントをテストする（設定済みヘッダーを使用）：

   make_api_request("https://api.example.com/users", spec_id="my-api")
   

10. 特定のリクエストのヘッダーを上書きする：

    make_api_request("https://api.example.com/admin", spec_id="my-api", headers={"X-Admin-Token": "admin-token"})
    

11. 仕様のメタデータを取得する：

    get_spec_metadata("my-api")
    

デモ環境

OpenAPI Navigator には、インタラクティブなテストと開発のための包括的なデモ環境が用意されています。

Nanobot との連携

Nanobot を使ってインタラクティブなデモを実行します（インストールが必要です）：

# Install nanobot
brew install nanobot-ai/tap/nanobot

# Create .env file with your API key
echo "ANTHROPIC_API_KEY=your-key-here" > .env

# Start the demo
make demo

デモは http://localhost:8080 で利用でき、OpenAPI Navigator の機能をテストするためのウェブインターフェースを提供します。

MCP Inspector との連携

Web UI Inspector

make inspect

インタラクティブなツールテストを行うための MCP Inspector Web UI を http://localhost:6274 で開きます。

CLI Inspector

make inspect-cli

コマンドラインから利用可能なすべてのツールを一覧表示します。

自動 Inspector テスト

make test-inspector

MCP Inspector CLI を使って自動テストを実行し、ツールの機能を検証します。

開発

テスト

OpenAPI Navigator には、ユニットテストと統合テストを含む包括的なテストスイートが用意されています。

テストの実行

すべてのテスト：

uv run pytest

ユニットテストのみ（高速）：

uv run pytest tests/unit/

統合テストのみ：

uv run pytest tests/integration/

カバレッジレポート付き：

uv run pytest --cov=src --cov-report=html

Makefile の使用

よく使うテストターゲットを含む Makefile が用意されています。

# Run all tests
make test

# Run only unit tests (fast feedback)
make test-unit

# Run integration tests
make test-integration

# Run tests with coverage report
make test-cov

# Clean up generated files
make clean

# Format code
make format

# Lint code
make lint

テスト構成

• tests/unit/ - 各コンポーネントのユニットテスト
  • test_spec_manager.py - コアの仕様管理に関するテスト
• tests/integration/ - ワークフロー全体の統合テスト
  • test_integration.py - エンドツーエンドのワークフローテスト
• tests/conftest.py - 共有のテストフィクスチャと設定

テストカバレッジ

テストスイートでは、少なくとも 65% のコードカバレッジを目指しており、以下が含まれます。

• 31 件のユニットテストでコア機能を網羅
• 5 件の統合テストでワークフロー全体を網羅
• 外部依存関係のモックテスト
• エラー処理の検証
• エッジケースの網羅

サーバーの検査

FastMCP CLI を使ってサーバーを検査します。

uvx fastmcp inspect openapi-navigator

利用可能なすべてのツールに関する詳細情報を含む server-info.json ファイルが生成されます。

CI/CD パイプライン

OpenAPI Navigator では、継続的インテグレーションとデプロイに GitHub Actions を使用しています。

ワークフロー

🔄 CI (ci.yml)

• トリガー：プルリクエストと main へのプッシュ
• 実行内容：Python 3.10、3.11、3.12 でテストを実行
• 機能：
  • 全テストスイートの実行
  • コードカバレッジのレポート
  • ruff によるリンティングとフォーマットチェック
  • black によるコードフォーマット

🏗️ Build (build.yml)

• トリガー：main ブランチへのマージ
• 機能：
  • 包括的なテスト
  • パッケージのビルド
  • コード品質チェック
  • アーティファクトのアップロード

🚀 Release (release.yml)

• トリガー：GitHub リリース
• 機能：
  • PyPI への自動公開（信頼されたパブリッシャーの OIDC に対応）
  • GitHub リリースの作成
  • リリース前のテスト

📦 Dependencies (dependencies.yml)

• トリガー：毎週（月曜日）＋手動
• 機能：
  • 依存関係の自動更新
  • プルリクエストの作成
  • テストによる検証

セットアップ要件

オプション 1：信頼されたパブリッシャー（推奨）

1. PyPI アカウント：pypi.org でアカウントを作成します
2. 信頼されたパブリッシャーの設定：PyPI の設定で、GitHub を信頼されたパブリッシャーとして追加します
3. GitHub にプッシュ：ワークフローが自動的に有効になります

オプション 2：API トークン（従来の方法）

1. PyPI アカウント：pypi.org でアカウントを作成します
2. API トークンの生成：PyPI の設定で API トークンを作成します
3. GitHub シークレット：PyPI トークンを PYPI_API_TOKEN として追加します
4. ワークフローの更新：.github/workflows/release.yml の UV_TOKEN 行のコメントを解除します
5. GitHub にプッシュ：ワークフローが自動的に有効になります

リリースプロセス

1. リリースの作成：GitHub で新しいバージョンにタグを付けます
2. 自動テスト：CI が全テストスイートを実行します
3. パッケージのビルド：配布可能なパッケージを作成します
4. PyPI への公開：PyPI に自動的に公開します
5. リリースノート：包括的なリリースノートを生成します

品質ゲート

• ✅ テストカバレッジ：最低 65% が必要です
• ✅ すべてのテストに合格：ユニットテストと統合テスト
• ✅ コード品質：ruff と black によるリンティングとフォーマット
• ✅ 依存関係：最新かつ安全な状態

アーキテクチャ

OpenAPI Navigator は、次の 2 つの主要コンポーネントで構成されています。

1. SpecManager：OpenAPI 仕様の読み込み、検証、インデックス作成を処理します
2. MCP Server：Model Context Protocol を通じてツールを公開します

SpecManager の機能

• 複数フォーマットへの対応：YAML と JSON の両方の OpenAPI 仕様を処理します
• バージョン検出：OpenAPI 3.x と Swagger 2.x を自動的に判別します
• スマートインデックス作成：エンドポイントとスキーマをすばやく検索するためのインデックスを作成します
• あいまい検索：エンドポイントのメタデータを対象としたインテリジェントな検索を提供します
• 参照の処理：自動解決を行わずに $ref 構造を保持します

エラー処理

• 検証警告：検証上の問題を警告しますが、可能な場合は処理を続行します
• グレースフルデグラデーション：中核機能を妨げる仕様のみを拒否します
• わかりやすいエラーメッセージ：問題の内容を明確に伝えます

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

• 絶対パスのみ：セキュリティ上、ローカルファイルの読み込みには絶対パスが必要です
• 自動実行なし：サーバーは仕様の読み取りと解析のみを行い、コードは実行しません
• 入力検証：すべての入力を処理前に検証します

貢献

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

ライセンス

このプロジェクトは MIT License の下でライセンスされています。