# Rozwiązywanie problemów

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

Napraw najczęstsze problemy z konfiguracją Maguyva: problemy z kluczem API, problemy z mostkiem @maguyva/mcp, wyszukiwanie repozytoriów oraz błędy połączenia.

### Problemy z kluczem API

- Sprawdź, czy Twój klucz zaczyna się od prefiksu mgv_.
- Sprawdź, czy zastąpiłeś placeholder mgv_xxxx z przykładów konfiguracji swoim prawdziwym kluczem z app.maguyva.ai.
- Jeśli Twoja konfiguracja odczytuje klucz z MAGUYVA_API_KEY, upewnij się, że zmienna jest ustawiona w środowisku, z którego faktycznie uruchamia się Twój klient. Eksporty powłoki dodane do ~/.zshrc lub ~/.bashrc działają dopiero po ponownym załadowaniu powłoki, a aplikacje GUI mogą ich w ogóle nie dziedziczyć. W razie wątpliwości wpisz klucz bezpośrednio do konfiguracji: w nagłówku Authorization natywnej konfiguracji zdalnej (Bearer, a po nim Twój klucz) lub w bloku env konfiguracji z mostkiem @maguyva/mcp.
- Upewnij się, że klucz nie wygasł ani nie został unieważniony.

### Problemy z mostkiem @maguyva/mcp

- Sprawdź, czy npx jest dostępny w Twoim PATH -- mostek wymaga działającej instalacji Node.js. Uruchom npx -y @maguyva/mcp --help w terminalu, aby potwierdzić, że się uruchamia.
- Sprawdź składnię konfiguracji MCP swojego klienta -- nieprawidłowo sformatowany plik JSON w niektórych klientach zawodzi bez żadnego komunikatu.
- Wiele klientów w ogóle nie potrzebuje mostka. Claude Code korzysta z pluginu Maguyva (/plugin install maguyva@maguyva), a Cursor, VS Code, Devin Desktop i Zed łączą się ze zdalnym serwerem natywnie za pomocą nagłówka Bearer (Zed przez context_servers). Mostek jest dla klientów, które nie mogą wysłać tego nagłówka ze swojej konfiguracji, jak Claude Desktop, którego claude_desktop_config.json uruchamia tylko serwery lokalne. Niestandardowe konektory Claude Desktop mogą wysyłać nagłówek żądania authorization, ale nagłówki żądań są w wersji beta dla ograniczonej liczby organizacji.

### Nie znaleziono repozytorium

- Sprawdź, czy repozytorium jest podłączone i zaindeksowane w app.maguyva.ai.
- Sprawdź format: "owner/repo" celuje w domyślną gałąź, "owner/repo:branch" celuje w konkretną gałąź (np. "owner/repository:develop").
- Upewnij się, że Twoje konto ma dostęp do repozytorium.
- Użyj repository_context(action="info", repository="..."), aby sprawdzić rozpoznawanie repozytorium; pomijaj parametr repository tylko wtedy, gdy Twój klient MCP dostarcza domyślne ustawienie dla żądania lub gdy klucz ma dostęp dokładnie do jednego repozytorium.

### Problemy z połączeniem MCP

- Przetestuj łączność z https://maguyva.tools/mcp ze swojej maszyny -- firmowe proxy i firewalle to zwykle winowajcy.
- Sprawdź, czy Twój token API jest ważny i nie wygasł.
- Sprawdź jeszcze raz konfigurację klienta względem przewodnika instalacji dla Twojego klienta -- lokalizacja i kształt pliku konfiguracyjnego różnią się w zależności od klienta.

### Zweryfikuj poprawkę

Po każdej zmianie zapytaj swojego agenta „Jakie repozytoria mam połączone?” -- to weryfikuje połączenie od początku do końca. Następnie zadaj prawdziwe pytanie o swoje repozytorium; powinieneś zobaczyć odpowiedzi ze ścieżkami plików i numerami linii z Twojego połączonego repozytorium.