OpenAPI to MCP Server

Uma ferramenta para criar servidores MCP a partir de especificações OpenAPI/Swagger, permitindo que assistentes de IA interajam com suas APIs.

GitHub
49
Experimente este MCPPatrocinado

Documentação

Servidor OpenAPI para MCP

Uma ferramenta que cria servidores MCP (Model Context Protocol) a partir de especificações OpenAPI/Swagger, permitindo que assistentes de IA interajam com suas APIs. Crie seus próprios MCPs personalizados e com marca para APIs ou serviços específicos.

Visão Geral

Este projeto cria um servidor MCP dinâmico que transforma especificações OpenAPI em ferramentas MCP. Ele permite a integração perfeita de APIs REST com assistentes de IA por meio do Model Context Protocol, transformando qualquer API em uma ferramenta acessível por IA.

Recursos

  • Carregamento dinâmico de especificações OpenAPI a partir de arquivos ou URLs HTTP/HTTPS
  • Suporte para OpenAPI Overlays carregados de arquivos ou URLs HTTP/HTTPS
  • Mapeamento personalizável de operações OpenAPI para ferramentas MCP
  • Filtragem avançada de operações usando padrões glob tanto para operationId quanto para caminhos de URL
  • Tratamento abrangente de parâmetros com preservação de formato e metadados de localização
  • Tratamento de autenticação de API
  • Metadados OpenAPI (título, versão, descrição) usados para configurar o servidor MCP
  • Fallbacks hierárquicos de descrição (descrição da operação → resumo da operação → resumo do caminho)
  • Suporte a cabeçalhos HTTP personalizados via variáveis de ambiente e CLI
  • Cabeçalho X-MCP para rastreamento e identificação de solicitações de API
  • Suporte para extensões personalizadas x-mcp no nível do caminho para substituir nomes e descrições de ferramentas

Usando com Assistentes de IA

Esta ferramenta cria um servidor MCP que permite que assistentes de IA interajam com APIs definidas por especificações OpenAPI. A principal forma de uso é configurando seu assistente de IA para executá-lo diretamente como uma ferramenta MCP.

Configuração no Claude Desktop

  1. Certifique-se de ter o Node.js instalado no seu computador

  2. Abra o Claude Desktop e navegue até Configurações > Desenvolvedor

  3. Edite o arquivo de configuração (ou ele será criado se não existir):

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  4. Adicione esta configuração (personalize conforme necessário):

{
  "mcpServers": {
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp@latest",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ],
      "enabled": true
    }
  }
}
  1. Reinicie o Claude Desktop
  2. Agora você deve ver um ícone de martelo na caixa de entrada de chat. Clique nele para acessar suas ferramentas de API.

Personalizando a Configuração

Você pode ajustar o array args para personalizar seu servidor MCP com várias opções:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp@latest",
        "--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
    }
  }
}

Configuração no Cursor

  1. Crie um arquivo de configuração em um destes locais:

    • Específico do projeto: .cursor/mcp.json no diretório do seu projeto
    • Global: ~/.cursor/mcp.json no seu diretório pessoal

  2. Adicione esta configuração (ajuste conforme necessário para sua API):

{
  "servers": [
    {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp@latest",
        "--spec",
        "./path/to/your/openapi.json"
      ],
      "name": "My API Tools"
    }
  ]
}
  1. Reinicie o Cursor ou recarregue a janela

Usando com o Vercel AI SDK

Você também pode usar este servidor MCP diretamente em suas aplicações JavaScript/TypeScript usando o cliente MCP do Vercel AI SDK:

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();

Configuração

A configuração é gerenciada por meio de variáveis de ambiente, opções de linha de comando ou um arquivo de configuração JSON:

Opções de Linha de Comando

# 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

Variáveis de Ambiente

Você pode defini-las em um arquivo .env ou diretamente no seu ambiente:

  • OPENAPI_SPEC_PATH: Caminho para o arquivo de especificação OpenAPI
  • OPENAPI_OVERLAY_PATHS: Caminhos separados por vírgula para arquivos JSON de overlay
  • TARGET_API_BASE_URL: URL base para chamadas de API (substitui os servidores OpenAPI)
  • MCP_WHITELIST_OPERATIONS: Lista separada por vírgulas de IDs de operação ou caminhos de URL a incluir (suporta padrões glob como getPet* ou GET:/pets/*)
  • MCP_BLACKLIST_OPERATIONS: Lista separada por vírgulas de IDs de operação ou caminhos de URL a excluir (suporta padrões glob, ignorado se a lista de permissões for usada)
  • API_KEY: Chave de API para a API de destino (se necessário)
  • SECURITY_SCHEME_NAME: Nome do esquema de segurança que requer a Chave de API
  • SECURITY_CREDENTIALS: String JSON contendo credenciais de segurança para múltiplos esquemas
  • CUSTOM_HEADERS: String JSON contendo cabeçalhos personalizados para incluir em todas as solicitações de API
  • HEADER_*: Qualquer variável de ambiente que comece com HEADER_ será adicionada como cabeçalho personalizado (por exemplo, HEADER_X_API_Version=1.0.0 adiciona o cabeçalho X-API-Version: 1.0.0)
  • DISABLE_X_MCP: Defina como true para desativar a adição do cabeçalho X-MCP: 1 a todas as solicitações de API
  • CONFIG_FILE: Caminho para um arquivo de configuração JSON

Configuração JSON

Você também pode usar um arquivo de configuração JSON em vez de variáveis de ambiente ou opções de linha de comando. O servidor MCP procurará arquivos de configuração na seguinte ordem:

  1. Caminho especificado pela opção de linha de comando --config
  2. Caminho especificado pela variável de ambiente CONFIG_FILE
  3. config.json no diretório atual
  4. openapi-mcp.json no diretório atual
  5. .openapi-mcp.json no diretório atual

Exemplo de arquivo de configuração 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
}

Um exemplo completo de arquivo de configuração com comentários explicativos está disponível em config.example.json no diretório raiz.

Precedência de Configuração

As configurações são aplicadas na seguinte ordem de precedência (da maior para a menor):

  1. Opções de linha de comando
  2. Variáveis de ambiente
  3. Arquivo de configuração JSON

Desenvolvimento

Instalação

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

# Install dependencies
npm install

# Build the project
npm run build

Testes Locais

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

Personalizando e Publicando Sua Própria Versão

Você pode usar este repositório como base para criar seu próprio servidor OpenAPI para MCP personalizado. Esta seção explica como fazer um fork do repositório, personalizá-lo para suas APIs específicas e publicá-lo como um pacote.

Fazendo Fork e Personalizando

  1. Faça um Fork do Repositório: Faça um fork deste repositório no GitHub para criar sua própria cópia que você pode personalizar.

  2. Adicione Suas Especificações 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. Configure as Configurações Padrão: Crie um arquivo de configuração personalizado que será incluído no seu pacote:

    # 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. Atualize o 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. Garanta que as Especificações Estejam Incluídas: O campo files no package.json (mostrado acima) garante que suas especificações e arquivo de configuração serão incluídos no pacote publicado.

Personalizando o Workflow do GitHub

O repositório inclui um workflow do GitHub Actions para publicação automática no npm. Para personalizá-lo para seu repositório com fork:

  1. Atualize o Nome do Workflow: Edite .github/workflows/publish-npm.yaml para atualizar o nome, se desejado:

    name: Publish My Custom MCP Package

  2. Defina o Escopo do Pacote (se necessário): Se você quiser publicar sob um escopo de organização npm, descomente e modifique a linha de escopo no arquivo de workflow:

    - 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. Configure o Token npm: Adicione seu token npm como um segredo do GitHub chamado NPM_TOKEN nas configurações do seu repositório com fork.

Publicando Seu Pacote Personalizado

Depois de personalizar o repositório:

  1. Crie e Envie uma Tag:

    # 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. O GitHub Actions irá:

    • Compilar automaticamente o pacote
    • Atualizar a versão no package.json para corresponder à tag
    • Publicar no npm com suas especificações e configuração incluídas

Uso Após a Publicação

Os usuários do seu pacote personalizado podem instalá-lo e usá-lo com npm:

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

# Run it
your-custom-mcp-server

Eles podem substituir suas configurações padrão por meio de variáveis de ambiente ou opções de linha de comando, conforme descrito na seção Configuração.

Licença

MIT