# Praktické návody

Canonical source: https://maguyva.ai/cs/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).

Praktické návody pro každodenní práci s Maguyva MCP. Každý popisuje nástroje a pořadí kroků — nenahrazuje úplnou referenční příručku parametrů. Parametry nástrojů najdete v [Referenční příručka MCP API](https://maguyva.ai/docs/mcp-api). Při prvním nastavení použijte [Rychlý start](https://maguyva.ai/docs/quickstart).

### Vyberte si správný nástroj

Většina otázek začíná jedním voláním nástroje. Eskalujte pouze tehdy, když je první odpověď příliš široká nebo příliš stručná.

- `intelligent_search` — zde začněte s otázkou o kódu položenou přirozeným jazykem. Výchozí auto/balanced směruje dotazy, u nichž s vysokou jistotou rozpozná hledání definice, na strukturální vyhledávání, dotazy na reference nebo dopady do grafu a dotazy na přesnou shodu na textové vyhledávání. Ostatní dotazy využívají sémantický význam a indexovaný text. Pomocí mode=hybrid nebo auto s quality=thorough požádejte o všechny čtyři modality vyhledávání. Výslovně zvolený režim má přednost před nastavením quality.
- `find_symbol` — již znáte název funkce, třídy nebo proměnné.
- `dependency_search` — rozsah dopadu: volající, závislé části nebo dopad před (a po) úpravě.
- `get_task_context` — neznámá oblast; jeden ohraničený svazek souborů, symbolů a závislostí pro popis úlohy.
- `repository_context` — seznam přístupných úložišť nebo kontrola, jak se překládá název úložiště.
- `ask_maguyva` s `operation="guidance"` — místní nápověda k výběru nástroje a použití Maguyva (žádná změna repozitáře).

Bloky JSON jsou vstupy pro MCP tools/call. Nahraďte owner/repo, větev a názvy symbolů hodnotami ze svého repozitáře.

### Nainstalujte a ověřte klienta

Připojte Maguyva ke svému klientovi MCP a potvrďte připojení se skutečným seznamem repozitářů.

1. Vytvořte klíč API v [app.maguyva.ai](https://app.maguyva.ai) (klíče začínají `mgv_`).
2. Připojte a indexujte alespoň jedno úložiště GitHub, kterému již rozumíte.
3. Připojte svého klienta pomocí [Průvodce instalací](https://maguyva.ai/docs/installation) (plugin Claude Code nebo nativní vzdálená konfigurace pro Cursor, VS Code, Devin Desktop, Zed a další).
4. Položte agentovi otázku "Jaké repozitáře mám připojené?" — tím ověříte autentizaci a `repository_context` od začátku do konce.
5. Položte jednu skutečnou otázku o tomto repozitáři, jejíž odpověď dokážete posoudit. Měli byste vidět cesty k souborům a čísla řádků z indexovaného stromu.

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

Potíže s klíči nebo propojením nebo chybějící repozitáře? [Řešení problémů](https://maguyva.ai/docs/troubleshooting).

### Před úpravou se zeptejte

Zmapujte symboly a rozsah dopadu před změnou sdíleného kódu. Nástroje Maguyva neupravují vaše úložiště – poskytují podklady pro úpravy, které váš klient provádí lokálně.

1. Pokud znáte název symbolu, zavolejte `find_symbol`, abyste se dostali k definicím a použití.
2. Pokud máte pouze popis úkolu („přidat jednotné přihlášení“, „opravit fakturační webhook“), začněte na `get_task_context` nebo `intelligent_search`.
3. Před úpravou sdíleného symbolu zavolejte `dependency_search` s analýzou závislých částí nebo dopadu (nebo předejte změněné cesty pro dopad ve stylu PR), abyste viděli rozsah dopadu.
4. Otevřete citované soubory (lokální čtení pro soubory na disku; `get_file` pro vzdálené/cross-repo cesty) a potvrďte plán proti skutečnému kódu.
5. Po úpravě znovu zkontrolujte stejné symboly pomocí `dependency_search` s verify_after_edit=true a targets nebo changed_paths. Nástroj čte indexovaný graf, nikoli lokální změny bez commitu: než výsledek použijete jako důkaz pro novou revizi, zkontrolujte indexed_commit_sha a aktuálnost indexu a spusťte lokální testy.

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

Kompletní parametry: [Referenční příručka MCP API](https://maguyva.ai/docs/mcp-api).

### Vyhledejte a změňte

Výchozí smyčka agenta: prozkoumat → ukotvit symboly → upravit pomocí důkazů.

1. Začněte se `intelligent_search` a jednoduchým dotazem („jak funguje vypršení platnosti relace“, „kde je logika opakovaných pokusů“).
2. Pokud je první sada výsledků příliš široká, zúžte ji filtrem jazyka nebo cesty. language_filter vynechá graf v auto/hybrid; dotaz v auto směrovaný pouze do grafu se pak vrátí k sémantickému a textovému vyhledávání. Výslovný režim graph s language_filter je odmítnut. Vybraný plán vyhledávání zjistíte z pole routing_decision.modalities_used; warnings se objeví jen tehdy, když server vydal varování.
3. Slibné výsledky dále prozkoumejte pomocí `find_symbol` nebo `dependency_search`, místo abyste opakovali stejnou neurčitou otázku.
4. `get_file` použijte pouze v případě, že potřebujete konkrétní indexovanou cestu, která není na disku.
5. Upravte v běžných klientských nástrojích. Maguyva je pro zjišťování a ověřování – nikoli pro zápisy.

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

Proč tato smyčka funguje: [Jak to funguje](https://maguyva.ai/docs/how-it-works).

### Prázdné nebo neúplné výsledky

Když nástroje nevracejí nic užitečného, nejdřív opravte rozpoznání repozitáře a indexování, místo abyste donekonečna přeformulovávali dotaz.

1. Ověřte, že je úložiště připojeno a indexování dokončeno v [app.maguyva.ai](https://app.maguyva.ai).
2. Zkontrolujte identifikátor repozitáře: `"owner/repo"` používá výchozí větev; `"owner/repo:branch"` určuje konkrétní větev. Porovnávání nerozlišuje velká a malá písmena, ale nepoužívá přibližnou shodu — překlepy se automaticky neopravují.
3. Zavolejte `repository_context` s `action="info"` a zkontrolujte metadata rozpoznání repozitáře (například `metadata.resolution_reason`).
4. `repository` vynechte pouze tehdy, když klient MCP poskytuje výchozí repozitář pro daný požadavek nebo když má klíč přístup právě k jednomu repozitáři; jinak parametr předejte výslovně.
5. Zkuste to znovu s konkrétnějším dotazem, známým názvem symbolu prostřednictvím `find_symbol` nebo filtrem jazyka/cesty. Pokud je samotné připojení přerušeno, použijte [Řešení problémů](https://maguyva.ai/docs/troubleshooting).

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

Selhání nastavení: [Řešení problémů](https://maguyva.ai/docs/troubleshooting).

### Práce s více repozitáři

Zvolte správný indexovaný repozitář, když má klíč přístup k více repozitářům.

1. Jednou zavolejte `repository_context` s `action="list"`, abyste zjistili přesné identifikátory repozitářů, které může váš klíč prohledávat.
2. Pokud potřebujete jiný než výchozí repozitář (například `"owner/other-repo"` nebo `"owner/other-repo:develop"`), předejte `repository` výslovně nástrojům pro vyhledávání a práci se symboly.
3. Držte se pravidla jedna otázka = jeden repozitář, pokud záměrně neporovnáváte repozitáře v samostatných voláních.
4. Použijte `get_file`, když soubor žije v indexovaném úložišti, které není vaším aktuálním pracovním stromem.
5. Pamatujte: nástroje nikdy nezapisují zpět na platformu GitHub — kontext z více repozitářů slouží jen ke čtení a plánování.

Podrobnosti o formátu úložiště: [Referenční příručka MCP API](https://maguyva.ai/docs/mcp-api).

Nastavujete vše poprvé? Začněte s [Rychlý start](https://maguyva.ai/docs/quickstart) a pak použijte tyto postupy pro každodenní úkoly.