Cookbook

Practical recipes for everyday Maguyva MCP work. Each recipe names the tools and the sequence — not a full parameter reference. For tool parameters, use the MCP API Reference. For first-time setup, use the Quickstart.

The JSON blocks are MCP tools/call inputs. Replace owner/repo, branch, and symbol names with values from your repository.

Most questions start with one call. Escalate only when the first answer is too broad or too thin.

• intelligent_search — start here for a natural-language codebase question. Default auto/balanced routes confident definition questions to structural search, reference or impact questions to graph, and exact-match questions to text. Other questions use semantic meaning and indexed text. Use mode=hybrid or auto with quality=thorough to request all four; an explicit mode takes precedence over quality.
• find_symbol — you already know the function, class, or variable name.
• dependency_search — blast radius: callers, dependents, or impact before (and after) an edit.
• get_task_context — unfamiliar area; one bounded bundle of files, symbols, and dependencies for a task description.
• repository_context — list accessible repositories or inspect how a repository name resolves.
• ask_maguyva with operation="guidance" — local help on tool selection and Maguyva usage (no repo mutation).

Get Maguyva into your MCP client and confirm the connection with a real repository list.

1. Create an API key in app.maguyva.ai (keys start with mgv_).
2. Connect and index at least one GitHub repository you already understand.
3. Wire your client using the Installation Guide (Claude Code plugin, or native remote config for Cursor, VS Code, Devin Desktop, Zed, and others).
4. Ask your agent "What repositories do I have connected?" — that exercises authentication and repository_context end to end.
5. Ask one real question about that repo whose answer you can grade. You should see file paths and line numbers from the indexed tree.

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

Stuck on keys, bridges, or missing repos? Troubleshooting.

Map symbols and blast radius before changing shared code. Maguyva tools do not modify your repositories — they inform the edit your client applies locally.

1. If you know the symbol name, call find_symbol to land on definitions and uses.
2. If you only have a task description ("add SSO", "fix the billing webhook"), start with get_task_context or intelligent_search.
3. Before editing a shared symbol, call dependency_search with dependents/impact analysis (or pass changed paths for PR-style impact) so you see the blast radius.
4. Open the cited files (local read for files on disk; get_file for remote/cross-repo paths) and confirm the plan against real code.
5. After the edit, re-check the same symbols with dependency_search using verify_after_edit=true and targets or changed_paths. This reads the indexed graph, not uncommitted local changes: check indexed_commit_sha and index freshness before treating it as evidence for the new revision, and run local tests.

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

Full parameters: MCP API Reference.

A default agent loop: explore → pin symbols → edit with evidence.

1. Start with intelligent_search and a plain-language query ("how does session expiry work", "where is retry logic").
2. Narrow with language or path filters when the first window is noisy. A language_filter omits graph from auto/hybrid; an auto query routed only to graph falls back to semantic and text. Explicit graph mode with a language_filter is rejected. Inspect routing_decision.modalities_used to see the selected search plan; warnings is present only when the server raised one.
3. Promote promising hits to find_symbol or dependency_search instead of re-asking the same vague question.
4. Use get_file only when you need a specific indexed path that is not on disk.
5. Edit in your normal client tools. Maguyva is for discovery and verification — not writes.

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

Why this loop works: How It Works.

When tools return nothing useful, fix resolution and indexing before rewriting the query forever.

1. Confirm the repository is connected and finished indexing in app.maguyva.ai.
2. Check the repository string: "owner/repo" uses the default branch; "owner/repo:branch" pins a branch. Matching is case-insensitive, not fuzzy — typos do not auto-correct.
3. Call repository_context with action="info" and inspect resolution metadata (for example metadata.resolution_reason).
4. Omit repository only when your MCP client supplies a request default or the key can access exactly one repository; otherwise pass it explicitly.
5. Retry with a more specific query, a known symbol name via find_symbol, or a language/path filter. If the connection itself is broken, use Troubleshooting.

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

Setup failures: Troubleshooting.

Target the right indexed repo when a key can see more than one.

1. Call repository_context with action="list" once to learn the exact slugs your key can search.
2. Pass repository explicitly on search and symbol tools when you need a non-default repo (for example "owner/other-repo" or "owner/other-repo:develop").
3. Keep one question = one repository unless you intentionally compare across repos in separate calls.
4. Use get_file when the file lives in an indexed repo that is not your current working tree.
5. Remember: tools never write back to GitHub — multi-repo context is for reading and planning only.

Repository format details: MCP API Reference.

• Quickstart — key, index, connect, first graded answer
• Installation Guide — per-client MCP config
• MCP API Reference — every tool, parameter by parameter
• Troubleshooting — API key, bridge, and repository failures