APIWeaver

Un puente universal para convertir cualquier API web en un servidor MCP, compatible con múltiples tipos de transporte.

GitHub
49
Prueba este MCPPatrocinado

Documentación

APIWeaver

Un servidor FastMCP que crea dinámicamente servidores MCP (Model Context Protocol) a partir de configuraciones de APIs web. Esto te permite integrar fácilmente cualquier API REST, endpoint de GraphQL o servicio web en una herramienta compatible con MCP que puede ser utilizada por asistentes de IA como Claude.

Características

  • 🚀 Registro Dinámico de APIs: Registra cualquier API web en tiempo de ejecución
  • 🔐 Múltiples Métodos de Autenticación: Tokens Bearer, claves de API, autenticación Basic, OAuth2 y cabeceras personalizadas
  • 🛠️ Todos los Métodos HTTP: Soporte para GET, POST, PUT, DELETE, PATCH y más
  • 📝 Parámetros Flexibles: Parámetros de consulta, parámetros de ruta, cabeceras y cuerpos de solicitud
  • 🔄 Generación Automática de Herramientas: Cada endpoint de API se convierte en una herramienta MCP
  • 🧪 Pruebas Integradas: Prueba las conexiones de API antes de usarlas
  • 📊 Manejo de Respuestas: Análisis JSON automático con respaldo a texto
  • 🌐 Múltiples Tipos de Transporte: Soporte de transporte STDIO, SSE y HTTP Streamable

Tipos de Transporte

APIWeaver soporta tres tipos diferentes de transporte para adaptarse a diversos escenarios de despliegue:

Transporte STDIO (Predeterminado)

  • Uso: apiweaver run o apiweaver run --transport stdio
  • Ideal para: Herramientas locales, uso desde línea de comandos y clientes MCP que se conectan mediante entrada/salida estándar
  • Características: Comunicación directa entre procesos, menor latencia, adecuado para aplicaciones de escritorio
  • Endpoint: N/A (utiliza stdin/stdout)

Transporte SSE (Legado)

  • Uso: apiweaver run --transport sse --host 127.0.0.1 --port 8000
  • Ideal para: Clientes MCP antiguos que solo admiten Server-Sent Events
  • Características: Basado en HTTP, transmisión unidireccional del servidor al cliente
  • Endpoint: http://host:port/mcp
  • Nota: Este transporte está obsoleto en favor de HTTP Streamable

Transporte HTTP Streamable (Recomendado)

  • Uso: apiweaver run --transport streamable-http --host 127.0.0.1 --port 8000
  • Ideal para: Despliegues web modernos, entornos en la nube y nuevos clientes MCP
  • Características: Comunicación completa basada en HTTP, transmisión bidireccional, mejor manejo de errores
  • Endpoint: http://host:port/mcp
  • Recomendado: Este es el transporte preferido para nuevos despliegues

Instalación

# 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"]
    }
  }
}

Iniciar el Servidor

Hay varias formas de ejecutar el servidor APIWeaver con diferentes tipos de transporte:

1. Después de la instalación (recomendado):

Si has instalado el paquete (por ejemplo, usando pip install . desde la raíz del proyecto después de instalar los 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. Directamente desde el repositorio (para desarrollo):

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

Opciones de Transporte:

  • --transport: Elige entre stdio (predeterminado), sse o streamable-http
  • --host: Dirección del host para transportes HTTP (predeterminado: 127.0.0.1)
  • --port: Puerto para transportes HTTP (predeterminado: 8000)
  • --path: Ruta URL para el endpoint MCP (predeterminado: /mcp)

Ejecuta apiweaver run --help para ver todas las opciones disponibles.

Uso con Asistentes de IA (como Claude Desktop)

APIWeaver está diseñado para exponer APIs web como herramientas para asistentes de IA que admiten el Model Context Protocol (MCP). Así es como se usa:

  1. Inicia el Servidor APIWeaver:

    Para clientes MCP modernos (recomendado):

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

    Para compatibilidad con versiones anteriores:

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

    Para aplicaciones de escritorio locales:

    apiweaver run  # Uses STDIO transport

  2. Configura tu Asistente de IA: El endpoint MCP estará disponible en:

    • HTTP Streamable: http://127.0.0.1:8000/mcp
    • SSE: http://127.0.0.1:8000/mcp
    • STDIO: Comunicación directa entre procesos

  3. Registra APIs y Usa Herramientas: Una vez conectado, usa la herramienta integrada register_api para definir APIs web y luego usa las herramientas de endpoint generadas.

Herramientas Principales

El servidor proporciona estas herramientas integradas:

  1. register_api - Registra una nueva API y crea herramientas para sus endpoints
  2. list_apis - Lista todas las APIs registradas y sus endpoints
  3. unregister_api - Elimina una API y sus herramientas
  4. test_api_connection - Prueba la conectividad con una API registrada
  5. call_api - Herramienta genérica para llamar a cualquier endpoint de API registrado
  6. get_api_schema - Obtiene información del esquema para APIs y endpoints

Formato de Configuración 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"
        }
      ]
    }
  ]
}

Ejemplos

Ejemplo 1: API de 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"]
        }
      ]
    }
  ]
}

Ejemplo 2: API de 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 Autenticación

Token Bearer

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

Clave de API (Cabecera)

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

Clave de API (Parámetro de Consulta)

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

Autenticación Básica

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

Cabeceras Personalizadas

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

Ubicaciones de Parámetros

  • query: Parámetros de cadena de consulta (?param=value)
  • path: Parámetros de ruta (/users/{id})
  • header: Cabeceras HTTP
  • body: Cuerpo de la solicitud (para POST, PUT, PATCH)

Tipos de Parámetros

  • string: Valores de texto
  • integer: Números enteros
  • number: Números decimales
  • boolean: verdadero/falso
  • array: Listas de valores
  • object: Objetos JSON

Características Avanzadas

Tiempos de Espera Personalizados

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

Valores de Enumeración

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

Valores Predeterminados

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

Configuración de 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"]
    }
  }
}

Manejo de Errores

El servidor proporciona mensajes de error detallados para:

  • Parámetros obligatorios faltantes
  • Errores HTTP (con códigos de estado)
  • Fallos de conexión
  • Errores de autenticación
  • Configuraciones no válidas

Consejos

  1. Elige el Transporte Adecuado: Usa streamable-http para despliegues modernos, stdio para herramientas locales
  2. Prueba Primero: Usa siempre test_api_connection después de registrar una API
  3. Comienza con Algo Simple: Empieza con endpoints GET antes de pasar a solicitudes POST complejas
  4. Verifica la Autenticación: Asegúrate de que tus credenciales de autenticación sean correctas
  5. Usa Descripciones: Proporciona descripciones claras para una mejor comprensión por parte de la IA
  6. Maneja los Errores: El servidor informará errores HTTP con detalles

Solución de Problemas

Problemas Comunes

  1. 401 No Autorizado: Verifica tus credenciales de autenticación
  2. 404 No Encontrado: Verifica la URL base y las rutas de los endpoints
  3. Errores de Tiempo de Espera: Aumenta el valor de tiempo de espera para APIs lentas
  4. Errores SSL: Algunas APIs pueden requerir configuraciones SSL específicas

Modo de Depuración

Ejecuta con registro detallado (si está instalado):

apiweaver run --verbose

Problemas Específicos del Transporte

  • STDIO: Asegúrate de que el cliente maneje correctamente la comunicación stdin/stdout
  • SSE: Verifica que el endpoint HTTP sea accesible y que CORS esté configurado
  • HTTP Streamable: Verifica que el endpoint MCP responda a solicitudes HTTP

Contribuciones

Siéntete libre de ampliar este servidor con características adicionales:

  • Actualización de tokens OAuth2
  • Soporte para GraphQL
  • Endpoints WebSocket
  • Caché de respuestas
  • Limitación de velocidad
  • Reintentos de solicitudes

Licencia

Licencia MIT: siéntete libre de usar y modificar según sea necesario.