OpenAPI MCP Server

OpenAPI MCP Server

Un servidor de Protocolo de Contexto del Modelo (MCP) que permite a los LLM explorar y entender especificaciones OpenAPI mediante herramientas estructuradas.

Características

• 🔍 Exploración Inteligente de APIs - Navega por APIs según categorías, endpoints y esquemas
• 🚀 Múltiples Modos - Ejecuta como stdio (para Claude Desktop), servidor HTTP o CLI interactivo
• 💾 Caché Inteligente - Almacena en caché especificaciones OpenAPI remotas para un acceso más rápido
• 🏗️ Multi-Arquitectura - Soporta Linux AMD64 y ARM64

Inicio Rápido

Usando Claude Desktop

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en 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"]
    }
  }
}

O usa un binario local:

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

Instalación

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

Descargar Binarios

Descarga desde releases:

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

Compilar desde el Código Fuente

# 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

Variables de Entorno

• OPENAPI_SPEC_URL (obligatorio) - URL o ruta de archivo a la especificación OpenAPI
• OPENAPI_CACHE_DIR (opcional) - Directorio de caché (por defecto: ~/.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 Interactivo

# 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

Herramientas Disponibles

El servidor proporciona estas herramientas a los LLM:

1. list_categories - Lista las categorías de la API basadas en segmentos de ruta
2. list_endpoints - Lista los endpoints, opcionalmente filtrados por categoría
3. show_endpoint - Muestra información detallada del endpoint, incluyendo parámetros y esquemas
4. get_spec_info - Obtiene información general sobre la API
5. show_schema - Inspecciona componentes de esquema específicos

Ejemplos

Archivo Local

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

Con Caché Personalizada

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

Docker con Montaje de Volumen

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

Desarrollo

Estructura del Proyecto

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

Compilación de Imágenes Docker

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

# Build all modes
./build.sh docker

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.