amplitude-automation

通过 Rube MCP 自动化 Amplitude

通过 Rube MCP 使用 Composio 的 Amplitude 工具包自动化 Amplitude 产品分析。

工具包文档：composio.dev/toolkits/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、邮箱或 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 界面中配置；API 提供只读访问
• 类别中的事件名称区分大小写
• 发送事件前，可使用这些类别验证 event_type 值

常见模式

ID 解析

应用 user_id -> Amplitude 内部 ID：

1. Call AMPLITUDE_FIND_USER with user=your_user_id
2. Extract Amplitude's internal user ID from response
3. Use internal ID for GET_USER_ACTIVITY

群组名称 -> 群组 ID：

1. Call AMPLITUDE_LIST_COHORTS
2. Find cohort by name in results
3. Extract id for cohort operations

用户属性操作

Amplitude IDENTIFY 支持以下属性操作：

• $set：设置属性值（覆盖现有值）
• $setOnce：仅在属性尚未设置时设置
• $add：递增数值型属性
• $append：向列表属性追加内容
• $unset：完全移除属性

示例结构：

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

异步操作模式

对于群组成员更新：

1. Call AMPLITUDE_UPDATE_COHORT_MEMBERSHIP -> get request_id
2. Call AMPLITUDE_CHECK_COHORT_STATUS with request_id
3. Repeat step 2 until status is 'complete' or 'error'

已知注意事项

用户 ID：

• Amplitude 使用自己的内部用户 ID，与应用中的用户 ID 不同
• FIND_USER 可将你的 ID 解析为 Amplitude 内部 ID
• GET_USER_ACTIVITY 需要 Amplitude 内部 ID，而非你的 user_id

事件时间戳：

• 必须使用自纪元起算的毫秒数（13 位数字）
• 秒数（10 位数字）会被解释为非常久远的日期
• 省略时间戳时，将使用服务器接收时间

速率限制：

• 每个项目的事件摄取吞吐量有限制
• 尽可能批量发送事件，以减少 API 调用
• 群组成员更新受异步处理限制

响应解析：

• 响应数据可能嵌套在 data 键下
• 用户活动中的事件按时间倒序返回
• 群组列表可能包含已归档的群组；请检查状态字段
• 对可选字段进行解析时，请采用防御式处理并提供回退方案

快速参考

任务	工具标识	关键参数
发送事件	AMPLITUDE_SEND_EVENTS	events（数组）
查找用户	AMPLITUDE_FIND_USER	user
获取用户活动	AMPLITUDE_GET_USER_ACTIVITY	user, offset, limit
识别用户	AMPLITUDE_IDENTIFY	user_id, user_properties
列出群组	AMPLITUDE_LIST_COHORTS	（无）
获取群组	AMPLITUDE_GET_COHORT	cohort_id
更新群组成员	AMPLITUDE_UPDATE_COHORT_MEMBERSHIP	cohort_id, memberships
检查群组状态	AMPLITUDE_CHECK_COHORT_STATUS	request_id
列出事件类别	AMPLITUDE_GET_EVENT_CATEGORIES	（无）

---

由 Composio 提供支持