Unbundle OpenAPI Specs MCP

Desvincular el servidor MCP de OpenAPI

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) con herramientas para dividir los archivos de especificación de OpenAPI en varios archivos o extraer puntos finales específicos en un nuevo archivo. Permite a un cliente MCP (como un asistente de IA) manipular las especificaciones de OpenAPI mediante programación.

Prerrequisitos

• Node.js (versión LTS recomendada, por ejemplo, v18 o v20)
• npm (viene con Node.js)

Uso

Instalación mediante herrería

Para instalar Unbundle OpenAPI MCP Server para Claude Desktop automáticamente a través de Smithery :

La forma más sencilla de utilizar este servidor es a través de npx , lo que garantiza que siempre esté utilizando la última versión sin necesidad de una instalación global.

Alternativamente, puedes instalarlo globalmente (generalmente no se recomienda):

El servidor se iniciará y escuchará las solicitudes MCP en la entrada/salida estándar (stdio).

Configuración del cliente

Para usar este servidor con clientes MCP como VS Code, Cline, Cursor o Claude Desktop, agregue su configuración al archivo de configuración correspondiente. El método recomendado es npx .

VS Code / Cline / Cursor

Agregue lo siguiente a su User settings.json (accesible a través de Ctrl+Shift+P > Preferences: Open User Settings (JSON) ) o a un archivo .vscode/mcp.json en la raíz de su espacio de trabajo.

Escritorio de Claude

Agregue lo siguiente a su archivo claude_desktop_config.json .

Después de agregar la configuración, reinicie su aplicación cliente para que los cambios surtan efecto.

Herramientas MCP proporcionadas

split_openapi

Descripción: Ejecuta el comando redocly split para descomponer un archivo de definición de OpenAPI en varios archivos más pequeños según su estructura.

Argumentos:

• apiPath (cadena, obligatoria): la ruta absoluta al archivo de definición de OpenAPI de entrada (por ejemplo, openapi.yaml ).
• outputDir (cadena, obligatoria): La ruta absoluta al directorio donde se guardarán los archivos de salida divididos. Este directorio se creará si no existe.

Devoluciones:

• En caso de éxito: un mensaje de texto que contiene la salida estándar del comando redocly split (generalmente un mensaje de confirmación).
• En caso de error: un mensaje de error que contiene los detalles del error estándar o de la excepción de la ejecución del comando, marcado con isError: true .

Ejemplo de uso (solicitud MCP conceptual):

extract_openapi_endpoints

Descripción: Extrae puntos de conexión específicos de un archivo de definición OpenAPI grande y crea un nuevo archivo OpenAPI más pequeño que contiene únicamente esos puntos de conexión y sus componentes referenciados. Esto se logra dividiendo el archivo original, modificando la estructura para conservar únicamente las rutas especificadas y, a continuación, empaquetando el resultado.

Argumentos:

• inputApiPath (cadena, obligatoria): la ruta absoluta al archivo de definición de OpenAPI de entrada grande.
• endpointsToKeep (matriz de cadenas, obligatorio): Una lista de las rutas exactas de los endpoints (cadenas) que se incluirán en la salida final (p. ej., ["/api", "/api/projects/{id}{.format}"] ). Se ignorarán las rutas que no se encuentren en la especificación original.
• outputApiPath (cadena, obligatoria): La ruta absoluta donde se guardará el archivo OpenAPI final, más pequeño y empaquetado. El directorio se creará si no existe.

Devoluciones:

• En caso de éxito: un mensaje de texto que indica la ruta del archivo creado y la salida estándar del comando redocly bundle .
• En caso de error: un mensaje de error que contiene detalles sobre el paso que falló (dividir, modificar, agrupar), marcado con isError: true .

Ejemplo de uso (solicitud MCP conceptual):

Nota: Este servidor utiliza internamente npx @redocly/cli@latest para ejecutar los comandos subyacentes split y bundle . Es posible que se requiera una conexión a internet para que npx obtenga @redocly/cli si no está almacenado en caché. Los archivos temporales se crean durante el proceso extract_openapi_endpoints y se limpian automáticamente.

Desarrollo

Si desea contribuir o ejecutar el servidor desde la fuente:

1. Clonar: Clonar este repositorio.
2. Navegar: cd unbundle_openapi_mcp
3. Instalar dependencias: npm install
4. Compilación: npm run build (compila TypeScript en dist/ )
5. Ejecutar: npm start (inicia el servidor usando el código compilado en dist/ )