amplitude-automation

Rube MCP による Amplitude 自動化

Rube MCP を介して、Composio の Amplitude ツールキットによる Amplitude プロダクト分析を自動化します。

前提条件

• Rube MCP が接続されている必要があります（RUBE_SEARCH_TOOLS が利用可能）
• ツールキット amplitude を指定した RUBE_MANAGE_CONNECTIONS による有効な Amplitude 接続
• 最新のツールスキーマを取得するため、常に最初に RUBE_SEARCH_TOOLS を呼び出してください

セットアップ

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 に 1 つ以上のイベントを送信します [必須]

主要なパラメータ:

• 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 パラメータには、アプリケーションの user_id ではなく、Amplitude の内部ユーザー 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: ユーザー ID の add および/または remove 配列を持つオブジェクト
• 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 があります
• FIND_USER は、あなたの ID を Amplitude の内部 ID に解決します
• GET_USER_ACTIVITY には、あなたの user_id ではなく Amplitude の内部 ID が必要です

イベントのタイムスタンプ:

• エポックからのミリ秒 (13 桁) で指定する必要があります
• 秒 (10 桁) は非常に古い日付として解釈されます
• タイムスタンプを省略すると、サーバーの受信時刻が使用されます

レート制限:

• イベントの取り込みにはプロジェクトごとのスループット制限があります
• API 呼び出しを減らすため、可能な限りイベントをバッチ処理してください
• コホートのメンバーシップ更新には非同期処理の制限があります

レスポンスの解析:

• レスポンスデータは data キーの下にネストされている場合があります
• ユーザーアクティビティは、イベントを新しい順に返します
• コホートの一覧にはアーカイブされたコホートが含まれる場合があります。status フィールドを確認してください
• 任意のフィールドにはフォールバックを用意して、防御的に解析してください

クイックリファレンス

タスク	ツールスラッグ	主なパラメータ
イベントを送信	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	(なし)

使用する場面

このスキルは、概要に記載されているワークフローまたはアクションを実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記のスコープに明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、成功基準が欠けている場合は、作業を中断して確認を求めてください。