ReAPI OpenAPI

Serve múltiplas especificações OpenAPI para habilitar integrações de IDE com LLM.

GitHub
90
Experimente este MCPPatrocinado

Documentação

@reapi/mcp-openapi

Um servidor Model Context Protocol (MCP) que carrega e serve múltiplas especificações OpenAPI para habilitar integrações de IDE com LLM. Este servidor atua como uma ponte entre suas especificações OpenAPI e ferramentas de desenvolvimento com LLM, como Cursor e outros editores de código.

Recursos

  • Carrega múltiplas especificações OpenAPI de um diretório
  • Expõe operações e esquemas de API através do protocolo MCP
  • Permite que LLMs entendam e trabalhem com suas APIs diretamente no seu IDE
  • Suporta esquemas dereferenciados para contexto completo da API
  • Mantém um catálogo de todas as APIs disponíveis

Desenvolvido pela ReAPI

Este servidor MCP de código aberto é patrocinado pela ReAPI, uma plataforma de API de próxima geração que simplifica o design e os testes de API. Enquanto este servidor fornece integração OpenAPI local para desenvolvimento, a ReAPI oferece dois módulos poderosos:

🎨 API CMS

  • Projete APIs usando um editor no-code intuitivo
  • Gere e publique especificações OpenAPI automaticamente
  • Colabore com membros da equipe em tempo real
  • Controle de versão e gerenciamento de alterações

🧪 Testes de API

  • A solução de teste de API no-code mais amigável para desenvolvedores
  • Crie e gerencie casos de teste com uma interface intuitiva
  • Poderosos recursos de asserção e validação
  • Executor de testes em nuvem serverless
  • Perfeito para equipes de QA e desenvolvedores
  • Pronto para integração com CI/CD

Experimente a ReAPI gratuitamente em reapi.com e experimente o futuro do desenvolvimento de APIs.

Configuração do Cursor

Para integrar o servidor MCP OpenAPI com o IDE Cursor, você tem duas opções para os locais de configuração:

Opção 1: Configuração Específica do Projeto (Recomendado)

Crie um arquivo .cursor/mcp.json no diretório do seu projeto. Esta opção é recomendada, pois permite manter diferentes conjuntos de especificações para diferentes projetos

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "./specs"],
      "env": {}
    }
  }
}

Dica: Usar um caminho relativo como ./specs torna a configuração portátil e mais fácil de compartilhar entre os membros da equipe.

Nota: Recomendamos usar a tag @latest, pois atualizamos frequentemente o servidor com novos recursos e melhorias.

Importante: A configuração específica do projeto ajuda a gerenciar os limites de contexto do LLM. Quando todas as especificações são colocadas em uma única pasta, os metadados combinados podem exceder a janela de contexto do LLM, causando erros. Organizar as especificações por projeto mantém o tamanho do contexto gerenciável.

Opção 2: Configuração Global

Crie ou edite ~/.cursor/mcp.json no seu diretório inicial para disponibilizar o servidor em todos os projetos:

{
  "mcpServers": {
    "@reapi/mcp-openapi": {
      "command": "npx",
      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "/path/to/your/specs"],
      "env": {}
    }
  }
}

Habilitar nas Configurações do Cursor

Após adicionar a configuração:

  1. Abra o IDE Cursor
  2. Vá para Configurações > Configurações do Cursor > MCP
  3. Habilite o servidor @reapi/mcp-openapi
  4. Clique no ícone de atualizar ao lado do servidor para aplicar as alterações

Nota: Por padrão, o Cursor exige confirmação para cada execução de ferramenta MCP. Se você quiser permitir a execução automática sem confirmação, você pode habilitar o modo Yolo nas configurações do Cursor.

O servidor agora está pronto para uso. Quando você adicionar novas especificações OpenAPI ao seu diretório, você pode atualizar o catálogo:

  1. Abrindo o painel de chat do Cursor
  2. Digitando um destes prompts: 
    "Please refresh the API catalog"
"Reload the OpenAPI specifications"

Requisitos da Especificação OpenAPI

  1. Coloque suas especificações OpenAPI 3.x no diretório de destino:

    • Suporta formatos JSON e YAML
    • Os arquivos devem ter extensões .json, .yaml ou .yml
    • O scanner descobrirá e processará automaticamente todos os arquivos de especificação

  2. Configuração do ID da Especificação:

    • Por padrão, o nome do arquivo (sem extensão) é usado como o ID da especificação
    • Para especificar um ID personalizado, adicione x-spec-id no objeto de informações OpenAPI:
    openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  x-spec-id: my-custom-api-id  # Custom specification ID

    Importante: Definir um x-spec-id personalizado é crucial ao trabalhar com múltiplas especificações que possuem:

    • Caminhos de endpoint semelhantes ou idênticos
    • Mesmos nomes de esquema
    • IDs de operação sobrepostos

    O ID da especificação ajuda a distinguir entre esses recursos semelhantes e evita conflitos de nomenclatura. Por exemplo:

    # user-service.yaml
info:
  x-spec-id: user-service
paths:
  /users:
    get: ...

# admin-service.yaml
info:
  x-spec-id: admin-service
paths:
  /users:
    get: ...

    Agora você pode referenciar esses endpoints especificamente como user-service/users e admin-service/users

Como Funciona

  1. O servidor verifica o diretório especificado em busca de arquivos de especificação OpenAPI
  2. Ele processa e dereferencia as especificações para contexto completo
  3. Cria e mantém um catálogo de todas as operações e esquemas de API
  4. Expõe essas informações através do protocolo MCP
  5. As integrações de IDE podem então usar essas informações para:
    • Fornecer contexto de API para LLMs
    • Habilitar conclusão de código inteligente
    • Auxiliar na integração de API
    • Gerar trechos de código cientes da API

Ferramentas

  1. refresh-api-catalog

    • Atualizar o catálogo de APIs
    • Retorna: Mensagem de sucesso quando o catálogo é atualizado

  2. get-api-catalog

    • Obter o catálogo de APIs; o catálogo contém metadados sobre todas as especificações OpenAPI, suas operações e esquemas
    • Retorna: Catálogo completo de APIs com todas as especificações, operações e esquemas

  3. search-api-operations

    • Buscar operações em todas as especificações
    • Entradas:
      • query (string): Consulta de busca
      • specId (string opcional): ID específico da especificação de API para buscar
    • Retorna: Operações correspondentes do catálogo de APIs

  4. search-api-schemas

    • Buscar esquemas em todas as especificações
    • Entradas:
      • query (string): Consulta de busca
      • specId (string opcional): ID específico da especificação de API para buscar
    • Retorna: Esquemas correspondentes do catálogo de APIs

  5. load-api-operation-by-operationId

    • Carregar uma operação pelo operationId
    • Entradas:
      • specId (string): ID da especificação de API
      • operationId (string): ID da operação a ser carregada
    • Retorna: Detalhes completos da operação

  6. load-api-operation-by-path-and-method

    • Carregar uma operação por caminho e método
    • Entradas:
      • specId (string): ID da especificação de API
      • path (string): Caminho do endpoint da API
      • method (string): Método HTTP
    • Retorna: Detalhes completos da operação

  7. load-api-schema-by-schemaName

    • Carregar um esquema pelo schemaName
    • Entradas:
      • specId (string): ID da especificação de API
      • schemaName (string): Nome do esquema a ser carregado
    • Retorna: Detalhes completos do esquema

Roadmap

  1. Busca Semântica

    • Habilitar consultas em linguagem natural para operações e esquemas de API
    • Melhorar a precisão da busca com compreensão semântica

  2. Sincronização de Especificações Remotas

    • Suportar sincronização de especificações OpenAPI de fontes remotas

  3. Modelos de Código

    • Expor modelos de código através do protocolo MCP
    • Fornecer padrões de referência para geração de código por LLM

  4. Contribuições da Comunidade

    • Enviar solicitações de recursos e relatórios de bugs
    • Contribuir para melhorar o servidor

Exemplos de Prompts no Cursor

Aqui estão alguns exemplos de prompts que você pode usar no IDE Cursor para interagir com suas APIs:

  1. Explorar APIs Disponíveis

    "Show me all available APIs in the catalog with their operations"
"List all API specifications and their endpoints"

  2. Detalhes da Operação de API

    "Show me the details of the create pet API endpoint"
"What are the required parameters for creating a new pet?"
"Explain the response schema for the pet creation endpoint"

  3. Esquema e Dados Mock

    "Generate mock data for the Pet schema"
"Create a valid request payload for the create pet endpoint"
"Show me examples of valid pet objects based on the schema"

  4. Geração de Código

    "Generate an Axios client for the create pet API"
"Create a TypeScript interface for the Pet schema"
"Write a React hook that calls the create pet endpoint"

  5. Assistência de Integração de API

    "Help me implement error handling for the pet API endpoints"
"Generate unit tests for the pet API client"
"Create a service class that encapsulates all pet-related API calls"

  6. Documentação e Uso

    "Show me example usage of the pet API with curl"
"Generate JSDoc comments for the pet API client methods"
"Create a README section explaining the pet API integration"

  7. Validação e Tipos

    "Generate Zod validation schema for the Pet model"
"Create TypeScript types for all pet-related API responses"
"Help me implement request payload validation for the pet endpoints"

  8. Busca e Descoberta de API

    "Find all endpoints related to pet management"
"Show me all APIs that accept file uploads"
"List all endpoints that return paginated responses"

Esses prompts demonstram como aproveitar os recursos do servidor MCP para desenvolvimento de API. Sinta-se à vontade para adaptá-los às suas necessidades específicas ou combiná-los para tarefas mais complexas.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.