Any OpenAPI

Un servidor que crea dinámicamente endpoints MCP a partir de cualquier URL de especificación OpenAPI.

GitHub
82
Prueba este MCPPatrocinado

Documentación

Servidor MCP: Descubrimiento de Endpoints OpenAPI Escalable y Herramienta de Solicitud de API

Docker Hub License: MIT

TODO

  • La imagen de docker es de 2GB sin modelos precargados. ¡¡Es de 3.76GB con modelos precargados!! Demasiado grande, alguien por favor ayúdeme a reducir el tamaño.

Configuración

Personaliza mediante variables de entorno. GLOBAL_TOOL_PROMPT es IMPORTANTE!

  • OPENAPI_JSON_DOCS_URL: URL al JSON de especificación OpenAPI (por defecto https://api.staging.readymojo.com/openapi.json)
  • MCP_API_PREFIX: Espacio de nombres de herramienta personalizable (por defecto "any_openapi"): 
    # Creates tools: custom_api_request_schema and custom_make_request
docker run -e MCP_API_PREFIX=finance ...
  • GLOBAL_TOOL_PROMPT: Texto opcional para anteponer a todas las descripciones de herramientas. Esto es crucial para que Claude seleccione o no seleccione tu herramienta con precisión. 
    # Adds "Access to insights apis for ACME Financial Services abc.com . " to the beginning of all tool descriptions
docker run -e GLOBAL_TOOL_PROMPT="Access to insights apis for ACME Financial Services abc.com ." ...

TL'DR

Por qué creo esto: Quiero servir mi API privada, cuyos documentos swagger openapi tienen un tamaño de unos cientos de KB.

  • Claude MCP simplemente falla al procesar archivos de este tamaño
  • Intenté convertir el resultado a YAML, no es lo suficientemente pequeño y tiene muchos errores. FALLÓ
  • Intenté proporcionar una categoría de API y luego pedir al Cliente MCP (Claude Desktop) que obtuviera el documento de API por grupo. Sigue siendo demasiado grande, FALLÓ.

Finalmente llegué a esta solución:

  • Utiliza búsqueda semántica en memoria para encontrar endpoints de API relevantes mediante lenguaje natural (como listar productos)
  • Devuelve la documentación completa del endpoint (como la diseñé para almacenar un endpoint como un fragmento) en milisegundos (ya que está en memoria)

Boom, Claude ahora sabe qué API llamar, ¡con los parámetros completos!

Espera, tuve que crear otra herramienta en este servidor para hacer la solicitud restful real, porque el servidor "fetch" simplemente no funciona, y no quiero depurar por qué.

https://github.com/user-attachments/assets/484790d2-b5a7-475d-a64d-157e839ad9b0

Aspectos técnicos destacados:

query -> [Embedding] -> FAISS TopK -> OpenAPI docs -> MCP Client (Claude Desktop)
MCP Client -> Construct OpenAPI Request -> Execute Request -> Return Response

Características

  • 🧠 Usa archivo json openapi remoto como fuente, sin acceso al sistema de archivos local, sin necesidad de actualizar para cambios de API
  • 🔍 Búsqueda semántica usando el modelo optimizado MiniLM-L3 (43MB vs 90MB original)
  • 🚀 Servidor basado en FastAPI con soporte asíncrono
  • 🧠 Fragmentación de especificaciones OpenAPI basada en endpoints (maneja documentos de 100KB+), sin pérdida de contexto del endpoint
  • ⚡ Búsqueda vectorial FAISS en memoria para descubrimiento instantáneo de endpoints

Limitaciones

  • No soporta linux/arm/v7 (la compilación falla en la librería Transformer)
  • 🐢 Penalización de arranque en frío (~15s para carga de modelo) si no se usa la imagen docker
  • [Obsoleto] La imagen docker actual deshabilitó la descarga de modelos. Tienes una dependencia de huggingface. Cuando cargas Claude Desktop, tarda un tiempo en descargar el modelo. Si huggingface está caído, tu servidor no se iniciará.
  • La última imagen docker incluye modelos precargados. Si hay problemas, volvería a la anterior.

Ejemplo de configuración multi-instancia

Aquí está el ejemplo de configuración multi-instancia. Lo diseñé para que pueda usarse de manera más flexible para múltiples conjuntos de APIs:

{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    },
    "healthcare_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.healthcare.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=healthcare",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for Healthcare API services efg.com .",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

En este ejemplo:

  • El servidor extraerá automáticamente las URLs base de los documentos OpenAPI:
    • https://api.finance.com para APIs de finanzas
    • https://api.healthcare.com para APIs de salud
  • Opcionalmente puedes sobrescribir la URL base usando la variable de entorno API_REQUEST_BASE_URL:
{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e",
        "API_REQUEST_BASE_URL=https://api.finance.staging.com",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Ejemplo de uso en Claude Desktop

Prompt de proyecto de Claude Desktop:

You should get the api spec details from tools financial_api_request_schema

You task is use financial_make_request tool to make the requests to get response. You should follow the api spec to add authorization header:
Authorization: Bearer <xxxxxxxxx>

Note: The base URL will be returned in the api_request_schema response, you don't need to specify it manually.

En el chat, puedes hacer:

Get prices for all stocks

Instalación

Instalación mediante Smithery

Para instalar Scalable OpenAPI Endpoint Discovery and API Request Tool para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @baryhuang/mcp-server-any-openapi --client claude

Usando pip

pip install mcp-server-any-openapi

Herramientas disponibles

El servidor proporciona las siguientes herramientas (donde {prefix} está determinado por MCP_API_PREFIX):

{prefix}_api_request_schema

Obtén los esquemas de endpoints de API que coincidan con tu intención. Devuelve detalles del endpoint, incluyendo ruta, método, parámetros y formatos de respuesta.

Esquema de entrada:

{
    "query": {
        "type": "string",
        "description": "Describe what you want to do with the API (e.g., 'Get user profile information', 'Create a new job posting')"
    }
}

{prefix}_make_request

Esencial para una ejecución confiable con APIs complejas donde las implementaciones simplificadas fallan. Proporciona:

Esquema de entrada:

{
    "method": {
        "type": "string",
        "description": "HTTP method (GET, POST, PUT, DELETE, PATCH)",
        "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
    },
    "url": {
        "type": "string",
        "description": "Fully qualified API URL (e.g., https://api.example.com/users/123)"
    },
    "headers": {
        "type": "object",
        "description": "Request headers (optional)",
        "additionalProperties": {
            "type": "string"
        }
    },
    "query_params": {
        "type": "object",
        "description": "Query parameters (optional)",
        "additionalProperties": {
            "type": "string"
        }
    },
    "body": {
        "type": "object",
        "description": "Request body for POST, PUT, PATCH (optional)"
    }
}

Formato de respuesta:

{
    "status_code": 200,
    "headers": {
        "content-type": "application/json",
        ...
    },
    "body": {
        // Response data
    }
}

Soporte Docker

Compilaciones Multi-Arquitectura

Las imágenes oficiales soportan 3 plataformas:

# Build and push using buildx
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t buryhuang/mcp-server-any-openapi:latest \
  --push .

Nombres de Herramientas Flexibles

Controla los nombres de las herramientas mediante MCP_API_PREFIX:

# Produces tools with "finance_api" prefix:
docker run -e MCP_API_PREFIX=finance_ ...

Plataformas Soportadas

  • linux/amd64
  • linux/arm64

Opción 1: Usar Imagen Preconstruida (Docker Hub)

docker pull buryhuang/mcp-server-any-openapi:latest

Opción 2: Compilación de Desarrollo Local

docker build -t mcp-server-any-openapi .

Ejecutar el Contenedor

docker run \
  -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \
  -e MCP_API_PREFIX=finance \
  buryhuang/mcp-server-any-openapi:latest

Componentes Clave

  1. EndpointSearcher: Clase principal que maneja:

    • Análisis de especificaciones OpenAPI
    • Creación de índice de búsqueda semántica
    • Formateo de documentación de endpoints
    • Procesamiento de consultas en lenguaje natural

  2. Implementación del Servidor:

    • Servidor FastAPI asíncrono
    • Soporte de protocolo MCP
    • Manejo de registro e invocación de herramientas

Ejecutar desde el Código Fuente

python -m mcp_server_any_openapi

Integración con Claude Desktop

Configura el servidor MCP en la configuración de tu Claude Desktop:

{
  "mcpServers": {
    "any_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Contribuciones

  1. Haz un fork del repositorio
  2. Crea tu rama de características (git checkout -b feature/amazing-feature)
  3. Realiza tus cambios (git commit -m 'Add some amazing feature')
  4. Empuja a la rama (git push origin feature/amazing-feature)
  5. Abre una Solicitud de Extracción (Pull Request)

Licencia

Este proyecto está licenciado bajo los términos incluidos en el archivo LICENSE.

Notas de Implementación

  • Procesamiento Centrado en Endpoints: A diferencia del análisis a nivel de documento que falla con especificaciones grandes, indexamos endpoints individuales con:
    • Ruta + Método como identificadores únicos
    • Incrustaciones conscientes de parámetros
    • Contexto del esquema de respuesta
  • Manejo Optimizado de Especificaciones: Procesa especificaciones OpenAPI de hasta 10MB (~5,000 endpoints) mediante:
    • Carga perezosa de componentes de esquema
    • Análisis paralelo de elementos de ruta
    • Generación selectiva de incrustaciones (omite descripciones redundantes)