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 客户端提供请求默认值，或密钥恰好只能访问一个仓库时，请省略仓库；否则请显式传入

示例提示词:

询问特定仓库：    “在 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日从源码生成。

核心搜索工具

intelligent_search 稳定

任何代码库问题都可以从这里开始。默认的 auto/balanced 会在能够高置信度判断意图时，将定义类问题路由到结构搜索，将引用或影响类问题路由到图搜索，将精确匹配类问题路由到文本搜索。其他问题使用语义搜索和已索引文本。使用 mode=hybrid，或将 auto 与 quality=thorough 搭配，即可请求全部四种搜索模式。显式指定的 mode 优先于 quality。 language_filter 会从 auto/hybrid 中排除图搜索，与显式 mode=graph 搭配使用时会被拒绝。如果还不知道路径，请优先使用此工具，而非 Grep/Glob。

参数：

query 必填

类型: str minLength=1
描述: 搜索查询

repository 可选

类型: str
描述: 仓库格式为 owner/repo[:branch]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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

semantic_search 稳定

按含义而非精确文本查找代码。当不知道关键词或符号名时，用于“重试逻辑”“用户引导流程”等概念查询。返回相关代码块，并限制文件多样性的范围；通过 boost_by_importance 可选择启用图重要性重排。概念搜索优先使用此工具而非 Grep。

参数：

query 必填

类型: str minLength=1
描述: 搜索查询（概念性、基于含义）

repository 可选

类型: str
描述: 仓库格式为 owner/repo[:branch]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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

text_pattern_search 稳定

搜索已索引内容。exact 和 regex 模式对完整文件／blob 语料执行 grep；fuzzy content 模式搜索有范围限制的语义代码块语料。file 和 symbol 范围仅支持三字符组（trigram）匹配，默认 mode=exact 会转为 fuzzy。语言、大小写及自定义阈值控制要求使用 content 范围。文件路径过滤采用有界候选窗口，并报告覆盖不完整的情况。对于磁盘上范围较小的目录，使用本地 Grep。

参数：

query 必填

类型: str minLength=1
描述: 文本模式

repository 可选

类型: str
描述: 仓库格式为 owner/repo[:branch]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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 三种回退状态。

适用场景：

精确字符串、错误信息和正则表达式
针对近似文本的三字符组（trigram）模糊匹配

不推荐用于：

磁盘上已知的路径 —— 优先使用本地的 Grep
概念性查询 —— 使用 semantic_search

结构与图谱工具

structural_search 稳定

优先使用 preset=functions|classes|methods|imports|variables（或自由格式的 pattern=）。按 AST 形状而非文本查找代码。中级筛选器包括 name_pattern、node_type、decorator、parent_child。路径、ltree 和调用筛选器属于高级功能，有意使用时请设置 advanced=true。未设置时，高级筛选器仍会应用，但会在元数据中给出警告。请至少提供一个结构选择器。

参数：

repository 可选

类型: str
描述: 仓库格式为 owner/repo[:branch]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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 正则表达式或模糊文本；最多 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

dependency_search 稳定

主要的 blast-radius／图查询入口。通过真实的调用／导入图回答“什么在调用它？”／“它使用了什么？”。编辑前的影响分析：analysis_type="dependents" 或 analysis_type="impact"（incoming，impact 默认深度为 shallow），include_metrics 默认为 false（如需中心性 + refactor_risk 请选择启用）。PR/diff 影响：传入 changed_paths 和／或 patch（unified diff）——按路径解析符号，并返回紧凑的 shallow-incoming dependents 负载，无需符号名。编辑后，设置 verify_after_edit=true 并提供 targets 和／或 changed_paths，即可对受影响的符号进行紧凑的多根重新查询。同时支持 dependencies、centrality 和 orphans。analyze_dependencies 使用相同的遍历方式进行多跳影响分析。 dependents/impact 默认包含 production_callers：按种类区分的唯一生产使用位置（call、instantiate、作为值传递的函数对应的 value_reference），以及 IMPORT 位置；排除测试，并提供 EXTRACTED/INFERRED 置信分类，而非简单堆砌指标。

参数：

repository 可选

类型: str
描述: 仓库格式为 owner/repo[:branch]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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 = 影响范围（incoming dependents；省略 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]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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 排名前 10% 的符号，并排除通用工具代码的超级枢纽。如需查找关节点或桥接割点，设置 high_impact_mode=risk。

high_impact_mode 可选

类型: Literal[popularity, risk]
默认值: popularity
描述: 当 high_impact=true 时：popularity = PageRank 排名前 10% 的符号，排除通用工具代码的超级枢纽和模块；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]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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}）。在所选视图中不是关节点时风险为 "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]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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]。可选——省略时使用请求范围内的客户端默认值（如已提供）或唯一可访问的仓库；仅在需要指定另一个已索引仓库时显式传入。优先使用完全匹配的已索引分支；如果目标分支不可用，可能会回退到 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]
描述: 操作：列出可用仓库或获取仓库信息

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
描述: 已弃用的兼容性偏移量。请优先使用 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 维护者处理的错误报告和功能请求

不推荐用于：

数学、哈希或字符串计算——优先使用本地计算或宿主工具

最佳实践

谨慎使用显式覆盖: 当 MCP 客户端提供请求默认值，或密钥恰好只能访问一个仓库时，请省略仓库；否则请显式传入。
选择正确的搜索模式: 大多数情况下，使用 intelligent_search 配合 mode="auto"。当你明确知道自己需要什么时，再指定具体模式。
善用语言过滤器: 使用 language_filter 来缩小结果范围、提升性能。
GraphRAG 加权: 为使排序对 agent 安全，语义搜索默认禁用 GraphRAG 重要性加权（boost_by_importance=false）。若要进行架构巡览，可传入 boost_by_importance=true，以启用基于中心度的重新排序。
仓库匹配不区分大小写，而非模糊匹配: repository_context 匹配仓库名时不区分大小写，但不会纠正拼写错误。当实际提供的标识与请求的不一致时，metadata.resolution_reason 会报告 "defaulted"（未请求分支）或 "fallback"（请求的分支或仓库不可用）。请求完全匹配时，该字段会被省略。
组合使用工具: 组合使用多个 API 方法，进行全面分析。
处理大量结果: 使用 limit 以及各工具专属的分页控制项（例如 get_file 中的 line_start/line_end）。
使用 ask_maguyva 获取工具指引: 调用 ask_maguyva，指定 operation="guidance" 和 query="tool_selection"，获取工具选择建议和示例。计算和字符串转换请使用本地工具。
在编辑前后验证影响: 在编辑共享符号之前，先以 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）。

快速开始

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

最佳实践

性能特征

错误处理

快速开始

延伸阅读