跳转到内容

实用手册

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

选择合适的工具#

大多数问题只需一次调用即可开始。只有首个答案过宽或过于单薄时，才继续升级。

  • intelligent_search — 任何自然语言代码库问题都从这里开始；它会在语义、符号、结构和依赖搜索之间路由。
  • 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、Windsurf、Zed 等的原生远程配置）。
  4. 向代理询问 "我连接了哪些仓库？" — 这会端到端验证身份认证和 repository_context。
  5. 针对该仓库提出一个你能评判答案的真实问题。结果应包含索引树中的文件路径和行号。

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

编辑之前先询问#

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

  1. 如果知道符号名称，调用 find_symbol 定位定义和使用位置。
  2. 如果只有任务描述（如“添加 SSO”或“修复账单 Webhook”），从 get_task_context 或 intelligent_search 开始。
  3. 编辑共享符号前，调用 dependency_search 分析依赖项和影响（也可传入变更路径进行 PR 式影响分析），以看清波及范围。
  4. 打开引用的文件（磁盘上的文件在本地读取；远程或跨仓库路径使用 get_file），并对照真实代码确认计划。
  5. 编辑后用 dependency_search 重新检查相同符号（客户端支持时包括编辑后验证标志），确认调用方仍按预期解析。

完整参数：MCP API 参考。

先搜索，再修改#

默认代理循环：探索 → 锁定符号 → 基于证据编辑。

  1. 从 intelligent_search 和自然语言查询开始（如“会话过期如何工作”或“重试逻辑在哪里”）。
  2. 首个结果窗口噪声较多时，用语言或路径过滤器缩小范围。
  3. 将有价值的命中交给 find_symbol 或 dependency_search 深挖，不要重复提出同一个模糊问题。
  4. 只有在需要磁盘上不存在的特定已索引路径时才使用 get_file。
  5. 使用常规客户端工具进行编辑。Maguyva 用于发现和验证，不负责写入。

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

结果为空或信息不足#

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

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

设置故障：故障排除。

跨多个仓库工作#

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

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

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

刚开始使用 Maguyva？先完成 快速入门，需要日常工作循环时再回到这里。

后续步骤#