Swagger MCP

swagger-mcp

Visão Geral

swagger-mcp é uma ferramenta que lê uma especificação Swagger 2.0 ou OpenAPI 3.0 e gera dinamicamente ferramentas MCP em tempo de execução — uma ferramenta por endpoint de API. Essas ferramentas podem ser usadas por qualquer cliente MCP para interação com APIs orientada por LLM.

Formatos de especificação suportados:

• Swagger 2.0 (swagger: "2.0") — parâmetros de path/query/header e corpos de requisição in: body
• OpenAPI 3.0 (openapi: "3.0.x") — parâmetros de path/query/header e requestBody com esquemas inline ou $ref

Campos obrigatórios e opcionais são lidos do array required do esquema e respeitados nas definições de ferramentas geradas.

📽️ Vídeo de Demonstração

Confira o vídeo de demonstração mostrando o projeto em ação:

🙌 Suporte

Se você acha este projeto valioso, por favor me apoie no LinkedIn:

• 👍 Curtindo e compartilhando nossa postagem de demonstração
• 💬 Deixando seus pensamentos e feedback nos comentários
• 🔗 Conectando-se comigo para atualizações futuras

Seu apoio no LinkedIn me ajudará a alcançar mais pessoas e melhorar o projeto!

Pré-requisitos

Para usar swagger-mcp, certifique-se de ter as seguintes dependências:

1. Chave de API do Modelo LLM / LLM Local: Requer acesso aos modelos OpenAI, Claude ou Ollama.
2. Qualquer Cliente MCP: (Usado mark3labs - mcphost)

Instalação e Configuração

go install github.com/danishjsheikh/swagger-mcp@latest

Configuração de Execução

Modo Stdio (padrão)

swagger-mcp --specUrl=https://your_swagger_api_docs.json

Modo SSE

swagger-mcp --specUrl=https://your_swagger_api_docs.json --sse --sseAddr=:8080

Modo StreamableHTTP

swagger-mcp --specUrl=https://your_swagger_api_docs.json --http --httpAddr=:8080

Todas as flags

Flag	Descrição
--specUrl	URL ou caminho file:// da especificação JSON Swagger/OpenAPI (obrigatório)
--baseUrl	Substituir a URL base para requisições de API
--sse	Executar em modo SSE em vez de stdio
--sseAddr	Endereço de escuta SSE, :Port ou IP:Port
--sseUrl	URL base SSE (derivada automaticamente de --sseAddr se omitida)
--sseHeaders	Cabeçalhos de requisição separados por vírgula para encaminhar de SSE para API (ex.: Authorization,X-Tenant)
--http	Executar em modo StreamableHTTP em vez de stdio
--httpAddr	Endereço de escuta StreamableHTTP, :Port ou IP:Port
--httpPath	Caminho do endpoint StreamableHTTP (padrão /mcp)
--httpHeaders	Cabeçalhos de requisição separados por vírgula para encaminhar de HTTP para API
--includePaths	Caminhos ou padrões regex separados por vírgula para incluir
--excludePaths	Caminhos ou padrões regex separados por vírgula para excluir
--includeMethods	Métodos HTTP separados por vírgula para incluir (ex.: GET,POST)
--excludeMethods	Métodos HTTP separados por vírgula para excluir
--security	Tipo de autenticação: basic, bearer ou apiKey
--basicAuth	Credenciais de autenticação básica no formato user:password
--bearerAuth	Token Bearer para o cabeçalho Authorization
--apiKeyAuth	Chave(s) de API: passAs:name=value — passAs é header, query ou cookie; múltiplas entradas separadas por vírgula (ex.: header:token=abc,query:user=foo)
--headers	Cabeçalhos estáticos adicionais para cada requisição, name1=value1,name2=value2

Exemplo Xquik OpenAPI

A Xquik publica um documento OpenAPI remoto para sua API de automação X/Twitter. Como usa um cabeçalho de chave de API, passe a chave com --security=apiKey e --apiKeyAuth:

export XQUIK_API_KEY="your-xquik-api-key"

swagger-mcp \
  --specUrl=https://xquik.com/openapi.json \
  --baseUrl=https://xquik.com \
  --security=apiKey \
  --apiKeyAuth=header:x-api-key=$XQUIK_API_KEY

Os mesmos argumentos podem ser usados em uma configuração de cliente MCP:

{
  "mcpServers": {
    "xquik": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://xquik.com/openapi.json",
        "--baseUrl=https://xquik.com",
        "--security=apiKey",
        "--apiKeyAuth=header:x-api-key=<XQUIK_API_KEY>"
      ]
    }
  }
}

Configuração MCP

Para integrar com mcphost, inclua a seguinte configuração em .mcp.json:

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": ["--specUrl=<swagger/doc.json_url>"]
        }
    }
}

Com autenticação bearer e filtragem de caminho:

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": [
                "--specUrl=https://api.example.com/openapi.json",
                "--security=bearer",
                "--bearerAuth=your-token-here",
                "--includeMethods=GET,POST"
            ]
        }
    }
}

Suporte a Corpo de Requisição

Tanto corpos de requisição Swagger 2.0 quanto OpenAPI 3.0 são suportados:

• Swagger 2.0: parameters com in: body e um $ref ou esquema inline sob definitions
• OpenAPI 3.0: requestBody.content.<media-type>.schema — resolvido de components/schemas se houver um $ref, ou usado inline se for um esquema de objeto

Campos listados no array required do esquema são marcados como obrigatórios na ferramenta MCP. Todos os outros campos são opcionais e são omitidos da requisição se não forem fornecidos.

Fluxo de Demonstração

1. Algum Backend:

   go install github.com/danishjsheikh/go-backend-demo@latest 
   go-backend-demo
   

2. Ollama

   ollama run llama3.2
   

3. Cliente MCP

   go install github.com/mark3labs/mcphost@latest
   mcphost -m ollama:llama3.2 --config <.mcp.json_file_path>
   

Diagrama de Fluxo

🛠️ Precisa de Ajuda

Estou trabalhando em melhorar as definições de ferramentas para aprimorar:
✅ Melhor tratamento de erros para respostas mais precisas
✅ Controle de comportamento do LLM para garantir que ele dependa apenas das respostas da API e não use sua própria memória
✅ Prevenção de alucinações e geração de dados aleatórios impondo recuperação estrita de dados das APIs

Se você tem insights ou sugestões para melhorar esses aspectos, por favor contribua:

• Compartilhando sua experiência com implementações semelhantes
• Sugerindo modificações nas definições de ferramentas
• Fornecendo feedback sobre as limitações atuais

Sua contribuição será inestimável para tornar esta ferramenta mais confiável e eficaz! 🚀