Ambivo Claude MCP Server

Этот сервер Claude MCP (Model Context Protocol) предоставляет доступ к конечным точкам Ambivo API для запросов на естественном языке к данным сущностей с помощью Claude AI.

Возможности

• Запросы на естественном языке: Выполнение запросов на естественном языке к данным сущностей с использованием конечной точки /entity/natural_query

• JWT-аутентификация: Безопасный доступ с использованием аутентификации по Bearer-токену

• Ограничение скорости: Встроенное ограничение скорости для предотвращения злоупотребления API

• Кэширование токенов: Эффективная проверка токенов с кэшированием

• Обработка ошибок: Комплексная обработка ошибок с подробными сообщениями об ошибках

• Логика повторных попыток: Автоматические повторные попытки с экспоненциальной задержкой для неудачных запросов

Инструменты

1. set_auth_token

Установите JWT Bearer-токен для аутентификации с Ambivo API.

Параметры:

• token (строка, обязательный): JWT Bearer-токен

Использование:

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

2. natural_query

Выполнение запросов на естественном языке к данным сущностей Ambivo.

Параметры:

• query (строка, обязательный): Запрос на естественном языке, описывающий, какие данные вам нужны

• response_format (строка, необязательный): Формат ответа — "table", "natural" или "both" (по умолчанию: "both")

Примеры запросов:

• "Show me leads created this week"

• "Find contacts with gmail addresses"

• "List opportunities worth more than $10,000"

• "Show me leads with attribution_source google_ads from the last 7 days"

Использование:

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

О сервере

Это чистая реализация MCP-сервера на основе Claude для Ambivo API, предназначенная для бесшовной работы с Claude Desktop и другими MCP-клиентами, совместимыми с Claude. Она обеспечивает взаимодействие с данными Ambivo CRM на естественном языке благодаря мощным возможностям понимания языка Claude.

Установка

Вариант 1: Установка из PyPI (рекомендуется)

pip install ambivo-mcp-server

Вариант 2: Установка из исходного кода

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

Запуск сервера

# If installed via pip
ambivo-mcp-server

# Or using Python module
python -m ambivo_mcp_server.server

Конфигурация

Сервер использует следующую конфигурацию по умолчанию:

• Базовый URL: https://goferapi.ambivo.com

• Тайм-аут: 30 секунд

• Тип контента: application/json

Вы можете изменить эти настройки в классе AmbivoAPIClient, если это необходимо.

Аутентификация

1. Сначала установите свой токен аутентификации с помощью инструмента set_auth_token

2. Токен будет включен во все последующие API-запросы как Bearer-токен

3. Токен должен быть действительным JWT-токеном от аутентификации Ambivo API

Обработка ошибок

Сервер обеспечивает комплексную обработку ошибок:

• Ошибки аутентификации: Понятные сообщения, когда токен отсутствует или недействителен

• HTTP-ошибки: Подробные коды состояния HTTP и сообщения ответа

• Ошибки проверки: Проверка параметров с полезными сообщениями об ошибках

• Сетевые ошибки: Обработка тайм-аутов и ошибок соединения

Конечные точки API

Этот MCP-сервер взаимодействует со следующими конечными точками Ambivo API:

/entity/natural_query

• Метод: POST

• Назначение: Обработка запросов на естественном языке для получения данных сущностей

• Аутентификация: Требуется (JWT Bearer-токен)

• Content-Type: application/json

/entity/data

• Метод: POST

• Назначение: Прямой доступ к данным сущностей со структурированными параметрами

• Аутентификация: Требуется (JWT Bearer-токен)

• Content-Type: application/json

Пример рабочего процесса

1. Установка аутентификации:

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

2. Запрос на естественном языке:

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

3. Прямой запрос сущности:

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

Разработка

Чтобы расширить этот MCP-сервер:

1. Добавление новых инструментов: Реализуйте дополнительные инструменты в функциях handle_list_tools() и handle_call_tool()

2. Изменение API-клиента: Расширьте класс AmbivoAPIClient для поддержки дополнительных конечных точек

3. Обновление конфигурации: Измените настройки по умолчанию в разделе конфигурации

Устранение неполадок

Распространенные проблемы:

1. Ошибка "Authentication required": Убедитесь, что вы сначала вызвали set_auth_token

2. Ошибки HTTP 401/403: Проверьте, что ваш JWT-токен действителен и не истек

3. Тайм-аут соединения: Проверьте сетевое подключение и доступность конечной точки API

4. Недопустимые параметры: Просмотрите схемы инструментов для обязательных и необязательных параметров

Журналирование:

Сервер регистрирует важные события и ошибки. Проверьте вывод консоли для отладочной информации.