# Cookbook

Canonical source: https://maguyva.ai/docs/cookbook

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

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](https://maguyva.ai/docs/mcp-api). For first-time setup, use the [Quickstart](https://maguyva.ai/docs/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 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).

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

### 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](https://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](https://maguyva.ai/docs/installation) (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.

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

Stuck on keys, bridges, or missing repos? [Troubleshooting](https://maguyva.ai/docs/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` 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.

```json
{
  "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](https://maguyva.ai/docs/mcp-api).

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

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

Why this loop works: [How It Works](https://maguyva.ai/docs/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](https://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](https://maguyva.ai/docs/troubleshooting).

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

Setup failures: [Troubleshooting](https://maguyva.ai/docs/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](https://maguyva.ai/docs/mcp-api).

Setting up for the first time? Start with [Quickstart](https://maguyva.ai/docs/quickstart), then use these recipes for everyday tasks.