OpenAPI MCP Server

Servidor MCP OpenAPI

Um servidor Model Context Protocol (MCP) que permite que LLMs explorem e compreendam especificações OpenAPI por meio de ferramentas estruturadas.

Recursos

• 🔍 Exploração Inteligente de APIs - Navegue por APIs por categorias, endpoints e schemas
• 🚀 Múltiplos Modos - Execute como stdio (para Claude Desktop), servidor HTTP ou CLI interativo
• 💾 Cache Inteligente - Armazena em cache especificações OpenAPI remotas para acesso mais rápido
• 🏗️ Multi-Arquitetura - Suporta Linux AMD64 e ARM64

Início Rápido

Usando Claude Desktop

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "openapi": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "OPENAPI_SPEC_URL=https://api.example.com/openapi.json", "ghcr.io/sagenkoder/go-openapi-exploration-mcp-server:latest"]
    }
  }
}

Ou use um binário local:

{
  "mcpServers": {
    "openapi": {
      "command": "/path/to/openapi-mcp-stdio",
      "env": {
        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json"
      }
    }
  }
}

Instalação

Docker (Recomendado)

# Latest (stdio mode)
docker pull ghcr.io/sagenkoder/go-openapi-exploration-mcp-server:latest

# Specific modes
docker pull ghcr.io/sagenkoder/go-openapi-exploration-mcp-server:http
docker pull ghcr.io/sagenkoder/go-openapi-exploration-mcp-server:interactive

Baixar Binários

Baixe de releases:

• openapi-mcp-stdio-linux-amd64 - Modo stdio MCP
• openapi-mcp-http-linux-amd64 - Modo servidor HTTP
• openapi-mcp-interactive-linux-amd64 - Modo CLI interativo

Compilar a partir do Código-Fonte

# Clone
git clone https://github.com/SagenKoder/go-openapi-exploration-mcp-server.git
cd go-openapi-exploration-mcp-server

# Build all modes
./build.sh

# Or build specific mode
go build -o openapi-mcp-stdio ./cmd/openapi-mcp-stdio

Uso

Variáveis de Ambiente

• OPENAPI_SPEC_URL (obrigatório) - URL ou caminho de arquivo para a especificação OpenAPI
• OPENAPI_CACHE_DIR (opcional) - Diretório de cache (padrão: ~/.openapi-mcp-cache)

Modo Stdio (para clientes MCP)

# Docker
docker run -i --rm \
  -e OPENAPI_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
  ghcr.io/sagenkoder/go-openapi-exploration-mcp-server:latest

# Binary
OPENAPI_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json ./openapi-mcp-stdio

Modo HTTP

# Docker
docker run -p 8080:8080 \
  -e OPENAPI_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
  ghcr.io/sagenkoder/go-openapi-exploration-mcp-server:http

# Binary
OPENAPI_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json ./openapi-mcp-http -addr :8080

Modo Interativo

# Docker
docker run -it --rm \
  -e OPENAPI_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
  ghcr.io/sagenkoder/go-openapi-exploration-mcp-server:interactive

# Binary
OPENAPI_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json ./openapi-mcp-interactive

Ferramentas Disponíveis

O servidor fornece estas ferramentas aos LLMs:

1. list_categories - Lista categorias de API com base em segmentos de caminho
2. list_endpoints - Lista endpoints, opcionalmente filtrados por categoria
3. show_endpoint - Mostra informações detalhadas do endpoint, incluindo parâmetros e schemas
4. get_spec_info - Obtém informações gerais sobre a API
5. show_schema - Inspeciona componentes de schema específicos

Exemplos

Arquivo Local

OPENAPI_SPEC_URL=/path/to/openapi.yaml ./openapi-mcp-stdio

Com Cache Personalizado

OPENAPI_CACHE_DIR=/tmp/api-cache \
OPENAPI_SPEC_URL=https://api.example.com/openapi.json \
./openapi-mcp-stdio

Docker com Montagem de Volume

docker run -i --rm \
  -v $(pwd)/openapi.yaml:/openapi.yaml:ro \
  -e OPENAPI_SPEC_URL=/openapi.yaml \
  ghcr.io/sagenkoder/go-openapi-exploration-mcp-server:latest

Desenvolvimento

Estrutura do Projeto

cmd/
├── openapi-mcp-stdio/       # MCP stdio mode
├── openapi-mcp-http/        # HTTP server mode
└── openapi-mcp-interactive/ # Interactive CLI mode

internal/
├── cache.go      # Caching logic
├── handlers.go   # MCP tool handlers
├── server.go     # Core server logic
└── utils.go      # Utilities

Compilando Imagens Docker

# Build specific mode
docker build --build-arg MODE=stdio -t my-openapi-mcp:stdio .

# Build all modes
./build.sh docker

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.