# Przepisy

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

Praktyczne przepisy na codzienną pracę z Maguyva MCP. Każdy przepis podaje narzędzia i kolejność ich użycia, a nie pełną dokumentację parametrów. Parametry narzędzi opisuje sekcja „[Dokumentacja API MCP](https://maguyva.ai/docs/mcp-api)”. Przy pierwszej konfiguracji skorzystaj z sekcji „[Szybki start](https://maguyva.ai/docs/quickstart)”.

### Wybierz odpowiednie narzędzie

Większość pytań wymaga na początek jednego wywołania. Sięgaj po kolejne narzędzia dopiero wtedy, gdy pierwsza odpowiedź jest zbyt ogólna lub zawiera za mało informacji.

- `intelligent_search` — zacznij tutaj, gdy pytasz o kod w języku naturalnym. Domyślnie auto/balanced kieruje zapytania z wysoką pewnością rozpoznane jako pytania o definicje do wyszukiwania strukturalnego, pytania o odwołania lub wpływ do grafu, a pytania o dokładne dopasowanie do wyszukiwania tekstowego. Pozostałe pytania korzystają ze znaczenia semantycznego i zindeksowanego tekstu. Użyj mode=hybrid albo auto z quality=thorough, aby zażądać wszystkich czterech modalności wyszukiwania; jawnie wybrany tryb ma pierwszeństwo przed quality.
- `find_symbol` — znasz już nazwę funkcji, klasy lub zmiennej.
- `dependency_search` — zasięg wpływu: kod wywołujący, kod zależny od symbolu lub skutki przed edycją i po niej.
- `get_task_context` — nieznany obszar; jeden ograniczony pakiet plików, symboli i zależności dla opisu zadania.
- `repository_context` — wyświetla listę dostępnych repozytoriów lub sprawdza, jak nazwa repozytorium jest rozpoznawana.
- `ask_maguyva` z `operation="guidance"` — lokalna pomoc dotycząca wyboru narzędzia i użycia Maguyva (bez mutacji repo).

Bloki JSON zawierają dane wejściowe MCP tools/call. Zastąp owner/repo, nazwę gałęzi i nazwy symboli wartościami ze swojego repozytorium.

### Zainstaluj i zweryfikuj klienta

Podłącz Maguyva do swojego klienta MCP i potwierdź połączenie, pobierając rzeczywistą listę repozytoriów.

1. Utwórz klucz API w [app.maguyva.ai](https://app.maguyva.ai) (klucze zaczynają się od `mgv_`).
2. Połącz i zindeksuj co najmniej jedno repozytorium GitHub, które już znasz.
3. Podłącz klienta zgodnie z instrukcjami w sekcji „[Przewodnik instalacji](https://maguyva.ai/docs/installation)” (wtyczka Claude Code lub natywna zdalna konfiguracja dla Cursor, VS Code, Devin Desktop, Zed i innych).
4. Zapytaj swojego agenta: "Jakie repozytoria mam podłączone?" — w ten sposób sprawdzisz uwierzytelnianie i `repository_context` od początku do końca.
5. Zadaj jedno rzeczywiste pytanie o to repozytorium, na które potrafisz ocenić odpowiedź. Powinieneś zobaczyć ścieżki plików i numery linii z zaindeksowanego drzewa.

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

Utknąłeś na kluczach, mostach lub brakujących repozytoriach? [Rozwiązywanie problemów](https://maguyva.ai/docs/troubleshooting).

### Zapytaj zanim zaczniesz edytować

Zmapuj symbole i zasięg wpływu zmian przed edycją współdzielonego kodu. Narzędzia Maguyva nie modyfikują Twoich repozytoriów — dostarczają informacji potrzebnych do edycji wykonywanej lokalnie przez klienta.

1. Jeśli znasz nazwę symbolu, wywołaj `find_symbol`, aby zapoznać się z definicjami i zastosowaniami.
2. Jeśli masz tylko opis zadania („dodaj SSO”, „napraw webhook rozliczeniowy”), zacznij od `get_task_context` lub `intelligent_search`.
3. Przed edycją współdzielonego symbolu wywołaj `dependency_search` z analizą kodu, który od niego zależy, lub wpływu zmian (albo przekaż zmienione ścieżki do analizy wpływu w stylu PR), aby poznać zasięg wpływu.
4. Otwórz cytowane pliki (odczyt lokalny dla plików na dysku; `get_file` dla ścieżek zdalnych/cross-repo) i potwierdź plan względem prawdziwego kodu.
5. Po edycji ponownie sprawdź te same symbole za pomocą `dependency_search`, ustawiając verify_after_edit=true i targets lub changed_paths. Odczytywany jest zindeksowany graf, a nie lokalne zmiany bez commita: sprawdź indexed_commit_sha i aktualność indeksu, zanim uznasz wynik za dowód dotyczący nowej rewizji, i uruchom lokalne testy.

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

Pełne parametry: [Dokumentacja API MCP](https://maguyva.ai/docs/mcp-api).

### Wyszukaj, a następnie zmień

Domyślna pętla agenta: zbadaj kod → wskaż konkretne symbole → edytuj na podstawie dowodów.

1. Zacznij od `intelligent_search` i prostego zapytania („jak działa wygaśnięcie sesji”, „gdzie jest logika ponawiania prób”).
2. Zawęź wyniki filtrami języka lub ścieżki, jeśli pierwsze okno wyników zawiera dużo szumu. language_filter wyklucza graf z auto/hybrid; zapytanie auto skierowane wyłącznie do grafu przechodzi na wyszukiwanie semantyczne i tekstowe. Jawny tryb grafowy z language_filter jest odrzucany. Sprawdź routing_decision.modalities_used, aby poznać wybrany plan wyszukiwania; warnings pojawia się tylko wtedy, gdy serwer zgłosił ostrzeżenie.
3. Zbadaj obiecujące trafienia za pomocą `find_symbol` lub `dependency_search`, zamiast ponownie zadawać to samo niejasne pytanie.
4. Używaj `get_file` tylko wtedy, gdy potrzebujesz określonej indeksowanej ścieżki, której nie ma na dysku.
5. Edytuj w zwykłych narzędziach klienta. Maguyva służy do wykrywania i weryfikacji — nie zapisuje.

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

Dlaczego ta pętla działa: [Jak to działa](https://maguyva.ai/docs/how-it-works).

### Puste lub skąpe wyniki

Gdy narzędzia nie zwracają nic przydatnego, sprawdź rozpoznawanie repozytorium i indeksowanie, zamiast bez końca przepisywać zapytanie.

1. Potwierdź, że repozytorium jest podłączone i zakończyło indeksowanie w [app.maguyva.ai](https://app.maguyva.ai).
2. Sprawdź ciąg repozytorium: `"owner/repo"` używa gałęzi domyślnej; `"owner/repo:branch"` przypina gałąź. Dopasowywanie nie uwzględnia wielkości liter i nie jest rozmyte — literówki nie są korygowane automatycznie.
3. Wywołaj `repository_context` z `action="info"` i sprawdź metadane rozpoznawania repozytorium (na przykład `metadata.resolution_reason`).
4. Pomiń `repository` tylko wtedy, gdy Twój klient MCP dostarcza domyślne ustawienie dla żądania lub klucz ma dostęp dokładnie do jednego repozytorium; w przeciwnym razie przekaż ten parametr jawnie.
5. Spróbuj ponownie, używając bardziej szczegółowego zapytania, znanej nazwy symbolu za pomocą `find_symbol` lub filtra języka/ścieżki. Jeśli samo połączenie nie działa, skorzystaj z sekcji „[Rozwiązywanie problemów](https://maguyva.ai/docs/troubleshooting)”.

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

Błędy konfiguracji: [Rozwiązywanie problemów](https://maguyva.ai/docs/troubleshooting).

### Pracuj w wielu repozytoriach

Wybierz właściwe zaindeksowane repozytorium, gdy klucz ma dostęp do więcej niż jednego.

1. Wywołaj `repository_context` raz z `action="list"`, aby poznać dokładne identyfikatory repozytoriów, które możesz przeszukiwać za pomocą swojego klucza.
2. Przekaż `repository` jawnie w narzędziach wyszukiwania i symboli, gdy potrzebujesz repozytorium innego niż domyślne (na przykład `"owner/other-repo"` lub `"owner/other-repo:develop"`).
3. Zachowaj jedno pytanie = jedno repozytorium, chyba że celowo porównujesz repozytoria w oddzielnych wywołaniach.
4. Użyj `get_file`, gdy plik znajduje się w indeksowanym repozytorium, które nie jest bieżącym drzewem roboczym.
5. Pamiętaj: narzędzia nigdy nie zapisują zmian w GitHub — kontekst wielu repozytoriów służy wyłącznie do odczytu i planowania.

Szczegóły formatu repozytorium: [Dokumentacja API MCP](https://maguyva.ai/docs/mcp-api).

Pierwsza konfiguracja? Zacznij od [Szybki start](https://maguyva.ai/docs/quickstart), a następnie korzystaj z tych przepisów w codziennych zadaniach.