实用手册

面向日常 Maguyva MCP 工作的实用操作指南。每份指南都会列出工具和顺序，但不是完整的参数参考。工具参数请参阅 MCP API 参考；首次设置请参阅 快速入门。

这些 JSON 块是 MCP tools/call 的输入。请将 owner/repo、分支名称和符号名称替换为你自己的仓库中的值。

大多数问题只需一次调用即可开始。只有首个答案范围太宽或信息不足时，才进一步调用工具。

• intelligent_search — 用自然语言询问代码库问题时，从这里开始。 默认的 auto/balanced 会在能够高置信度判断意图时，将定义类问题路由到结构搜索，将引用或影响类问题路由到图搜索，将精确匹配类问题路由到文本搜索。其他问题使用语义搜索和已索引文本。 使用 mode=hybrid，或将 auto 与 quality=thorough 搭配，即可请求全部四种搜索模式。显式指定的 mode 优先于 quality。
• find_symbol — 你已经知道函数、类或变量的名称。
• dependency_search — 评估影响范围：调用方、依赖该符号的代码，以及编辑前后的影响。
• get_task_context — 面对陌生区域时，根据任务描述获取限定范围的一组文件、符号和依赖项。
• repository_context — 列出可访问的仓库，或检查仓库名称如何解析。
• 带 operation="guidance" 的 ask_maguyva — 在本地获取工具选择和 Maguyva 使用帮助（不会修改仓库）。

将 Maguyva 接入你的 MCP 客户端，并通过真实仓库列表确认连接。

1. 在 app.maguyva.ai 中创建 API 密钥（密钥以 mgv_ 开头）。
2. 连接并索引至少一个你已经熟悉的 GitHub 仓库。
3. 按照 安装指南 配置客户端（Claude Code 插件，或 Cursor、VS Code、Devin Desktop、Zed 等的原生远程配置）。
4. 向智能体询问 "我连接了哪些仓库？"，这会端到端验证身份认证和 repository_context。
5. 针对该仓库提出一个你能评判答案的真实问题。结果应包含索引树中的文件路径和行号。

{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}

卡在密钥、桥接或仓库缺失问题上？请参阅 故障排除。

修改共享代码前，先梳理符号和影响范围。Maguyva 工具不会修改仓库，而是为客户端在本地执行的编辑提供依据。

1. 如果知道符号名称，调用 find_symbol 定位定义和使用位置。
2. 如果只有任务描述（如“添加 SSO”或“修复账单 Webhook”），从 get_task_context 或 intelligent_search 开始。
3. 编辑共享符号前，调用 dependency_search 进行 dependents/impact 分析，查看依赖它的代码和影响（也可传入变更路径进行 PR 式影响分析），以看清影响范围。
4. 打开引用的文件（磁盘上的文件在本地读取；远程或跨仓库路径使用 get_file），并对照真实代码确认计划。
5. 编辑后，使用 dependency_search，指定 verify_after_edit=true 以及 targets 或 changed_paths，重新检查相同的符号。它读取的是已索引的图，而不是尚未提交的本地更改：将其视为新修订版本的依据前，请检查 indexed_commit_sha 和索引的新鲜度，并运行本地测试。

{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}

完整参数：MCP API 参考。

默认智能体循环：探索 → 锁定符号 → 基于证据编辑。

1. 从 intelligent_search 和自然语言查询开始（如“会话过期如何工作”或“重试逻辑在哪里”）。
2. 如果首批结果噪声较多，可用语言或路径筛选器缩小范围。language_filter 会从 auto/hybrid 中排除图搜索；仅路由到图搜索的 auto 查询会回退到语义和文本搜索。显式图模式与 language_filter 不能搭配使用。查看 routing_decision.modalities_used 了解所选搜索计划；warnings 仅在服务器发出警告时才会出现。
3. 将有价值的命中交给 find_symbol 或 dependency_search 深挖，不要重复提出同一个模糊问题。
4. 只有在需要磁盘上不存在的特定已索引路径时才使用 get_file。
5. 使用常规客户端工具进行编辑。Maguyva 用于发现和验证，不负责写入。

{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}

此循环有效的原因：工作原理。

工具没有返回有用内容时，先修复仓库名称解析和索引问题，不要无休止地改写查询。

1. 在 app.maguyva.ai 中确认仓库已连接并完成索引。
2. 检查仓库字符串："owner/repo" 使用默认分支；"owner/repo:branch" 固定分支。匹配不区分大小写，但不是模糊匹配，拼写错误不会自动纠正。
3. 使用 action="info" 调用 repository_context，检查仓库名称解析的元数据（例如 metadata.resolution_reason）。
4. 仅当 MCP 客户端提供请求默认值，或密钥恰好只能访问一个仓库时，才省略 repository；否则请明确传入。
5. 使用更具体的查询、通过 find_symbol 查找已知符号，或添加语言/路径过滤器重试。如果连接本身有问题，请参阅 故障排除。

{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}

设置故障：故障排除。

当一个密钥能看到多个仓库时，准确定位目标已索引仓库。

1. 使用 action="list" 调用一次 repository_context，了解该密钥可以搜索的确切仓库标识。
2. 需要非默认仓库时，在搜索和符号工具中明确传入 repository（例如 "owner/other-repo" 或 "owner/other-repo:develop"）。
3. 除非有意在不同调用中跨仓库比较，否则一个问题只对应一个仓库。
4. 文件位于已索引仓库而非当前工作树时，使用 get_file。
5. 请记住：工具绝不会写回 GitHub；多仓库上下文只用于读取和规划。

仓库格式详情：MCP API 参考。

• 快速入门 — 密钥、索引、连接、首个可评判的答案
• 安装指南 — 按客户端配置 MCP
• MCP API 参考 — 逐个参数说明所有工具
• 故障排除 — API 密钥、桥接和仓库故障