Unbundle OpenAPI MCP Server

Unbundle OpenAPI MCP Server

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) con herramientas para dividir archivos de especificación OpenAPI en múltiples archivos o extraer endpoints específicos a un nuevo archivo. Permite que un cliente MCP (como un asistente de IA) manipule especificaciones OpenAPI programáticamente.

Requisitos previos

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

Uso

Instalación mediante Smithery

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

npx -y @smithery/cli install @auto-browse/unbundle_openapi_mcp --client claude

La forma más sencilla de usar este servidor es mediante npx, lo que garantiza que siempre estés usando la versión más reciente sin necesidad de una instalación global.

npx @auto-browse/unbundle-openapi-mcp@latest

Alternativamente, puedes instalarlo globalmente (generalmente no recomendado):

npm install -g @auto-browse/unbundle-openapi-mcp
# Then run using: unbundle-openapi-mcp

El servidor se iniciará y escuchará 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, agrega su configuración al archivo de configuración correspondiente. El enfoque recomendado utiliza npx.

VS Code / Cline / Cursor

Agrega lo siguiente a tu settings.json de Usuario (accesible mediante Ctrl+Shift+P > Preferences: Open User Settings (JSON)) o a un archivo .vscode/mcp.json en la raíz de tu espacio de trabajo.

// In settings.json:
"mcp.servers": {
  "unbundle_openapi": { // You can choose any key name
    "command": "npx",
    "args": [
      "@auto-browse/unbundle-openapi-mcp@latest"
    ]
  }
  // ... other servers can be added here
},

// Or in .vscode/mcp.json (omit the top-level "mcp.servers"):
{
  "unbundle_openapi": { // You can choose any key name
    "command": "npx",
    "args": [
      "@auto-browse/unbundle-openapi-mcp@latest"
    ]
  }
  // ... other servers can be added here
}

Claude Desktop

Agrega lo siguiente a tu archivo claude_desktop_config.json.

{
	"mcpServers": {
		"unbundle_openapi": {
			// You can choose any key name
			"command": "npx",
			"args": ["@auto-browse/unbundle-openapi-mcp@latest"]
		}
		// ... other servers can be added here
	}
}

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

Herramientas MCP Proporcionadas

split_openapi

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

Argumentos:

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

Devuelve:

• 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 el error estándar o los detalles de la excepción de la ejecución del comando, marcado con isError: true.

Ejemplo de Uso (Solicitud MCP Conceptual):

{
	"tool_name": "split_openapi",
	"arguments": {
		"apiPath": "/path/to/your/openapi.yaml",
		"outputDir": "/path/to/output/directory"
	}
}

extract_openapi_endpoints

Descripción: Extrae endpoints específicos de un archivo de definición OpenAPI grande y crea un nuevo archivo OpenAPI más pequeño que contiene solo esos endpoints y sus componentes referenciados. Logra esto dividiendo el archivo original, modificando la estructura para mantener solo las rutas especificadas y luego agrupando el resultado.

Argumentos:

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

Devuelve:

• 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):

{
	"tool_name": "extract_openapi_endpoints",
	"arguments": {
		"inputApiPath": "/path/to/large-openapi.yaml",
		"endpointsToKeep": ["/users", "/users/{userId}/profile"],
		"outputApiPath": "/path/to/extracted-openapi.yaml"
	}
}

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

Desarrollo

Si deseas contribuir o ejecutar el servidor desde el código fuente:

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