Praktické návody

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. Při prvním nastavení použijte Rychlý start.

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

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

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

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

Potíže s klíči nebo propojením nebo chybějící repozitáře? Řešení problémů.

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.

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

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.

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

Proč tato smyčka funguje: Jak to funguje.

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

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

Selhání nastavení: Řešení problémů.

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.

• Rychlý start — klíč, index, připojení, první hodnotitelná odpověď
• Průvodce instalací — konfigurace MCP pro každého klienta
• Referenční příručka MCP API — každý nástroj, parametr po parametru
• Odstraňování problémů — Problémy s API klíčem, propojením a rozpoznáním repozitáře