openapi-to-mcp

Expor endpoints de API como ferramentas fortemente tipadas a partir de uma especificação OpenAPI. Suporta OpenAPI 2.0/3.0 nos formatos JSON ou YAML, de arquivos locais ou remotos.

GitHub
34
Experimente este MCPPatrocinado

Documentação

.NET Build NuGet

openapi-to-mcp

Use sua especificação OpenAPI para expor os endpoints da sua API como ferramentas fortemente tipadas.

Exemplo básico para https://petstore3.swagger.io/ 🎉

{
  "mcpServers": {
    "petstore": {
      "command": "openapi-to-mcp",
        "args": [
          "https://petstore3.swagger.io/api/v3/openapi.json"
        ]
    }
  }
}

Exemplo mais complexo, usando a API do Github:

{
    "mcpServers": {
        "github": {
            "command": "openapi-to-mcp",
            "args": [
                "https://raw.githubusercontent.com/github/rest-api-description/refs/heads/main/descriptions/api.github.com/api.github.com.yaml",
                "--bearer-token",
                "github_pat_xxxxxx",
                "--tool-naming-strategy",
                "verbandpath"
            ]
        }
    }
}

Este exemplo usa a autenticação por token bearer (com um Token de Acesso Pessoal do Github) e força a estratégia de nomenclatura de ferramentas para "verbo e caminho", pois os ids de operação do Github não são nomes de ferramentas válidos.

Github demo

Instalação

Como ferramenta Nuget: openapi-to-mcp

dotnet tool install --global openapi-to-mcp

Ou baixe os executáveis das versões

Uso

Usage:
  openapi-to-mcp <open-api> [options]

Arguments:
  <open-api>  You OpenAPI specification (URL or file) [required]

Options:
  -t, --tool-naming-strategy <extension|extension_or_operationid_or_verbandpath|operationid|verbandpath>  How the tool name should be computed [default: extension_or_operationid_or_verbandpath]
  -h, --host-override                                                                                     Host override
  -b, --bearer-token                                                                                      Bearer token
  -o2, --oauth-2-grant-type <client_credentials|password|refresh_token>                                   OAuth2 flow to be used
  -o2_tu, --oauth-2-token-url                                                                             OAuth2 token endpoint URL (override the one defined in your OpenAPI for your chosen OAuth2 flow)
  -o2_ci, --oauth-2-client-id                                                                             OAuth2 client id (for the client_credentials grant_type)
  -o2_cs, --oauth-2-client-secret                                                                         OAuth2 client secret (for the client_credentials grant_type)
  -o2_rt, --oauth-2-refresh-token                                                                         OAuth2 refresh token (for the refresh_token grant_type)
  -o2_un, --oauth-2-username                                                                              OAuth2 username (for the password grant_type)
  -o2_pw, --oauth-2-password                                                                              OAuth2 password (for the password grant_type)
  -i, --instructions                                                                                      MCP instruction to be advertised by the server
  --verbose                                                                                               Log more info (in sdterr) [default: False]
  -?, -h, --help                                                                                          Show help and usage information
  --version                                                                                               Show version information

Suporte a OpenAPI

  • Atualmente, OpenAPI 2.0 e 3.0 são suportados.
  • As especificações podem ser JSON/YAML e locais (arquivo) ou remotas (URL)
  • Apenas $refs locais são suportados

Extensões personalizadas do OpenAPI

Um conjunto de extensões personalizadas está disponível para personalizar como sua API deve ser exposta:

  • info.x-mcp-instructions (string): Instruções textuais expostas pelo servidor MCP durante o handshake de inicialização
  • operation.x-mcp-tool-name (string): Nome personalizado da ferramenta
  • operation.x-mcp-tool-description (string): Descrição personalizada da ferramenta
  • operation.x-mcp-tool-enabled (boolean): Habilita/desabilita uma operação específica (habilitada por padrão)

Recursos do MCP

Apenas o transporte STDIO é suportado atualmente.

Ferramentas

Operações ("endpoints") da sua especificação OpenAPI são traduzidas para ferramentas do MCP

  • Todos os parâmetros de caminho/consulta/corpo JSON são expostos (usando seu esquema JSON)
  • A resposta é retornada como está
  • Por padrão, o nome da ferramenta é calculado usando primeiro a extensão operation.x-mcp-tool-name, depois o operation.operationId e depois {httpMethod}_{escaped_path}
    • A estratégia de nomenclatura de ferramentas pode ser definida através da opção --tool-naming-strategy.
    • ⚠️As ferramentas são descartadas se seus nomes não corresponderem a ^[a-zA-Z0-9_-]{1,64}$
  • As descrições das ferramentas são extraídas da seguinte forma: operation.x-mcp-tool-description ?? operation.description ?? path.description

Chamada de ferramenta e host

Quando uma ferramenta é chamada, o servidor MCP chamará o endpoint subjacente. Para determinar qual host chamar, uma combinação de parâmetros é usada:

  • a opção --host-override
  • a URL do primeiro servidor da sua especificação, se for uma URL absoluta
  • o host do OpenAPI remoto fornecido
  • caso contrário, um erro é lançado

Por exemplo, executando openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json:

Autorização

Token bearer

Um token pode ser fornecido como opção --bearer-token. Ele será fornecido a todas as chamadas como o cabeçalho Authorization: Bearer {token}. Ele também será fornecido ao buscar uma especificação remota.

OAuth2

ClientCredentials, RefreshToken e Password são suportados. Se sua especificação OpenAPI declarar securitySchemes para esses fluxos, o tokenUrl correspondente será usado.

Como publicar

Crie uma nova tag/release 🤷