📦 Amplitude Automation — Amplitude自动化

# 通过 Rube MCP 实现 Amplitude 自动化 借助 Composio 的 Amplitude toolkit，通过 Rube MCP 自动化产品分析操作。 ## 前置条件 - 已连接 Rube MCP（可用 RUBE_SEARCH_TOOLS） - 通过 RUBE_MANAGE_CONNECTIONS 激活 toolkit 为 amplitude 的 Amplitude 连接 - 任何操作前务必先调用 RUBE_SEARCH_TOOLS 获取最新工具 schema ## 安装 获取 Rube MCP：在客户端配置里把 https://rube.app/mcp 添加为 MCP server。无需 API key，只需添加端点即可生效。 1. 确认 RUBE_SEARCH_TOOLS 能正常返回，验证 Rube MCP 已就绪 2. 调用 RUBE_MANAGE_CONNECTIONS，toolkit 指定为 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：事件时间戳，毫秒级 Unix 时间 易错点： - 每个事件必须至少含 user_id 或 device_id - 所有事件必填 event_type，不能为空 - time 必须是毫秒（13 位），不能是秒 - 单批有上限，先查 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. 管理分群（Cohort） 使用场景：用户想列出分群、查看详情或修改成员 工具顺序： 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 易错点： - 所有分群操作都需提供 cohort_id - UPDATE_COHORT_MEMBERSHIP 为异步，需用 CHECK_COHORT_STATUS 确认 - 检查状态时必须用更新接口返回的 request_id - 单次成员变更数有限，大量请分批 - 仅行为分群（behavioral cohort）支持 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 内部 user ID 3. 用该内部 ID 调 GET_USER_ACTIVITY ` 分群名称 → 分群 ID： ` 1. 调用 AMPLITUDE_LIST_COHORTS 2. 在结果里按名称找到分群 3. 提取 id 用于后续操作 ` ### 用户属性操作 Amplitude IDENTIFY 支持以下操作： - $set：设置属性值（覆盖旧值） - $setOnce：仅当属性不存在时设置 - $add：对数字属性做加法 - $append：往列表属性追加元素 - $unset：删除属性 示例结构： `json { "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' ` ## 已知坑 User IDs： - Amplitude 有独立的内部 user ID，与你系统 ID 不同 - FIND_USER 负责把你系统的 ID 解析成 Amplitude 内部 ID - GET_USER_ACTIVITY 必须用 Amplitude 内部 ID，而非你的 user_id 事件时间戳： - 必须是毫秒级 Unix 时间（13 位） - 用秒级（10 位）会被当成远古日期 - 不传时间戳则按服务器接收时间计算 速率限制： - 事件写入按项目有吞吐上限 - 尽量批量发送以减少 API 调用 - 分群成员异步更新也有处理上限 响应解析： - 返回数据可能嵌套在 data` 字段下 - 用户活动默认倒序返回 - 分群列表可能含已归档分群，注意 status 字段 - 对可选字段请做防御式解析 ## 速查表 | 任务 | 工具 Slug | 关键参数 | |------|-----------|------------| | 发送事件 | AMPLITUDE_SEND_EVENTS | events (array) | | 查找用户 | AMPLITUDE_FIND_USER | user | | 获取用户活动 | AMPLITUDE_GET_USER_ACTIVITY | user, offset, limit | | 识别用户 | AMPLITUDE_IDENTIFY | user_id, user_properties | | 列出分群 | AMPLITUDE_LIST_COHORTS | (none) | | 获取分群 | AMPLITUDE_GET_COHORT | cohort_id | | 更新分群成员 | AMPLITUDE_UPDATE_COHORT_MEMBERSHIP | cohort_id, memberships | | 检查分群状态 | AMPLITUDE_CHECK_COHORT_STATUS | request_id | | 列出事件分类 | AMPLITUDE_GET_EVENT_CATEGORIES | (none) |