클로드 문서 미드: OpenAPI 및 통합 생성용 MCP 서버

Node.js(ES Modules) 기반 Model Context Protocol (MCP) 생태계를 위한 엔터프라이즈급 서버로, OpenAPI/Swagger 사양을 학습하고 $ref를 역참조하여 LLM이 이를 조회하고 프로덕션 준비가 된 코드 통합을 생성할 수 있게 합니다.

@apidevtools/swagger-parser를 사용하여 서버 시작 시 모든 포인터와 컴포넌트 스키마를 메모리에서 해석하며, TypeScript, Python, JavaScript, cURL, C# 등 다양한 언어로 검색·검사·검증·HTTP 클라이언트 생성에 설계된 MCP 도구 8개의 카탈로그를 제공합니다.

📚 상세 문서

전문 가이드와 완전한 다이어그램은 다음을 참조하세요:

• 🏛️ 시스템 아키텍처 가이드 (docs/ARCHITECTURE.md): 플로우 다이어그램, 세션 바인딩, 관찰 가능성, 원자적 지속성 및 서킷 브레이커.

• 🛠️ MCP 도구 참고 자료 (docs/TOOLS_REFERENCE.md): 각 도구의 매개변수, JSON 스키마 및 응답 예제에 대한 자세한 설명.

• 📂 Swagger / OpenAPI 파일 가이드 (docs/SWAGGER_GUIDE.md): .yml 및 .json 사양을 추가, 검증, 구성하는 방법.

• 📋 Doters API Internal 구조 사양 (docs/MIDDLEWARE_API_SPEC.md): middleware-api.json의 110개 엔드포인트, 221개 DTO, 응답 래퍼 및 25개 도메인에 대한 분석.

Related MCP server: mcp-swagger

🏛️ 주요 기능

1. 자동 읽기 및 역참조 (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 확장과의 표준 통합.

   • SSE / HTTP: /sse, /messages, /metrics, /health, /dashboard 엔드포인트를 갖춘 Express 서버.

5. 관찰 가능성 및 보안:

   • 로그는 Pino와 함께 온전히 process.stderr로만 출력됩니다.

   • /metrics에 Prometheus(prom-client) 메트릭 제공.

   • /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단계: swaggers/ 에 파일 넣기

.json, .yml, .yaml 파일을 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 $\rightarrow$ specId: "avasa-car-rental"

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

2단계 2: npm run self-test 검증 검토

MCP 클라이언트를 실행하거나 서버를 무작정 재시작할 필요가 없습니다. 터미널에서 실행:

npm run self-test

이 명령은 15ms 안에 무엇을 할까요?

1. 새 파일을 감지하고 SHA-256 해시를 계산합니다.

2. 모든 $ref 포인터를 자동으로 해석하고 역참조합니다.

3. 끊어지거나 없는 참조를 정리하여 서버가 결코 무너지지 않게 합니다.

4. .cache/swaggers/에 무거운 트래픽용 스냅샷을 생성합니다.

5. 실시간 요약을 표시합니다:

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

3단계: 에이전트 및 LLM에서 조회할 준비 완료

즉시 8개의 MCP 도구가 추가 설정 없이 새 엔드포인트와 스키마를 학습합니다:

• 전역 검색: search_docs({ query: "renta autos" })은 모든 swagger에서 동시에 검색합니다.

• 한정 검색: search_docs({ query: "renta", specId: "avasa-car-rental" })은 해당 API만 조회합니다.

• 코드 생성: generate_integration_code({ path: "/v1/cars/book", language: "typescript" })은 형식화된 클라이언트를 생성합니다.

• Payload 검증: validate_payload({ schemaName: "CarBookingDto", 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이 자동으로 실제 테스트를 위한 payload를 만들 수 있습니다.

3. 명확한 태그(tags)를 사용하세요: 여러 태그로 그룹화(예: [ "CarRental", "Payments", "Security" ])하면 에이전트가 search_docs({ tag: "Payments" })으로 엔드포인트 컬렉션을 빠르게 필터링할 수 있습니다.

4. 보안(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% 이상의 문장(stmt) 커가 포함된 종합 테스트 스위트를 갖추고 있습니다:

# 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