# Řešení problémů

Canonical source: https://maguyva.ai/cs/docs/troubleshooting

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

Opravte běžná selhání při nastavování produktu Maguyva: problémy s API klíčem, potíže s mostem @maguyva/mcp, vyhledávání repozitářů a chyby připojení.

### Problémy s API klíčem

- Ověřte, že váš klíč začíná prefixem mgv_.
- Zkontrolujte, že jste zástupný text mgv_xxxx z ukázek konfigurace nahradili svým skutečným klíčem z app.maguyva.ai.
- Pokud vaše konfigurace čte klíč z MAGUYVA_API_KEY, ověřte, že je proměnná nastavená v prostředí, ze kterého se klient skutečně spouští. Exporty shellu přidané do ~/.zshrc nebo ~/.bashrc se projeví až po znovunačtení shellu a GUI aplikace je nemusí zdědit vůbec. V případě pochybností zapište klíč přímo do konfigurace: do hlavičky Authorization v nativní vzdálené konfiguraci (Bearer a za ním váš klíč), nebo do bloku env v konfiguraci s mostem @maguyva/mcp.
- Ujistěte se, že klíči nevypršela platnost a nebyl zneplatněn.

### Problémy s mostem @maguyva/mcp

- Ověřte, že je npx dostupný ve vaší PATH -- most potřebuje funkční instalaci Node.js. Spuštěním npx -y @maguyva/mcp --help v terminálu ověřte, že se dá spustit.
- Zkontrolujte syntaxi MCP konfigurace svého klienta -- poškozený JSON soubor u některých klientů selže potichu.
- Mnoho klientů most vůbec nepotřebuje. Claude Code používá plugin Maguyva (/plugin install maguyva@maguyva) a Cursor, VS Code, Devin Desktop a Zed se ke vzdálenému serveru připojují nativně pomocí hlavičky Bearer (Zed přes context_servers). Most je určen pro klienty, kteří tuto hlavičku nedokážou poslat ze své konfigurace, například Claude Desktop, jehož claude_desktop_config.json spouští jen lokální servery. Vlastní konektory Claude Desktop umějí poslat hlavičku požadavku authorization, ale hlavičky požadavků jsou v betě jen pro omezený počet organizací.

### Repozitář nenalezen

- Ověřte, zda je úložiště připojeno a indexováno v app.maguyva.ai.
- Zkontrolujte formát: „owner/repo“ cílí na výchozí větev, „owner/repo:branch“ cílí na konkrétní větev (např. „owner/repository:develop“).
- Ujistěte se, že váš účet má přístup k úložišti.
- Pomocí repository_context(action="info", repository="...") zjistěte, jak se repozitář vyhodnotí; parametr repository vynechte pouze tehdy, když klient MCP poskytuje výchozí hodnotu pro daný požadavek nebo když má klíč přístup právě k jednomu repozitáři.

### Problémy s připojením MCP

- Otestujte konektivitu k https://maguyva.tools/mcp ze svého počítače -- obvyklými viníky bývají firemní proxy a firewally.
- Zkontrolujte, že je váš API token platný a nevypršel.
- Znovu zkontrolujte konfiguraci klienta oproti Instalační příručce pro vašeho klienta -- umístění a tvar konfiguračního souboru se u jednotlivých klientů liší.

### Ověřte opravu

Po jakékoli změně se svého agenta zeptejte „Jaké repozitáře mám připojené?“ -- tím ověříte připojení od začátku do konce. Pak položte skutečnou otázku o svém repozitáři; měli byste vidět odpovědi s cestami k souborům a čísly řádků z vašeho připojeného repozitáře.