分析 MCP 伺服器 — 意圖與錯誤分析
生成一份報告，回答關於已使用 Amplitude MCP Analytics SDK 進行儀器化的 MCP 伺服器的三個問題：
- 哪些工具被使用，哪些失敗了？（每個工具的使用量 + 錯誤率）
- 呼叫者對每個工具想做什麼，以及每個意圖在哪裡出錯？（每個工具內的請求意圖 × 錯誤訊息）
- 團隊應該優先修復什麼？（基於錯誤證據的修復，而非直覺）
這項分析的核心價值在於：工具定位修復範圍；意圖解釋背後動機。 整體錯誤率說「4.5% 的呼叫失敗」。按工具拆解後它說「query_chart 失敗了 22% 的時間」— 現在你知道要打開什麼。加上該工具內的意圖後它說「失敗來自儀表板重新整理的代理碰到批次大小限制」— 現在你知道原因，修復方案自動浮現。意圖在很大程度上是工具範圍的（每個工具都有自己的呼叫理由），因此工具是主要軸線，意圖是工具內的第二層切割 — 全域性地對意圖進行聚類只會重新推導出工具的邊界，同時混合了無法比較的意圖。
先決條件
-
Amplitude MCP 連接器必須啟用。如果未啟用，請停止並要求使用者在他們的工具/連接器設定中加入 Amplitude 連接器 — 沒有備用資料來源。
-
一個包含 SDK 事件的專案。SDK 會發送 SDK 擁有的預設事件，所有事件都以
[MCP]為前綴，並且 — 關鍵是 — 它們攜帶的每個預設屬性也都以[MCP]為前綴，它們可能還有自訂屬性。事件：
[MCP] Tool Call Response— 主力事件：每次呼叫到達工具回呼（成功或錯誤）時產生一個事件。[MCP] Tool Call Rejected— 在任何工具執行之前就失敗的tools/call（未知/停用的工具、輸入架構驗證）。這就是幻覺/拼錯的工具名稱出現的地方，其資訊承載於[MCP] Attempted Tool Name（避免使用保留的[MCP] Tool Name）。[MCP] Session Initialized,[MCP] Session Ended,[MCP] Tools Listed。
[MCP] Tool Call Response上的關鍵屬性：[MCP] Tool Name,[MCP] Client Name,[MCP] Client Version,[MCP] Session ID,[MCP] Auth Type,[MCP] Rationale,[MCP] Is Error,[MCP] Error Message,[MCP] Error Type（returned_error與thrown_exception— 區分一個工具報告失敗和一個工具崩潰），[MCP] Response Duration,[MCP] Response Size,[MCP] Request Size。 -
事件/屬性名稱在不同 SDK 版本之間仍可能變化。永遠不要假設 — 在第 0 階段使用分類工具進行驗證。上述的標準名稱來自 SDK 的
constants.ts（EVENT_PROPERTY_KEYS）；如果專案的資料不一致，請相信專案並進行調整。
第 0 階段 — 定位並驗證資料
- 呼叫 Amplitude 上下文工具（不帶 projectId）來列出專案。如果有多個看似合理的專案且使用者未指定，請詢問。
- 確認所選專案中存在
[MCP]事件（搜尋事件或列出事件；get_events僅按精確名稱過濾，因此請使用搜尋來發現[MCP]前綴）。 - 提取
[MCP] Tool Call Response（和[MCP] Tool Call Rejected）的事件屬性，以確認確切的屬性名稱 — 記住它們是以[MCP]為前綴且採用首字母大寫的格式（例如[MCP] Rationale，而不是tool rationale）。將你找到的任何名稱綁定到下方查詢中使用的名稱。 - 執行一次使用量/時效性查詢：過去 60 天內
[MCP] Tool Call Response、[MCP] Session Initialized的總量，按週間隔劃分。這會告訴你可用的日期範圍以及是否有足夠的資料。如果工具呼叫總數少於約 5000 次，請警告使用者每個工具的細項會很稀疏且百分比不穩定 — 但仍繼續進行，但在報告中說明。
記錄：專案 ID、日期範圍、總呼叫量。後續每個查詢都使用相同的範圍，以便數字保持可比性。
第 1 階段 — 按工具細分（主幹）
這是主要地圖；所有其他項目都從這裡深入。
- 按工具計算使用量：
[MCP] Tool Call Response的總量，按[MCP] Tool Name分組，groupByLimit約 100。 - 按工具計算錯誤： 同上，但增加過濾條件
[MCP] Is Error is "true"。 - 按嘗試名稱計算被拒絕的呼叫：
[MCP] Tool Call Rejected的總量，按[MCP] Attempted Tool Name分組。這些呼叫從未到達回呼，因此對上述兩個查詢是不可見的 — 但一個高使用量的嘗試名稱如果不是一個真正的工具，就是最有行動價值的發現之一（代理持續猜測的重新命名或幻覺）。
計算每個工具的呼叫量、錯誤計數和錯誤率，並以兩種方式對工具進行排序：按呼叫量（哪些是承載負載的）和按錯誤量（哪些造成最多失敗）。選擇前 3-5 個工具進行深入分析 — 偏向高錯誤量，而不僅僅是高流量，並尊重使用者若指定了特定工具的選擇。一個低流量但錯誤率高達 90% 的工具可能比一個繁忙且健康的工具排名更高。
第 2 階段 — 每個主要工具內的請求意圖（「為什麼」）
對於每個主要工具，對其請求意圖進行取樣 — [MCP] Tool Call Response 的總量，按 [MCP] Rationale 分組，過濾到該特定工具（[MCP] Tool Name is "<tool>"），groupByLimit 約 150。然後閱讀這些意圖並按呼叫者嘗試使用此工具完成什麼來分組，而不是按措辭。指導原則：
- 在單一工具內，你通常會發現 2-5 個意圖群組，而不是九個 — 工具本身已經縮小了目的範圍。用意圖來命名它們（例如，對於一個
query_chart工具：「即時儀表板重新整理」、「臨時探索」、「排程報表生成」）。 - 按呼叫量加權（每個請求意圖值都攜帶其總數），而不是按不同的字串。
- 注意一個垃圾群組：「佔位符」、「忽略」、「無操作」、「測試」、「虛擬資料」、單個字母。其大小是一個意圖衛生（rationale-hygiene）的發現，並且垃圾不得污染真正的意圖。
- 像「速率限制後重試」/「正在重試 X」這樣的請求意圖表示重試迴圈 — 請註明。
- 非英文的請求意圖是正常的；按意義分組。
- 計算每個工具的請求意圖覆蓋率（該工具呼叫中具有非空請求意圖的比例）。如果這個比例很低（<50%），則意圖只能描述一部分 — 請說明，並且「在儀器化階段改善請求意圖覆蓋率」本身就會成為一個建議。
- 計算每個工具的主要意圖佔比（最大的意圖群組佔該工具請求意圖覆蓋呼叫量的百分比）。這是集中度信號：約 90% 表示該工具服務於一項工作，你可以針對它進行積極的最佳化（圍繞該路徑收緊架構/描述）；均勻分佈（主要意圖約 30%）表示該工具過載，可能需要拆分，或者其錯誤將分散在不同的意圖之間。報告這個數字，當主要意圖佔主導地位時，在工具旁邊命名它。
跨工具工作流程（次要）： 一些請求意圖描述了一個多工具目標（「在重新整理儀表板之前解析圖表 ID」）。當一個意圖明顯跨越工具時（例如 search_events → create_chart → create_dashboard），在跨領域章節中將其作為一個工作流程指出 — 這是純粹按工具檢視唯一會遺漏的事情。
第 3 階段 — 每個工具的錯誤深入分析
對於每個主要工具，執行（過濾到該工具 + [MCP] Is Error is "true"）：
- 按
[MCP] Error Message分組 → 為什麼失敗 - 可選地按
[MCP] Error Type（returned_error與thrown_exception）拆分，當訊息不明確時 — 崩潰和格式良好的拒絕都會引發[MCP] Is Error，但只有一個是該工具中的錯誤。
當一個工具具有來自第 2 階段的主導意圖群組時，通過請求意圖（加入 contains 過濾器）來限定錯誤，以獲得「此意圖以這種方式失敗」的句子。
將每個顯著的錯誤訊息分類為一個原型 — 原型決定修復方式：
| 原型 | 特徵 | 修復模式 |
|---|---|---|
| 過時/幻覺的工具名稱 | [MCP] Tool Call Rejected 且 [MCP] Attempted Tool Name = 一個重新命名或聽起來合理的工具名稱 | 為重新命名的工具提供伺服器端別名；拒絕回應中命名最接近的真實工具，以便代理一次性自我修正 |
| 缺少必要參數 | 驗證錯誤，「Required」，路徑命名字段 | 放寬架構（接受單一值或陣列，加上預設值），或使工具描述說明要求，以便代理在呼叫前就能做對 |
| 架構形狀不匹配 | 「Expected object, received string」等 | 在伺服器端加入強制轉換，或在工具描述中加入內聯範例 |
| 硬限制衝突 | 「Maximum of N …」, 「too_big」 | 提高限制，在伺服器端自動分塊，或在參數描述中說明限制 — 代理目前只能透過失敗來了解限制 |
| 範圍/保留違規 | 「time range too large」, 「does not retain data before …」 | 自動強制轉換（例如降低粒度）而不是報錯；在上下文負載中宣告保留/範圍限制 |
| 因果循環參數 | 一個上下文/發現工具需要它本身存在的 ID 才能提供 | 使發現工具在沒有必要參數的情況下也能工作，從驗證權杖中獲取預設值 |
| 權限被拒絕 | 角色/權限相關語言 | 不同的錯誤類別，以便「不允許」與「損壞」可區分；通常也表明文件/入門教程存在缺口 |
| 重複排程錯誤 | 每天在同一個工具上重複相同的訊息 | 如果是內部工具，修復任務的呼叫端；對於產品，標記為默默退化的自動化 — 沒有人會監看對話視窗 |
| 瞬態/上游錯誤 | 5xx, 逾時, 速率限制 | 在錯誤正文中提供重試後提示；檢查重試是否實際發生（參見迴圈漏斗） |
最佳的錯誤訊息會說明修復方式（「請使用 start >= … 重新執行」）。將每個高使用量的錯誤訊息以此標準衡量 — 「讓這個錯誤訊息和你最好的那個一樣可執行」通常是個合理的建議。
第 4 階段 — 可選的上下文指標
如果時間允許則加入；它們能讓故事更清晰：
- 重複錯誤迴圈： 3 步驟漏斗，每個步驟都是
[MCP] Tool Call Response且[MCP] Is Error is "true"，保持[MCP] Tool Name不變，轉換視窗約 1 小時。顯示有多少比例報錯的使用者會在同一個工具上陷入迴圈。（步驟不必是連續的事件 — 指「一小時內同一個工具上的 3+ 錯誤」，而不是「3 個連續事件」。） - 錯誤 → 復原： 2 步驟漏斗，先錯誤後成功，保持工具名稱不變。高復原率 + 高迴圈率加在一起表示成本是浪費的權杖/延遲，而不是使用者放棄 — 這是一個實質上不同的結論。
- 客戶端組合： 按
[MCP] Client Name分組的不重複數量。大量的「未知」佔比或幾乎重複的客戶端名稱（大小寫、插件前綴變體）是值得報告的儀器化發現。
第 5 階段 — 驗證，然後撰寫
在撰寫之前，至少用第二種方法重新驗證一個標題數字（例如，透過一個單獨的兩個事件總量查詢來驗證整體錯誤率）。從原始總數重新計算你引用的每一個百分比。如果一個數字無法驗證，則刪除它或將其標記為估計值。
報告結構
使用此範本 — 以工具為優先組織：
# MCP 伺服器分析 — <伺服器/專案名稱>
資料：<專案>, <日期範圍>, <N> 次工具呼叫，整體錯誤率 <X>%。
方法說明：工具細項是精確的查詢結果；工具內意圖是從請求意圖經由模型推導得出的（方向性）。被拒絕的呼叫名稱來自 [MCP] Tool Call Rejected。
## 工具一覽
<table: 工具 | 呼叫數 | 錯誤數 | 錯誤率 | 主要意圖 (佔比 %) | 請求意圖覆蓋率>
<如果顯著，請用一行說明被拒絕/嘗試的工具名稱；如果顯著，請指出垃圾請求意圖>
## 深入分析：前 3-5 個工具（按錯誤量排序）
針對每個工具：
**工具：<名稱> — <呼叫數>, <錯誤率> — 用途：<一句話說明>**
- 意圖（此工具內的請求意圖）：<群組 : 佔比>, …
- 編號的 1-4 條建議。每條都說明證據（錯誤訊息 + 計數）、原型和具體的修復方法。從能消除最多錯誤量的修復開始。
## 跨領域發現
<跨工具工作流程、迴圈/復原率、客戶端名稱衛生、請求意圖衛生、內部測試流量、…>
## 一句話總結
<能消除最多失敗量的單一變更，並附上數字>
風格：每個主張旁邊都要有數字；逐字引用錯誤訊息（可截斷）以便工程師可以 grep；建議以行動形式表述（「為 query_chart → query_charts 提交別名」），而不是觀察（「工具命名可以改進」）。
輸出中的圖表
在客戶端支援的情況下，使用即席圖表查詢 + 渲染工具（建立一個 eventsSegmentation/funnels 定義，然後渲染它）來渲染支援性的 Amplitude 圖表。要審慎判斷什麼可以、什麼不可以做成圖表：
- 可製圖 — 任何由查詢支援的內容。 這些是真實的 Amplitude 分段/漏斗結果，因此請渲染它們：按工具劃分的呼叫和錯誤（按
[MCP] Tool Name分組）、隨時間變化的錯誤率、按[MCP] Attempted Tool Name劃分的被拒絕呼叫、每個工具的重複錯誤迴圈和復原漏斗，以及按[MCP] Client Name劃分的客戶端組合。工具細項是自然的主角圖表。 - 不可製圖 — 工具內的意圖群組。 將請求意圖分組為意圖是在此模型中完成的；這些分組在 Amplitude 中並不存在作為一個屬性，因此沒有儲存的「按意圖劃分的呼叫」圖表。將意圖作為一個從請求意圖總數建立的表格來呈現，並清楚地說明意圖數字是模型推導的（方向性），而你渲染的圖表是精確的查詢結果。不要暗示渲染的圖表支援意圖分組。
查詢食譜
所有查詢都是針對第 0 階段的專案 ID 的 eventsSegmentation 或 funnels 定義。將事件/屬性名稱調整為第 0 階段驗證的名稱。已知可行的形狀：
工具細項（第 1 階段）：
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] 按工具劃分的呼叫",
"params":{"range":"Last 30 Days",
"events":[{"event_type":"[MCP] Tool Call Response",
"group_by":[{"type":"event","value":"[MCP] Tool Name"}]}],
"metric":"totals","countGroup":"User","groupBy":[],"interval":"day"}}
工具錯誤（第 1 階段）：
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] 按工具劃分的錯誤",
"params":{"range":"Last 30 Days",
"events":[{"event_type":"[MCP] Tool Call Response",
"filterType":"event","filters":[{"subprop_type":"event","value":"[MCP] Is Error","op":"is","clause":"true"}],
"group_by":[{"type":"event","value":"[MCP] Tool Name"}]}],
"metric":"totals","countGroup":"User","groupBy":[],"interval":"day"}}
被拒絕的呼叫（第 1 階段）：
{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] 按嘗試工具名稱劃分的被拒絕呼叫",
"params":{"range":"Last 30 Days",
"events":[{"event_type":"[MCP] Tool Call Rejected",
"group_by":[{"type":"event","value":"[MCP] Attempted Tool Name"}]}],
"metric":"totals","countGroup":"User","groupBy":[],"interval":"day"}}
工具內請求意圖（第 2 階段）： 在 events 中加入一個 filterType 和 filters 陣列，設定 "value":"[MCP] Tool Name","op":"is","clause":"<tool>"。將 group_by 中的 value 改為 "[MCP] Rationale"。
工具內錯誤（第 3 階段）： 加入兩個過濾器（[MCP] Tool Name 和 [MCP] Is Error），按 [MCP] Error Message 分組。
重複錯誤迴圈漏斗（第 4 階段）： 使用 type: funnels，三個步驟（每個步驟：[MCP] Tool Call Response 過濾到同一個工具名稱 + [MCP] Is Error is "true"），轉換視窗 3600 秒。
錯誤 → 復原漏斗（第 4 階段）： type: funnels，兩個步驟：場景 A 是錯誤，場景 A 是成功（同一個工具名稱）。轉換視窗 3600 秒。
客戶端組合（第 4 階段）： eventsSegmentation，事件 [MCP] Tool Call Response，按 [MCP] Client Name 分組，metric: uniques。