Ambivo MCP Server

🚀 Ambivo Claude MCP 服務器

Ambivo Claude MCP（模型上下文協議）服務器提供了訪問 Ambivo API 端點的功能，可藉助 Claude AI 對實體數據進行自然語言查詢。

✨ 主要特性

• 自然語言查詢：通過 /entity/natural_query 端點對實體數據執行自然語言查詢。
• JWT 身份驗證：使用 Bearer 令牌身份驗證確保訪問安全。
• 速率限制：內置速率限制，防止 API 被濫用。
• 令牌緩存：通過緩存實現高效的令牌驗證。
• 錯誤處理：全面的錯誤處理，提供詳細的錯誤消息。
• 重試邏輯：對於失敗的請求，採用指數退避策略自動重試。

🛠️ 工具

1. set_auth_token

設置用於與 Ambivo API 進行身份驗證的 JWT Bearer 令牌。

• 參數：
  • 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"
}

📋 關於

這是一個基於 Claude 的純 MCP 服務器實現，用於 Ambivo API，旨在與 Claude Desktop 和其他兼容 Claude 的 MCP 客戶端無縫協作。它通過 Claude 強大的語言理解能力，實現與 Ambivo CRM 數據的自然語言交互。

📦 安裝指南

選項 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 .

💻 運行服務器

# 如果通過 pip 安裝
ambivo-mcp-server

# 或者使用 Python 模塊
python -m ambivo_mcp_server.server

⚙️ 配置

服務器使用以下默認配置：

如有需要，您可以在 AmbivoAPIClient 類中修改這些設置。

🔑 身份驗證

1. 首先，使用 set_auth_token 工具設置您的身份驗證令牌。
2. 該令牌將作為 Bearer 令牌包含在所有後續 API 請求中。
3. 該令牌應為來自 Ambivo API 身份驗證的有效 JWT 令牌。

🚫 錯誤處理

服務器提供全面的錯誤處理：

• 身份驗證錯誤：當令牌缺失或無效時，會顯示清晰的消息。
• HTTP 錯誤：提供詳細的 HTTP 狀態代碼和響應消息。
• 驗證錯誤：對參數進行驗證，並提供有用的錯誤消息。
• 網絡錯誤：處理超時和連接錯誤。

📡 API 端點

此 MCP 服務器與以下 Ambivo API 端點進行交互：

/entity/natural_query

• 方法：POST
• 目的：處理自然語言查詢，以檢索實體數據。
• 身份驗證：必需（JWT Bearer 令牌）
• 內容類型：application/json

/entity/data

• 方法：POST
• 目的：通過結構化參數直接訪問實體數據。
• 身份驗證：必需（JWT Bearer 令牌）
• 內容類型：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. 參數無效：查看工具架構，瞭解必需和可選參數。

日誌記錄

服務器會記錄重要事件和錯誤。請檢查控制檯輸出以獲取調試信息。