Any OpenAPI

Um servidor que cria dinamicamente endpoints MCP a partir de qualquer URL de especificação OpenAPI.

GitHub
82
Experimente este MCPPatrocinado

Documentação

Servidor MCP: Descoberta Escalável de Endpoints OpenAPI e Ferramenta de Requisição de API

Docker Hub License: MIT

TODO

  • A imagem docker tem 2GB sem modelos pré-baixados. São 3,76GB com modelos pré-baixados!! Grande demais, alguém por favor me ajude a reduzir o tamanho.

Configuração

Personalize através de variáveis de ambiente. GLOBAL_TOOL_PROMPT é IMPORTANTE!

  • OPENAPI_JSON_DOCS_URL: URL para o JSON da especificação OpenAPI (padrão é https://api.staging.readymojo.com/openapi.json)
  • MCP_API_PREFIX: Namespace de ferramenta personalizável (padrão "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 prefixar todas as descrições de ferramentas. Isso é crucial para fazer o Claude selecionar e não selecionar sua ferramenta com precisão. 
    # 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 ." ...

Resumo

Por que criei isso: Quero servir minha API privada, cuja documentação swagger openapi tem algumas centenas de KB de tamanho.

  • O Claude MCP simplesmente dá erro ao processar arquivos desse tamanho
  • Tentei converter o resultado para YAML, não era pequeno o suficiente e tinha muitos erros. FALHOU
  • Tentei fornecer uma categoria de API e depois pedir ao Cliente MCP (Claude Desktop) para obter a documentação da API por grupo. Ainda era grande demais, FALHOU.

Eventualmente cheguei a esta solução:

  • Usa busca semântica em memória para encontrar endpoints de API relevantes por linguagem natural (como listar produtos)
  • Retorna a documentação completa dos endpoints (como projetei para armazenar um endpoint como um chunk) em milissegundos (já que está em memória)

Boom, o Claude agora sabe qual API chamar, com os parâmetros completos!

Espera, tive que criar outra ferramenta neste servidor para fazer a requisição restful real, porque o servidor "fetch" simplesmente não funciona, e não quero depurar o porquê.

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

Destaques técnicos:

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

Recursos

  • 🧠 Usa arquivo json openapi remoto como fonte, sem acesso ao sistema de arquivos local, sem necessidade de atualização para mudanças na API
  • 🔍 Busca semântica usando modelo MiniLM-L3 otimizado (43MB vs 90MB original)
  • 🚀 Servidor baseado em FastAPI com suporte assíncrono
  • 🧠 Chunking de especificações OpenAPI baseado em endpoints (lida com documentos de 100KB+), sem perda de contexto do endpoint
  • ⚡ Busca vetorial FAISS em memória para descoberta instantânea de endpoints

Limitações

  • Não suporta linux/arm/v7 (falha na compilação na biblioteca Transformer)
  • 🐢 Penalidade de inicialização a frio (~15s para carregamento do modelo) se não usar imagem docker
  • [Obsoleto] A imagem docker atual desabilitou o download de modelos. Você tem uma dependência do huggingface. Quando você carrega o Claude Desktop, leva algum tempo para baixar o modelo. Se o huggingface estiver fora do ar, seu servidor não iniciará.
  • A imagem docker mais recente incorpora modelos pré-baixados. Se houver problemas, reverterei para a antiga.

Exemplo de configuração multi-instância

Aqui está o exemplo de configuração multi-instância. Projetei para que possa ser usado de forma mais flexível para múltiplos 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"
      ]
    }
  }
}

Neste exemplo:

  • O servidor extrairá automaticamente URLs base dos documentos OpenAPI:
    • https://api.finance.com para APIs financeiras
    • https://api.healthcare.com para APIs de saúde
  • Você pode opcionalmente sobrescrever a URL base usando a variável de ambiente 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"
      ]
    }
  }
}

Exemplo de uso no Claude Desktop

Prompt de Projeto do 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.

No chat, você pode fazer:

Get prices for all stocks

Instalação

Instalando via Smithery

Para instalar o Scalable OpenAPI Endpoint Discovery and API Request Tool para Claude Desktop automaticamente via Smithery:

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

Usando pip

pip install mcp-server-any-openapi

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas (onde {prefix} é determinado por MCP_API_PREFIX):

{prefix}_api_request_schema

Obtém esquemas de endpoints de API que correspondem à sua intenção. Retorna detalhes do endpoint incluindo caminho, método, parâmetros e formatos de resposta.

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

Essencial para execução confiável com APIs complexas onde implementações simplificadas falham. Fornece:

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 Resposta:

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

Suporte Docker

Builds Multi-Arquitetura

Imagens oficiais suportam 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 Flexível de Ferramentas

Controle os nomes das ferramentas através de MCP_API_PREFIX:

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

Plataformas Suportadas

  • linux/amd64
  • linux/arm64

Opção 1: Usar Imagem Pré-construída (Docker Hub)

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

Opção 2: Build de Desenvolvimento Local

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

Executando o Contêiner

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 Principais

  1. EndpointSearcher: Classe principal que lida com:

    • Análise de especificação OpenAPI
    • Criação de índice de busca semântica
    • Formatação de documentação de endpoints
    • Processamento de consultas em linguagem natural

  2. Implementação do Servidor:

    • Servidor FastAPI assíncrono
    • Suporte ao protocolo MCP
    • Registro de ferramentas e tratamento de invocação

Executando a partir do Código Fonte

python -m mcp_server_any_openapi

Integração com Claude Desktop

Configure o servidor MCP nas configurações do seu 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"
      ]
    }
  }
}

Contribuindo

  1. Faça um fork do repositório
  2. Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para a branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Licença

Este projeto é licenciado sob os termos incluídos no arquivo LICENSE.

Notas de Implementação

  • Processamento Centrado em Endpoints: Ao contrário da análise em nível de documento que tem dificuldades com especificações grandes, indexamos endpoints individuais com:
    • Caminho + Método como identificadores únicos
    • Embeddings cientes de parâmetros
    • Contexto do esquema de resposta
  • Manipulação Otimizada de Especificações: Processa especificações OpenAPI de até 10MB (~5.000 endpoints) através de:
    • Carregamento preguiçoso de componentes de esquema
    • Análise paralela de itens de caminho
    • Geração seletiva de embeddings (omite descrições redundantes)