跳至主要內容

操作手冊

Maguyva MCP 日常工作的實用秘訣。每個配方都命名了工具和順序——而不是完整的參數參考。對於工具參數，請使用 MCP API 參考。首次設定時，請使用 快速入門。

選擇正確的工具#

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

  • intelligent_search — 從這裡開始解決任何自然語言程式碼庫問題；它跨越語義、符號、結構和依賴搜尋。
  • find_symbol — 您已經知道函數、類別或變數名稱。
  • dependency_search — 影響範圍：呼叫者、相依項目或編輯之前（和之後）的影響。
  • get_task_context－陌生區域；用於任務描述的一組有界文件、符號和依賴項。
  • repository_context — 列出可存取的儲存庫或檢查儲存庫名稱的解析方式。
  • ask_maguyva 和 operation="guidance" — 有關工具選擇和 Maguyva 使用的本機說明（無修改儲存庫）。

安裝並驗證用戶端#

將 Maguyva 連接至您的 MCP 用戶端並確認與真實儲存庫清單的連線。

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

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

編輯前詢問#

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

  1. 如果您知道符號名稱，請呼叫 find_symbol 來了解定義和用途。
  2. 如果您只有任務描述（「新增 SSO」、「修復計費 Webhook」），請從 get_task_context 或 intelligent_search 開始。
  3. 在編輯共享符號之前，請使用依賴項/影響分析呼叫 dependency_search（或傳遞變更的路徑以實現 PR 式影響），以便您看到影響範圍。
  4. 開啟引用的檔案（本機讀取磁碟上的檔案；get_file 用於遠端/跨儲存庫路徑）並根據實際程式碼確認計畫。
  5. 編輯後，使用 dependency_search 重新檢查相同的符號（包括當您的用戶端支援驗證標誌時的編輯後驗證），以便呼叫者仍按預期解析。

完整參數：MCP API 參考。

搜尋，然後更改#

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

  1. 從 intelligent_search 和簡單語言查詢開始（「會話過期如何運作」、「重試邏輯在哪裡」）。
  2. 當第一個視窗有雜訊時，使用語言或路徑過濾器縮小範圍。
  3. 將有希望的命中推廣到 find_symbol 或 dependency_search，而不是重新提出相同的模糊問題。
  4. 僅當您需要不在磁碟上的特定索引路徑時才使用 get_file。
  5. 在普通用戶端工具中進行編輯。 Maguyva 用於發現和驗證——而不是寫入。

為什麼這個循環有效：它是如何運作的。

結果為空或資訊不足#

當工具未傳回任何有用的內容時，請在永遠重寫查詢之前修復解析和索引。

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

設定失敗：疑難排解。

跨多個儲存庫工作#

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

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

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

Maguyva 新手？先完成快速入門，然後回到這裡進行後續日常流程。

後續步驟#