Przejdź do treści

Przepisy

Praktyczne przepisy na codzienną pracę Maguyva MCP. Każdy przepis zawiera nazwę narzędzi i kolejność, a nie pełne odniesienie do parametrów. W przypadku parametrów narzędzia użyj Dokumentacja API MCP. Do pierwszej konfiguracji użyj Quickstart.

Wybierz odpowiednie narzędzie#

Większość pytań zaczyna się od jednej rozmowy. Eskaluj tylko wtedy, gdy pierwsza odpowiedź jest zbyt ogólna lub zbyt wąska.

  • intelligent_search — rozpocznij tutaj w przypadku dowolnego pytania dotyczącego bazy kodu języka naturalnego; kieruje wyszukiwaniem semantycznym, symbolicznym, strukturalnym i zależnościowym.
  • find_symbol — znasz już nazwę funkcji, klasy lub zmiennej.
  • dependency_search — promień wybuchu: osoby dzwoniące, osoby na utrzymaniu lub uderzenie przed (i po) edycją.
  • 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).

Zainstaluj i zweryfikuj klienta#

Pobierz Maguyva do swojego klienta MCP i potwierdź połączenie z 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. Połącz swojego klienta za pomocą Przewodnik instalacji (wtyczka Claude Code lub natywna zdalna konfiguracja dla Cursor, VS Code, Windsurf, Zed i innych).
  4. Zapytaj swojego agenta "Jakie repozytoria mam podłączone?" — który przeprowadza uwierzytelnianie i repository_context od początku do końca.
  5. Zadaj jedno prawdziwe pytanie na temat tego repozytorium, którego odpowiedź możesz ocenić. Powinieneś zobaczyć ścieżki plików i numery linii z indeksowanego drzewa.

Utknąłeś na kluczach, mostach lub brakujących repozytoriach? Troubleshooting.

Zapytaj zanim zaczniesz edytować#

Mapuj symbole i promień wybuchu przed zmianą udostępnionego kodu. Narzędzia Maguyva nie modyfikują Twoich repozytoriów — informują o edycji, którą Twój klient stosuje lokalnie.

  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 zależnościami/analizą wpływu (lub przekaż zmienione ścieżki dla wpływu w stylu PR), aby zobaczyć promień wybuchu.
  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 sprawdź ponownie te same symbole za pomocą dependency_search (w tym weryfikację po edycji, jeśli Twój klient obsługuje flagi weryfikacji), aby obiekty wywołujące nadal działały zgodnie z oczekiwaniami.

Pełne parametry: Dokumentacja API MCP.

Wyszukaj, a następnie zmień#

Domyślna pętla agenta: eksploruj → symbole przypinania → edytuj z dowodami.

  1. Zacznij od intelligent_search i prostego zapytania („jak działa wygaśnięcie sesji”, „gdzie jest logika ponawiania prób”).
  2. Zawęź za pomocą filtrów języka lub ścieżki, gdy pierwsze okno jest zaszumione.
  3. Promuj obiecujące trafienia w 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.

Dlaczego ta pętla działa: Jak to działa.

Puste lub cienkie wyniki#

Gdy narzędzia nie zwrócą nic przydatnego, napraw rozdzielczość i indeksowanie przed ponownym przepisaniem zapytania na zawsze.

  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 za pomocą action="info" i sprawdź metadane rozdzielczości (na przykład metadata.resolution_reason).
  4. Pomiń repository tylko wtedy, gdy Twój klient MCP dostarcza żądanie domyślne lub klucz może uzyskać dostęp dokładnie do jednego repozytorium; w przeciwnym razie przekaż to wyraźnie.
  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 zostanie zerwane, użyj Troubleshooting.

Błędy konfiguracji: Troubleshooting.

Pracuj w wielu repozytoriach#

Wybierz właściwe indeksowane repozytorium, gdy klucz może widzieć więcej niż jeden.

  1. Zadzwoń raz do repository_context za pomocą action="list", aby dowiedzieć się, jakie dokładnie ślimaki może wyszukiwać Twój klucz.
  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 odpisują do GitHub — kontekst wielu repozytoriów służy wyłącznie do czytania i planowania.

Szczegóły formatu repozytorium: Dokumentacja API MCP.

Nie znasz jeszcze Maguyva? Najpierw przejdź Quickstart, a następnie wróć tutaj na pętle drugiego dnia.

Kolejne kroki#