OpenAPI Schema Explorer

Acceso eficiente en tokens a especificaciones OpenAPI/Swagger a través de Recursos MCP

Documentación

MCP OpenAPI Schema Explorer

Un servidor MCP (Model Context Protocol) que proporciona acceso eficiente en tokens a especificaciones OpenAPI (v3.0) y Swagger (v2.0) mediante Plantillas de Recursos MCP.

Objetivo del Proyecto

El objetivo principal de este proyecto es permitir que los clientes MCP (como Cline o Claude Desktop) exploren la estructura y los detalles de especificaciones OpenAPI de gran tamaño sin necesidad de cargar el archivo completo en la ventana de contexto de un LLM. Esto se logra exponiendo partes de la especificación a través de Plantillas de Recursos MCP, que proporcionan patrones de acceso parametrizados para la exploración de datos de solo lectura.

Este servidor admite la carga de especificaciones desde rutas de archivos locales y URLs HTTP/HTTPS remotas. Las especificaciones Swagger v2.0 se convierten automáticamente a OpenAPI v3.0 al cargarlas.

Nota: Este servidor proporciona plantillas de recursos (no recursos pre-enumerados). Los clientes MCP acceden a estas plantillas mediante el método de protocolo resources/templates/list. Para obtener más información sobre las plantillas de recursos, consulte la documentación de Plantillas de Recursos MCP.

¿Por qué Plantillas de Recursos MCP?

El Model Context Protocol define tanto Recursos como Herramientas.

Recursos: Representan fuentes de datos (como archivos, respuestas de API). Son ideales para acceso de solo lectura y exploración por parte de clientes MCP.
- Plantillas de Recursos: Un tipo especial de recurso que utiliza URIs parametrizados (por ejemplo, openapi://paths/{path}/{method}), permitiendo acceso dinámico sin pre-enumerar todos los valores posibles.
Herramientas: Representan acciones o funciones ejecutables, a menudo utilizadas por LLMs para realizar tareas o interactuar con sistemas externos.

Si bien existen otros servidores MCP que proporcionan acceso a especificaciones OpenAPI mediante Herramientas, este proyecto se centra específicamente en proporcionar acceso mediante Plantillas de Recursos. Este enfoque es particularmente eficiente para APIs grandes porque:

No requiere pre-enumerar miles de rutas y componentes potenciales
Los clientes pueden descubrir recursos disponibles dinámicamente utilizando los patrones de plantilla
Proporciona acceso estructurado y bajo demanda a partes específicas de la especificación

Para más detalles sobre los clientes MCP y sus capacidades, consulte la Documentación de Clientes MCP.

Guías de Inicio Rápido por Cliente

Claude Code - La herramienta CLI de Anthropic para programar con Claude
Claude Desktop, Cline, Windsurf - Consulte las instrucciones de instalación a continuación

Instalación

Para los métodos de uso recomendados (npx y Docker, descritos a continuación), no se requiere un paso de instalación separado. Su cliente MCP descargará el paquete o extraerá la imagen de Docker automáticamente según la configuración que proporcione.

Sin embargo, si prefiere o necesita instalar el servidor explícitamente, tiene dos opciones:

Instalación Global: Puede instalar el paquete globalmente usando npm:
```
npm install -g mcp-openapi-schema-explorer
```
Consulte el Método 3 a continuación para configurar su cliente MCP para usar un servidor instalado globalmente.
Desarrollo/Instalación Local: Puede clonar el repositorio y compilarlo localmente:
```
git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
cd mcp-openapi-schema-explorer
npm install
npm run build
```
Consulte el Método 4 a continuación para configurar su cliente MCP para ejecutar el servidor desde su compilación local usando node.

Agregar el Servidor a su Cliente MCP

Este servidor está diseñado para ser ejecutado por clientes MCP (como Claude Desktop, Windsurf, Cline, etc.). Para usarlo, agrega una entrada de configuración al archivo de configuración de su cliente (a menudo un archivo JSON). Esta entrada le indica al cliente cómo ejecutar el proceso del servidor (por ejemplo, usando npx, docker o node). El servidor en sí no requiere configuración adicional más allá de los argumentos de línea de comandos especificados en la entrada de configuración del cliente.

A continuación se presentan los métodos comunes para agregar la entrada del servidor a la configuración de su cliente.

Método 1: npx (Recomendado)

Se recomienda usar npx ya que evita la instalación global/local y garantiza que el cliente use la última versión publicada.

Ejemplo de Entrada de Configuración del Cliente (Método npx):

Agregue el siguiente objeto JSON a la sección mcpServers del archivo de configuración de su cliente MCP. Esta entrada le indica al cliente cómo ejecutar el servidor usando npx:

{
  "mcpServers": {
    "My API Spec (npx)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-openapi-schema-explorer@latest",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

Notas de Configuración:

Reemplace "My API Spec (npx)" con un nombre único para esta instancia del servidor en su cliente.
Reemplace <path-or-url-to-spec> con la ruta de archivo local absoluta o la URL remota completa de su especificación.
--output-format es opcional (json, yaml, json-minified), con valor predeterminado json.
Para explorar múltiples especificaciones, agregue entradas separadas en mcpServers, cada una con un nombre único y apuntando a una especificación diferente.

Método 2: Docker

Puede indicar a su cliente MCP que ejecute el servidor usando la imagen oficial de Docker: kadykov/mcp-openapi-schema-explorer.

Ejemplo de Entradas de Configuración del Cliente (Método Docker):

Agregue uno de los siguientes objetos JSON a la sección mcpServers del archivo de configuración de su cliente MCP. Estas entradas le indican al cliente cómo ejecutar el servidor usando docker run:

URL Remota: Pase la URL directamente a docker run.

Usando una URL Remota:

{
  "mcpServers": {
    "My API Spec (Docker Remote)": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "kadykov/mcp-openapi-schema-explorer:latest",
        "<remote-url-to-spec>"
      ],
      "env": {}
    }
  }
}

Usando un Archivo Local: (Requiere montar el archivo en el contenedor)

{
  "mcpServers": {
    "My API Spec (Docker Local)": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/full/host/path/to/spec.yaml:/spec/api.yaml",
        "kadykov/mcp-openapi-schema-explorer:latest",
        "/spec/api.yaml",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

Importante: Reemplace /full/host/path/to/spec.yaml con la ruta absoluta correcta en su máquina host. La ruta /spec/api.yaml es la ruta correspondiente dentro del contenedor.

Método 3: Instalación Global (Menos Común)

Si ha instalado el paquete globalmente usando npm install -g, puede configurar su cliente para ejecutarlo directamente.

# Run this command once in your terminal
npm install -g mcp-openapi-schema-explorer

Ejemplo de Entrada de Configuración del Cliente (Método de Instalación Global):

Agregue la siguiente entrada al archivo de configuración de su cliente MCP. Esto asume que el comando mcp-openapi-schema-explorer es accesible en el PATH del entorno de ejecución del cliente.

{
  "mcpServers": {
    "My API Spec (Global)": {
      "command": "mcp-openapi-schema-explorer",
      "args": ["<path-or-url-to-spec>", "--output-format", "yaml"],
      "env": {}
    }
  }
}

Asegúrese de que command (mcp-openapi-schema-explorer) sea accesible en la variable de entorno PATH utilizada por su cliente MCP.

Método 4: Desarrollo/Instalación Local

Este método es útil si ha clonado el repositorio localmente para desarrollo o para ejecutar una versión modificada.

Pasos de Configuración (Ejecutar una vez en su terminal):

Clone el repositorio: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
Navegue al directorio: cd mcp-openapi-schema-explorer
Instale las dependencias: npm install
Compile el proyecto: npm run build (o just build)

Ejemplo de Entrada de Configuración del Cliente (Método de Desarrollo Local):

Agregue la siguiente entrada al archivo de configuración de su cliente MCP. Esto le indica al cliente que ejecute el servidor compilado localmente usando node.

{
  "mcpServers": {
    "My API Spec (Local Dev)": {
      "command": "node",
      "args": [
        "/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],

      "env": {}
    }
  }
}

Importante: Reemplace /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js con la ruta absoluta correcta al archivo index.js compilado en su repositorio clonado.

Características

Acceso a Plantillas de Recursos MCP: Explore especificaciones OpenAPI mediante plantillas URI parametrizadas (openapi://info, openapi://paths/{path}/{method}, openapi://components/{type}/{name}).
Soporte OpenAPI v3.0 y Swagger v2.0: Carga ambos formatos, convirtiendo automáticamente v2.0 a v3.0.
Archivos Locales y Remotos: Cargue especificaciones desde rutas de archivos locales o URLs HTTP/HTTPS.
Eficiente en Tokens: Diseñado para minimizar el uso de tokens para LLMs proporcionando acceso estructurado.
Múltiples Formatos de Salida: Obtenga vistas detalladas en JSON (predeterminado), YAML o JSON minificado (--output-format).
Nombre de Servidor Dinámico: El nombre del servidor en los clientes MCP refleja el info.title de la especificación cargada.
Transformación de Referencias: Los $ref internos (#/components/...) se transforman en URIs MCP clicables.

Recursos MCP Disponibles

Este servidor expone las siguientes plantillas de recursos MCP para explorar la especificación OpenAPI.

Importante: Este servidor proporciona plantillas de recursos, no recursos pre-enumerados. Cuando use un cliente MCP:

El cliente llama a resources/templates/list para descubrir los patrones de plantilla disponibles

Luego construye URIs específicos completando los parámetros de la plantilla (por ejemplo, reemplazando {path} con users%2F%7Bid%7D)

El cliente usa resources/read con su URI construido para obtener el contenido real

Si llama a resources/list (sin "templates"), obtendrá una lista vacía—este es el comportamiento esperado.

Comprensión de Parámetros Multi-Valor (*)

Algunas plantillas de recursos incluyen parámetros que terminan con un asterisco (*), como {method*} o {name*}. Esto indica que el parámetro acepta múltiples valores separados por comas. Por ejemplo, para solicitar detalles tanto para los métodos GET como POST de una ruta, usaría un URI como openapi://paths/users/get,post. Esto permite obtener detalles de múltiples elementos en una sola solicitud.

Plantillas de Recursos:

openapi://{field}
- Descripción: Accede a campos de nivel superior del documento OpenAPI (por ejemplo, info, servers, tags) o lista el contenido de paths o components. Los campos específicos disponibles dependen de la especificación cargada.
- Ejemplo: openapi://info
- Salida: Lista text/plain para paths y components; formato configurado (JSON/YAML/JSON minificado) para otros campos.
- Completaciones: Proporciona sugerencias dinámicas para {field} basadas en las claves de nivel superior reales encontradas en la especificación cargada.
openapi://paths/{path}
- Descripción: Lista los métodos HTTP (operaciones) disponibles para una ruta de API específica.
- Parámetro: {path} - La cadena de ruta de la API. Debe estar codificada en URL (por ejemplo, /users/{id} se convierte en users%2F%7Bid%7D).
- Ejemplo: openapi://paths/users%2F%7Bid%7D
- Salida: Lista text/plain de métodos.
- Completaciones: Proporciona sugerencias dinámicas para {path} basadas en las rutas encontradas en la especificación cargada (codificadas en URL).
openapi://paths/{path}/{method*}
- Descripción: Obtiene la especificación detallada de una o más operaciones (métodos HTTP) en una ruta de API específica.
- Parámetros:
  - {path} - La cadena de ruta de la API. Debe estar codificada en URL.
  - {method*} - Uno o más métodos HTTP (por ejemplo, get, post, get,post). No distingue entre mayúsculas y minúsculas.
- Ejemplo (Individual): openapi://paths/users%2F%7Bid%7D/get
- Ejemplo (Múltiple): openapi://paths/users%2F%7Bid%7D/get,post
- Salida: Formato configurado (JSON/YAML/JSON minificado).
- Completaciones: Proporciona sugerencias dinámicas para {path}. Proporciona sugerencias estáticas para {method*} (verbos HTTP comunes como GET, POST, PUT, DELETE, etc.).
openapi://components/{type}
- Descripción: Lista los nombres de todos los componentes definidos de un tipo específico (por ejemplo, schemas, responses, parameters). Los tipos específicos disponibles dependen de la especificación cargada. También proporciona una breve descripción para cada tipo listado.
- Ejemplo: openapi://components/schemas
- Salida: Lista text/plain de nombres de componentes con descripciones.
- Completaciones: Proporciona sugerencias dinámicas para {type} basadas en los tipos de componentes encontrados en la especificación cargada.
openapi://components/{type}/{name*}
- Descripción: Obtiene la especificación detallada de uno o más componentes nombrados de un tipo específico.
- Parámetros:
  - {type} - El tipo de componente.
  - {name*} - Uno o más nombres de componentes (p. ej., User, Order, User,Order). Distingue entre mayúsculas y minúsculas.
- Ejemplo (único): openapi://components/schemas/User
- Ejemplo (múltiple): openapi://components/schemas/User,Order
- Salida: Formato configurado (JSON/YAML/JSON minimizado).
- Completados: Proporciona sugerencias dinámicas para {type}. Proporciona sugerencias dinámicas para {name*} solo si la especificación cargada contiene exactamente un tipo de componente en general (p. ej., solo schemas). Esta limitación existe porque el SDK de MCP actualmente no admite proporcionar completados limitados al {type} seleccionado; proporcionar todos los nombres de todos los tipos podría ser engañoso.

Contribuciones

¡Las contribuciones son bienvenidas! Consulta el archivo CONTRIBUTING.md para obtener pautas sobre cómo configurar el entorno de desarrollo, ejecutar pruebas y enviar cambios.

Lanzamientos

Este proyecto utiliza semantic-release para la gestión automatizada de versiones y la publicación de paquetes basada en Conventional Commits.

Planes futuros

(Planes futuros por determinar)