名称： amplitude-automation
描述： "通过 Rube MCP (Composio) 自动化 Amplitude 任务：事件发送、用户活动、用户分群、用户识别。请务必先搜索工具以获取最新模式。"
requires:
mcp: [rube]

通过 Rube MCP 自动化 Amplitude

通过 Composio 的 Amplitude 工具包和 Rube MCP，实现 Amplitude 产品分析的自动化。

前提条件

• Rube MCP 必须已连接（RUBE_SEARCH_TOOLS 可用）
• 通过 RUBE_MANAGE_CONNECTIONS 建立活跃的 Amplitude 连接，并指定工具包 amplitude
• 始终先调用 RUBE_SEARCH_TOOLS 以获取最新的工具模式

设置

获取 Rube MCP：在您的客户端配置中将 https://rube.app/mcp 添加为 MCP 服务器。无需 API 密钥，只需添加端点即可使用。

1. 通过确认 RUBE_SEARCH_TOOLS 有响应，验证 Rube MCP 是否可用。
2. 调用 RUBE_MANAGE_CONNECTIONS，指定工具包 amplitude。
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 Amplitude 身份验证。
4. 在运行任何工作流之前，确认连接状态显示为 ACTIVE。

核心工作流

1. 发送事件

使用场景：用户希望跟踪事件或将事件数据发送到 Amplitude。

工具调用顺序：
1. AMPLITUDE_SEND_EVENTS - 向 Amplitude 发送一个或多个事件 [必需]

关键参数：
- events：事件对象数组，每个对象包含：
- event_type：事件名称（例如 page_view、purchase）
- user_id：唯一用户标识符（若无 device_id 则必需）
- device_id：设备标识符（若无 user_id 则必需）
- event_properties：包含自定义事件属性的对象
- user_properties：包含要设置的用户属性的对象
- time：事件时间戳（自纪元以来的毫秒数）

注意事项：
- 每个事件至少需要提供 user_id 或 device_id 之一。
- 每个事件都必须有 event_type，且不能为空。
- time 必须为毫秒（13位纪元时间戳），而非秒。
- 存在批量限制；请检查模式以了解每次请求的最大事件数。
- 事件处理是异步的；成功的 API 响应并不意味着数据立即可查询。

2. 获取用户活动

使用场景：用户希望查看特定用户的事件历史记录。

工具调用顺序：
1. AMPLITUDE_FIND_USER - 通过 ID 或属性查找用户 [先决条件]
2. AMPLITUDE_GET_USER_ACTIVITY - 检索用户的事件流 [必需]

关键参数：
- user：Amplitude 内部用户 ID（来自 FIND_USER）
- offset：事件列表的分页偏移量
- limit：要返回的最大事件数

注意事项：
- user 参数需要 Amplitude 的内部用户 ID，不是您应用程序的 user_id。
- 必须先调用 FIND_USER，将您的 user_id 解析为 Amplitude 的内部 ID。
- 默认情况下，活动记录按时间倒序返回。
- 大量的活动历史记录需要通过 offset 进行分页处理。

3. 查找与识别用户

使用场景：用户希望查找用户或设置用户属性。

工具调用顺序：
1. AMPLITUDE_FIND_USER - 通过各种标识符搜索用户 [必需]
2. AMPLITUDE_IDENTIFY - 设置或更新用户属性 [可选]

关键参数：
- FIND_USER：
- user：搜索词（user_id、email 或 Amplitude ID）
- IDENTIFY：
- user_id：您应用程序的用户标识符
- device_id：设备标识符（可作为 user_id 的替代）
- user_properties：包含 $set、$unset、$add、$append 操作的对象

注意事项：
- FIND_USER 会在 user_id、device_id 和 Amplitude ID 中搜索。
- IDENTIFY 使用特殊的属性操作符（$set、$unset、$add、$append）。
- $set 会覆盖现有值；$setOnce 仅在属性未设置时才设置。
- IDENTIFY 至少需要 user_id 或 device_id 之一。
- 用户属性更改是最终一致的，并非立即生效。

4. 管理用户分群

使用场景：用户希望列出分群、查看分群详情或更新分群成员。

工具调用顺序：
1. AMPLITUDE_LIST_COHORTS - 列出所有已保存的分群 [必需]
2. AMPLITUDE_GET_COHORT - 获取分群的详细信息 [可选]
3. AMPLITUDE_UPDATE_COHORT_MEMBERSHIP - 向分群添加/移除用户 [可选]
4. AMPLITUDE_CHECK_COHORT_STATUS - 检查异步分群操作状态 [可选]

关键参数：
- LIST_COHORTS：无必需参数。
- GET_COHORT：cohort_id（来自列表结果）。
- UPDATE_COHORT_MEMBERSHIP：
- cohort_id：目标分群 ID
- memberships：包含 add 和/或 remove 用户 ID 数组的对象
- CHECK_COHORT_STATUS：来自更新响应的 request_id

注意事项：
- 所有分群特定操作都需要分群 ID。
- UPDATE_COHORT_MEMBERSHIP 是异步操作；使用 CHECK_COHORT_STATUS 来验证。
- 需要更新响应中的 request_id 来检查状态。
- 每次请求的成员变更数量可能有限制；对于大量更新请分批处理。
- 只有行为分群支持通过 API 更新成员。

5. 浏览事件分类

使用场景：用户希望发现 Amplitude 中可用的事件类型和分类。

工具调用顺序：
1. AMPLITUDE_GET_EVENT_CATEGORIES - 列出所有事件分类 [必需]

关键参数：
- 无必需参数；返回所有已配置的事件分类。

注意事项：
- 分类在 Amplitude UI 中配置；API 提供读取访问权限。
- 分类内的事件名称区分大小写。
- 发送事件前，可使用这些分类来验证 event_type 值。

常用模式

ID 解析

应用程序 user_id -> Amplitude 内部 ID：

1. 使用 user=您的_user_id 调用 AMPLITUDE_FIND_USER
2. 从响应中提取 Amplitude 的内部用户 ID
3. 将内部 ID 用于 GET_USER_ACTIVITY

分群名称 -> 分群 ID：

1. 调用 AMPLITUDE_LIST_COHORTS
2. 在结果中按名称查找分群
3. 提取分群操作的 id

用户属性操作

Amplitude 的 IDENTIFY 支持以下属性操作：
- $set：设置属性值（覆盖现有值）
- $setOnce：仅在属性未设置时设置
- $add：增加数值属性
- $append：向列表属性追加元素
- $unset：完全移除属性

示例结构：

{
  "user_properties": {
    "$set": {"plan": "premium", "company": "Acme"},
    "$add": {"login_count": 1}
  }
}

异步操作模式

用于分群成员更新：

1. 调用 AMPLITUDE_UPDATE_COHORT_MEMBERSHIP -> 获取 request_id
2. 使用 request_id 调用 AMPLITUDE_CHECK_COHORT_STATUS
3. 重复步骤 2，直到状态为 'complete' 或 'error'

已知注意事项

用户 ID：
- Amplitude 拥有其自己的内部用户 ID，与您应用程序的 ID 不同。
- FIND_USER 将您的 ID 解析为 Amplitude 的内部 ID。
- GET_USER_ACTIVITY 需要 Amplitude 的内部 ID，而不是您的 user_id。

事件时间戳：
- 必须是自纪元以来的毫秒数（13位数字）。
- 秒（10位数字）将被解释为非常旧的日期。
- 省略时间戳将使用服务器接收时间。

速率限制：
- 事件摄取有每个项目的吞吐量限制。
- 尽可能批量发送事件以减少 API 调用次数。
- 分群成员更新有异步处理限制。

响应解析：
- 响应数据可能嵌套在 data 键下。
- 用户活动返回的事件默认按时间倒序排列。
- 分群列表可能包含已归档的分群；请检查 status 字段。
- 解析时需谨慎，为可选字段提供回退方案。

快速参考