Lumaktaw papunta sa content

Sanggunian sa MCP API

Kumpletong sanggunian para sa lahat ng 11 MCP tool ng Maguyva na para sa mga customer. Kasama sa bawat tool ang mga parameter, gabay sa paggamit, at mga rekomendasyon kung kailan ito pinakamainam gamitin.

Buod ng API#

Kasalukuyang naglalantad ang Maguyva MCP API ng 11 tool para sa mga customer sa 4 pangunahing kategorya:

  • Mga Pangunahing Search Tool - Advanced na kakayahan sa paghahanap sa buong codebase mo
  • Mga Structural at Graph Tool - Mga AST query, paghahanap ng simbolo, at pagsusuri ng dependency
  • Mga Code Analysis Tool - Malalim na code analysis at relationship mapping
  • Mga System at Utility Tool - Repository context, deterministic compute, at gabay

Lahat ng tool ay gumagamit ng consistent na format ng repository identifier: "owner/repo:branch". Nagde-default sa main ang branch kung hindi ito specified.

Alisin ang repository kapag nagbibigay ang iyong MCP client ng request default o eksaktong isang repository lang ang maa-access ng key; kung hindi, tahasan itong ipasa. Gamitin ang repository_context(action="info", repository="owner/repo") upang makita kung paano nireresolba ang isang repository.

Format ng Repository Parameter#

Ginagamit ng lahat ng MCP tool ang repository identifier format na ito:

  • May branch: "owner/repo:branch" - hal., "owner/repository:develop"
  • Default na branch: "owner/repo" - gumagamit ng main branch kapag walang tinukoy na branch "owner/repository"
  • Default ng request o nag-iisang repository: Alisin ang repository kapag nagbibigay ang MCP client ng request default o eksaktong isang repository lang ang maa-access ng key; kung hindi, tahasan itong ipasa

Mga halimbawang prompt:

Magtanong tungkol sa partikular na repo:  "Search owner/my-repo for authentication middleware"
Ilista ang accessible na repo:            "Anong mga repository ang maaaring i-access ng Maguyva key na ito?"
I-override para sa isang query lang:      "Search owner/other-repo:develop for auth patterns"

Pag-filter ng Language#

Sinusuportahan ng lahat ng search tool ang pag-filter ng resulta ayon sa programming language:

  • language_filter="python" - I-filter lang sa mga Python file
  • language_filter="typescript" - I-filter lang sa mga TypeScript file
  • Sensitibo sa case: Gumamit ng lowercase na pangalan ng wika
  • Karaniwan: Walang laman na string (walang filtering) - nagbabalik ng resulta mula sa lahat ng wika
  • Sinusuportahang coverage: Gumagana ang mga language filter sa kabuuang 279+ na suportadong mga wika at teknolohiyang batay sa text. Tingnan ang compatibility para sa buong listahan.
"Hanapin ang authentication middleware sa Python files lang"
"Maghanap ng database connections sa TypeScript"

Ang API reference ay ginawa mula sa source noong Hulyo 22, 2026.

Mga Pangunahing Search Tool#

intelligent_searchMatatag

Magsimula dito para sa anumang tanong sa codebase. Bigyan ito ng query sa natural na wika (hal. "paano gumagana ang auth", "saan pinangangasiwaan ang pagsingil") at nag-auto-ruta ito sa paghahanap ng semantiko, simbolo, istruktura, at dependency ng na-index na repo. Mas gusto ito kaysa sa ahente ng Explore at Grep/Glob para sa paggalugad at pagpaplano — hinanap nito ang buong na-index na repo nang sabay-sabay sa halip na mag-scan ng mga file.

Mga Parameter:

queryKailangan
Uri
str
Paglalarawan
Query para sa paghahanap
repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
modeOpsyonal
Uri
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Default
auto
Paglalarawan
Mode ng paghahanap
limitOpsyonal
Uri
int
Default
10
Paglalarawan
Max na bilang ng resulta sa ranked top-K window na ito
language_filterOpsyonal
Uri
str
Paglalarawan
Filter ayon sa wika
path_filterOpsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
boost_by_importanceOpsyonal
Uri
bool
Default
Paglalarawan
Opsyonal: i-re-rank ayon sa centrality gamit ang per-symbol graph metrics (is_articulation_point, bridge_count, k_core, centrality, atbp.). Naka-off ito bilang default para sa agent-safe na ranking (maaaring malunod ng mga global hub ang implementation hits); i-enable para sa architecture tours. Applicable sa lahat ng 4 modalities kapag may symbol linkage ang bawat resulta.
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
qualityOpsyonal
Uri
Literal[quick, balanced, thorough]
Default
balanced
Paglalarawan
Kalidad ng paghahanap
include_contentOpsyonal
Uri
bool
Default
true
Paglalarawan
Isama ang content sa mga resulta
explain_routingOpsyonal
Uri
bool
Default
Paglalarawan
Isama ang paliwanag sa desisyon sa routing
importance_weightOpsyonal
Uri
float
Default
0.3
Paglalarawan
Bigat para sa importance boosting (0=wala, 1=buo)
orphansOpsyonal
Uri
bool
Default
Paglalarawan
Ibinabalik ang mga symbol na walang incoming reference (posibleng dead code). Kapaki-pakinabang para sa cleanup pero maaaring kasama ang mga decorator, inner function, o CLI entry point.
include_community_contextOpsyonal
Uri
bool
Default
Paglalarawan
Isama ang mga related symbol mula sa parehong code community para sa mas malawak na context. Kapaki-pakinabang kapag tinutuklas kung paano gumagana ang isang feature o module.
community_depthOpsyonal
Uri
int
Default
1
Paglalarawan
Lalim ng pagpapalawak ng community context
graph_viewOpsyonal
Uri
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Paglalarawan
Graph view para sa mga metric
seed_symbol_idsOpsyonal
Uri
list[str]
Paglalarawan
Tier-1 na panimulang simbolo para sa gawain: mga ID ng simbolong mahalaga sa kasalukuyang gawain. Kapag itinakda, muling niraranggo ang pinagsamang resulta ayon sa lapit ng depth-decay ng Approach A (eksaktong tugma sa panimulang simbolo at mga hakbang sa graph edge). Karagdagan lamang ito — alisin para sa pangkalahatang ranggo.
seed_file_pathsOpsyonal
Uri
list[str]
Paglalarawan
Tier-1 na panimulang file para sa gawain: mga naka-index na path ng file na binuksan o katatapos lang i-edit ng agent. Kapag itinakda, muling niraranggo ang pinagsamang resulta ayon sa lapit ng path gamit ang 1/(1+d) depth-decay (parehong file → parehong direktoryo → kalapit na package). Karagdagan lamang ito — alisin para sa pangkalahatang ranggo.

Pinakamainam Para sa:

  • Pagsusuri sa buong index o cold-start exploration kapag hindi malinaw kung alin ang tamang tool
  • Multi-modal na pinagsamang ranking sa semantiko, teksto, istruktura, at graph

Hindi Inirerekomenda Para sa:

  • Kilalang pangalan ng symbol — gamitin direkta ang find_symbol
  • Kilalang path na nasa disk — gamitin muna ang lokal na Read/Grep

semantic_searchMatatag

Maghanap ng code ayon sa kahulugan, hindi eksaktong teksto. Gamitin para sa mga haka-haka na query tulad ng "retry logic" o "user onboarding flow" kapag hindi mo alam ang keyword o pangalan ng simbolo. Ibinabalik ang pinakanauugnay na mga chunks ng code na niraranggo ayon sa kahalagahan. Mas gusto kaysa sa Grep kapag ang paghahanap ay konseptwal.

Mga Parameter:

queryKailangan
Uri
str
Paglalarawan
Search query (conceptual, batay sa kahulugan)
repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
limitOpsyonal
Uri
int
Default
5
Paglalarawan
Max na bilang ng resulta sa ranked top-K window na ito
similarity_thresholdOpsyonal
Uri
float
Default
0.6
Paglalarawan
Minimum na similarity score
language_filterOpsyonal
Uri
str
Paglalarawan
I-filter ang mga resulta sa mga file na na-detect bilang ang partikular na programming language na ito
path_filterOpsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
boost_by_importanceOpsyonal
Uri
bool
Default
Paglalarawan
Opsyonal: i-re-rank ayon sa PageRank centrality (naka-off bilang default para sa agent-safe na ranking; i-enable para sa architecture tours)
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch (default: mula sa repository parameter o main)
include_contentOpsyonal
Uri
bool
Default
true
Paglalarawan
Isama ang chunk content sa mga resulta
graph_viewOpsyonal
Uri
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Paglalarawan
Graph view para sa metrics

Pinakamainam Para sa:

  • Mga konseptwal na query (hal. "paano gumagana ang auth?", "caching strategy")
  • Similarity search sa iba't ibang package

Hindi Inirerekomenda Para sa:

  • Kilalang pangalan ng symbol — gamitin na lang ang find_symbol
  • Eksaktong strings o error messages — gamitin ang text_pattern_search

text_pattern_searchMatatag

Maghanap sa indexed content. Ang exact at regex mode ay nag-ge-grep sa buong file/blob corpus; ang fuzzy content mode ay naghahanap sa bounded semantic chunk corpus. Fuzzy-only ang file at symbol scopes. Gumamit ng lokal na Grep para sa maliit na directory na nasa disk na.

Mga Parameter:

queryKailangan
Uri
str
Paglalarawan
Pattern ng text
repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
modeOpsyonal
Uri
Literal[fuzzy, exact, regex]
Default
exact
Paglalarawan
Mode ng paghahanap
search_scopeOpsyonal
Uri
Literal[content, symbols, files]
Default
content
Paglalarawan
Ano ang hahanapin
limitOpsyonal
Uri
int
Default
5
Paglalarawan
Max na bilang ng resulta na ibinalik sa page na ito
offsetOpsyonal
Uri
int
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursorOpsyonal
Uri
str
Paglalarawan
Opaque cursor mula sa pagination.next_cursor. Ipasa nang hindi nagbabago at panatilihing pareho ang query at mga filter.
language_filterOpsyonal
Uri
str
Paglalarawan
Filter ayon sa wika
path_filterOpsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
case_sensitiveOpsyonal
Uri
bool
Default
Paglalarawan
Case sensitive (may pagkakaiba ang malaki't maliit na letra)
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
fuzzy_algorithmOpsyonal
Uri
Literal[hybrid, trigram, levenshtein]
Default
hybrid
Paglalarawan
Algorithm ng fuzzy matching
thresholdOpsyonal
Uri
float
Default
0.05
Paglalarawan
Pinakamababang similarity threshold para sa fuzzy search
semantic_fallbackOpsyonal
Uri
bool
Default
Paglalarawan
Bumalik sa semantic search kapag walang resulta

Pinakamainam Para sa:

  • Eksaktong strings, error messages, at regex
  • Trigram fuzzy matching para sa halos-tugmang teksto

Hindi Inirerekomenda Para sa:

  • Kilalang path na nasa disk — mas piliin ang lokal na Grep
  • Mga konseptwal na query — gamitin ang semantic_search

Mga Structural at Graph Tool#

structural_searchMatatag

Mas piliin ang preset=functions|classes|methods|imports|variables (o free pattern=). Hanapin ang code ayon sa AST shape (hindi text). Mid-tier na filters: name_pattern, node_type, decorator, parent_child. Advanced ang path/ltree/call filters — itakda ang advanced=true kapag sinasadya itong gamitin; tinatanggap pa rin ang flat advanced keys para sa back-compat. Magbigay ng kahit isang structural selector.

Mga Parameter:

repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
presetOpsyonal
Uri
Literal[functions, classes, methods, imports, variables]
Paglalarawan
Preferred na structural selector. Nag-e-expand sa cross-language AST node types — functions (function/arrow/method definitions sa iba't ibang language); classes (class/struct/impl definitions); methods (method definitions (at function_definition para sa mga language na walang method node)); imports (import/use/include statements); variables (variable/let/const/static declarations). Mas piliin ito kaysa sa free-form pattern/node_type para sa browse-style queries.
patternOpsyonal
Uri
str
Paglalarawan
Free-form pattern kapag masyadong coarse ang presets (auto-detected: 'def foo(' → node_type + name_pattern). Mas piliin ang preset= para sa browse queries.
name_patternOpsyonal
Uri
str
Paglalarawan
Symbol name pattern (shell wildcard, bounded POSIX regex, o fuzzy text; max 256 characters)
node_typeOpsyonal
Uri
str
Paglalarawan
AST node type (function_definition, class_definition, atbp.) — mas piliin ang preset= para sa common shapes
decoratorOpsyonal
Uri
str
Paglalarawan
Filter ayon sa pangalan ng decorator
base_classOpsyonal
Uri
str
Paglalarawan
Base class name filter (maghanap ng mga class na nag-i-inherit dito)
language_filterOpsyonal
Uri
str
Paglalarawan
Filter ayon sa wika
limitOpsyonal
Uri
int
Default
20
Paglalarawan
Max na bilang ng resulta na ibinalik sa page na ito
offsetOpsyonal
Uri
int
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursorOpsyonal
Uri
str
Paglalarawan
Opaque cursor mula sa pagination.next_cursor. Ipasa nang hindi nagbabago at panatilihing pareho ang query at mga filter.
path_filterOpsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
query_typeOpsyonal
Uri
Literal[node_type, name_pattern, parent_child]
Paglalarawan
Tiyak na uri ng query
parent_typeOpsyonal
Uri
str
Paglalarawan
Filter sa uri ng parent AST node
relationshipOpsyonal
Uri
Literal[parent, ancestor]
Default
parent
Paglalarawan
Para sa parent_child query: direktang parent lang, o alinmang ancestor (gamitin ang ancestor para sa class method na naka-nest sa class body/block)
has_modifierOpsyonal
Uri
str
Paglalarawan
I-filter ayon sa modifier (export, async, static, atbp.)
advancedOpsyonal
Uri
bool
Default
Paglalarawan
Itakda ang true kapag sinasadyang gumamit ng mga advanced na path, ltree, o mga filter ng tawag (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Bilang default, pinapanatili ng false ang interface ng ahente na nakatuon sa mga preset. Gumagana pa rin ang mga advanced na key sa flat format para sa backward compatibility, na may babala sa metadata.
callee_textOpsyonal
Uri
str
Paglalarawan
Advanced — mas piliin ang preset=functions|classes|methods|imports|variables. Call expression callee text filter. Itakda ang advanced=true kapag sinasadyang gamitin ang path/ltree/call filters.
callee_nameOpsyonal
Uri
str
Paglalarawan
Advanced — mas piliin ang preset=functions|classes|methods|imports|variables. Call expression callee name filter. Itakda ang advanced=true kapag sinasadyang gamitin ang path/ltree/call filters.
field_roleOpsyonal
Uri
str
Paglalarawan
Advanced — mas piliin ang preset=functions|classes|methods|imports|variables. AST field role filter. Itakda ang advanced=true kapag sinasadyang gamitin ang path/ltree/call filters.
ltree_ancestorOpsyonal
Uri
str
Paglalarawan
Advanced — mas piliin ang preset=functions|classes|methods|imports|variables. AST ltree ancestor path filter. Itakda ang advanced=true kapag sinasadyang gamitin ang path/ltree/call filters.
ltree_descendantOpsyonal
Uri
str
Paglalarawan
Advanced — mas piliin ang preset=functions|classes|methods|imports|variables. AST ltree descendant path filter. Itakda ang advanced=true kapag sinasadyang gamitin ang path/ltree/call filters.
definition_nameOpsyonal
Uri
str
Paglalarawan
Advanced — mas piliin ang preset=functions|classes|methods|imports|variables. Definition name filter. Itakda ang advanced=true kapag sinasadyang gamitin ang path/ltree/call filters.
min_depthOpsyonal
Uri
int
Paglalarawan
Advanced — mas piliin ang preset=functions|classes|methods|imports|variables. Minimum AST depth. Itakda ang advanced=true kapag sinasadyang gamitin ang path/ltree/call filters.
max_depthOpsyonal
Uri
int
Paglalarawan
Advanced — mas piliin ang preset=functions|classes|methods|imports|variables. Maximum AST depth. Itakda ang advanced=true kapag sinasadyang gamitin ang path/ltree/call filters.

Pinakamainam Para sa:

  • Structure sa AST level: classes, decorators, function/method presets
  • Paghahanap ng code batay sa hugis, hindi sa teksto

Hindi Inirerekomenda Para sa:

  • Plain-text o konseptwal na query — gamitin ang semantic_search o intelligent_search

dependency_searchMatatag

Primary na blast radius / graph surface. Sinasagot ang "ano ang tumatawag dito?" / "ano ang gumagamit nito?" gamit ang totoong call/import graph. Para sa impact bago mag-edit: analysis_type="dependents" o analysis_type="impact" (incoming, shallow ang default para sa impact), include_metrics=false bilang default (opt-in para sa centrality + refactor_risk). PR/diff impact (P1-8): magpasa ng changed_paths at/o patch (unified diff) — nire-resolve ang symbols per path at ibinabalik ang compact na shallow-incoming dependents payload nang hindi kailangan ng symbol name. Pagkatapos mag-edit, itakda ang verify_after_edit=true na may targets at/o changed_paths para sa compact na multi-root re-query ng mga apektadong symbol. Sinusuportahan din ang dependencies, centrality, at orphans. Isang thin alias ang analyze_dependencies para sa impact path — mas piliin ang tool na ito para sa mga bagong agent.

Mga Parameter:

repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
queryOpsyonal
Uri
str
Paglalarawan
Pangalan ng symbol o search term
targetOpsyonal
Uri
str
Paglalarawan
Pangalan ng symbol (alias para sa query)
changed_pathsOpsyonal
Uri
list[str]
Paglalarawan
Mga path na relatibo sa repo para sa epekto ng PR/diff (default), o mga panimulang punto ng pag-verify pagkatapos mag-edit kapag verify_after_edit=true. Para sa PR/diff: hinahanap ang mga simbolo sa bawat path at sinusundan ang mababaw na papasok na dependent; maaaring isama sa patch=. Para sa pag-verify: hanggang 5 simbolo bawat path ang ginagawang panimulang punto (mas mababa ang limitasyon sa mode na ito). Hindi kailangan ang query/target para sa epekto ng PR/diff.
patchOpsyonal
Uri
str
Paglalarawan
Epekto ng PR/diff: pinag-isang diff o git patch na teksto. Kinukuha ang mga path mula sa mga header na diff --git / --- / +++; ginagamit ang parehong pinaikling pagsusuri ng epekto gaya ng changed_paths.
analysis_typeOpsyonal
Uri
Literal[centrality, dependencies, dependents, impact, orphans]
Default
dependencies
Paglalarawan
Analysis mode. impact = blast radius (incoming dependents; shallow ang depth kapag hindi ibinigay ang depth). Sinasagot din ng dependents ang impact. Kapag naka-set ang changed_paths o patch, pinipilit maging PR/diff impact ang analysis. Hindi nangangailangan ng target ang centrality/orphans.
depthOpsyonal
Uri
Literal[shallow, balanced, deep]
Default
balanced
Paglalarawan
Traversal depth. Para sa analysis_type=impact at PR/diff impact, shallow ang effective default maliban kung tahasan mong itinakda ang depth.
limitOpsyonal
Uri
int
Default
20
Paglalarawan
Max na bilang ng resulta na ibinalik sa page na ito
offsetOpsyonal
Uri
int
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursorOpsyonal
Uri
str
Paglalarawan
Opaque cursor mula sa pagination.next_cursor. Ipasa nang hindi nagbabago at panatilihing pareho ang query at mga filter.
path_filterOpsyonal
Uri
str
Paglalarawan
Hinihigpitan ang target symbol resolution ayon sa file path prefix; maaaring lumagpas sa labas ng path na iyon ang ibinalik na graph relationships
language_filterOpsyonal
Uri
str
Paglalarawan
I-filter ang target resolution at browse results ayon sa language
directionOpsyonal
Uri
Literal[outgoing, incoming, both]
Paglalarawan
Direksyon ng traversal (pinapalitan ang inference ng analysis_type)
relationship_typesOpsyonal
Uri
list[str]
Paglalarawan
I-filter ang edge types (CALL, IMPORT, INHERITS_FROM, atbp.). Papalitan ng non-empty na list ang mga default ng graph_view.
exclude_test_pathsOpsyonal
Uri
bool
Default
true
Paglalarawan
Default na true: ibukod ang test, fixture, vendor, at example paths mula sa traversal at centrality results. Itakda ang false para isama ang mga ito. Palaging inilalapat ng orphan analysis ang sarili nitong mas mahigpit na noise exclusions.
exclude_generated_pathsOpsyonal
Uri
bool
Default
Paglalarawan
Ibukod ang mga nabuong deklarasyon kasama ang build, coverage, cache, source-map, at minified artifact path mula sa mga resulta ng traversal
include_module_symbolsOpsyonal
Uri
bool
Default
Paglalarawan
Bilang default, hindi kasama ng false ang mga gilid ng graph kapag ang from_name o to_name ay ang synthetic na simbolo ng __module__ (module-level na ingay). Itakda ang true na isama ang mga gilid sa antas ng module sa mga resulta para sa mga ugnayang umaasa at dependency.
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
per_hop_limitOpsyonal
Uri
int
Paglalarawan
Max na bilang ng relationships bawat hop (1-300)
include_metricsOpsyonal
Uri
bool
Default
Paglalarawan
Opt-in na graph metrics sa result rows (compacted kasama ang refactor_risk). Kino-fetch din internally ang metrics kapag min_centrality>0 pero hindi ito ibinabalik maliban kung true ito.
metrics_detailOpsyonal
Uri
Literal[summary, full]
Default
summary
Paglalarawan
Kapag ang include_metrics=true: summary (default) ay nagbabalik ng mga signal ng desisyon + refactor_risk; Ibinabalik ng full ang mas malaking na-curate na hanay ng sukatan
include_edge_metadataOpsyonal
Uri
bool
Default
Paglalarawan
Isama ang raw edge metadata at mga timbang (malaki). Ang mga compact na impact payload ay hindi ito ginagawa.
symbol_typesOpsyonal
Uri
list[str]
Paglalarawan
I-filter ang mga ibinalik na symbol ayon sa kind (function, class, method, atbp.)
exact_matchOpsyonal
Uri
bool
Default
Paglalarawan
Kailangan ng exact match sa pangalan ng symbol (case-insensitive). Dini-disable ang fuzzy matching
find_similar_patternsOpsyonal
Uri
bool
Default
Paglalarawan
Maghanap ng katulad na usage patterns
min_centralityOpsyonal
Uri
float
Default
0
Paglalarawan
Minimum na PageRank score. Kino-fetch internally ang metrics para sa filtering; ibinabalik lang ang graph_metrics kapag include_metrics=true.
graph_viewOpsyonal
Uri
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Paglalarawan
Graph view na ginagamit para sa traversal relationship defaults, metrics, at centrality ranking; kinakalkula ang orphan analysis sa lahat ng views
verify_after_editOpsyonal
Uri
bool
Default
Paglalarawan
P2-7 na mode ng pag-verify pagkatapos mag-edit: muling suriin ang naka-index na graph ng epekto para sa mga simbolong kamakailang na-edit sa isang maikling sagot na may maraming panimulang punto. Kailangan ang targets at/o changed_paths (o target/query). Default ang mababaw na papasok na dependent; maaaring mahuli sa aktuwal na edit ang naka-index na graph. Kapag true, inuuna ito kaysa epekto ng PR/diff sa parehong changed_paths.
targetsOpsyonal
Uri
list[str]
Paglalarawan
Kapag verify_after_edit=true: mga pangalan ng simbolong muling susuriin (mga caller/dependent). Isinasama sa target/query kung parehong ibinigay.

Pinakamainam Para sa:

  • Blast-radius / impact analysis bago i-edit ang isang shared symbol
  • PR/diff impact gamit ang changed_paths o patch
  • Post-edit verification gamit ang verify_after_edit

Hindi Inirerekomenda Para sa:

  • Simpleng text o symbol lookups — gamitin ang text_pattern_search o find_symbol

Mga Code Analysis Tool#

find_symbolMatatag

Tumalon sa definition at mga paggamit ng function, class, o variable. Gamitin kapag alam mo ang pangalan (hal. "getCurrentUser") — mas mabilis at mas eksakto kaysa Grep at sakop ang buong indexed repo. Maaari ring ibalik ang references at importance metrics.

Mga Parameter:

symbol_nameOpsyonal
Uri
str
Paglalarawan
Pangalan ng symbol na hahanapin (opsyonal — alisin para mag-browse ayon sa metrics)
repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
scopeOpsyonal
Uri
Literal[definitions, references, both]
Default
both
Paglalarawan
Saklaw: definitions|references|both
limitOpsyonal
Uri
int
Default
15
Paglalarawan
Max na bilang ng resulta na ibinalik sa page na ito
offsetOpsyonal
Uri
int
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursorOpsyonal
Uri
str
Paglalarawan
Opaque cursor mula sa pagination.next_cursor. Ipasa nang hindi nagbabago at panatilihing pareho ang query at mga filter.
find_similarOpsyonal
Uri
bool
Default
Paglalarawan
Maghanap ng mga katulad na symbol
include_metricsOpsyonal
Uri
bool
Default
Paglalarawan
Isama ang centrality metrics
metrics_detailOpsyonal
Uri
Literal[summary, full]
Default
summary
Paglalarawan
Kapag ang include_metrics=true: summary (default) ay nagbabalik ng mga signal ng desisyon + refactor_risk; Ibinabalik ng full ang mas malaking na-curate na hanay ng sukatan
path_filterOpsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
symbol_typeOpsyonal
Uri
Literal[function, class, variable, method, constant, module, interface, type]
Paglalarawan
Filter ayon sa symbol type
high_impactOpsyonal
Uri
bool
Default
Paglalarawan
Mag-browse ng mga architecturally important na symbol (alisin ang symbol_name). Popularity ang default mode (top PageRank decile minus ang mga utility mega-hub). Itakda ang high_impact_mode=risk para sa articulation/bridge cut-vertices.
high_impact_modeOpsyonal
Uri
Literal[popularity, risk]
Default
popularity
Paglalarawan
Kapag high_impact=true: popularity = pinakamataas na desil ng PageRank, hindi kasama ang karaniwang utility hub at module; risk = mga articulation point na niraranggo ayon sa SMV bridge_count at pagkatapos ay k_core (panganib sa structural refactor, hindi kasikatan ng hub).
in_cycleOpsyonal
Uri
bool
Default
Paglalarawan
Nasa cycle lang
exclude_test_pathsOpsyonal
Uri
bool
Default
true
Paglalarawan
Kapag nagba-browse ayon sa mga sukatan ng graph, ibukod ang mga pagsubok, fixtures, third-party na code, at mga halimbawa bago ang pagraranggo. Ang paghahanap sa pamamagitan ng isang pinangalanang simbolo ay hindi nagbabago.

Pinakamainam Para sa:

  • Pag-pin sa definition, references, at graph metrics ng isang kilalang symbol
  • Pag-browse ayon sa centrality, high_impact, o in_cycle kapag naiwan ang symbol_name

Hindi Inirerekomenda Para sa:

  • Konseptwal na query o query sa hindi pamilyar na area — gamitin ang intelligent_search o semantic_search

analyze_dependenciesMatatag

Alias para sa blast radius via dependency_search (dependents/incoming). Mas piliin ang dependency_search na may analysis_type="dependents" o "impact" para sa mga bagong agent. Pinapanatili ang legacy multi-hop impact response shape (graph, connection_summary, opsyonal na metrics na may refactor_risk). Gamitin ang graph_view para limitahan ang relationship family: dependency (default), type, data_flow, control_flow.

Mga Parameter:

repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
targetKailangan
Uri
str
Paglalarawan
Pangalan ng symbol na susuriin
depthOpsyonal
Uri
Literal[shallow, balanced, deep]
Default
balanced
Paglalarawan
Lalim ng analysis (sinusuportahan ang mga alias: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
limitOpsyonal
Uri
int
Default
10
Paglalarawan
Max na bilang ng resulta na ibinalik sa page na ito
offsetOpsyonal
Uri
int
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursorOpsyonal
Uri
str
Paglalarawan
Opaque cursor mula sa pagination.next_cursor. Ipasa nang hindi nagbabago at panatilihing pareho ang query at mga filter.
directionOpsyonal
Uri
Literal[incoming, outgoing, both]
Default
incoming
Paglalarawan
Direksyon ng traversal: 'outgoing' = kung saan umaasa ang symbol na ito (mga dependency nito), 'incoming' = kung ano ang umaasa sa symbol na ito (mga dependent nito), 'both' = buong context. Gamitin ang 'incoming' para mahanap ang lahat ng caller/user ng isang symbol.
relationship_typesOpsyonal
Uri
list[str]
Paglalarawan
I-filter ang edge types (CALL, IMPORT, INHERITS_FROM, atbp.). Kapag ibinigay, palaging pinapalitan nito ang default na mula sa graph_view sa ibaba.
graph_viewOpsyonal
Uri
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Paglalarawan
Graph view: tinutukoy ang default traversal edge types at kung aling view ang gagamiting metric kapag include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (default), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Ginagamit lang bilang default ng relationship_types kapag walang tahasang relationship_types. Kapareho ito ng umiiral na graph_view parameter ng dependency_search para pare-pareho ang mga tool.
path_filterOpsyonal
Uri
str
Paglalarawan
Hinihigpitan ang target symbol resolution ayon sa file path prefix; maaaring lumagpas sa labas ng path na iyon ang ibinalik na graph relationships
language_filterOpsyonal
Uri
str
Paglalarawan
Limitahan ang mga resulta sa isang wika
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
per_hop_limitOpsyonal
Uri
int
Paglalarawan
Max na bilang ng relationships bawat hop (1-300)
include_metricsOpsyonal
Uri
bool
Default
Paglalarawan
Isama ang mga sukatan ng graph sa mga resulta, ang bawat isa ay pinayaman ng hinangong refactor_risk block ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). Ang risk ay "low" kapag hindi isang articulation point (sa napiling view), "medium" kapag ang isang articulation point ay nag-bridging ng ilang mga gilid, "high" kapag nag-bridging ng marami (heuristic threshold, hindi empirically validated). Inalis ang bawat simbolo kapag walang row ng mga sukatan para sa simbolo/view na iyon.
metrics_detailOpsyonal
Uri
Literal[summary, full]
Default
summary
Paglalarawan
Kapag ang include_metrics=true: summary (default) ay nagbabalik ng mga signal ng desisyon + refactor_risk; Ibinabalik ng full ang mas malaking na-curate na hanay ng sukatan
include_edge_metadataOpsyonal
Uri
bool
Default
Paglalarawan
Isama ang raw edge metadata at mga timbang. Hindi pinagana bilang default dahil maaaring malaki ang metadata ng extractor; iniuulat ang saklaw ng pagpapayaman kapag pinagana.
exclude_test_pathsOpsyonal
Uri
bool
Default
true
Paglalarawan
Default na true: ibukod ang test, fixture, vendor, at mga halimbawang path mula sa mga ibinalik na gilid ng graph. Itakda ang false upang isama ang mga ito.
include_module_symbolsOpsyonal
Uri
bool
Default
Paglalarawan
Bilang default, ibinubukod ng false ang mga gilid ng graph kapag ang from_name o to_name ay ang synthetic na simbolo ng __module__. Itakda ang true upang isama ang mga gilid sa antas ng module.

Pinakamainam Para sa:

  • Mga legacy caller na naka-wire na sa response shape nito (graph, connection_summary)

Hindi Inirerekomenda Para sa:

  • Mga bagong agent loop — mas piliin ang dependency_search, na parehong traversal core ang ginagamit

get_task_contextMatatag

Nagsisimula sa hindi pamilyar na area? Ilarawan ang task (hal. "magdagdag ng SSO support", "ayusin ang billing webhook") at makakuha ng bounded, one-call na bundle ng mga kaugnay na file, code, symbols, at dependencies. Nag-a-contribute ng direct indexed content ang mga seeded files kahit walang symbols na nade-define. Para sa mas maraming resulta, magpatuloy sa specialized search tool para sa layer na iyon.

Mga Parameter:

task_descriptionKailangan
Uri
str
Paglalarawan
Deskripsyon ng task
repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
limitOpsyonal
Uri
int
Default
15
Paglalarawan
Pinakamaraming resulta bawat layer
scopeOpsyonal
Uri
Literal[semantic, symbols, dependencies, all]
Default
all
Paglalarawan
Mga context layer na isasama. Valid: 'semantic', 'symbols', 'dependencies', 'all'. Default: ['semantic', 'symbols', 'dependencies']
language_filterOpsyonal
Uri
str
Paglalarawan
I-filter ang mga resulta sa mga file na na-detect bilang ang partikular na programming language na ito
path_filterOpsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
include_related_contextOpsyonal
Uri
bool
Default
Paglalarawan
Isama ang kaugnay na context mula sa katabing mga symbol
seed_symbol_idsOpsyonal
Uri
list[str]
Paglalarawan
Tier-1 na tahasang seed: mga symbol ID na alam na ng agent na sentro sa task (hal. mga symbol sa nakabukas na file). Inuuna sa keyword-derived seeds sa dependencies/related_context layers. Additive — alisin para sa kasalukuyang keyword-only behavior.
seed_file_pathsOpsyonal
Uri
list[str]
Paglalarawan
Tier-1 explicit seeds: mga indexed file path na bukas o kakatapos lang i-edit ng agent. Ibinabalik ang bounded direct file evidence at nire-resolve ang hanggang 5 symbols per file para sa graph context, kasama ang symbol-free docs at config. Additive lang ito — alisin para sa keyword-only na behavior.

Pinakamainam Para sa:

  • Task-aware na context na pinagsasama ang seeded files sa semantiko, symbol, at dependency layers

Hindi Inirerekomenda Para sa:

  • Single-tool lookups kung saan may mas specific na tool na nakakasagot na sa tanong

get_fileMatatag

Magbasa ng file mula sa indexed repo ayon sa path. Mas piliin ang lokal na Read tool para sa mga file na nasa disk — gamitin ito para sa cross-repo o remote lookups kapag wala ang file sa working tree mo. May optional na line range; magpatuloy sa token-truncated na response mula sa metadata.next_line_start.

Mga Parameter:

file_pathKailangan
Uri
str
Paglalarawan
File path na relative sa repository root
repositoryOpsyonal
Uri
str
Paglalarawan
Repository bilang owner/repo[:branch]. Opsyonal — alisin upang gamitin ang request-scoped client default (kapag ibinigay) o ang nag-iisang maa-access na repository; tahasang ipasa lamang upang pumili ng ibang indexed repo. Ipinapakita ng tugon kung aling repository ang ginamit.
line_startOpsyonal
Uri
int
Paglalarawan
Panimulang linya (1-indexed)
line_endOpsyonal
Uri
int
Paglalarawan
End line (1-indexed, inclusive; dapat nasa line_start o pagkatapos nito)
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
max_tokensOpsyonal
Uri
int
Default
5000
Paglalarawan
Max na bilang ng token
include_metadataOpsyonal
Uri
bool
Default
true
Paglalarawan
Isama ang metadata

Pinakamainam Para sa:

  • Remote o indexed na file snapshots (line ranges, token limits)

Hindi Inirerekomenda Para sa:

  • Path na nasa lokal na disk na — gamitin ang lokal na Read tool

Mga System at Utility Tool#

repository_contextMatatag

Ilista ang mga repository na maaari mong hanapin, o kumuha ng identity info tungkol sa isa (namespace/branch, indexed_commit_sha / index freshness). Tawagin gamit ang action:"list" nang isang beses para malaman ang eksaktong repo slug na tinatanggap ng search tools. (Kung iisa lang ang repo ng key mo, doon nag-de-default ang search tools — pwede mo itong laktawan.) Opt-in ang namespace-wide file/blob/edge counts via include_statistics=true.

Mga Parameter:

actionKailangan
Uri
Literal[list, info]
Paglalarawan
Action: ilista ang available na repo o kumuha ng impormasyon tungkol sa repo
repositoryOpsyonal
Uri
str
Paglalarawan
Repository sa owner/repo o owner/repo:branch na format (kailangan para sa info)
branchOpsyonal
Uri
str
Paglalarawan
Pag-override sa branch
patternOpsyonal
Uri
str
Paglalarawan
Pattern para sa pag-filter
include_statisticsOpsyonal
Uri
bool
Default
Paglalarawan
Opsyonal: isama ang namespace-wide indexed-data counts (file/blob/edge). Default na false — hindi kailangan ng repository identity ang mas mabagal na aggregate na ito.
limitOpsyonal
Uri
int
Default
20
Paglalarawan
Max na bilang ng resulta na ibinalik sa page na ito
offsetOpsyonal
Uri
int
Paglalarawan
Hindi na ginagamit na compatibility offset. Mas gusto ang cursor mula sa pagination.next_cursor.
cursorOpsyonal
Uri
str
Paglalarawan
Opaque cursor mula sa pagination.next_cursor. Ipasa ito nang hindi nabago at panatilihing hindi nagbabago ang query at mga filter.

Pinakamainam Para sa:

  • Paglilista ng mga naa-access na repository
  • Pagre-resolve ng repository identity, branch, at HEAD-vs-index freshness

Hindi Inirerekomenda Para sa:

  • Namespace-wide na statistics bilang default — magpasa ng include_statistics=true nang explicit, dahil mas mabagal ito kaysa sa resolution

ask_maguyvaMatatag

Tulong at feedback para sa Maguyva. Primary: kumuha ng tool guidance, o mag-submit ng bug report / feature request na naka-store para sa mga maintainer ng Maguyva. Huwag kailanman isama ang secrets o sensitive personal data sa feedback. Nananatili ang evaluate operation para sa back-compat lang — mas piliin ang local compute o host tools para sa math/hash/string work.

Mga Parameter:

operationKailangan
Uri
Literal[guidance, report_bug, request_feature, evaluate]
Paglalarawan
Primary: guidance, report_bug, request_feature. Legacy/compat lang: evaluate (deterministic expression engine; hindi bahagi ng primary agent workflow).
queryOpsyonal
Uri
str
Paglalarawan
Guidance topic (hal. tool_selection, semantic_search). Para sa legacy evaluate lang: expression string.
descriptionOpsyonal
Uri
str
Paglalarawan
Required para sa report_bug at request_feature. Free-form na feedback para sa mga maintainer ng Maguyva. Huwag kailanman isama ang secrets o sensitive personal data.
related_toolOpsyonal
Uri
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]
Paglalarawan
Opsyonal na tool na Maguyva na pinaka malapit na nauugnay sa feedback

Pinakamainam Para sa:

  • Tool guidance (operation="guidance")
  • Matatag na bug report at feature request para sa mga maintainer ng Maguyva

Hindi Inirerekomenda Para sa:

  • Math/hash/string computation — legacy/back-compat lang ang evaluate operation; mas piliin ang local host compute

Mga Best Practice#

  1. Sadyang Gumamit ng mga Tahasang Override: Alisin ang repository kapag nagbibigay ang iyong MCP client ng request default o eksaktong isang repository lang ang maa-access ng key; kung hindi, tahasan itong ipasa.
  2. Piliin ang Tamang Search Mode: Gamitin ang intelligent_search kasama ang mode="auto" sa karamihan ng cases. Mag-specify ng mode kung alam mo talaga ang kailangan mo.
  3. Gamitin ang Language Filters: Gamitin ang language_filter para paliitin ang resulta at mapahusay ang performance.
  4. Boosting ng GraphRAG: Naka-off by default ang GraphRAG importance boosting para sa semantic search (boost_by_importance=false) para panatilihing agent-safe ang ranking. I-pass ang boost_by_importance=true para i-enable ang centrality-aware re-ranking para sa architecture tours.
  5. Case-Insensitive ang Repository Matching, Hindi Fuzzy: Nire-match ng repository_context ang mga repository name nang case-insensitive — hindi nito ino-correct ang mga typo. I-check ang metadata.resolution_reason sa info action ("exact" laban sa "corrected") para makita kung paano na-resolve ang isang name.
  6. Pagsamahin ang mga Tool: Gumamit ng maraming API method nang sabay-sabay para sa comprehensive na analysis.
  7. I-handle ang mga Malaking Resulta: Gamitin ang limit at tool-specific na paging controls (halimbawa line_start/line_end sa get_file).
  8. Gamitin ang ask_maguyva para sa Tool Guidance: Ang ask_maguyva evaluate operation (hash, base64, JSON, math) ay legacy / back-compat na lang. Sa halip, tawagin ang ask_maguyva gamit ang operation="guidance" at query="tool_selection" para sa local-tool-wins matrix at kumpletong tool-by-tool cheat sheet.
  9. I-verify ang Impact Bago at Pagkatapos Mag-edit: Bago mag-edit ng shared symbol, tawagin ang dependency_search gamit ang analysis_type="impact" (o i-pass ang changed_paths para sa PR/diff impact) para makita ang blast radius nito. Pagkatapos mag-edit, i-set ang verify_after_edit=true kasama ang targets at/o changed_paths para sa maikling re-check ng parehong mga symbol.

Mga Katangian sa Performance#

OperasyonMga tala sa performance
Semantic searchMababa sa isang segundo, pero may live embedding API call bawat pagkakataon (hindi naka-cache) — asahan ang extra latency sa ibabaw ng vector query
Text searchMababa sa isang segundo para sa exact/regex; ang fuzzy content search ay nagpe-page sa client side, kaya mas mahal ang malalalim na offset — paliitin gamit ang path_filter/language_filter
Structural searchAST-indexed — sumusukat ang cost base sa dami ng resulta, hindi sa laki ng repository
Dependency searchSumusukat ang cost base sa depth — mas maganda ang depth="shallow" maliban kung kailangan mo ng multi-hop context; nili-limit ng per_hop_limit ang fan-out
Pagkuha ng fileHalos instant para sa isang file — i-page ang malalaking file gamit ang line_start/line_end o max_tokens sa halip na isang malaking pull
Repository contextNaka-cache lang ang namespace resolution per request, hindi across calls — bawat tool invocation ay nagre-resolve ulit
ask_maguyva (guidance / evaluate)Halos instant — tumatakbo in-Worker nang walang database call

Pag-handle ng Error#

Nagbabalik ang lahat ng API method ng structured envelope:

  • status: String — "success" o "error". Ang degraded-match at freshness signal ay nasa nested field tulad ng metadata.resolution_reason sa repository_context o metadata.index_freshness.status.
  • tool: Pangalan ng tool na gumawa ng response
  • data: Result payload kapag successful (naiiba ang structure depende sa tool)
  • error: Structured error object kapag status ay "error" — kasama ang type, message, suggestions, at recovery_actions
  • metadata: Karagdagang impormasyon tungkol sa operation (routing, caching, parameter adjustments)
  • pagination: Nakikita sa list responses — kasama ang has_more at next_cursor

Laging i-check ang status field bago i-process ang resulta — "success" o "error" lang ang posibleng value nito. Para sa degraded-match o freshness signal, basahin na lang ang nested field: metadata.resolution_reason sa repository_context, o metadata.index_freshness.status (known/partial/unknown/unavailable).

Paano Magsimula#

  1. I-configure ang MCP Client: Ituro ang MCP client mo sa Maguyva server endpoint
  2. Kumpirmahin ang Access sa Repository: Gamitin ang repository_context na may list o info para suriin ang mga repository na available sa API key
  3. Simulan ang Paghahanap: Magsimula sa intelligent_search at galugarin ang mga specialized tool kung kinakailangan
  4. Pagsamahin ang mga Tool: Gamitin nang sabay-sabay ang maraming tool para sa komprehensibong code analysis

Para sa detalyadong integration instructions, tingnan ang gabay sa pag-install.