Przejdź do treści

Dokumentacja API MCP

Poznaj 11 narzędzi MCP Maguyva, ich parametry i zastosowania. Dostępne argumenty znajdziesz w odpowiedzi tools/list podłączonego klienta.

Przegląd API

#

Narzędzia są podzielone na następującą liczbę kategorii: 4.

  • Podstawowe narzędzia wyszukiwania - Zaawansowane możliwości wyszukiwania w Twojej bazie kodu
  • Narzędzia strukturalne i grafowe - Zapytania AST, wyszukiwanie symboli i analiza zależności
  • Narzędzia analizy kodu - Dogłębna analiza kodu i mapowanie relacji
  • Narzędzia systemowe i pomocnicze - Kontekst repozytorium, pomoc dotycząca narzędzi i opinie

Dla narzędzi przyjmujących repozytorium zastosuj następujący zapis (format identyfikatora repozytorium): "owner/repo:branch". Jeśli nie podasz gałęzi, domyślną jest main.

Pomiń repository, gdy Twój klient MCP dostarcza domyślne ustawienie dla żądania lub gdy klucz ma dostęp dokładnie do jednego repozytorium; w przeciwnym razie przekaż je jawnie. Użyj repository_context(action="info", repository="owner/repo"), aby sprawdzić, jak rozwiązuje się repozytorium.

Format parametru repozytorium

#

Przy wskazywaniu repozytorium używaj tych formatów:

  • Z gałęzią: "owner/repo:branch" - np., "owner/repository:develop"
  • Domyślna gałąź: "owner/repo" - używa gałęzi main, gdy nie podano gałęzi "owner/repository"
  • Domyślne repozytorium żądania lub jedyne dostępne: Pomiń repository, gdy klient MCP przekazuje domyślne repozytorium dla żądania lub klucz ma dostęp dokładnie do jednego repozytorium; w przeciwnym razie podaj je jawnie.

Przykładowe polecenia:

Zapytaj o konkretne repo:       "Wyszukaj warstwę pośrednią uwierzytelniania w owner/my-repo"
Wyświetl dostępne repozytoria:  "Do których repozytoriów ma dostęp ten klucz Maguyva?"
Jednorazowe nadpisanie:         "Wyszukaj wzorce uwierzytelniania w owner/other-repo:develop"

Filtrowanie języków

#

Używaj language_filter w obsługiwanych trybach wyszukiwania. Dla text_pattern_search wybierz search_scope="content"; dla get_task_context użyj scope="semantic" bez punktów początkowych ani powiązanego kontekstu.

  • language_filter="python" - Filtruj tylko pliki Python
  • language_filter="typescript" - Filtruj tylko pliki TypeScript
  • Rozróżnianie wielkości liter: Używaj nazw języków pisanych małymi literami
  • Domyślnie: Pusty ciąg znaków (brak filtrowania) – zwraca wyniki ze wszystkich języków
  • Obsługiwany zakres: Filtry językowe działają w pełnym zakresie ponad 285 obsługiwanych języków i technologii tekstowych. Pełną listę znajdziesz na stronie „kompatybilność”. 
„Znajdź middleware uwierzytelniania tylko w plikach Python”
„Szukaj połączeń z bazą danych w TypeScript”

Dokumentacja API wygenerowana ze źródła dnia 21 października 2026.

Podstawowe narzędzia wyszukiwania

#

intelligent_search Stabilne

Zacznij tutaj z dowolnym pytaniem o kod. 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. language_filter wyklucza graf z auto/hybrid i odrzuca jawne mode=graph. Wybierz to zamiast Grep/Glob, jeśli nie znasz jeszcze ścieżki.

Parametry:

query Wymagane
Typ
str minLength=1
Opis
Zapytanie wyszukiwania
repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
mode Opcjonalne
Typ
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Domyślnie
auto
Opis
Tryb wyszukiwania
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
10
Opis
Maksymalna liczba wyników w tym rankingowanym oknie top-K
language_filter Opcjonalne
Typ
str
Opis
Filtr języka
path_filter Opcjonalne
Typ
str
Opis
Filtruje kandydatów wyszukiwania według prefiksu ścieżki pliku. Sąsiednie węzły grafu i dołączony kontekst społeczności mogą zawierać pliki spoza tego prefiksu.
boost_by_importance Opcjonalne
Typ
bool
Domyślnie
false
Opis
Opcjonalnie: ponowne rankingowanie według centralności z użyciem metryk grafowych na poziomie symbolu (is_articulation_point, bridge_count, k_core, centrality itd.). Domyślnie wyłączone dla bezpiecznego dla agentów rankingu (globalne huby mogą zagłuszyć trafienia implementacyjne); włącz dla przeglądów architektury. Dotyczy wszystkich 4 modalności, gdy każdy wynik zawiera powiązanie z symbolem.
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (jednorazowe)
quality Opcjonalne
Typ
Literal[quick, balanced, thorough]
Domyślnie
balanced
Opis
Preset jakości wyszukiwania
include_content Opcjonalne
Typ
bool
Domyślnie
true
Opis
Dołącz treść w wynikach
explain_routing Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz wyjaśnienie decyzji routingu
importance_weight Opcjonalne
Typ
float minimum=0, maximum=1
Domyślnie
0.3
Opis
Waga wzmacniania ważności (0=brak, 1=pełne)
orphans Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz symbole osierocone (bez przychodzących referencji)
include_community_context Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz powiązane symbole z tej samej społeczności kodu dla szerszego kontekstu
community_depth Opcjonalne
Typ
int minimum=1, maximum=3
Domyślnie
1
Opis
Głębokość rozszerzenia kontekstu społeczności
graph_view Opcjonalne
Typ
Literal[dependency, type, data_flow, control_flow]
Domyślnie
dependency
Opis
Widok grafu dla metryk
seed_symbol_ids Opcjonalne
Typ
list[str] maxItems=20
Opis
Punkty początkowe zadania Tier-1: identyfikatory symboli kluczowych dla bieżącego zadania. Po ustawieniu parametru połączone wyniki są ponownie rankingowane według bliskości, z wagą malejącą wraz z głębokością zgodnie z Approach A (dokładne dopasowanie symbolu początkowego + przejścia po krawędziach grafu). To dodatkowy sygnał — pomiń parametr, aby użyć globalnego rankingu.
seed_file_paths Opcjonalne
Typ
list[str] maxItems=10
Opis
Punkty początkowe zadania Tier-1: zaindeksowane ścieżki plików, które agent ma otwarte lub właśnie edytował. Po ustawieniu parametru połączone wyniki są ponownie rankingowane według bliskości ścieżek, z wagą malejącą z głębokością zgodnie z 1/(1+d) (ten sam plik → ten sam katalog → pobliskie pakiety). To dodatkowy sygnał — pomiń parametr, aby użyć globalnego rankingu.

Najlepsze do:

  • Eksploracja całego indeksu lub start od zera, gdy nie wiadomo, które narzędzie wybrać
  • Wielomodalne, połączone rankingowanie w wynikach semantycznych, tekstowych, strukturalnych i grafowych

Niezalecane do:

  • Znana nazwa symbolu — użyj bezpośrednio find_symbol
  • Znana ścieżka na dysku — najpierw użyj lokalnego Read/Grep

semantic_search Stabilne

Znajduj kod według znaczenia, nie dokładnego tekstu. Używaj do zapytań pojęciowych, takich jak „logika ponawiania” czy „wdrażanie użytkownika”, gdy nie znasz słowa kluczowego ani nazwy symbolu. Zwraca trafne fragmenty z ograniczoną różnorodnością plików; zmianę kolejności według ważności w grafie włącza boost_by_importance. Przy wyszukiwaniu pojęciowym wybierz to narzędzie zamiast Grep.

Parametry:

query Wymagane
Typ
str minLength=1
Opis
Zapytanie wyszukiwania (koncepcyjne, oparte na znaczeniu)
repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
5
Opis
Maksymalna liczba wyników w tym rankingowanym oknie top-K
similarity_threshold Opcjonalne
Typ
float minimum=0, maximum=1
Domyślnie
0.6
Opis
Minimalny wynik podobieństwa
language_filter Opcjonalne
Typ
str
Opis
Filtr języka (python, typescript itp.)
path_filter Opcjonalne
Typ
str
Opis
Filtr według prefiksu ścieżki pliku
boost_by_importance Opcjonalne
Typ
bool
Domyślnie
false
Opis
Opcjonalnie: zmiana kolejności według znormalizowanej ważności każdego symbolu w grafie (domyślnie wyłączona; limit 1,5-krotności podobieństwa).
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (domyślnie: z parametru repository lub main)
include_content Opcjonalne
Typ
bool
Domyślnie
true
Opis
Dołącz zawartość fragmentu w wynikach
graph_view Opcjonalne
Typ
Literal[dependency, type, data_flow, control_flow]
Domyślnie
dependency
Opis
Widok grafu dla metryk

Najlepsze do:

  • Zapytania koncepcyjne („jak działa uwierzytelnianie?”, „strategia buforowania”)
  • Wyszukiwanie podobieństw między pakietami

Niezalecane do:

  • Znana nazwa symbolu — użyj zamiast tego find_symbol
  • Dokładne ciągi znaków lub komunikaty błędów — użyj text_pattern_search

text_pattern_search Stabilne

Przeszukuj indeksowaną zawartość. exact i regex stosują grep do całego korpusu plików/blob; fuzzy content przeszukuje ograniczony korpus fragmentów semantycznych. Zakresy file i symbol obsługują tylko trigramy — domyślne mode=exact jest zmieniane na fuzzy. Ustawienia języka, wielkości liter i własnego progu wymagają zakresu content. Filtrowanie ścieżek korzysta z ograniczonego okna kandydatów i zgłasza niepełne pokrycie. Dla niewielkiego katalogu na dysku użyj lokalnego Grep.

Parametry:

query Wymagane
Typ
str minLength=1
Opis
Wzorzec tekstowy do wyszukania
repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
mode Opcjonalne
Typ
Literal[fuzzy, exact, regex]
Domyślnie
exact
Opis
Tryb wyszukiwania. Regex wykonuje zaawansowaną/składnię POSIX PostgreSQL; użyj \y dla granic wyrazów (\b oznacza backspace). Wzorce przechodzą też przez walidator bezpieczeństwa JavaScript, więc konstrukcje właściwe tylko dla PostgreSQL, takie jak wbudowane flagi (?i), są odrzucane; zamiast tego użyj case_sensitive.
search_scope Opcjonalne
Typ
Literal[content, symbols, files]
Domyślnie
content
Opis
Co przeszukiwać
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
5
Opis
Maksymalna liczba wyników na stronie bez cursor. Kontynuacja korzysta z rozmiaru strony zapisanego w cursor; pomiń cursor, aby zacząć z innym limit.
offset Opcjonalne
Typ
int minimum=0
Opis
Przestarzały offset dla zgodności wstecznej. Preferuj cursor z pagination.next_cursor.
cursor Opcjonalne
Typ
str
Opis
Nieprzezroczysty cursor z pagination.next_cursor. Przekaż go bez zmian i pozostaw query oraz filtry niezmienione. Jego pozycja i rozmiar strony mają pierwszeństwo przed offset i limit.
language_filter Opcjonalne
Typ
str
Opis
Filtr języka
path_filter Opcjonalne
Typ
str
Opis
Filtr według prefiksu ścieżki pliku
case_sensitive Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dopasowanie uwzględniające wielkość liter
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (jednorazowe)
fuzzy_algorithm Opcjonalne
Typ
Literal[hybrid, trigram, levenshtein]
Domyślnie
hybrid
Opis
Algorytm dopasowania rozmytego
threshold Opcjonalne
Typ
float minimum=0, maximum=1
Domyślnie
0.05
Opis
Minimalny próg podobieństwa dla fuzzy
semantic_fallback Opcjonalne
Typ
bool
Domyślnie
false
Opis
Próbuje wyszukiwania semantycznego po pustej pierwszej stronie leksykalnej; metadata.fallback_status rozróżnia stany zapasowe used, empty i unavailable.

Najlepsze do:

  • Dokładne ciągi znaków, komunikaty błędów i wyrażenia regularne
  • Dopasowywanie trigramowe fuzzy dla tekstu zbliżonego

Niezalecane do:

  • Znana ścieżka na dysku — preferuj lokalny Grep
  • Zapytania koncepcyjne — użyj semantic_search

Narzędzia strukturalne i grafowe

#

structural_search Stabilne

Preferuj preset=functions|classes|methods|imports|variables lub dowolny pattern=. Szukaj kodu według kształtu AST, nie tekstu. Filtry pośrednie: name_pattern, node_type, decorator, parent_child. Filtry ścieżek, ltree i wywołań są zaawansowane — ustaw advanced=true, gdy używasz ich świadomie. Bez tego również zostaną zastosowane, lecz z ostrzeżeniem w metadanych. Podaj co najmniej jeden selektor strukturalny.

Parametry:

repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
preset Opcjonalne
Typ
Literal[functions, classes, methods, imports, variables]
Opis
Preferowany selektor strukturalny. Rozwija się do wielojęzycznych typów węzłów AST — functions (definicje funkcji/funkcji strzałkowych/metod w różnych językach); classes (deklaracje klas/struktur/interfejsów, ciała typów i implementacje); methods (definicje metod (i function_definition dla języków bez węzła metody)); imports (instrukcje import/use/include); variables (deklaracje zmiennych variable/let/const/static). Preferuj zamiast dowolnego pattern/node_type do zapytań w stylu przeglądania.
pattern Opcjonalne
Typ
str
Opis
Dowolny pattern uzupełnia brakujące selektory (automatyczne wykrywanie: 'def foo(' → node_type + name_pattern). Można łączyć z preset; jawne selektory mają pierwszeństwo. Dla zapytań przeglądowych zalecane jest preset=.
name_pattern Opcjonalne
Typ
str maxLength=256
Opis
Wzorzec nazwy symbolu (symbol wieloznaczny powłoki, ograniczone wyrażenie regularne POSIX lub tekst rozmyty; maks. 256 znaków)
node_type Opcjonalne
Typ
str
Opis
Typ węzła AST (function_definition, class_definition itd.) — dla typowych kształtów preferuj preset=
decorator Opcjonalne
Typ
str
Opis
Filtr nazwy dekoratora
base_class Opcjonalne
Typ
str
Opis
Filtr klasy bazowej
language_filter Opcjonalne
Typ
str
Opis
Filtr języka (python, typescript itp.)
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
20
Opis
Maksymalna liczba wyników na stronie bez cursor. Kontynuacja korzysta z rozmiaru strony zapisanego w cursor; pomiń cursor, aby zacząć z innym limit.
offset Opcjonalne
Typ
int minimum=0
Opis
Przestarzały offset dla zgodności wstecznej. Preferuj cursor z pagination.next_cursor.
cursor Opcjonalne
Typ
str
Opis
Nieprzezroczysty cursor z pagination.next_cursor. Przekaż go bez zmian i pozostaw query oraz filtry niezmienione. Jego pozycja i rozmiar strony mają pierwszeństwo przed offset i limit.
path_filter Opcjonalne
Typ
str
Opis
Filtr według prefiksu ścieżki pliku
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (jednorazowe)
query_type Opcjonalne
Typ
Literal[node_type, name_pattern, parent_child]
Opis
Jawny typ zapytania
parent_type Opcjonalne
Typ
str
Opis
Filtr typu węzła nadrzędnego AST
relationship Opcjonalne
Typ
Literal[parent, ancestor]
Domyślnie
parent
Opis
Dla zapytań parent_child: tylko bezpośredni rodzic, lub dowolny przodek (użyj ancestor dla metod klas zagnieżdżonych w ciele klasy)
has_modifier Opcjonalne
Typ
str
Opis
Filtruj po modyfikatorze (export, async, static itp.)
advanced Opcjonalne
Typ
bool
Domyślnie
false
Opis
Ustaw true, gdy świadomie używasz zaawansowanych filtrów ścieżek, ltree lub wywołań (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Przy false podane filtry zaawansowane są stosowane z ostrzeżeniem w metadanych. Dla zwykłych zapytań strukturalnych preferuj preset=.
callee_text Opcjonalne
Typ
str
Opis
Zaawansowane — preferuj preset=functions|classes|methods|imports|variables. Filtr tekstu callee wyrażenia wywołania. Ustaw advanced=true, gdy celowo używasz filtrów path/ltree/call.
callee_name Opcjonalne
Typ
str
Opis
Zaawansowane — preferuj preset=functions|classes|methods|imports|variables. Filtr nazwy callee wyrażenia wywołania. Ustaw advanced=true, gdy celowo używasz filtrów path/ltree/call.
field_role Opcjonalne
Typ
str
Opis
Zaawansowane — preferuj preset=functions|classes|methods|imports|variables. Filtr roli pola AST. Ustaw advanced=true, gdy celowo używasz filtrów path/ltree/call.
ltree_ancestor Opcjonalne
Typ
str
Opis
Zaawansowane — preferuj preset=functions|classes|methods|imports|variables. Filtr ścieżki przodka ltree AST. Ustaw advanced=true, gdy celowo używasz filtrów path/ltree/call.
ltree_descendant Opcjonalne
Typ
str
Opis
Zaawansowane — preferuj preset=functions|classes|methods|imports|variables. Filtr ścieżki potomka ltree AST. Ustaw advanced=true, gdy celowo używasz filtrów path/ltree/call.
definition_name Opcjonalne
Typ
str
Opis
Zaawansowane — preferuj preset=functions|classes|methods|imports|variables. Filtr nazwy definicji. Ustaw advanced=true, gdy celowo używasz filtrów path/ltree/call.
min_depth Opcjonalne
Typ
int
Opis
Zaawansowane — preferuj preset=functions|classes|methods|imports|variables. Minimalna głębokość AST. Ustaw advanced=true, gdy celowo używasz filtrów path/ltree/call.
max_depth Opcjonalne
Typ
int
Opis
Zaawansowane — preferuj preset=functions|classes|methods|imports|variables. Maksymalna głębokość AST. Ustaw advanced=true, gdy celowo używasz filtrów path/ltree/call.

Najlepsze do:

  • Struktura na poziomie AST: klasy, dekoratory, presety funkcji/metod
  • Wyszukiwanie kodu według kształtu, a nie tekstu

Niezalecane do:

  • Zapytania w wolnym tekście lub koncepcyjne — użyj semantic_search lub intelligent_search

dependency_search Stabilne

Podstawowe narzędzie do analizy zasięgu wpływu i grafu. Odpowiada na „jaki kod wywołuje ten symbol?” / „z czego korzysta ten symbol?” na podstawie rzeczywistego grafu wywołań/importów. Przed edycją użyj analysis_type="dependents" lub analysis_type="impact" (relacje przychodzące; dla impact domyślnie shallow), z include_metrics=false domyślnie (włącz dla centrality + refactor_risk). dependents/impact domyślnie zawierają production_callers: unikalne miejsca użycia w kodzie produkcyjnym według rodzaju (call, instantiate, value_reference dla funkcji przekazywanych jako wartości) oraz miejsca IMPORT, bez testów, z poziomem pewności EXTRACTED/INFERRED — nie sam zrzut metryk. Aby zbadać wpływ PR/diff, przekaż changed_paths i/lub patch (unified diff): narzędzie znajduje symbole dla każdej ścieżki i zwraca zwięzłą odpowiedź z kodem zależnym od nich, po płytkim przejściu po relacjach przychodzących, bez konieczności podawania nazwy symbolu. Po edycji ustaw verify_after_edit=true z targets i/lub changed_paths, aby zwięźle ponownie odpytać symbole objęte wpływem zmian z wielu punktów początkowych. Obsługuje też dependencies, centrality i orphans. analyze_dependencies używa tego samego przechodzenia grafu do analizy wpływu przez wiele skoków.

Parametry:

repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
query Opcjonalne
Typ
str
Opis
Nazwa symbolu lub fraza wyszukiwania
target Opcjonalne
Typ
str
Opis
Nazwa symbolu (alias dla query)
symbol_id Opcjonalne
Typ
UUID
Opis
Wybierz za pomocą UUID konkretne wystąpienie spośród kandydatów o nazwie wskazanej w query/target, po filtrowaniu według przestrzeni nazw, ścieżki i języka. Użyj ID zwróconego przez find_symbol lub alternatywne wyniki grafu. Tylko dla przechodzenia grafu z podaną nazwą; ID spoza ograniczonego okna kandydatów powoduje błąd.
changed_paths Opcjonalne
Typ
list[str] maxItems=50
Opis
Dokładne ścieżki plików względem katalogu głównego repozytorium do analizy wpływu PR/diff (domyślnie) lub, przy verify_after_edit=true, punkty początkowe weryfikacji po edycji. Nierozwiązane ścieżki mogą zwrócić oznaczone sugestie; zasugerowane pliki nigdy nie stają się punktami początkowymi analizy wpływu. PR/diff: bez informacji o liniach przechodzi po definicjach najwyższego poziomu każdej ścieżki (najpierw eksportowanych, w kolejności z pliku) i zgłasza changed_lines_unknown; przekaż patch=, aby uzyskać symbole zmienione na poziomie linii. Weryfikacja: do 5 definicji najwyższego poziomu na ścieżkę jako punkty początkowe (w trybie weryfikacji obowiązuje niższy limit maksymalny). Analiza wpływu PR/diff nie wymaga query/target.
patch Opcjonalne
Typ
str maxLength=500000
Opis
Analiza wpływu PR/diff: tekst w formacie unified diff / git patch. Ścieżki pochodzą z nagłówków diff --git / --- / +++; linie hunków (stara strona = zindeksowany commit) są mapowane na obejmujące je funkcje, metody i klasy, po których następnie przechodzi się, by znaleźć dokładne elementy zależne, public_api_changed i elementy wywołujące, których diff nie dotyka.
head_commit Opcjonalne
Typ
str pattern=^[0-9a-fA-F]{7,64}$
Opis
SHA commita kodu, o który pytasz (git rev-parse HEAD albo commit bazowy patcha). complete:true wymaga, by indeks był na tym commicie i został zbudowany przez bieżący resolver; w przeciwnym razie zostaje complete:false z index_stale / index_freshness_unverified / index_built_by_older_resolver, a index_basis.statement mówi, w jakim zakresie odpowiedź jest kompletna. Dostarcza go też wiersz 'base-commit:' patcha (git format-patch --base).
analysis_type Opcjonalne
Typ
Literal[centrality, dependencies, dependents, impact, orphans]
Domyślnie
dependencies
Opis
Tryb analizy. impact = zasięg wpływu (kod zależny od symbolu przez relacje przychodzące; głębokość shallow, gdy pominięto depth). dependents również służy do analizy wpływu. Gdy ustawiono changed_paths lub patch, wymuszana jest analiza wpływu PR/diff. centrality/orphans nie wymagają target. orphans to kandydaci na nieużywany kod, a nie dowód, że można go bezpiecznie usunąć; sprawdź odwołania w kodzie źródłowym.
depth Opcjonalne
Typ
Literal[shallow, balanced, deep]
Opis
Głębokość przechodzenia. Domyślnie balanced; impact i PR/diff impact domyślnie używają shallow. Jawnie podane depth zastępuje te wartości domyślne. Tryb weryfikacji zawsze używa shallow.
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
20
Opis
Maksymalna liczba wyników na stronie bez cursor. Kontynuacja korzysta z rozmiaru strony zapisanego w cursor; pomiń cursor, aby zacząć z innym limit.
offset Opcjonalne
Typ
int minimum=0
Opis
Przestarzały offset dla zgodności wstecznej. Preferuj cursor z pagination.next_cursor.
cursor Opcjonalne
Typ
str
Opis
Nieprzezroczysty cursor z pagination.next_cursor. Przekaż go bez zmian i pozostaw query oraz filtry niezmienione. Jego pozycja i rozmiar strony mają pierwszeństwo przed offset i limit.
path_filter Opcjonalne
Typ
str
Opis
Ogranicza rozwiązywanie symbolu docelowego według prefiksu ścieżki pliku; zwrócone relacje grafu mogą wykraczać poza tę ścieżkę
language_filter Opcjonalne
Typ
str
Opis
Filtruje rozwiązywanie celu i wyniki przeglądania według języka
direction Opcjonalne
Typ
Literal[outgoing, incoming, both]
Opis
Kierunek przechodzenia (nadpisuje inferencję analysis_type)
relationship_types Opcjonalne
Typ
list[str]
Opis
Filtr typów krawędzi (CALL, IMPORT, INHERITS_FROM itd.). Niepusta lista zastępuje wartości domyślne graph_view.
exclude_test_paths Opcjonalne
Typ
bool
Domyślnie
true
Opis
Domyślnie true: wyklucza ścieżki testów, fixture'ów, kodu dostawców (vendor) i przykładów z wyników przeszukiwania i centrality. Ustaw false, aby je uwzględnić. Analiza orphan respektuje to ustawienie tylko tam, gdzie obsługuje je wdrożony backend; w przeciwnym razie zachowuje własne, bardziej rygorystyczne wykluczenia szumu i zgłasza tę korektę.
exclude_generated_paths Opcjonalne
Typ
bool
Domyślnie
false
Opis
Wyklucz z wyników przechodzenia wygenerowane deklaracje oraz ścieżki artefaktów kompilacji, raportów pokrycia testami, pamięci podręcznej, map kodu źródłowego i zminifikowanych plików
include_module_symbols Opcjonalne
Typ
bool
Domyślnie
false
Opis
Domyślnie false: pomijaj krawędzie, których from_name lub to_name to syntetyczny symbol __module__ (szum na poziomie modułu). Ustaw true, aby uwzględnić krawędzie na poziomie modułu w wynikach dependents/dependencies.
include_isolated Opcjonalne
Typ
bool
Opis
Tylko dla orphans. Domyślnie false. Ustaw true, aby zwracać także symbole bez wiersza w metrykach grafu (bez żadnych krawędzi w grafie). Dopóki exclude_test_paths ma wartość true, symbole arkuszy stylów, znaczników i danych (CSS, HTML, ...), deklaracje .d.ts oraz ścieżki test/fixture/vendor/example pozostają wykluczone tam, gdzie backend to obsługuje, chyba że language_filter wskazuje dany język; właściwości literałów obiektowych TypeScript nadal mogą pojawiać się jako izolowane funkcje.
exclude_exported Opcjonalne
Typ
bool
Domyślnie
false
Opis
Tylko dla osieroconych symboli. Domyślnie false: eksportowane symbole (publiczne API), których nic w repozytorium nie używa, są zwracane z is_exported=true. Ustaw true, aby uzyskać tylko kandydatów wewnętrznych.
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (jednorazowe)
per_hop_limit Opcjonalne
Typ
int minimum=1, maximum=300
Opis
Maksymalna liczba relacji na jeden przeskok (1-300)
include_metrics Opcjonalne
Typ
bool
Domyślnie
false
Opis
Opcjonalne metryki grafowe w wierszach wyników (skompresowane z refactor_risk). Metryki są też pobierane wewnętrznie, gdy min_centrality>0, ale nie są zwracane, jeśli to nie jest ustawione na true.
metrics_detail Opcjonalne
Typ
Literal[summary, full]
Domyślnie
summary
Opis
Gdy include_metrics=true: summary (domyślnie) zwraca sygnały decyzyjne + refactor_risk; full zwraca większy, wyselekcjonowany zestaw metryk
include_edge_metadata Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz surowe metadane i wagi krawędzi (duża objętość danych). Zwięzłe odpowiedzi analizy wpływu pozostawiają ten parametr wyłączony.
symbol_types Opcjonalne
Typ
list[str]
Opis
Filtruje zwracane symbole według rodzaju (function, class, method itd.). Nieobsługiwane w analizie orphan; użyj tam path_filter lub language_filter. Pusta lista oznacza brak filtrowania według rodzaju.
exact_match Opcjonalne
Typ
bool
Domyślnie
false
Opis
Wymagaj dokładnego dopasowania nazwy symbolu
find_similar_patterns Opcjonalne
Typ
bool
Domyślnie
false
Opis
Znajdź podobne wzorce użycia
min_centrality Opcjonalne
Typ
float minimum=0
Domyślnie
0
Opis
Minimalny wynik PageRank dla przechodzenia po nazwanych symbolach i analizy wpływu PR/diff. Wartości progowe większe od zera nie są obsługiwane w trybach przeglądania centrality/orphans. Metryki są pobierane wewnętrznie do filtrowania; graph_metrics są zwracane tylko wtedy, gdy include_metrics=true. Ignorowane przez verify_after_edit, które używa stałych, zwięzłych ustawień.
graph_view Opcjonalne
Typ
Literal[dependency, type, data_flow, control_flow]
Domyślnie
dependency
Opis
Widok grafu używany do wartości domyślnych relacji przeszukiwania, metryk i rankingu centrality; analiza orphan jest obliczana we wszystkich widokach
verify_after_edit Opcjonalne
Typ
bool
Domyślnie
false
Opis
Ponownie odpytuje zindeksowany graf wpływu dla edytowanych symboli w jednej kompaktowej odpowiedzi z wieloma korzeniami. Wymaga targets i/lub changed_paths (lub target/query). Używa stałego przechodzenia shallow i kompaktowych limitów; ustawienia depth/limit/cursor/metrics nie mają zastosowania. Domyślnie zwraca incoming dependents; wyniki odzwierciedlają zindeksowany graf (mogą być opóźnione względem bieżących edycji). Gdy true, ma pierwszeństwo przed PR/diff impact dla tych samych changed_paths.
targets Opcjonalne
Typ
list[str] maxItems=15
Opis
Gdy verify_after_edit=true: nazwy symboli do ponownej weryfikacji (kod, który je wywołuje lub od nich zależy). Łączone z target/query, jeśli podano oba źródła.

Najlepsze do:

  • Analiza zasięgu wpływu przed edycją współdzielonego symbolu
  • Wpływ PR/diff poprzez changed_paths lub patch
  • Weryfikacja po edycji poprzez verify_after_edit

Niezalecane do:

  • Proste wyszukiwania tekstu lub symboli — użyj text_pattern_search lub find_symbol

Narzędzia analizy kodu

#

find_symbol Stabilne

Przejdź do miejsca, gdzie funkcja, klasa lub zmienna jest zdefiniowana i używana. Używaj, gdy znasz nazwę (np. "getCurrentUser") — szybsze i precyzyjniejsze niż Grep, obejmuje całe zaindeksowane repo. Opcjonalnie zwraca referencje i metryki ważności.

Parametry:

symbol_name Opcjonalne
Typ
str
Opis
Nazwa symbolu do wyszukania (opcjonalne — pomiń, aby przeglądać według metryk)
repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
scope Opcjonalne
Typ
Literal[definitions, references, both]
Domyślnie
both
Opis
Zakres wyszukiwania; references wymaga niepustego symbol_name.
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
15
Opis
Maksymalna liczba wyników na stronie bez cursor. Kontynuacja korzysta z rozmiaru strony zapisanego w cursor; pomiń cursor, aby zacząć z innym limit.
offset Opcjonalne
Typ
int minimum=0
Opis
Przestarzały offset dla zgodności wstecznej. Preferuj cursor z pagination.next_cursor.
cursor Opcjonalne
Typ
str
Opis
Nieprzezroczysty cursor z pagination.next_cursor. Przekaż go bez zmian i pozostaw query oraz filtry niezmienione. Jego pozycja i rozmiar strony mają pierwszeństwo przed offset i limit.
find_similar Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz podobne nazwy symboli
include_metrics Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz metryki centralności
metrics_detail Opcjonalne
Typ
Literal[summary, full]
Domyślnie
summary
Opis
Gdy include_metrics=true: summary (domyślnie) zwraca sygnały decyzyjne + refactor_risk; full zwraca większy, wyselekcjonowany zestaw metryk
path_filter Opcjonalne
Typ
str
Opis
Filtr według prefiksu ścieżki pliku
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (jednorazowe)
symbol_type Opcjonalne
Typ
str minLength=1
Opis
Filtruj według indeksowanego rodzaju symbolu, np. function, class, struct, enum lub trait. Użyj rodzaju zwróconego przez wynik symbolu; rodzaj różni się w zależności od języka.
high_impact Opcjonalne
Typ
bool
Domyślnie
false
Opis
Przeglądaj architektonicznie ważne symbole (pomiń symbol_name). Domyślny tryb to popularity (górny decyl PageRank z wyłączeniem silnie połączonych węzłów kodu pomocniczego). Ustaw high_impact_mode=risk dla punktów artykulacji, czyli wierzchołków rozcinających, które łączą części grafu.
high_impact_mode Opcjonalne
Typ
Literal[popularity, risk]
Domyślnie
popularity
Opis
Gdy high_impact=true: popularity = górny decyl PageRank z wyłączeniem silnie połączonych węzłów/modułów kodu pomocniczego; risk = punkty artykulacji uszeregowane według SMV bridge_count, a następnie k_core (ryzyko refaktoryzacji strukturalnej, a nie popularność węzła)
in_cycle Opcjonalne
Typ
bool
Domyślnie
false
Opis
Filtruje symbole z odnotowaną przynależnością do cyklu zależności.
exclude_test_paths Opcjonalne
Typ
bool
Domyślnie
true
Opis
Przy przeglądaniu według metryk grafu wyklucz testy, fixture’y testowe, kod zewnętrzny i przykłady przed rankingowaniem; wyszukiwanie symbolu po nazwie pozostaje bez zmian
reference_views Opcjonalne
Typ
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
Opis
Widoki grafu, których krawędzie przychodzące wypełniają references/reference_count (scope references/both). Domyślnie ["dependency", "type"]: wywołania, importy, eksporty, odwołania, tworzenie instancji, dziedziczenie, nadpisania, dekoratory i użycie typów. Bez wybrania data_flow dokładnie rozstrzygnięte użycia data_flow (wywołania zwrotne, procedury obsługi, klucze sortowania) są zwracane osobno jako value_references/value_reference_count, bez dopasowań wywnioskowanych tylko z nazwy. Dodaj data_flow lub control_flow albo przekaż ["all"] dla wszystkich typów i poziomów krawędzi. Te same rodziny widoków co graph_view w dependency_search.
relationship_types Opcjonalne
Typ
list[str]
Opis
Jawne typy krawędzi odwołań (CALL, IMPORT, READS itd.). Niepusta lista zastępuje reference_views.

Najlepsze do:

  • Przypięcie definicji, referencji i metryk grafowych znanego symbolu
  • Przeglądanie według centrality, high_impact lub in_cycle, gdy symbol_name jest pominięty

Niezalecane do:

  • Zapytania koncepcyjne lub dotyczące nieznanego obszaru — użyj intelligent_search lub semantic_search

analyze_dependencies Stabilne

Analizuje zasięg wpływu, używając tego samego przechodzenia grafu co dependency_search (dependents/incoming). Do analizy wpływu preferuj dependency_search z analysis_type="dependents" lub "impact". Zwraca odpowiedź obejmującą wiele skoków z graph, connection_summary oraz opcjonalnymi metrykami z refactor_risk. Użyj graph_view, aby określić zakres rodziny relacji: dependency (domyślnie), type, data_flow, control_flow. connection_summary zlicza dla wybranego korzenia krawędzie ograniczone do rodziny relacji, przed jakimkolwiek filtrowaniem testów i ścieżek. Przestarzałe pola incoming_production/outgoing_production oznaczają krawędzie spoza modułów, wraz z testami; nie są to liczby wywołujących funkcji produkcyjnych.

Parametry:

repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
target Wymagane
Typ
str minLength=1
Opis
Nazwa symbolu do analizy
symbol_id Opcjonalne
Typ
UUID
Opis
Wybierz za pomocą UUID konkretne wystąpienie spośród kandydatów target, po filtrowaniu według przestrzeni nazw, ścieżki i języka; ID spoza ograniczonego okna kandydatów powodują błąd.
depth Opcjonalne
Typ
Literal[shallow, balanced, deep]
Domyślnie
balanced
Opis
Głębokość analizy
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
10
Opis
Maksymalna liczba wyników na stronie bez cursor. Kontynuacja korzysta z rozmiaru strony zapisanego w cursor; pomiń cursor, aby zacząć z innym limit.
offset Opcjonalne
Typ
int minimum=0
Opis
Przestarzały offset dla zgodności wstecznej. Preferuj cursor z pagination.next_cursor.
cursor Opcjonalne
Typ
str
Opis
Nieprzezroczysty cursor z pagination.next_cursor. Przekaż go bez zmian i pozostaw query oraz filtry niezmienione. Jego pozycja i rozmiar strony mają pierwszeństwo przed offset i limit.
direction Opcjonalne
Typ
Literal[incoming, outgoing, both]
Domyślnie
incoming
Opis
Kierunek przechodzenia
relationship_types Opcjonalne
Typ
list[str]
Opis
Filtruje typy krawędzi (CALL, IMPORT, INHERITS_FROM itd.). Niepusta lista zastępuje wartości domyślne graph_view; pusta lista używa tych wartości domyślnych.
graph_view Opcjonalne
Typ
Literal[dependency, type, data_flow, control_flow]
Domyślnie
dependency
Opis
Widok grafu: określa zarówno domyślne typy przechodzonych krawędzi, jak i to, z którego widoku pochodzą metryki używane przy include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (domyślny), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Stosowany jako wartość domyślna relationship_types, gdy relationship_types jest pominięty lub pusty. Zgodny z istniejącą już nazwą parametru graph_view w dependency_search, dla spójności między narzędziami.
path_filter Opcjonalne
Typ
str
Opis
Ogranicza rozwiązywanie symbolu docelowego według prefiksu ścieżki pliku; zwrócone relacje grafu mogą wykraczać poza tę ścieżkę
language_filter Opcjonalne
Typ
str
Opis
Filtr języka
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (jednorazowe)
per_hop_limit Opcjonalne
Typ
int minimum=1, maximum=300
Opis
Maksymalna liczba relacji na jeden przeskok (1-300)
include_metrics Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz do wyników metryki grafu, wzbogacone o pochodny blok refactor_risk ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk ma wartość "low", gdy symbol nie jest punktem artykulacji w wybranym widoku, "medium", gdy jest punktem artykulacji łączącym niewiele krawędzi, oraz "high", gdy łączy ich wiele (próg heurystyczny, niezweryfikowany empirycznie). Blok jest pomijany dla danego symbolu, jeśli nie ma wiersza metryk dla tego symbolu/widoku.
metrics_detail Opcjonalne
Typ
Literal[summary, full]
Domyślnie
summary
Opis
Gdy include_metrics=true: summary (domyślnie) zwraca sygnały decyzyjne + refactor_risk; full zwraca większy, wyselekcjonowany zestaw metryk
include_edge_metadata Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz surowe metadane i wagi krawędzi. Domyślnie wyłączone, ponieważ metadane ekstraktora mogą być duże; po włączeniu raportowany jest odsetek krawędzi wzbogaconych o dodatkowe dane.
exclude_test_paths Opcjonalne
Typ
bool
Domyślnie
true
Opis
Domyślnie true: wyklucz ścieżki testów, fixture’ów testowych, kodu zewnętrznego i przykładów ze zwracanych krawędzi grafu. Ustaw false, aby je uwzględnić.
include_module_symbols Opcjonalne
Typ
bool
Domyślnie
false
Opis
Domyślnie false: pomijaj krawędzie, których from_name lub to_name to syntetyczny symbol __module__. Ustaw true, aby uwzględnić krawędzie na poziomie modułu.
head_commit Opcjonalne
Typ
str pattern=^[0-9a-fA-F]{7,64}$
Opis
SHA commita kodu, o który pytasz (git rev-parse HEAD albo commit bazowy patcha). complete:true wymaga, by indeks był na tym commicie i został zbudowany przez bieżący resolver; w przeciwnym razie zostaje complete:false z index_stale / index_freshness_unverified / index_built_by_older_resolver, a index_basis.statement mówi, w jakim zakresie odpowiedź jest kompletna. Dostarcza go też wiersz 'base-commit:' patcha (git format-patch --base).

Najlepsze do:

  • Analiza wpływu przez wiele skoków, gdy potrzebujesz pól odpowiedzi graph i connection_summary

Niezalecane do:

  • Ogólna analiza wpływu — preferuj dependency_search do elastycznego przechodzenia grafu i kontroli z wielu punktów początkowych

get_task_context Stabilne

Zaczynasz pracę w nieznanym obszarze? Opisz zadanie (np. „dodaj obsługę SSO”, „napraw webhook rozliczeniowy”), aby jednym wywołaniem otrzymać ograniczony zestaw powiązanych plików, kodu, symboli i zależności. Pliki przekazane jako seed dostarczają bezpośrednio zindeksowaną treść, nawet jeśli nie definiują żadnych symboli. Nieudane warstwy są oznaczane; całkowite niepowodzenie pobierania zwraca błąd narzędzia. Aby uzyskać więcej wyników, kontynuuj z dedykowanym narzędziem wyszukiwania dla danej warstwy.

Parametry:

task_description Wymagane
Typ
str minLength=1
Opis
Opis zadania, dla którego potrzebujesz kontekstu
repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
15
Opis
Maksymalna liczba elementów kontekstu na warstwę
scope Opcjonalne
Typ
Literal[semantic, symbols, dependencies, all]
Domyślnie
all
Opis
Które warstwy kontekstu uwzględnić
language_filter Opcjonalne
Typ
str
Opis
Filtr języka: wymaga scope=semantic bez jawnych punktów startowych ani powiązanego kontekstu; indeksy innych warstw nie mogą wymusić języka.
path_filter Opcjonalne
Typ
str
Opis
Prefiks ścieżki pliku dla punktów startowych wyszukiwania semantycznego i słów kluczowych. Jawne punkty początkowe mogą znajdować się poza tym prefiksem; kontekst grafu może wykraczać poza granice katalogów.
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (jednorazowe)
include_related_context Opcjonalne
Typ
bool
Domyślnie
false
Opis
Dołącz powiązany kontekst od sąsiednich symboli
seed_symbol_ids Opcjonalne
Typ
list[str] maxItems=20
Opis
Jawne punkty początkowe zadania: pojawiają się jako pierwsze w warstwie symboli i są zachowywane w ograniczonym oknie dependencies/related_context. Warstwy grafu porządkują jawne punkty początkowe i ich najbliższe sąsiedztwo przed powrotem do słów kluczowych; znaczenie rozstrzyga tylko przy równej trafności. Rozszerzanie grafu wymaga scope=all|dependencies (scope=symbols|semantic nigdy nie uruchamia przeszukiwania zależności). Pomiń parametr, aby uzyskać ranking wyłącznie na podstawie słów kluczowych, według malejącego wraz z głębokością znaczenia.
seed_file_paths Opcjonalne
Typ
list[str] maxItems=10
Opis
Jawne punkty początkowe: dokładne zaindeksowane ścieżki plików, które agent ma otwarte lub właśnie edytował. Zwraca ograniczoną ilość treści bezpośrednio z tych plików oraz do 5 grafowych punktów początkowych na plik, przedkładając dokładne dopasowania do nazwy zadania z ograniczonego wyszukiwania symboli nad definicje i symbole przypadkowe. Pliki bez symboli również dostarczają materiału. Brakujące pliki mogą zwrócić oznaczone sugestie, które nie są punktami początkowymi. Rozszerzanie grafu wymaga scope=all|dependencies.

Najlepsze do:

  • Kontekst uwzględniający zadanie, łączący pliki wskazane jako punkty początkowe z warstwami semantyczną, symboli i zależności

Niezalecane do:

  • Wyszukiwania jednym narzędziem, gdzie bardziej wyspecjalizowane narzędzie już odpowiada na pytanie

get_file Stabilne

Odczytuje plik z indeksowanego repozytorium według ścieżki. Dla plików na dysku preferuj lokalne narzędzia plikowe; użyj tego do zdalnych indeksowanych migawek. Kontynuuj ograniczone odpowiedzi za pomocą metadata.next_line_start i next_character_start. Usuwaj końcowy znak nowej linii oraz znacznik [truncated] tylko wtedy, gdy metadata.truncated=true; w przeciwnym razie może to być dosłowny tekst źródłowy.

Parametry:

file_path Wymagane
Typ
str
Opis
Ścieżka pliku względem katalogu głównego repozytorium
repository Opcjonalne
Typ
str
Opis
Repozytorium w formacie owner/repo[:branch]. Opcjonalne — pomiń, aby użyć domyślnego ustawienia klienta dla danego żądania (gdy jest dostarczone) lub jedynego dostępnego repozytorium; przekaż jawnie tylko wtedy, gdy chcesz celować w inne zaindeksowane repo. Preferowane są dokładnie zaindeksowane gałęzie; niedostępna gałąź może zostać zastąpiona gałęzią main lub jedyną dostępną gałęzią. Metadane odpowiedzi pokazują żądaną i faktycznie użytą tożsamość oraz ostrzegają o takim zastąpieniu.
line_start Opcjonalne
Typ
int minimum=1
Opis
Linia początkowa (indeksowana od 1)
line_end Opcjonalne
Typ
int minimum=1
Opis
Wiersz końcowy (indeksowanie od 1, włącznie; musi być równy lub większy niż line_start)
character_start Opcjonalne
Typ
int minimum=0
Domyślnie
0
Opis
Przesunięcie w jednostkach kodowych UTF-16 tylko w wierszu początkowym (indeksowanie od 0). Użyj metadata.next_character_start, aby kontynuować częściowo odczytany wiersz.
branch Opcjonalne
Typ
str
Opis
Nadpisanie gałęzi (jednorazowe)
max_tokens Opcjonalne
Typ
int minimum=1, maximum=50000
Domyślnie
5000
Opis
Przybliżony budżet treści (4 jednostki kodowe UTF-16 na token; nie jest dokładnym limitem tokenizatora).
include_metadata Opcjonalne
Typ
bool
Domyślnie
true
Opis
Dołącz opisowe metadane pliku. Metadane obcięcia i kontynuacji są zawsze zwracane.

Najlepsze do:

  • Zdalne lub zaindeksowane migawki plików (zakresy wierszy, limity tokenów)

Niezalecane do:

  • Ścieżka już obecna na dysku lokalnym — użyj lokalnego narzędzia Read

Narzędzia systemowe i pomocnicze

#

repository_context Stabilne

Wyświetla listę repozytoriów, które możesz przeszukiwać, lub pobiera informacje identyfikacyjne o jednym z nich (namespace/branch, indexed_commit_sha / aktualność indeksu). Użyj action:"list", gdy nie znasz sluga repozytorium; narzędzia wyszukiwania akceptują znany slug bezpośrednio albo domyślnie używają jedynego repozytorium przypisanego do Twojego klucza. list korzysta z pattern i paginacji; info wymaga repository oraz obsługuje branch i opcjonalne include_statistics=true.

Parametry:

action Wymagane
Typ
Literal[list, info]
Opis
Akcja: list — wyświetl dostępne repo lub info — pobierz informacje o repo
repository Opcjonalne
Typ
str
Opis
Tylko dla info: repozytorium w formacie owner/repo lub owner/repo:branch (wymagane dla info)
branch Opcjonalne
Typ
str
Opis
Tylko dla info: nadpisanie gałęzi
pattern Opcjonalne
Typ
str
Opis
Tylko dla list: podciąg nazwy repozytorium bez rozróżniania wielkości liter
include_statistics Opcjonalne
Typ
bool
Domyślnie
false
Opis
Tylko informacyjnie: obejmuje ograniczone liczniki danych indeksowanych. Liczniki file/blob są dokładne; większe liczniki indeksu są szacunkowe. Zobacz count_accuracy i estimate_analyzed_at. Domyślnie false.
limit Opcjonalne
Typ
int minimum=1, maximum=50
Domyślnie
20
Opis
Maksymalna liczba wyników na stronie bez cursor. Kontynuacja korzysta z rozmiaru strony zapisanego w cursor; pomiń cursor, aby zacząć z innym limit.
offset Opcjonalne
Typ
int minimum=0
Opis
Przestarzały offset zachowany dla zgodności wstecznej. Preferuj cursor z pagination.next_cursor.
cursor Opcjonalne
Typ
str
Opis
Nieprzezroczysty cursor z pagination.next_cursor. Przekaż go bez zmian i pozostaw query oraz filtry niezmienione. Jego pozycja i rozmiar strony mają pierwszeństwo przed offset i limit.

Najlepsze do:

  • Wyświetlanie listy dostępnych repozytoriów
  • Ustalanie tożsamości repozytorium, gałęzi i aktualności HEAD względem indeksu

Niezalecane do:

  • Statystyki dla całej przestrzeni nazw domyślnie — przekaż jawnie include_statistics=true, ponieważ może to być wolniejsze niż samo rozwiązywanie

ask_maguyva Stabilne

Uzyskaj pomoc dotyczącą narzędzi Maguyva lub wyślij zgłoszenie błędu albo prośbę o funkcję, które zostaną zapisane dla opiekunów Maguyva. Nigdy nie umieszczaj w opiniach sekretów ani wrażliwych danych osobowych. evaluate obsługuje wyrażenia deterministyczne; do matematyki, skrótów i ciągów znaków preferuj obliczenia lokalne lub narzędzia środowiska.

Parametry:

operation Wymagane
Typ
Literal[guidance, report_bug, request_feature, evaluate]
Opis
Użyj guidance do pomocy o narzędziach, report_bug do błędów lub request_feature do sugestii. evaluate wykonuje wyrażenia deterministyczne; preferuj obliczenia lokalne.
query Opcjonalne
Typ
str maxLength=500
Opis
Temat pomocy (np. tool_selection, semantic_search) albo ciąg wyrażenia dla evaluate.
description Opcjonalne
Typ
str minLength=1, maxLength=4000
Opis
Wymagane dla report_bug i request_feature. Opinia w dowolnej formie dla opiekunów Maguyva. Nigdy nie umieszczaj sekretów ani wrażliwych danych osobowych.
related_tool Opcjonalne
Typ
Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
Opis
Opcjonalne narzędzie Maguyva najbardziej powiązane z opinią lub zgłoszeniem

Najlepsze do:

  • Wskazówki dotyczące narzędzia (operation="guidance")
  • Trwałe zgłoszenia błędów i propozycje funkcji dla opiekunów Maguyva

Niezalecane do:

  • Obliczenia matematyczne, skróty i ciągi znaków — preferuj obliczenia lokalne lub narzędzia środowiska

Najlepsze praktyki

#
  1. Używaj jawnych nadpisań świadomie: Pomiń repozytorium, gdy Twój klient MCP dostarcza domyślne ustawienie dla żądania lub gdy klucz ma dostęp dokładnie do jednego repozytorium; w przeciwnym razie przekaż je jawnie.
  2. Wybierz właściwy tryb wyszukiwania: Używaj intelligent_search z mode="auto" w większości przypadków. Określ tryb, gdy wiesz dokładnie, czego potrzebujesz.
  3. Wykorzystuj filtry językowe: Użyj language_filter, aby zawęzić wyniki i poprawić wydajność.
  4. Wzmacnianie GraphRAG: Wzmacnianie ważności GraphRAG jest domyślnie wyłączone dla wyszukiwania semantycznego (boost_by_importance=false), aby ranking pozostawał bezpieczny dla agentów. Przekaż boost_by_importance=true, aby włączyć ponowne rankingowanie uwzględniające centralność do przeglądów architektury.
  5. Dopasowanie repozytorium jest niewrażliwe na wielkość liter, ale nie rozmyte: repository_context dopasowuje nazwy repozytoriów bez rozróżniania wielkości liter — ale nie poprawia literówek. Gdy wydana tożsamość różni się od żądanej, metadata.resolution_reason zgłasza "defaulted" (nie zażądano gałęzi) lub "fallback" (żądana gałąź lub repozytorium jest niedostępne). Przy dokładnym dopasowaniu pole jest pomijane.
  6. Łącz narzędzia: Używaj wielu metod API razem, aby uzyskać kompleksową analizę.
  7. Obsługuj duże wyniki: Używaj limit oraz parametrów stronicowania specyficznych dla narzędzia (np. line_start/line_end w get_file).
  8. Używaj ask_maguyva do wskazówek dotyczących narzędzi: Wywołaj ask_maguyva z operation="guidance" i query="tool_selection", aby uzyskać wskazówki i przykłady wyboru narzędzi. Do obliczeń i przekształceń ciągów używaj narzędzi lokalnych.
  9. Sprawdzaj wpływ przed edycją i po niej: Przed edycją współdzielonego symbolu wywołaj dependency_search z analysis_type="impact" (lub przekaż changed_paths dla analizy wpływu PR/diff), aby zobaczyć zasięg wpływu zmiany. Po edycji ustaw verify_after_edit=true z targets i/lub changed_paths, aby uzyskać kompaktową ponowną weryfikację zindeksowanego grafu. Ta kontrola odczytuje zindeksowany graf, a nie lokalne zmiany bez commita, i nie zastępuje lokalnych testów. Sprawdź indexed_commit_sha i aktualność indeksu, zanim uznasz wyniki za dowód dotyczący nowej rewizji.

Charakterystyka wydajności

#
Operacja Uwagi dotyczące wydajności
Wyszukiwanie semantyczne Obejmuje tworzenie reprezentacji wektorowej zapytania i wyszukiwanie wektorowe. Opóźnienie zależy od obu operacji.
Wyszukiwanie tekstowe Przy rozmytym wyszukiwaniu treści dalsze strony pobierają więcej kandydatów. Zawęź zapytanie przez path_filter i language_filter.
Wyszukiwanie strukturalne Odpytuje zindeksowane węzły AST. Użyj konkretnego ustawienia wstępnego lub wzorca i ogranicz liczbę wyników.
Wyszukiwanie zależności Koszt skaluje się wraz z głębokością — preferuj depth="shallow", chyba że potrzebujesz kontekstu wieloetapowego; per_hop_limit ogranicza rozrost
Pobieranie plików Odczytaj potrzebny zakres przez line_start/line_end lub max_tokens, a dla uciętej treści użyj zwróconych metadanych kontynuacji.
Kontekst repozytorium Rozpoznawanie repozytorium odbywa się przy każdym wywołaniu narzędzia. Przekaż repository jawnie, gdy potrzebujesz konkretnego repozytorium.
ask_maguyva (guidance / evaluate) Działa na serwerze MCP bez odpytywania indeksu repozytorium.

Obsługa błędów

#

Odpowiedzi narzędzi zawierają wspólne pola statusu i pola danych właściwe narzędziu na najwyższym poziomie. Wyszukiwanie zwraca results; get_file zwraca content. Wspólne pola obejmują:

  • status: Ciąg znaków — "success" lub "error". Sygnały obniżonego dopasowania i świeżości indeksu mają własne pola: metadata.resolution_reason w metadata oraz index_freshness.status na najwyższym poziomie akcji info w repository_context.
  • timing_ms: Czas wykonania narzędzia w milisekundach
  • applied_filters: Faktycznie zastosowane parametry żądania zapisane dla operacji
  • error: Ciąg komunikatu błędu, gdy status ma wartość "error"; może zawierać wskazówki naprawcze.
  • metadata: Dodatkowe informacje o operacji (routing, cache'owanie, korekty parametrów)
  • pagination: Obecne w odpowiedziach kolekcji stronicowanych kursorem — zawiera has_more i next_cursor. Okna wyszukiwania rankingowego to ograniczone wyniki top-K, a nie kompletne stronicowane kolekcje.

Sprawdź pole status, zanim przetworzysz ładunek narzędzia — jego wartości to "success" lub "error". Obsłuż też błędy transportu MCP/JSON-RPC i walidacji żądania, które mogą wystąpić, zanim jakikolwiek ładunek powstanie. W przypadku sygnałów obniżonego dopasowania lub świeżości czytaj przeznaczone do tego pole: metadata.resolution_reason w metadata albo index_freshness.status na najwyższym poziomie akcji info w repository_context (known/partial/unknown/unavailable).

Pierwsze kroki

#
  1. Skonfiguruj klienta MCP: Skieruj klienta MCP na endpoint serwera Maguyva
  2. Potwierdź dostęp do repozytorium: Użyj repository_context z akcją "list" lub "info", aby sprawdzić repozytoria dostępne dla klucza API
  3. Rozpocznij wyszukiwanie: Zacznij od intelligent_search i w razie potrzeby korzystaj ze specjalizowanych narzędzi
  4. Łącz narzędzia: Używaj wielu narzędzi razem dla kompleksowej analizy kodu

Szczegółowe instrukcje integracji znajdziesz tutaj: przewodnik instalacji.

Powiązane

Czytaj dalej