Hoppa till innehåll

MCP API-referens

Fullständig referens för alla 11 kundvända Maguyva MCP-verktyg. Varje verktyg innehåller parametrar, användningsvägledning och rekommendationer för bästa användning.

API-översikt#

Maguyva MCP API exponerar för närvarande 11 kundvända verktyg fördelade på 4 huvudkategorier:

  • Grundläggande sökverktyg - Avancerade sökfunktioner i hela din kodbas
  • Strukturella verktyg & grafverktyg - AST-frågor, symboluppslagning och beroendeanalys
  • Kodanalysverktyg - Djup kodanalys och relationskartläggning
  • System- och hjälpverktyg - Repository-kontext, deterministisk beräkning och vägledning

Alla verktyg använder ett konsekvent format för repository-identifierare: "owner/repo:branch". Grenen sätts som standard till main om inget anges.

Utelämna repository när MCP-klienten anger ett anropsspecifikt standardrepo eller när nyckeln har åtkomst till exakt ett repo; ange det annars uttryckligen. Använd repository_context(action="info", repository="owner/repo") för att se hur ett repo matchas.

Format för repository-parameter#

Alla MCP-verktyg använder det här formatet för repository-identifierare:

  • Med gren: "owner/repo:branch" - t.ex., "owner/repository:develop"
  • Standardgren: "owner/repo" - använder main-grenen när ingen gren anges "owner/repository"
  • Standard för anrop eller enda repo: Utelämna repot när MCP-klienten anger ett anropsspecifikt standardrepo eller när nyckeln har åtkomst till exakt ett repo; ange det annars uttryckligen

Exempelprompter:

Fråga om ett specifikt repo:  "Sök owner/my-repo efter autentiseringsmellanprogram"
Lista tillgängliga repor:     "Vilka arkiv kan denna Maguyva-nyckel komma åt?"
Åsidosätt för en fråga:       "Sök owner/other-repo:develop efter autentiseringsmönster"

Språkfiltrering#

Alla sökverktyg stöder filtrering av resultat efter programmeringsspråk:

  • language_filter="python" - Filtrera till endast Python-filer
  • language_filter="typescript" - Filtrera till endast TypeScript-filer
  • Skiftlägeskänsligt: Använd gemena språknamn
  • Standard: Tom sträng (ingen filtrering) - returnerar resultat från alla språk
  • Språktäckning: Språkfilter fungerar över alla 279+ av de språk och textbaserade teknologier som stöds. Se kompatibilitet för den fullständiga listan.
"Hitta autentiseringsmiddleware endast i Python-filer"
"Sök efter databasanslutningar i TypeScript"

API-referens genererad från källkod 22 juli 2026.

Grundläggande sökverktyg#

intelligent_searchStabil

Börja här för alla frågor om kodbasen. Ge en fråga på naturligt språk (t.ex. "hur fungerar autentisering", "var hanteras fakturering") så dirigeras den automatiskt mellan semantisk sökning, symbolsökning, strukturell sökning och beroendesökning i det indexerade repot. Föredra detta framför Explore-agenten och Grep/Glob för utforskning och planering — hela det indexerade repot söks igenom på en gång i stället för att filer skannas.

Parametrar:

queryObligatorisk
Typ
str
Beskrivning
Sökfråga
repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
modeValfri
Typ
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Standard
auto
Beskrivning
Sökläge
limitValfri
Typ
int
Standard
10
Beskrivning
Max antal resultat i detta rankade top-K-fönster
language_filterValfri
Typ
str
Beskrivning
Språkfilter
path_filterValfri
Typ
str
Beskrivning
Filtrera efter filsökvägsprefix
boost_by_importanceValfri
Typ
bool
Standard
Beskrivning
Opt-in: sortera om efter centralitet med symbolspecifika grafmetriker (is_articulation_point, bridge_count, k_core, centrality med mera). Avstängt som standard för agentsäker rankning (globala hubbar kan dränka implementationsträffar); aktivera för arkitekturrundturer. Gäller alla 4 modaliteter när varje resultat har symbolkoppling.
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
qualityValfri
Typ
Literal[quick, balanced, thorough]
Standard
balanced
Beskrivning
Förinställd sökkvalitet
include_contentValfri
Typ
bool
Standard
true
Beskrivning
Inkludera innehåll i resultaten
explain_routingValfri
Typ
bool
Standard
Beskrivning
Inkludera förklaring av routingbeslut
importance_weightValfri
Typ
float
Standard
0.3
Beskrivning
Vikt för betydelseförstärkning (0=ingen, 1=full)
orphansValfri
Typ
bool
Standard
Beskrivning
Inkludera föräldralösa symboler (inga inkommande referenser)
include_community_contextValfri
Typ
bool
Standard
Beskrivning
Inkludera relaterade symboler från samma kodgemenskap
community_depthValfri
Typ
int
Standard
1
Beskrivning
Djup av gemenskapskontextexpansion
graph_viewValfri
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beskrivning
Grafvy för mätvärden
seed_symbol_idsValfri
Typ
list[str]
Beskrivning
Tier-1 uppgiftsfrön: symbol-ID:n centrala för den aktuella uppgiften. När det är inställt, rankas om fusionerade träffar med Approach A djupförfallsnärhet (exakt seedmatch + grafkantshopp). Additiv — utelämna för global rankning.
seed_file_pathsValfri
Typ
list[str]
Beskrivning
Tier-1 uppgiftsfrön: indexerade filsökvägar som agenten har öppnat eller just redigerat. När det är inställt, rankas sammanslagna träffar på nytt efter vägnärhet med 1/(1+d) djupförfall (samma fil → samma dir → närliggande paket). Additiv — utelämna för global rankning.

Bäst för:

  • Indexomfattande eller cold-start-utforskning när det är oklart vilket verktyg som är rätt
  • Multimodal sammanslagen rangordning över semantisk, text, strukturell och graf

Rekommenderas inte för:

  • Ett känt symbolnamn — använd find_symbol direkt
  • En känd sökväg på disk — använd lokal Read/Grep först

semantic_searchStabil

Hitta kod efter betydelse, inte exakt text. Använd för konceptuella frågor som "retry-logik" eller "användarens onboardingflöde" när du inte känner till nyckelordet eller symbolnamnet. Returnerar de mest relevanta kodavsnitten, rangordnade efter betydelse. Föredra detta framför Grep när sökningen är konceptuell.

Parametrar:

queryObligatorisk
Typ
str
Beskrivning
Sökfråga (konceptuell, meningsbaserad)
repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
limitValfri
Typ
int
Standard
5
Beskrivning
Max antal resultat i detta rankade top-K-fönster
similarity_thresholdValfri
Typ
float
Standard
0.6
Beskrivning
Minsta likhetspoäng
language_filterValfri
Typ
str
Beskrivning
Språkfilter (python, typskript, etc.)
path_filterValfri
Typ
str
Beskrivning
Filtrera efter filsökvägsprefix
boost_by_importanceValfri
Typ
bool
Standard
Beskrivning
Opt-in: sortera om efter PageRank-centralitet (avstängt som standard för agentsäker rankning; aktivera för arkitekturrundturer)
branchValfri
Typ
str
Beskrivning
Grenåsidosättning (standard: från repository-parametern eller main)
include_contentValfri
Typ
bool
Standard
true
Beskrivning
Inkludera bitinnehåll i resultaten
graph_viewValfri
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beskrivning
Grafvy för mätvärden

Bäst för:

  • Konceptuella frågor ("hur fungerar auth?", "cachningsstrategi")
  • Likhetssökning över flera paket

Rekommenderas inte för:

  • Ett känt symbolnamn — använd find_symbol istället
  • Exakta strängar eller felmeddelanden — använd text_pattern_search

text_pattern_searchStabil

Sök i indexerat innehåll. Lägena exact och regex använder grep på hela fil-/blobkorpusen; läget fuzzy content söker i den avgränsade korpusen med semantiska avsnitt. Omfången file och symbol stöder endast fuzzy-sökning. Använd lokal Grep för en avgränsad katalog som redan finns på disken.

Parametrar:

queryObligatorisk
Typ
str
Beskrivning
Textmönster att söka efter
repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
modeValfri
Typ
Literal[fuzzy, exact, regex]
Standard
exact
Beskrivning
Sökläge
search_scopeValfri
Typ
Literal[content, symbols, files]
Standard
content
Beskrivning
Vad ska man söka
limitValfri
Typ
int
Standard
5
Beskrivning
Max antal resultat som returneras på denna sida
offsetValfri
Typ
int
Beskrivning
Föråldrad kompatibilitets-offset. Föredra cursor från pagination.next_cursor.
cursorValfri
Typ
str
Beskrivning
Ogenomskinlig cursor från pagination.next_cursor. Skicka den oförändrad och håll query och filter oförändrade.
language_filterValfri
Typ
str
Beskrivning
Språkfilter
path_filterValfri
Typ
str
Beskrivning
Filtrera efter filsökvägsprefix
case_sensitiveValfri
Typ
bool
Standard
Beskrivning
Skiftlägeskänslig matchning
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
fuzzy_algorithmValfri
Typ
Literal[hybrid, trigram, levenshtein]
Standard
hybrid
Beskrivning
Luddig matchningsalgoritm
thresholdValfri
Typ
float
Standard
0.05
Beskrivning
Minsta likhetströskel för fuzzy
semantic_fallbackValfri
Typ
bool
Standard
Beskrivning
Gå tillbaka till semantisk sökning om inga resultat

Bäst för:

  • Exakta strängar, felmeddelanden och regex
  • Trigram-fuzzy-matchning för nästan matchande text

Rekommenderas inte för:

  • En känd sökväg på disk — föredra lokal Grep
  • Konceptuella frågor — använd semantic_search

Strukturella verktyg och grafverktyg#

structural_searchStabil

Föredra preset=functions|classes|methods|imports|variables (eller fritt pattern=). Hittar kod efter AST-form (inte text). Filter på mellannivå: name_pattern, node_type, decorator, parent_child. Path-/ltree-/call-filter är avancerade — sätt advanced=true när du använder dem avsiktligt; platta advanced-nycklar accepteras fortfarande av kompatibilitetsskäl. Ange minst en strukturell selektor.

Parametrar:

repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
presetValfri
Typ
Literal[functions, classes, methods, imports, variables]
Beskrivning
Föredragen strukturell selektor. Expanderas till språköverskridande AST-nodtyper — functions (funktions-/pil-/metoddefinitioner över språk); classes (class-/struct-/impl-definitioner); methods (metoddefinitioner, samt function_definition för språk utan metodnod); imports (import-/use-/include-satser); variables (variable-/let-/const-/static-deklarationer). Föredra framför fritt pattern/node_type för browse-liknande frågor.
patternValfri
Typ
str
Beskrivning
Free-form-mönster när presets är för grova (identifieras automatiskt: 'def foo(' → node_type + name_pattern). Föredra preset= för browse-frågor.
name_patternValfri
Typ
str
Beskrivning
Symbolnamnsmönster (skal-wildcard, avgränsat POSIX-regex eller fuzzy-text; max 256 tecken)
node_typeValfri
Typ
str
Beskrivning
AST-nodtyp (function_definition, class_definition med mera) — föredra preset= för vanliga former
decoratorValfri
Typ
str
Beskrivning
Filter för dekoratornamn
base_classValfri
Typ
str
Beskrivning
Basklassfilter
language_filterValfri
Typ
str
Beskrivning
Språkfilter (python, typskript, etc.)
limitValfri
Typ
int
Standard
20
Beskrivning
Max antal resultat som returneras på denna sida
offsetValfri
Typ
int
Beskrivning
Föråldrad kompatibilitets-offset. Föredra cursor från pagination.next_cursor.
cursorValfri
Typ
str
Beskrivning
Ogenomskinlig cursor från pagination.next_cursor. Skicka den oförändrad och håll query och filter oförändrade.
path_filterValfri
Typ
str
Beskrivning
Filtrera efter filsökvägsprefix
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
query_typeValfri
Typ
Literal[node_type, name_pattern, parent_child]
Beskrivning
Explicit frågetyp
parent_typeValfri
Typ
str
Beskrivning
Förälder AST nodtyp filter
relationshipValfri
Typ
Literal[parent, ancestor]
Standard
parent
Beskrivning
För parent_child-frågor: endast direkt överordnad, eller valfri förfader (använd förfader för klassmetoder kapslade under en klasskropp/-block)
has_modifierValfri
Typ
str
Beskrivning
Filtrera efter modifierare (export, asynkron, statisk, etc.)
advancedValfri
Typ
bool
Standard
Beskrivning
Ställ in true när du avsiktligt använder avancerade sökvägs-, ltree- eller anropsfilter (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Som standard håller false agentgränssnittet fokuserat på förinställningar. Avancerade nycklar i platt format fungerar fortfarande för bakåtkompatibilitet, med en metadatavarning.
callee_textValfri
Typ
str
Beskrivning
Avancerat — föredra preset=functions|classes|methods|imports|variables. Filter för callee-text i ett anropsuttryck. Sätt advanced=true när du avsiktligt använder path-/ltree-/call-filter.
callee_nameValfri
Typ
str
Beskrivning
Avancerat — föredra preset=functions|classes|methods|imports|variables. Filter för callee-namn i ett anropsuttryck. Sätt advanced=true när du avsiktligt använder path-/ltree-/call-filter.
field_roleValfri
Typ
str
Beskrivning
Avancerat — föredra preset=functions|classes|methods|imports|variables. Filter för AST-fältroll. Sätt advanced=true när du avsiktligt använder path-/ltree-/call-filter.
ltree_ancestorValfri
Typ
str
Beskrivning
Avancerat — föredra preset=functions|classes|methods|imports|variables. Filter för AST-ltree-förfaderväg. Sätt advanced=true när du avsiktligt använder path-/ltree-/call-filter.
ltree_descendantValfri
Typ
str
Beskrivning
Avancerat — föredra preset=functions|classes|methods|imports|variables. Filter för AST-ltree-avkomlingsväg. Sätt advanced=true när du avsiktligt använder path-/ltree-/call-filter.
definition_nameValfri
Typ
str
Beskrivning
Avancerat — föredra preset=functions|classes|methods|imports|variables. Filter för definitionsnamn. Sätt advanced=true när du avsiktligt använder path-/ltree-/call-filter.
min_depthValfri
Typ
int
Beskrivning
Avancerat — föredra preset=functions|classes|methods|imports|variables. Minsta AST-djup. Sätt advanced=true när du avsiktligt använder path-/ltree-/call-filter.
max_depthValfri
Typ
int
Beskrivning
Avancerat — föredra preset=functions|classes|methods|imports|variables. Högsta AST-djup. Sätt advanced=true när du avsiktligt använder path-/ltree-/call-filter.

Bäst för:

  • Struktur på AST-nivå: classes, decorators, function-/method-presets
  • Hitta kod efter form snarare än efter text

Rekommenderas inte för:

  • Fritext eller konceptuella frågor — använd semantic_search eller intelligent_search

dependency_searchStabil

Primärt påverkansradie-/grafverktyg. Svarar på "vad anropar detta?" / "vad använder detta?" via den verkliga anrops-/importgrafen. För påverkan före ändring: analysis_type="dependents" eller analysis_type="impact" (inkommande, shallow som standard för impact), include_metrics=false som standard (aktivera valfritt för centrality + refactor_risk). PR-/diff-påverkan (P1-8): skicka changed_paths och/eller patch (unified diff) — löser symboler per sökväg och returnerar en kompakt, grunt inkommande dependents-nyttolast utan att kräva ett symbolnamn. Sätt efter en ändring verify_after_edit=true med targets och/eller changed_paths för en kompakt multi-root-omfrågning av påverkade symboler. Stöder även dependencies, centrality och orphans. analyze_dependencies är ett tunt alias för impact-vägen — föredra detta verktyg för nya agenter.

Parametrar:

repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
queryValfri
Typ
str
Beskrivning
Symbolnamn eller sökterm
targetValfri
Typ
str
Beskrivning
Symbolnamn (alias för fråga)
changed_pathsValfri
Typ
list[str]
Beskrivning
Repo-relativa sökvägar för PR/diff-påverkan (standard) eller, med verify_after_edit=true, verifiera rötter efter redigering. PR/diff: löser symboler per bana och går grunda inkommande anhöriga; kan kombineras med patch=. Verifiera: löser upp till 5 symboler per sökväg som verifieringsrötter (begränsat lägre i verifieringsläget). Kräver inte query/target för PR/diff-påverkan.
patchValfri
Typ
str
Beskrivning
PR/diff inverkan: unified diff / git patch text. Sökvägar analyseras från diff --git / --- / +++ rubriker; samma kompakta stötbana som changed_paths.
analysis_typeValfri
Typ
Literal[centrality, dependencies, dependents, impact, orphans]
Standard
dependencies
Beskrivning
Analysläge. impact = påverkansradie (inkommande dependents; shallow djup när depth utelämnas). dependents besvarar också impact. När changed_paths eller patch är satt tvingas analysen till PR-/diff-impact. centrality/orphans kräver inget target.
depthValfri
Typ
Literal[shallow, balanced, deep]
Standard
balanced
Beskrivning
Traverseringsdjup. För analysis_type=impact och PR-/diff-impact är standardvärdet effektivt shallow om du inte anger depth explicit.
limitValfri
Typ
int
Standard
20
Beskrivning
Max antal resultat som returneras på denna sida
offsetValfri
Typ
int
Beskrivning
Föråldrad kompatibilitets-offset. Föredra cursor från pagination.next_cursor.
cursorValfri
Typ
str
Beskrivning
Ogenomskinlig cursor från pagination.next_cursor. Skicka den oförändrad och håll query och filter oförändrade.
path_filterValfri
Typ
str
Beskrivning
Begränsar upplösningen av målsymbolen till ett filsökvägsprefix; returnerade grafrelationer kan sträcka sig utanför den sökvägen
language_filterValfri
Typ
str
Beskrivning
Filtrerar målupplösning och browse-resultat efter språk
directionValfri
Typ
Literal[outgoing, incoming, both]
Beskrivning
Traverseringsriktning (åsidosätter analysis_type slutledning)
relationship_typesValfri
Typ
list[str]
Beskrivning
Filtrerar kanttyper (CALL, IMPORT, INHERITS_FROM med mera). En icke-tom lista åsidosätter graph_view-standardvärden.
exclude_test_pathsValfri
Typ
bool
Standard
true
Beskrivning
Standard true: exkluderar test-, fixture-, vendor- och exempelsökvägar från traverserings- och centralitetsresultat. Sätt false för att inkludera dem. Orphan-analysen tillämpar alltid sina egna strängare brusexkluderingar.
exclude_generated_pathsValfri
Typ
bool
Standard
Beskrivning
Uteslut genererade deklarationer plus build, täckning, cache, källkarta och minifierade artefaktvägar från genomgångsresultat
include_module_symbolsValfri
Typ
bool
Standard
Beskrivning
Som standard utesluter false grafkanter när from_name eller to_name är den syntetiska __module__-symbolen (brus på modulnivå). Ställ in true för att inkludera kanter på modulnivå i resultat för beroende- och beroenderelationer.
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
per_hop_limitValfri
Typ
int
Beskrivning
Max antal relationer per hop (1-300)
include_metricsValfri
Typ
bool
Standard
Beskrivning
Valfria grafmetriker på resultatrader (komprimerade med refactor_risk). Metriker hämtas även internt när min_centrality>0 men returneras bara om detta är true.
metrics_detailValfri
Typ
Literal[summary, full]
Standard
summary
Beskrivning
När include_metrics=true: summary (standard) returnerar beslutssignaler + refactor_risk; full returnerar den större kurerade metriska uppsättningen
include_edge_metadataValfri
Typ
bool
Standard
Beskrivning
Inkludera rå kantmetadata och vikter (stora). Kompakt nyttolaster lämnar detta.
symbol_typesValfri
Typ
list[str]
Beskrivning
Filtrerar returnerade symboler efter typ (function, class, method med mera)
exact_matchValfri
Typ
bool
Standard
Beskrivning
Kräv exakt matchning av symbolnamn
find_similar_patternsValfri
Typ
bool
Standard
Beskrivning
Hitta liknande användningsmönster
min_centralityValfri
Typ
float
Standard
0
Beskrivning
Lägsta PageRank-poäng. Metriker hämtas internt för filtrering; graph_metrics returneras endast när include_metrics=true.
graph_viewValfri
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beskrivning
Grafvy som används för traverseringsrelationers standardvärden, metriker och centralitetsrankning; orphan-analys beräknas över alla vyer
verify_after_editValfri
Typ
bool
Standard
Beskrivning
P2-7 verifieringsläge efter redigering: fråga om den indexerade effektgrafen för nyligen redigerade symboler i ett kompakt svar med flera rotar. Kräver targets och/eller changed_paths (eller target/query). Standard för ytliga inkommande anhöriga; resultaten återspeglar den indexerade grafen (kan släpa efter liveredigeringar). När sant, har företräde framför PR/diff påverkan på samma changed_paths.
targetsValfri
Typ
list[str]
Beskrivning
När verify_after_edit=true: symbolnamn att återverifiera (uppringare/beroende). Slås samman med target/query om båda medföljer.

Bäst för:

  • Påverkansradie-/konsekvensanalys innan du redigerar en delad symbol
  • PR-/diff-påverkan via changed_paths eller patch
  • Verifiering efter redigering via verify_after_edit

Rekommenderas inte för:

  • Enkla text- eller symboluppslagningar — använd text_pattern_search eller find_symbol

Kodanalysverktyg#

find_symbolStabil

Hoppa till där en funktion, klass eller variabel definieras och används. Använd när du känner till namnet (t.ex. "getCurrentUser") - snabbare och mer exakt än Grep, och det sträcker sig över hela den indexerade repan. Returnerar valfritt referenser och viktmätvärden.

Parametrar:

symbol_nameValfri
Typ
str
Beskrivning
Symbolnamn att söka efter (valfritt – utelämna för att bläddra efter mätvärden)
repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
scopeValfri
Typ
Literal[definitions, references, both]
Standard
both
Beskrivning
Sökomfång
limitValfri
Typ
int
Standard
15
Beskrivning
Max antal resultat som returneras på denna sida
offsetValfri
Typ
int
Beskrivning
Föråldrad kompatibilitets-offset. Föredra cursor från pagination.next_cursor.
cursorValfri
Typ
str
Beskrivning
Ogenomskinlig cursor från pagination.next_cursor. Skicka den oförändrad och håll query och filter oförändrade.
find_similarValfri
Typ
bool
Standard
Beskrivning
Inkludera liknande symbolnamn
include_metricsValfri
Typ
bool
Standard
Beskrivning
Inkludera centralitetsmått
metrics_detailValfri
Typ
Literal[summary, full]
Standard
summary
Beskrivning
När include_metrics=true: summary (standard) returnerar beslutssignaler + refactor_risk; full returnerar den större kurerade metriska uppsättningen
path_filterValfri
Typ
str
Beskrivning
Filtrera efter filsökvägsprefix
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
symbol_typeValfri
Typ
Literal[function, class, variable, method, constant, module, interface, type]
Beskrivning
Filtrera efter symboltyp
high_impactValfri
Typ
bool
Standard
Beskrivning
Bläddra bland arkitektoniskt viktiga symboler (utelämna symbol_name). Standardläget är popularity (högsta PageRank-decilen minus utility-megahubbar). Sätt high_impact_mode=risk för artikulations-/bridge-skärningspunkter.
high_impact_modeValfri
Typ
Literal[popularity, risk]
Standard
popularity
Beskrivning
När high_impact=true: popularitet = topp PageRank decil minus verktyg mega-hubbar/moduler; risk = artikulationspoäng rankade efter SMV bridge_count sedan k_core (strukturell refaktorrisk, inte navpopularitet)
in_cycleValfri
Typ
bool
Standard
Beskrivning
Filtrera till symboler i beroendecykler
exclude_test_pathsValfri
Typ
bool
Standard
true
Beskrivning
När du bläddrar efter grafstatistik, uteslut tester, fixtures, tredjepartskod och exempel före rankning. Uppslag med en namngiven symbol är oförändrad.

Bäst för:

  • Slå fast en känd symbols definition, referenser och grafmätvärden
  • Bläddra efter centrality, high_impact eller in_cycle när symbol_name utelämnas

Rekommenderas inte för:

  • Konceptuella frågor eller frågor inom ett okänt område — använd intelligent_search eller semantic_search

analyze_dependenciesStabil

Alias för påverkansradie via dependency_search (dependents/incoming). Föredra dependency_search med analysis_type="dependents" eller "impact" för nya agenter. Behåller den äldre multi-hop impact-svarsformen (graph, connection_summary, valfria metriker med refactor_risk). Använd graph_view för att avgränsa relationsfamiljen: dependency (standard), type, data_flow, control_flow.

Parametrar:

repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
targetObligatorisk
Typ
str
Beskrivning
Symbolnamn att analysera
depthValfri
Typ
Literal[shallow, balanced, deep]
Standard
balanced
Beskrivning
Analysdjup
limitValfri
Typ
int
Standard
10
Beskrivning
Max antal resultat som returneras på denna sida
offsetValfri
Typ
int
Beskrivning
Föråldrad kompatibilitets-offset. Föredra cursor från pagination.next_cursor.
cursorValfri
Typ
str
Beskrivning
Ogenomskinlig cursor från pagination.next_cursor. Skicka den oförändrad och håll query och filter oförändrade.
directionValfri
Typ
Literal[incoming, outgoing, both]
Standard
incoming
Beskrivning
Traverseringsriktning
relationship_typesValfri
Typ
list[str]
Beskrivning
Filterkanttyper (CALL, IMPORT, INHERITS_FROM, etc.). Åsidosätter alltid den graph_view-härledda standarden nedan när den levereras.
graph_viewValfri
Typ
Literal[dependency, type, data_flow, control_flow]
Standard
dependency
Beskrivning
Grafvy: bestämmer både standardtyperna för tvärgående kant och vilken vys mätvärden som används när include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (standard), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Används endast som relationship_types-standard när relationship_types inte uttryckligen tillhandahålls. Matchar dependency_search:s befintliga graph_view-parameternamn för konsekvens mellan verktyg.
path_filterValfri
Typ
str
Beskrivning
Begränsar upplösningen av målsymbolen till ett filsökvägsprefix; returnerade grafrelationer kan sträcka sig utanför den sökvägen
language_filterValfri
Typ
str
Beskrivning
Språkfilter
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
per_hop_limitValfri
Typ
int
Beskrivning
Max antal relationer per hop (1-300)
include_metricsValfri
Typ
bool
Standard
Beskrivning
Inkludera grafstatistik i resultaten, var och en berikad med ett härlett refactor_risk-block ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risken är "low" när den inte är en artikulationspunkt (i den valda vyn), "medium" när en artikulationspunkt överbryggar få kanter, "high" när den överbryggar många (heuristisk tröskel, ej empiriskt validerad). Utelämnad per symbol när det inte finns någon mätvärdesrad för den symbolen/vyn.
metrics_detailValfri
Typ
Literal[summary, full]
Standard
summary
Beskrivning
När include_metrics=true: summary (standard) returnerar beslutssignaler + refactor_risk; full returnerar den större kurerade metriska uppsättningen
include_edge_metadataValfri
Typ
bool
Standard
Beskrivning
Inkludera rå kantmetadata och vikter. Inaktiverad som standard eftersom extraheringsmetadata kan vara stora; anrikningstäckning rapporteras när den är aktiverad.
exclude_test_pathsValfri
Typ
bool
Standard
true
Beskrivning
Standard true: exkludera test-, fixtur-, leverantörs- och exempelsökvägar från returnerade grafkanter. Ställ in false för att inkludera dem.
include_module_symbolsValfri
Typ
bool
Standard
Beskrivning
Som standard utesluter false grafkanter när from_name eller to_name är den syntetiska __module__-symbolen. Ställ in true för att inkludera kanter på modulnivå.

Bäst för:

  • Äldre anropare som redan är kopplade till dess svarsform (graph, connection_summary)

Rekommenderas inte för:

  • Nya agentloopar — föredra dependency_search, som delar samma traverseringskärna

get_task_contextStabil

Börjar du arbeta i ett okänt område? Beskriv uppgiften (t.ex. "lägg till SSO-stöd", "fixa faktureringswebbhooken") och få tillbaka ett begränsat paket med relevanta filer, kod, symboler och beroenden i ett enda anrop. Seed-filer bidrar med direkt indexerat innehåll även när de inte definierar några symboler. För fler resultat, fortsätt med det specialiserade sökverktyget för det lagret.

Parametrar:

task_descriptionObligatorisk
Typ
str
Beskrivning
Beskrivning av uppgiften du behöver sammanhang för
repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
limitValfri
Typ
int
Standard
15
Beskrivning
Maximalt antal resultat per lager
scopeValfri
Typ
Literal[semantic, symbols, dependencies, all]
Standard
all
Beskrivning
Vilka kontextlager som ska inkluderas
language_filterValfri
Typ
str
Beskrivning
Språkfilter
path_filterValfri
Typ
str
Beskrivning
Filtrera efter filsökvägsprefix
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
include_related_contextValfri
Typ
bool
Standard
Beskrivning
Inkludera relaterad kontext från intilliggande symboler
seed_symbol_idsValfri
Typ
list[str]
Beskrivning
Nivå-1 explicita frön: symbol-ID:n som agenten redan vet är centrala för uppgiften (t.ex. symboler i filer som den har öppna). Placerad före nyckelordshärledda frön i beroenden/related_context-lagren. Tillsats — utelämna för dagens beteende med enbart nyckelord.
seed_file_pathsValfri
Typ
list[str]
Beskrivning
Tier-1-explicita seeds: indexerade filsökvägar som agenten har öppna eller just har redigerat. Returnerar begränsade direkta filbevis och löser upp till 5 symboler per fil för grafkontext, inklusive symbolfri dokumentation och konfiguration. Additivt — utelämna för enbart nyckelordsbeteende.

Bäst för:

  • Uppgiftsmedveten kontext som blandar seed-filer med semantiska, symbol- och beroendelager

Rekommenderas inte för:

  • Uppslagningar med ett enda verktyg där ett mer specifikt verktyg redan besvarar frågan

get_fileStabil

Läser en fil från det indexerade repot efter sökväg. Föredra det lokala Read-verktyget för filer på disk — använd detta för uppslag i andra repon eller på distans när filen inte finns i ditt arbetsträd. Stöder ett valfritt radintervall; fortsätt ett token-avkapat svar från metadata.next_line_start.

Parametrar:

file_pathObligatorisk
Typ
str
Beskrivning
Filsökväg i förhållande till arkivroten
repositoryValfri
Typ
str
Beskrivning
Repo som owner/repo[:branch]. Valfritt — utelämna för att använda klientens anropsspecifika standardrepo (om ett sådant anges) eller det enda tillgängliga repot; ange det uttryckligen bara för att välja ett annat indexerat repo. Svaret visar vilket repo som användes.
line_startValfri
Typ
int
Beskrivning
Startrad (1-indexerad)
line_endValfri
Typ
int
Beskrivning
Slutrad (1-indexerad, inklusive; måste vara vid eller efter line_start)
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
max_tokensValfri
Typ
int
Standard
5000
Beskrivning
Maximalt antal tokens att returnera
include_metadataValfri
Typ
bool
Standard
true
Beskrivning
Inkludera filmetadata som svar

Bäst för:

  • Fjärr- eller indexerade filsnapshots (radintervall, tokengränser)

Rekommenderas inte för:

  • En sökväg som redan finns på lokal disk — använd det lokala Read-verktyget

System- och hjälpverktyg#

repository_contextStabil

Listar de repon du kan söka i, eller hämtar identitetsinformation om ett (namespace/branch, indexed_commit_sha / indexets aktualitet). Anropa action:"list" en gång för att se den exakta repo-slug som sökverktygen accepterar. (Om din nyckel bara har ett repo använder sökverktygen det som standard — då kan du hoppa över detta.) Namespace-omfattande antal filer/blobbar/kanter är valfritt via include_statistics=true.

Parametrar:

actionObligatorisk
Typ
Literal[list, info]
Beskrivning
Åtgärd: lista tillgängliga repo med list eller hämta repoinformation med info
repositoryValfri
Typ
str
Beskrivning
Repository i formatet owner/repo eller owner/repo:branch (krävs för info)
branchValfri
Typ
str
Beskrivning
Grenöverstyrning
patternValfri
Typ
str
Beskrivning
Filtrera förrådslistan efter mönster
include_statisticsValfri
Typ
bool
Standard
Beskrivning
Opt-in: inkluderar namespace-omfattande antal indexerad data (fil/blob/kant). Standard false — repots identitet kräver inte detta långsammare aggregat.
limitValfri
Typ
int
Standard
20
Beskrivning
Max antal resultat som returneras på denna sida
offsetValfri
Typ
int
Beskrivning
Utfasad kompatibilitetsoffset. Föredrar cursor från pagination.next_cursor.
cursorValfri
Typ
str
Beskrivning
Opak cursor från pagination.next_cursor. Skicka den oförändrad och behåll frågan och filtren oförändrade.

Bäst för:

  • Lista tillgängliga repon
  • Fastställa repo-identitet, branch och HEAD-kontra-index-aktualitet

Rekommenderas inte för:

  • Namespace-omfattande statistik som standard — skicka include_statistics=true explicit, eftersom det kan vara långsammare än upplösning

ask_maguyvaStabil

Hjälp och feedback för Maguyva. Primärt: få verktygsvägledning, eller skicka in en felrapport / funktionsförfrågan som sparas för Maguyvas underhållare. Inkludera aldrig hemligheter eller känsliga personuppgifter i feedback. operationen evaluate finns kvar endast för bakåtkompatibilitet — föredra lokal beräkning eller värdverktyg för matte-/hash-/strängarbete.

Parametrar:

operationObligatorisk
Typ
Literal[guidance, report_bug, request_feature, evaluate]
Beskrivning
Primärt: guidance, report_bug, request_feature. Endast legacy/kompatibilitet: evaluate (deterministisk uttrycksmotor; inte en del av det primära agentarbetsflödet).
queryValfri
Typ
str
Beskrivning
Vägledningsämne (t.ex. tool_selection, semantic_search). Endast för legacy evaluate: uttrycksträng.
descriptionValfri
Typ
str
Beskrivning
Krävs för report_bug och request_feature. Free-form-feedback för Maguyva-underhållare. Inkludera aldrig hemligheter eller känsliga personuppgifter.
related_toolValfri
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]
Beskrivning
Valfritt Maguyva-verktyg som är närmast relaterat till feedbacken

Bäst för:

  • Verktygsvägledning (operation="guidance")
  • Beständiga felrapporter och funktionsförfrågningar för underhållarna av Maguyva

Rekommenderas inte för:

  • Matte-/hash-/strängberäkningar — operationen evaluate är endast för bakåtkompatibilitet; föredra lokal värdberäkning

Bästa praxis#

  1. Använd explicita åsidosättanden medvetet: Utelämna repot när MCP-klienten anger ett anropsspecifikt standardrepo eller när nyckeln har åtkomst till exakt ett repo; ange det annars uttryckligen.
  2. Välj rätt sökläge: Använd intelligent_search med mode="auto" i de flesta fall. Ange ett läge när du vet exakt vad du behöver.
  3. Utnyttja språkfilter: Använd language_filter för att begränsa resultat och förbättra prestanda.
  4. GraphRAG Boosting: GraphRAG-viktökning är avstängd som standard för semantisk sökning (boost_by_importance=false) för att hålla rankningen agentsäker. Skicka boost_by_importance=true för att aktivera centralitetsmedveten omrankning för arkitekturgenomgångar.
  5. Repository-matchning är skiftlägesokänslig, inte luddig: repository_context matchar repositorynamn utan hänsyn till skiftläge — det rättar inte stavfel. Kontrollera metadata.resolution_reason på info-åtgärden ("exact" jämfört med "corrected") för att se hur ett namn matchades.
  6. Kombinera verktyg: Använd flera API-metoder tillsammans för omfattande analys.
  7. Hantera stora resultat: Använd limit och verktygsspecifika pagineringskontroller (till exempel line_start/line_end i get_file).
  8. Använd ask_maguyva för verktygsvägledning: ask_maguyvas evaluate-åtgärd (hash, base64, JSON, matematik) är endast legacy / för bakåtkompatibilitet. Anropa istället ask_maguyva med operation="guidance" och query="tool_selection" för local-tool-wins-matrisen och en fullständig verktyg-för-verktyg-guide.
  9. Verifiera påverkan före och efter redigering: Innan du redigerar en delad symbol, anropa dependency_search med analysis_type="impact" (eller skicka changed_paths för PR-/diff-påverkan) för att se dess påverkansradie. Efter redigering, sätt verify_after_edit=true med targets och/eller changed_paths för en kompakt omkontroll av samma symboler.

Prestandaegenskaper#

ÅtgärdPrestandaanteckningar
Semantisk sökningUnder en sekund, men innehåller varje gång ett live-anrop till embedding-API:et (cachas inte) — räkna med extra latens utöver vektorfrågan
TextsökningUnder en sekund för exakt/regex; luddig fritextsökning sidnumreras klientsidan, så djupa offset kostar mer — begränsa med path_filter/language_filter
Strukturell sökningAST-indexerad — kostnaden skalar med resultatvolymen, inte med repositorystorleken
BeroendesökningKostnaden skalar med djupet — föredra depth="shallow" om du inte behöver kontext med flera hopp; per_hop_limit begränsar spridningen
FilhämtningNästan omedelbart för en enskild fil — dela upp stora filer med line_start/line_end eller max_tokens istället för en stor hämtning
Repository-kontextNamnrymdsupplösning cachas endast per anrop, inte mellan anrop — varje verktygsanrop löses upp igen
ask_maguyva (guidance / evaluate)Nästan omedelbart — körs in-Worker utan databasanrop

Felhantering#

Alla API-metoder returnerar ett strukturerat svarskuvert:

  • status: Sträng — "success" eller "error". Signaler om försämrad matchning eller aktualitet finns i nästlade fält som metadata.resolution_reason för repository_context eller metadata.index_freshness.status.
  • tool: Namnet på verktyget som genererade svaret
  • data: Resultatdata vid lyckat anrop (strukturen varierar per verktyg)
  • error: Strukturerat felobjekt när status är "error" — inkluderar type, message, suggestions och recovery_actions
  • metadata: Ytterligare information om operationen (routning, cachning, parameterjusteringar)
  • pagination: Finns på listsvar — inkluderar has_more och next_cursor

Kontrollera alltid fältet status innan du bearbetar resultat — det är alltid antingen "success" eller "error". För signaler om försämrad matchning eller aktualitet, läs istället det nästlade fältet: metadata.resolution_reason för repository_context, eller metadata.index_freshness.status (known/partial/unknown/unavailable).

Kom igång#

  1. Konfigurera MCP-klienten: Rikta MCP-klienten till Maguyva-serverns slutpunkt
  2. Bekräfta repoåtkomst: Använd repository_context med "list" eller "info" för att granska repon som API-nyckeln har åtkomst till
  3. Börja söka: Börja med intelligent_search och utforska specialiserade verktyg efter behov
  4. Kombinera verktyg: Använd flera verktyg tillsammans för en heltäckande kodanalys

För detaljerade integrationsinstruktioner, se installationsguide.