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は概要導線に限定し、詳細は関連ドキュメントへ追記します。