🚀 OpenAPI to MCP Server Code Generator

🚀 OpenAPI から MCP サーバーへのコード生成ツール

概要

このツールは、OpenAPI 仕様から Model Context Protocol（MCP）サーバーを生成し、AI アシスタントが API とやり取りするために利用できる Python パッケージを作成します。中核となるアーキテクチャでは、OpenAPI 仕様をツール、モデル、クライアントコードを備えた構造化された MCP サーバーに変換します。

クイックスタート

• uv をインストールします
• サーバーを生成します（必要に応じてエージェント／評価機能も生成します）：

  uvx --from git+https://github.com/cnoe-io/openapi-mcp-codegen.git openapi_mcp_codegen \
    --spec-file examples/petstore/openapi_petstore.json \
    --output-dir examples/petstore \
    --generate-agent \
    --generate-eval
  

✨ 機能

• ⚡ OpenAPI 仕様から MCP サーバーを自動生成
• 📝 JSON および YAML 形式に対応
• 🛠️ 各 API エンドポイント用のツールモジュール
• 🤖 API クライアントコードの生成
• 📋 ロギングとエラー処理のセットアップ
• ⚙️ 設定ファイル（pyproject.toml、.env.example）
• 📚 包括的なドキュメントの生成
• 🚀 --generate-agent フラグ — 生成された MCP サーバーとともに、LangGraph React エージェント（A2A サーバー、Makefile、README、.env.example を含む）を追加生成
• 📊 --generate-eval：対話型評価モードと自動評価スイートを追加
• 🧠 --generate-system-prompt：設定済みの LLM を使用して、エージェント用の SYSTEM プロンプトを生成
• 🔌 オプションで SLIM トランスポートに対応しています（実験的な機能のセクションを参照）

仕組み

• OpenAPI 仕様（JSON または YAML）を指定します。
• ジェネレーターがパス、オペレーション、スキーマを解析し、Jinja2 テンプレートをレンダリングして、構造化された Python MCP サーバーを生成します。
• オプションで、生成された MCP ツールを呼び出せる LangGraph エージェントと A2A サーバーラッパーも生成できます。
• LangFuse を使用したトレーシングと評価にも対応しています。

開発

ローカル開発コマンド

# Setup venv
uv venv && source .venv/bin/activate

# Initial setup (requires uv CLI)
uv sync

CLI オプション

• --generate-agent
  • 生成された MCP サーバーをラップする LangGraph React エージェントを生成します
  • A2A サーバー、Makefile、README、.env.example が含まれます
• --generate-eval
  • 以下を追加します：
    • eval_mode.py（トレースを eval/dataset.yaml に保存する対話型データセットビルダー）
    • eval/evaluate_agent.py（正確性、ハルシネーション、軌跡の精度を評価する LangFuse 対応の評価機能）
• --generate-system-prompt
  • 設定済みの LLM を使用して、生成されたツールに合わせた SYSTEM プロンプトを作成します
• --enhance-docstring-with-llm
  • オプションで、LLM を使用してツールの docstring を書き換えます
• --enable-slim
  • 生成された A2A Starlette アプリケーションを AgntcyFactory 経由で SLIM に接続し、サービスを起動する docker-compose ファイルを生成します

生成されるアーキテクチャ

🏗️ アーキテクチャ

flowchart TD
  subgraph Client Layer
    A[User Client A2A]
  end
  subgraph Agent Transport Layer
    B[Google A2A]
  end
  subgraph Agent Framework Layer
    C[LangGraph ReAct Agent]
  end
  subgraph Tools/MCP Layer
    D[Petstore MCP Server]
    E[Petstore API Server]
  end
  A --> B
  B --> C
  C -.-> D
  D -.-> C
  D -.-> E
  E -.-> D

生成されるアーキテクチャには、STDIO モードの MCP サーバーと、組み込みユーティリティツールの get_current_time および iso8601_to_unix が含まれます。

例：Petstore A2A LangGraph エージェント＋MCP サーバー

1. エージェントと評価を生成します

uvx --from git+https://github.com/cnoe-io/openapi-mcp-codegen.git openapi_mcp_codegen \
  --spec-file examples/petstore/openapi_petstore.json \
  --output-dir examples/petstore \
  --generate-agent \
  --generate-eval

2. エージェントと LLM を設定します（LLM プロバイダーのドキュメントと、Langfuse のdocker-compose を使ったデプロイ、API キーの作成に関するドキュメントを参照してください）。

cat > .env << 'EOF'
# Petstore API
PETSTORE_API_URL=http://0.0.0.0:10000
PETSTORE_TOKEN=foo

# LLM provider (configure per your provider)
LLM_PROVIDER=openai
OPENAI_API_KEY=<your-openai-api-key>
OPENAI_ENDPOINT=https://api.openai.com/v1
OPENAI_MODEL_NAME=gpt-5

# Langfuse (optional)
LANGFUSE_HOST=http://localhost:3000
LANGFUSE_PUBLIC_KEY=<your-langfuse-public-key>
LANGFUSE_SECRET_KEY=<your-langfuse-secret-key>
EOF

また、変数をシェルにエクスポートします：

# Exports each line of the .env ignoring lines starting with #
export $(grep -v '^#' .env | xargs)

3. エージェントのディレクトリに移動し、モックサーバーを実行します：

cd examples/petstore
uv run python petstore_mock_server.py

4. Git リポジトリのルートから、新しいターミナルを開いて実行します：

cd examples/petstore
make run-a2a

5. Git リポジトリのルートから、新しいターミナルを開いて実行します（先にDocker をインストールしてください）：

cd examples/petstore
make run-a2a-client

これでエージェントとクライアントがデプロイされました。たとえば、List my available pets と尋ねてみてください。有効になっている場合は、LangFuse（http://localhost:3000）でトレースを確認できます。エージェントを評価するには、次の手順に進みます：

6. 新しいターミナルで、評価モードでエージェントを起動します。ツールの一覧が出力され、それぞれを評価して eval/dataset.yaml にデータセットを作成するよう求められます。

make run-a2a-eval-mode

7. データセットの作成が完了したら、評価を開始します：

make eval

これにより、LangFuse に新しいデータセットが作成され、評価が実行されます。

拡張機能：SLIM

このセクションでは、host.docker.internal にアクセスできる必要があります。問題が発生した場合は、この GitHub の issueを参照してください。

8. --enable-slim を指定して生成した場合は、SLIM 上で A2A サーバーを実行し、docker-compose でローカルの SLIM データプレーンを自動起動することもできます：

export PETSTORE_API_URL=http://host.docker.internal:10000  # Needed so that the MCP server can talk to the mock API server running on the host
make run-a2a-and-slim

この docker-compose では：

• 2 つのコンテナを実行します。一方は HTTP 経由の A2A、もう一方は SLIM にブリッジされた A2A です。
• slim-config.yaml で定義された slim-dataplane サービスを起動します。
• 両方のコンテナに Langfuse を接続します（host.docker.internal にアクセスできることが前提です。別の方法として、生成された docker-compose ファイルに langfuse コンポーネントを追加し、LANGFUSE_HOST 環境変数を http://langfuse-web:3000 に更新します）。

9. 新しいターミナルでクライアントから SLIM ブリッジ経由のエージェントに接続するには、次を実行します：

make run-slim-client

A2A インスペクターツール

A2A インスペクターは、A2A サーバーの検査とデバッグに使うユーティリティです。エージェントカードを調べたり、エージェントを呼び出したりするためのビジュアルインターフェースを提供します。プロジェクトページの手順に従ってインスペクターをビルドして実行してください。localhost:8080 で利用できます。その後、localhost:8000/.well-known/agent.json で実行中のエージェントに接続できます。

プロジェクト固有の規約

設定ファイル

• 各サンプルには、認可ヘッダーなどのメタデータを含む config.yaml が必要です。
• 生成される pyproject.toml には、エージェント固有の依存関係が含まれます。
• .env.example テンプレートには、エージェント固有の環境変数が含まれます。

コード生成のパターン

• Operation ID は Python の関数名になります（snake_case に変換）。
• OpenAPI のパラメーターは、型ヒント付きの関数引数にマッピングされます。
• 生成されるツールは、次のパターンに従います：async def operation_id(params) -> Any
• API クライアントは、設定可能なベース URL とヘッダーを使用する httpx で構成されます。

統合ポイント

外部依存関係

• MCP プロトコル：FastMCP サーバーの実装に mcp>=1.9.0 を使用します。
• uv パッケージマネージャー：依存関係の管理と実行に必要です。
• Jinja2：コード生成用のテンプレートエンジンです。
• Ruff：コードのフォーマットとリンティングを行います（生成コードに自動適用）。

理解するための主要ファイル

• openapi_mcp_codegen/mcp_codegen.py：中核となる生成ロジックとテンプレートのレンダリング
• openapi_mcp_codegen/templates/：テンプレート構造は出力構造を反映しています。
• examples/petstore/：OpenAPI 仕様と設定を含む、完全に動作するサンプル
• tests/test_mcp_codegen.py：期待される生成フローを示す統合テスト

実験的

SLIM のサポート

--enable-slim を使用して、SLIM トランスポート経由で A2A サーバーを実行できるエージェントをビルドします。

• --enable-slim を指定して生成すると、docker-compose で slim-dataplane サービスも起動し、エージェントを SLIM 経由で接続します。
• エージェントの A2A サーバーは、AgntcyFactory を介して SLIM 上で実行されます。
• make run-a2a-and-slim を使用すると、HTTP A2A と slim-dataplane を含む SLIM ブリッジスタックの両方を起動できます。
• クライアントから SLIM ブリッジ経由のエージェントに接続するには、次の手順に従います。

  make run-slim-client
  

• 参考資料：
  • SLIM Core：https://docs.agntcy.org/messaging/slim-core/

A2A プロキシ

--with-a2a-proxy フラグ

• 外部の a2a-proxy の背後に配置することを想定した、最小限の WebSocket アップストリームサーバーを生成します。
• 外部の a2a-proxy を別途デプロイし、WS アップストリーム（ws://host:port）に接続するよう設定します。プロキシは、クライアント向けに A2A HTTP API（例：/a2a/v1）を公開します。
• --generate-agent と組み合わせると、WS アップストリームをローカルで起動する Makefile ターゲット（例：make run-with-proxy）が用意される場合があります。
• この方式は実験段階であり、変更される可能性があります。評価とプロトタイピングにのみ使用してください。

よくあるデバッグパターン

• 生成されたコードには、Python の logging モジュールを使った詳細なログが含まれます。
• render_template() の Jinja2 コンテキストからテンプレート変数にアクセスできます。
• --dry-run フラグを使用すると、ファイルを書き込まずに生成結果をプレビューできます。

---

🎯 OpenAPI Overlay によるドキュメントの強化

概要

このツールは、OpenAPI Overlay Specification 1.0.0 を使用した LLM によるドキュメント強化 に対応しました。エージェントが理解しやすいよう、最適化された docstring を備えた AI フレンドリーな MCP サーバーを生成できます。

クイックスタート：強化された生成

# One-command enhanced MCP server generation
python -m openapi_mcp_codegen.enhance_and_generate \
    examples/argo-workflows/openapi_argo_workflows.json \
    examples/argo-workflows/mcp_server \
    examples/argo-workflows/config.yaml \
    --save-overlay overlay.yaml \
    --save-enhanced-spec enhanced_openapi.json

このコマンドでは、次の処理が行われます。

1. AI フレンドリーな説明を含むオーバーレイを生成します（利用可能な場合は LLM を使用）。
2. オーバーレイを適用して、強化された OpenAPI 仕様を作成します。
3. 最適化された docstring を含む MCP サーバーを生成します。

強化パイプライン

flowchart LR
    A[OpenAPI Spec] -->|1. Analyze| B[Overlay Generator]
    B -->|2. LLM Enhance| C[overlay.yaml]
    A -->|3. Apply| D[Overlay Applier]
    C --> D
    D -->|4. Enhanced| E[enhanced_openapi.json]
    E -->|5. Generate| F[MCP Server]
    style B fill:#e1f5ff
    style C fill:#fff4e6
    style E fill:#e8f5e9
    style F fill:#f3e5f5

主な機能

1. LLM による説明の強化

• OpenAI 互換 の形式（250 文字未満）
• プレーンテキスト — Markdown や特殊な書式は使用しません
• ユースケースのコンテキスト —「使用する場面：<シナリオ>」
• アクション指向 — 明確な動詞で始めます

2. スマートなパラメーター処理

• 複雑なスキーマを 自動検出
• ネストされたパラメーターが 10 個を超えるスキーマ向けの 辞書モード
• すっきりした関数シグネチャ — 1000 個を超えるパラメーターを持つ関数は不要になります
• 結果：複雑な操作ではコードサイズを 98% 削減

3. OpenAPI Overlay 標準

• 業界標準 の Overlay Specification 1.0.0
• ツールやプラットフォーム間で 再利用可能
• ドキュメントの強化を バージョン管理
• 元の OpenAPI 仕様を 破壊しません

設定

config.yaml の title フィールドで、パッケージ名を設定できるようになりました。

title: argo_workflows              # → mcp_argo_workflows
description: Argo Workflows MCP Server
author: Your Name
email: [email protected]
version: 0.1.0
license: Apache-2.0

headers:
  Authorization: Bearer {token}
  Accept: application/json

オーバーレイ生成オプション

# Generate overlay only (with LLM)
python -m openapi_mcp_codegen.overlay_generator \
    spec.json overlay.yaml --use-llm

# Apply existing overlay
python -m openapi_mcp_codegen.overlay_applier \
    spec.json overlay.yaml enhanced_spec.json

# Full pipeline
python -m openapi_mcp_codegen.enhance_and_generate \
    spec.json output/ config.yaml \
    --save-overlay overlay.yaml \
    --format yaml

例：強化前と強化後

強化前

GET /api/v1/workflows:
  description: "Get workflows"

LLM による強化後

GET /api/v1/workflows:
  description: "List all workflows in a namespace. Use when: you need to discover running workflows or check workflow status. Required: namespace"

生成された関数

async def workflow_service_list_workflows(
    path_namespace: str,
    param_listOptions_labelSelector: str = None
) -> Any:
    """
    List all workflows in a namespace

    OpenAPI Description:
        List all workflows in a namespace. Use when: you need to
        discover running workflows or check workflow status.

    Args:
        path_namespace (str): Kubernetes namespace to scope the operation
        param_listOptions_labelSelector (str): Filter by labels
    """

パフォーマンスへの影響

指標	変更前	変更後	改善
関数のサイズ（複雑なもの）	5,735 行	82 行	98.6% ↓
パラメーター数	1,000+	7 個のパラメーター	99.3% ↓
説明の長さ	300+ 文字	250 文字未満	OpenAI 準拠 ✅
ツール選択の精度	ベースライン	+35%	エージェントのパフォーマンス向上

ファイル管理

バージョン管理に保存するファイル：

• ✅ openapi.json — 元の OpenAPI 仕様
• ✅ config.yaml — 設定
• 🤔 overlay.yaml — 任意（再生成できますが、レビューや編集に便利です）

自動生成されるため保存しないファイル：

• ❌ enhanced_openapi.json — 元の仕様とオーバーレイから生成
• ❌ mcp_server/ — 生成されたコードの出力先

LLM プロバイダーの設定

# Set LLM API keys
export OPENAI_API_KEY=your-key
export ANTHROPIC_API_KEY=your-key
export LLM_PROVIDER=openai  # or anthropic

# The overlay generator will automatically use LLM if keys are set
# Falls back to rule-based generation if no LLM available

応用：カスタムオーバーレイ

細かな制御を行う場合は、overlay.yaml を手動で編集できます。

overlay: 1.0.0
info:
  title: Custom Enhancements
  version: 1.0.0

actions:
  - target: $.paths['/api/v1/workflows'].get.description
    update: "Your custom description here"

  - target: $.paths['/api/v1/workflows'].get.parameters[0].description
    update: "Custom parameter description"

次に、適用して再生成します。

python -m openapi_mcp_codegen.overlay_applier \
    original_spec.json overlay.yaml enhanced_spec.json

python -m openapi_mcp_codegen \
    --spec-file enhanced_spec.json \
    --output-dir mcp_server

---

📚 追加リソース

• アーキテクチャガイド：アーキテクチャの詳細なドキュメントと、Argo Workflows を使った実装ガイドについては、Architecture.md を参照してください
• オーバーレイ仕様：OpenAPI Overlay Specification 1.0.0
• MCP プロトコル：Model Context Protocol
• 例：動作する完全な例については、examples/ ディレクトリを確認してください