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" - 未指定分支时，使用主分支 "owner/repository"
请求默认值或唯一仓库默认值: 当 MCP 客户端提供请求默认值，或密钥恰好只能访问一个仓库时，请省略仓库；否则请显式传入

示例提示词:

询问特定仓库：    “在 owner/my-repo 中搜索身份验证中间件”
列出可访问的仓库：  "这个 Maguyva 密钥可以访问哪些仓库？"
针对单次查询覆盖：  “在 owner/other-repo:develop 中搜索身份验证模式”

语言过滤#

所有搜索工具都支持按编程语言过滤结果：

language_filter="python" - 只过滤 Python 文件
language_filter="typescript" - 只过滤 TypeScript 文件
区分大小写: 使用小写的语言名称
默认值: 空字符串（不过滤）——返回所有语言的结果
支持的覆盖范围: 语言过滤器适用于全部 279+ 种受支持的语言及基于文本的技术。完整列表请参见兼容性。

“只在 Python 文件中查找身份验证中间件”
“在 TypeScript 中搜索数据库连接”

本 API 参考文档于 2026年7月22日从源码生成。

核心搜索工具#

intelligent_search稳定

任何代码库问题都从这里开始。输入自然语言查询（例如“身份验证如何工作”“计费在哪里处理”），它会在整个已索引仓库的语义、符号、结构和依赖搜索之间自动路由。探索和规划时应优先使用它，而不是 Explore 代理或 Grep/Glob；它会一次搜索整个已索引仓库，而不是逐个扫描文件。

参数：

query必填

类型: str
描述: 搜索查询

repository可选

类型: str
描述: 仓库格式为 owner/repo[:branch]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

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
描述: 分支覆盖

quality可选

类型: Literal[quick, balanced, thorough]
默认值: balanced
描述: 搜索质量

include_content可选

类型: bool
默认值: true
描述: 在结果中包含内容

explain_routing可选

类型: bool
默认值
描述: 包含路由决策说明

importance_weight可选

类型: float
默认值: 0.3
描述: 重要性提升权重（0=不提升，1=完全提升）

orphans可选

类型: bool
默认值
描述: 返回没有任何传入引用的符号（可能是死代码）。有助于清理工作，但可能包含装饰器、内部函数和 CLI 入口点。

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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`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`	否	-	分支覆盖
`quality`	`Literal[quick, balanced, thorough]`	否	`balanced`	搜索质量
`include_content`	`bool`	否	`true`	在结果中包含内容
`explain_routing`	`bool`	否		包含路由决策说明
`importance_weight`	`float`	否	`0.3`	重要性提升权重（0=不提升，1=完全提升）
`orphans`	`bool`	否		返回没有任何传入引用的符号（可能是死代码）。有助于清理工作，但可能包含装饰器、内部函数和 CLI 入口点。
`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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

limit可选

类型: int
默认值: 5
描述: 该排名 top-K 窗口中的最大结果数

similarity_threshold可选

类型: float
默认值: 0.6
描述: 最小相似度分数

language_filter可选

类型: str
描述: 将结果过滤为检测到属于该编程语言的文件

path_filter可选

类型: str
描述: 按文件路径前缀筛选

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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`limit`	`int`	否	`5`	该排名 top-K 窗口中的最大结果数
`similarity_threshold`	`float`	否	`0.6`	最小相似度分数
`language_filter`	`str`	否	-	将结果过滤为检测到属于该编程语言的文件
`path_filter`	`str`	否	-	按文件路径前缀筛选
`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稳定

搜索已索引内容。exact 和 regex 模式会 grep 完整的文件/blob 语料库；fuzzy content 模式搜索范围受限的语义代码块语料库。file 和 symbol 范围仅支持 fuzzy。对于磁盘上已知的狭窄目录，请使用本地 Grep。

参数：

query必填

类型: str
描述: 文本模式

repository可选

类型: str
描述: 仓库格式为 owner/repo[:branch]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

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
描述: 按文件路径前缀筛选

case_sensitive可选

类型: bool
默认值
描述: 区分大小写

branch可选

类型: str
描述: 分支覆盖

fuzzy_algorithm可选

类型: Literal[hybrid, trigram, levenshtein]
默认值: hybrid
描述: 模糊匹配算法

threshold可选

类型: float
默认值: 0.05
描述: 模糊搜索的最低相似度阈值

semantic_fallback可选

类型: bool
默认值
描述: 无结果时回退到语义搜索

参数	类型	必填	默认值	描述
`query`	`str`	是	-	文本模式
`repository`	`str`	否	-	仓库格式为 owner/repo[:branch]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`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`	否	-	按文件路径前缀筛选
`case_sensitive`	`bool`	否		区分大小写
`branch`	`str`	否	-	分支覆盖
`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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

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 正则表达式或模糊文本；最多 256 个字符）

node_type可选

类型: str
描述: AST 节点类型（function_definition、class_definition 等）——常见形状请优先使用 preset=。

decorator可选

类型: str
描述: 装饰器名称过滤器

base_class可选

类型: str
描述: 基类名称过滤器（查找继承自该类的子类）

language_filter可选

类型: str
描述: 语言过滤器

limit可选

类型: int
默认值: 20
描述: 本页返回的最大结果数

offset可选

类型: int
描述: 已弃用的兼容性 offset。请改用 pagination.next_cursor 中的 cursor。

cursor可选

类型: str
描述: 来自 pagination.next_cursor 的不透明 cursor。原样传递，且保持 query 和筛选条件不变。

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
默认值
描述: 当有意使用高级路径、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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`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 正则表达式或模糊文本；最多 256 个字符）
`node_type`	`str`	否	-	AST 节点类型（function_definition、class_definition 等）——常见形状请优先使用 preset=。
`decorator`	`str`	否	-	装饰器名称过滤器
`base_class`	`str`	否	-	基类名称过滤器（查找继承自该类的子类）
`language_filter`	`str`	否	-	语言过滤器
`limit`	`int`	否	`20`	本页返回的最大结果数
`offset`	`int`	否	-	已弃用的兼容性 offset。请改用 pagination.next_cursor 中的 cursor。
`cursor`	`str`	否	-	来自 pagination.next_cursor 的不透明 cursor。原样传递，且保持 query 和筛选条件不变。
`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`	否		当有意使用高级路径、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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

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
描述: 分支覆盖

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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`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`	否	-	分支覆盖
`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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

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
描述: 按文件路径前缀筛选

branch可选

类型: str
描述: 分支覆盖

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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`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`	否	-	按文件路径前缀筛选
`branch`	`str`	否	-	分支覆盖
`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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

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” = 完整上下文。使用 “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 时用作其默认值。为保持工具一致性，参数名沿用 dependency_search 的 graph_view。

path_filter可选

类型: str
描述: 将目标符号解析限制在指定的文件路径前缀内；返回的图关系可能会延伸到该路径之外。

language_filter可选

类型: str
描述: 将结果限制在某种语言内

branch可选

类型: str
描述: 分支覆盖

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}）。在所选视图中不是关节点时风险为 "low"；是连接少量边的关节点时为 "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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`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” = 完整上下文。使用 “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 时用作其默认值。为保持工具一致性，参数名沿用 dependency_search 的 graph_view。
`path_filter`	`str`	否	-	将目标符号解析限制在指定的文件路径前缀内；返回的图关系可能会延伸到该路径之外。
`language_filter`	`str`	否	-	将结果限制在某种语言内
`branch`	`str`	否	-	分支覆盖
`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}）。在所选视图中不是关节点时风险为 "low"；是连接少量边的关节点时为 "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稳定

要在不熟悉的区域开始工作？描述任务（例如 "add SSO support"、"fix the billing webhook"），即可通过一次有界调用获得相关文件、代码、符号和依赖的集合。作为种子的文件即使未定义任何符号，也会贡献直接索引的内容。如需更多结果，请继续使用该层的专用搜索工具。

参数：

task_description必填

类型: str
描述: 任务描述

repository可选

类型: str
描述: 仓库格式为 owner/repo[:branch]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

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
描述: 分支覆盖

include_related_context可选

类型: bool
默认值
描述: 包含来自相邻符号的相关上下文

seed_symbol_ids可选

类型: list[str]
描述: 第 1 级显式种子：代理已知与任务密切相关的符号 ID（例如已打开文件中的符号）。在 dependencies/related_context 层中，它们排在由关键词推导的种子之前。此参数是增量式的；省略即可保持当前仅依赖关键词的行为。

seed_file_paths可选

类型: list[str]
描述: Tier-1 显式种子：代理已打开或刚编辑的已索引文件路径。返回有界的直接文件证据，并为图上下文按每个文件解析最多 5 个符号，包括无符号的文档和配置。是附加性的——如需仅关键字行为则省略。

参数	类型	必填	默认值	描述
`task_description`	`str`	是	-	任务描述
`repository`	`str`	否	-	仓库格式为 owner/repo[:branch]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`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`	否	-	分支覆盖
`include_related_context`	`bool`	否		包含来自相邻符号的相关上下文
`seed_symbol_ids`	`list[str]`	否	-	第 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]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。

line_start可选

类型: int
描述: 起始行（从 1 开始）

line_end可选

类型: int
描述: 结束行（从 1 开始，含边界；必须不小于 line_start）

branch可选

类型: str
描述: 分支覆盖

max_tokens可选

类型: int
默认值: 5000
描述: 最大 token 数

include_metadata可选

类型: bool
默认值: true
描述: 包含元数据

参数	类型	必填	默认值	描述
`file_path`	`str`	是	-	相对于仓库根目录的文件路径
`repository`	`str`	否	-	仓库格式为 owner/repo[:branch]。可选 — 省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。响应会显示实际使用的仓库。
`line_start`	`int`	否	-	起始行（从 1 开始）
`line_end`	`int`	否	-	结束行（从 1 开始，含边界；必须不小于 line_start）
`branch`	`str`	否	-	分支覆盖
`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]
描述: 操作：列出可用仓库或获取仓库信息

repository可选

类型: str
描述: owner/repo 或 owner/repo:branch 格式的仓库（info 操作必填）

branch可选

类型: str
描述: 分支覆盖

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]`	是	-	操作：列出可用仓库或获取仓库信息
`repository`	`str`	否	-	owner/repo 或 owner/repo:branch 格式的仓库（info 操作必填）
`branch`	`str`	否	-	分支覆盖
`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 客户端提供请求默认值，或密钥恰好只能访问一个仓库时，请省略仓库；否则请显式传入。
选择正确的搜索模式: 大多数情况下，使用 intelligent_search 配合 mode="auto"。当你明确知道自己需要什么时，再指定具体模式。
善用语言过滤器: 使用 language_filter 来缩小结果范围、提升性能。
GraphRAG 加权: 为使排序对 agent 安全，语义搜索默认禁用 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、数学运算）仅为遗留／向后兼容用途。若要获取本地工具优先矩阵以及逐个工具的完整速查表，请改用 ask_maguyva，并传入 operation="guidance" 和 query="tool_selection"。
在编辑前后验证影响: 在编辑共享符号之前，先以 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 方法都返回一个结构化的响应封装：

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稳定

最佳实践#

性能特征#

错误处理#

快速开始#