Przepisy

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”. Przy pierwszej konfiguracji skorzystaj z sekcji „Szybki start”.

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

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

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

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

Utknąłeś na kluczach, mostach lub brakujących repozytoriach? Rozwiązywanie problemów.

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.

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

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.

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

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

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

Błędy konfiguracji: Rozwiązywanie problemów.

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.

• Szybki start — klucz, indeksowanie, połączenie, pierwsza oceniona odpowiedź
• Przewodnik instalacji — konfiguracja MCP dla poszczególnych klientów
• Dokumentacja API MCP — każde narzędzie, parametr po parametrze
• Rozwiązywanie problemów — Awarie klucza API, mostu i repozytorium