amplitude-automation

Rube MCP による Amplitude の自動化

Rube MCP を通じて Composio の Amplitude ツールキットを使用し、Amplitude のプロダクト分析を自動化します。

ツールキットのドキュメント：composio.dev/toolkits/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 - 1 つ以上のイベントを Amplitude に送信します［必須］

主なパラメーター：

• 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 桁のエポック値）で指定する必要があります
• バッチ上限が適用されます。1 リクエストあたりの最大イベント数はスキーマで確認してください
• イベントは非同期で処理されます。API が成功を返しても、データをすぐにクエリできるとは限りません

2. ユーザーアクティビティを取得する

使用する場面：ユーザーが特定のユーザーのイベント履歴を確認したい場合

ツールの順序：

1. AMPLITUDE_FIND_USER - ID またはプロパティでユーザーを検索します［前提条件］
2. AMPLITUDE_GET_USER_ACTIVITY - ユーザーのイベントストリームを取得します［必須］

主なパラメーター：

• user：Amplitude の内部ユーザー ID（FIND_USER から取得）
• offset：イベントリストのページネーションオフセット
• limit：返すイベントの最大数

注意点：

• user パラメーターには Amplitude の内部ユーザー ID が必要です。アプリケーションの user_id ではありません
• アプリケーションの user_id を Amplitude の内部 ID に解決するため、先に FIND_USER を呼び出す必要があります
• デフォルトでは、アクティビティは新しい順に返されます
• アクティビティ履歴が多い場合は、offset を使ったページネーションが必要です

3. ユーザーを検索して識別する

使用する場面：ユーザーがユーザーの検索やユーザープロパティの設定を希望する場合

ツールの順序：

1. AMPLITUDE_FIND_USER - さまざまな識別子でユーザーを検索します［必須］
2. AMPLITUDE_IDENTIFY - ユーザープロパティを設定または更新します［任意］

主なパラメーター：

• FIND_USER の場合：
  • user：検索語（user_id、メールアドレス、または 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 が必要です
• 1 回のリクエストで変更できるメンバーシップ数には上限がある場合があります。大量の更新は分割してください
• 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 には、ユーザーの 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	（なし）

---

Composio によって提供