Servidor MCP: herramienta escalable de detección de puntos finales OpenAPI y solicitud de API

HACER

La imagen de Docker ocupa 2 GB sin los modelos predescargados. ¡Ocupa 3,76 GB con los modelos predescargados! Es demasiado grande. Por favor, necesito ayuda para reducir el tamaño.

Configuración

Personalice mediante variables de entorno. ¡GLOBAL_TOOL_PROMPT es IMPORTANTE !

OPENAPI_JSON_DOCS_URL : URL al JSON de la especificación OpenAPI (el valor predeterminado es https://api.staging.readymojo.com/openapi.json )
MCP_API_PREFIX : Espacio de herramientas personalizable (predeterminado "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 y no seleccione la 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 ." ...

Resumen

Por qué creo esto : quiero servir mi API privada, cuyos documentos de OpenAPI de Swagger tienen un tamaño de unos cientos de KB.

Claude MCP simplemente cometió un error al procesar este tamaño de archivo
Intenté convertir el resultado a YAML, no es lo suficientemente pequeño y hay muchos errores. FALLÓ
Intenté proporcionar una categoría de API y luego le pedí al cliente MCP (Claude Desktop) que obtuviera la documentación de la API por grupo. Aún era demasiado grande, FALLÓ.

Al final llegué a esta solución:

Utiliza la búsqueda semántica en memoria para encontrar puntos finales de API relevantes mediante lenguaje natural (como productos de lista).
Devuelve los documentos completos del punto final (ya que lo diseñé para almacenar un punto final como un fragmento) en millones de segundos (como está en la memoria).

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

Espere, tengo que crear otra herramienta en este servidor para realizar la solicitud REST real, porque el servidor de "búsqueda" 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

🧠 Utilice el archivo json openapi remoto como fuente, sin acceso al sistema de archivos local, no se requiere actualización para cambios de API
🔍 Búsqueda semántica utilizando el modelo MiniLM-L3 optimizado (43 MB frente a los 90 MB originales)
Servidor basado en FastAPI con soporte asíncrono
🧠 Segmentación basada en puntos finales según especificaciones OpenAPI (maneja documentos de más de 100 KB), sin pérdida de contexto de punto final
⚡ Búsqueda de vectores FAISS en memoria para el descubrimiento instantáneo de puntos finales

Limitaciones

No es compatible con Linux/Arm/v7 (la compilación falla en la biblioteca Transformer)
Penalización por inicio en frío (~15 s para la carga del modelo) si no se usa la imagen de Docker
[Obsoleto] La imagen actual de Docker deshabilitó la descarga de modelos. Tiene una dependencia con huggingface. Al cargar el Escritorio Claude, la descarga del modelo tarda un tiempo. Si huggingface no funciona, su servidor no se iniciará.
La última imagen de Docker integra modelos precargados. Si hay problemas, recomiendo volver a la versión anterior.

Ejemplo de configuración de múltiples instancias

Aquí está el ejemplo de configuración multiinstancia. Lo diseñé para que sea más flexible para usar con múltiples conjuntos de API:

{
  "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 URL base de la documentación de OpenAPI:
- https://api.finance.com para API financieras
- https://api.healthcare.com para API de atención médica
Opcionalmente, puede anular la URL base utilizando 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 de Claude Desktop

Indicación del proyecto de escritorio de Claude:

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 herrería

Para instalar automáticamente Scalable OpenAPI Endpoint Discovery y API Request Tool para Claude Desktop a través de 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 ):

{prefijo}_esquema_de_solicitud_api

Obtén esquemas de endpoints de API que coincidan con tu intención. Devuelve detalles de endpoints, como 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')"
    }
}

{prefijo}_hacer_solicitud

Esencial para una ejecución confiable con API 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 de Docker

Construcciones multiarquitectura

Las imágenes oficiales son compatibles con 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 .

Nomenclatura flexible de herramientas

Nombres de herramientas de control a través de MCP_API_PREFIX :

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

Plataformas compatibles

Linux/amd64
Linux/arm64

Opción 1: Usar una imagen prediseñada (Docker Hub)

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

Opción 2: Construcción de desarrollo local

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

Ejecución del 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

EndpointSearcher : clase principal que maneja:
- Análisis de especificaciones de OpenAPI
- Creación de índices de búsqueda semántica
- Formato de la documentación del punto final
- Procesamiento de consultas en lenguaje natural
Implementación del servidor :
- Servidor FastAPI asíncrono
- Compatibilidad con el protocolo MCP
- Registro de herramientas y manejo de invocaciones

Corriendo desde la fuente

python -m mcp_server_any_openapi

Integración con Claude Desktop

Configure el servidor MCP en la configuración de 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"
      ]
    }
  }
}

Contribuyendo

Bifurcar el repositorio
Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
Confirme sus cambios ( git commit -m 'Add some amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

Licencia

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

Notas de implementación

Procesamiento centrado en puntos finales : a diferencia del análisis a nivel de documento que tiene dificultades con grandes especificaciones, indexamos puntos finales individuales con:
- Ruta + Método como identificadores únicos
- Incrustaciones que reconocen parámetros
- Contexto del esquema de respuesta
Manejo optimizado de especificaciones : procesa especificaciones OpenAPI de hasta 10 MB (aproximadamente 5000 puntos finales) a través de:
- Carga diferida de componentes del esquema
- Análisis paralelo de elementos de ruta
- Generación de incrustación selectiva (omite descripciones redundantes)

MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

Integrations