openapi-md-mcp

OpenAPI spec を段階的開示（progressive disclosure）して markdown にする MCP server。

なぜ

• Swagger UI（/docs）は JS シェルで、AI が内容を取得できない

• /openapi.json は全体で数十 K tokens になり、コンテキストに丸ごと入れるのは高コスト

• 本ツールは AI の常駐コンテキストを「キー + 要約」のエンドポイント表のみ（~1k tokens）に抑え、 キーでドリルダウンして単一エンドポイント / 単一 schema の markdown 詳細を取得。実測で約 90% のコンテキストを節約

Related MCP server: OpenAPI MCP Server

ツール面（渐进的开示、出力はすべて markdown）

ドリルダウンキー = METHOD /path または schema 名で、上位の出力から直接取得できます。

バッチモード（select + get_batch）

単一キーのドリルダウンでは横断的な質問（「すべての認証エンドポイント」は個別に get_endpoint を数十回行う必要がある）に答えられないため、 バッチ層で補完します：

• select(patterns=["GET /v1/auth/*", "* /v1/scoring/*"], security="X-Service-Token", tag="scoring", schema_glob="Credit*")

  • patterns の要素は "METHOD /path/glob" 形式：メソッドは * 可（大文字小文字を区別しない）；パス glob は大文字小文字を区別

  • security は scheme 名；patterns 間は OR、security/tag とは AND

  • ゼロ一致は成功テキストを返す（利用可能な scheme / tag + 緩和の提案）、エラーではない

• get_batch(["POST /v1/scoring/credit", "CreditBatchRequest"])

  • キーは重複排除して順序保持、上限 40 個；レンダリング総文字数上限 100k、超過時は include_refs=False または分割を推奨

  • include_refs=True はレンダリング中に参照された $ref を自動で「共有 schema 付録」に統合（各名前は1回のみレンダリング）

設定（env）

• spec は JSON と YAML に対応；ロード後はプロセス内に 60 秒キャッシュ

• リクエストは直接接続（trust_env=False）：対象は localhost / 内ネットワークの spec で、システムプロキシを経由しない（macOS のシステムプロキシは localhost を 502 に乗っ取るため）

• 読み取り専用で、API 呼び出し機能は提供しない（認証ヘッダーは MCP 層に入らない）

任意のリポジトリへの接続

Claude Code ユーザーレベル登録（一度登録すれば全リポジトリで利用可能）：

claude mcp add openapi-md -s user -- \
  uv run --directory /path/to/openapi-md-mcp openapi-md-mcp

異なるデータソースが必要なリポジトリは、各プロジェクトレベルの .mcp.json で env を上書きするだけです。

プロトコル準拠（MCP 2026-07-28、通称 2.0）

• ツール名 / 説明 / inputSchema は仕様 §Tools に準拠（名前の文字セットと長さ、決定論的な tools/list 順序）

• 5 ツールすべてが annotations.readOnlyHint: true（読み取り専用）を宣言

• エラー意味論は仕様 §Tools Error Handling に準拠：spec ロード失敗、不明なキー（類似キーの提案を含む）、 不正なフィルターパターンとバッチ上限超過は Tool Execution Error として ToolError をスロー → オンライン上では CallToolResult(isError=true) として現れ、クライアントは提案をモデルにフィードバックして自己修正；ゼロ一致は成功テキスト； call（API 呼び出し）機能は提供しない

• バージョン交渉：stdio は initialize ハンドシェイクエポック（最大 2025-11-25）；2026-07-28 のステートレス エンベロープエポックは SDK が HTTP トランスポート層で処理（server/discover）、stdio シナリオでは関与しない

開発

uv sync                 # 安装依赖
uv run pytest --cov=openapi_md_mcp   # 测试（fixture 为真实 OpenAPI 3.1 快照）