Ambivo Claude MCP Server

Este servidor Claude MCP (Model Context Protocol) proporciona acceso a los endpoints de la API de Ambivo para consultas en lenguaje natural de datos de entidades con Claude AI.

Características

• Consultas en lenguaje natural: Ejecuta consultas en lenguaje natural contra datos de entidades utilizando el endpoint /entity/natural_query

• Autenticación JWT: Acceso seguro mediante autenticación con token Bearer

• Limitación de velocidad: Limitación de velocidad integrada para prevenir el abuso de la API

• Caché de tokens: Validación eficiente de tokens con caché

• Manejo de errores: Manejo integral de errores con mensajes de error detallados

• Lógica de reintentos: Reintento automático con retroceso exponencial para solicitudes fallidas

Herramientas

1. set_auth_token

Establece el token Bearer JWT para la autenticación con la API de Ambivo.

Parámetros:

• token (cadena, obligatorio): Token Bearer JWT

Uso:

{
  "token": "your-jwt-token-here"
}

2. natural_query

Ejecuta consultas en lenguaje natural contra los datos de entidades de Ambivo.

Parámetros:

• query (cadena, obligatorio): Consulta en lenguaje natural que describe los datos que deseas

• response_format (cadena, opcional): Formato de respuesta: "table", "natural" o "both" (por defecto: "both")

Consultas de ejemplo:

• "Muéstrame los leads creados esta semana"

• "Encuentra contactos con direcciones de Gmail"

• "Lista las oportunidades que valen más de $10,000"

• "Muéstrame los leads con attribution_source google_ads de los últimos 7 días"

Uso:

{
  "query": "Show me leads created this week with attribution_source google_ads",
  "response_format": "both"
}

Acerca de

Esta es una implementación de servidor MCP puramente basada en Claude para la API de Ambivo, diseñada para funcionar sin problemas con Claude Desktop y otros clientes MCP compatibles con Claude. Permite la interacción en lenguaje natural con los datos de tu CRM de Ambivo mediante las potentes capacidades de comprensión del lenguaje de Claude.

Instalación

Opción 1: Instalar desde PyPI (Recomendado)

pip install ambivo-mcp-server

Opción 2: Instalar desde el código fuente

git clone https://github.com/ambivo-corp/ambivo-mcp-server.git
cd ambivo-mcp-server
pip install -e .

Ejecutar el servidor

# If installed via pip
ambivo-mcp-server

# Or using Python module
python -m ambivo_mcp_server.server

Configuración

El servidor utiliza la siguiente configuración predeterminada:

• URL base: https://goferapi.ambivo.com

• Tiempo de espera: 30 segundos

• Tipo de contenido: application/json

Puedes modificar estos ajustes en la clase AmbivoAPIClient si es necesario.

Autenticación

1. Primero, establece tu token de autenticación usando la herramienta set_auth_token

2. El token se incluirá en todas las solicitudes posteriores a la API como token Bearer

3. El token debe ser un token JWT válido de tu autenticación en la API de Ambivo

Manejo de errores

El servidor proporciona un manejo integral de errores:

• Errores de autenticación: Mensajes claros cuando el token falta o no es válido

• Errores HTTP: Códigos de estado HTTP detallados y mensajes de respuesta

• Errores de validación: Validación de parámetros con mensajes de error útiles

• Errores de red: Manejo de tiempos de espera y errores de conexión

Endpoints de la API

Este servidor MCP se integra con estos endpoints de la API de Ambivo:

/entity/natural_query

• Método: POST

• Propósito: Procesar consultas en lenguaje natural para la recuperación de datos de entidades

• Autenticación: Requerida (token Bearer JWT)

• Content-Type: application/json

/entity/data

• Método: POST

• Propósito: Acceso directo a datos de entidades con parámetros estructurados

• Autenticación: Requerida (token Bearer JWT)

• Content-Type: application/json

Flujo de trabajo de ejemplo

1. Configurar autenticación:

   {
     "tool": "set_auth_token",
     "arguments": {
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
     }
   }

2. Consulta en lenguaje natural:

   {
     "tool": "natural_query", 
     "arguments": {
       "query": "Show me all leads created in the last 30 days with phone numbers",
       "response_format": "both"
     }
   }

3. Consulta directa de entidades:

   {
     "tool": "entity_data",
     "arguments": {
       "entity_type": "contact",
       "filters": {"email": {"$regex": "@gmail.com$"}},
       "limit": 100,
       "sort": {"created_date": -1}
     }
   }

Desarrollo

Para ampliar este servidor MCP:

1. Añadir nuevas herramientas: Implementa herramientas adicionales en las funciones handle_list_tools() y handle_call_tool()

2. Modificar el cliente de la API: Amplía la clase AmbivoAPIClient para admitir endpoints adicionales

3. Actualizar la configuración: Modifica los ajustes predeterminados en la sección de configuración

Solución de problemas

Problemas comunes:

1. Error de "Authentication required": Asegúrate de haber llamado a set_auth_token primero

2. Errores HTTP 401/403: Verifica que tu token JWT sea válido y no esté caducado

3. Tiempo de espera de conexión: Comprueba la conectividad de red y la disponibilidad del endpoint de la API

4. Parámetros no válidos: Revisa los esquemas de las herramientas para ver los parámetros obligatorios y opcionales

Registro:

El servidor registra eventos y errores importantes. Consulta la salida de la consola para obtener información de depuración.