openapi-mcp

OpenAPI仕様を入力として、MCPサーバー(stdio)のツール定義と実行処理を自動構成する実験プロジェクトです。 API仕様を単一のsource of truthとして維持し、LLM連携時の実装負荷と運用負荷を下げることを目的とします。

目次

1. 主要機能
2. 技術スタック
3. セットアップ手順
4. 使用方法
5. プロジェクト構造
6. 関連ドキュメント

主要機能

• OpenAPI仕様の読み込み: --specで単一/複数ファイル、--dirでディレクトリ探索に対応します。
• MCPツール自動生成: pathsとoperationを走査し、入力スキーマと説明文を自動で生成します。
• 公開制御: x-mcp.exposeと--deny-*引数を併用して公開/非公開を制御します。
• 認証情報の解決: APIキー認証とBasic認証を環境変数から解決してHTTPリクエストへ注入します。
• エラー正規化: HTTPステータスごとにhintとretryableを付与した構造化エラーを返します。
• サンプル仕様対応: 複数形式のOpenAPI入力を使った検証に対応します。

技術スタック

言語・実行環境

• JavaScript: ECMAScript Modules
• Node.js: fetchが利用できるランタイムを想定
• zx: 実行ランタイム兼ユーティリティ

主要ライブラリ

• @modelcontextprotocol/sdk: MCPサーバー実装
• @apidevtools/swagger-parser: OpenAPI仕様の解決

品質管理ツール

• markdownlint-cli2: Markdownルール検証
• textlint: 日本語品質ルール検証
• prettier: 文章・設定ファイルの整形

セットアップ手順

前提条件

• Node.js
• zx(公式リポジトリー)

インストール

1. リポジトリーを取得します。

   git clone https://github.com/wate/openapi-mcp.git
   cd openapi-mcp
   

2. 動作確認としてサーバーを起動します。

   zx --install ./mcp-server.mjs --spec ./openapi/endoflife.yml
   

3. ドキュメント品質チェックを実行する場合のみ、依存関係をインストールします。

   yarn install
   

使用方法

基本フロー

1. 入力するOpenAPI仕様を選びます。
2. zx --install ./mcp-server.mjsでMCPサーバーを起動します。
3. MCPクライアントからtools/listとtools/callを実行します。
4. 必要に応じてx-mcpや--deny-*で公開範囲を調整します。

代表コマンド

# 単一specを指定
zx --install ./mcp-server.mjs --spec ./openapi/endoflife.yml

# 複数specを指定
zx --install ./mcp-server.mjs \
    --spec ./openapi/endoflife.yml \
    --spec ./openapi/jgrants.yaml

# ディレクトリを指定して自動探索
zx --install ./mcp-server.mjs --dir ./openapi

# 公開除外を指定
zx --install ./mcp-server.mjs --spec ./openapi/endoflife.yml --deny-methods delete

x-mcpによる補助情報

paths:
  /customers:
    get:
      operationId: searchCustomers
      x-mcp:
        expose: true
        name: search_customers
        description: 顧客検索用ツール
        annotations:
          readOnlyHint: true
          destructiveHint: false
          idempotentHint: true

プロジェクト構造

.
├ README.md
├ mcp-server.mjs
├ package.json
├ lib/
│    ├ args.mjs
│    ├ auth.mjs
│    ├ config.mjs
│    ├ executor.mjs
│    ├ tools.mjs
│    ├ trimming.mjs
│    └ utils.mjs
├ tests/
│    ├ unit/
│    ├ integration/
│    └ e2e/
└ docs/
     └ design.md

• mcp-server.mjs: エントリーポイント。main のみを担当します。
• lib/: OpenAPI解析、ツール生成、HTTP実行、エラー整形などのロジックを分離したモジュール群です。
• tests/: ユニット・統合・E2E テスト。
• docs/design.md: 設計方針と仕様詳細を管理します。

関連ドキュメント

初回把握向け

• 設計メモ: 変換方針、優先順位、設計背景を確認するときに参照します。

更新ポリシー

• 実装方針を変更した場合は、まずdocs/design.mdを更新します。
• 進捗や判断理由は、Git管理下の運用ドキュメントに記録します。
• READMEは概要導線に限定し、詳細は関連ドキュメントへ追記します。