MCP-DOC-MID: MCP-сервер для OpenAPI и генерации интеграций

Корпоративный сервер для экосистемы Model Context Protocol (MCP) на Node.js (ES Modules), специализирующийся на изучении, разворачивании ссылок ($ref) и предоставлении LLM возможности запрашивать спецификации OpenAPI/Swagger и генерировать интеграции кода, готовые к продакшену.

Использует @apidevtools/swagger-parser для разрешения в памяти всех указателей и схем компонентов при запуске сервера и предоставляет каталог из 8 инструментов MCP, предназначенных для поиска, инспекции, валидации и генерации HTTP-клиентов на нескольких языках (TypeScript, Python, JavaScript, cURL, C#).

📚 Подробная документация

Для специализированных руководств и полных схем обратитесь к:

• 🏛️ Руководство по архитектуре системы (docs/ARCHITECTURE.md): Диаграммы потоков, Session Binding, наблюдаемость, атомарное персистентное хранение и Circuit Breaker.

• 🛠️ Справочник инструментов MCP (docs/TOOLS_REFERENCE.md): Исчерпывающее описание параметров, JSON-схем и примеров ответов для каждого инструмента.

• 📂 Руководство по файлам Swagger / OpenAPI (docs/SWAGGER_GUIDE.md): Инструкции по добавлению, проверке и организации файлов .yml и .json.

• 📋 Спецификация структуры Doters API Internal (docs/MIDDLEWARE_API_SPEC.md): Анализ 110 endpoints, 221 DTOs, обёрток ответов и 25 доменов middleware-api.json.

Related MCP server: mcp-swagger

🏛️ Основные характеристики

1. Автоматическое чтение и разворачивание ссылок (swaggers/):

   • Рекурсивное сканирование файлов .yml, .yaml и .json.

   • Полное разрешение ссылок $ref в компонентах, параметрах и моделях.

2. Генерация интеграций кода для LLM:

   • generate_integration_code: генерирует сниппеты и строго типизированные клиенты для любого endpoint.

   • Поддержка 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.

   • SSE / HTTP: сервер Express, поддерживающий /sse, /messages, /metrics, /health и /dashboard.

5. Наблюдаемость и безопасность:

   • Логи направляются только в process.stderr через Pino.

   • Метрики Prometheus (prom-client) в /metrics.

   • Привязка сеанса и защита от Session Hijacking в /messages.

🛣️ Процесс интеграции за 3 шага (Zero-Code)

Чтобы интеграция новых API была 100% масштабируемой, без трения и без изменения ни одной строки кода, сервер реализует Автообнаружение и загрузку по соглашению:

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:// /c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/swaggers).

📁 Рекомендуемая масштабируемая структура (по доменам или микросервисам):

Сканер рекурсивный, поэтому вы можете организовывать файлы в тематические подпапки по мере роста количества 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-rental.json → specId: "avasa-car-rental"

• openpay-gateway.yml → specId: "openpay-gateway"

2️⃣ Шаг 2: Проверка целостности с помощью npm run self-test

Вам не нужно поднимать MCP-клиенты или вслепую перезапускать серверы. Выполните в терминале:

npm run self-test

Что делает эта команда за время, меньшее 15 мс?

1. Обнаруживает новый файл и вычисляет его SHA-256 хэш.

2. Автоматически разрешает и разворачивает все указатели $ref.

3. Исправляет битые или отсутствующие ссылки, чтобы сервер никогда не выходил из строя.

4. Генерирует быстродействующий снапшот в .cache/swaggers/.

5. Выводит сводку в реальном времени:

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

3️⃣ Шаг 3: Готово для запросов агентов и LLM

Немедленно, без дополнительной настройки, 8 8 инструментов MCP осваивают новые endpoints и схемы:

• Глобальный поиск: search_docs({ query: "renta autos" }) будет искать по всем swaggers одновременно.

• Фильтрованный поиск: search_docs({ query: "renta", specName: "avasa-car-rental" }) запросит только эту спецификацию.

• Генерация кода: generate_integration_code({ path: "/v1/cars/book", language: "typescript" }) сгенерирует типизированный клиент.

• Валидация payload: validate_payload({ schemaName: "CarBookingDto", payload: { ... } }) выполнит проверку по новой модели.

🏆 Рекомендуемые практики для максимального качества в LLM

Чтобы языковые модели генерировали превосходный код и точные ответы при чтении ваших новых swaggers:

1. Укажите базовый URL (servers):

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

2. Вставляйте примеры в схемы (example / examples): Примеры позволяют инструменту generate_integration_code и LLM автоматически создавать реалистичные тестовые данные.

3. Используйте понятные теги (tags): Группировка по тегам (например, [ "CarRental", "Payments", "Security" ]) позволяет агентам быстро фильтровать наборы endpoints через search_docs({ selector: "Payments" }).

4. Указывайте security-схемы (components.securitySchemes): Опишите bearerFormat: JWT, ApiKey или OAuth2, чтобы инструмент 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%) и покрытие более 93% по инструкциям:

# 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