ReAPI OpenAPI

Sirve múltiples especificaciones OpenAPI para habilitar integraciones de IDE impulsadas por LLM

GitHub
90
Prueba este MCPPatrocinado

Documentación

@reapi/mcp-openapi

Un servidor de Model Context Protocol (MCP) que carga y sirve múltiples especificaciones OpenAPI para habilitar integraciones de IDE impulsadas por LLM. Este servidor actúa como un puente entre tus especificaciones OpenAPI y herramientas de desarrollo impulsadas por LLM como Cursor y otros editores de código.

Características

  • Carga múltiples especificaciones OpenAPI desde un directorio
  • Expone operaciones y esquemas de API a través del protocolo MCP
  • Permite que los LLM comprendan y trabajen con tus APIs directamente en tu IDE
  • Soporta esquemas dereferenciados para un contexto completo de API
  • Mantiene un catálogo de todas las APIs disponibles

Impulsado por ReAPI

Este servidor MCP de código abierto está patrocinado por ReAPI, una plataforma de API de próxima generación que simplifica el diseño y las pruebas de API. Mientras que este servidor proporciona integración local de OpenAPI para desarrollo, ReAPI ofrece dos módulos potentes:

🎨 API CMS

  • Diseña APIs usando un editor intuitivo sin código
  • Genera y publica especificaciones OpenAPI automáticamente
  • Colabora con miembros del equipo en tiempo real
  • Control de versiones y gestión de cambios

🧪 Pruebas de API

  • La solución de pruebas de API sin código más amigable para desarrolladores
  • Crea y gestiona casos de prueba con una interfaz intuitiva
  • Potentes capacidades de aserción y validación
  • Ejecutor de pruebas en la nube sin servidor
  • Perfecto tanto para equipos de QA como para desarrolladores
  • Listo para integración con CI/CD

Prueba ReAPI gratis en reapi.com y experimenta el futuro del desarrollo de APIs.

Configuración de Cursor

Para integrar el servidor MCP OpenAPI con el IDE de Cursor, tienes dos opciones para las ubicaciones de configuración:

Opción 1: Configuración específica del proyecto (Recomendada)

Crea un archivo .cursor/mcp.json en el directorio de tu proyecto. Esta opción es recomendada porque te permite mantener diferentes conjuntos de especificaciones para diferentes proyectos

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "./specs"],
      "env": {}
    }
  }
}

Consejo: Usar una ruta relativa como ./specs hace que la configuración sea portátil y más fácil de compartir entre miembros del equipo.

Nota: Recomendamos usar la etiqueta @latest ya que actualizamos frecuentemente el servidor con nuevas características y mejoras.

Importante: La configuración específica del proyecto ayuda a gestionar los límites de contexto del LLM. Cuando todas las especificaciones se colocan en una sola carpeta, los metadatos combinados podrían exceder la ventana de contexto del LLM, lo que provocaría errores. Organizar las especificaciones por proyecto mantiene el tamaño del contexto manejable.

Opción 2: Configuración global

Crea o edita ~/.cursor/mcp.json en tu directorio de inicio para que el servidor esté disponible en todos los proyectos:

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "/path/to/your/specs"],
      "env": {}
    }
  }
}

Habilitar en la configuración de Cursor

Después de agregar la configuración:

  1. Abre el IDE de Cursor
  2. Ve a Configuración > Configuración de Cursor > MCP
  3. Habilita el servidor @reapi/mcp-openapi
  4. Haz clic en el ícono de actualizar junto al servidor para aplicar los cambios

Nota: Por defecto, Cursor requiere confirmación para cada ejecución de herramienta MCP. Si deseas permitir la ejecución automática sin confirmación, puedes habilitar el modo Yolo en la configuración de Cursor.

El servidor ahora está listo para usar. Cuando agregues nuevas especificaciones OpenAPI a tu directorio, puedes actualizar el catálogo:

  1. Abriendo el panel de chat de Cursor
  2. Escribiendo uno de estos mensajes: 
    "Please refresh the API catalog"
"Reload the OpenAPI specifications"

Requisitos de las especificaciones OpenAPI

  1. Coloca tus especificaciones OpenAPI 3.x en el directorio de destino:

    • Soporta formatos JSON y YAML
    • Los archivos deben tener extensiones .json, .yaml o .yml
    • El escáner descubrirá y procesará automáticamente todos los archivos de especificación

  2. Configuración del ID de especificación:

    • Por defecto, el nombre del archivo (sin extensión) se usa como ID de especificación
    • Para especificar un ID personalizado, agrega x-spec-id en el objeto de información de OpenAPI:
    openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  x-spec-id: my-custom-api-id  # Custom specification ID

    Importante: Establecer un x-spec-id personalizado es crucial cuando se trabaja con múltiples especificaciones que tienen:

    • Rutas de endpoints similares o idénticas
    • Mismos nombres de esquemas
    • IDs de operación superpuestos

    El ID de especificación ayuda a distinguir entre estos recursos similares y previene conflictos de nombres. Por ejemplo:

    # user-service.yaml
info:
  x-spec-id: user-service
paths:
  /users:
    get: ...

# admin-service.yaml
info:
  x-spec-id: admin-service
paths:
  /users:
    get: ...

    Ahora puedes referenciar estos endpoints específicamente como user-service/users y admin-service/users

Cómo funciona

  1. El servidor escanea el directorio especificado en busca de archivos de especificación OpenAPI
  2. Procesa y dereferencia las especificaciones para un contexto completo
  3. Crea y mantiene un catálogo de todas las operaciones y esquemas de API
  4. Expone esta información a través del protocolo MCP
  5. Las integraciones del IDE pueden usar esta información para:
    • Proporcionar contexto de API a los LLM
    • Habilitar la finalización de código inteligente
    • Asistir en la integración de API
    • Generar fragmentos de código conscientes de la API

Herramientas

  1. refresh-api-catalog

    • Actualiza el catálogo de API
    • Devuelve: Mensaje de éxito cuando el catálogo se actualiza

  2. get-api-catalog

    • Obtiene el catálogo de API; el catálogo contiene metadatos sobre todas las especificaciones openapi, sus operaciones y esquemas
    • Devuelve: Catálogo completo de API con todas las especificaciones, operaciones y esquemas

  3. search-api-operations

    • Busca operaciones en todas las especificaciones
    • Entradas:
      • query (cadena): Consulta de búsqueda
      • specId (cadena opcional): ID de especificación de API específica para buscar dentro
    • Devuelve: Operaciones coincidentes del catálogo de API

  4. search-api-schemas

    • Busca esquemas en todas las especificaciones
    • Entradas:
      • query (cadena): Consulta de búsqueda
      • specId (cadena opcional): ID de especificación de API específica para buscar
    • Devuelve: Esquemas coincidentes del catálogo de API

  5. load-api-operation-by-operationId

    • Carga una operación por operationId
    • Entradas:
      • specId (cadena): ID de especificación de API
      • operationId (cadena): ID de operación a cargar
    • Devuelve: Detalles completos de la operación

  6. load-api-operation-by-path-and-method

    • Carga una operación por ruta y método
    • Entradas:
      • specId (cadena): ID de especificación de API
      • path (cadena): Ruta del endpoint de API
      • method (cadena): Método HTTP
    • Devuelve: Detalles completos de la operación

  7. load-api-schema-by-schemaName

    • Carga un esquema por schemaName
    • Entradas:
      • specId (cadena): ID de especificación de API
      • schemaName (cadena): Nombre del esquema a cargar
    • Devuelve: Detalles completos del esquema

Hoja de ruta

  1. Búsqueda semántica

    • Habilitar consultas en lenguaje natural para operaciones y esquemas de API
    • Mejorar la precisión de búsqueda con comprensión semántica

  2. Sincronización de especificaciones remotas

    • Soporte para sincronizar especificaciones OpenAPI desde fuentes remotas

  3. Plantillas de código

    • Exponer plantillas de código a través del protocolo MCP
    • Proporcionar patrones de referencia para la generación de código LLM

  4. Contribuciones de la comunidad

    • Enviar solicitudes de características e informes de errores
    • Contribuir para mejorar el servidor

Ejemplos de mensajes en Cursor

Aquí hay algunos ejemplos de mensajes que puedes usar en el IDE de Cursor para interactuar con tus APIs:

  1. Explorar APIs disponibles

    "Show me all available APIs in the catalog with their operations"
"List all API specifications and their endpoints"

  2. Detalles de operaciones de API

    "Show me the details of the create pet API endpoint"
"What are the required parameters for creating a new pet?"
"Explain the response schema for the pet creation endpoint"

  3. Esquemas y datos simulados

    "Generate mock data for the Pet schema"
"Create a valid request payload for the create pet endpoint"
"Show me examples of valid pet objects based on the schema"

  4. Generación de código

    "Generate an Axios client for the create pet API"
"Create a TypeScript interface for the Pet schema"
"Write a React hook that calls the create pet endpoint"

  5. Asistencia de integración de API

    "Help me implement error handling for the pet API endpoints"
"Generate unit tests for the pet API client"
"Create a service class that encapsulates all pet-related API calls"

  6. Documentación y uso

    "Show me example usage of the pet API with curl"
"Generate JSDoc comments for the pet API client methods"
"Create a README section explaining the pet API integration"

  7. Validación y tipos

    "Generate Zod validation schema for the Pet model"
"Create TypeScript types for all pet-related API responses"
"Help me implement request payload validation for the pet endpoints"

  8. Búsqueda y descubrimiento de API

    "Find all endpoints related to pet management"
"Show me all APIs that accept file uploads"
"List all endpoints that return paginated responses"

Estos mensajes demuestran cómo aprovechar las capacidades del servidor MCP para el desarrollo de APIs. Siéntete libre de adaptarlos a tus necesidades específicas o combinarlos para tareas más complejas.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).