OpenAPI al servidor MCP

Una herramienta que crea servidores MCP (Protocolo de Contexto de Modelo) a partir de las especificaciones de OpenAPI/Swagger, lo que permite que los asistentes de IA interactúen con tus API. Crea tus propios para API o servicios específicos.

Descripción general

Este proyecto crea un servidor MCP dinámico que transforma las especificaciones OpenAPI en herramientas MCP. Permite la integración fluida de las API REST con asistentes de IA mediante el Protocolo de Contexto de Modelo, convirtiendo cualquier API en una herramienta accesible para IA.

Características

• Carga dinámica de especificaciones OpenAPI desde archivos o URL HTTP/HTTPS

• Compatibilidad con superposiciones OpenAPI cargadas desde archivos o URL HTTP/HTTPS

• Mapeo personalizable de operaciones OpenAPI a herramientas MCP

• Filtrado avanzado de operaciones mediante patrones glob tanto para operationId como para rutas URL

• Manejo integral de parámetros con conservación de formato y metadatos de ubicación

• Manejo de autenticación de API

• Metadatos de OpenAPI (título, versión, descripción) utilizados para configurar el servidor MCP

• Alternativas de descripción jerárquica (descripción de la operación → resumen de la operación → resumen de la ruta)

• Compatibilidad con encabezados HTTP personalizados a través de variables de entorno y CLI

• Encabezado X-MCP para seguimiento e identificación de solicitudes de API

• Compatibilidad con extensiones x-mcp personalizadas en el nivel de ruta para anular los nombres y descripciones de las herramientas

Uso con asistentes de IA

Esta herramienta crea un servidor MCP que permite a los asistentes de IA interactuar con las API definidas por las especificaciones de OpenAPI. La principal forma de usarlo es configurar el asistente de IA para que se ejecute directamente como una herramienta MCP.

Configuración en Claude Desktop

1. Asegúrese de tener Node.js instalado en su computadora

2. Abra Claude Desktop y navegue a Configuración > Desarrollador

3. Edite el archivo de configuración (o se creará si no existe):

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Ventanas: %APPDATA%\Claude\claude_desktop_config.json

4. Agregue esta configuración (personalícela según sea necesario):

5. Reiniciar Claude Desktop

6. Ahora deberías ver un icono de martillo en el cuadro de entrada del chat. Haz clic en él para acceder a las herramientas de la API.

Personalización de la configuración

Puede ajustar la matriz args para personalizar su servidor MCP con varias opciones:

Configuración en el cursor

1. Cree un archivo de configuración en una de estas ubicaciones:

   • Específico del proyecto: .cursor/mcp.json en el directorio de su proyecto

   • Global: ~/.cursor/mcp.json en su directorio de inicio

2. Agregue esta configuración (ajústela según sea necesario para su API):

3. Reiniciar el cursor o recargar la ventana

Uso con Vercel AI SDK

También puede utilizar este servidor MCP directamente en sus aplicaciones JavaScript/TypeScript utilizando el cliente MCP del SDK de Vercel AI:

Configuración

La configuración se administra a través de variables de entorno, opciones de línea de comandos o un archivo de configuración JSON:

Opciones de línea de comandos

Variables de entorno

Puede configurarlos en un archivo .env o directamente en su entorno:

• OPENAPI_SPEC_PATH : Ruta al archivo de especificaciones de OpenAPI

• OPENAPI_OVERLAY_PATHS : Rutas separadas por comas para superponer archivos JSON

• TARGET_API_BASE_URL : URL base para llamadas API (anula los servidores OpenAPI)

• MCP_WHITELIST_OPERATIONS : Lista separada por comas de ID de operaciones o rutas URL para incluir (admite patrones glob como getPet* o GET:/pets/* )

• MCP_BLACKLIST_OPERATIONS : Lista separada por comas de ID de operaciones o rutas URL para excluir (admite patrones glob, se ignora si se usa una lista blanca)

• API_KEY : Clave API para la API de destino (si es necesario)

• SECURITY_SCHEME_NAME : Nombre del esquema de seguridad que requiere la clave API

• SECURITY_CREDENTIALS : cadena JSON que contiene credenciales de seguridad para múltiples esquemas

• CUSTOM_HEADERS : cadena JSON que contiene encabezados personalizados para incluir en todas las solicitudes de API

• HEADER_* : Cualquier variable de entorno que comience con HEADER_ se agregará como un encabezado personalizado (por ejemplo, HEADER_X_API_Version=1.0.0 agrega el encabezado X-API-Version: 1.0.0 )

• DISABLE_X_MCP : Establézcalo como true para deshabilitar la adición del encabezado X-MCP: 1 a todas las solicitudes de API

• CONFIG_FILE : Ruta a un archivo de configuración JSON

Configuración JSON

También puede usar un archivo de configuración JSON en lugar de variables de entorno u opciones de línea de comandos. El servidor MCP buscará los archivos de configuración en el siguiente orden:

1. Ruta especificada por la opción de línea de comandos --config

2. Ruta especificada por la variable de entorno CONFIG_FILE

3. config.json en el directorio actual

4. openapi-mcp.json en el directorio actual

5. .openapi-mcp.json en el directorio actual

Ejemplo de archivo de configuración JSON:

Un archivo de configuración de ejemplo completo con comentarios explicativos está disponible en config.example.json en el directorio raíz.

Precedencia de configuración

Los ajustes de configuración se aplican en el siguiente orden de precedencia (de mayor a menor):

1. Opciones de línea de comandos

2. Variables de entorno

3. Archivo de configuración JSON

Desarrollo

Instalación

Pruebas locales

Personalizar y publicar su propia versión

Puedes usar este repositorio como base para crear tu propio servidor OpenAPI a MCP personalizado. Esta sección explica cómo bifurcar el repositorio, personalizarlo para tus API específicas y publicarlo como paquete.

Bifurcación y personalización

1. Bifurcar el repositorio : bifurca este repositorio en GitHub para crear tu propia copia que puedas personalizar.

2. Agregue sus especificaciones OpenAPI :

   # Create a specs directory if it doesn't exist mkdir -p specs # Add your OpenAPI specifications cp path/to/your/openapi-spec.json specs/ # Add any overlay files cp path/to/your/overlay.json specs/

3. Configurar ajustes predeterminados : Cree un archivo de configuración personalizado que se incluirá con su paquete:

   # Copy the example config cp config.example.json config.json # Edit the config to point to your bundled specs # and set any default settings

4. Actualizar package.json :

   { "name": "your-custom-mcp-server", "version": "1.0.0", "description": "Your customized MCP server for specific APIs", "files": [ "dist/**/*", "config.json", "specs/**/*", "README.md" ] }

5. Asegúrese de que las especificaciones estén incluidas : el campo files en package.json (que se muestra arriba) garantiza que sus especificaciones y archivo de configuración se incluirán en el paquete publicado.

Personalizar el flujo de trabajo de GitHub

El repositorio incluye un flujo de trabajo de GitHub Actions para la publicación automática en npm. Para personalizarlo para tu repositorio bifurcado:

1. Actualizar el nombre del flujo de trabajo : edite .github/workflows/publish-npm.yaml para actualizar el nombre si lo desea:

   name: Publish My Custom MCP Package

2. Establecer el alcance del paquete (si es necesario) : si desea publicar bajo un alcance de organización npm, descomente y modifique la línea de alcance en el archivo de flujo de trabajo:

   - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: "18" registry-url: "https://registry.npmjs.org/" # Uncomment and update with your organization scope: scope: "@your-org"

3. Configurar el token npm : agregue su token npm como un secreto de GitHub llamado NPM_TOKEN en la configuración de su repositorio bifurcado.

Publicación de su paquete personalizado

Una vez que haya personalizado el repositorio:

1. Crear y enviar una etiqueta :

   # Update version in package.json (optional, the workflow will update it based on the tag) npm version 1.0.0 # Push the tag git push --tags

2. Las acciones de GitHub harán lo siguiente:

   • Construir automáticamente el paquete

   • Actualizar la versión en package.json para que coincida con la etiqueta

   • Publique en npm con sus especificaciones y configuración incluidas

Uso después de la publicación

Los usuarios de su paquete personalizado pueden instalarlo y usarlo con npm:

Pueden anular su configuración predeterminada a través de variables de entorno u opciones de línea de comando como se describe en la sección Configuración.

Licencia

Instituto Tecnológico de Massachusetts (MIT)