APIWeaver

Uma ponte universal para converter qualquer API web em um servidor MCP, suportando múltiplos tipos de transporte.

GitHub
49
Experimente este MCPPatrocinado

Documentação

APIWeaver

Um servidor FastMCP que cria dinamicamente servidores MCP (Model Context Protocol) a partir de configurações de APIs web. Isso permite integrar facilmente qualquer API REST, endpoint GraphQL ou serviço web em uma ferramenta compatível com MCP que pode ser usada por assistentes de IA como o Claude.

Recursos

  • 🚀 Registro Dinâmico de APIs: Registre qualquer API web em tempo de execução
  • 🔐 Múltiplos Métodos de Autenticação: Tokens Bearer, chaves de API, autenticação Basic, OAuth2 e cabeçalhos personalizados
  • 🛠️ Todos os Métodos HTTP: Suporte para GET, POST, PUT, DELETE, PATCH e outros
  • 📝 Parâmetros Flexíveis: Parâmetros de consulta, parâmetros de caminho, cabeçalhos e corpos de requisição
  • 🔄 Geração Automática de Ferramentas: Cada endpoint de API se torna uma ferramenta MCP
  • 🧪 Testes Integrados: Teste conexões de API antes de usá-las
  • 📊 Tratamento de Respostas: Parsing automático de JSON com fallback para texto
  • 🌐 Múltiplos Tipos de Transporte: Suporte a transporte STDIO, SSE e HTTP Streamable

Tipos de Transporte

O APIWeaver suporta três tipos diferentes de transporte para acomodar diversos cenários de implantação:

Transporte STDIO (Padrão)

  • Uso: apiweaver run ou apiweaver run --transport stdio
  • Melhor para: Ferramentas locais, uso em linha de comando e clientes MCP que se conectam via entrada/saída padrão
  • Características: Comunicação direta entre processos, menor latência, adequado para aplicações desktop
  • Endpoint: N/A (usa stdin/stdout)

Transporte SSE (Legado)

  • Uso: apiweaver run --transport sse --host 127.0.0.1 --port 8000
  • Melhor para: Clientes MCP legados que suportam apenas Server-Sent Events
  • Características: Baseado em HTTP, streaming unidirecional do servidor para o cliente
  • Endpoint: http://host:port/mcp
  • Nota: Este transporte está obsoleto em favor do HTTP Streamable

Transporte HTTP Streamable (Recomendado)

  • Uso: apiweaver run --transport streamable-http --host 127.0.0.1 --port 8000
  • Melhor para: Implantações web modernas, ambientes em nuvem e novos clientes MCP
  • Características: Comunicação totalmente baseada em HTTP, streaming bidirecional, melhor tratamento de erros
  • Endpoint: http://host:port/mcp
  • Recomendado: Este é o transporte preferido para novas implantações

Instalação

# Clone or download this repository
cd ~/Desktop/APIWeaver

# Install dependencies
pip install -r requirements.txt

Uso

Claude Desktop

{
  "mcpServers": {
    "apiweaver": {
      "command": "uvx",
      "args": ["apiweaver", "run"]
    }
  }
}

Iniciando o Servidor

Existem várias maneiras de executar o servidor APIWeaver com diferentes tipos de transporte:

1. Após a instalação (recomendado):

Se você instalou o pacote (por exemplo, usando pip install . a partir da raiz do projeto após instalar os requisitos):

# Default STDIO transport
apiweaver run

# Streamable HTTP transport (recommended for web deployments)
apiweaver run --transport streamable-http --host 127.0.0.1 --port 8000

# SSE transport (legacy compatibility)
apiweaver run --transport sse --host 127.0.0.1 --port 8000

2. Diretamente do repositório (para desenvolvimento):

# From the root of the repository
python -m apiweaver.cli run [OPTIONS]

Opções de Transporte:

  • --transport: Escolha entre stdio (padrão), sse ou streamable-http
  • --host: Endereço do host para transportes HTTP (padrão: 127.0.0.1)
  • --port: Porta para transportes HTTP (padrão: 8000)
  • --path: Caminho da URL para o endpoint MCP (padrão: /mcp)

Execute apiweaver run --help para todas as opções disponíveis.

Usando com Assistentes de IA (como Claude Desktop)

O APIWeaver foi projetado para expor APIs web como ferramentas para assistentes de IA que suportam o Model Context Protocol (MCP). Veja como usar:

  1. Inicie o Servidor APIWeaver:

    Para clientes MCP modernos (recomendado):

    apiweaver run --transport streamable-http --host 127.0.0.1 --port 8000

    Para compatibilidade legada:

    apiweaver run --transport sse --host 127.0.0.1 --port 8000

    Para aplicações desktop locais:

    apiweaver run  # Uses STDIO transport

  2. Configure Seu Assistente de IA: O endpoint MCP estará disponível em:

    • HTTP Streamable: http://127.0.0.1:8000/mcp
    • SSE: http://127.0.0.1:8000/mcp
    • STDIO: Comunicação direta entre processos

  3. Registre APIs e Use Ferramentas: Uma vez conectado, use a ferramenta integrada register_api para definir APIs web e depois use as ferramentas de endpoint geradas.

Ferramentas Principais

O servidor fornece estas ferramentas integradas:

  1. register_api - Registra uma nova API e cria ferramentas para seus endpoints
  2. list_apis - Lista todas as APIs registradas e seus endpoints
  3. unregister_api - Remove uma API e suas ferramentas
  4. test_api_connection - Testa a conectividade com uma API registrada
  5. call_api - Ferramenta genérica para chamar qualquer endpoint de API registrado
  6. get_api_schema - Obtém informações de esquema para APIs e endpoints

Formato de Configuração de API

{
  "name": "my_api",
  "base_url": "https://api.example.com",
  "description": "Example API integration",
  "auth": {
    "type": "bearer",
    "bearer_token": "your-token-here"
  },
  "headers": {
    "Accept": "application/json"
  },
  "endpoints": [
    {
      "name": "list_users",
      "description": "Get all users",
      "method": "GET",
      "path": "/users",
      "params": [
        {
          "name": "limit",
          "type": "integer",
          "location": "query",
          "required": false,
          "default": 10,
          "description": "Number of users to return"
        }
      ]
    }
  ]
}

Exemplos

Exemplo 1: API OpenWeatherMap

{
  "name": "weather",
  "base_url": "https://api.openweathermap.org/data/2.5",
  "description": "OpenWeatherMap API",
  "auth": {
    "type": "api_key",
    "api_key": "your-api-key",
    "api_key_param": "appid"
  },
  "endpoints": [
    {
      "name": "get_current_weather",
      "description": "Get current weather for a city",
      "method": "GET",
      "path": "/weather",
      "params": [
        {
          "name": "q",
          "type": "string",
          "location": "query",
          "required": true,
          "description": "City name"
        },
        {
          "name": "units",
          "type": "string",
          "location": "query",
          "required": false,
          "default": "metric",
          "enum": ["metric", "imperial", "kelvin"]
        }
      ]
    }
  ]
}

Exemplo 2: API GitHub

{
  "name": "github",
  "base_url": "https://api.github.com",
  "description": "GitHub REST API",
  "auth": {
    "type": "bearer",
    "bearer_token": "ghp_your_token_here"
  },
  "headers": {
    "Accept": "application/vnd.github.v3+json"
  },
  "endpoints": [
    {
      "name": "get_user",
      "description": "Get a GitHub user's information",
      "method": "GET",
      "path": "/users/{username}",
      "params": [
        {
          "name": "username",
          "type": "string",
          "location": "path",
          "required": true,
          "description": "GitHub username"
        }
      ]
    }
  ]
}

Tipos de Autenticação

Token Bearer

{
  "auth": {
    "type": "bearer",
    "bearer_token": "your-token-here"
  }
}

Chave de API (Cabeçalho)

{
  "auth": {
    "type": "api_key",
    "api_key": "your-key-here",
    "api_key_header": "X-API-Key"
  }
}

Chave de API (Parâmetro de Consulta)

{
  "auth": {
    "type": "api_key",
    "api_key": "your-key-here",
    "api_key_param": "api_key"
  }
}

Autenticação Básica

{
  "auth": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

Cabeçalhos Personalizados

{
  "auth": {
    "type": "custom",
    "custom_headers": {
      "X-Custom-Auth": "custom-value",
      "X-Client-ID": "client-123"
    }
  }
}

Locais de Parâmetros

  • query: Parâmetros de string de consulta (?param=value)
  • path: Parâmetros de caminho (/users/{id})
  • header: Cabeçalhos HTTP
  • body: Corpo da requisição (para POST, PUT, PATCH)

Tipos de Parâmetros

  • string: Valores de texto
  • integer: Números inteiros
  • number: Números decimais
  • boolean: verdadeiro/falso
  • array: Listas de valores
  • object: Objetos JSON

Recursos Avançados

Timeouts Personalizados

{
  "timeout": 60.0  // Timeout in seconds
}

Valores Enum

{
  "name": "status",
  "type": "string",
  "enum": ["active", "inactive", "pending"]
}

Valores Padrão

{
  "name": "page",
  "type": "integer",
  "default": 1
}

Configuração do Claude Desktop

Para Transporte HTTP Streamable (Recomendado)

{
  "mcpServers": {
    "apiweaver": {
      "command": "apiweaver",
      "args": ["run", "--transport", "streamable-http", "--host", "127.0.0.1", "--port", "8000"]
    }
  }
}

Para Transporte STDIO (Tradicional)

{
  "mcpServers": {
    "apiweaver": {
      "command": "apiweaver",
      "args": ["run"]
    }
  }
}

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para:

  • Parâmetros obrigatórios ausentes
  • Erros HTTP (com códigos de status)
  • Falhas de conexão
  • Erros de autenticação
  • Configurações inválidas

Dicas

  1. Escolha o Transporte Certo: Use streamable-http para implantações modernas, stdio para ferramentas locais
  2. Teste Primeiro: Sempre use test_api_connection após registrar uma API
  3. Comece Simples: Comece com endpoints GET antes de avançar para requisições POST complexas
  4. Verifique a Autenticação: Certifique-se de que suas credenciais de autenticação estão corretas
  5. Use Descrições: Forneça descrições claras para melhor compreensão pela IA
  6. Trate Erros: O servidor reportará erros HTTP com detalhes

Solução de Problemas

Problemas Comuns

  1. 401 Não Autorizado: Verifique suas credenciais de autenticação
  2. 404 Não Encontrado: Verifique a URL base e os caminhos dos endpoints
  3. Erros de Timeout: Aumente o valor de timeout para APIs lentas
  4. Erros SSL: Algumas APIs podem exigir configurações SSL específicas

Modo de Depuração

Execute com registro detalhado (se instalado):

apiweaver run --verbose

Problemas Específicos de Transporte

  • STDIO: Certifique-se de que o cliente lida corretamente com a comunicação stdin/stdout
  • SSE: Verifique se o endpoint HTTP está acessível e se o CORS está configurado
  • HTTP Streamable: Verifique se o endpoint MCP responde a requisições HTTP

Contribuindo

Sinta-se à vontade para estender este servidor com recursos adicionais:

  • Atualização de token OAuth2
  • Suporte a GraphQL
  • Endpoints WebSocket
  • Cache de respostas
  • Limitação de taxa
  • Tentativas de requisição

Licença

Licença MIT - sinta-se à vontade para usar e modificar conforme necessário.