Amplitude MCP 分析設定
為 MCP 伺服器加入監控，讓每次工具呼叫都成為 Amplitude 事件，並可與產品中其他 Amplitude 資料（留存率、收益、網頁/行動端使用數據）串聯。
權威的 SDK 參考資料是套件 README：
https://github.com/amplitude/Amplitude-MCP-Analytics-Node (npm: @amplitude/mcp-analytics)
SDK 仍處於預覽階段且快速演進 — 務必擷取最新的 README 並遵循其安裝、API 格式、設定與預設事件說明。 請勿依賴記憶中的程式碼片段或本技能的摘要來取得 SDK API 細節；若有衝突，以 README 為準。
總共四個步驟。步驟 1-2 為必要步驟，已記錄在 README 中 — 本技能會告訴你該遵循哪些章節，以及需驗證哪些不變條件。步驟 3-4 為強烈建議步驟，此處提供完整說明，因為它們需要變更 SDK 外部的內容（伺服器的工具結構定義與產品的網頁應用程式），而 SDK README 特意未涵蓋這些部分。
請依序執行：步驟 1（工具呼叫） → 步驟 2（身份識別） → 步驟 3（推理過程） → 步驟 4（UTM，僅當伺服器回傳連結時）。在正確設定身份識別前，切勿宣稱「完成」— 下游所有環節都依賴於此。
開始之前
確認：
- 這是一個以
@modelcontextprotocol/sdk為基礎的 Node/TypeScript MCP 伺服器。此 SDK 不支援其他語言或執行環境。 - 使用者擁有（或可以取得）一個 Amplitude API 金鑰，用於指定事件歸屬的專案。
- 該儲存庫使用的套件管理器（pnpm/npm/yarn）— 據此調整安裝指令。
步驟 1 — 安裝 SDK 並追蹤工具呼叫（必要）
擷取 README 並遵循其安裝與快速入門章節。務必安裝最新發行版本（例如 pnpm add @amplitude/mcp-analytics@latest）— 切勿根據記憶鎖定版本，也不要複製本技能中的安裝指令。
設定完成後需驗證的不變條件（README 會逐一說明）：
analytics.instrumentServer(server, ...)必須在server.connect()之前執行 — 順序很重要。- 每個工具處理函式都應以
analytics.instrumentTool(...)包裹。未包裹的工具將不會被追蹤。該包裹器的形狀與處理函式相同，且若伺服器從未綁定，則為無操作傳遞，因此防禦性地包裹是安全的。 - 所有預設事件都帶有
[MCP]前綴，因此絕不會與產品既有的 Amplitude 事件衝突。請參閱 README 的預設事件表格（以及儲存庫中的docs/events.md）以取得目前的事件集合與屬性。
可選：透過 instrumentTool/instrumentServer 的 extra 參數附加穩定的自訂維度（方案層級、團隊、功能標誌） — 請參閱 README 的自訂事件屬性章節。
步驟 2 — 正確設定身份識別（必要，在宣告步驟 1「完成」前執行此步驟）
MCP 事件必須攜帶與產品在網頁/行動端已傳送至 Amplitude 的相同 user_id。跳過此步驟會導致 MCP 使用數據顯示為一個孤立的群體，無法與產品資料串聯 — 這將破壞整合的大部分價值。
請遵循 README 的身份識別章節以取得目前的 API：它提供伺服器層級的綁定、處理函式內的每次請求 setIdentity()，以及從請求的 authInfo 宣告中進行對應的可選 resolveIdentity。選擇適合該伺服器驗證模型的方式。
需要向使用者說明的一件事：完全匿名、無錨點的事件預設會被丟棄（不計為使用者），除非透過 emitAnonymousEvent: true 明確選擇加入以進行僅彙總追蹤 — 在開啟此選項前請先詢問使用者，因為這會改變計數方式。
步驟 3 — 擷取推理過程（建議）
與人類點擊按鈕不同，代理程式可以告訴你它為何呼叫某個工具。擷取這個資訊能將數據從「發生了什麼事」轉變為「使用者想達成什麼目的」。
SDK 端只需一次呼叫（analytics.setRationale(...) — 請參閱 README 的推理過程章節），但 SDK 本身不會從工具輸入中讀取推理過程：推理過程如何到達伺服器是此技能實作的伺服器端慣例。 經過驗證的模式是結構注入 — 在每個工具的輸入結構中加入一個可選的 rationale 欄位。由於參數已寫入代理程式會讀取的結構中，它們會在所有用戶端上自動填入，無需任何用戶端變更：
// 加入至每個工具的輸入結構（zod 範例）：
rationale: z
.string()
.optional()
.describe(
'簡短說明你為何呼叫此工具，以及你期望從結果中學到什麼。',
),
然後在已包裹的處理函式中讀取它，並傳遞給 SDK：
analytics.instrumentTool(async (args, extra) => {
if (typeof args.rationale === 'string') {
analytics.setRationale(args.rationale);
}
return doWork(args);
}, { name: 'search' });
將該欄位設為可選，表示當代理程式省略時不會造成任何問題。它會以保留的 [MCP] Rationale 屬性發出（截斷至 1,000 個字元；最後寫入的值優先）。建議對每個工具都這麼做，而不只是抽樣。
步驟 4 — 為外部連結加上 UTM 標籤（建議，僅當伺服器回傳 URL 時）
此步驟完全在 SDK 外部 — 它會改變伺服器建構 URL 的方式，且依賴於產品的網頁端分析。SDK README 未涵蓋此部分。
如果任何工具回應包含連結（儀表板、文件、產品頁面），請在它離開伺服器前加上標籤，以便將點擊歸因於 MCP/代理程式流量，而非顯示為直接流量：
function addUtmParams(url: string, clientName?: string): string {
const u = new URL(url);
u.searchParams.append('utm_source', 'mcp');
u.searchParams.append('utm_medium', 'referral');
// 連線的用戶端（例如 "Claude"、"Cursor"），如果你知道的話：
u.searchParams.append('utm_content', clientName ?? 'unknown');
return u.toString();
}
將工具回應中所有建構 URL 的路徑都透過一個這樣的集中函式處理 — 任何一個未加標籤的連結都會破壞該流程的歸因。
必要條件（明確告知使用者）： 這只有在他們的網頁分析工具能在頁面瀏覽事件（或他們的網站著陸時觸發的任何事件）中擷取 UTM 參數時才有效。Amplitude 的 Browser SDK 2 預設會這樣做 — 請參閱追蹤行銷歸因（UTM、參照來源和點擊 ID 參數預設會被擷取）。如果他們使用自訂的頁面瀏覽追蹤器，他們需要確認 UTM 值也會出現在那些事件上，否則就沒有東西可以與 MCP 標籤的點擊進行串聯。
相關的 Amplitude 文件：
- Browser SDK 2 — 追蹤行銷歸因（網頁端的 UTM 擷取，此步驟的實作部分）
- 工作階段、管道與行銷分析歸因（標籤流量如何變成管道分析）
- 自動擷取（頁面瀏覽及其他）
完成監控後
一旦事件開始流動，請引導程式碼代理程式前往 Amplitude 已發佈的 analyze-mcp-server 技能，以執行意圖分群並依意圖呈現工具呼叫錯誤模式。（如果此專案已安裝 mcp-intent-error-analysis 技能，那就是要使用的技能 — 一旦使用者有數據流動並想要分析時，就使用它，而不是在此處重複該分析。）
需標記的常見錯誤
- 遵循過時的 API 片段而非最新的 README — 請重新擷取；SDK 處於預覽階段且快速變動。
- 安裝鎖定/舊版而非最新版本。
- 在
server.connect()之後呼叫instrumentServer()— 必須在此之前。 - 包裹部分工具處理函式但遺漏其他 — 每個工具都需要
instrumentTool。 - 傳送的
user_id與網頁/行動端使用的不同 — 破壞資料串聯性，這是整合的關鍵。 - 在未經使用者理解的情況下開啟
emitAnonymousEvent: true，這會以無錨點流量膨脹彙總計數。 - 忘記 UTM 必要條件（網頁端擷取），並假設僅標籤連結就足夠。