Lumaktaw papunta sa content

Sanggunian sa MCP API

Alamin ang 11 MCP tool ng Maguyva, ang mga parameter nito, at kung kailan gagamitin ang bawat isa. Tingnan ang tools/list response ng nakakonektang client para sa mga argument na maaari mong gamitin.

Buod ng API

#

Nakaayos ang mga tool sa 4 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 - Konteksto ng repository, gabay sa mga tool, at puna

Para sa mga tool na tumatanggap ng repository, gamitin ang format ng repository identifier na ito: "owner/repo:branch". Default ang main na branch kung walang tinukoy.

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

#

Gamitin ang mga format na ito kapag tumutukoy ng repository:

  • 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

#

Gamitin ang language_filter sa mga search mode na sumusuporta rito. Para sa text_pattern_search, piliin ang search_scope="content"; para sa get_task_context, gamitin ang scope="semantic" nang walang mga panimulang seed o kaugnay na konteksto.

  • 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 285+ 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 Oktubre 21, 2026.

Mga Pangunahing Search Tool

#

intelligent_search Matatag

Magsimula rito para sa anumang tanong tungkol sa codebase. Sa default na auto/balanced, ang mga query na may mataas na kumpiyansang natukoy bilang paghahanap ng definition ay dinadala sa structural search, ang mga tanong tungkol sa reference o epekto sa graph, at ang mga tanong tungkol sa eksaktong tugma sa text search. Gumagamit ang ibang tanong ng semantic na kahulugan at naka-index na text. Gamitin ang mode=hybrid o auto na may quality=thorough para hilingin ang lahat ng apat na paraan ng paghahanap. Mas nasusunod ang tahasang piniling mode kaysa sa quality. Inaalis ng language_filter ang graph sa auto/hybrid at tinatanggihan ito kapag tahasang itinakda ang mode=graph. Mas piliin ito kaysa Grep/Glob kapag hindi mo pa alam ang path.

Mga Parameter:

query Kailangan
Uri
str minLength=1
Paglalarawan
Query para sa paghahanap
repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
mode Opsyonal
Uri
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Default
auto
Paglalarawan
Mode ng paghahanap
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
10
Paglalarawan
Max na bilang ng resulta sa ranked top-K window na ito
language_filter Opsyonal
Uri
str
Paglalarawan
Filter ayon sa wika
path_filter Opsyonal
Uri
str
Paglalarawan
Salain ang mga kandidato sa retrieval ayon sa prefix ng file path. Maaaring magsama ng mga file sa labas ng prefix na ito ang mga kapitbahay sa graph at ang kalakip na konteksto ng komunidad.
boost_by_importance Opsyonal
Uri
bool
Default
false
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.
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch
quality Opsyonal
Uri
Literal[quick, balanced, thorough]
Default
balanced
Paglalarawan
Preset ng kalidad ng paghahanap
include_content Opsyonal
Uri
bool
Default
true
Paglalarawan
Isama ang content sa mga resulta
explain_routing Opsyonal
Uri
bool
Default
false
Paglalarawan
Isama ang paliwanag sa desisyon sa routing
importance_weight Opsyonal
Uri
float minimum=0, maximum=1
Default
0.3
Paglalarawan
Bigat para sa importance boosting (0=wala, 1=buo)
orphans Opsyonal
Uri
bool
Default
false
Paglalarawan
Isama ang mga orphan symbol (walang incoming reference)
include_community_context Opsyonal
Uri
bool
Default
false
Paglalarawan
Isama ang mga kaugnay na symbol mula sa parehong code community
community_depth Opsyonal
Uri
int minimum=1, maximum=3
Default
1
Paglalarawan
Lalim ng pagpapalawak ng community context
graph_view Opsyonal
Uri
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Paglalarawan
Graph view para sa mga metric
seed_symbol_ids Opsyonal
Uri
list[str] maxItems=20
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_paths Opsyonal
Uri
list[str] maxItems=10
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_search Matatag

Maghanap ng code ayon sa kahulugan, hindi sa eksaktong text. Gamitin sa konseptuwal na query gaya ng 'retry logic' o 'user onboarding flow' kapag hindi mo alam ang keyword o pangalan ng symbol. Nagbabalik ng kaugnay na chunks na may limitadong pagkakaiba-iba ng file; opsyonal ang muling pag-rank ayon sa graph importance sa pamamagitan ng boost_by_importance. Unahin ito kaysa Grep para sa konseptuwal na paghahanap.

Mga Parameter:

query Kailangan
Uri
str minLength=1
Paglalarawan
Search query (conceptual, batay sa kahulugan)
repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
5
Paglalarawan
Max na bilang ng resulta sa ranked top-K window na ito
similarity_threshold Opsyonal
Uri
float minimum=0, maximum=1
Default
0.6
Paglalarawan
Minimum na similarity score
language_filter Opsyonal
Uri
str
Paglalarawan
Filter ayon sa wika (python, typescript, atbp.)
path_filter Opsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
boost_by_importance Opsyonal
Uri
bool
Default
false
Paglalarawan
Opsyonal: muling i-rank ayon sa normalized graph importance ng bawat symbol (naka-off bilang default; hanggang 1.5x ng similarity).
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch (default: mula sa repository parameter o main)
include_content Opsyonal
Uri
bool
Default
true
Paglalarawan
Isama ang chunk content sa mga resulta
graph_view Opsyonal
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_search Matatag

Maghanap sa naka-index na content. Gine-grep ng exact at regex modes ang buong file/blob corpus; naghahanap ang fuzzy content mode sa limitadong semantic chunk corpus. Trigram lang ang file at symbol scopes — ginagawang fuzzy ang default na mode=exact. Kailangan ng content scope para sa language, case, at custom-threshold controls. Gumagamit ang file path filter ng limitadong candidate window at nag-uulat kapag hindi kumpleto ang saklaw. Gamitin ang lokal na Grep para sa maliit na directory na nasa disk na.

Mga Parameter:

query Kailangan
Uri
str minLength=1
Paglalarawan
Pattern ng text
repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
mode Opsyonal
Uri
Literal[fuzzy, exact, regex]
Default
exact
Paglalarawan
Mode ng paghahanap. Ginagamit ng Regex ang advanced/POSIX syntax ng PostgreSQL; gamitin ang \y para sa word boundaries (ang \b ay nangangahulugang backspace). Dumaraan din ang mga pattern sa isang JavaScript safety validator, kaya tinatanggihan ang mga PostgreSQL-only na construct tulad ng inline (?i) flags; gamitin na lang ang case_sensitive.
search_scope Opsyonal
Uri
Literal[content, symbols, files]
Default
content
Paglalarawan
Ano ang hahanapin
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
5
Paglalarawan
Pinakamataas na bilang ng resulta bawat page kung walang cursor. Ginagamit ng pagpapatuloy ang page size na naka-imbak sa cursor; laktawan ang cursor para magsimula na may ibang limit.
offset Opsyonal
Uri
int minimum=0
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursor Opsyonal
Uri
str
Paglalarawan
Opaque na cursor mula sa pagination.next_cursor. Ipasa ito nang hindi binabago at panatilihing hindi nagbabago ang query at mga filter. Ang posisyon at page size nito ang mananaig kaysa sa offset at limit.
language_filter Opsyonal
Uri
str
Paglalarawan
Filter ayon sa wika
path_filter Opsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
case_sensitive Opsyonal
Uri
bool
Default
false
Paglalarawan
Case sensitive (may pagkakaiba ang malaki't maliit na letra)
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch
fuzzy_algorithm Opsyonal
Uri
Literal[hybrid, trigram, levenshtein]
Default
hybrid
Paglalarawan
Algorithm ng fuzzy matching
threshold Opsyonal
Uri
float minimum=0, maximum=1
Default
0.05
Paglalarawan
Pinakamababang similarity threshold para sa fuzzy search
semantic_fallback Opsyonal
Uri
bool
Default
false
Paglalarawan
Sinusubukan ang semantic search pagkatapos ng blangkong unang lexical page; ang metadata.fallback_status ang nagbubukod sa used, empty, at unavailable na fallback status.

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_search Matatag

Mas piliin ang preset=functions|classes|methods|imports|variables (o malayang pattern=). Hanapin ang code ayon sa hugis ng AST, hindi sa teksto. Mga filter sa gitnang antas: name_pattern, node_type, decorator, parent_child. Mas advanced ang mga filter ng path/ltree/call — itakda ang advanced=true kapag sadyang ginagamit ang mga ito. Kung wala ito, ilalapat ang mga advanced na filter na may babala sa metadata. Magbigay ng kahit isang structural selector.

Mga Parameter:

repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
preset Opsyonal
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/interface declarations, type bodies, at implementations); 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.
pattern Opsyonal
Uri
str
Paglalarawan
Pinupunan ng free-form na pattern ang mga nawawalang selector (auto-detect: 'def foo(' → node_type + name_pattern). Puwedeng pagsamahin sa preset; unang priyoridad ang mga explicit na selector. Mas piliin ang preset= para sa mga browse query.
name_pattern Opsyonal
Uri
str maxLength=256
Paglalarawan
Symbol name pattern (shell wildcard, bounded POSIX regex, o fuzzy text; max 256 characters)
node_type Opsyonal
Uri
str
Paglalarawan
AST node type (function_definition, class_definition, atbp.) — mas piliin ang preset= para sa common shapes
decorator Opsyonal
Uri
str
Paglalarawan
Filter ayon sa pangalan ng decorator
base_class Opsyonal
Uri
str
Paglalarawan
Filter ayon sa base class
language_filter Opsyonal
Uri
str
Paglalarawan
Filter ayon sa wika (python, typescript, atbp.)
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
20
Paglalarawan
Pinakamataas na bilang ng resulta bawat page kung walang cursor. Ginagamit ng pagpapatuloy ang page size na naka-imbak sa cursor; laktawan ang cursor para magsimula na may ibang limit.
offset Opsyonal
Uri
int minimum=0
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursor Opsyonal
Uri
str
Paglalarawan
Opaque na cursor mula sa pagination.next_cursor. Ipasa ito nang hindi binabago at panatilihing hindi nagbabago ang query at mga filter. Ang posisyon at page size nito ang mananaig kaysa sa offset at limit.
path_filter Opsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch
query_type Opsyonal
Uri
Literal[node_type, name_pattern, parent_child]
Paglalarawan
Tiyak na uri ng query
parent_type Opsyonal
Uri
str
Paglalarawan
Filter sa uri ng parent AST node
relationship Opsyonal
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_modifier Opsyonal
Uri
str
Paglalarawan
I-filter ayon sa modifier (export, async, static, atbp.)
advanced Opsyonal
Uri
bool
Default
false
Paglalarawan
Itakda ang true kapag sadyang ginagamit ang mga advanced na filter ng path/ltree/call (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Kapag false, ilalapat ang ibinigay na mga advanced na filter na may babala sa metadata. Mas piliin ang preset= para sa karaniwang structural query.
callee_text Opsyonal
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_name Opsyonal
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_role Opsyonal
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_ancestor Opsyonal
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_descendant Opsyonal
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_name Opsyonal
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_depth Opsyonal
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_depth Opsyonal
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_search Matatag

Primary na saklaw ng epekto / graph surface. Sinasagot ang "ano ang tumatawag dito?" / "ano ang ginagamit 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: 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. Ginagamit ng analyze_dependencies ang parehong pagdaan sa graph para sa pagsusuri ng epekto sa maraming hakbang. Kasama sa dependents/impact ang production_callers bilang default: mga natatanging production usage site ayon sa uri (call, instantiate, value_reference para sa mga function na ipinapasa bilang value), kasama ang mga IMPORT site, hindi kasama ang mga test, at may kumpiyansang EXTRACTED/INFERRED — hindi basta listahan ng mga metric.

Mga Parameter:

repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
query Opsyonal
Uri
str
Paglalarawan
Pangalan ng symbol o search term
target Opsyonal
Uri
str
Paglalarawan
Pangalan ng symbol (alias para sa query)
symbol_id Opsyonal
Uri
UUID
Paglalarawan
Pumili ng partikular na paglitaw na may UUID mula sa mga kandidatong tumutugma sa pinangalanang query/target matapos salain ayon sa namespace, path at wika. Gumamit ng ID na ibinalik ng find_symbol o ng mga alternatibong resulta ng graph. Para lamang sa traversal na may tinukoy na pangalan; magdudulot ng error ang ID na wala sa limitadong saklaw ng mga kandidato.
changed_paths Opsyonal
Uri
list[str] maxItems=50
Paglalarawan
Eksaktong mga path ng file 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. Ang mga path na hindi ma-resolve ay maaaring magbalik ng mga naka-label na suhestiyon; ang mga isinuhestiyong file ay hindi kailanman nagiging panimulang punto ng epekto. Para sa PR/diff: kapag walang impormasyon sa linya, dinadaanan ang mga top-level na depinisyon ng bawat path (inuuna ang mga naka-export, ayon sa pagkakasunod sa file) at iniuulat ang changed_lines_unknown; ipasa ang patch= para sa mga simbolong nagbago kada linya. Para sa pag-verify: hanggang 5 top-level na depinisyon 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.
patch Opsyonal
Uri
str maxLength=500000
Paglalarawan
Epekto ng PR/diff: unified diff o git patch na teksto. Kinukuha ang mga path mula sa mga header na diff --git / --- / +++; ang mga linya ng hunk (lumang panig = ang na-index na commit) ay itinutugma sa mga function/method/class na sumasaklaw sa mga ito, na sinusundan para sa eksaktong mga dependent, public_api_changed, at mga caller na hindi ginalaw ng diff.
head_commit Opsyonal
Uri
str pattern=^[0-9a-fA-F]{7,64}$
Paglalarawan
Commit SHA ng code na tinatanong mo (git rev-parse HEAD, o ang base commit ng patch). Kailangan ng complete:true na nasa commit na ito ang index at na-build ito ng kasalukuyang resolver; kung hindi, mananatiling complete:false na may index_stale / index_freshness_unverified / index_built_by_older_resolver, at sinasabi ng index_basis.statement kung hanggang saan kumpleto ang sagot. Puwede rin itong manggaling sa 'base-commit:' line ng isang patch (git format-patch --base).
analysis_type Opsyonal
Uri
Literal[centrality, dependencies, dependents, impact, orphans]
Default
dependencies
Paglalarawan
Analysis mode. impact = saklaw ng epekto (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. Ang orphans ay mga kandidatong hindi ginagamit na code, hindi patunay na ligtas nang tanggalin; i-verify ang mga source reference.
depth Opsyonal
Uri
Literal[shallow, balanced, deep]
Paglalarawan
Lalim ng traversal. Ang default ay balanced; default sa shallow ang impact at PR/diff impact. Ang explicit na depth ang mag-o-override sa mga default na ito. Palaging gumagamit ng shallow ang verify mode.
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
20
Paglalarawan
Pinakamataas na bilang ng resulta bawat page kung walang cursor. Ginagamit ng pagpapatuloy ang page size na naka-imbak sa cursor; laktawan ang cursor para magsimula na may ibang limit.
offset Opsyonal
Uri
int minimum=0
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursor Opsyonal
Uri
str
Paglalarawan
Opaque na cursor mula sa pagination.next_cursor. Ipasa ito nang hindi binabago at panatilihing hindi nagbabago ang query at mga filter. Ang posisyon at page size nito ang mananaig kaysa sa offset at limit.
path_filter Opsyonal
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_filter Opsyonal
Uri
str
Paglalarawan
I-filter ang target resolution at browse results ayon sa language
direction Opsyonal
Uri
Literal[outgoing, incoming, both]
Paglalarawan
Direksyon ng traversal (pinapalitan ang inference ng analysis_type)
relationship_types Opsyonal
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_paths Opsyonal
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. Sinusunod lang ito ng orphan analysis kung saan sinusuportahan ito ng naka-deploy na backend; kung hindi, pinananatili nito ang sarili nitong mas mahigpit na noise exclusions at iniuulat ang pagsasaayos.
exclude_generated_paths Opsyonal
Uri
bool
Default
false
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_symbols Opsyonal
Uri
bool
Default
false
Paglalarawan
Default: false. Hindi kasama ang mga graph edge kung ang from_name o to_name ay ang synthetic na __module__ symbol (module-level noise). Itakda sa true para isama ang mga module-level edge sa dependents/dependencies traversal.
include_isolated Opsyonal
Uri
bool
Paglalarawan
Para sa orphans lang. Default: false. Itakda sa true para isama rin ang mga simbolong walang row sa graph metrics (walang anumang graph edge kahit saan). Habang true ang exclude_test_paths, nananatiling hindi kasama ang mga stylesheet/markup/data symbol (CSS, HTML, ...), mga .d.ts declaration, at mga test/fixture/vendor/example path kung saan ito sinusuportahan ng backend, maliban kung pinangalanan ng language_filter ang wikang iyon; maaari pa ring lumabas ang mga property ng TypeScript object literal bilang mga isolated function.
exclude_exported Opsyonal
Uri
bool
Default
false
Paglalarawan
Para lang sa mga orphan. Default na false: ibinabalik ang mga exported symbol (public API) na walang gumagamit sa repository, na may is_exported=true. Itakda sa true para sa mga internal na kandidato lang.
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch
per_hop_limit Opsyonal
Uri
int minimum=1, maximum=300
Paglalarawan
Max na bilang ng relationships bawat hop (1-300)
include_metrics Opsyonal
Uri
bool
Default
false
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_detail Opsyonal
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_metadata Opsyonal
Uri
bool
Default
false
Paglalarawan
Isama ang raw edge metadata at mga timbang (malaki). Naka-off ito sa mga compact na impact payload.
symbol_types Opsyonal
Uri
list[str]
Paglalarawan
Fine-filter ang mga ibinalik na symbol ayon sa uri (function, class, method, atbp). Hindi suportado sa orphan analysis; gamitin sa halip ang path_filter o language_filter doon. Walang ilalapat na filter sa uri kung walang laman ang listahan.
exact_match Opsyonal
Uri
bool
Default
false
Paglalarawan
Kailangan ng eksaktong tugma sa pangalan ng symbol
find_similar_patterns Opsyonal
Uri
bool
Default
false
Paglalarawan
Maghanap ng katulad na usage patterns
min_centrality Opsyonal
Uri
float minimum=0
Default
0
Paglalarawan
Minimum na PageRank score para sa traversal ng mga simbolong may pangalan at sa impact ng PR/diff. Hindi suportado ang positibong threshold sa mga browse mode na centrality/orphans. Kino-fetch internally ang metrics para sa filtering; ibinabalik lang ang graph_metrics kapag include_metrics=true. Hindi ito pinapansin ng verify_after_edit, na gumagamit ng nakapirming compact na kontrol.
graph_view Opsyonal
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_edit Opsyonal
Uri
bool
Default
false
Paglalarawan
Muling ni-kuquery ang indexed na impact graph para sa mga na-edit na symbol sa iisang compact na multi-root response. Kailangan ang targets at/o changed_paths (o target/query). Gumagamit ito ng fixed na shallow traversal at compact na budget; hindi applicable ang mga kontrol na depth/limit/cursor/metrics. Default na ibinabalik ang incoming dependents; sinasalamin ng resulta ang indexed na graph (posibleng mahuli sa live na mga edit). Kapag true, mas nauuna ito kaysa sa PR/diff impact para sa parehong changed_paths.
targets Opsyonal
Uri
list[str] maxItems=15
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_symbol Matatag

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_name Opsyonal
Uri
str
Paglalarawan
Pangalan ng symbol na hahanapin (opsyonal — alisin para mag-browse ayon sa metrics)
repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
scope Opsyonal
Uri
Literal[definitions, references, both]
Default
both
Paglalarawan
Saklaw ng paghahanap; kailangan ng references ang hindi blangkong symbol_name.
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
15
Paglalarawan
Pinakamataas na bilang ng resulta bawat page kung walang cursor. Ginagamit ng pagpapatuloy ang page size na naka-imbak sa cursor; laktawan ang cursor para magsimula na may ibang limit.
offset Opsyonal
Uri
int minimum=0
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursor Opsyonal
Uri
str
Paglalarawan
Opaque na cursor mula sa pagination.next_cursor. Ipasa ito nang hindi binabago at panatilihing hindi nagbabago ang query at mga filter. Ang posisyon at page size nito ang mananaig kaysa sa offset at limit.
find_similar Opsyonal
Uri
bool
Default
false
Paglalarawan
Isama ang mga magkahawig na pangalan ng symbol
include_metrics Opsyonal
Uri
bool
Default
false
Paglalarawan
Isama ang centrality metrics
metrics_detail Opsyonal
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_filter Opsyonal
Uri
str
Paglalarawan
I-filter ayon sa prefix ng file path
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch
symbol_type Opsyonal
Uri
str minLength=1
Paglalarawan
I-filter ayon sa indexed symbol kind, hal. function, class, struct, enum, o trait. Gamitin ang kind na ibinalik ng resulta ng symbol; nag-iiba ang kind depende sa language.
high_impact Opsyonal
Uri
bool
Default
false
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_mode Opsyonal
Uri
Literal[popularity, risk]
Default
popularity
Paglalarawan
Kapag high_impact=true: popularity = pinakamataas na desil ng PageRank, hindi kasama ang mga utility mega-hub/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_cycle Opsyonal
Uri
bool
Default
false
Paglalarawan
Fine-filter ang mga symbol na may naitalang pagiging kasapi sa isang dependency cycle.
exclude_test_paths Opsyonal
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.
reference_views Opsyonal
Uri
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
Paglalarawan
Mga graph view na ang mga papasok na edge ay pumupuno sa references/reference_count (scope na references/both). Default na ["dependency", "type"]: mga tawag, import, export, reference, instantiation, inheritance, override, decorator, at paggamit ng type. Kung hindi pinili ang data_flow, hiwalay na ibinabalik bilang value_references/value_reference_count ang mga eksaktong na-resolve na paggamit ng data_flow (callback, handler, sort key), nang walang mga tugmang hinula sa pangalan lang. Idagdag ang data_flow o control_flow, o ipasa ang ["all"] para sa lahat ng uri at antas ng edge. Pareho ang mga pamilya ng view sa graph_view ng dependency_search.
relationship_types Opsyonal
Uri
list[str]
Paglalarawan
Mga tahasang uri ng reference edge (CALL, IMPORT, READS, atbp.). Nauuna sa reference_views ang isang listahang hindi walang laman.

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_dependencies Matatag

Suriin ang saklaw ng epekto gamit ang parehong pagdaan sa graph ng dependency_search (dependents/incoming). Mas piliin ang dependency_search na may analysis_type="dependents" o "impact" para sa pagsusuri ng epekto. Nagbabalik ng tugon para sa epekto sa maraming hakbang na may graph, connection_summary, at opsyonal na metrics na may refactor_risk. Gamitin ang graph_view para limitahan ang relationship family: dependency (default), type, data_flow, control_flow. Binibilang ng connection_summary ang mga edge na saklaw ng napiling relationship family para sa napiling root, bago ang anumang test/path filtering. Ang mga lumang field na incoming_production/outgoing_production ay tumutukoy sa mga edge na hindi module, kasama ang mga test; hindi ito bilang ng production callers.

Mga Parameter:

repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
target Kailangan
Uri
str minLength=1
Paglalarawan
Pangalan ng symbol na susuriin
symbol_id Opsyonal
Uri
UUID
Paglalarawan
Pumili ng partikular na paglitaw na may UUID mula sa mga kandidatong target matapos salain ayon sa namespace, path at wika; magdudulot ng error ang mga ID na wala sa limitadong saklaw ng mga kandidato.
depth Opsyonal
Uri
Literal[shallow, balanced, deep]
Default
balanced
Paglalarawan
Lalim ng analysis
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
10
Paglalarawan
Pinakamataas na bilang ng resulta bawat page kung walang cursor. Ginagamit ng pagpapatuloy ang page size na naka-imbak sa cursor; laktawan ang cursor para magsimula na may ibang limit.
offset Opsyonal
Uri
int minimum=0
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursor Opsyonal
Uri
str
Paglalarawan
Opaque na cursor mula sa pagination.next_cursor. Ipasa ito nang hindi binabago at panatilihing hindi nagbabago ang query at mga filter. Ang posisyon at page size nito ang mananaig kaysa sa offset at limit.
direction Opsyonal
Uri
Literal[incoming, outgoing, both]
Default
incoming
Paglalarawan
Direksyon ng traversal
relationship_types Opsyonal
Uri
list[str]
Paglalarawan
Fine-filter ang mga uri ng edge (CALL, IMPORT, INHERITS_FROM, atbp). Ang listahang hindi blangko ang mag-o-override sa default ng graph_view; ang blangkong listahan ang gagamit sa mga default na iyon.
graph_view Opsyonal
Uri
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Paglalarawan
Graph view: tinutukoy nito ang default na mga uri ng edge sa traversal pati na rin kung aling view ang metrics na gagamitin 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]. Inilalapat ito bilang default ng relationship_types kapag naka-omit o blangko ang relationship_types. Tumutugma ito sa umiiral nang graph_view na parameter name ng dependency_search, para sa consistency sa pagitan ng mga tool.
path_filter Opsyonal
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_filter Opsyonal
Uri
str
Paglalarawan
Limitahan ang mga resulta sa isang wika
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch
per_hop_limit Opsyonal
Uri
int minimum=1, maximum=300
Paglalarawan
Max na bilang ng relationships bawat hop (1-300)
include_metrics Opsyonal
Uri
bool
Default
false
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). Hindi isinasama ang metrics para sa isang symbol kapag walang metrics row para sa symbol/view na iyon.
metrics_detail Opsyonal
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_metadata Opsyonal
Uri
bool
Default
false
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_paths Opsyonal
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_symbols Opsyonal
Uri
bool
Default
false
Paglalarawan
Default: false. Hindi kasama ang mga graph edge kung ang from_name o to_name ay ang synthetic na __module__ symbol. Itakda sa true para isama ang mga module-level edge.
head_commit Opsyonal
Uri
str pattern=^[0-9a-fA-F]{7,64}$
Paglalarawan
Commit SHA ng code na tinatanong mo (git rev-parse HEAD, o ang base commit ng patch). Kailangan ng complete:true na nasa commit na ito ang index at na-build ito ng kasalukuyang resolver; kung hindi, mananatiling complete:false na may index_stale / index_freshness_unverified / index_built_by_older_resolver, at sinasabi ng index_basis.statement kung hanggang saan kumpleto ang sagot. Puwede rin itong manggaling sa 'base-commit:' line ng isang patch (git format-patch --base).

Pinakamainam Para sa:

  • Pagsusuri ng epekto sa maraming hakbang kapag kailangan ang mga response field na graph at connection_summary

Hindi Inirerekomenda Para sa:

  • Pangkalahatang pagsusuri ng epekto — mas piliin ang dependency_search para sa flexible na pagdaan sa graph at pagsusuri mula sa maraming panimulang punto

get_task_context Matatag

Magsisimula ka bang magtrabaho sa isang hindi pamilyar na lugar? Ilarawan ang task (hal. "magdagdag ng SSO support", "ayusin ang billing webhook") at makakuha, sa iisang tawag, ng limitadong bundle ng mga kaugnay na file, code, symbol, at dependency. Ang mga file na ipinasa bilang seed ay nag-aambag ng direktang indexed na content kahit na wala silang natukoy na symbol. Nila-label ang mga layer na nabigo; ang kabuuang pagkabigo sa pagkuha ay nagbabalik ng tool error. Para sa mas maraming resulta, ituloy ang paggamit ng specialized na search tool para sa layer na iyon.

Mga Parameter:

task_description Kailangan
Uri
str minLength=1
Paglalarawan
Paglalarawan ng task na kailangan mong bigyan ng context
repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
15
Paglalarawan
Pinakamaraming resulta bawat layer
scope Opsyonal
Uri
Literal[semantic, symbols, dependencies, all]
Default
all
Paglalarawan
Mga context layer na isasama
language_filter Opsyonal
Uri
str
Paglalarawan
Language filter: kailangan ang scope=semantic na walang tahasang seeds o related context; hindi kayang ipatupad ng ibang layer indexes ang language filter.
path_filter Opsyonal
Uri
str
Paglalarawan
Prefix ng file path para sa semantic at keyword retrieval roots. Maaaring nasa labas ng prefix na ito ang mga tahasang seed; maaaring lumagpas sa hangganan ng directory ang graph context.
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch
include_related_context Opsyonal
Uri
bool
Default
false
Paglalarawan
Isama ang kaugnay na context mula sa katabing mga symbol
seed_symbol_ids Opsyonal
Uri
list[str] maxItems=20
Paglalarawan
Tahasang seed ng task: unang lumalabas sa symbol layer at pinananatili sa loob ng may-hangganang dependencies/related_context window. Sa graph layers, nauuna ang mga tahasang seed at ang pinakamalapit nilang kapitbahayan bago ang keyword fallback; ang kahalagahan ang nagpapasya lamang kapag magkapantay sa relevance. Kailangan ng graph expansion ang scope=all|dependencies (hindi kailanman pinapatakbo ng scope=symbols|semantic ang dependency traversal). Alisin ito para sa ranggo ayon sa keyword lang at sa kahalagahang bumababa sa lalim.
seed_file_paths Opsyonal
Uri
list[str] maxItems=10
Paglalarawan
Tahasang seeds: eksaktong mga indexed file path na bukas o kakatapos lang i-edit ng agent. Ibinabalik ang bounded direct file evidence at hanggang 5 graph seed bawat file, na inuuna ang eksaktong tugma sa pangalan ng task mula sa may-hangganang symbol lookup bago ang mga definition at ang mga di-sinasadyang simbolo. Nagbibigay pa rin ng ebidensiya ang mga file na walang simbolo. Ang mga nawawalang file ay maaaring magbalik ng mga naka-label na suhestiyon na hindi seed. Kailangan ng graph expansion ang scope=all|dependencies.

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_file Matatag

Magbasa ng file mula sa indexed repo gamit ang path. Mas mainam gamitin ang lokal na file tools para sa mga file na nasa disk; gamitin ito para sa remote indexed snapshots. Ipagpatuloy ang mga bounded na tugon gamit ang metadata.next_line_start at next_character_start. Alisin lamang ang trailing newline kasama ang [truncated] marker kapag metadata.truncated=true; kung hindi, maaaring literal na source text ito.

Mga Parameter:

file_path Kailangan
Uri
str
Paglalarawan
File path na relative sa repository root
repository Opsyonal
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. Uunahin ang eksaktong indexed branch; kapag hindi available ang isang branch, maaari itong bumalik sa main o sa nag-iisang naa-access na branch. Ipinapakita ng metadata ng tugon ang hiniling at ang aktwal na ginamit na identity, at nagbibigay ng babala kapag nangyari ito.
line_start Opsyonal
Uri
int minimum=1
Paglalarawan
Panimulang linya (1-indexed)
line_end Opsyonal
Uri
int minimum=1
Paglalarawan
End line (1-indexed, inclusive; dapat nasa line_start o pagkatapos nito)
character_start Opsyonal
Uri
int minimum=0
Default
0
Paglalarawan
Offset sa mga UTF-16 code unit sa loob lamang ng panimulang linya (0-indexed). Gamitin ang metadata.next_character_start upang ipagpatuloy ang linyang bahagyang nabasa.
branch Opsyonal
Uri
str
Paglalarawan
Pag-override sa branch
max_tokens Opsyonal
Uri
int minimum=1, maximum=50000
Default
5000
Paglalarawan
Tinatayang content budget (4 UTF-16 code units bawat token; hindi eksaktong limitasyon ng tokenizer).
include_metadata Opsyonal
Uri
bool
Default
true
Paglalarawan
Isama ang naglalarawang file metadata. Laging ibinabalik ang truncation at continuation 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_context Matatag

Naglilista ng mga repository na maaari mong hanapin, o kumukuha ng identity information ng isa (namespace/branch, indexed_commit_sha / kasariwaan ng index). Gamitin ang action:"list" kapag hindi alam ang slug ng repository; direktang tinatanggap ng mga search tool ang alam na slug o default na ginagamit ang nag-iisang repository ng iyong key. Gumagamit ang list ng pattern at pagination; kailangan ng info ang repository at sinusuportahan nito ang branch at opt-in na include_statistics=true.

Mga Parameter:

action Kailangan
Uri
Literal[list, info]
Paglalarawan
Action: ilista ang available na repo o kumuha ng impormasyon tungkol sa repo
repository Opsyonal
Uri
str
Paglalarawan
Para sa info lang: repository sa format na owner/repo o owner/repo:branch (required para sa info)
branch Opsyonal
Uri
str
Paglalarawan
Para sa info lang: pag-override sa branch
pattern Opsyonal
Uri
str
Paglalarawan
Para sa list lang: substring ng pangalan ng repository, hindi case-sensitive
include_statistics Opsyonal
Uri
bool
Default
false
Paglalarawan
Para sa impormasyon lamang: isama ang bounded indexed-data counts. Eksakto ang file/blob counts; estimate naman ang mas malalaking index counts. Basahin ang count_accuracy at estimate_analyzed_at. Default na false.
limit Opsyonal
Uri
int minimum=1, maximum=50
Default
20
Paglalarawan
Pinakamataas na bilang ng resulta bawat page kung walang cursor. Ginagamit ng pagpapatuloy ang page size na naka-imbak sa cursor; laktawan ang cursor para magsimula na may ibang limit.
offset Opsyonal
Uri
int minimum=0
Paglalarawan
Deprecated na compatibility offset. Mas piliin ang cursor mula sa pagination.next_cursor.
cursor Opsyonal
Uri
str
Paglalarawan
Opaque na cursor mula sa pagination.next_cursor. Ipasa ito nang hindi binabago at panatilihing hindi nagbabago ang query at mga filter. Ang posisyon at page size nito ang mananaig kaysa sa offset at limit.

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_maguyva Matatag

Kumuha ng gabay sa mga tool ng Maguyva o magsumite ng ulat ng bug o hiling na feature na itatago para sa mga tagapangalaga ng Maguyva. Huwag magsama ng mga sikreto o sensitibong personal na datos sa puna. Sinusuportahan ng evaluate ang mga deterministikong expression; mas piliin ang lokal na pagkalkula o mga tool ng host para sa math/hash/string.

Mga Parameter:

operation Kailangan
Uri
Literal[guidance, report_bug, request_feature, evaluate]
Paglalarawan
Gamitin ang guidance para sa tulong sa tool, report_bug para sa mga bug, o request_feature para sa mga mungkahi. Nagpapatakbo ang evaluate ng mga deterministikong expression; mas piliin ang lokal na pagkalkula para sa mga kalkulasyon.
query Opsyonal
Uri
str maxLength=500
Paglalarawan
Paksa ng gabay (hal. tool_selection, semantic_search), o string ng expression para sa evaluate.
description Opsyonal
Uri
str minLength=1, maxLength=4000
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_tool Opsyonal
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")
  • Mga naka-save na bug report at feature request para sa mga maintainer ng Maguyva

Hindi Inirerekomenda Para sa:

  • Pagkalkula ng math/hash/string — mas piliin ang lokal na pagkalkula o mga tool ng host

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: Ang repository_context ay tumutugma sa mga pangalan ng repository nang hindi isinasaalang-alang ang case — hindi nito itinatama ang typo. Kapag naiiba ang identity na inihahain sa hiniling, iniuulat ng metadata.resolution_reason ang "defaulted" (walang hiniling na branch) o "fallback" (hindi available ang hiniling na branch o repository). Inaalis ito kapag eksaktong tumugma ang hiling.
  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: Tawagin ang ask_maguyva gamit ang operation="guidance" at query="tool_selection" para sa payo at halimbawa sa pagpili ng tool. Gamitin ang mga lokal mong tool para sa pagkalkula at pagbabago ng mga string.
  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 saklaw ng epekto 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. Naka-index na graph ang sinusuri nito, hindi ang mga lokal na pagbabagong hindi pa naka-commit, at hindi nito pinapalitan ang mga lokal na test. Tingnan ang indexed_commit_sha at kung gaano kabago ang index bago ituring ang resulta bilang ebidensiya para sa bagong revision.

Mga Katangian sa Performance

#
Operasyon Mga tala sa performance
Semantic search Kasama ang paggawa ng embedding ng query at pagkuha ng resulta mula sa mga vector. Nakadepende ang tagal sa parehong operasyon.
Text search Sa fuzzy na paghahanap sa nilalaman, mas maraming kandidato ang kinukuha sa mas malalim na mga pahina. Paliitin ang query gamit ang path_filter at language_filter.
Structural search Nagtatanong sa mga naka-index na AST node. Gumamit ng tiyak na preset o pattern at limitahan ang bilang ng resulta.
Dependency search Nakabatay ang cost 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 file Basahin ang bahaging kailangan gamit ang line_start/line_end o max_tokens, at gamitin ang ibinalik na continuation metadata para sa naputol na nilalaman.
Repository context Nire-resolve ang repository sa bawat tawag ng tool. Tahasang ipasa ang repository kapag kailangan mo ng partikular na repository.
ask_maguyva (guidance / evaluate) Tumatakbo sa MCP server nang hindi nagtatanong sa index ng repository.

Pag-handle ng Error

#

Nasa pinakamataas na antas ng tugon ng tool ang mga karaniwang status field at mga payload field na partikular sa tool. Nagbabalik ng results ang paghahanap; content naman ang ibinabalik ng get_file. Kabilang sa mga karaniwang field ang:

  • status: String — "success" o "error". May sariling field ang degraded-match at freshness signal: metadata.resolution_reason sa ilalim ng metadata, at top-level na index_freshness.status sa info action ng repository_context.
  • timing_ms: Tagal ng pagpapatakbo ng tool sa millisecond
  • applied_filters: Mga aktuwal na parameter ng request na naitala para sa operasyon
  • error: String ng mensahe ng error kapag "error" ang status; maaari itong may gabay sa pag-recover.
  • metadata: Karagdagang impormasyon tungkol sa operation (routing, caching, parameter adjustments)
  • pagination: Makikita sa mga tugon para sa koleksiyong gumagamit ng cursor paging — kasama ang has_more at next_cursor. Ang mga niranggong resulta ng paghahanap ay limitadong top-K, hindi kumpletong koleksiyong nahahati sa mga pahina.

I-check ang status field bago i-process ang payload ng tool — ang value nito ay "success" o "error". Asikasuhin din ang MCP/JSON-RPC transport at request-validation error, na maaaring mangyari bago pa mabuo ang payload ng tool. Para sa degraded-match o freshness signal, basahin ang nakalaang field: metadata.resolution_reason sa ilalim ng metadata, o top-level na index_freshness.status sa info action ng repository_context (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.

Kaugnay

Susunod na babasahin