amplitude-automation

通过 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. 使用工具包 amplitude 调用 RUBE_MANAGE_CONNECTIONS
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：事件时间戳，以自 epoch 起的毫秒数表示

注意事项：

• 每个事件至少需要 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：
  • 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. 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

事件时间戳：

• 必须是自 epoch 以来的毫秒数（13 位数字）
• 秒数（10 位数字）会被解释为非常久远的日期
• 省略时间戳时会使用服务器接收时间

速率限制：

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

响应解析：

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

快速参考

任务	工具 Slug	关键参数
发送事件	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	（无）

使用场景

此技能适用于执行概述中描述的工作流或操作。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。