OpenAPI Schema Explorer

Explorador de esquemas OpenAPI de MCP

Un servidor MCP (Protocolo de contexto de modelo) que proporciona acceso eficiente en términos de tokens a las especificaciones OpenAPI (v3.0) y Swagger (v2.0) a través 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 extensas 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 Recursos MCP, ideales para la exploración de datos de solo lectura.

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

¿Por qué MCP Resources?

El Protocolo de Contexto Modelo define tanto Recursos como Herramientas .

• Recursos: Representan fuentes de datos (como archivos y respuestas de API). Son ideales para el acceso de solo lectura y la exploración por parte de clientes de MCP (p. ej., al explorar rutas de API en Claude Desktop).
• Herramientas: representan acciones o funciones ejecutables, a menudo utilizadas por los LLM para realizar tareas o interactuar con sistemas externos.

Aunque existen otros servidores MCP que proporcionan acceso a las especificaciones de OpenAPI mediante Herramientas , este proyecto se centra específicamente en proporcionar acceso mediante Recursos . Esto lo hace especialmente útil para la exploración directa dentro de las aplicaciones cliente MCP.

Para obtener más detalles sobre los clientes MCP y sus capacidades, consulte la Documentación del cliente MCP .

Instalación

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

Sin embargo, si prefieres o necesitas instalar el servidor explícitamente, tienes dos opciones:

1. Instalación global: puedes instalar el paquete globalmente usando npm:
   npm install -g mcp-openapi-schema-explorer
   Consulte el método 3 a continuación para saber cómo configurar su cliente MCP para utilizar un servidor instalado globalmente.
2. Desarrollo/Instalación local: puedes 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 saber cómo configurar su cliente MCP para ejecutar el servidor desde su compilación local usando node .

Cómo 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, se agrega una entrada de configuración al archivo de configuración del cliente (generalmente un archivo JSON). Esta entrada 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 la línea de comandos especificados en la entrada de configuración del cliente.

A continuación se muestran 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 utilice la última versión publicada.

Ejemplo de entrada de configuración de 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 indica al cliente cómo ejecutar el servidor usando npx :

Notas de configuración:

• Reemplace "My API Spec (npx)" con un nombre único para esta instancia de 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.
• El --output-format es opcional ( json , yaml , json-minified ) y el valor predeterminado es json .
• Para explorar múltiples especificaciones, agregue entradas separadas en mcpServers , cada una con un nombre único y que apunte a una especificación diferente.

Método 2: Docker

Puede indicarle 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 de 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 indican al cliente cómo ejecutar el servidor mediante docker run :

• URL remota: pasa 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": {} } } }
• Uso de 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 equipo 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.

Ejemplo de entrada de configuración de cliente (método de instalación global):

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

• Asegúrese de que el 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):

1. Clonar el repositorio: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. Navegue al directorio: cd mcp-openapi-schema-explorer
3. Instalar dependencias: npm install
4. Construya el proyecto: npm run build (o just build )

Ejemplo de entrada de configuración de cliente (método de desarrollo local):

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

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

Características

• Acceso a recursos de MCP: explore las especificaciones de OpenAPI a través de URI intuitivos ( openapi://info , openapi://paths/... , openapi://components/... ).
• Compatibilidad con OpenAPI v3.0 y Swagger v2.0: carga ambos formatos y convierte automáticamente v2.0 a v3.0.
• Archivos locales y remotos: cargue especificaciones desde rutas de archivos locales o URL HTTP/HTTPS.
• Uso eficiente de tokens: diseñado para minimizar el uso de tokens para LLM al proporcionar acceso estructurado.
• Múltiples formatos de salida: obtenga vistas detalladas en JSON (predeterminado), YAML o JSON minimizado ( --output-format ).
• Nombre del servidor dinámico: el nombre del servidor en los clientes MCP refleja el info.title de la especificación cargada.
• Transformación de referencia: $ref internas ( #/components/... ) se transforman en URI de MCP en los que se puede hacer clic.

Recursos MCP disponibles

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

Comprensión de los parámetros multivalor ( * )

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

Plantillas de recursos:

• openapi://{field}
  • Descripción: Accede a los campos de nivel superior del documento OpenAPI (p. ej., 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 minimizado) para otros campos.
  • Compleciones: proporciona sugerencias dinámicas para {field} en función de las claves de nivel superior reales que se encuentran en la especificación cargada.
• openapi://paths/{path}
  • Descripción: enumera los métodos HTTP (operaciones) disponibles para una ruta API específica.
  • Parámetro: {path} - La cadena de ruta de la API. Debe estar codificada como URL (p. ej., /users/{id} se convierte en users/{id} ).
  • Ejemplo: openapi://paths/users/{id}
  • Salida: lista de métodos text/plain .
  • Compleciones: proporciona sugerencias dinámicas para {path} en función de las rutas encontradas en la especificación cargada (codificada 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 API específica.
  • Parámetros:
    • {path} - La cadena de ruta de la API. Debe estar codificada como URL .
    • {method*} - Uno o más métodos HTTP (p. ej., get , post , get,post ). No distingue entre mayúsculas y minúsculas.
  • Ejemplo (único): openapi://paths/users/{id}/get
  • Ejemplo (múltiple): openapi://paths/users/{id}/get,post
  • Salida: Formato configurado (JSON/YAML/JSON minimizado).
  • Compleciones: Ofrece sugerencias dinámicas para {path} . Ofrece sugerencias estáticas para {method*} (verbos HTTP comunes como GET, POST, PUT, DELETE, etc.).
• openapi://components/{type}
  • Descripción: Enumera los nombres de todos los componentes definidos de un tipo específico (p. ej., schemas , responses , parameters ). Los tipos específicos disponibles dependen de la especificación cargada. También proporciona una breve descripción de cada tipo listado.
  • Ejemplo: openapi://components/schemas
  • Salida: lista text/plain de nombres de componentes con descripciones.
  • Compleciones: proporciona sugerencias dinámicas para {type} en función de 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).
  • Compleciones: Proporciona sugerencias dinámicas para {type} . Proporciona sugerencias dinámicas para {name*}solo si la especificación cargada contiene exactamente un tipo de componente (p. ej., solo schemas ). Esta limitación existe porque el SDK de MCP actualmente no permite proporcionar compleciones con el alcance del {type} seleccionado; proporcionar todos los nombres de todos los tipos podría ser engañoso.

Contribuyendo

¡Agradecemos sus contribuciones! Consulte el archivo CONTRIBUTING.md para obtener instrucciones 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 confirmaciones convencionales .

Planes futuros

(Planes futuros por determinar)