Swagger MCP Server

Servidor MCP de Documentación Swagger OpenAPI de Acceleronix

Un servidor integral del Model Context Protocol (MCP) que proporciona acceso fluido a 32 OpenAPIs del Acceleronix Developer Center. Construido sobre Cloudflare Workers con gestión inteligente de herramientas y autenticación con Bearer token.

Características

• 32 OpenAPIs de Acceleronix PaaS: Cobertura integral de gestión de dispositivos, almacenamiento de datos, servicios familiares y más
• Gestión inteligente de herramientas: Equilibrio de carga inteligente con 3-8 herramientas por API (~100 herramientas en total)
• Arquitectura de múltiples niveles: Niveles de acceso EndUser, Enterprise y Open API
• Autenticación con Bearer Token: Autenticación unificada en todas las APIs
• Acceso en tiempo real: Implementado en Cloudflare Workers para acceso global de baja latencia
• Integración con Claude: Integración directa con Claude Desktop y AI Playground

Categorías de API compatibles

Gestión principal de dispositivos (18 APIs habilitadas)

• Device Manager (Enterprise) - Gestión del ciclo de vida y configuración de dispositivos
• Device Shadow (Enterprise) - Sincronización de estado de dispositivos y operaciones de sombra
• Binding Service (EndUser/Enterprise) - Vinculación de dispositivos y asociación de usuarios
• DeviceGroup Service (EndUser) - Gestión de grupos y operaciones por lotes

Servicios de plataforma

• App Service (EndUser) - Gestión e implementación de aplicaciones
• Family Service (EndUser) - Gestión de cuentas familiares multiusuario
• EndUser Service (EndUser) - Operaciones de perfil de usuario y cuenta
• Product Management (Enterprise) - Catálogo de productos y ciclo de vida

Datos y análisis

• Data Storage (EndUser) - Almacenamiento y recuperación de datos de series temporales
• Weather Service (EndUser) - Integración de datos meteorológicos
• Rule Engine (EndUser) - Procesamiento de eventos y reglas de automatización
• Category Management (EndUser) - Categorización y taxonomía de dispositivos

Servicios de infraestructura

• OTA Service (EndUser) - Actualizaciones de firmware por aire
• Thing Specification Language (Enterprise) - Definiciones de modelos de dispositivos
• Matter Service (EndUser) - Integración del protocolo Matter
• I18n Service (EndUser) - Internacionalización y localización
• Global Bootstrap (Open) - Servicios de inicialización de plataforma

APIs adicionales (14 disponibles, actualmente deshabilitadas)

• Servicio de correo, notificaciones push móviles, aplicación OEM, servicio de portal, órdenes de trabajo, SMS, medios de transmisión y más

Inicio rápido

Implementar en Cloudflare Workers

# Clone the repository
git clone <repository-url>
cd swagger-mcp-server

# Install dependencies
npm install

# Deploy to Cloudflare Workers
npm run deploy

Su servidor MCP estará disponible en: https://swagger-mcp-server.<your-account>.workers.dev/sse

Desarrollo local

# Start local development server
npm run dev

# Server available at: http://localhost:8787/sse

Configuración

Configuración del Bearer Token

Actualice los tokens de autenticación en src/config.ts:

{
  name: "device_mgr_enterprise",
  title: "IoT Device Manager (Enterprise)",
  auth: { type: 'bearer', token: 'your-bearer-token-here' },
  enabled: true,
  maxTools: 8
}

Habilitar/Deshabilitar APIs

Controle qué APIs están activas modificando el indicador enabled:

{
  "name": "mail_enduser",
  "title": "Mail Service (EndUser)",
  "enabled": false,  // Set to true to enable
  "maxTools": 4
}

Integración con Claude Desktop

Agregue a su configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "iot-apis": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://swagger-mcp-server.your-account.workers.dev/sse"
      ]
    }
  }
}

Herramientas disponibles

El servidor genera automáticamente herramientas a partir de las especificaciones Swagger con nombres inteligentes:

• device_mgr_enterprise_getDevices - Listar todos los dispositivos
• binding_enduser_bindDevice - Vincular dispositivo a usuario
• deviceshadow_enterprise_updateShadow - Actualizar sombra de dispositivo
• weather_enduser_getCurrentWeather - Obtener datos meteorológicos actuales
• Y aproximadamente 96 herramientas más en todas las APIs habilitadas

Herramientas de gestión

Listar APIs disponibles

# Using Claude
"List all available APIs and their status"

Probar conexión

# Using Claude  
"Test the MCP server connection"

Arquitectura

Claude Desktop/AI Playground
           ↓
    MCP JSON-RPC 2.0
           ↓
   Cloudflare Workers
           ↓
    McpAgent (Durable Objects)
           ↓
   Multi-API Tool Router
           ↓
    32 IoT APIs (Acceleronix)

Estrategia de distribución de herramientas

• APIs de alta prioridad: 6-8 herramientas cada una (Device Management, Product, TSL)
• APIs de prioridad media: 4-6 herramientas cada una (Binding, Shadow, Data Storage)
• APIs de utilidad: 3-4 herramientas cada una (Weather, I18n, Bootstrap)
• Total: ~100 herramientas en 18 APIs habilitadas

Características de seguridad

• Autenticación con Bearer token para todas las llamadas a la API
• Soporte de variables de entorno para tokens sensibles
• CORS habilitado para clientes de navegador
• Validación de solicitudes y manejo de errores

Endpoints

• MCP SSE: /sse - Endpoint de eventos enviados por el servidor para Claude
• Health Check: /health - Estado del servicio e información de versión
• MCP JSON-RPC: /mcp - Endpoint directo JSON-RPC 2.0

Documentación de la API

Cada API proporciona documentación Swagger completa accesible a través de las herramientas. Use la herramienta list_apis para ver todas las APIs disponibles y sus descripciones.

Contribuciones

1. Haga un fork del repositorio
2. Agregue nuevas APIs a src/config.ts
3. Pruebe localmente con npm run dev
4. Implemente y pruebe con Claude Desktop
5. Envíe un pull request

Licencia

Licencia MIT: consulte el archivo LICENSE para obtener más detalles