@reapi/mcp-openapi

Un servidor de Protocolo de Contexto de Modelo (MCP) que carga y sirve múltiples especificaciones OpenAPI para facilitar la integración con IDEs basados en LLM. Este servidor actúa como puente entre las especificaciones OpenAPI y las herramientas de desarrollo basadas en 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 a los LLM comprender y trabajar con sus API directamente en su IDE

• Admite esquemas desreferenciados para un contexto de API completo

• Mantiene un catálogo de todas las API disponibles

Desarrollado por ReAPI

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

🎨 API CMS

• Diseñe API utilizando un editor intuitivo sin código

• Genere y publique especificaciones OpenAPI automáticamente

• Colaborar con los 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 los desarrolladores

• Cree y gestione casos de prueba con una interfaz intuitiva

• Potentes capacidades de afirmación y validación

• Ejecutor de pruebas en la nube sin servidor

• Perfecto tanto para equipos de control de calidad como para desarrolladores.

• Listo para integración CI/CD

Pruebe ReAPI gratis en reapi.com y experimente el futuro del desarrollo de API.

Configuración del cursor

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

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

Cree un archivo .cursor/mcp.json en el directorio de su proyecto. Se recomienda esta opción, ya que permite mantener diferentes conjuntos de especificaciones para distintos proyectos.

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

Nota : Recomendamos utilizar la etiqueta @latest ya que actualizamos frecuentemente el servidor con nuevas funciones y mejoras.

Importante : La configuración específica del proyecto ayuda a gestionar los límites del contexto LLM. Al colocar todas las especificaciones 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 permite controlar el tamaño del contexto.

Opción 2: Configuración global

Cree o edite ~/.cursor/mcp.json en su directorio de inicio para que el servidor esté disponible en todos los proyectos:

Habilitar en la configuración del cursor

Después de agregar la configuración:

1. Abrir cursor IDE

2. Vaya a Configuración > Configuración del cursor > MCP

3. Habilitar el servidor @reapi/mcp-openapi

4. Haga clic en el icono de actualización junto al servidor para aplicar los cambios

Nota : De forma predeterminada, Cursor requiere confirmación para cada ejecución de la herramienta MCP. Si desea permitir la ejecución automática sin confirmación, puede habilitar el modo Yolo en la configuración de Cursor.

El servidor ya está listo para usar. Al agregar nuevas especificaciones de OpenAPI a su directorio, puede actualizar el catálogo mediante:

1. Apertura del panel de chat de Cursor

2. Escribiendo una de estas indicaciones:

   "Please refresh the API catalog" "Reload the OpenAPI specifications"

Requisitos de la especificación OpenAPI

1. Coloque sus especificaciones OpenAPI 3.x en el directorio de destino:

   • Admite 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 especificaciones

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

   • De forma predeterminada, se utiliza el nombre del archivo (sin extensión) como ID de especificación

   • Para especificar un ID personalizado, agregue 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 puntos finales similares o idénticos

   • Mismos nombres de esquema

   • Identificadores de operaciones superpuestos

   El ID de especificación ayuda a distinguir entre estos recursos similares y evita 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 hacer referencia a estos puntos finales 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 desreferencia las especificaciones para obtener 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 IDE pueden luego utilizar esta información para:

   • Proporcionar contexto de API a los LLM

   • Habilitar la finalización inteligente de código

   • Ayudar en la integración de API

   • Generar fragmentos de código compatibles con API

Herramientas

1. refresh-api-catalog

   • Actualizar el catálogo de API

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

2. get-api-catalog

   • Obtenga el catálogo de API, el catálogo contiene metadatos sobre todas las especificaciones de OpenAPI, sus operaciones y esquemas.

   • Devoluciones: Catálogo API completo con todas las especificaciones, operaciones y esquemas

3. search-api-operations

   • Búsqueda de 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

   • Devoluciones: Operaciones coincidentes del catálogo de API

4. search-api-schemas

   • Búsqueda de 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

   • Devoluciones: esquemas coincidentes del catálogo de API

5. load-api-operation-by-operationId

   • Cargar una operación por operationId

   • Entradas:

     • specId (cadena): ID de especificación de API

     • operationId (cadena): ID de la operación a cargar

   • Devoluciones: Detalles completos de la operación

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

   • Cargar una operación por ruta y método

   • Entradas:

     • specId (cadena): ID de especificación de API

     • path (cadena): ruta del punto final de la API

     • method (cadena): método HTTP

   • Devoluciones: Detalles completos de la operación

7. load-api-schema-by-schemaName

   • Cargar 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

   • Mejore la precisión de la búsqueda con la comprensión semántica

2. Sincronización remota de especificaciones

   • Admite la sincronización de 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 funciones e informes de errores

   • Contribuir a mejorar el servidor

Ejemplos de indicaciones en el cursor

A continuación se muestran algunos ejemplos de indicaciones que puede utilizar en Cursor IDE para interactuar con sus API:

1. Explorar las API disponibles

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

2. Detalles de la operación de la 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. Esquema 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 para la 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"

Estas indicaciones muestran cómo aprovechar las capacidades del servidor MCP para el desarrollo de API. Puede adaptarlas a sus necesidades específicas o combinarlas para tareas más complejas.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.