Přeskočit na obsah

Cookbook

Praktické recepty pro každodenní práci Maguyva MCP. Každý recept pojmenovává nástroje a sekvenci – nejde o úplný odkaz na parametry. Pro parametry nástroje použijte Referenční příručka MCP API. Pro první nastavení použijte 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 — začněte zde pro jakoukoli otázku kódové základny v přirozeném jazyce; směruje přes sémantické, symbolové, strukturální a vyhledávání závislostí.
  • 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).

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 (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, Windsurf, Zed a další).
  4. Zeptejte se svého agenta "Jaká úložiště mám připojená?" — to provádí ověřování a repository_context od začátku do konce.
  5. Zeptejte se na jednu skutečnou otázku o tomto repo, jehož odpověď můžete ohodnotit. Měli byste vidět cesty k souborům a čísla řádků z indexovaného stromu.

Potíže s klíči nebo propojením nebo chybějící repozitáře? 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ě – informují o úpravách, které váš klient aplikuje 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ávislostí/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 (včetně ověření po úpravě, když váš klient podporuje příznaky ověření), aby se volající stále vyřešili podle očekávání.

Kompletní parametry: Referenční příručka 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 opakování“).
  2. Zúžení pomocí jazykových filtrů nebo filtrů cest, když je první okno hlučné.
  3. Propagujte slibné hity na find_symbol nebo dependency_search místo opětovného pokládání stejné vágní otázky.
  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.

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

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

Když nástroje nevrací nic užitečného, ​​opravte rozlišení a indexování, než dotaz navždy přepíšete.

  1. Ověřte, že je úložiště připojeno a indexování dokončeno v app.maguyva.ai.
  2. Zkontrolujte řetězec úložiště: "owner/repo" používá výchozí větev; "owner/repo:branch" připojí větev. Párování nerozlišuje malá a velká písmena, není nejasné – překlepy se automaticky neopravují.
  3. Zavolejte repository_context pomocí action="info" a zkontrolujte metadata rozlišení (například metadata.resolution_reason).
  4. Vynechejte repository pouze v případě, že váš klient MCP poskytne výchozí požadavek nebo když klíč může přistupovat přesně k jednomu úložišti; jinak to 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 Troubleshooting.

Selhání nastavení: Troubleshooting.

Práce napříč více úložišti#

Zacilte na správné indexované úložiště, když klíč vidí více než jeden.

  1. Zavolejte jednou na repository_context s action="list" a zjistěte, jaké přesné identifikátory repozitářů dokáže váš klíč vyhledat.
  2. Pokud potřebujete jiný než výchozí repo (například "owner/other-repo" nebo "owner/other-repo:develop"), předejte repository explicitně pomocí nástrojů pro vyhledávání a symboly.
  3. Nechte si jednu otázku = jedno úložiště, pokud záměrně neporovnáváte mezi repozitáři 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 do GitHub – kontext více repo je pouze pro čtení a plánování.

Podrobnosti o formátu úložiště: Referenční příručka MCP API.

Jste v Maguyva noví? Nejprve projděte Quickstart, pak se sem vraťte na navazující pracovní postupy.

Další kroky#