Amplitude 自动化

通过 Rube MCP 实现 Amplitude 自动化

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

前置条件

• 必须连接 Rube MCP（RUBE_SEARCH_TOOLS 可用）

• 通过 RUBE_MANAGE_CONNECTIONS 建立了活跃的 Amplitude 连接，工具集为 amplitude

• 始终先调用 RUBE_SEARCH_TOOLS 以获取当前的工具 Schema

安装配置

获取 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: 事件对象数组，每个对象包含：

常见坑点：

• 每个事件必须至少提供 user_id 或 device_id 其中之一

• 每个事件必须包含 event_type，且不能为空

• time 必须是毫秒（13 位 epoch），而非秒

• 存在批处理限制；请检查 Schema 以确认每次请求的最大事件数

• 事件是异步处理的；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：

• 对于 IDENTIFY：

常见坑点：

• FIND_USER 会在 user_id, device_id 和 Amplitude ID 中进行搜索

• IDENTIFY 使用特殊的属性操作（$set, $unset, $add, $append）

• $set 覆盖现有值；$setOnce 仅在属性未设置时进行设置

• IDENTIFY 至少需要 user_id 或 device_id 其中之一

• 用户属性的更改是最终一致性的，而非立即生效

4. 管理人群 (Cohorts)

使用场景：用户想要列出人群、查看人群详情或更新人群成员身份

工具序列：
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：

• CHECK_COHORT_STATUS：更新响应中的 request_id

注意事项：

• 所有人群相关操作都需要人群 ID

• UPDATE_COHORT_MEMBERSHIP 是异步的；请使用 CHECK_COHORT_STATUS 进行验证

• 状态检查需要更新响应中返回的 request_id

• 每次请求的成员变更数量可能有上限；请对大规模更新进行分片处理

• 仅行为人群 (behavioral cohorts) 支持通过 API 更新成员身份

5. 浏览事件类别

使用场景：用户想要发现 Amplitude 中可用的事件类型和类别

工具序列：
1. AMPLITUDE_GET_EVENT_CATEGORIES - 列出所有事件类别 [必选]

关键参数：

• 无必填参数；返回所有配置的事件类别

注意事项：

• 类别在 Amplitude UI 中配置；API 提供只读访问

• 类别中的事件名称区分大小写

• 在发送事件前，可使用这些类别来验证 event_type 的值

常见模式

ID 解析

应用 user_id -> Amplitude 内部 ID：

1. 调用 AMPLITUDE_FIND_USER，参数 user=your_user_id
2. 从响应中提取 Amplitude 的内部用户 ID
3. 在 GET_USER_ACTIVITY 中使用该内部 ID

人群名称 -> 人群 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

• FIND_USER 将您的 ID 解析为 Amplitude 的内部 ID

• GET_USER_ACTIVITY 需要 Amplitude 的内部 ID，而非您的 user_id

事件时间戳：

• 必须是自 epoch 以来的毫秒数（13 位）

• 秒数（10 位）将被解释为非常久远的日期

• 若省略时间戳，则使用服务器接收时间

速率限制：

• 每个项目的事件摄入都有吞吐量限制

• 建议对事件进行批处理

• 可减少 API 调用次数

• Cohort 成员更新存在异步处理限制

响应解析：

• 响应数据可能嵌套在 data 键下

• 用户活动按时间反序返回事件

• Cohort 列表可能包含已归档的 Cohort；请检查 status 字段

• 采用防御性解析，为可选字段提供回退方案

快速参考

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

使用场景

局限性

• 仅在任务明确符合上述范围时使用此技能。

• 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。

• 如果缺失必要输入、权限、安全边界或成功标准，请停止操作并请求澄清。