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 MCP personalizados y con tu marca 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.

Related MCP server: Swagger MCP

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

{
  "mcpServers": {
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ],
      "enabled": true
    }
  }
}

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:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json",
        "--overlays",
        "./path/to/overlay.json,https://example.com/api/overlay.json",
        "--whitelist",
        "getPet*,POST:/users/*",
        "--targetUrl",
        "https://api.example.com"
      ],
      "enabled": true
    }
  }
}

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

{
  "servers": [
    {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json"
      ],
      "name": "My API Tools"
    }
  ]
}

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:

import { experimental_createMCPClient } from 'ai';
import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
import { generateText } from 'ai';
import { createGoogleGenerativeAI } from '@ai-sdk/google';

// Initialize the Google Generative AI provider
const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_API_KEY, // Set your API key in environment variables
});
const model = google('gemini-2.0-flash');

// Create an MCP client with stdio transport
const mcpClient = await experimental_createMCPClient({
  transport: {
    type: 'stdio',
    command: 'npx', // Command to run the MCP server
    args: ['-y', '@tyk-technologies/api-to-mcp', '--spec', 'https://petstore3.swagger.io/api/v3/openapi.json'], // OpenAPI spec
    env: {
      // You can set environment variables here
      // API_KEY: process.env.YOUR_API_KEY,
    },
  },
});

async function main() {
  try {
    // Retrieve tools from the MCP server
    const tools = await mcpClient.tools();

    // Generate text using the AI SDK with MCP tools
    const { text } = await generateText({
      model,
      prompt: 'List all available pets in the pet store using the API.',
      tools, // Pass the MCP tools to the model
    });

    console.log('Generated text:', text);
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Always close the MCP client to release resources
    await mcpClient.close();
  }
}

main();

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

# Start with specific OpenAPI spec file
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json

# Apply overlays to the spec
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --overlays=./path/to/overlay.json,https://example.com/api/overlay.json

# Include only specific operations (supports glob patterns)
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"

# Specify target API URL
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --targetUrl=https://api.example.com

# Add custom headers to all API requests
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --headers='{"X-Api-Version":"1.0.0"}'

# Disable the X-MCP header
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --disableXMcp

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:

{
  "spec": "./path/to/openapi-spec.json",
  "overlays": "./path/to/overlay1.json,https://example.com/api/overlay.json",
  "targetUrl": "https://api.example.com",
  "whitelist": "getPets,createPet,/pets/*",
  "blacklist": "deletePet,/admin/*",
  "apiKey": "your-api-key",
  "securitySchemeName": "ApiKeyAuth",
  "securityCredentials": {
    "ApiKeyAuth": "your-api-key",
    "OAuth2": "your-oauth-token"
  },
  "headers": {
    "X-Custom-Header": "custom-value",
    "User-Agent": "OpenAPI-MCP-Client/1.0"
  },
  "disableXMcp": false
}

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

# Clone the repository
git clone <repository-url>
cd openapi-to-mcp-generator

# Install dependencies
npm install

# Build the project
npm run build

Pruebas locales

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

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:

# Install your customized package
npm install your-custom-mcp-server -g

# Run it
your-custom-mcp-server

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)