跳至主要內容

MCP API 參考文件

了解 Maguyva 的 11 個 MCP 工具、各自的參數與適用情境。請查看已連線用戶端的 tools/list 回應,確認可用的引數。

API 概覽

#

工具分為 4 個類別:

  • 核心搜尋工具 - 橫跨整個程式碼庫的進階搜尋能力
  • 結構與圖譜工具 - AST 查詢、符號查詢與依賴分析
  • 程式碼分析工具 - 深度程式碼分析與關係對應
  • 系統與公用工具 - 儲存庫情境、工具指南與意見回饋

對於接受儲存庫引數的工具,請使用此儲存庫識別碼格式:"owner/repo:branch"。未指定分支時,預設為 main。

當你的 MCP 用戶端提供此次請求的預設值,或該金鑰僅能存取單一儲存庫時,省略 repository;否則請明確傳入。使用 repository_context(action="info", repository="owner/repo") 檢查儲存庫的解析方式。

儲存庫參數格式

#

指定儲存庫時,請使用以下格式:

  • 含分支: "owner/repo:branch" - 例如, "owner/repository:develop"
  • 預設分支: "owner/repo" - 未指定分支時使用 main 分支 "owner/repository"
  • 請求層級或唯一儲存庫預設: 當 MCP 用戶端提供請求層級預設值,或金鑰只能存取一個儲存庫時,可省略 repository;否則必須明確傳入。

提示範例:

詢問特定 repo:  "在 owner/my-repo 中搜尋驗證中介軟體"
列出可用儲存庫:    "這個 Maguyva 金鑰可以存取哪些儲存庫?"
僅對單一查詢覆寫:   "在 owner/other-repo:develop 中搜尋驗證模式"

語言篩選

#

在支援的搜尋模式中使用 language_filter。對於 text_pattern_search,選擇 search_scope="content";對於 get_task_context,使用 scope="semantic",不提供種子或相關情境。

  • language_filter="python" - 僅篩選 Python 檔案
  • language_filter="typescript" - 僅篩選 TypeScript 檔案
  • 區分大小寫: 請使用小寫的語言名稱
  • 預設值: 空字串(不篩選)——回傳所有語言的結果
  • 支援涵蓋範圍: 語言篩選功能,適用於全部 285+ 種支援的程式語言與文字型技術。 完整清單請見 相容性。
「只在 Python 檔案中尋找身分驗證中介軟體」
「在 TypeScript 中搜尋資料庫連線」

本 API 參考文件由原始碼於 2026年10月21日 產生。

核心搜尋工具

#

有任何程式碼庫問題,都從這裡開始。預設的 auto/balanced 會將能高度確定是在詢問定義的查詢導向結構搜尋,將參照或影響查詢導向圖搜尋,將精確比對查詢導向文字搜尋。其他查詢使用語意與已索引文字。使用 mode=hybrid,或在 auto 下設定 quality=thorough,即可要求全部四種搜尋方式;明確指定的模式優先於 quality。 language_filter 會從 auto/hybrid 排除圖搜尋,並拒絕明確指定的 mode=graph。若尚不知道路徑,請優先使用此工具,而非 Grep/Glob。

參數:

query 必填
類型
str minLength=1
說明
搜尋查詢
repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
mode 選填
類型
Literal[auto, hybrid, semantic, text, structural, ast, graph]
預設值
auto
說明
搜尋模式
limit 選填
類型
int minimum=1, maximum=50
預設值
10
說明
此排名 top-K 視窗中的最大回傳結果數
language_filter 選填
類型
str
說明
語言篩選
path_filter 選填
類型
str
說明
依檔案路徑前綴篩選檢索候選。圖中的相鄰節點與附加的社群上下文可能包含此路徑前綴範圍之外的檔案。
boost_by_importance 選填
類型
bool
預設值
false
說明
可選啟用:使用每個符號的圖譜指標(is_articulation_point、bridge_count、k_core、centrality 等)依中心性重新排名。為確保對代理安全的排名,預設關閉(全域樞紐可能淹沒實作層面的命中);進行架構巡覽時啟用。當每個結果都帶有符號關聯時,適用於全部 4 種模態。
branch 選填
類型
str
說明
分支覆寫
quality 選填
類型
Literal[quick, balanced, thorough]
預設值
balanced
說明
搜尋品質預設
include_content 選填
類型
bool
預設值
true
說明
在結果中包含內容
explain_routing 選填
類型
bool
預設值
false
說明
包含路由決策說明
importance_weight 選填
類型
float minimum=0, maximum=1
預設值
0.3
說明
重要性加權權重(0=無,1=完全)
orphans 選填
類型
bool
預設值
false
說明
包含孤立符號(無傳入參照)
include_community_context 選填
類型
bool
預設值
false
說明
包含同一程式碼社群的相關符號
community_depth 選填
類型
int minimum=1, maximum=3
預設值
1
說明
社群情境擴展深度
graph_view 選填
類型
Literal[dependency, type, data_flow, control_flow]
預設值
dependency
說明
指標用的圖譜檢視
seed_symbol_ids 選填
類型
list[str] maxItems=20
說明
Tier-1 任務種子:目前任務的核心符號 ID。設定後,會依 Approach A 的深度衰減鄰近度重新排序融合結果(精確種子比對 + 沿圖譜邊的跳數)。這是在原有排序上加入的加權;若要使用全域排序,請省略此參數。
seed_file_paths 選填
類型
list[str] maxItems=10
說明
Tier-1 任務種子:代理已開啟或剛編輯的已索引檔案路徑。設定後,會依路徑鄰近度重新排序融合結果,並隨深度按 1/(1+d) 衰減權重(同一檔案 → 同一目錄 → 鄰近套件)。這是在原有排序上加入的加權;若要使用全域排序,請省略此參數。

最適用於:

  • 不清楚該用哪個工具時,進行全索引或冷啟動式探索
  • 跨語意、文字、結構和圖的多模態融合排序

不建議用於:

  • 已知的符號名 —— 直接使用 find_symbol
  • 磁碟上已知的路徑 —— 先使用本機的 Read/Grep

依含義而非精確文字尋找程式碼。不知道關鍵字或符號名稱時,用於「重試邏輯」「使用者引導流程」等概念查詢。傳回相關區塊,並限制檔案多樣性的範圍;可透過 boost_by_importance 選擇啟用圖重要性重新排序。概念搜尋優先使用此工具而非 Grep。

參數:

query 必填
類型
str minLength=1
說明
搜尋查詢(概念性、語意導向)
repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
limit 選填
類型
int minimum=1, maximum=50
預設值
5
說明
此排名 top-K 視窗中的最大回傳結果數
similarity_threshold 選填
類型
float minimum=0, maximum=1
預設值
0.6
說明
最低相似度分數
language_filter 選填
類型
str
說明
語言篩選(python、typescript 等)
path_filter 選填
類型
str
說明
以檔案路徑前綴篩選
boost_by_importance 選填
類型
bool
預設值
false
說明
選擇啟用:依每個符號正規化後的圖重要性重新排序(預設關閉,上限為相似度的 1.5 倍)。
branch 選填
類型
str
說明
分支覆寫(預設:來自 repository 參數或 main)
include_content 選填
類型
bool
預設值
true
說明
在結果中包含區塊內容
graph_view 選填
類型
Literal[dependency, type, data_flow, control_flow]
預設值
dependency
說明
指標用的圖譜檢視

最適用於:

  • 概念性查詢(「驗證機制如何運作?」、「快取策略」)
  • 跨套件的相似度搜尋

不建議用於:

  • 已知的符號名 —— 改用 find_symbol
  • 精確字串或錯誤訊息 —— 使用 text_pattern_search

搜尋已索引內容。exact 和 regex 模式對完整檔案/blob 語料執行 grep;fuzzy content 模式搜尋有範圍限制的語意區塊語料。file 和 symbol 範圍僅支援三字元組比對,預設 mode=exact 會轉為 fuzzy。語言、大小寫及自訂閾值控制須使用 content 範圍。檔案路徑篩選採用有界候選視窗,並回報涵蓋不完整的情況。對磁碟上範圍較小的目錄,使用本機 Grep。

參數:

query 必填
類型
str minLength=1
說明
要搜尋的文字模式
repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
mode 選填
類型
Literal[fuzzy, exact, regex]
預設值
exact
說明
搜尋模式。正規表示式執行 PostgreSQL 進階/POSIX 語法;使用 \y 表示單字邊界(\b 表示退格)。模式也需通過 JavaScript 安全驗證器,因此僅 PostgreSQL 支援的結構(例如內嵌 (?i) 旗標)會被拒絕;請改用 case_sensitive。
search_scope 選填
類型
Literal[content, symbols, files]
預設值
content
說明
搜尋範圍
limit 選填
類型
int minimum=1, maximum=50
預設值
5
說明
不使用 cursor 時每頁的最大結果數。繼續翻頁時會使用 cursor 中保存的分頁大小;省略 cursor 即可用不同的 limit 重新開始。
offset 選填
類型
int minimum=0
說明
已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
cursor 選填
類型
str
說明
來自 pagination.next_cursor 的不透明 cursor。請原樣傳遞,並保持 query 與篩選條件不變。其位置與分頁大小會覆寫 offset 與 limit。
language_filter 選填
類型
str
說明
語言篩選
path_filter 選填
類型
str
說明
以檔案路徑前綴篩選
case_sensitive 選填
類型
bool
預設值
false
說明
區分大小寫比對
branch 選填
類型
str
說明
分支覆寫
fuzzy_algorithm 選填
類型
Literal[hybrid, trigram, levenshtein]
預設值
hybrid
說明
模糊比對演算法
threshold 選填
類型
float minimum=0, maximum=1
預設值
0.05
說明
模糊比對的最低相似度門檻
semantic_fallback 選填
類型
bool
預設值
false
說明
在首次詞法搜尋結果為空時嘗試語意搜尋;metadata.fallback_status 用來區分 used、empty、unavailable 三種回退狀態。

最適用於:

  • 精確字串、錯誤訊息和正規表示式
  • 針對近似文字的三字元組模糊比對

不建議用於:

  • 磁碟上已知的路徑 —— 優先使用本機的 Grep
  • 概念性查詢 —— 使用 semantic_search

結構與圖譜工具

#

優先使用 preset=functions|classes|methods|imports|variables(或自由格式的 pattern=)。依 AST 形狀而非文字尋找程式碼。中階篩選器包括 name_pattern、node_type、decorator、parent_child。路徑、ltree 與呼叫篩選器屬於進階功能,有意使用時請設定 advanced=true。未設定時,進階篩選器仍會套用,但會在中繼資料中給出警告。請至少提供一個結構選擇器。

參數:

repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
preset 選填
類型
Literal[functions, classes, methods, imports, variables]
說明
首選的結構選擇器。會展開為跨語言的 AST 節點類型——functions(各語言的 function/arrow/method 定義);classes(class/struct/interface 宣告、型別主體與實作);methods(method 定義,對於沒有 method 節點的語言則為 function_definition);imports(import/use/include 陳述式);variables(variable/let/const/static 宣告)。對於瀏覽式查詢,優先於自由形式的 pattern/node_type。
pattern 選填
類型
str
說明
自由形式的 pattern 用於補齊缺少的選擇器(自動偵測:'def foo(' → node_type + name_pattern)。可與 preset 併用,明確指定的選擇器優先。瀏覽類查詢建議優先使用 preset=。
name_pattern 選填
類型
str maxLength=256
說明
符號名稱模式(shell 萬用字元、有界的 POSIX regex 或模糊文字;最多 256 個字元)
node_type 選填
類型
str
說明
AST 節點類型(function_definition、class_definition 等)——常見形狀請優先使用 preset=。
decorator 選填
類型
str
說明
裝飾器名稱篩選
base_class 選填
類型
str
說明
基底類別篩選
language_filter 選填
類型
str
說明
語言篩選(python、typescript 等)
limit 選填
類型
int minimum=1, maximum=50
預設值
20
說明
不使用 cursor 時每頁的最大結果數。繼續翻頁時會使用 cursor 中保存的分頁大小;省略 cursor 即可用不同的 limit 重新開始。
offset 選填
類型
int minimum=0
說明
已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
cursor 選填
類型
str
說明
來自 pagination.next_cursor 的不透明 cursor。請原樣傳遞,並保持 query 與篩選條件不變。其位置與分頁大小會覆寫 offset 與 limit。
path_filter 選填
類型
str
說明
以檔案路徑前綴篩選
branch 選填
類型
str
說明
分支覆寫
query_type 選填
類型
Literal[node_type, name_pattern, parent_child]
說明
明確指定查詢類型
parent_type 選填
類型
str
說明
父 AST 節點類型篩選
relationship 選填
類型
Literal[parent, ancestor]
預設值
parent
說明
對於 parent_child 查詢:僅限直接父節點,或任一祖先節點(若類別方法位於類別主體/區塊之下,請使用 ancestor)
has_modifier 選填
類型
str
說明
以修飾子篩選(export、async、static 等)
advanced 選填
類型
bool
預設值
false
說明
有意使用進階路徑、ltree 或呼叫篩選器(ltree_ancestor、ltree_descendant、min_depth、max_depth、field_role、definition_name、callee_text、callee_name)時,設為 true。為 false 時,提供的進階篩選器仍會套用,但會在中繼資料中給出警告。常見結構查詢請優先使用 preset=。
callee_text 選填
類型
str
說明
進階——優先使用 preset=functions|classes|methods|imports|variables。依呼叫運算式中的被呼叫對象(callee)文字篩選。刻意使用 path/ltree/call 類篩選器時請設定 advanced=true。
callee_name 選填
類型
str
說明
進階——優先使用 preset=functions|classes|methods|imports|variables。依呼叫運算式中的被呼叫對象(callee)名稱篩選。刻意使用 path/ltree/call 類篩選器時請設定 advanced=true。
field_role 選填
類型
str
說明
進階——優先使用 preset=functions|classes|methods|imports|variables。AST 欄位角色篩選器。刻意使用 path/ltree/call 類篩選器時請設定 advanced=true。
ltree_ancestor 選填
類型
str
說明
進階——優先使用 preset=functions|classes|methods|imports|variables。AST ltree 祖先路徑篩選器。刻意使用 path/ltree/call 類篩選器時請設定 advanced=true。
ltree_descendant 選填
類型
str
說明
進階——優先使用 preset=functions|classes|methods|imports|variables。AST ltree 後代路徑篩選器。刻意使用 path/ltree/call 類篩選器時請設定 advanced=true。
definition_name 選填
類型
str
說明
進階——優先使用 preset=functions|classes|methods|imports|variables。定義名稱篩選器。刻意使用 path/ltree/call 類篩選器時請設定 advanced=true。
min_depth 選填
類型
int
說明
進階——優先使用 preset=functions|classes|methods|imports|variables。最小 AST 深度。刻意使用 path/ltree/call 類篩選器時請設定 advanced=true。
max_depth 選填
類型
int
說明
進階——優先使用 preset=functions|classes|methods|imports|variables。最大 AST 深度。刻意使用 path/ltree/call 類篩選器時請設定 advanced=true。

最適用於:

  • AST 層級的結構:類別、裝飾器、函式/方法預設
  • 以形狀而非文字尋找程式碼

不建議用於:

  • 自由文字或概念性查詢 —— 使用 semantic_search 或 intelligent_search

主要的影響範圍/圖譜查詢介面。透過實際的呼叫/匯入圖譜回答「誰呼叫了它?」或「它使用了什麼?」。編輯前的影響分析:使用 analysis_type="dependents" 或 analysis_type="impact"(沿入向關係走訪,impact 預設深度為 shallow);include_metrics=false 為預設值,可選擇啟用中心性指標與 refactor_risk。dependents/impact 預設包含 production_callers:依種類區分的唯一正式環境使用位置(call、instantiate、以值傳遞的函式所對應的 value_reference),以及 IMPORT 位置;排除測試,並提供 EXTRACTED/INFERRED 信心分類,而非單純堆疊指標。分析 PR/diff 影響時,傳入 changed_paths 和/或 patch(unified diff),即可依路徑解析符號,並傳回沿入向關係淺層走訪所得的依賴者精簡回應,無需提供符號名稱。編輯後,設定 verify_after_edit=true 並提供 targets 和/或 changed_paths,即可從多個起點重新查詢受影響的符號,取得精簡回應。同時支援 dependencies、centrality 與 orphans。analyze_dependencies 使用相同的走訪方式進行多跳影響分析。

參數:

repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
query 選填
類型
str
說明
符號名稱或搜尋字串
target 選填
類型
str
說明
符號名稱(query 的別名)
symbol_id 選填
類型
UUID
說明
依命名空間、路徑和語言篩選後,在指定名稱的 query/target 候選中以 UUID 選取某個具體出現位置。使用 find_symbol 或圖的替代結果傳回的 ID。僅適用於依名稱走訪;不在限定候選範圍內的 ID 會產生錯誤。
changed_paths 選填
類型
list[str] maxItems=50
說明
相對於儲存庫根目錄的精確檔案路徑,用於 PR/diff 影響分析(預設),或在 verify_after_edit=true 時作為編輯後驗證的起點。無法解析的路徑可能會回傳附標籤的建議;建議的檔案絕不會成為影響分析的起點。PR/diff:沒有行資訊時,會走訪各路徑的頂層定義(匯出的優先,依檔案內順序),並回報 changed_lines_unknown;若要取得逐行變更的符號,請傳入 patch=。驗證:每個路徑最多取 5 個頂層定義作為驗證起點(驗證模式內的上限較低)。PR/diff 影響分析不需要 query/target。
patch 選填
類型
str maxLength=500000
說明
PR/diff 影響分析:unified diff/git patch 格式的文字。路徑取自 diff --git / --- / +++ 標頭;差異區塊中的行(舊側 = 已索引的提交)會對應到包住它們的函式/方法/類別,再沿這些符號走訪,取得精確的依賴方、public_api_changed,以及該差異未觸及的呼叫端。
head_commit 選填
類型
str pattern=^[0-9a-fA-F]{7,64}$
說明
你所詢問程式碼的提交 SHA(git rev-parse HEAD,或修補檔的基準提交)。complete:true 要求索引位於此提交,且由目前的解析器建置;否則會維持 complete:false,並附上 index_stale / index_freshness_unverified / index_built_by_older_resolver,而 index_basis.statement 會說明答案在什麼範圍內是完整的。修補檔中的 'base-commit:' 行(git format-patch --base)也能提供此值。
analysis_type 選填
類型
Literal[centrality, dependencies, dependents, impact, orphans]
預設值
dependencies
說明
分析模式。impact = 影響範圍(沿入向關係追蹤依賴目標的對象;省略 depth 時使用 shallow 深度)。dependents 也可用於影響分析。設定 changed_paths 或 patch 時,會強制改用 PR/diff 影響分析。centrality/orphans 不需要 target。orphans 是未使用程式碼的候選項,並不能證明可以安全移除;請查核原始碼中的參照。
depth 選填
類型
Literal[shallow, balanced, deep]
說明
走訪深度。預設為 balanced;impact 與 PR/diff impact 預設使用 shallow。明確指定 depth 會覆寫這些預設值。驗證模式一律使用 shallow。
limit 選填
類型
int minimum=1, maximum=50
預設值
20
說明
不使用 cursor 時每頁的最大結果數。繼續翻頁時會使用 cursor 中保存的分頁大小;省略 cursor 即可用不同的 limit 重新開始。
offset 選填
類型
int minimum=0
說明
已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
cursor 選填
類型
str
說明
來自 pagination.next_cursor 的不透明 cursor。請原樣傳遞,並保持 query 與篩選條件不變。其位置與分頁大小會覆寫 offset 與 limit。
path_filter 選填
類型
str
說明
將目標符號解析限制在指定的檔案路徑前綴內;回傳的圖譜關聯可能會延伸至該路徑之外。
language_filter 選填
類型
str
說明
依語言篩選目標解析與瀏覽結果
direction 選填
類型
Literal[outgoing, incoming, both]
說明
走訪方向(會覆寫 analysis_type 的推論)
relationship_types 選填
類型
list[str]
說明
篩選邊類型(CALL、IMPORT、INHERITS_FROM 等)。非空清單會覆寫 graph_view 預設值。
exclude_test_paths 選填
類型
bool
預設值
true
說明
預設 true:從走訪與中心性結果中排除測試、fixture、vendor 與範例路徑。設為 false 以納入它們。orphan 分析僅在已部署的後端支援時才遵循此設定;否則會保留其自身更嚴格的雜訊排除,並回報此調整。
exclude_generated_paths 選填
類型
bool
預設值
false
說明
從走訪結果中排除自動產生的宣告,以及建置產物、覆蓋率報告、快取、原始碼對應檔與壓縮產物的路徑
include_module_symbols 選填
類型
bool
預設值
false
說明
預設為 false:排除 from_name 或 to_name 是合成符號 __module__ 的邊(模組層級雜訊)。設為 true,則在 dependents/dependencies 結果中包含模組層級的邊。
include_isolated 選填
類型
bool
說明
僅適用於 orphans。預設 false。設為 true 時,也會回傳在圖譜指標中沒有對應列的符號(任何地方都沒有圖譜邊)。當 exclude_test_paths 為 true 時,只要後端支援,樣式表/標記/資料符號(CSS、HTML 等)、.d.ts 宣告以及 test/fixture/vendor/example 路徑仍會被排除,除非 language_filter 指定了該語言;TypeScript 物件字面值的屬性仍可能顯示為孤立函式。
exclude_exported 選填
類型
bool
預設值
false
說明
僅適用於孤立符號。預設為 false:儲存庫內未被使用的匯出符號(公開 API)仍會回傳,並標記 is_exported=true。設為 true 可僅保留內部候選項。
branch 選填
類型
str
說明
分支覆寫
per_hop_limit 選填
類型
int minimum=1, maximum=300
說明
每一跳的最大關聯數(1-300)
include_metrics 選填
類型
bool
預設值
false
說明
在結果列上可選啟用的圖譜指標(與 refactor_risk 一併精簡化)。當 min_centrality>0 時也會在內部取得指標,但除非此項為 true,否則不會回傳。
metrics_detail 選填
類型
Literal[summary, full]
預設值
summary
說明
當 include_metrics=true 時:summary(預設)回傳決策參考訊號與 refactor_risk;full 回傳範圍較大的精選指標集
include_edge_metadata 選填
類型
bool
預設值
false
說明
包含邊的原始中繼資料與權重(資料量較大)。精簡的影響分析回應會停用此選項。
symbol_types 選填
類型
list[str]
說明
依種類(function、class、method 等)篩選回傳的符號。orphan 分析不支援此參數;請改用 path_filter 或 language_filter。空清單表示不依種類篩選。
exact_match 選填
類型
bool
預設值
false
說明
要求符號名稱精確比對
find_similar_patterns 選填
類型
bool
預設值
false
說明
尋找相似的使用模式
min_centrality 選填
類型
float minimum=0
預設值
0
說明
用於具名符號走訪與 PR/diff 影響分析的最小 PageRank 分數。centrality/orphans 瀏覽模式不支援大於零的閾值。指標會在內部取得以供篩選;僅當 include_metrics=true 時才回傳 graph_metrics。verify_after_edit 會忽略此參數,它使用固定的精簡控制項。
graph_view 選填
類型
Literal[dependency, type, data_flow, control_flow]
預設值
dependency
說明
用於走訪關聯預設值、指標與中心性排名的圖譜檢視;orphan 分析會跨所有檢視計算。
verify_after_edit 選填
類型
bool
預設值
false
說明
針對已編輯的符號重新查詢已索引的影響圖,以一次精簡的多根回應傳回。需要 targets 和/或 changed_paths(或 target/query)。使用固定的 shallow 走訪與精簡預算;depth/limit/cursor/metrics 等控制項不適用。預設回傳 incoming dependents;結果反映已索引的圖(可能落後於即時編輯)。為 true 時,在相同 changed_paths 上優先於 PR/diff impact。
targets 選填
類型
list[str] maxItems=15
說明
當 verify_after_edit=true 時:要重新驗證的符號名稱(呼叫端/依賴者)。如果兩者都提供,則與 target/query 合併。

最適用於:

  • 編輯共享符號之前的影響範圍/影響分析
  • 透過 changed_paths 或 patch 分析 PR/差異影響
  • 透過 verify_after_edit 進行編輯後驗證

不建議用於:

  • 簡單的文字或符號尋找 —— 使用 text_pattern_search 或 find_symbol

程式碼分析工具

#

find_symbol 穩定版

跳轉到函式、類別或變數的定義與使用位置。當你已知道名稱(例如 "getCurrentUser")時使用——比 Grep 更快且更精確,可涵蓋整個已編入索引的儲存庫。可選回傳參照與重要性指標。

參數:

symbol_name 選填
類型
str
說明
要搜尋的符號名稱(可選 — 省略以依指標瀏覽)
repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
scope 選填
類型
Literal[definitions, references, both]
預設值
both
說明
搜尋範圍;references 需要非空的 symbol_name。
limit 選填
類型
int minimum=1, maximum=50
預設值
15
說明
不使用 cursor 時每頁的最大結果數。繼續翻頁時會使用 cursor 中保存的分頁大小;省略 cursor 即可用不同的 limit 重新開始。
offset 選填
類型
int minimum=0
說明
已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
cursor 選填
類型
str
說明
來自 pagination.next_cursor 的不透明 cursor。請原樣傳遞,並保持 query 與篩選條件不變。其位置與分頁大小會覆寫 offset 與 limit。
find_similar 選填
類型
bool
預設值
false
說明
包含相似符號名稱
include_metrics 選填
類型
bool
預設值
false
說明
包含中心性指標
metrics_detail 選填
類型
Literal[summary, full]
預設值
summary
說明
當 include_metrics=true 時:summary(預設)回傳決策參考訊號與 refactor_risk;full 回傳範圍較大的精選指標集
path_filter 選填
類型
str
說明
以檔案路徑前綴篩選
branch 選填
類型
str
說明
分支覆寫
symbol_type 選填
類型
str minLength=1
說明
依索引符號種類篩選,例如 function、class、struct、enum 或 trait。請使用符號結果所回傳的種類;種類會依語言而異。
high_impact 選填
類型
bool
預設值
false
說明
瀏覽架構上重要的符號(省略 symbol_name)。預設模式為 popularity(PageRank 最高的十分之一,排除通用工具類的超級樞紐)。設為 high_impact_mode=risk,可尋找作為關節點/橋接點的割點。
high_impact_mode 選填
類型
Literal[popularity, risk]
預設值
popularity
說明
當 high_impact=true 時:popularity = PageRank 最高的十分之一,排除通用工具類的超級樞紐/模組;risk = 關節點,先依 SMV bridge_count、再依 k_core 排序(評估結構性的重構風險,而非樞紐的熱門程度)
in_cycle 選填
類型
bool
預設值
false
說明
篩選出有記錄依賴循環成員關係的符號。
exclude_test_paths 選填
類型
bool
預設值
true
說明
依圖譜指標瀏覽時,會在排序前排除測試、測試固定資料、第三方程式碼與範例;依名稱查找符號的行為不變
reference_views 選填
類型
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
說明
透過輸入邊填入 references/reference_count 的圖檢視(scope 為 references/both)。預設 ["dependency", "type"] 包括呼叫、匯入、匯出、參照、實例化、繼承、覆寫、裝飾器和型別使用。未選取 data_flow 時,精確解析的 data_flow 使用(回呼、處理常式、排序鍵)會另以 value_references/value_reference_count 回傳,不包含僅憑名稱推斷的匹配。可加入 data_flow 或 control_flow,或傳入 ["all"] 以包含所有邊類型和層級。檢視類別與 dependency_search 的 graph_view 相同。
relationship_types 選填
類型
list[str]
說明
明確指定參照邊類型(CALL、IMPORT、READS 等)。非空清單會覆蓋 reference_views。

最適用於:

  • 鎖定已知符號的定義、參照和圖指標
  • 省略 symbol_name 時,依 centrality、high_impact 或 in_cycle 瀏覽

不建議用於:

  • 概念性或未知領域的查詢 —— 使用 intelligent_search 或 semantic_search

analyze_dependencies 穩定版

使用與 dependency_search 相同的走訪方式(dependents/incoming)分析影響範圍。影響分析請優先使用帶 analysis_type="dependents" 或 "impact" 的 dependency_search。傳回多跳影響回應,包含 graph、connection_summary,以及可選的含 refactor_risk 的指標。使用 graph_view 來限定關聯族:dependency(預設)、type、data_flow、control_flow。 connection_summary 統計所選根節點上依關聯族限定的邊,且在依測試/路徑篩選之前計數。舊的 incoming_production/outgoing_production 欄位表示非模組的邊(包含測試),並不是正式環境呼叫端的數量。

參數:

repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
target 必填
類型
str minLength=1
說明
要分析的符號名稱
symbol_id 選填
類型
UUID
說明
依命名空間、路徑和語言篩選後,在 target 候選中以 UUID 選取某個具體出現位置;不在限定候選範圍內的 ID 會產生錯誤。
depth 選填
類型
Literal[shallow, balanced, deep]
預設值
balanced
說明
分析深度
limit 選填
類型
int minimum=1, maximum=50
預設值
10
說明
不使用 cursor 時每頁的最大結果數。繼續翻頁時會使用 cursor 中保存的分頁大小;省略 cursor 即可用不同的 limit 重新開始。
offset 選填
類型
int minimum=0
說明
已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
cursor 選填
類型
str
說明
來自 pagination.next_cursor 的不透明 cursor。請原樣傳遞,並保持 query 與篩選條件不變。其位置與分頁大小會覆寫 offset 與 limit。
direction 選填
類型
Literal[incoming, outgoing, both]
預設值
incoming
說明
走訪方向
relationship_types 選填
類型
list[str]
說明
依邊類型(CALL、IMPORT、INHERITS_FROM 等)篩選。非空清單會覆寫 graph_view 的預設值;空清單則使用這些預設值。
graph_view 選填
類型
Literal[dependency, type, data_flow, control_flow]
預設值
dependency
說明
圖譜視圖:同時決定預設的走訪邊類型,以及 include_metrics=true 時使用哪個視圖的指標。dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES](預設)、type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE]、data_flow=[READS,WRITES,ASSIGNS_TO]、control_flow=[CONTROL_FLOW,THROWS,CATCHES]。當 relationship_types 省略或為空時,會以此作為 relationship_types 的預設值。與 dependency_search 既有的 graph_view 參數名稱保持一致,以確保工具間的一致性。
path_filter 選填
類型
str
說明
將目標符號解析限制在指定的檔案路徑前綴內;回傳的圖譜關聯可能會延伸至該路徑之外。
language_filter 選填
類型
str
說明
語言篩選
branch 選填
類型
str
說明
分支覆寫
per_hop_limit 選填
類型
int minimum=1, maximum=300
說明
每一跳的最大關聯數(1-300)
include_metrics 選填
類型
bool
預設值
false
說明
在結果中包含圖譜指標,並為每筆指標補上推導出的 refactor_risk 區塊({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons})。在所選檢視中,符號不是關節點時,risk 為 "low";是關節點且橋接的邊較少時為 "medium",橋接的邊較多時為 "high"(此門檻採用啟發式判定,未經實證驗證)。若某個符號/檢視沒有指標資料列,則省略該符號的指標。
metrics_detail 選填
類型
Literal[summary, full]
預設值
summary
說明
當 include_metrics=true 時:summary(預設)回傳決策參考訊號與 refactor_risk;full 回傳範圍較大的精選指標集
include_edge_metadata 選填
類型
bool
預設值
false
說明
包含邊的原始中繼資料與權重。由於擷取器的中繼資料可能很大,預設停用;啟用時會回報資料補充的涵蓋率。
exclude_test_paths 選填
類型
bool
預設值
true
說明
預設為 true:從回傳的圖譜邊中排除測試、測試固定資料、第三方程式碼與範例路徑。設為 false 即可納入。
include_module_symbols 選填
類型
bool
預設值
false
說明
預設為 false:排除 from_name 或 to_name 是合成符號 __module__ 的邊。設為 true 即可包含模組層級的邊。
head_commit 選填
類型
str pattern=^[0-9a-fA-F]{7,64}$
說明
你所詢問程式碼的提交 SHA(git rev-parse HEAD,或修補檔的基準提交)。complete:true 要求索引位於此提交,且由目前的解析器建置;否則會維持 complete:false,並附上 index_stale / index_freshness_unverified / index_built_by_older_resolver,而 index_basis.statement 會說明答案在什麼範圍內是完整的。修補檔中的 'base-commit:' 行(git format-patch --base)也能提供此值。

最適用於:

  • 需要 graph 與 connection_summary 回應欄位時的多跳影響分析

不建議用於:

  • 一般影響分析——優先使用 dependency_search,以便彈性走訪並從多個起點檢查

get_task_context 穩定版

要在陌生的程式碼區域展開工作?描述你的任務(例如「新增 SSO 支援」「修復帳單 Webhook」),即可一次呼叫取得相關檔案、程式碼、符號與依賴關係的完整組合。作為種子傳入的檔案即使未定義任何符號,也會提供直接索引的內容。失敗的層會被標記;若全部擷取都失敗,則回傳工具錯誤。若需要更多結果,可繼續使用該層專用的搜尋工具。

參數:

task_description 必填
類型
str minLength=1
說明
你需要情境的任務描述
repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
limit 選填
類型
int minimum=1, maximum=50
預設值
15
說明
每層的最大結果數
scope 選填
類型
Literal[semantic, symbols, dependencies, all]
預設值
all
說明
要包含哪些情境層
language_filter 選填
類型
str
說明
語言篩選:須設定 scope=semantic,且不使用明確種子或相關情境;其他層的索引無法強制限制語言。
path_filter 選填
類型
str
說明
用於語意檢索與關鍵字檢索起點的檔案路徑前綴。明確指定的種子可以位於此前綴之外;圖譜脈絡可能跨越目錄邊界。
branch 選填
類型
str
說明
分支覆寫
include_related_context 選填
類型
bool
預設值
false
說明
包含來自相鄰符號的相關情境
seed_symbol_ids 選填
類型
list[str] maxItems=20
說明
明確指定的任務種子:會在符號層中排在最前面,並保留在有邊界的 dependencies/related_context 視窗內。圖譜層會先為明確指定的種子及其最近鄰排序,之後才退回關鍵字;重要性僅在相關性相同時用來決定先後。圖譜擴展需要 scope=all|dependencies(scope=symbols|semantic 絕不會執行相依性走訪)。若要僅依關鍵字並以深度遞減的重要性排序,請省略此參數。
seed_file_paths 選填
類型
list[str] maxItems=10
說明
明確指定的種子:代理已開啟或剛編輯的精確已索引檔案路徑。直接回傳數量受限的檔案佐證,並為每個檔案提供最多 5 個圖譜種子,優先採用有邊界的符號查詢中與任務名稱完全相符的項目,其次才是定義與附帶出現的符號。沒有符號的檔案同樣可提供佐證。找不到的檔案可能會回傳附標籤的建議,但這些建議並非種子。圖譜擴展需要 scope=all|dependencies。

最適用於:

  • 將種子檔案與語意、符號和依賴層結合的、以任務為導向的情境

不建議用於:

  • 已有更專用工具可回答問題的單一工具尋找

get_file 穩定版

依路徑從索引儲存庫讀取檔案。磁碟上的檔案請優先使用本機檔案工具;此工具適用於遠端索引快照。可使用 metadata.next_line_start 與 next_character_start 繼續取得有邊界的回應。僅當 metadata.truncated=true 時才移除結尾換行符與 [truncated] 標記;否則它可能是字面原始文字。

參數:

file_path 必填
類型
str
說明
相對於儲存庫根的檔案路徑
repository 選填
類型
str
說明
儲存庫(owner/repo[:branch])。可選 — 當 MCP 用戶端為此次請求提供預設值,或金鑰僅能存取單一儲存庫時可省略;僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。系統會優先採用完全相符的已索引分支;若目標分支無法使用,可能會回退至 main 或唯一可存取的分支。回應中繼資料會顯示所要求與實際解析出的身分,並在發生回退時提出警告。
line_start 選填
類型
int minimum=1
說明
開始行(以 1 為起始)
line_end 選填
類型
int minimum=1
說明
結束行(從 1 開始,含邊界;必須不小於 line_start)
character_start 選填
類型
int minimum=0
預設值
0
說明
僅在起始行內使用的 UTF-16 編碼單元偏移量(從 0 開始)。使用 metadata.next_character_start 繼續讀取尚未讀完的行。
branch 選填
類型
str
說明
分支覆寫
max_tokens 選填
類型
int minimum=1, maximum=50000
預設值
5000
說明
近似內容預算(每個 token 以 4 個 UTF-16 編碼單元估算,並非精確的分詞器上限)。
include_metadata 選填
類型
bool
預設值
true
說明
包含描述性檔案中繼資料。截斷及續讀中繼資料一律傳回。

最適用於:

  • 遠端或已索引檔案的快照(行範圍、詞元上限)

不建議用於:

  • 已在本機磁碟上的路徑 —— 使用本機的 Read 工具

系統與實用工具

#

repository_context 穩定版

列出你可以搜尋的儲存庫,或取得某個儲存庫的識別資訊(namespace/branch、indexed_commit_sha / 索引新鮮度)。當不知道儲存庫 slug 時使用 action:"list";搜尋工具可直接接受已知 slug,或預設使用你金鑰下的唯一儲存庫。list 使用 pattern 與分頁;info 需要 repository,並支援 branch 與可選的 include_statistics=true。

參數:

action 必填
類型
Literal[list, info]
說明
操作:列出可用儲存庫或取得儲存庫資訊(list 或 info)
repository 選填
類型
str
說明
僅用於 info:owner/repo 或 owner/repo:branch 格式的儲存庫(info 時必填)
branch 選填
類型
str
說明
僅用於 info:分支覆寫
pattern 選填
類型
str
說明
僅用於 list:不分大小寫的儲存庫名稱子字串
include_statistics 選填
類型
bool
預設值
false
說明
僅供資訊:包含有邊界的索引資料計數。file/blob 計數為精確值;較大的索引計數為估計值。請參閱 count_accuracy 與 estimate_analyzed_at。預設為 false。
limit 選填
類型
int minimum=1, maximum=50
預設值
20
說明
不使用 cursor 時每頁的最大結果數。繼續翻頁時會使用 cursor 中保存的分頁大小;省略 cursor 即可用不同的 limit 重新開始。
offset 選填
類型
int minimum=0
說明
已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
cursor 選填
類型
str
說明
來自 pagination.next_cursor 的不透明 cursor。請原樣傳遞,並保持 query 與篩選條件不變。其位置與分頁大小會覆寫 offset 與 limit。

最適用於:

  • 列出可存取的儲存庫
  • 解析儲存庫識別、分支以及 HEAD 與索引的新鮮度

不建議用於:

  • 預設進行整個命名空間的統計 —— 請明確傳入 include_statistics=true,因為它可能比解析更慢

ask_maguyva 穩定版

取得 Maguyva 工具指南,或提交供 Maguyva 維護者保存的錯誤報告及功能請求。切勿在意見回饋中包含秘密資訊或敏感個人資料。evaluate 操作支援確定性運算式;數學、雜湊與字串處理請優先使用本機計算或主機工具。

參數:

operation 必填
類型
Literal[guidance, report_bug, request_feature, evaluate]
說明
工具說明使用 guidance,錯誤報告使用 report_bug,建議使用 request_feature。evaluate 執行確定性運算式;計算請優先在本機完成。
query 選填
類型
str maxLength=500
說明
指南主題(例如 tool_selection、semantic_search),或供 evaluate 使用的運算式字串。
description 選填
類型
str minLength=1, maxLength=4000
說明
report_bug 與 request_feature 必填。提供給 Maguyva 維護者的自由格式意見回饋。切勿包含機密資訊或敏感的個人資料。
related_tool 選填
類型
Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
說明
與回饋最密切相關的可選Maguyva工具

最適用於:

  • 工具指引(operation="guidance")
  • 面向 Maguyva 維護者的持久性錯誤報告和功能請求

不建議用於:

  • 數學、雜湊或字串計算——優先使用本機計算或主機工具

最佳實務

#
  1. 有意識地使用明確覆寫: 當你的 MCP 用戶端提供此次請求的預設值,或金鑰僅能存取單一儲存庫時,請省略儲存庫;否則請明確傳入。
  2. 選擇正確的搜尋模式: 大多數情況下搭配 mode="auto" 使用 intelligent_search。當你已確定需求時再指定具體模式。
  3. 善用語言篩選: 使用 language_filter 縮小結果範圍並提升效能。
  4. GraphRAG 重要性加權: 為使排序對代理而言安全,語意搜尋預設停用 GraphRAG 重要性加權(boost_by_importance=false)。若要進行架構巡覽,可傳入 boost_by_importance=true,以啟用基於中心度的重新排序。
  5. 儲存庫比對不區分大小寫,而非模糊比對: repository_context 比對儲存庫名稱時不區分大小寫,但不會修正拼字錯誤。當實際提供的識別資訊與請求的不同時,metadata.resolution_reason 會回報 "defaulted"(未請求分支)或 "fallback"(請求的分支或儲存庫無法使用)。若請求完全相符,則會省略此欄位。
  6. 組合使用工具: 結合使用多個 API 方法以取得全面分析結果。
  7. 處理大量結果: 使用 limit 與工具專屬分頁控制(例如在 get_file 中使用 line_start/line_end)。
  8. 使用 ask_maguyva 取得工具指引: 呼叫 ask_maguyva,指定 operation="guidance" 與 query="tool_selection",取得工具選擇建議與範例。計算與字串轉換請使用本機工具。
  9. 在編輯前後驗證影響: 在編輯共用符號之前,先以 analysis_type="impact" 呼叫 dependency_search(或傳入 changed_paths 以查看 PR/diff 影響),檢視其影響範圍。編輯之後,將 verify_after_edit=true 與 targets 及/或 changed_paths 一併設定,即可對已索引的圖譜進行精簡的重新檢查。這裡檢查的是已索引的圖譜,不會讀取尚未提交的本機變更,也不能取代本機測試。將結果視為新修訂版本的依據前,請檢查 indexed_commit_sha 與索引的新鮮度。

效能特性

#
操作 效能說明
語意搜尋 包含查詢嵌入向量的產生與向量檢索。延遲取決於這兩項操作。
文字搜尋 模糊內容搜尋中,越後面的頁面會取得越多候選項目。使用 path_filter 與 language_filter 縮小查詢範圍。
結構搜尋 查詢已索引的 AST 節點。使用具體的預設選項或模式,並限制結果數量。
相依性搜尋 成本隨深度增加——除非需要多跳上下文,否則建議使用 depth="shallow";per_hop_limit 用於限制展開範圍
檔案擷取 使用 line_start/line_end 或 max_tokens 讀取所需範圍;對於截斷的內容,請使用傳回的續讀中繼資料。
儲存庫上下文 每次工具呼叫都會解析儲存庫。需要特定儲存庫時,請明確傳入 repository。
ask_maguyva(guidance / evaluate) 在 MCP 伺服器中執行,不查詢儲存庫索引。

錯誤處理

#

工具回應在最上層包含共通的狀態欄位與工具特有的承載資料欄位。搜尋傳回 results;get_file 傳回 content。常見欄位包括:

  • status: 字串 — "success" 或 "error"。降級比對與索引新鮮度訊號各有專屬欄位:metadata 底下的 metadata.resolution_reason,以及 repository_context info 動作最上層的 index_freshness.status。
  • timing_ms: 工具執行耗時,單位為毫秒
  • applied_filters: 為該操作記錄的實際生效請求參數
  • error: 當 status 為 "error" 時提供的錯誤訊息字串;其中可能包含復原建議。
  • metadata: 關於此操作的額外資訊(路由、快取、參數調整)
  • pagination: 出現在以游標分頁的集合回應中,包含 has_more 與 next_cursor。排序搜尋的結果視窗是有界的 top-K 結果,而不是涵蓋全部內容的分頁集合。

處理工具回傳內容前,請先檢查 status 欄位,其值為 "success" 或 "error"。也要處理 MCP/JSON-RPC 傳輸錯誤與請求驗證錯誤,這些可能在工具回傳內容產生之前就發生。至於降級比對或新鮮度訊號,請改讀專屬欄位:metadata 底下的 metadata.resolution_reason,或 repository_context info 動作最上層的 index_freshness.status(known/partial/unknown/unavailable)。

快速上手

#
  1. 設定 MCP 用戶端: 把你的 MCP 用戶端指向 Maguyva 伺服器端點
  2. 確認儲存庫存取: 使用 repository_context 的 list 或 info 操作檢視 API 金鑰可存取的儲存庫
  3. 開始搜尋: 以 intelligent_search 開始,必要時再探索專用工具
  4. 組合使用工具: 將多個工具搭配使用以進行全面程式碼分析

詳細的整合說明,請參閱安裝指南。