posthog-automation

通过 Rube MCP 实现 PostHog 自动化

通过 Rube MCP 使用 Composio 的 PostHog 工具包，实现 PostHog 产品分析和功能标志管理。

工具包文档：composio.dev/toolkits/posthog

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 PostHog 连接，并使用工具包 posthog
• 始终先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

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

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 已就绪
2. 使用工具包 posthog 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 PostHog 身份验证
4. 在运行任何工作流之前，确认连接状态显示为 ACTIVE

核心工作流

1. 捕获事件

适用场景：用户想要向 PostHog 发送事件数据以进行分析跟踪

工具调用顺序：

1. POSTHOG_CAPTURE_EVENT - 向 PostHog 发送一个或多个事件［必需］

关键参数：

• event：事件名称（例如，'$pageview'、'user_signed_up'、'purchase_completed'）
• distinct_id：用户唯一标识符（必需）
• properties：包含事件特定属性的对象
• timestamp：ISO 8601 时间戳（可选；默认为服务端时间）

注意事项：

• 每个事件都必须提供 distinct_id；它用于标识用户/设备
• PostHog 系统事件使用 $ 前缀（例如，'$pageview'、'$identify'）
• 自定义事件不应使用 $ 前缀
• 属性可自由定义；请确保不同事件的架构一致
• 事件采用异步处理；摄取延迟通常为几秒

2. 列出和筛选事件

适用场景：用户想要浏览或搜索已捕获的事件

工具调用顺序：

1. POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS - 使用筛选条件查询事件［必需］

关键参数：

• project_id：PostHog 项目 ID（必需）
• event：按事件名称筛选
• person_id：按人员 ID 筛选
• after：此 ISO 8601 时间戳之后的事件
• before：此 ISO 8601 时间戳之前的事件
• limit：要返回的最大事件数
• offset：分页偏移量

注意事项：

• 必须提供 project_id；请先通过 LIST_PROJECTS 获取
• 日期筛选条件使用 ISO 8601 格式（例如，'2024-01-15T00:00:00Z'）
• 事件量较大时需要分页；请使用 offset 和 limit
• 默认按时间倒序返回结果
• 事件属性采用嵌套结构；请谨慎解析

3. 管理功能标志

适用场景：用户想要创建、查看或管理功能标志

工具调用顺序：

1. POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS - 列出现有功能标志［必需］
2. POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS - 获取标志配置详情［可选］
3. POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT - 创建新的功能标志［可选］

关键参数：

• 列表操作：project_id（必需）
• 查看详情：project_id、id（功能标志 ID）
• 创建操作：
  • project_id：目标项目
  • key：标志键（例如，'new-dashboard-beta'）
  • name：易于理解的名称
  • filters：定向规则和发布百分比
  • active：标志是否已启用

注意事项：

• 功能标志 key 在项目内必须唯一
• 标志键应使用 kebab-case（例如，'my-feature-flag'）
• filters 用于定义带有属性和发布百分比的定向用户组
• 使用 active: true 创建标志后，会立即向符合条件的用户启用该标志
• 由于 PostHog 的轮询机制，标志更改会在几秒内生效

4. 管理项目

适用场景：用户想要列出或查看 PostHog 项目和组织

工具调用顺序：

1. POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION - 列出所有项目［必需］

关键参数：

• organization_id：组织标识符（根据身份验证设置可能是可选项）
• limit：每页结果数量
• offset：分页偏移量

注意事项：

• 项目 ID 为数字；大多数其他端点都将其用作参数
• 可能需要组织 ID；请检查 PostHog 设置
• 分页基于偏移量；持续迭代，直到结果为空
• 项目设置包含 API 密钥和配置详情

5. 用户资料和身份验证

适用场景：用户想要查看当前用户详情或验证 API 访问权限

工具调用顺序：

1. POSTHOG_WHOAMI - 获取当前 API 用户信息［可选］
2. POSTHOG_RETRIEVE_CURRENT_USER_PROFILE - 获取详细的用户资料［可选］

关键参数：

• 两个调用都不需要必填参数
• 返回当前已验证身份的用户详情、权限和组织信息

注意事项：

• WHOAMI 是轻量级检查；可用于验证 API 连接
• 用户资料包含组织成员身份和权限
• 这些端点可确认 API 密钥的访问级别和范围

常见模式

ID 解析

组织 -> 项目 ID：

1. Call POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
2. Find project by name in results
3. Extract id (numeric) for use in other endpoints

功能标记名称 -> 标记 ID：

1. Call POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS with project_id
2. Find flag by key or name
3. Extract id for detailed operations

功能标记定向

功能标记支持复杂的定向规则：

{
  "filters": {
    "groups": [
      {
        "properties": [
          {"key": "email", "value": "@company.com", "operator": "icontains"}
        ],
        "rollout_percentage": 100
      },
      {
        "properties": [],
        "rollout_percentage": 10
      }
    ]
  }
}

• 按顺序评估各组；第一个匹配的组决定发布情况
• 属性根据用户特征筛选用户
• 发布百分比决定匹配用户中有多少比例会看到此标记

分页

• 事件：使用 offset 和 limit（基于偏移量）
• 功能标记：使用 offset 和 limit（基于偏移量）
• 项目：使用 offset 和 limit（基于偏移量）
• 持续获取结果，直到结果数组为空或小于 limit

已知注意事项

项目 ID：

• 大多数 API 端点都需要项目 ID
• 始终先将项目名称解析为数字 ID
• 一个组织中可以有多个项目

事件命名：

• 系统事件使用 $ 前缀（$pageview、$identify、$autocapture）
• 自定义事件不应使用 $ 前缀
• 事件名称区分大小写；请保持一致

功能标记：

• 同一项目中的标记键必须唯一
• 标记键使用 kebab-case 格式
• 更改会在几秒内生效
• 删除标记不可撤销；建议改为停用

速率限制：

• 事件写入吞吐量有限制
• 尽可能批量发送事件以提高效率
• API 端点有每分钟速率限制

响应解析：

• 响应数据可能嵌套在 data 或 results 键下
• 分页响应包含 count、next、previous 字段
• 事件属性是嵌套对象；请谨慎访问
• 使用备用值对可选字段进行防御性解析

快速参考

任务	工具别名	关键参数
捕获事件	POSTHOG_CAPTURE_EVENT	event, distinct_id, properties
列出事件	POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS	project_id, event, after, before
列出功能标记	POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS	project_id
获取标记详情	POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS	project_id, id
创建标记	POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT	project_id, key, filters
列出项目	POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION	organization_id
我是谁	POSTHOG_WHOAMI	(none)
用户资料	POSTHOG_RETRIEVE_CURRENT_USER_PROFILE	(none)

---

由 Composio 提供支持