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

⚙️ 配置

服务器使用以下默认配置： | 属性 | 详情 | | ---- | ---- | | 基础 URL | https://goferapi.ambivo.com | | 超时时间 | 30 秒 | | 内容类型 | application/json |

如有需要，您可以在 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. 参数无效：查看工具架构，了解必需和可选参数。

日志记录

服务器会记录重要事件和错误。请检查控制台输出以获取调试信息。