MCP-DOC-MID：用于 OpenAPI 与集成生成的 MCP 服务器

为 Node.js（ES Modules）中的 Model Context Protocol（MCP） 生态系统打造的企业级服务器，专注于 学习、解引用（$ref）并让 LLM 查询 OpenAPI/Swagger 规范，从而生成可直接用于生产的代码集成。

它使用 @apidevtools/swagger-parser 在服务器启动时于内存中解析所有指针和组件模型，并公开了一个包含 8 个 MCP 工具 的目录，这些工具专为搜索、检查、验证和生成多种语言（TypeScript、Python、JavaScript、cURL、C#）的 HTTP 客户端而设计。

📚 详细文档

如需专业指南和完整图表，请参阅：

• 🏛️ 系统架构指南（docs/ARCHITECTURE.md）：流程图、会话绑定、可观测性、原子持久化与熔断器。

• 🛠️ MCP 工具参考（docs/TOOLS_REFERENCE.md）：每种工具的参数、JSON 格式和响应示例的详细说明。

• 📂 Swagger / OpenAPI 文件指南（docs/SWAGGER_GUIDE.md）：用于添加、验证和整理 .yml 和 .json 文件的说明。

• 📋 Doters API 内部规范（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：Express 服务器，支持 /sse、/messages、/metrics、/health 和 /dashboard。

5. 可观测性与安全性：

   • 使用 Pino 将日志仅输出到 process.stderr。

   • 在 /metrics 上提供 Prometheus 指标（prom-client）。

   • 在 /messages 中实现会话绑定与会话劫持保护。

🛣️ 三步整合流程（零代码）

为了让新 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/ 目录中即可。

📁 推荐的可扩展结构（按域名或微服务组织）：

扫描器是 递归的，因此随着 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

这个命令在 < 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 个 MCP 工具会立即学习新的端点和模式，无需任何额外配置：

• 全局搜索：search_docs({ query: "renta autos" }) 将同时对所有 swaggers 进行搜索。

• 过滤搜索：search_docs({ query: "renta", specId: "avasa-car-rental" }) 仅查询该 API。

• 代码生成：generate_integration_code({ path: "/v1/cars/book", language: "typescript" }) 将生成类型化客户端。

• 加载模板验证：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" ]）可让代理通过 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%：

# 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