MCP API 參考文件

涵蓋全部 11 項面向客戶的 Maguyva MCP 工具的完整參考文件。每個工具都包含參數、使用指引，以及最適用情境建議。

API 概覽#

Maguyva MCP API 目前提供 11 項面向客戶的工具，分屬 4 個主要類別：

核心搜尋工具 - 橫跨整個程式碼庫的進階搜尋能力
結構與圖譜工具 - AST 查詢、符號查詢與依賴分析
程式碼分析工具 - 深度程式碼分析與關係對應
系統與公用工具 - 儲存庫情境、確定性運算與操作指引

所有工具都使用一致的儲存庫識別碼格式："owner/repo:branch"。若未指定分支，預設為 main。

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

儲存庫參數格式#

所有 MCP 工具都使用以下的儲存庫識別碼格式：

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

提示範例:

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

語言篩選#

所有搜尋工具都支援依程式語言篩選結果：

language_filter="python" - 僅篩選 Python 檔案
language_filter="typescript" - 僅篩選 TypeScript 檔案
區分大小寫: 請使用小寫的語言名稱
預設值: 空字串（不篩選）——回傳所有語言的結果
支援涵蓋範圍: 語言篩選功能，適用於全部 279+ 種支援的程式語言與文字型技術。完整清單請見相容性。

「只在 Python 檔案中尋找 authentication middleware」
「在 TypeScript 中搜尋 database connections」

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

核心搜尋工具#

intelligent_search穩定版

任何程式碼庫問題從這裡開始。給它一個自然語言查詢（例如「身份驗證如何運作」、「帳單在哪裡處理」），它會自動路由索引儲存庫的語義、符號、結構和依賴項搜尋。在探索和規劃方面，與 Explore 代理程式和 Grep/Glob 相比，它更喜歡這種方式 - 它會立即搜尋整個索引儲存庫，而不是掃描檔案。

參數：

query必填

類型: str
說明: 搜尋查詢

repository選填

類型: str
說明: 儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

mode選填

類型: Literal[auto, hybrid, semantic, text, structural, ast, graph]
預設值: auto
說明: 搜尋模式

limit選填

類型: int
預設值: 10
說明: 此排名 top-K 視窗中的最大回傳結果數

language_filter選填

類型: str
說明: 語言篩選

path_filter選填

類型: str
說明: 以檔案路徑前綴篩選

boost_by_importance選填

類型: bool
預設值
說明: 可選啟用：使用每個符號的圖譜指標（is_articulation_point、bridge_count、k_core、centrality 等）依中心性重新排名。為確保對代理安全的排名，預設關閉（全域樞紐可能淹沒實作層面的命中）；進行架構巡覽時啟用。當每個結果都帶有符號關聯時，適用於全部 4 種模態。

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

quality選填

類型: Literal[quick, balanced, thorough]
預設值: balanced
說明: 搜尋品質預設

include_content選填

類型: bool
預設值: true
說明: 在結果中包含內容

explain_routing選填

類型: bool
預設值
說明: 包含路由決策說明

importance_weight選填

類型: float
預設值: 0.3
說明: 重要性加權權重（0=無，1=完全）

orphans選填

類型: bool
預設值
說明: 包含孤立符號（無傳入參照）

include_community_context選填

類型: bool
預設值
說明: 包含同一程式碼社群的相關符號

community_depth選填

類型: int
預設值: 1
說明: 社群情境擴展深度

graph_view選填

類型: Literal[dependency, type, data_flow, control_flow]
預設值: dependency
說明: 指標用的圖譜檢視

seed_symbol_ids選填

類型: list[str]
說明: Tier-1 任務種子：目前任務的核心符號 ID。設定後，按 Approach A 深度衰減接近度（精確種子匹配 + 圖形邊緣跳躍）對融合命中重新排序。添加劑 — 忽略全球排名。

seed_file_paths選填

類型: list[str]
說明: Tier-1 任務種子：代理程式已開啟或剛剛編輯的索引檔案路徑。設定後，透過 1/(1+d) 深度衰減的路徑鄰近度重新排列融合命中（相同檔案 → 相同目錄 → 附近的套件）。添加劑 — 忽略全球排名。

參數	類型	必填	預設值	說明
`query`	`str`	是	-	搜尋查詢
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	否	`auto`	搜尋模式
`limit`	`int`	否	`10`	此排名 top-K 視窗中的最大回傳結果數
`language_filter`	`str`	否	-	語言篩選
`path_filter`	`str`	否	-	以檔案路徑前綴篩選
`boost_by_importance`	`bool`	否		可選啟用：使用每個符號的圖譜指標（is_articulation_point、bridge_count、k_core、centrality 等）依中心性重新排名。為確保對代理安全的排名，預設關閉（全域樞紐可能淹沒實作層面的命中）；進行架構巡覽時啟用。當每個結果都帶有符號關聯時，適用於全部 4 種模態。
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`quality`	`Literal[quick, balanced, thorough]`	否	`balanced`	搜尋品質預設
`include_content`	`bool`	否	`true`	在結果中包含內容
`explain_routing`	`bool`	否		包含路由決策說明
`importance_weight`	`float`	否	`0.3`	重要性加權權重（0=無，1=完全）
`orphans`	`bool`	否		包含孤立符號（無傳入參照）
`include_community_context`	`bool`	否		包含同一程式碼社群的相關符號
`community_depth`	`int`	否	`1`	社群情境擴展深度
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	否	`dependency`	指標用的圖譜檢視
`seed_symbol_ids`	`list[str]`	否	-	Tier-1 任務種子：目前任務的核心符號 ID。設定後，按 Approach A 深度衰減接近度（精確種子匹配 + 圖形邊緣跳躍）對融合命中重新排序。添加劑 — 忽略全球排名。
`seed_file_paths`	`list[str]`	否	-	Tier-1 任務種子：代理程式已開啟或剛剛編輯的索引檔案路徑。設定後，透過 1/(1+d) 深度衰減的路徑鄰近度重新排列融合命中（相同檔案 → 相同目錄 → 附近的套件）。添加劑 — 忽略全球排名。

最適用於：

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

不建議用於：

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

semantic_search穩定版

根據含義查找代碼，而不是確切的文字。當您不知道關鍵字或符號名稱時，可用於「重試邏輯」或「使用者入門流程」等概念查詢。傳回按重要性排名的最相關的程式碼區塊。當搜尋是概念性的時，優於 Grep。

參數：

query必填

類型: str
說明: 搜尋查詢（概念性、語意導向）

repository選填

類型: str
說明: 儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

limit選填

類型: int
預設值: 5
說明: 此排名 top-K 視窗中的最大回傳結果數

similarity_threshold選填

類型: float
預設值: 0.6
說明: 最低相似度分數

language_filter選填

類型: str
說明: 語言篩選（python、typescript 等）

path_filter選填

類型: str
說明: 以檔案路徑前綴或萬用字元篩選（例如 'src/services/'、'*.py'）

boost_by_importance選填

類型: bool
預設值
說明: 可選啟用：依 PageRank 中心性重新排名（為確保對代理安全的排名，預設關閉；進行架構巡覽時啟用）。

branch選填

類型: str
說明: 分支覆寫（預設：來自 repository 參數或 main）

include_content選填

類型: bool
預設值: true
說明: 在結果中包含區塊內容

graph_view選填

類型: Literal[dependency, type, data_flow, control_flow]
預設值: dependency
說明: 指標用的圖譜檢視

參數	類型	必填	預設值	說明
`query`	`str`	是	-	搜尋查詢（概念性、語意導向）
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`limit`	`int`	否	`5`	此排名 top-K 視窗中的最大回傳結果數
`similarity_threshold`	`float`	否	`0.6`	最低相似度分數
`language_filter`	`str`	否	-	語言篩選（python、typescript 等）
`path_filter`	`str`	否	-	以檔案路徑前綴或萬用字元篩選（例如 'src/services/'、'*.py'）
`boost_by_importance`	`bool`	否		可選啟用：依 PageRank 中心性重新排名（為確保對代理安全的排名，預設關閉；進行架構巡覽時啟用）。
`branch`	`str`	否	-	分支覆寫（預設：來自 repository 參數或 main）
`include_content`	`bool`	否	`true`	在結果中包含區塊內容
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	否	`dependency`	指標用的圖譜檢視

最適用於：

概念性查詢（"how does auth work?"、"caching strategy"）
跨套件的相似度搜尋

不建議用於：

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

text_pattern_search穩定版

搜尋已編入索引的內容。精確與 regex 模式會掃描完整檔案/Blob 語料庫；fuzzy 模式搜尋受限的語意區塊語料。檔案與符號範圍僅在 fuzzy 模式支援。若要在本機已存在的目錄做精準搜尋，請使用本地 Grep。

參數：

query必填

類型: str
說明: 要搜尋的文字模式

repository選填

類型: str
說明: 儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

mode選填

類型: Literal[fuzzy, exact, regex]
預設值: exact
說明: 搜尋模式

search_scope選填

類型: Literal[content, symbols, files]
預設值: content
說明: 搜尋範圍

limit選填

類型: int
預設值: 5
說明: 本頁回傳的最大結果數

offset選填

類型: int
說明: 已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。

cursor選填

類型: str
說明: 來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。

language_filter選填

類型: str
說明: 語言篩選

path_filter選填

類型: str
說明: 以檔案路徑前綴或萬用字元篩選（例如 'src/pipeline/'、'*.py'）

case_sensitive選填

類型: bool
預設值
說明: 區分大小寫比對

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

fuzzy_algorithm選填

類型: Literal[hybrid, trigram, levenshtein]
預設值: hybrid
說明: 模糊比對演算法

threshold選填

類型: float
預設值: 0.05
說明: 模糊比對的最低相似度門檻

semantic_fallback選填

類型: bool
預設值
說明: 無結果時備援為語意搜尋

參數	類型	必填	預設值	說明
`query`	`str`	是	-	要搜尋的文字模式
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`mode`	`Literal[fuzzy, exact, regex]`	否	`exact`	搜尋模式
`search_scope`	`Literal[content, symbols, files]`	否	`content`	搜尋範圍
`limit`	`int`	否	`5`	本頁回傳的最大結果數
`offset`	`int`	否	-	已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
`cursor`	`str`	否	-	來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。
`language_filter`	`str`	否	-	語言篩選
`path_filter`	`str`	否	-	以檔案路徑前綴或萬用字元篩選（例如 'src/pipeline/'、'*.py'）
`case_sensitive`	`bool`	否		區分大小寫比對
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	否	`hybrid`	模糊比對演算法
`threshold`	`float`	否	`0.05`	模糊比對的最低相似度門檻
`semantic_fallback`	`bool`	否		無結果時備援為語意搜尋

最適用於：

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

不建議用於：

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

結構與圖譜工具#

優先使用 preset=functions|classes|methods|imports|variables（或自由的 pattern=）。依 AST 形狀（而非文字）尋找程式碼。中間層篩選器：name_pattern、node_type、decorator、parent_child。path/ltree/call 類篩選器屬於進階用法——刻意使用時請設定 advanced=true；為向後相容，扁平的 advanced 鍵仍被接受。請至少提供一個結構選擇器。

參數：

repository選填

類型: str
說明: 儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

preset選填

類型: Literal[functions, classes, methods, imports, variables]
說明: 首選的結構選擇器。會展開為跨語言的 AST 節點類型——functions（各語言的 function/arrow/method 定義）；classes（class/struct/impl 定義）；methods（method 定義，對於沒有 method 節點的語言則為 function_definition）；imports（import/use/include 陳述式）；variables（variable/let/const/static 宣告）。對於瀏覽式查詢，優先於自由形式的 pattern/node_type。

pattern選填

類型: str
說明: 當 preset 過於粗略時使用的自由格式模式（自動偵測：'def foo(' → node_type + name_pattern）。瀏覽式查詢請優先使用 preset=。

name_pattern選填

類型: str
說明: 符號名稱模式（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
預設值: 20
說明: 本頁回傳的最大結果數

offset選填

類型: int
說明: 已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。

cursor選填

類型: str
說明: 來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。

path_filter選填

類型: str
說明: 以檔案路徑前綴或萬用字元篩選（例如 'src/pipeline/'、'*.py'、'tree_sitter_queries/**/*.scm'）

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

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
預設值
說明: 當有意使用進階路徑、ltree 或呼叫過濾器（ltree_ancestor、ltree_descendant、min_depth、max_depth、field_role、definition_name、callee_text、callee_name）時設定 true。預設情況下，false 使座席介面聚焦於預設。平面格式的高級密鑰仍然可以向後相容，並帶有元資料警告。

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 field role 篩選器。刻意使用 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。

參數	類型	必填	預設值	說明
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`preset`	`Literal[functions, classes, methods, imports, variables]`	否	-	首選的結構選擇器。會展開為跨語言的 AST 節點類型——functions（各語言的 function/arrow/method 定義）；classes（class/struct/impl 定義）；methods（method 定義，對於沒有 method 節點的語言則為 function_definition）；imports（import/use/include 陳述式）；variables（variable/let/const/static 宣告）。對於瀏覽式查詢，優先於自由形式的 pattern/node_type。
`pattern`	`str`	否	-	當 preset 過於粗略時使用的自由格式模式（自動偵測：'def foo(' → node_type + name_pattern）。瀏覽式查詢請優先使用 preset=。
`name_pattern`	`str`	否	-	符號名稱模式（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`	否	`20`	本頁回傳的最大結果數
`offset`	`int`	否	-	已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
`cursor`	`str`	否	-	來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。
`path_filter`	`str`	否	-	以檔案路徑前綴或萬用字元篩選（例如 'src/pipeline/'、'.py'、'tree_sitter_queries//.scm'）
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`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`	否		當有意使用進階路徑、ltree 或呼叫過濾器（ltree_ancestor、ltree_descendant、min_depth、max_depth、field_role、definition_name、callee_text、callee_name）時設定 true。預設情況下，false 使座席介面聚焦於預設。平面格式的高級密鑰仍然可以向後相容，並帶有元資料警告。
`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 field role 篩選器。刻意使用 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

dependency_search穩定版

主要的 blast-radius／圖譜查詢介面。透過真實的呼叫／匯入圖譜回答「什麼在呼叫它？」／「它使用了什麼？」。編輯前的影響分析：analysis_type="dependents" 或 analysis_type="impact"（incoming，impact 預設深度為 shallow），include_metrics 預設為 false（若需中心性 + refactor_risk 請選擇啟用）。PR/diff 影響（P1-8）：傳入 changed_paths 和／或 patch（unified diff）——依路徑解析符號，並回傳精簡的 shallow-incoming dependents 負載，無需符號名稱。編輯後，設定 verify_after_edit=true 並提供 targets 和／或 changed_paths，即可對受影響的符號進行精簡的多根重新查詢。同時支援 dependencies、centrality 與 orphans。analyze_dependencies 是 impact 路徑的輕量別名——新代理請優先使用本工具。

參數：

repository選填

類型: str
說明: 儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

query選填

類型: str
說明: 符號名稱或搜尋字串

target選填

類型: str
說明: 符號名稱（query 的別名）

changed_paths選填

類型: list[str]
說明: PR/diff 影響的儲存庫相對路徑（預設），或對於 verify_after_edit=true，編輯後驗證根。 PR/diff：解析每個路徑的符號並遍歷淺層傳入相依性；可與 patch= 組合。驗證：將每個路徑最多 5 個符號解析為驗證根（在驗證模式下上限較低）。對於 PR/diff 影響不需要 query/target。

patch選填

類型: str
說明: PR/diff 影響：統一 diff/git 補丁文字。路徑從 diff --git / --- / +++ 標頭解析；與 changed_paths 相同的緊湊衝擊路徑。

analysis_type選填

類型: Literal[centrality, dependencies, dependents, impact, orphans]
預設值: dependencies
說明: 分析模式。impact = 影響範圍（incoming dependents；省略 depth 時使用 shallow 深度）。dependents 同樣可回答影響分析。設定了 changed_paths 或 patch 時，分析會強制為 PR/diff 影響。centrality/orphans 不需要 target。

depth選填

類型: Literal[shallow, balanced, deep]
預設值: balanced
說明: 走訪深度。對於 analysis_type=impact 和 PR/diff 影響，除非你明確設定 depth，否則實際預設值為 shallow。

limit選填

類型: int
預設值: 20
說明: 本頁回傳的最大結果數

offset選填

類型: int
說明: 已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。

cursor選填

類型: str
說明: 來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。

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
預設值
說明: 從遍歷結果中排除產生的聲明以及建置、覆蓋、快取、來源映射和縮小的工件路徑

include_module_symbols選填

類型: bool
預設值
說明: 預設情況下，當 from_name 或 to_name 是合成 __module__ 符號（模組級雜訊）時，false 排除圖形邊緣。設定 true 以在依賴關係和依賴關係的結果中包含模組級邊緣。

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

per_hop_limit選填

類型: int
說明: 每一跳的最大關聯數（1-300）

include_metrics選填

類型: bool
預設值
說明: 在結果列上可選啟用的圖譜指標（與 refactor_risk 一併精簡化）。當 min_centrality>0 時也會在內部取得指標，但除非此項為 true，否則不會回傳。

metrics_detail選填

類型: Literal[summary, full]
預設值: summary
說明: 當include_metrics=true時：summary（預設）返回判決訊號+refactor_risk；full 返回更大的規劃指標集

include_edge_metadata選填

類型: bool
預設值
說明: 包括原始邊緣元資料和權重（大）。緊湊型衝擊有效載荷則不會出現這種情況。

symbol_types選填

類型: list[str]
說明: 依種類篩選回傳的符號（function、class、method 等）

exact_match選填

類型: bool
預設值
說明: 要求符號名稱精確比對（不區分大小寫），並停用模糊比對

find_similar_patterns選填

類型: bool
預設值
說明: 尋找相似的使用模式

min_centrality選填

類型: float
預設值: 0
說明: 最小 PageRank 分數。指標會在內部取得以供篩選；僅當 include_metrics=true 時才回傳 graph_metrics。

graph_view選填

類型: Literal[dependency, type, data_flow, control_flow]
預設值: dependency
說明: 用於走訪關聯預設值、指標與中心性排名的圖譜檢視；orphan 分析會跨所有檢視計算。

verify_after_edit選填

類型: bool
預設值
說明: P2-7 編輯後驗證模式：在一個緊湊的多根回應中重新查詢最近編輯的符號的索引影響圖。需要 targets 和/或 changed_paths（或 target/query）。預設為淺傳入家屬；結果反映了索引圖（可能滯後於即時編輯）。如果為 true，則優先於 PR/diff 對相同 changed_paths 的影響。

targets選填

類型: list[str]
說明: 當 verify_after_edit=true 時：要重新驗證的符號名稱（呼叫者/依賴者）。如果兩者都提供，則與 target/query 合併。

參數	類型	必填	預設值	說明
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`query`	`str`	否	-	符號名稱或搜尋字串
`target`	`str`	否	-	符號名稱（query 的別名）
`changed_paths`	`list[str]`	否	-	PR/diff 影響的儲存庫相對路徑（預設），或對於 verify_after_edit=true，編輯後驗證根。 PR/diff：解析每個路徑的符號並遍歷淺層傳入相依性；可與 patch= 組合。驗證：將每個路徑最多 5 個符號解析為驗證根（在驗證模式下上限較低）。對於 PR/diff 影響不需要 query/target。
`patch`	`str`	否	-	PR/diff 影響：統一 diff/git 補丁文字。路徑從 diff --git / --- / +++ 標頭解析；與 changed_paths 相同的緊湊衝擊路徑。
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	否	`dependencies`	分析模式。impact = 影響範圍（incoming dependents；省略 depth 時使用 shallow 深度）。dependents 同樣可回答影響分析。設定了 changed_paths 或 patch 時，分析會強制為 PR/diff 影響。centrality/orphans 不需要 target。
`depth`	`Literal[shallow, balanced, deep]`	否	`balanced`	走訪深度。對於 analysis_type=impact 和 PR/diff 影響，除非你明確設定 depth，否則實際預設值為 shallow。
`limit`	`int`	否	`20`	本頁回傳的最大結果數
`offset`	`int`	否	-	已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
`cursor`	`str`	否	-	來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。
`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`	否		從遍歷結果中排除產生的聲明以及建置、覆蓋、快取、來源映射和縮小的工件路徑
`include_module_symbols`	`bool`	否		預設情況下，當 from_name 或 to_name 是合成 __module__ 符號（模組級雜訊）時，false 排除圖形邊緣。設定 true 以在依賴關係和依賴關係的結果中包含模組級邊緣。
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`per_hop_limit`	`int`	否	-	每一跳的最大關聯數（1-300）
`include_metrics`	`bool`	否		在結果列上可選啟用的圖譜指標（與 refactor_risk 一併精簡化）。當 min_centrality>0 時也會在內部取得指標，但除非此項為 true，否則不會回傳。
`metrics_detail`	`Literal[summary, full]`	否	`summary`	當include_metrics=true時：summary（預設）返回判決訊號+refactor_risk；full 返回更大的規劃指標集
`include_edge_metadata`	`bool`	否		包括原始邊緣元資料和權重（大）。緊湊型衝擊有效載荷則不會出現這種情況。
`symbol_types`	`list[str]`	否	-	依種類篩選回傳的符號（function、class、method 等）
`exact_match`	`bool`	否		要求符號名稱精確比對（不區分大小寫），並停用模糊比對
`find_similar_patterns`	`bool`	否		尋找相似的使用模式
`min_centrality`	`float`	否	`0`	最小 PageRank 分數。指標會在內部取得以供篩選；僅當 include_metrics=true 時才回傳 graph_metrics。
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	否	`dependency`	用於走訪關聯預設值、指標與中心性排名的圖譜檢視；orphan 分析會跨所有檢視計算。
`verify_after_edit`	`bool`	否		P2-7 編輯後驗證模式：在一個緊湊的多根回應中重新查詢最近編輯的符號的索引影響圖。需要 targets 和/或 changed_paths（或 target/query）。預設為淺傳入家屬；結果反映了索引圖（可能滯後於即時編輯）。如果為 true，則優先於 PR/diff 對相同 changed_paths 的影響。
`targets`	`list[str]`	否	-	當 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 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

scope選填

類型: Literal[definitions, references, both]
預設值: both
說明: 搜尋範圍（definitions|references|both）

limit選填

類型: int
預設值: 15
說明: 本頁回傳的最大結果數

offset選填

類型: int
說明: 已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。

cursor選填

類型: str
說明: 來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。

find_similar選填

類型: bool
預設值
說明: 包含相似符號名稱

include_metrics選填

類型: bool
預設值
說明: 包含中心性指標

metrics_detail選填

類型: Literal[summary, full]
預設值: summary
說明: 當include_metrics=true時：summary（預設）返回判決訊號+refactor_risk；full 返回更大的規劃指標集

path_filter選填

類型: str
說明: 路徑萬用字元篩選（例如 'src/'、'*.py'）

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

symbol_type選填

類型: Literal[function, class, variable, method, constant, module, interface, type]
說明: 以符號類型篩選

high_impact選填

類型: bool
預設值
說明: 瀏覽在架構上重要的符號（省略 symbol_name）。預設模式為熱門度（PageRank 前 10% 分位減去實用型超級樞紐）。對於關節點／橋接割點，設定 high_impact_mode=risk。

high_impact_mode選填

類型: Literal[popularity, risk]
預設值: popularity
說明: 當 high_impact=true 時：流行度 = 最高 PageRank 十分位數減去公用事業大型集線器/模組；風險 = 按 SMV bridge_count 然後 k_core 排名的銜接點（結構重構風險，而不是中心受歡迎）

in_cycle選填

類型: bool
預設值
說明: 僅限處於依賴循環中的符號

exclude_test_paths選填

類型: bool
預設值: true
說明: 依圖表指標瀏覽時，請在排名前排除測試、fixtures、第三方程式碼和範例。透過命名符號進行的查找沒有改變。

參數	類型	必填	預設值	說明
`symbol_name`	`str`	否	-	要搜尋的符號名稱（可選 — 省略以依指標瀏覽）
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`scope`	`Literal[definitions, references, both]`	否	`both`	搜尋範圍（definitions\|references\|both）
`limit`	`int`	否	`15`	本頁回傳的最大結果數
`offset`	`int`	否	-	已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
`cursor`	`str`	否	-	來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。
`find_similar`	`bool`	否		包含相似符號名稱
`include_metrics`	`bool`	否		包含中心性指標
`metrics_detail`	`Literal[summary, full]`	否	`summary`	當include_metrics=true時：summary（預設）返回判決訊號+refactor_risk；full 返回更大的規劃指標集
`path_filter`	`str`	否	-	路徑萬用字元篩選（例如 'src/'、'*.py'）
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	否	-	以符號類型篩選
`high_impact`	`bool`	否		瀏覽在架構上重要的符號（省略 symbol_name）。預設模式為熱門度（PageRank 前 10% 分位減去實用型超級樞紐）。對於關節點／橋接割點，設定 high_impact_mode=risk。
`high_impact_mode`	`Literal[popularity, risk]`	否	`popularity`	當 high_impact=true 時：流行度 = 最高 PageRank 十分位數減去公用事業大型集線器/模組；風險 = 按 SMV bridge_count 然後 k_core 排名的銜接點（結構重構風險，而不是中心受歡迎）
`in_cycle`	`bool`	否		僅限處於依賴循環中的符號
`exclude_test_paths`	`bool`	否	`true`	依圖表指標瀏覽時，請在排名前排除測試、fixtures、第三方程式碼和範例。透過命名符號進行的查找沒有改變。

最適用於：

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

不建議用於：

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

analyze_dependencies穩定版

透過 dependency_search（dependents/incoming）實現的 blast-radius 別名。新代理請優先使用帶 analysis_type="dependents" 或 "impact" 的 dependency_search。保留傳統的多跳 impact 回應形狀（graph、connection_summary、帶 refactor_risk 的選用指標）。使用 graph_view 來限定關聯族：dependency（預設）、type、data_flow、control_flow。

參數：

repository選填

類型: str
說明: 儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

target必填

類型: str
說明: 要分析的符號名稱

depth選填

類型: Literal[shallow, balanced, deep]
預設值: balanced
說明: 分析深度（支援別名：auto、shallow/quick=1、balanced/medium=2、deep/thorough=3）

limit選填

類型: int
預設值: 10
說明: 本頁回傳的最大結果數

offset選填

類型: int
說明: 已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。

cursor選填

類型: str
說明: 來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。

direction選填

類型: Literal[incoming, outgoing, both]
預設值: incoming
說明: 遍歷方向：'outgoing'、'incoming' 或 'both'

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 時作為預設。為與 dependency_search 保持一致而使用相同參數名稱。

path_filter選填

類型: str
說明: 將目標符號解析限制在指定的檔案路徑前綴內；回傳的圖譜關聯可能會延伸至該路徑之外。

language_filter選填

類型: str
說明: 語言篩選

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

per_hop_limit選填

類型: int
說明: 每一跳的最大關聯數（1-300）

include_metrics選填

類型: bool
預設值
說明: 在結果中包含圖形指標，每個指標都透過衍生的 refactor_risk 區塊 ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}) 進行豐富。當不是鉸接點（在選定視圖中）時，risk 為 "low"；當鉸接點橋接少量邊緣時，"medium" 為 "medium"；當橋接許多邊緣時，"high"（啟發式閾值，未經經驗驗證）。當該交易品種/視圖不存在指標行時，忽略每個交易品種。

metrics_detail選填

類型: Literal[summary, full]
預設值: summary
說明: 當include_metrics=true時：summary（預設）返回判決訊號+refactor_risk；full 返回更大的規劃指標集

include_edge_metadata選填

類型: bool
預設值
說明: 包括原始邊緣元資料和權重。預設情況下停用，因為提取器元資料可能很大；啟用時會報告豐富覆蓋範圍。

exclude_test_paths選填

類型: bool
預設值: true
說明: 預設 true：從傳回的圖形邊緣排除測試、夾具、供應商和範例路徑。设置 false 以包含它们。

include_module_symbols選填

類型: bool
預設值
說明: 預設情況下，當 from_name 或 to_name 是合成 __module__ 符號時，false 排除圖形邊緣。設定 true 以包含模組級邊緣。

參數	類型	必填	預設值	說明
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`target`	`str`	是	-	要分析的符號名稱
`depth`	`Literal[shallow, balanced, deep]`	否	`balanced`	分析深度（支援別名：auto、shallow/quick=1、balanced/medium=2、deep/thorough=3）
`limit`	`int`	否	`10`	本頁回傳的最大結果數
`offset`	`int`	否	-	已棄用的相容性 offset。請改用 pagination.next_cursor 中的 cursor。
`cursor`	`str`	否	-	來自 pagination.next_cursor 的不透明 cursor。原樣傳遞，並保持 query 與篩選條件不變。
`direction`	`Literal[incoming, outgoing, both]`	否	`incoming`	遍歷方向：'outgoing'、'incoming' 或 'both'
`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 時作為預設。為與 dependency_search 保持一致而使用相同參數名稱。
`path_filter`	`str`	否	-	將目標符號解析限制在指定的檔案路徑前綴內；回傳的圖譜關聯可能會延伸至該路徑之外。
`language_filter`	`str`	否	-	語言篩選
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`per_hop_limit`	`int`	否	-	每一跳的最大關聯數（1-300）
`include_metrics`	`bool`	否		在結果中包含圖形指標，每個指標都透過衍生的 refactor_risk 區塊 ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}) 進行豐富。當不是鉸接點（在選定視圖中）時，risk 為 "low"；當鉸接點橋接少量邊緣時，"medium" 為 "medium"；當橋接許多邊緣時，"high"（啟發式閾值，未經經驗驗證）。當該交易品種/視圖不存在指標行時，忽略每個交易品種。
`metrics_detail`	`Literal[summary, full]`	否	`summary`	當include_metrics=true時：summary（預設）返回判決訊號+refactor_risk；full 返回更大的規劃指標集
`include_edge_metadata`	`bool`	否		包括原始邊緣元資料和權重。預設情況下停用，因為提取器元資料可能很大；啟用時會報告豐富覆蓋範圍。
`exclude_test_paths`	`bool`	否	`true`	預設 true：從傳回的圖形邊緣排除測試、夾具、供應商和範例路徑。设置 false 以包含它们。
`include_module_symbols`	`bool`	否		預設情況下，當 from_name 或 to_name 是合成 __module__ 符號時，false 排除圖形邊緣。設定 true 以包含模組級邊緣。

最適用於：

已依賴其回應結構（graph、connection_summary）的舊有呼叫方

不建議用於：

新的代理迴圈 —— 優先使用 dependency_search，它共用同一套巡訪核心

get_task_context穩定版

要在不熟悉的區域開始工作嗎？描述任務（例如「新增 SSO 支援」、「修正計費 webhook」），即可在單次呼叫中取得相關的程式碼、符號與依賴情境——等同於從多個搜尋組合出來的結果。

參數：

task_description必填

類型: str
說明: 您需要情境的任務描述

repository選填

類型: str
說明: 儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

limit選填

類型: int
預設值: 15
說明: 每層的最大結果數

scope選填

類型: Literal[semantic, symbols, dependencies, all]
預設值: all
說明: 要包含的情境層（有效值：'semantic'、'symbols'、'dependencies'、'all'；預設：['semantic','symbols','dependencies']）

language_filter選填

類型: str
說明: 語言篩選

path_filter選填

類型: str
說明: 以檔案路徑前綴篩選

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

include_related_context選填

類型: bool
預設值
說明: 包含來自相鄰符號的相關情境

seed_symbol_ids選填

類型: list[str]
說明: Tier-1 明定種子：代理已知與任務核心相關的符號 ID（例如代理已開啟的檔案內符號）。在 dependencies/related_context 層級中會優先排名。為累加行為 — 若要今日僅以關鍵字為種子，可省略。

seed_file_paths選填

類型: list[str]
說明: Tier-1 明確種子：代理已開啟或剛編輯的已索引檔案路徑。回傳有界的直接檔案證據，並為圖譜脈絡依每個檔案解析最多 5 個符號，包括無符號的文件與設定。屬附加性——若需僅關鍵字行為則省略。

參數	類型	必填	預設值	說明
`task_description`	`str`	是	-	您需要情境的任務描述
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`limit`	`int`	否	`15`	每層的最大結果數
`scope`	`Literal[semantic, symbols, dependencies, all]`	否	`all`	要包含的情境層（有效值：'semantic'、'symbols'、'dependencies'、'all'；預設：['semantic','symbols','dependencies']）
`language_filter`	`str`	否	-	語言篩選
`path_filter`	`str`	否	-	以檔案路徑前綴篩選
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`include_related_context`	`bool`	否		包含來自相鄰符號的相關情境
`seed_symbol_ids`	`list[str]`	否	-	Tier-1 明定種子：代理已知與任務核心相關的符號 ID（例如代理已開啟的檔案內符號）。在 dependencies/related_context 層級中會優先排名。為累加行為 — 若要今日僅以關鍵字為種子，可省略。
`seed_file_paths`	`list[str]`	否	-	Tier-1 明確種子：代理已開啟或剛編輯的已索引檔案路徑。回傳有界的直接檔案證據，並為圖譜脈絡依每個檔案解析最多 5 個符號，包括無符號的文件與設定。屬附加性——若需僅關鍵字行為則省略。

最適用於：

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

不建議用於：

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

get_file穩定版

依路徑從已索引的儲存庫讀取檔案。對於磁碟上的檔案請優先使用本地 Read 工具——本工具用於工作樹中沒有的跨儲存庫或遠端查找。支援選用的行範圍；對於因 token 而被截斷的回應，可從 metadata.next_line_start 繼續。

參數：

file_path必填

類型: str
說明: 相對於儲存庫根的檔案路徑

repository選填

類型: str
說明: 儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。

line_start選填

類型: int
說明: 開始行（以 1 為起始）

line_end選填

類型: int
說明: 結束行（從 1 開始，含邊界；必須不小於 line_start）

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

max_tokens選填

類型: int
預設值: 5000
說明: 最大回傳 token 數

include_metadata選填

類型: bool
預設值: true
說明: 在回應中包含檔案中繼資料

參數	類型	必填	預設值	說明
`file_path`	`str`	是	-	相對於儲存庫根的檔案路徑
`repository`	`str`	否	-	儲存庫（owner/repo[:branch]）。可選 — 當 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時可省略；僅在要鎖定不同的已編入索引之儲存庫時才明確傳入。回應會顯示實際使用的儲存庫。
`line_start`	`int`	否	-	開始行（以 1 為起始）
`line_end`	`int`	否	-	結束行（從 1 開始，含邊界；必須不小於 line_start）
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`max_tokens`	`int`	否	`5000`	最大回傳 token 數
`include_metadata`	`bool`	否	`true`	在回應中包含檔案中繼資料

最適用於：

遠端或已索引檔案的快照（行範圍、詞元上限）

不建議用於：

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

系統與實用工具#

repository_context穩定版

列出你可以搜尋的儲存庫，或取得其中之一的身分資訊（namespace/branch、indexed_commit_sha／索引新鮮度）。用 action:"list" 呼叫一次，以了解搜尋工具接受的確切儲存庫 slug。（若你的金鑰只有單一儲存庫，搜尋工具會預設使用它——可以略過。）namespace 範圍內的檔案／blob／邊數量可透過 include_statistics=true 選擇啟用。

參數：

action必填

類型: Literal[list, info]
說明: 操作：列出可用儲存庫或取得儲存庫資訊（list 或 info）

repository選填

類型: str
說明: 儲存庫（owner/repo 或 owner/repo:branch，info 操作時為必填）

branch選填

類型: str
說明: 分支覆寫（留空則使用 repository 參數或預設）

pattern選填

類型: str
說明: 以模式篩選儲存庫清單

include_statistics選填

類型: bool
預設值
說明: 可選啟用：包含 namespace 範圍內的已索引資料數量（檔案／blob／邊）。預設 false——儲存庫身分不需要這項較慢的彙總。

limit選填

類型: int
預設值: 20
說明: 本頁回傳的最大結果數

offset選填

類型: int
說明: 已棄用的兼容性偏移量。與 pagination.next_cursor 相比，更喜歡 cursor。

cursor選填

類型: str
說明: pagination.next_cursor 的不透明 cursor。不加修改地傳遞它，並保持查詢和過濾器不變。

參數	類型	必填	預設值	說明
`action`	`Literal[list, info]`	是	-	操作：列出可用儲存庫或取得儲存庫資訊（list 或 info）
`repository`	`str`	否	-	儲存庫（owner/repo 或 owner/repo:branch，info 操作時為必填）
`branch`	`str`	否	-	分支覆寫（留空則使用 repository 參數或預設）
`pattern`	`str`	否	-	以模式篩選儲存庫清單
`include_statistics`	`bool`	否		可選啟用：包含 namespace 範圍內的已索引資料數量（檔案／blob／邊）。預設 false——儲存庫身分不需要這項較慢的彙總。
`limit`	`int`	否	`20`	本頁回傳的最大結果數
`offset`	`int`	否	-	已棄用的兼容性偏移量。與 pagination.next_cursor 相比，更喜歡 cursor。
`cursor`	`str`	否	-	pagination.next_cursor 的不透明 cursor。不加修改地傳遞它，並保持查詢和過濾器不變。

最適用於：

列出可存取的儲存庫
解析儲存庫識別、分支以及 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
說明: 指引主題（例如 tool_selection、semantic_search）。僅用於舊版 evaluate：運算式字串。

description選填

類型: str
說明: 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`	`Literal[guidance, report_bug, request_feature, evaluate]`	是	-	主要用途：guidance、report_bug、request_feature。僅限舊版／相容：evaluate（確定性的運算式引擎；不屬於主要代理工作流程）。
`query`	`str`	否	-	指引主題（例如 tool_selection、semantic_search）。僅用於舊版 evaluate：運算式字串。
`description`	`str`	否	-	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 維護者的持久性錯誤報告和功能請求

不建議用於：

數學／雜湊／字串計算 —— evaluate 操作僅為舊有／向後相容用途；優先在本機主機上計算

最佳實務#

有意識地使用明確覆寫: 當您的 MCP 用戶端提供此次請求的預設值，或金鑰僅能存取單一儲存庫時，請省略儲存庫；否則請明確傳入。
選擇正確的搜尋模式: 大多數情況下搭配 mode="auto" 使用 intelligent_search。當您已確定需求時再指定具體模式。
善用語言篩選: 使用 language_filter 縮小結果範圍並提升效能。
GraphRAG 重要性加權: 為使排序對代理程式而言安全，語意搜尋預設停用 GraphRAG 重要性加權（boost_by_importance=false）。若要進行架構巡覽，可傳入 boost_by_importance=true，以啟用基於中心度的重新排序。
儲存庫比對不區分大小寫，而非模糊比對: repository_context 以不區分大小寫的方式比對儲存庫名稱——它不會修正拼字錯誤。可在 info 動作上查看 metadata.resolution_reason（"exact" 或 "corrected"），以了解名稱是如何解析的。
組合使用工具: 結合使用多個 API 方法以取得全面分析結果。
處理大量結果: 使用 limit 與工具專屬分頁控制（例如在 get_file 中使用 line_start/line_end）。
使用 ask_maguyva 取得工具指引: ask_maguyva 的 evaluate 操作（雜湊、base64、JSON、數學運算）僅供舊版／向後相容用途。若要取得本地工具優先矩陣以及逐一工具的完整速查表，請改為以 operation="guidance" 與 query="tool_selection" 呼叫 ask_maguyva。
在編輯前後驗證影響: 在編輯共用符號之前，先以 analysis_type="impact" 呼叫 dependency_search（或傳入 changed_paths 以查看 PR／diff 影響），檢視其影響範圍。編輯之後，將 verify_after_edit=true 與 targets 及／或 changed_paths 一併設定，即可對同一批符號進行精簡的重新檢查。

效能特性#

操作	效能說明
語意搜尋	亞秒級，但每次都會包含一次即時的嵌入 API 呼叫（不快取）——請預期在向量查詢之外還會有額外延遲
文字搜尋	exact/regex 為亞秒級；模糊內容搜尋在用戶端分頁，因此位移越深成本越高——請用 path_filter/language_filter 縮小範圍
結構搜尋	以 AST 建立索引——成本隨結果數量增加，而非隨儲存庫大小增加
相依性搜尋	成本隨深度增加——除非需要多跳上下文，否則建議使用 depth="shallow"；per_hop_limit 用於限制展開範圍
檔案擷取	單一檔案近乎即時——對於大型檔案，請用 line_start/line_end 或 max_tokens 分頁，而非一次大量拉取
儲存庫上下文	命名空間解析僅依請求快取，不跨呼叫保留——每次工具呼叫都會重新解析
ask_maguyva（guidance / evaluate）	近乎即時——在 Worker 內執行，無需資料庫呼叫

錯誤處理#

所有 API 方法都會回傳一個結構化的封裝（envelope）：

status: 字串——"success" 或 "error"。降級比對與新鮮度訊號位於巢狀欄位中，例如 repository_context 上的 metadata.resolution_reason 或 metadata.index_freshness.status。
tool: 產生該回應的工具名稱
data: 成功時的結果酬載（結構因工具而異）
error: 當 status 為 "error" 時的結構化錯誤物件——包含 type、message、suggestions 與 recovery_actions
metadata: 關於此操作的額外資訊（路由、快取、參數調整）
pagination: 出現在清單回應中——包含 has_more 與 next_cursor

在處理結果之前，務必先檢查 status 欄位——它的值只會是 "success" 或 "error"。對於降級比對或新鮮度訊號，請改讀巢狀欄位：repository_context 上的 metadata.resolution_reason，或 metadata.index_freshness.status（known/partial/unknown/unavailable）。

快速上手#

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

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

MCP API 參考文件

API 概覽#

儲存庫參數格式#

語言篩選#

核心搜尋工具#

intelligent_search穩定版

semantic_search穩定版

text_pattern_search穩定版

結構與圖譜工具#

structural_search穩定版

dependency_search穩定版

程式碼分析工具#

find_symbol穩定版

analyze_dependencies穩定版

get_task_context穩定版

get_file穩定版

系統與實用工具#

repository_context穩定版

ask_maguyva穩定版

最佳實務#

效能特性#

錯誤處理#

快速上手#