Přeskočit na obsah

Referenční příručka MCP API

Kompletní přehled všech 11 MCP nástrojů Maguyva určených zákazníkům. Každý nástroj obsahuje parametry, návod k použití a doporučení, k čemu se nejlépe hodí.

Přehled API#

MCP API Maguyva aktuálně nabízí 11 nástrojů určených zákazníkům rozdělených do 4 hlavních kategorií:

  • Základní vyhledávací nástroje - Pokročilé vyhledávací možnosti napříč vaší kódovou základnou
  • Strukturální a grafové nástroje - AST dotazy, vyhledávání symbolů a analýza závislostí
  • Nástroje pro analýzu kódu - Hloubková analýza kódu a mapování vztahů
  • Systémové a pomocné nástroje - Kontext repozitáře, deterministické výpočty a nápověda

Všechny nástroje používají jednotný formát identifikátoru repozitáře: "owner/repo:branch". Větev se ve výchozím stavu nastaví na main, pokud není zadaná.

repository vynechte, pokud klient MCP poskytuje výchozí hodnotu pro daný požadavek nebo pokud má klíč přístup právě k jednomu repozitáři; jinak jej zadejte explicitně. Pomocí repository_context(action="info", repository="owner/repo") zjistíte, jak se repozitář vyhodnotí.

Formát parametru repozitáře#

Všechny MCP nástroje používají tento formát identifikátoru repozitáře:

  • S větví: "owner/repo:branch" - např., "owner/repository:develop"
  • Výchozí větev: "owner/repo" - používá hlavní větev, když není zadána žádná větev "owner/repository"
  • Výchozí repozitář požadavku nebo jediný repozitář: Repozitář vynechte, pokud klient MCP poskytuje výchozí hodnotu pro daný požadavek nebo pokud má klíč přístup právě k jednomu repozitáři; jinak jej zadejte explicitně

Příklady dotazů:

Zeptejte se na konkrétní repo:  "Vyhledat owner/my-repo pro autentizační middleware"
Seznam přístupných úložišť:     "K jakým úložištím může tento klíč Maguyva přistupovat?"
Přepsat pro jeden dotaz:        "Vyhledat vzory ověřování owner/other-repo:develop"

Filtrování podle jazyka#

Všechny vyhledávací nástroje podporují filtrování výsledků podle programovacího jazyka:

  • language_filter="python" - Filtrovat pouze soubory Python
  • language_filter="typescript" - Filtrovat pouze soubory TypeScript
  • Rozlišuje velikost písmen: Používejte názvy jazyků malými písmeny
  • Výchozí: Prázdný řetězec (bez filtrování) – vrátí výsledky ze všech jazyků
  • Podporované pokrytí: Jazykové filtry fungují napříč všemi 279+ podporovanými jazyků a textových technologií. Úplný seznam najdete na kompatibilitu.
"Najdi autentizační middleware pouze v souborech Python"
"Vyhledej databázová připojení v TypeScript"

Referenční příručka API vygenerována ze zdroje dne 22. července 2026.

Základní vyhledávací nástroje#

intelligent_searchStabilní

Začněte zde s jakoukoli otázkou o kódové bázi. Zadejte dotaz v přirozeném jazyce (např. „jak funguje auth“, „kde se zpracovává fakturace“) a nástroj jej automaticky směruje přes sémantické, symbolové, strukturální vyhledávání a vyhledávání závislostí v indexovaném repozitáři. Pro průzkum a plánování jej upřednostněte před agentem Explore a Grep/Glob — prohledá celý indexovaný repozitář najednou místo skenování souborů.

Parametry:

queryPovinné
Typ
str
Popis
Vyhledávací dotaz
repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
modeVolitelné
Typ
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Výchozí
auto
Popis
Režim vyhledávání
limitVolitelné
Typ
int
Výchozí
10
Popis
Maximální počet výsledků v tomto seřazeném okně top-K
language_filterVolitelné
Typ
str
Popis
Filtr jazyka
path_filterVolitelné
Typ
str
Popis
Filtrujte podle předpony cesty k souboru
boost_by_importanceVolitelné
Typ
bool
Výchozí
Popis
Volitelné: přeřazení podle centrality pomocí grafových metrik na úrovni symbolu (is_articulation_point, bridge_count, k_core, centrality atd.). Ve výchozím nastavení vypnuto pro řazení bezpečné pro agenty (globální huby mohou přehlušit relevantní zásahy v implementaci); zapněte pro architektonické prohlídky. Platí pro všechny 4 modality, pokud každý výsledek nese vazbu na symbol.
branchVolitelné
Typ
str
Popis
Přepsání větve
qualityVolitelné
Typ
Literal[quick, balanced, thorough]
Výchozí
balanced
Popis
Předvolba kvality vyhledávání
include_contentVolitelné
Typ
bool
Výchozí
true
Popis
Zahrnout obsah do výsledků
explain_routingVolitelné
Typ
bool
Výchozí
Popis
Zahrňte vysvětlení rozhodnutí o směrování
importance_weightVolitelné
Typ
float
Výchozí
0.3
Popis
Váha pro zvýšení důležitosti (0=žádná, 1=plná)
orphansVolitelné
Typ
bool
Výchozí
Popis
Zahrnout symboly sirotků (žádné příchozí reference)
include_community_contextVolitelné
Typ
bool
Výchozí
Popis
Zahrňte související symboly ze stejné kódové komunity
community_depthVolitelné
Typ
int
Výchozí
1
Popis
Hloubka rozšíření komunitního kontextu
graph_viewVolitelné
Typ
Literal[dependency, type, data_flow, control_flow]
Výchozí
dependency
Popis
Zobrazení grafu pro metriky
seed_symbol_idsVolitelné
Typ
list[str]
Popis
Tier-1 semena úlohy: ID symbolů ústřední pro aktuální úlohu. Když je nastaveno, přehodnotí fúzované zásahy podle blízkosti hloubky rozpadu Approach A (přesná shoda semene + skoky na hraně grafu). Aditivum — pro globální hodnocení vynechejte.
seed_file_pathsVolitelné
Typ
list[str]
Popis
Semena úlohy Tier-1: cesty k indexovaným souborům, které agent otevřel nebo právě upravil. Je-li nastaveno, přehodnotí sloučené zásahy podle blízkosti cesty s hloubkovým rozpadem 1/(1+d) (stejný soubor → stejný adresář → blízké balíčky). Aditivum — pro globální hodnocení vynechejte.

Nejlepší pro:

  • Prohledávání celého indexu nebo start od nuly, když není jasné, který nástroj použít
  • Multimodální sloučené řazení napříč sémantickým, textovým, strukturálním a grafovým vyhledáváním

Nedoporučeno pro:

  • Známý název symbolu — použijte přímo find_symbol
  • Známá cesta na disku — nejprve použijte lokální Read/Grep

semantic_searchStabilní

Najděte kód podle významu, ne přesného textu. Použijte pro koncepční dotazy, jako je „logika opakování“ nebo „tok přihlášení uživatele“, když neznáte název klíčového slova nebo symbolu. Vrátí nejrelevantnější části kódu seřazené podle důležitosti. Pokud je vyhledávání koncepční, preferujte před Grep.

Parametry:

queryPovinné
Typ
str
Popis
vyhledávací dotaz (pojmový, založený na významu)
repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
limitVolitelné
Typ
int
Výchozí
5
Popis
Maximální počet výsledků v tomto seřazeném okně top-K
similarity_thresholdVolitelné
Typ
float
Výchozí
0.6
Popis
Minimální skóre podobnosti
language_filterVolitelné
Typ
str
Popis
Jazykový filtr (python, typescript atd.)
path_filterVolitelné
Typ
str
Popis
Filtrujte podle předpony cesty k souboru
boost_by_importanceVolitelné
Typ
bool
Výchozí
Popis
Volitelné: přeřazení podle centrality PageRank (ve výchozím nastavení vypnuto pro řazení bezpečné pro agenty; zapněte pro architektonické prohlídky)
branchVolitelné
Typ
str
Popis
Přepsání větve (výchozí: z parametru úložiště nebo hlavního)
include_contentVolitelné
Typ
bool
Výchozí
true
Popis
Zahrnout blokový obsah do výsledků
graph_viewVolitelné
Typ
Literal[dependency, type, data_flow, control_flow]
Výchozí
dependency
Popis
Zobrazení grafu pro metriky

Nejlepší pro:

  • Koncepční dotazy ("how does auth work?", "caching strategy")
  • Vyhledávání podobnosti napříč balíčky

Nedoporučeno pro:

  • Známý název symbolu — použijte místo toho find_symbol
  • Přesné řetězce nebo chybové zprávy — použijte text_pattern_search

text_pattern_searchStabilní

Prohledávejte indexovaný obsah. Režimy „exact“ a „regex“ prohledávají pomocí grep celý korpus souborů/blobů; režim obsahu „fuzzy“ prohledává omezený korpus sémantických úseků. Rozsahy „file“ a „symbol“ podporují pouze režim „fuzzy“. Pro přesně vymezený adresář, který je již na disku, použijte místní Grep.

Parametry:

queryPovinné
Typ
str
Popis
Textový vzor k vyhledání
repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
modeVolitelné
Typ
Literal[fuzzy, exact, regex]
Výchozí
exact
Popis
Režim vyhledávání
search_scopeVolitelné
Typ
Literal[content, symbols, files]
Výchozí
content
Popis
Co hledat
limitVolitelné
Typ
int
Výchozí
5
Popis
Maximální počet výsledků vrácených na této stránce
offsetVolitelné
Typ
int
Popis
Zastaralý offset pro zpětnou kompatibilitu. Upřednostněte cursor z pagination.next_cursor.
cursorVolitelné
Typ
str
Popis
Neprůhledný cursor z pagination.next_cursor. Předávejte jej beze změny a query i filtry ponechte nezměněné.
language_filterVolitelné
Typ
str
Popis
Filtr jazyka
path_filterVolitelné
Typ
str
Popis
Filtrujte podle předpony cesty k souboru
case_sensitiveVolitelné
Typ
bool
Výchozí
Popis
Rozlišování velkých a malých písmen
branchVolitelné
Typ
str
Popis
Přepsání větve
fuzzy_algorithmVolitelné
Typ
Literal[hybrid, trigram, levenshtein]
Výchozí
hybrid
Popis
Fuzzy párovací algoritmus
thresholdVolitelné
Typ
float
Výchozí
0.05
Popis
Minimální práh podobnosti pro fuzzy
semantic_fallbackVolitelné
Typ
bool
Výchozí
Popis
Pokud nejsou žádné výsledky, vraťte se k sémantickému vyhledávání

Nejlepší pro:

  • Přesné řetězce, chybové zprávy a regulární výrazy
  • Trigramové fuzzy porovnávání pro téměř shodný text

Nedoporučeno pro:

  • Známá cesta na disku — upřednostněte lokální Grep
  • Koncepční dotazy — použijte semantic_search

Strukturální a grafové nástroje#

structural_searchStabilní

Upřednostněte preset=functions|classes|methods|imports|variables (nebo volný pattern=). Vyhledávejte kód podle tvaru AST (ne podle textu). Filtry střední úrovně: name_pattern, node_type, decorator, parent_child. Filtry path/ltree/call jsou pokročilé — nastavte advanced=true, když je používáte záměrně; ploché klíče advanced jsou stále přijímány pro zpětnou kompatibilitu. Zadejte alespoň jeden strukturální selektor.

Parametry:

repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
presetVolitelné
Typ
Literal[functions, classes, methods, imports, variables]
Popis
Preferovaný strukturální selektor. Rozbaluje se na mezijazykové typy uzlů AST — functions (definice funkcí/šipkových funkcí/metod napříč jazyky); classes (definice tříd/struktur/impl); methods (definice metod (a function_definition pro jazyky bez uzlu metody)); imports (příkazy import/use/include); variables (deklarace proměnných variable/let/const/static). Upřednostněte před volným pattern/node_type pro dotazy typu procházení.
patternVolitelné
Typ
str
Popis
Free-form vzor, když jsou přednastavení příliš hrubá (automatická detekce: 'def foo(' → node_type + name_pattern). Pro procházecí dotazy upřednostněte preset=.
name_patternVolitelné
Typ
str
Popis
Vzor názvu symbolu (zástupný znak shellu, omezený POSIX regulární výraz nebo fuzzy text; max. 256 znaků)
node_typeVolitelné
Typ
str
Popis
Typ uzlu AST (function_definition, class_definition atd.) — pro běžné tvary upřednostněte preset=
decoratorVolitelné
Typ
str
Popis
Filtr názvu dekorátoru
base_classVolitelné
Typ
str
Popis
Filtr základní třídy
language_filterVolitelné
Typ
str
Popis
Jazykový filtr (python, typescript atd.)
limitVolitelné
Typ
int
Výchozí
20
Popis
Maximální počet výsledků vrácených na této stránce
offsetVolitelné
Typ
int
Popis
Zastaralý offset pro zpětnou kompatibilitu. Upřednostněte cursor z pagination.next_cursor.
cursorVolitelné
Typ
str
Popis
Neprůhledný cursor z pagination.next_cursor. Předávejte jej beze změny a query i filtry ponechte nezměněné.
path_filterVolitelné
Typ
str
Popis
Filtrujte podle předpony cesty k souboru
branchVolitelné
Typ
str
Popis
Přepsání větve
query_typeVolitelné
Typ
Literal[node_type, name_pattern, parent_child]
Popis
Explicitní typ dotazu
parent_typeVolitelné
Typ
str
Popis
Nadřazený filtr typu uzlu AST
relationshipVolitelné
Typ
Literal[parent, ancestor]
Výchozí
parent
Popis
Pro dotazy parent_child: pouze přímý rodič nebo jakýkoli předek (použijte předka pro metody třídy vnořené pod tělem/blokem třídy)
has_modifierVolitelné
Typ
str
Popis
Filtrujte podle modifikátoru (export, asynchronní, statický atd.)
advancedVolitelné
Typ
bool
Výchozí
Popis
Nastavte true, když záměrně používáte pokročilé filtry cest, lstromu nebo volání (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Ve výchozím nastavení ponechává false rozhraní agenta zaměřené na předvolby. Pokročilé klávesy v plochém formátu stále fungují pro zpětnou kompatibilitu s upozorněním na metadata.
callee_textVolitelné
Typ
str
Popis
Pokročilé — upřednostněte preset=functions|classes|methods|imports|variables. Filtr textu callee volajícího výrazu. Nastavte advanced=true, když záměrně používáte filtry path/ltree/call.
callee_nameVolitelné
Typ
str
Popis
Pokročilé — upřednostněte preset=functions|classes|methods|imports|variables. Filtr názvu callee volajícího výrazu. Nastavte advanced=true, když záměrně používáte filtry path/ltree/call.
field_roleVolitelné
Typ
str
Popis
Pokročilé — upřednostněte preset=functions|classes|methods|imports|variables. Filtr role pole AST. Nastavte advanced=true, když záměrně používáte filtry path/ltree/call.
ltree_ancestorVolitelné
Typ
str
Popis
Pokročilé — upřednostněte preset=functions|classes|methods|imports|variables. Filtr cesty předka ltree AST. Nastavte advanced=true, když záměrně používáte filtry path/ltree/call.
ltree_descendantVolitelné
Typ
str
Popis
Pokročilé — upřednostněte preset=functions|classes|methods|imports|variables. Filtr cesty potomka ltree AST. Nastavte advanced=true, když záměrně používáte filtry path/ltree/call.
definition_nameVolitelné
Typ
str
Popis
Pokročilé — upřednostněte preset=functions|classes|methods|imports|variables. Filtr názvu definice. Nastavte advanced=true, když záměrně používáte filtry path/ltree/call.
min_depthVolitelné
Typ
int
Popis
Pokročilé — upřednostněte preset=functions|classes|methods|imports|variables. Minimální hloubka AST. Nastavte advanced=true, když záměrně používáte filtry path/ltree/call.
max_depthVolitelné
Typ
int
Popis
Pokročilé — upřednostněte preset=functions|classes|methods|imports|variables. Maximální hloubka AST. Nastavte advanced=true, když záměrně používáte filtry path/ltree/call.

Nejlepší pro:

  • Struktura na úrovni AST: třídy, dekorátory, přednastavení funkcí/metod
  • Hledání kódu podle tvaru, ne podle textu

Nedoporučeno pro:

  • Volný text nebo koncepční dotazy — použijte semantic_search nebo intelligent_search

dependency_searchStabilní

Primární povrch pro blast radius / graf. Odpovídá na otázky „co tohle volá?“ / „co tohle používá?“ prostřednictvím skutečného grafu volání/importů. Pro dopad před úpravou: analysis_type="dependents" nebo analysis_type="impact" (příchozí, ve výchozím stavu shallow pro impact), include_metrics=false ve výchozím nastavení (zapněte pro centrality + refactor_risk). Analýza dopadu PR/diffu (P1-8): předejte changed_paths a/nebo patch (unified diff) — symboly se řeší podle jednotlivých cest a vrací se kompaktní, mělká (shallow) datová sada příchozích závislých bez nutnosti uvádět název symbolu. Po úpravě nastavte verify_after_edit=true s targets a/nebo changed_paths pro kompaktní vícekořenové opětovné dotazování na dotčené symboly. Podporuje také dependencies, centrality a orphans. analyze_dependencies je tenký alias pro cestu impact — pro nové agenty upřednostněte tento nástroj.

Parametry:

repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
queryVolitelné
Typ
str
Popis
Název symbolu nebo hledaný výraz
targetVolitelné
Typ
str
Popis
Název symbolu (alias pro dotaz)
changed_pathsVolitelné
Typ
list[str]
Popis
Repo-relativní cesty pro dopad PR/diff (výchozí) nebo v případě verify_after_edit=true ověřovací kořeny po úpravě. PR/diff: rozlišuje symboly na cestu a prochází mělké příchozí závislé; lze kombinovat s patch=. Verify: Vyřeší až 5 symbolů na cestu jako ověřovací kořeny (uvnitř ověřovacího režimu omezeny níže). Nevyžaduje query/target pro náraz PR/diff.
patchVolitelné
Typ
str
Popis
Dopad PR/diff: sjednocený text opravy rozdílů / git. Cesty jsou analyzovány ze záhlaví diff --git / --- / +++; stejná kompaktní dráha dopadu jako changed_paths.
analysis_typeVolitelné
Typ
Literal[centrality, dependencies, dependents, impact, orphans]
Výchozí
dependencies
Popis
Režim analýzy. impact = blast radius (příchozí závislí; hloubka shallow, pokud depth není zadána). dependents také odpovídá na impact. Když je nastaveno changed_paths nebo patch, analýza je vynucena na dopad PR/diffu. centrality/orphans nevyžadují target.
depthVolitelné
Typ
Literal[shallow, balanced, deep]
Výchozí
balanced
Popis
Hloubka procházení. Pro analysis_type=impact a dopad PR/diffu je efektivní výchozí hodnotou shallow, pokud hloubku (depth) nenastavíte explicitně.
limitVolitelné
Typ
int
Výchozí
20
Popis
Maximální počet výsledků vrácených na této stránce
offsetVolitelné
Typ
int
Popis
Zastaralý offset pro zpětnou kompatibilitu. Upřednostněte cursor z pagination.next_cursor.
cursorVolitelné
Typ
str
Popis
Neprůhledný cursor z pagination.next_cursor. Předávejte jej beze změny a query i filtry ponechte nezměněné.
path_filterVolitelné
Typ
str
Popis
Omezuje rozřešení cílového symbolu podle prefixu cesty k souboru; vrácené vztahy grafu mohou přesahovat mimo tuto cestu
language_filterVolitelné
Typ
str
Popis
Filtruje rozřešení cíle a výsledky procházení podle jazyka
directionVolitelné
Typ
Literal[outgoing, incoming, both]
Popis
Směr průchodu (přepisuje odvození analysis_type)
relationship_typesVolitelné
Typ
list[str]
Popis
Filtr typů hran (CALL, IMPORT, INHERITS_FROM atd.). Neprázdný seznam přepisuje výchozí hodnoty graph_view.
exclude_test_pathsVolitelné
Typ
bool
Výchozí
true
Popis
Výchozí hodnota true: vylučuje cesty testů, fixtures, vendor kódu a příkladů z výsledků procházení a centrality. Nastavte false pro jejich zahrnutí. Analýza orphan vždy uplatňuje vlastní přísnější vyloučení šumu.
exclude_generated_pathsVolitelné
Typ
bool
Výchozí
Popis
Vyloučit generované deklarace plus sestavení, pokrytí, mezipaměť, zdrojovou mapu a minifikované cesty artefaktů z výsledků procházení
include_module_symbolsVolitelné
Typ
bool
Výchozí
Popis
Ve výchozím nastavení false vylučuje okraje grafu, když from_name nebo to_name je syntetický symbol __module__ (šum na úrovni modulu). Nastavte true tak, aby zahrnoval hrany na úrovni modulu ve výsledcích pro závislé a závislé vztahy.
branchVolitelné
Typ
str
Popis
Přepsání větve
per_hop_limitVolitelné
Typ
int
Popis
Maximální počet vztahů na jeden přechod (1-300)
include_metricsVolitelné
Typ
bool
Výchozí
Popis
Volitelné grafové metriky v řádcích výsledků (zkompaktněné s refactor_risk). Metriky se také interně načítají, když min_centrality>0, ale nevrací se, pokud toto není nastaveno na true.
metrics_detailVolitelné
Typ
Literal[summary, full]
Výchozí
summary
Popis
Když include_metrics=true: summary (výchozí) vrací rozhodovací signály + refactor_risk; full vrátí větší soubor vybraných metrik
include_edge_metadataVolitelné
Typ
bool
Výchozí
Popis
Zahrnout nezpracovaná okrajová metadata a váhy (velké). Kompaktní rázové užitečné zatížení toto nechávají vypnuté.
symbol_typesVolitelné
Typ
list[str]
Popis
Filtruje vrácené symboly podle druhu (function, class, method atd.)
exact_matchVolitelné
Typ
bool
Výchozí
Popis
Vyžadovat přesnou shodu názvu symbolu
find_similar_patternsVolitelné
Typ
bool
Výchozí
Popis
Najděte podobné vzorce použití
min_centralityVolitelné
Typ
float
Výchozí
0
Popis
Minimální skóre PageRank. Metriky se interně načítají pro filtrování; graph_metrics se vrací pouze při include_metrics=true.
graph_viewVolitelné
Typ
Literal[dependency, type, data_flow, control_flow]
Výchozí
dependency
Popis
Zobrazení grafu použité pro výchozí hodnoty vztahů procházení, metriky a řazení podle centrality; analýza orphan se počítá napříč všemi zobrazeními
verify_after_editVolitelné
Typ
bool
Výchozí
Popis
Režim ověření po úpravě P2-7: znovu se dotazujte na indexovaný graf dopadu na nedávno upravené symboly v jedné kompaktní odpovědi s více kořeny. Vyžaduje targets a/nebo changed_paths (nebo target/query). Výchozí nastavení pro mělké příchozí závislé osoby; výsledky odrážejí indexovaný graf (mohou se zpozdit živé úpravy). Když je pravda, má přednost před dopadem PR/diff na stejný changed_paths.
targetsVolitelné
Typ
list[str]
Popis
Když verify_after_edit=true: názvy symbolů k opětovnému ověření (volající/závislí). Sloučeno s target/query, pokud jsou dodány oba.

Nejlepší pro:

  • Analýza blast radius / dopadu před úpravou sdíleného symbolu
  • Dopad PR/diff pomocí changed_paths nebo patch
  • Ověření po úpravě pomocí verify_after_edit

Nedoporučeno pro:

  • Jednoduché vyhledávání textu nebo symbolů — použijte text_pattern_search nebo find_symbol

Nástroje pro analýzu kódu#

find_symbolStabilní

Přejít na místo, kde je definována a použita funkce, třída nebo proměnná. Použijte, když znáte název (např. „getCurrentUser“) – rychlejší a přesnější než Grep a zahrnuje celé indexované repo. Volitelně vrací reference a metriky důležitosti.

Parametry:

symbol_nameVolitelné
Typ
str
Popis
Název symbolu, který se má hledat (volitelné – vynechejte procházení podle metrik)
repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
scopeVolitelné
Typ
Literal[definitions, references, both]
Výchozí
both
Popis
Rozsah vyhledávání
limitVolitelné
Typ
int
Výchozí
15
Popis
Maximální počet výsledků vrácených na této stránce
offsetVolitelné
Typ
int
Popis
Zastaralý offset pro zpětnou kompatibilitu. Upřednostněte cursor z pagination.next_cursor.
cursorVolitelné
Typ
str
Popis
Neprůhledný cursor z pagination.next_cursor. Předávejte jej beze změny a query i filtry ponechte nezměněné.
find_similarVolitelné
Typ
bool
Výchozí
Popis
Zahrnout podobné názvy symbolů
include_metricsVolitelné
Typ
bool
Výchozí
Popis
Zahrnout metriky centrality
metrics_detailVolitelné
Typ
Literal[summary, full]
Výchozí
summary
Popis
Když include_metrics=true: summary (výchozí) vrací rozhodovací signály + refactor_risk; full vrátí větší soubor vybraných metrik
path_filterVolitelné
Typ
str
Popis
Filtrujte podle předpony cesty k souboru
branchVolitelné
Typ
str
Popis
Přepsání větve
symbol_typeVolitelné
Typ
Literal[function, class, variable, method, constant, module, interface, type]
Popis
Filtrujte podle typu symbolu
high_impactVolitelné
Typ
bool
Výchozí
Popis
Procházejte architektonicky důležité symboly (vynechte symbol_name). Výchozí režim je popularity (horní decil PageRank minus utilitní mega-huby). Nastavte high_impact_mode=risk pro artikulační/mostní řezné vrcholy (articulation/bridge cut-vertices).
high_impact_modeVolitelné
Typ
Literal[popularity, risk]
Výchozí
popularity
Popis
Když high_impact=true: popularita = top PageRank decil mínus užitkové megarozbočovače/moduly; riziko = artikulační body seřazené podle SMV bridge_count pak k_core (riziko strukturálního refaktoru, nikoli popularita hubu)
in_cycleVolitelné
Typ
bool
Výchozí
Popis
Filtrujte na symboly v cyklech závislostí
exclude_test_pathsVolitelné
Typ
bool
Výchozí
true
Popis
Při procházení podle metrik grafu před hodnocením vylučte testy, fixtures, kód třetí strany a příklady. Vyhledávání podle pojmenovaného symbolu se nemění.

Nejlepší pro:

  • Ukotvení definice, referencí a grafových metrik známého symbolu
  • Procházení podle centrality, high_impact nebo in_cycle, když je symbol_name vynechán

Nedoporučeno pro:

  • Koncepční dotazy nebo dotazy z neznámé oblasti — použijte intelligent_search nebo semantic_search

analyze_dependenciesStabilní

Alias pro blast radius prostřednictvím dependency_search (dependents/incoming). Pro nové agenty upřednostněte dependency_search s analysis_type="dependents" nebo "impact". Zachovává starší vícekrokový tvar odpovědi impact (graph, connection_summary, volitelné metriky s refactor_risk). Pomocí graph_view určete rozsah rodiny vztahů: dependency (výchozí), type, data_flow, control_flow.

Parametry:

repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
targetPovinné
Typ
str
Popis
Název symbolu k analýze
depthVolitelné
Typ
Literal[shallow, balanced, deep]
Výchozí
balanced
Popis
Hloubka analýzy
limitVolitelné
Typ
int
Výchozí
10
Popis
Maximální počet výsledků vrácených na této stránce
offsetVolitelné
Typ
int
Popis
Zastaralý offset pro zpětnou kompatibilitu. Upřednostněte cursor z pagination.next_cursor.
cursorVolitelné
Typ
str
Popis
Neprůhledný cursor z pagination.next_cursor. Předávejte jej beze změny a query i filtry ponechte nezměněné.
directionVolitelné
Typ
Literal[incoming, outgoing, both]
Výchozí
incoming
Popis
Směr průchodu
relationship_typesVolitelné
Typ
list[str]
Popis
Typy hran filtrů (CALL, IMPORT, INHERITS_FROM atd.). Vždy přepíše výchozí nastavení odvozené z graph_view níže, když je dodáno.
graph_viewVolitelné
Typ
Literal[dependency, type, data_flow, control_flow]
Výchozí
dependency
Popis
Zobrazení grafu: Určuje jak výchozí typy hran přechodu, tak metriky pohledu, které se použijí při include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (výchozí), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Použije se pouze jako výchozí relationship_types, když relationship_types není explicitně dodáno. Odpovídá stávajícímu názvu parametru graph_view dependency_search pro konzistenci mezi nástroji.
path_filterVolitelné
Typ
str
Popis
Omezuje rozřešení cílového symbolu podle prefixu cesty k souboru; vrácené vztahy grafu mohou přesahovat mimo tuto cestu
language_filterVolitelné
Typ
str
Popis
Jazykový filtr
branchVolitelné
Typ
str
Popis
Přepsání větve
per_hop_limitVolitelné
Typ
int
Popis
Maximální počet vztahů na jeden přechod (1-300)
include_metricsVolitelné
Typ
bool
Výchozí
Popis
Zahrňte do výsledků metriky grafu, každou obohacenou o odvozený blok refactor_risk ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). riziko je "low", pokud se nejedná o artikulační bod (ve vybraném pohledu), "medium" když artikulační bod přemosťuje několik hran, "high" když přemosťuje mnoho (heuristický práh, empiricky neověřeno). Vynecháno pro každý symbol, pokud pro tento symbol/zobrazení neexistuje žádný řádek metrik.
metrics_detailVolitelné
Typ
Literal[summary, full]
Výchozí
summary
Popis
Když include_metrics=true: summary (výchozí) vrací rozhodovací signály + refactor_risk; full vrátí větší soubor vybraných metrik
include_edge_metadataVolitelné
Typ
bool
Výchozí
Popis
Zahrňte nezpracovaná metadata hran a váhy. Ve výchozím nastavení zakázáno, protože metadata extraktoru mohou být velká; pokrytí obohacením je hlášeno, když je povoleno.
exclude_test_pathsVolitelné
Typ
bool
Výchozí
true
Popis
Výchozí true: vyloučit cesty testu, přípravku, dodavatele a příkladu z vrácených okrajů grafu. Chcete-li je zahrnout, nastavte false.
include_module_symbolsVolitelné
Typ
bool
Výchozí
Popis
Ve výchozím nastavení false vylučuje okraje grafu, když from_name nebo to_name je syntetický symbol __module__. Nastavte true tak, aby zahrnoval hrany na úrovni modulu.

Nejlepší pro:

  • Starší volání již napojená na tvar jeho odpovědi (graph, connection_summary)

Nedoporučeno pro:

  • Nové smyčky agentů — upřednostněte dependency_search, které sdílí stejné jádro procházení

get_task_contextStabilní

Začínáte práci v neznámé oblasti? Popište úkol (např. „přidat podporu SSO“, „opravit billing webhook“) a získejte omezený balíček relevantních souborů, kódu, symbolů a závislostí v jednom volání. Seed soubory poskytují přímý indexovaný obsah, i když nedefinují žádné symboly. Pro více výsledků pokračujte specializovaným vyhledávacím nástrojem pro danou vrstvu.

Parametry:

task_descriptionPovinné
Typ
str
Popis
Popis úkolu, pro který potřebujete kontext
repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
limitVolitelné
Typ
int
Výchozí
15
Popis
Maximální výsledky na vrstvu
scopeVolitelné
Typ
Literal[semantic, symbols, dependencies, all]
Výchozí
all
Popis
Které kontextové vrstvy zahrnout
language_filterVolitelné
Typ
str
Popis
Jazykový filtr
path_filterVolitelné
Typ
str
Popis
Filtrujte podle předpony cesty k souboru
branchVolitelné
Typ
str
Popis
Přepsání větve
include_related_contextVolitelné
Typ
bool
Výchozí
Popis
Zahrňte související kontext ze sousedních symbolů
seed_symbol_idsVolitelné
Typ
list[str]
Popis
Explicitní semena úrovně Tier-1: ID symbolů, o kterých agent již ví, že jsou pro úlohu klíčové (např. symboly v otevřených souborech). Ve vrstvách dependencies/related_context jsou řazena před semena odvozená z klíčových slov. Jde o doplněk — vynechte jej, chcete-li zachovat současné chování založené pouze na klíčových slovech.
seed_file_pathsVolitelné
Typ
list[str]
Popis
Explicitní seedy úrovně 1: indexované cesty souborů, které má agent otevřené nebo právě upravil. Vrací omezené přímé souborové důkazy a řeší až 5 symbolů na soubor pro grafový kontext, včetně dokumentace a konfigurace bez symbolů. Aditivní — vynechte pro chování založené pouze na klíčových slovech.

Nejlepší pro:

  • Kontext zohledňující úkol, který kombinuje seed soubory se sémantickou, symbolovou a závislostní vrstvou

Nedoporučeno pro:

  • Vyhledávání jedním nástrojem, kde na otázku už odpovídá specifičtější nástroj

get_fileStabilní

Přečte soubor z indexovaného repozitáře podle cesty. Pro soubory na disku upřednostněte lokální nástroj Read — tento nástroj použijte pro mezirepozitářová nebo vzdálená vyhledávání, kdy soubor není ve vašem pracovním stromu. Podporuje volitelný rozsah řádků; pokračujte v odpovědi oříznuté podle tokenů z metadata.next_line_start.

Parametry:

file_pathPovinné
Typ
str
Popis
Cesta k souboru vzhledem ke kořenovému adresáři úložiště
repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo[:branch]. Volitelné — vynechte jej, chcete-li použít výchozí repozitář klienta pro daný požadavek (pokud je poskytnut) nebo jediný přístupný repozitář; explicitně jej zadejte pouze pro jiný indexovaný repozitář. Odpověď uvádí použitý repozitář.
line_startVolitelné
Typ
int
Popis
Počáteční řádek (1-indexovaný)
line_endVolitelné
Typ
int
Popis
Koncový řádek (číslováno od 1, včetně; musí být na hodnotě line_start nebo za ní)
branchVolitelné
Typ
str
Popis
Přepsání větve
max_tokensVolitelné
Typ
int
Výchozí
5000
Popis
Maximální počet tokenů k vrácení
include_metadataVolitelné
Typ
bool
Výchozí
true
Popis
V odpovědi zahrňte metadata souboru

Nejlepší pro:

  • Vzdálené nebo indexované snímky souborů (rozsahy řádků, limity tokenů)

Nedoporučeno pro:

  • Cesta již existující na lokálním disku — použijte lokální nástroj Read

Systémové a pomocné nástroje#

repository_contextStabilní

Zobrazí seznam repozitářů, které můžete prohledávat, nebo získá identifikační informace o jednom z nich (namespace/branch, indexed_commit_sha / aktuálnost indexu). Zavolejte jednou s action:"list", abyste zjistili přesný slug repozitáře, který vyhledávací nástroje akceptují. (Pokud má váš klíč přístup pouze k jednomu repozitáři, vyhledávací nástroje jej použijí jako výchozí — toto můžete přeskočit.) Počty file/blob/edge napříč jmenným prostorem jsou volitelné přes include_statistics=true.

Parametry:

actionPovinné
Typ
Literal[list, info]
Popis
Akce: vypsat dostupné repozitáře pomocí list nebo získat informace pomocí info
repositoryVolitelné
Typ
str
Popis
Repozitář ve formátu owner/repo nebo owner/repo:branch (pro info povinné)
branchVolitelné
Typ
str
Popis
Přepsání větve
patternVolitelné
Typ
str
Popis
Filtrovat seznam úložiště podle vzoru
include_statisticsVolitelné
Typ
bool
Výchozí
Popis
Volitelné: zahrne počty indexovaných dat napříč jmenným prostorem (file/blob/edge). Výchozí hodnota false — identifikace repozitáře tento pomalejší agregát nevyžaduje.
limitVolitelné
Typ
int
Výchozí
20
Popis
Maximální počet výsledků vrácených na této stránce
offsetVolitelné
Typ
int
Popis
Zastaralý posun kompatibility. Preferujte cursor před pagination.next_cursor.
cursorVolitelné
Typ
str
Popis
Neprůhledný cursor od pagination.next_cursor. Předejte jej beze změny a ponechte dotaz a filtry nezměněné.

Nejlepší pro:

  • Výpis dostupných repozitářů
  • Zjištění identity repozitáře, větve a aktuálnosti HEAD oproti indexu

Nedoporučeno pro:

  • Statistiky napříč jmenným prostorem ve výchozím nastavení — předejte explicitně include_statistics=true, protože to může být pomalejší než samotné rozlišení

ask_maguyvaStabilní

Nápověda a zpětná vazba k Maguyva. Primární: získejte pokyny k nástrojům nebo odešlete hlášení chyby / požadavek na funkci uložené pro správce Maguyva. Nikdy do zpětné vazby nezahrnujte tajemství ani citlivé osobní údaje. Operace evaluate zůstává pouze pro zpětnou kompatibilitu — pro matematické/hashovací/řetězcové operace upřednostněte lokální výpočty nebo nástroje hostitele.

Parametry:

operationPovinné
Typ
Literal[guidance, report_bug, request_feature, evaluate]
Popis
Primární: guidance, report_bug, request_feature. Pouze starší/pro kompatibilitu: evaluate (deterministický engine výrazů; není součástí primárního pracovního postupu agenta).
queryVolitelné
Typ
str
Popis
Téma nápovědy (např. tool_selection, semantic_search). Pouze pro starší evaluate: řetězec výrazu.
descriptionVolitelné
Typ
str
Popis
Vyžadováno pro report_bug a request_feature. Free-form zpětná vazba pro správce Maguyva. Nikdy nezahrnujte tajemství ani citlivé osobní údaje.
related_toolVolitelné
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]
Popis
Volitelný nástroj Maguyva nejblíže související se zpětnou vazbou

Nejlepší pro:

  • Nápověda k nástroji (operation="guidance")
  • Trvalá hlášení chyb a požadavky na funkce pro správce Maguyva

Nedoporučeno pro:

  • Matematické/hashovací/řetězcové výpočty — operace evaluate zůstává pouze pro zpětnou kompatibilitu; upřednostněte lokální výpočet na hostiteli

Osvědčené postupy#

  1. Záměrně používejte explicitní přepisy: Repozitář vynechte, pokud klient MCP poskytuje výchozí hodnotu pro daný požadavek nebo pokud má klíč přístup právě k jednomu repozitáři; jinak jej zadejte explicitně.
  2. Vyberte správný režim vyhledávání: Pro většinu případů použijte intelligent_search s mode="auto". Určete režim, když přesně víte, co potřebujete.
  3. Využijte jazykové filtry: Použijte language_filter k zúžení výsledků a zlepšení výkonu.
  4. GraphRAG Posílení: Posílení důležitosti GraphRAG je pro sémantické vyhledávání ve výchozím nastavení vypnuto (boost_by_importance=false), aby řazení zůstalo bezpečné pro agenty. Předejte boost_by_importance=true, čímž zapnete přeřazení podle centrality pro architektonické prohlídky.
  5. Shoda repozitáře nerozlišuje velikost písmen, ale není fuzzy: repository_context porovnává názvy repozitářů bez ohledu na velikost písmen — překlepy neopravuje. Zkontrolujte metadata.resolution_reason u akce info ("exact" vs "corrected"), abyste zjistili, jak byl název vyřešen.
  6. Kombinovat nástroje: Pro komplexní analýzu použijte více metod API společně.
  7. Zvládněte velké výsledky: Použijte limit a ovládací prvky stránkování specifické pro nástroj (například line_start/line_end v get_file).
  8. Použijte ask_maguyva pro nápovědu k nástrojům: Operace evaluate u ask_maguyva (hash, base64, JSON, matematika) je zastaralá / určená jen pro zpětnou kompatibilitu. Místo ní volejte ask_maguyva s operation="guidance" a query="tool_selection" — získáte tak matici priority lokálních nástrojů a kompletní tahák pro každý nástroj.
  9. Ověřujte dopad před úpravou i po ní: Před úpravou sdíleného symbolu zavolejte dependency_search s analysis_type="impact" (nebo předejte changed_paths pro analýzu dopadu PR/diffu), abyste viděli jeho rozsah dopadu. Po úpravě nastavte verify_after_edit=true s targets a/nebo changed_paths pro kompaktní opětovnou kontrolu stejných symbolů.

Charakteristiky výkonu#

OperacePoznámky k výkonu
Sémantické vyhledáváníPod sekundu, ale pokaždé zahrnuje samostatné volání embedding API (bez cachování) — počítejte s dodatečnou latencí navíc k vektorovému dotazu
Textové vyhledáváníPod sekundu pro přesné/regex vyhledávání; fuzzy vyhledávání obsahu stránkuje na straně klienta, takže hluboké offsety stojí víc — zužte pomocí path_filter/language_filter
Strukturální vyhledáváníIndexováno přes AST — náklady škálují podle objemu výsledků, ne podle velikosti repozitáře
Vyhledávání závislostíNáklady škálují podle hloubky — preferujte depth="shallow", pokud nepotřebujete vícekrokový kontext; per_hop_limit omezuje rozrůstání
Načtení souboruTéměř okamžité pro jeden soubor — velké soubory stránkujte přes line_start/line_end nebo max_tokens místo jednoho velkého načtení
Kontext repozitářeRozřešení jmenného prostoru se cachuje pouze v rámci jednoho požadavku, ne mezi voláními — každé volání nástroje jej vyhodnocuje znovu
ask_maguyva (guidance / evaluate)Téměř okamžité — běží uvnitř Workeru bez volání databáze

Zpracování chyb#

Všechny metody API vracejí strukturovanou obálku:

  • status: Řetězec — "success" nebo "error". Signály částečné shody a zastaralosti dat najdete ve vnořených polích, například metadata.resolution_reason u repository_context nebo metadata.index_freshness.status.
  • tool: Název nástroje, který odpověď vygeneroval
  • data: Datový obsah výsledku při úspěchu (struktura se liší podle nástroje)
  • error: Strukturovaný objekt chyby, když je status rovno "error" — obsahuje type, message, suggestions a recovery_actions
  • metadata: Doplňující informace o operaci (směrování, cachování, úpravy parametrů)
  • pagination: Přítomno u odpovědí se seznamy — obsahuje has_more a next_cursor

Vždy zkontrolujte pole status před zpracováním výsledků — nabývá pouze hodnoty "success" nebo "error". Pro signály částečné shody nebo zastaralosti dat čtěte místo toho vnořené pole: metadata.resolution_reason u repository_context nebo metadata.index_freshness.status (known/partial/unknown/unavailable).

Začínáme#

  1. Nakonfigurujte klienta MCP: Nasměrujte klienta MCP na koncový bod serveru Maguyva
  2. Ověřte přístup k repozitářům: Pomocí repository_context s akcí "list" nebo "info" zkontrolujte repozitáře dostupné pro klíč API
  3. Začněte hledat: Začněte s intelligent_search a podle potřeby prozkoumejte specializované nástroje
  4. Kombinujte nástroje: Pro komplexní analýzu kódu používejte více nástrojů společně

Podrobné pokyny k integraci najdete v průvodce instalací.