Skip to content

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.

Pick the right tool#

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

  • intelligent_search — start here for any natural-language codebase question; it routes across semantic, symbol, structural, and dependency search.
  • 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).

Install and verify a client#

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, Windsurf, 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.

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

Ask before you edit#

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 (including post-edit verification when your client supports the verify flags) so callers still resolve as expected.

Full parameters: MCP API Reference.

Search, then change#

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.
  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.

Why this loop works: How It Works.

Empty or thin results#

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.

Setup failures: Troubleshooting.

Work across multiple repositories#

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.

New to Maguyva? Walk Quickstart first, then come back here for day-two loops.

Next steps#