MCP-DOC-MID: OpenAPIとインテグレーション生成のためのMCPサーバー

Node.js（ES Modules）で動作するエンタープライズグレードの**Model Context Protocol（MCP）**エコシステム向けサーバー。OpenAPI / Swagger の仕様を読み込み、$refを解決（デリファレンス）し、LLMがそれらの仕様を参照し、プロダクション対応のコードを生成できるようにすることを専門としています。

@apidevtools/swagger-parserを使って、サーバー起動時にメモリ上で全ポイントとコンポーネント・スキーマを解決し、複数言語（TypeScript、Python、JavaScript、cURL、C#）向けて検索、検査、検証、HTTPクライアンド生成のためのMCPツールを公開します。

📚 詳参なドキュメンテーション

専門的なガイドや完全なるダイアグラムについては、以下を参照してください：

• ️ [システム・アーキテクチュア・ガイド (docs/ARCHITECTURE.md)](file://, in/Users/Manuel/Documents/Vivaerobuses/Doters/MCP/mcp-docu-mid/docs/ARCHITECTURE.md): フロー図、セッションバインジグ、オーミーバビティ、アトミックなパスタンス、サーキットブレール。

• ️ [MCPツール・リファレンス (docs/TOOLS_REFERENCE.md)](file://, in/...): 各ツールのパラメター、JSONスキーマ、応答例を詳網。

• 🏆 Swagger / OpenAPI ファイル・ガイド (docs/SWAGGER_GUIDE.md): .yml, .json 仕様の追加、検証、整理方。

• 📆 Doters API Internal 構造仕様 (docs/MIDDLEWARE_API_SPEC.md): middleware-api.json の 110 points, 221 DTOs, αポンスラッパー, 25ドメインの分析。

Related MCP server: mcp-swagger

️ 主な特長

1. 自動込み込みと Dフィレース（swaggers/）:

   • .yml, .yaml, .json のファイルを再帰的にス²ン。

   • コンポーネント、パラメータ、モデル内の$ref参照を完全に解決。

2. LLM向けのコー・インテグレーション生成:

   • generate_integration_code: 任意のエンドポイントに対し、強く型付けされたクライアントを生成。

   • TypeScript（fetch / axios）、JavaScript、Python（httpx / requests）、cURL、C# をサポート。

3. セキュリティの検証と抽出:

   • validate_payload: JSONペイロードの型と必須フィールドを事前検証。

   • get_security_schemes: 認証スキーマを抽出（Bearerトークン、APIキー、OAuth2）。

4. デュアル・トランスポート:

   • STDIO: Claude Desktop, Antigravity, Cursor, MCP extensionsとの standard integration。

   • SSE / HTTP: /sse, /meessages, /metrics, /helth, /dashboard を備えた Express サーバー。

5. オーーバーイとセキュリティ:

   • ログはPinoによりprocess.stderrへ完全に専出。

   • /metrics での Prometheus メトリクs（prom-cl）。

   • /meessages でのセッション・バ计バインデ and Session-Jacking 防御。

🇳 3ステップのインテグレーション・フロー（ゼロ・コーー）

新しarapi integrationを100% スケール可能・摩擦なし・コード1行も変えずにするため、サーバーはオートデイスカバリーと約に基づくロードを実装しています：

flowchart LR
    A["1. Copiar Archivo\n(swaggers/mi-api.json o .yml)"] --> B["2. Auto-Discovery & Caching\n(Hash SHA-256 + Dereference)"]
    B --> C["3. Auto-Diagnóstico\n(npm run self-test)"]
    C --> D["✅ Disponible en las 8 Tools MCP\n(search_docs, get_endpoint_doc, etc.)"]

1️⃣ スップ1: ファイルをswaggers/に配置

.json, .yml, .yaml ファイルを [swaggers/](file://, /... ただく配置するだでOKです。

🏖 推奨されるスケール可能な構成（ドメイン・マイクロサビスごと）:

スキャナーは再帰的なので、APIイズとともに、テーマックに応じたサブフォルダーでファイルを整理することができます：

swaggers/
├── middleware-api.json                # API Core Middleware
├── partners/
│   ├── avasa-car-rental.json          # Swagger de Avasa
│   └── iamsa-bus.json                 # Swagger de IAMSA
├── payments/
│   └── openpay-gateway.yml            # OpenAPI de Pasarelas de Pago
└── flights/
    └── viva-booking.yaml              # OpenAPI de Reservaciones Viva

[!TIP] 自動表示子（specId）:
ファイルベ名から自動的にspecIdを生成します。

• avasa-car-arental.json $\rightarrow$ specId: "avasa-car-arental"

• openpay-gatway.yml $\rightarrow$ specId: "openpay-gatway"

2️⃣ スップ2: npm run self-test で整合性を確認

MCPクライアントとして起動したり、手動でサーバーを昇り直す必要はありません。ターミナルで次を実行します：

npm run self-test

このコマンドは<15 msで何をしますか？

1. 新しいファイルを検出し、SHA-25ハッーを計算します。

2. $refポインタを自動的に解決し、デリファーします。

3. 壊れたり欠損した欠損 }参照を無効するのでサーバーがクラッシュしません。

4. .cache / swaggers / に高パフォーマンス・スアンプショットを生成します。

5. 結果のマーをリアータ表现します：

{
  "status": "healthy",
  "checks": {
    "swaggers": {
      "status": "pass",
      "specsCount": 4,
      "endpointsCount": 285,
      "schemasCount": 412
    }
  }
}

3️⃣ Step 3: エージェントとLLMから検クする準備が完了

すぐに、8つのMCPツールが新規エンドポイントをスキーマを追加設定なしで学習・取込します：

• グローバル検索: search_docs({ quary: "rent a autos" }) で、全スワガースを一度に横断検索します。

• フィルター検索: search_docs({ query: "renta, specd: "avasa-car-1-rental" }) で、そのAPIだけを照合します。

• コーデ生成: generate_integration_code({ path: "/v1/cars/book" language: "typeScript" }) で、型付きクライアントを生成します。

• ペイロード検証: validate_payload({ schemaName: "CarBokkingDto", payload: { ... } }) で、新しいモデルに対して検証します。

🏆 LLMで最大品質を保証するための実装実践

言語モデルが新しいSwaggerを読んだとき、最良のコードと正確な値を生成できるように：

1. アベースURLを宣言する（servers）:

   servers:
     - url: https://api.vivaaerobus.com/v1
       description: Ambiente de Producción

2. スキーマする擬 (example / examples): 例を含めることで、generate_integration_code と LLMが、実際のテスト用ペイロードを自動で作することができます。

3. 明確のタグするタグでグルーパングする（例：["CarRental", "Payments" ]）、search_docs({ tag: "Payments" }) でエージェントがすばやくエンドポイント集まりをフィルターができます。

4. セキュリティを宣言する（components.securitySchemes）: bearerFormat: JWT、apiKey、OAuth2Fを指定すると、get_security_schemes ツールが必要なヘッダーを公开できます。

{MCPツールの一覧

実現環境変数（.env）

💡 クイック・スタート

# 1. Instalar dependencias
npm install

# 2. Autodiagnóstico en runtime (<5ms)
npm run self-test

# 3. Iniciar en modo STDIO (predeterminado)
npm start

# 4. Iniciar en modo SSE / HTTP (servidor web)
TRANSPORT_MODE=sse PORT=3000 npm start

〵 自動テトとベンチマーク

このプロジェクトには、116テス（100%per）と文カバレッジ90%以上を含む統合テスートスートがあります：

# 1. Ejecutar suite completa de pruebas unitarias y de integración
npm test

# 2. Reporte de cobertura detallado con Vitest y V8 (>93% Stmts)
npm run test:coverage

# 3. Pruebas de carga de alta concurrencia (100 agentes concurrentes)
npm run test:load

# 4. Benchmark de latencia y throughput (<5ms)
npm run benchmark

# 5. Pipeline de integración continua (CI)
npm run test:ci

|| Docker でのインタロイメント

# Construir imagen Docker multi-stage
docker build -t mcp-doc-mid:latest .

# Ejecutar contenedor en modo SSE
docker run -p 3000:3000 -e TRANSPORT_MODE=sse mcp-doc-mid:latest