操作手冊

Maguyva MCP 日常工作的實用操作指南。每份指南都列出所用工具與操作順序，而不是完整的參數說明。工具參數請參閱 MCP API 參考；首次設定請參閱快速入門。

這些 JSON 區塊是 MCP tools/call 的輸入。請將 owner/repo、分支名稱與符號名稱替換為你儲存庫中的值。

選擇正確的工具

大多數問題都是從一次工具呼叫開始的。只有在第一個答案太寬泛或資訊太少時才升級。

intelligent_search — 以自然語言詢問程式碼庫時，從這裡開始。預設的 auto/balanced 會將能高度確定是在詢問定義的查詢導向結構搜尋，將參照或影響查詢導向圖搜尋，將精確比對查詢導向文字搜尋。其他查詢使用語意與已索引文字。使用 mode=hybrid，或在 auto 下設定 quality=thorough，即可要求全部四種搜尋方式；明確指定的模式優先於 quality。
find_symbol — 你已經知道函式、類別或變數名稱。
dependency_search — 影響範圍：呼叫端、依賴該符號的程式碼，以及編輯前後的影響。
get_task_context — 面對陌生的程式碼區域時，依任務描述取得一組範圍有限的檔案、符號與依賴關係。
repository_context — 列出可存取的儲存庫或檢查儲存庫名稱的解析方式。
ask_maguyva 搭配 operation="guidance" — 工具內的使用說明，協助選擇工具與使用 Maguyva（不會修改儲存庫）。

安裝並驗證用戶端

將 Maguyva 接入你的 MCP 用戶端，並取得真實的儲存庫清單以確認連線正常。

在 app.maguyva.ai 中建立 API 金鑰（金鑰以 mgv_ 開頭）。
連接並索引至少一個你已經了解的 GitHub 儲存庫。
使用安裝指南（Claude Code 外掛或 Cursor、VS Code、Devin Desktop、Zed 等的原生遠端連線設定）連接你的用戶端。
詢問你的代理 "我連接了哪些儲存庫？" — 端對端執行身份驗證和 repository_context。
詢問一個有關該儲存庫的真實問題，你可以對其答案進行評分。你應該會看到索引樹中的檔案路徑和行號。

repository_context

{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}

遇到 API 金鑰、橋接設定或找不到儲存庫的問題？疑難排解。

編輯前詢問

更改共用程式碼之前掌握符號及其影響範圍。 Maguyva 工具不會修改你的儲存庫 - 它們為用戶端在本機套用的編輯提供依據。

如果你知道符號名稱，請呼叫 find_symbol 來了解定義和用途。
如果你只有任務描述（「新增 SSO」、「修復計費 Webhook」），請從 get_task_context 或 intelligent_search 開始。
編輯共用符號前，請呼叫 dependency_search 分析依賴該符號的程式碼或變更影響（也可傳入變更路徑，進行 PR 式影響分析），以了解影響範圍。
開啟引用的檔案（本機讀取磁碟上的檔案；get_file 用於遠端/跨儲存庫路徑）並根據實際程式碼確認計畫。
編輯後，使用 dependency_search，指定 verify_after_edit=true 以及 targets 或 changed_paths，重新檢查相同符號。它讀取的是已索引的圖，而不是尚未提交的本機變更：將其視為新修訂版本的依據前，請檢查 indexed_commit_sha 與索引的新鮮度，並執行本機測試。

dependency_search

{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}

完整參數：MCP API 參考。

搜尋，然後更改

預設代理循環：探索→鎖定符號→依據證據進行編輯。

從 intelligent_search 和簡單語言查詢開始（「會話過期如何運作」、「重試邏輯在哪裡」）。
若第一批結果有過多無關資訊，可用語言或路徑篩選器縮小範圍。language_filter 會從 auto/hybrid 排除圖搜尋；若 auto 查詢原本僅導向圖搜尋，則會退回語意與文字搜尋。明確指定圖模式並搭配 language_filter 時，請求會遭拒。查看 routing_decision.modalities_used 即可了解選定的搜尋計畫；warnings 只有在伺服器提出警告時才會出現。
針對看來有用的搜尋結果，進一步使用 find_symbol 或 dependency_search，而不是重複提出同一個模糊問題。
僅當你需要不在磁碟上的特定索引路徑時才使用 get_file。
在普通用戶端工具中進行編輯。 Maguyva 用於發現和驗證——而不是寫入。

intelligent_search

{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}

為什麼這個循環有效：運作原理。

結果為空或資訊不足

工具沒有傳回有用結果時，先修正儲存庫名稱解析與索引問題，別只是不斷重寫查詢。

確認儲存庫已連線並完成 app.maguyva.ai 中的索引。
檢查儲存庫字串："owner/repo" 使用預設分支；"owner/repo:branch" 指定分支。匹配不區分大小寫，而不是模糊 - 拼寫錯誤不會自動更正。
使用 action="info" 呼叫 repository_context 並檢查解析元資料（例如 metadata.resolution_reason）。
只有當你的 MCP 用戶端提供請求預設值或金鑰只能存取一個儲存庫時，才省略 repository；否則明確傳遞它。
使用更具體的查詢、透過 find_symbol 的已知符號名稱或語言/路徑過濾器重試。如果連接本身損壞，請使用疑難排解。

repository_context

{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}

設定失敗：疑難排解。

跨多個儲存庫工作

當一個 API 金鑰可存取多個儲存庫時，以正確的索引儲存庫為目標。

使用 action="list" 呼叫 repository_context 一次，以了解你的金鑰可以搜尋的確切的儲存庫識別名稱。
當你需要非預設儲存庫（例如 "owner/other-repo" 或 "owner/other-repo:develop"）時，在搜尋和符號工具上明確傳遞 repository。
保持一個問題=一個儲存庫，除非你有意在單獨的呼叫中跨儲存庫進行比較。
當檔案位於不是目前工作樹的索引儲存庫中時，請使用 get_file。
請記住：工具永遠不會寫回 GitHub - 多儲存庫上下文僅用於閱讀和規劃。

儲存庫格式詳細資訊：MCP API 參考。

首次設定？從快速入門開始，再用這些操作指南處理日常任務。

後續步驟

快速入門 — 金鑰、索引、連線，以及第一個經過驗證的答案
安裝指南 — 每個用戶端 MCP 設定
MCP API 參考 — 每個工具，逐一參數
故障排除 — API 金鑰、橋接器和儲存庫故障