OpenAPI Schema Explorer

Acesso eficiente em tokens a especificações OpenAPI/Swagger via Recursos MCP

GitHub
76
Experimente este MCPPatrocinado

Documentação

MCP OpenAPI Schema Explorer Logo

MCP OpenAPI Schema Explorer

npm version NPM Downloads Docker Pulls License: MIT codecov Verified on MseeP Trust Score Listed on Spark

Um servidor MCP (Model Context Protocol) que fornece acesso eficiente em termos de tokens a especificações OpenAPI (v3.0) e Swagger (v2.0) por meio de Modelos de Recursos MCP.

Objetivo do Projeto

O objetivo principal deste projeto é permitir que clientes MCP (como Cline ou Claude Desktop) explorem a estrutura e os detalhes de especificações OpenAPI grandes sem precisar carregar o arquivo inteiro na janela de contexto de um LLM. Isso é alcançado expondo partes da especificação por meio de Modelos de Recursos MCP, que fornecem padrões de acesso parametrizados para exploração de dados somente leitura.

Este servidor suporta o carregamento de especificações tanto de caminhos de arquivos locais quanto de URLs HTTP/HTTPS remotas. Especificações Swagger v2.0 são automaticamente convertidas para OpenAPI v3.0 ao serem carregadas.

Nota: Este servidor fornece modelos de recursos (não recursos pré-enumerados). Os clientes MCP acessam esses modelos por meio do método de protocolo resources/templates/list. Para mais informações sobre modelos de recursos, consulte a documentação de Modelos de Recursos MCP.

Por que Modelos de Recursos MCP?

O Model Context Protocol define tanto Recursos quanto Ferramentas.

  • Recursos: Representam fontes de dados (como arquivos, respostas de API). São ideais para acesso somente leitura e exploração por clientes MCP.
    • Modelos de Recursos: Um tipo especial de recurso que usa URIs parametrizados (ex.: openapi://paths/{path}/{method}), permitindo acesso dinâmico sem pré-enumerar todos os valores possíveis.
  • Ferramentas: Representam ações ou funções executáveis, frequentemente usadas por LLMs para realizar tarefas ou interagir com sistemas externos.

Embora existam outros servidores MCP que fornecem acesso a especificações OpenAPI via Ferramentas, este projeto se concentra especificamente em fornecer acesso via Modelos de Recursos. Essa abordagem é particularmente eficiente para APIs grandes porque:

  • Não requer pré-enumerar milhares de caminhos e componentes potenciais
  • Os clientes podem descobrir recursos disponíveis dinamicamente usando os padrões de modelo
  • Fornece acesso estruturado e sob demanda a partes específicas da especificação

Para mais detalhes sobre clientes MCP e suas capacidades, consulte a Documentação do Cliente MCP.

Guias de Início Rápido por Cliente

  • Claude Code - Ferramenta CLI da Anthropic para codificação com Claude
  • Claude Desktop, Cline, Windsurf - Veja as instruções de instalação abaixo

Instalação

Para os métodos de uso recomendados (npx e Docker, descritos abaixo), nenhuma etapa de instalação separada é necessária. Seu cliente MCP baixará o pacote ou puxará a imagem Docker automaticamente com base na configuração que você fornecer.

No entanto, se você preferir ou precisar instalar o servidor explicitamente, você tem duas opções:

  1. Instalação Global: Você pode instalar o pacote globalmente usando npm:

    npm install -g mcp-openapi-schema-explorer

    Veja o Método 3 abaixo para saber como configurar seu cliente MCP para usar um servidor instalado globalmente.

  2. Desenvolvimento/Instalação Local: Você pode clonar o repositório e compilá-lo localmente:

    git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
cd mcp-openapi-schema-explorer
npm install
npm run build

    Veja o Método 4 abaixo para saber como configurar seu cliente MCP para executar o servidor a partir da sua compilação local usando node.

Adicionando o Servidor ao seu Cliente MCP

Este servidor foi projetado para ser executado por clientes MCP (como Claude Desktop, Windsurf, Cline, etc.). Para usá-lo, você adiciona uma entrada de configuração ao arquivo de configurações do seu cliente (geralmente um arquivo JSON). Essa entrada informa ao cliente como executar o processo do servidor (ex.: usando npx, docker ou node). O servidor em si não requer configuração separada além dos argumentos de linha de comando especificados na entrada de configurações do cliente.

Abaixo estão os métodos comuns para adicionar a entrada do servidor à configuração do seu cliente.

Método 1: npx (Recomendado)

Usar npx é recomendado, pois evita instalação global/local e garante que o cliente use a versão publicada mais recente.

Exemplo de Entrada de Configuração do Cliente (Método npx):

Adicione o seguinte objeto JSON à seção mcpServers do arquivo de configuração do seu cliente MCP. Esta entrada instrui o cliente sobre como executar o servidor usando npx:

{
  "mcpServers": {
    "My API Spec (npx)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-openapi-schema-explorer@latest",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

Notas de Configuração:

  • Substitua "My API Spec (npx)" por um nome exclusivo para esta instância do servidor no seu cliente.
  • Substitua <path-or-url-to-spec> pelo caminho absoluto do arquivo local ou URL remota completa da sua especificação.
  • O --output-format é opcional (json, yaml, json-minified), com padrão json.
  • Para explorar múltiplas especificações, adicione entradas separadas em mcpServers, cada uma com um nome exclusivo e apontando para uma especificação diferente.

Método 2: Docker

Você pode instruir seu cliente MCP a executar o servidor usando a imagem Docker oficial: kadykov/mcp-openapi-schema-explorer.

Exemplo de Entradas de Configuração do Cliente (Método Docker):

Adicione um dos seguintes objetos JSON à seção mcpServers do arquivo de configuração do seu cliente MCP. Estas entradas instruem o cliente sobre como executar o servidor usando docker run:

  • URL Remota: Passe a URL diretamente para docker run.

  • Usando uma URL Remota:

    {
  "mcpServers": {
    "My API Spec (Docker Remote)": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "kadykov/mcp-openapi-schema-explorer:latest",
        "<remote-url-to-spec>"
      ],
      "env": {}
    }
  }
}

  • Usando um Arquivo Local: (Requer montar o arquivo no contêiner)

    {
  "mcpServers": {
    "My API Spec (Docker Local)": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/full/host/path/to/spec.yaml:/spec/api.yaml",
        "kadykov/mcp-openapi-schema-explorer:latest",
        "/spec/api.yaml",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

    Importante: Substitua /full/host/path/to/spec.yaml pelo caminho absoluto correto na sua máquina host. O caminho /spec/api.yaml é o caminho correspondente dentro do contêiner.

Método 3: Instalação Global (Menos Comum)

Se você instalou o pacote globalmente usando npm install -g, você pode configurar seu cliente para executá-lo diretamente.

# Run this command once in your terminal
npm install -g mcp-openapi-schema-explorer

Exemplo de Entrada de Configuração do Cliente (Método de Instalação Global):

Adicione a seguinte entrada ao arquivo de configuração do seu cliente MCP. Isso pressupõe que o comando mcp-openapi-schema-explorer esteja acessível no PATH do ambiente de execução do cliente.

{
  "mcpServers": {
    "My API Spec (Global)": {
      "command": "mcp-openapi-schema-explorer",
      "args": ["<path-or-url-to-spec>", "--output-format", "yaml"],
      "env": {}
    }
  }
}
  • Garanta que o command (mcp-openapi-schema-explorer) esteja acessível na variável de ambiente PATH usada pelo seu cliente MCP.

Método 4: Desenvolvimento/Instalação Local

Este método é útil se você clonou o repositório localmente para desenvolvimento ou para executar uma versão modificada.

Etapas de Configuração (Execute uma vez no seu terminal):

  1. Clone o repositório: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
  2. Navegue para o diretório: cd mcp-openapi-schema-explorer
  3. Instale as dependências: npm install
  4. Compile o projeto: npm run build (ou just build)

Exemplo de Entrada de Configuração do Cliente (Método de Desenvolvimento Local):

Adicione a seguinte entrada ao arquivo de configuração do seu cliente MCP. Isso instrui o cliente a executar o servidor compilado localmente usando node.

{
  "mcpServers": {
    "My API Spec (Local Dev)": {
      "command": "node",
      "args": [
        "/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],

      "env": {}
    }
  }
}

Importante: Substitua /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js pelo caminho absoluto correto para o arquivo index.js compilado no seu repositório clonado.

Recursos

  • Acesso a Modelos de Recursos MCP: Explore especificações OpenAPI via modelos de URI parametrizados (openapi://info, openapi://paths/{path}/{method}, openapi://components/{type}/{name}).
  • Suporte a OpenAPI v3.0 e Swagger v2.0: Carrega ambos os formatos, convertendo automaticamente v2.0 para v3.0.
  • Arquivos Locais e Remotos: Carrega especificações de caminhos de arquivos locais ou URLs HTTP/HTTPS.
  • Eficiente em Tokens: Projetado para minimizar o uso de tokens para LLMs, fornecendo acesso estruturado.
  • Múltiplos Formatos de Saída: Obtenha visualizações detalhadas em JSON (padrão), YAML ou JSON minificado (--output-format).
  • Nome de Servidor Dinâmico: O nome do servidor nos clientes MCP reflete o info.title da especificação carregada.
  • Transformação de Referências: $refs internos (#/components/...) são transformados em URIs MCP clicáveis.

Recursos MCP Disponíveis

Este servidor expõe os seguintes modelos de recursos MCP para explorar a especificação OpenAPI.

Importante: Este servidor fornece modelos de recursos, não recursos pré-enumerados. Ao usar um cliente MCP:

  • O cliente chama resources/templates/list para descobrir os padrões de modelo disponíveis
  • Você então constrói URIs específicos preenchendo os parâmetros do modelo (ex.: substituindo {path} por users%2F%7Bid%7D)
  • O cliente usa resources/read com seu URI construído para buscar o conteúdo real

Se você chamar resources/list (sem "templates"), você obterá uma lista vazia—isso é comportamento esperado.

Entendendo Parâmetros de Múltiplos Valores (*)

Alguns modelos de recursos incluem parâmetros que terminam com um asterisco (*), como {method*} ou {name*}. Isso indica que o parâmetro aceita múltiplos valores separados por vírgula. Por exemplo, para solicitar detalhes para os métodos GET e POST de um caminho, você usaria um URI como openapi://paths/users/get,post. Isso permite buscar detalhes para múltiplos itens em uma única solicitação.

Modelos de Recursos:

  • openapi://{field}

    • Descrição: Acessa campos de nível superior do documento OpenAPI (ex.: info, servers, tags) ou lista o conteúdo de paths ou components. Os campos específicos disponíveis dependem da especificação carregada.
    • Exemplo: openapi://info
    • Saída: Lista text/plain para paths e components; formato configurado (JSON/YAML/JSON minificado) para outros campos.
    • Completions: Fornece sugestões dinâmicas para {field} com base nas chaves de nível superior reais encontradas na especificação carregada.

  • openapi://paths/{path}

    • Descrição: Lista os métodos HTTP disponíveis (operações) para um caminho de API específico.
    • Parâmetro: {path} - A string do caminho da API. Deve ser codificada em URL (ex.: /users/{id} torna-se users%2F%7Bid%7D).
    • Exemplo: openapi://paths/users%2F%7Bid%7D
    • Saída: Lista text/plain de métodos.
    • Completions: Fornece sugestões dinâmicas para {path} com base nos caminhos encontrados na especificação carregada (codificados em URL).

  • openapi://paths/{path}/{method*}

    • Descrição: Obtém a especificação detalhada para uma ou mais operações (métodos HTTP) em um caminho de API específico.
    • Parâmetros:
      • {path} - A string do caminho da API. Deve ser codificada em URL.
      • {method*} - Um ou mais métodos HTTP (ex.: get, post, get,post). Não diferencia maiúsculas de minúsculas.
    • Exemplo (Único): openapi://paths/users%2F%7Bid%7D/get
    • Exemplo (Múltiplo): openapi://paths/users%2F%7Bid%7D/get,post
    • Saída: Formato configurado (JSON/YAML/JSON minificado).
    • Completions: Fornece sugestões dinâmicas para {path}. Fornece sugestões estáticas para {method*} (verbos HTTP comuns como GET, POST, PUT, DELETE, etc.).

  • openapi://components/{type}

    • Descrição: Lista os nomes de todos os componentes definidos de um tipo específico (ex.: schemas, responses, parameters). Os tipos específicos disponíveis dependem da especificação carregada. Também fornece uma breve descrição para cada tipo listado.
    • Exemplo: openapi://components/schemas
    • Saída: Lista text/plain de nomes de componentes com descrições.
    • Completions: Fornece sugestões dinâmicas para {type} com base nos tipos de componentes encontrados na especificação carregada.

  • openapi://components/{type}/{name*}

    • Descrição: Obtém a especificação detalhada de um ou mais componentes nomeados de um tipo específico.
    • Parâmetros:
      • {type} - O tipo do componente.
      • {name*} - Um ou mais nomes de componentes (ex.: User, Order, User,Order). Sensível a maiúsculas/minúsculas.
    • Exemplo (Único): openapi://components/schemas/User
    • Exemplo (Múltiplo): openapi://components/schemas/User,Order
    • Saída: Formato configurado (JSON/YAML/JSON minificado).
    • Completions: Fornece sugestões dinâmicas para {type}. Fornece sugestões dinâmicas para {name*} somente se a especificação carregada contiver exatamente um tipo de componente no total (ex.: apenas schemas). Essa limitação existe porque o SDK MCP atualmente não suporta fornecer completions limitadas ao {type} selecionado; fornecer todos os nomes de todos os tipos poderia ser enganoso.

Contribuindo

Contribuições são bem-vindas! Consulte o arquivo CONTRIBUTING.md para diretrizes sobre como configurar o ambiente de desenvolvimento, executar testes e enviar alterações.

Lançamentos

Este projeto usa semantic-release para gerenciamento automatizado de versões e publicação de pacotes com base em Conventional Commits.

Planos Futuros

(Planos futuros a serem determinados)