Lompat ke konten

Referensi API MCP

Jelajahi 11 alat MCP Maguyva, parameternya, dan kapan setiap alat digunakan. Periksa respons tools/list dari klien yang terhubung untuk mengetahui argumen yang tersedia.

Gambaran Umum API

#

Alat dikelompokkan dalam 4 kategori:

  • Tool Pencarian Inti - Kemampuan pencarian tingkat lanjut di seluruh codebase Anda
  • Tool Struktural & Graf - Query AST, pencarian simbol, dan analisis dependensi
  • Tool Analisis Kode - Analisis kode mendalam dan pemetaan relasi
  • Tool Sistem & Utilitas - Konteks repositori, panduan alat, dan umpan balik

Untuk alat yang menerima repositori, gunakan format pengidentifikasi repository ini: "owner/repo:branch". Cabang default adalah main jika tidak ditentukan.

Jangan sertakan repository ketika klien MCP Anda menyediakan default untuk permintaan tersebut atau kunci dapat mengakses tepat satu repository; jika tidak, berikan secara eksplisit. Gunakan repository_context(action="info", repository="owner/repo") untuk memeriksa bagaimana sebuah repository ditentukan.

Format Parameter Repository

#

Gunakan format berikut saat menentukan repositori:

  • Dengan branch: "owner/repo:branch" - misalnya, "owner/repository:develop"
  • Branch default: "owner/repo" - menggunakan branch main bila tidak ada branch yang ditentukan "owner/repository"
  • Default permintaan atau satu-satunya repository: Jangan sertakan repository jika klien MCP menyediakan default untuk permintaan tersebut atau key hanya dapat mengakses tepat satu repository; jika tidak, berikan secara eksplisit.

Contoh prompt:

Tanyakan tentang repo tertentu:  "Cari middleware autentikasi di owner/my-repo"
Daftar repo yang dapat diakses:  "Repository mana yang dapat diakses key Maguyva ini?"
Menimpa untuk satu query:        "Cari pola autentikasi di owner/other-repo:develop"

Filter Bahasa

#

Gunakan language_filter pada mode pencarian yang mendukungnya. Untuk text_pattern_search, pilih search_scope="content"; untuk get_task_context, gunakan scope="semantic" tanpa titik awal maupun konteks terkait.

  • language_filter="python" - Filter hanya ke file Python
  • language_filter="typescript" - Filter hanya ke file TypeScript
  • Peka huruf besar/kecil: Gunakan nama bahasa huruf kecil
  • Default: String kosong (tanpa filter) - mengembalikan hasil dari semua bahasa
  • Cakupan yang didukung: Filter bahasa bekerja di seluruh 285+ bahasa dan teknologi berbasis teks yang didukung. Lihat kompatibilitas untuk daftar lengkapnya. 
"Temukan middleware autentikasi hanya di file Python"
"Cari koneksi database di TypeScript"

Referensi API dibuat dari kode sumber pada 21 Oktober 2026.

Tool Pencarian Inti

#

intelligent_search Stabil

Mulai di sini untuk pertanyaan apa pun tentang basis kode. Pengaturan bawaan auto/balanced mengarahkan kueri yang dikenali dengan keyakinan tinggi sebagai pencarian definisi ke pencarian struktural, pertanyaan tentang referensi atau dampak ke graf, dan pertanyaan tentang kecocokan persis ke pencarian teks. Pertanyaan lainnya menggunakan makna semantik dan teks yang diindeks. Gunakan mode=hybrid atau auto dengan quality=thorough untuk meminta keempat modalitas pencarian. Mode yang dipilih secara eksplisit didahulukan daripada quality. language_filter menghilangkan graf dari auto/hybrid dan ditolak saat mode=graph dipilih secara eksplisit. Utamakan alat ini daripada Grep/Glob jika Anda belum mengetahui path-nya.

Parameter:

query Wajib
Tipe
str minLength=1
Deskripsi
Kueri pencarian
repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
mode Opsional
Tipe
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Default
auto
Deskripsi
Mode pencarian
limit Opsional
Tipe
int minimum=1, maximum=50
Default
10
Deskripsi
Jumlah maksimum hasil dalam jendela top-K yang diberi peringkat ini
language_filter Opsional
Tipe
str
Deskripsi
Filter bahasa
path_filter Opsional
Tipe
str
Deskripsi
Memfilter kandidat pencarian berdasarkan prefix jalur file. Simpul tetangga dalam graf dan konteks komunitas yang dilampirkan dapat mencakup file di luar prefix ini.
boost_by_importance Opsional
Tipe
bool
Default
false
Deskripsi
Opsional: susun ulang berdasarkan centrality menggunakan metrik graf per simbol (is_articulation_point, bridge_count, k_core, centrality, dll.). Default nonaktif untuk peringkat yang aman bagi agen (hub global bisa menenggelamkan hasil implementasi); aktifkan untuk tur arsitektur. Berlaku di semua 4 modalitas ketika setiap hasil memiliki keterkaitan dengan simbol.
branch Opsional
Tipe
str
Deskripsi
Override branch
quality Opsional
Tipe
Literal[quick, balanced, thorough]
Default
balanced
Deskripsi
Preset kualitas pencarian
include_content Opsional
Tipe
bool
Default
true
Deskripsi
Sertakan konten dalam hasil
explain_routing Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan penjelasan keputusan routing
importance_weight Opsional
Tipe
float minimum=0, maximum=1
Default
0.3
Deskripsi
Bobot untuk boosting kepentingan (0=tidak, 1=penuh)
orphans Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan simbol orphan (tanpa referensi masuk)
include_community_context Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan simbol terkait dari komunitas kode yang sama
community_depth Opsional
Tipe
int minimum=1, maximum=3
Default
1
Deskripsi
Kedalaman perluasan konteks komunitas
graph_view Opsional
Tipe
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Deskripsi
Tampilan graf untuk metrik
seed_symbol_ids Opsional
Tipe
list[str] maxItems=20
Deskripsi
Titik awal tugas Tier-1: ID simbol yang menjadi inti tugas saat ini. Jika parameter ini diisi, hasil gabungan diberi peringkat ulang berdasarkan kedekatan dengan bobot yang menurun seiring kedalaman menurut Approach A (kecocokan persis dengan simbol awal + lompatan melalui sisi graf). Ini sinyal tambahan — jangan sertakan parameter ini untuk memakai peringkat global.
seed_file_paths Opsional
Tipe
list[str] maxItems=10
Deskripsi
Titik awal tugas Tier-1: jalur file terindeks yang sedang dibuka atau baru saja diedit agen. Jika parameter ini diisi, hasil gabungan diberi peringkat ulang berdasarkan kedekatan jalur dengan bobot yang menurun seiring kedalaman menurut 1/(1+d) (file yang sama → direktori yang sama → paket terdekat). Ini sinyal tambahan — jangan sertakan parameter ini untuk memakai peringkat global.

Paling Cocok Untuk:

  • Eksplorasi seluruh indeks atau dari awal ketika tool yang tepat belum jelas
  • Pemeringkatan gabungan multimodal dari pencarian semantik, teks, struktural, dan graf

Tidak Direkomendasikan Untuk:

  • Nama symbol yang sudah diketahui — langsung gunakan find_symbol
  • Path yang sudah diketahui di disk — gunakan local Read/Grep dulu

semantic_search Stabil

Temukan kode berdasarkan makna, bukan teks persis. Gunakan untuk kueri konseptual seperti 'logika percobaan ulang' atau 'alur pengenalan pengguna' saat kata kunci atau nama simbol belum diketahui. Mengembalikan potongan relevan dengan keragaman berkas yang dibatasi; pemeringkatan ulang berdasarkan kepentingan graf diaktifkan melalui boost_by_importance. Utamakan daripada Grep untuk pencarian konseptual.

Parameter:

query Wajib
Tipe
str minLength=1
Deskripsi
Query pencarian (konseptual, berbasis makna)
repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
limit Opsional
Tipe
int minimum=1, maximum=50
Default
5
Deskripsi
Jumlah maksimum hasil dalam jendela top-K yang diberi peringkat ini
similarity_threshold Opsional
Tipe
float minimum=0, maximum=1
Default
0.6
Deskripsi
Skor kesamaan minimum
language_filter Opsional
Tipe
str
Deskripsi
Filter bahasa (python, typescript, dll.)
path_filter Opsional
Tipe
str
Deskripsi
Filter berdasarkan prefix jalur file
boost_by_importance Opsional
Tipe
bool
Default
false
Deskripsi
Opsional: peringkat ulang berdasarkan kepentingan graf ternormalisasi per simbol (bawaan nonaktif; dibatasi hingga 1,5 kali kemiripan).
branch Opsional
Tipe
str
Deskripsi
Override branch (default: dari parameter repository atau main)
include_content Opsional
Tipe
bool
Default
true
Deskripsi
Sertakan konten cuplikan dalam hasil
graph_view Opsional
Tipe
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Deskripsi
Tampilan graf untuk metrik

Paling Cocok Untuk:

  • Kueri konseptual ("bagaimana autentikasi bekerja?", "strategi cache")
  • Pencarian kemiripan lintas-paket

Tidak Direkomendasikan Untuk:

  • Nama symbol yang sudah diketahui — gunakan find_symbol
  • String persis atau pesan error — gunakan text_pattern_search

text_pattern_search Stabil

Cari konten terindeks. exact dan regex menjalankan grep pada seluruh korpus berkas/blob; fuzzy content mencari pada korpus potongan semantik yang dibatasi. Cakupan file dan symbol hanya memakai trigram — mode=exact bawaan diubah menjadi fuzzy. Kontrol bahasa, kapitalisasi, dan ambang khusus memerlukan cakupan content. Filter jalur berkas memakai jendela kandidat terbatas dan melaporkan cakupan yang tidak lengkap. Gunakan Grep lokal untuk direktori sempit yang sudah ada di disk.

Parameter:

query Wajib
Tipe
str minLength=1
Deskripsi
Pola teks untuk dicari
repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
mode Opsional
Tipe
Literal[fuzzy, exact, regex]
Default
exact
Deskripsi
Mode pencarian. Regex menjalankan sintaks lanjutan/POSIX PostgreSQL; gunakan \y untuk batas kata (\b berarti backspace). Pola juga melewati validator keamanan JavaScript, sehingga konstruksi khusus PostgreSQL seperti flag (?i) inline ditolak; gunakan case_sensitive sebagai gantinya.
search_scope Opsional
Tipe
Literal[content, symbols, files]
Default
content
Deskripsi
Apa yang dicari
limit Opsional
Tipe
int minimum=1, maximum=50
Default
5
Deskripsi
Jumlah maksimum hasil per halaman tanpa cursor. Kelanjutan menggunakan ukuran halaman yang tersimpan di cursor; abaikan cursor untuk mulai dengan limit berbeda.
offset Opsional
Tipe
int minimum=0
Deskripsi
Offset kompatibilitas yang sudah usang. Utamakan cursor dari pagination.next_cursor.
cursor Opsional
Tipe
str
Deskripsi
cursor buram dari pagination.next_cursor. Teruskan tanpa perubahan dan pertahankan query serta filter tetap sama. Posisi dan ukuran halamannya menggantikan offset dan limit.
language_filter Opsional
Tipe
str
Deskripsi
Filter bahasa
path_filter Opsional
Tipe
str
Deskripsi
Filter berdasarkan awalan jalur file
case_sensitive Opsional
Tipe
bool
Default
false
Deskripsi
Pencocokan peka huruf besar/kecil
branch Opsional
Tipe
str
Deskripsi
Override branch
fuzzy_algorithm Opsional
Tipe
Literal[hybrid, trigram, levenshtein]
Default
hybrid
Deskripsi
Algoritma pencocokan fuzzy
threshold Opsional
Tipe
float minimum=0, maximum=1
Default
0.05
Deskripsi
Ambang kesamaan minimum untuk fuzzy
semantic_fallback Opsional
Tipe
bool
Default
false
Deskripsi
Mencoba semantic search setelah halaman lexical pertama kosong; metadata.fallback_status membedakan status fallback used, empty, dan unavailable.

Paling Cocok Untuk:

  • String persis, pesan error, dan regex
  • Pencocokan trigram fuzzy untuk teks yang hampir mirip

Tidak Direkomendasikan Untuk:

  • Path yang sudah diketahui di disk — utamakan local Grep
  • Kueri konseptual — gunakan semantic_search

Tool Struktural & Graf

#

structural_search Stabil

Utamakan preset=functions|classes|methods|imports|variables atau pattern= bebas. Temukan kode berdasarkan bentuk AST, bukan teks. Filter tingkat menengah: name_pattern, node_type, decorator, parent_child. Filter jalur, ltree, dan panggilan adalah tingkat lanjut; atur advanced=true saat sengaja memakainya. Tanpa itu, filter lanjutan tetap diterapkan dengan peringatan pada metadata. Berikan setidaknya satu pemilih struktural.

Parameter:

repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
preset Opsional
Tipe
Literal[functions, classes, methods, imports, variables]
Deskripsi
Structural selector yang disarankan. Meluas ke tipe node AST lintas bahasa — functions (definisi function/arrow/method di berbagai bahasa); classes (deklarasi class/struct/interface, badan tipe, dan implementasi); methods (definisi method (dan function_definition untuk bahasa tanpa node method)); imports (pernyataan import/use/include); variables (deklarasi variable/let/const/static). Utamakan ini daripada pattern/node_type bebas untuk query bergaya browse.
pattern Opsional
Tipe
str
Deskripsi
pattern bebas mengisi selector yang hilang (deteksi otomatis: 'def foo(' → node_type + name_pattern). Bisa dikombinasikan dengan preset; selector eksplisit lebih diutamakan. Gunakan preset= untuk query browsing.
name_pattern Opsional
Tipe
str maxLength=256
Deskripsi
Pattern nama symbol (wildcard shell, regex POSIX terbatas, atau teks fuzzy; maksimal 256 karakter)
node_type Opsional
Tipe
str
Deskripsi
Tipe node AST (function_definition, class_definition, dll.) — utamakan preset= untuk bentuk umum
decorator Opsional
Tipe
str
Deskripsi
Filter nama decorator
base_class Opsional
Tipe
str
Deskripsi
Filter nama base class
language_filter Opsional
Tipe
str
Deskripsi
Filter bahasa (python, typescript, dll.)
limit Opsional
Tipe
int minimum=1, maximum=50
Default
20
Deskripsi
Jumlah maksimum hasil per halaman tanpa cursor. Kelanjutan menggunakan ukuran halaman yang tersimpan di cursor; abaikan cursor untuk mulai dengan limit berbeda.
offset Opsional
Tipe
int minimum=0
Deskripsi
Offset kompatibilitas yang sudah usang. Utamakan cursor dari pagination.next_cursor.
cursor Opsional
Tipe
str
Deskripsi
cursor buram dari pagination.next_cursor. Teruskan tanpa perubahan dan pertahankan query serta filter tetap sama. Posisi dan ukuran halamannya menggantikan offset dan limit.
path_filter Opsional
Tipe
str
Deskripsi
Filter berdasarkan awalan jalur file
branch Opsional
Tipe
str
Deskripsi
Override branch
query_type Opsional
Tipe
Literal[node_type, name_pattern, parent_child]
Deskripsi
Tipe query eksplisit
parent_type Opsional
Tipe
str
Deskripsi
Filter jenis node induk AST
relationship Opsional
Tipe
Literal[parent, ancestor]
Default
parent
Deskripsi
Untuk kueri parent_child: hanya simpul induk langsung atau leluhur mana pun (gunakan ancestor untuk metode kelas yang bersarang dalam badan/blok kelas)
has_modifier Opsional
Tipe
str
Deskripsi
Filter berdasarkan modifier (export, async, static, dll.)
advanced Opsional
Tipe
bool
Default
false
Deskripsi
Atur true saat sengaja memakai filter jalur, ltree, atau panggilan tingkat lanjut (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Saat false, filter lanjutan yang diberikan tetap diterapkan dengan peringatan metadata. Utamakan preset= untuk kueri struktural umum.
callee_text Opsional
Tipe
str
Deskripsi
Tingkat lanjut — utamakan preset=functions|classes|methods|imports|variables. Filter teks objek yang dipanggil (callee) dalam ekspresi pemanggilan. Atur advanced=true saat sengaja menggunakan filter jalur/ltree/pemanggilan.
callee_name Opsional
Tipe
str
Deskripsi
Tingkat lanjut — utamakan preset=functions|classes|methods|imports|variables. Filter nama objek yang dipanggil (callee) dalam ekspresi pemanggilan. Atur advanced=true saat sengaja menggunakan filter jalur/ltree/pemanggilan.
field_role Opsional
Tipe
str
Deskripsi
Tingkat lanjut — utamakan preset=functions|classes|methods|imports|variables. Filter peran field AST. Atur advanced=true saat sengaja menggunakan filter jalur/ltree/pemanggilan.
ltree_ancestor Opsional
Tipe
str
Deskripsi
Tingkat lanjut — utamakan preset=functions|classes|methods|imports|variables. Filter jalur leluhur AST berbasis ltree. Atur advanced=true saat sengaja menggunakan filter jalur/ltree/pemanggilan.
ltree_descendant Opsional
Tipe
str
Deskripsi
Tingkat lanjut — utamakan preset=functions|classes|methods|imports|variables. Filter jalur turunan AST berbasis ltree. Atur advanced=true saat sengaja menggunakan filter jalur/ltree/pemanggilan.
definition_name Opsional
Tipe
str
Deskripsi
Tingkat lanjut — utamakan preset=functions|classes|methods|imports|variables. Filter nama definisi. Atur advanced=true saat sengaja menggunakan filter jalur/ltree/pemanggilan.
min_depth Opsional
Tipe
int
Deskripsi
Tingkat lanjut — utamakan preset=functions|classes|methods|imports|variables. Kedalaman minimum AST. Atur advanced=true saat sengaja menggunakan filter jalur/ltree/pemanggilan.
max_depth Opsional
Tipe
int
Deskripsi
Tingkat lanjut — utamakan preset=functions|classes|methods|imports|variables. Kedalaman maksimum AST. Atur advanced=true saat sengaja menggunakan filter jalur/ltree/pemanggilan.

Paling Cocok Untuk:

  • Struktur tingkat AST: class, decorator, preset function/method
  • Menemukan kode berdasarkan bentuk, bukan teks

Tidak Direkomendasikan Untuk:

  • Kueri free-text atau konseptual — gunakan semantic_search atau intelligent_search

dependency_search Stabil

Tool utama untuk analisis cakupan dampak dan graf. Menjawab "apa yang memanggil simbol ini?" / "apa yang digunakan oleh simbol ini?" melalui graf pemanggilan/impor yang sesungguhnya. Untuk analisis dampak sebelum mengedit: analysis_type="dependents" atau analysis_type="impact" (relasi masuk, default shallow untuk impact), dengan include_metrics=false secara default (aktifkan untuk centrality + refactor_risk). dependents/impact menyertakan production_callers secara default: lokasi penggunaan produksi unik menurut jenis (call, instantiate, value_reference untuk fungsi yang diteruskan sebagai nilai), serta lokasi IMPORT, kode tes dikecualikan, dengan tingkat keyakinan EXTRACTED/INFERRED — bukan sekadar kumpulan metrik. Untuk analisis dampak PR/diff, kirim changed_paths dan/atau patch (unified diff): tool menemukan simbol per jalur dan mengembalikan respons ringkas tentang kode yang bergantung pada simbol tersebut melalui penelusuran dangkal atas relasi masuk, tanpa memerlukan nama simbol. Setelah mengedit, atur verify_after_edit=true dengan targets dan/atau changed_paths untuk mengueri ulang simbol terdampak secara ringkas dari beberapa titik awal. Juga mendukung dependencies, centrality, dan orphans. analyze_dependencies memakai penelusuran yang sama untuk analisis dampak beberapa lompatan.

Parameter:

repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
query Opsional
Tipe
str
Deskripsi
Nama simbol atau istilah pencarian
target Opsional
Tipe
str
Deskripsi
Nama simbol (alias untuk query)
symbol_id Opsional
Tipe
UUID
Deskripsi
Pilih kemunculan tertentu dengan UUID dari kandidat yang cocok dengan nama dalam query/target setelah penyaringan berdasarkan namespace, jalur, dan bahasa. Gunakan ID yang dikembalikan oleh find_symbol atau hasil alternatif graf. Hanya untuk penelusuran dengan nama yang ditentukan; ID di luar jendela kandidat yang dibatasi akan menghasilkan kesalahan.
changed_paths Opsional
Tipe
list[str] maxItems=50
Deskripsi
Jalur file persis yang relatif terhadap root repositori untuk analisis dampak PR/diff (default) atau, dengan verify_after_edit=true, sebagai titik awal verifikasi pasca-edit. Jalur yang tidak dapat diselesaikan dapat mengembalikan saran berlabel; file yang disarankan tidak pernah menjadi akar dampak. PR/diff: tanpa info baris, menelusuri definisi tingkat atas di setiap jalur (yang diekspor lebih dulu, sesuai urutan file) dan melaporkan changed_lines_unknown; berikan patch= untuk simbol yang berubah per baris. Verifikasi: hingga 5 definisi tingkat atas per jalur sebagai titik awal verifikasi (batas maksimumnya lebih rendah dalam mode verifikasi). Analisis dampak PR/diff tidak memerlukan query/target.
patch Opsional
Tipe
str maxLength=500000
Deskripsi
Analisis dampak PR/diff: teks dalam format unified diff / git patch. Jalur diambil dari header diff --git / --- / +++; baris hunk (sisi lama = commit yang diindeks) dipetakan ke fungsi/metode/kelas yang melingkupinya, lalu ditelusuri untuk mendapatkan dependen yang tepat, public_api_changed, dan pemanggil yang tidak tersentuh diff.
head_commit Opsional
Tipe
str pattern=^[0-9a-fA-F]{7,64}$
Deskripsi
SHA commit dari kode yang Anda tanyakan (git rev-parse HEAD, atau base commit dari patch). complete:true mensyaratkan index berada di commit ini dan dibangun oleh resolver saat ini; jika tidak, tetap complete:false dengan index_stale / index_freshness_unverified / index_built_by_older_resolver, dan index_basis.statement menyebutkan dalam cakupan apa jawabannya lengkap. Baris 'base-commit:' pada patch (git format-patch --base) juga menyediakannya.
analysis_type Opsional
Tipe
Literal[centrality, dependencies, dependents, impact, orphans]
Default
dependencies
Deskripsi
Mode analisis. impact = cakupan dampak (kode yang bergantung pada simbol melalui relasi masuk; kedalaman shallow jika depth tidak diisi). dependents juga memberikan analisis dampak. Jika changed_paths atau patch diisi, analisis dipaksa menjadi analisis dampak PR/diff. centrality/orphans tidak memerlukan target. orphans adalah kandidat kode yang tidak terpakai, bukan bukti bahwa kode itu aman dihapus; verifikasi referensinya di kode sumber.
depth Opsional
Tipe
Literal[shallow, balanced, deep]
Deskripsi
Kedalaman traversal. Defaultnya balanced; impact dan PR/diff impact default ke shallow. depth eksplisit menggantikan default ini. Mode verifikasi selalu menggunakan shallow.
limit Opsional
Tipe
int minimum=1, maximum=50
Default
20
Deskripsi
Jumlah maksimum hasil per halaman tanpa cursor. Kelanjutan menggunakan ukuran halaman yang tersimpan di cursor; abaikan cursor untuk mulai dengan limit berbeda.
offset Opsional
Tipe
int minimum=0
Deskripsi
Offset kompatibilitas yang sudah usang. Utamakan cursor dari pagination.next_cursor.
cursor Opsional
Tipe
str
Deskripsi
cursor buram dari pagination.next_cursor. Teruskan tanpa perubahan dan pertahankan query serta filter tetap sama. Posisi dan ukuran halamannya menggantikan offset dan limit.
path_filter Opsional
Tipe
str
Deskripsi
Membatasi resolusi target symbol berdasarkan prefix file path; relasi graf yang dikembalikan bisa melintas keluar dari path tersebut
language_filter Opsional
Tipe
str
Deskripsi
Filter resolusi target dan hasil browse berdasarkan bahasa
direction Opsional
Tipe
Literal[outgoing, incoming, both]
Deskripsi
Arah traversal (menimpa inferensi analysis_type)
relationship_types Opsional
Tipe
list[str]
Deskripsi
Filter tipe edge (CALL, IMPORT, INHERITS_FROM, dll.). Daftar yang tidak kosong menggantikan default graph_view.
exclude_test_paths Opsional
Tipe
bool
Default
true
Deskripsi
Default true: mengecualikan path test, fixture, vendor, dan contoh dari hasil traversal dan centrality. Atur false untuk menyertakannya. Analisis orphan hanya mematuhi pengaturan ini jika backend yang di-deploy mendukungnya; jika tidak, analisis tersebut mempertahankan pengecualian noise-nya sendiri yang lebih ketat dan melaporkan penyesuaiannya.
exclude_generated_paths Opsional
Tipe
bool
Default
false
Deskripsi
Kecualikan deklarasi yang dihasilkan secara otomatis serta jalur artefak build, laporan cakupan pengujian, cache, peta kode sumber, dan file hasil minifikasi dari hasil penelusuran
include_module_symbols Opsional
Tipe
bool
Default
false
Deskripsi
Default false: kecualikan sisi graf yang from_name atau to_name-nya merupakan simbol sintetis __module__ (noise tingkat modul). Atur true untuk menyertakan sisi tingkat modul dalam hasil dependents/dependencies.
include_isolated Opsional
Tipe
bool
Deskripsi
Khusus orphan. Default false. Atur true untuk juga mengembalikan simbol tanpa baris metrik graf (tanpa sisi graf sama sekali). Selama exclude_test_paths bernilai true, simbol stylesheet/markup/data (CSS, HTML, ...), deklarasi .d.ts, serta path test/fixture/vendor/example tetap dikecualikan jika backend mendukungnya, kecuali language_filter menyebut bahasa tersebut; properti object literal TypeScript masih dapat muncul sebagai fungsi terisolasi.
exclude_exported Opsional
Tipe
bool
Default
false
Deskripsi
Hanya untuk simbol yatim. Default false: simbol yang diekspor (API publik) yang tidak dipakai dalam repositori dikembalikan dengan is_exported=true. Atur true untuk kandidat internal saja.
branch Opsional
Tipe
str
Deskripsi
Override branch
per_hop_limit Opsional
Tipe
int minimum=1, maximum=300
Deskripsi
Jumlah maksimum relationship per hop (1-300)
include_metrics Opsional
Tipe
bool
Default
false
Deskripsi
Metrik graf opt-in pada baris hasil (dipadatkan dengan refactor_risk). Metrics juga diambil secara internal ketika min_centrality>0 tetapi tidak dikembalikan kecuali ini true.
metrics_detail Opsional
Tipe
Literal[summary, full]
Default
summary
Deskripsi
Ketika include_metrics=true: summary (default) mengembalikan sinyal keputusan + refactor_risk; full mengembalikan kumpulan metrik hasil kurasi yang lebih besar
include_edge_metadata Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan metadata mentah dan bobot sisi graf (berukuran besar). Respons analisis dampak yang ringkas membiarkan parameter ini nonaktif.
symbol_types Opsional
Tipe
list[str]
Deskripsi
Memfilter symbol yang dikembalikan berdasarkan jenis (function, class, method, dll). Tidak didukung pada analisis orphan; gunakan path_filter atau language_filter di sana. List kosong tidak menerapkan filter jenis apa pun.
exact_match Opsional
Tipe
bool
Default
false
Deskripsi
Wajibkan pencocokan nama simbol persis
find_similar_patterns Opsional
Tipe
bool
Default
false
Deskripsi
Temukan pola penggunaan serupa
min_centrality Opsional
Tipe
float minimum=0
Default
0
Deskripsi
Skor PageRank minimum untuk penelusuran simbol bernama dan analisis dampak PR/diff. Ambang batas positif tidak didukung dalam mode browse centrality/orphans. Metrics diambil secara internal untuk filtering; graph_metrics hanya dikembalikan ketika include_metrics=true. Diabaikan oleh verify_after_edit, yang memakai kontrol ringkas tetap.
graph_view Opsional
Tipe
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Deskripsi
Tampilan graf yang digunakan untuk default relationship traversal, metrics, dan peringkat centrality; analisis orphan dihitung di semua view
verify_after_edit Opsional
Tipe
bool
Default
false
Deskripsi
Meng-query ulang graf dampak yang terindeks untuk symbol yang diedit dalam satu respons multi-root yang ringkas. Membutuhkan targets dan/atau changed_paths (atau target/query). Menggunakan traversal shallow tetap dan anggaran ringkas; kontrol depth/limit/cursor/metrics tidak berlaku. Default mengembalikan incoming dependents; hasil mencerminkan graf terindeks (bisa tertinggal dari edit langsung). Jika true, lebih diutamakan daripada PR/diff impact untuk changed_paths yang sama.
targets Opsional
Tipe
list[str] maxItems=15
Deskripsi
Ketika verify_after_edit=true: nama simbol untuk diverifikasi ulang (kode yang memanggilnya atau bergantung padanya). Digabungkan dengan target/query jika keduanya disediakan.

Paling Cocok Untuk:

  • Analisis cakupan dampak sebelum mengedit simbol yang dipakai bersama
  • Analisis dampak PR/diff lewat changed_paths atau patch
  • Verifikasi pasca-edit lewat verify_after_edit

Tidak Direkomendasikan Untuk:

  • Pencarian text atau symbol sederhana — gunakan text_pattern_search atau find_symbol

Tool Analisis Kode

#

find_symbol Stabil

Lompat ke lokasi definisi dan penggunaan fungsi, class, atau variabel. Gunakan ketika Anda tahu nama (mis. "getCurrentUser") — lebih cepat dan presisi daripada Grep, serta mencakup seluruh repo terindeks. Opsional mengembalikan referensi dan metrik kepentingan.

Parameter:

symbol_name Opsional
Tipe
str
Deskripsi
Nama simbol untuk dicari (opsional — kosongi untuk menelusuri berdasarkan metrik)
repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
scope Opsional
Tipe
Literal[definitions, references, both]
Default
both
Deskripsi
Cakupan pencarian; references membutuhkan symbol_name yang tidak kosong.
limit Opsional
Tipe
int minimum=1, maximum=50
Default
15
Deskripsi
Jumlah maksimum hasil per halaman tanpa cursor. Kelanjutan menggunakan ukuran halaman yang tersimpan di cursor; abaikan cursor untuk mulai dengan limit berbeda.
offset Opsional
Tipe
int minimum=0
Deskripsi
Offset kompatibilitas yang sudah usang. Utamakan cursor dari pagination.next_cursor.
cursor Opsional
Tipe
str
Deskripsi
cursor buram dari pagination.next_cursor. Teruskan tanpa perubahan dan pertahankan query serta filter tetap sama. Posisi dan ukuran halamannya menggantikan offset dan limit.
find_similar Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan nama simbol serupa
include_metrics Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan metrik centrality
metrics_detail Opsional
Tipe
Literal[summary, full]
Default
summary
Deskripsi
Ketika include_metrics=true: summary (default) mengembalikan sinyal keputusan + refactor_risk; full mengembalikan kumpulan metrik hasil kurasi yang lebih besar
path_filter Opsional
Tipe
str
Deskripsi
Filter berdasarkan awalan jalur file
branch Opsional
Tipe
str
Deskripsi
Override branch
symbol_type Opsional
Tipe
str minLength=1
Deskripsi
Filter berdasarkan jenis simbol yang diindeks, mis. function, class, struct, enum, atau trait. Gunakan jenis yang dikembalikan oleh hasil simbol; jenis bervariasi menurut bahasa.
high_impact Opsional
Tipe
bool
Default
false
Deskripsi
Jelajahi simbol yang penting secara arsitektural (jangan sertakan symbol_name). Mode default adalah popularity (desil PageRank teratas, tidak termasuk simpul kode utilitas dengan sangat banyak koneksi). Atur high_impact_mode=risk untuk titik artikulasi/simpul pemutus yang menghubungkan bagian-bagian graf.
high_impact_mode Opsional
Tipe
Literal[popularity, risk]
Default
popularity
Deskripsi
Ketika high_impact=true: popularity = desil PageRank teratas, tidak termasuk simpul/modul utilitas dengan sangat banyak koneksi; risk = titik artikulasi yang diberi peringkat berdasarkan SMV bridge_count lalu k_core (risiko refaktor struktural, bukan popularitas simpul)
in_cycle Opsional
Tipe
bool
Default
false
Deskripsi
Memfilter symbol dengan keanggotaan siklus dependensi yang tercatat.
exclude_test_paths Opsional
Tipe
bool
Default
true
Deskripsi
Saat menelusuri berdasarkan metrik graf, kecualikan pengujian, fixture pengujian, kode pihak ketiga, dan contoh sebelum pemeringkatan; pencarian simbol berdasarkan nama tidak berubah
reference_views Opsional
Tipe
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
Deskripsi
Tampilan graf yang sisi masuknya mengisi references/reference_count (scope references/both). Default ["dependency", "type"]: panggilan, impor, ekspor, referensi, instansiasi, pewarisan, penimpaan, dekorator, dan penggunaan tipe. Jika data_flow tidak dipilih, penggunaan data_flow yang diresolusikan secara tepat (callback, handler, kunci pengurutan) dikembalikan terpisah sebagai value_references/value_reference_count, tanpa kecocokan yang disimpulkan hanya dari nama. Tambahkan data_flow atau control_flow, atau berikan ["all"] untuk semua jenis dan tingkat sisi. Keluarga tampilannya sama dengan graph_view pada dependency_search.
relationship_types Opsional
Tipe
list[str]
Deskripsi
Jenis sisi referensi eksplisit (CALL, IMPORT, READS, dll.). Daftar yang tidak kosong menggantikan reference_views.

Paling Cocok Untuk:

  • Memastikan definisi, referensi, dan metrik graf dari simbol yang sudah diketahui
  • Menelusuri berdasarkan centrality, high_impact, atau in_cycle ketika symbol_name tidak disertakan

Tidak Direkomendasikan Untuk:

  • Kueri konseptual atau area yang belum dikenal — gunakan intelligent_search atau semantic_search

analyze_dependencies Stabil

Menganalisis cakupan dampak dengan penelusuran yang sama seperti dependency_search (dependents/incoming). Utamakan dependency_search dengan analysis_type="dependents" atau "impact" untuk analisis dampak. Mengembalikan respons dampak beberapa lompatan dengan kolom graph, connection_summary, dan metrik opsional dengan refactor_risk. Gunakan graph_view untuk membatasi kelompok relasi: dependency (default), type, data_flow, control_flow. connection_summary menghitung edge yang dibatasi pada keluarga relasi untuk root yang dipilih, sebelum penyaringan test/path. Field lama incoming_production/outgoing_production berarti edge non-modul, termasuk test; keduanya bukan jumlah pemanggil produksi.

Parameter:

repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
target Wajib
Tipe
str minLength=1
Deskripsi
Nama simbol untuk dianalisis
symbol_id Opsional
Tipe
UUID
Deskripsi
Pilih kemunculan tertentu dengan UUID dari kandidat target setelah penyaringan berdasarkan namespace, jalur, dan bahasa; ID di luar jendela kandidat yang dibatasi akan menghasilkan kesalahan.
depth Opsional
Tipe
Literal[shallow, balanced, deep]
Default
balanced
Deskripsi
Kedalaman analisis
limit Opsional
Tipe
int minimum=1, maximum=50
Default
10
Deskripsi
Jumlah maksimum hasil per halaman tanpa cursor. Kelanjutan menggunakan ukuran halaman yang tersimpan di cursor; abaikan cursor untuk mulai dengan limit berbeda.
offset Opsional
Tipe
int minimum=0
Deskripsi
Offset kompatibilitas yang sudah usang. Utamakan cursor dari pagination.next_cursor.
cursor Opsional
Tipe
str
Deskripsi
cursor buram dari pagination.next_cursor. Teruskan tanpa perubahan dan pertahankan query serta filter tetap sama. Posisi dan ukuran halamannya menggantikan offset dan limit.
direction Opsional
Tipe
Literal[incoming, outgoing, both]
Default
incoming
Deskripsi
Arah traversal
relationship_types Opsional
Tipe
list[str]
Deskripsi
Memfilter jenis edge (CALL, IMPORT, INHERITS_FROM, dll). List yang tidak kosong menggantikan default graph_view; list kosong menggunakan default tersebut.
graph_view Opsional
Tipe
Literal[dependency, type, data_flow, control_flow]
Default
dependency
Deskripsi
Tampilan graf: menentukan baik jenis edge traversal default maupun metrics dari view mana yang digunakan saat 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]. Diterapkan sebagai default relationship_types ketika relationship_types diabaikan atau kosong. Cocok dengan nama parameter graph_view yang sudah ada di dependency_search, demi konsistensi antar tool.
path_filter Opsional
Tipe
str
Deskripsi
Membatasi resolusi target symbol berdasarkan prefix file path; relasi graf yang dikembalikan bisa melintas keluar dari path tersebut
language_filter Opsional
Tipe
str
Deskripsi
Filter bahasa
branch Opsional
Tipe
str
Deskripsi
Override branch
per_hop_limit Opsional
Tipe
int minimum=1, maximum=300
Deskripsi
Jumlah maksimum relationship per hop (1-300)
include_metrics Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan metrik graf dalam hasil, masing-masing dilengkapi blok refactor_risk turunan ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk bernilai "low" jika simbol bukan titik artikulasi dalam tampilan yang dipilih, "medium" jika titik artikulasi menjembatani sedikit sisi, dan "high" jika menjembatani banyak sisi (ambang heuristik, belum divalidasi secara empiris). Blok ini tidak disertakan untuk simbol tertentu jika tidak ada baris metrik untuk simbol/tampilan tersebut.
metrics_detail Opsional
Tipe
Literal[summary, full]
Default
summary
Deskripsi
Ketika include_metrics=true: summary (default) mengembalikan sinyal keputusan + refactor_risk; full mengembalikan kumpulan metrik hasil kurasi yang lebih besar
include_edge_metadata Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan metadata mentah dan bobot sisi graf. Nonaktif secara default karena metadata ekstraktor bisa berukuran besar; cakupan pengayaan dilaporkan saat diaktifkan.
exclude_test_paths Opsional
Tipe
bool
Default
true
Deskripsi
Default true: kecualikan jalur pengujian, fixture pengujian, kode pihak ketiga, dan contoh dari sisi graf yang dikembalikan. Atur false untuk menyertakannya.
include_module_symbols Opsional
Tipe
bool
Default
false
Deskripsi
Default false: kecualikan sisi graf yang from_name atau to_name-nya merupakan simbol sintetis __module__. Atur true untuk menyertakan sisi tingkat modul.
head_commit Opsional
Tipe
str pattern=^[0-9a-fA-F]{7,64}$
Deskripsi
SHA commit dari kode yang Anda tanyakan (git rev-parse HEAD, atau base commit dari patch). complete:true mensyaratkan index berada di commit ini dan dibangun oleh resolver saat ini; jika tidak, tetap complete:false dengan index_stale / index_freshness_unverified / index_built_by_older_resolver, dan index_basis.statement menyebutkan dalam cakupan apa jawabannya lengkap. Baris 'base-commit:' pada patch (git format-patch --base) juga menyediakannya.

Paling Cocok Untuk:

  • Analisis dampak beberapa lompatan saat Anda memerlukan kolom respons graph dan connection_summary

Tidak Direkomendasikan Untuk:

  • Analisis dampak umum — utamakan dependency_search untuk penelusuran fleksibel dan pemeriksaan dari beberapa titik awal

get_task_context Stabil

Mulai bekerja di area yang belum dikenal? Jelaskan tugasnya (misalnya "tambahkan dukungan SSO", "perbaiki webhook billing") dan dapatkan, dalam satu kali panggilan, kumpulan file, kode, symbol, dan dependensi terkait yang terbatas. File yang diberikan sebagai seed menyumbangkan konten yang terindeks langsung meskipun tidak mendefinisikan symbol apa pun. Layer yang gagal akan diberi label; kegagalan pengambilan total mengembalikan error tool. Untuk hasil lebih lanjut, lanjutkan dengan search tool khusus untuk layer tersebut.

Parameter:

task_description Wajib
Tipe
str minLength=1
Deskripsi
Deskripsi task yang membutuhkan konteks
repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
limit Opsional
Tipe
int minimum=1, maximum=50
Default
15
Deskripsi
Item konteks maksimum per layer
scope Opsional
Tipe
Literal[semantic, symbols, dependencies, all]
Default
all
Deskripsi
Layer konteks yang disertakan
language_filter Opsional
Tipe
str
Deskripsi
Filter bahasa: memerlukan scope=semantic tanpa titik awal eksplisit atau konteks terkait; indeks lapisan lain tidak dapat memberlakukan bahasa.
path_filter Opsional
Tipe
str
Deskripsi
Prefix jalur file untuk akar pengambilan semantik dan kata kunci. Seed eksplisit dapat berada di luar prefix ini; konteks graf dapat melintasi batas direktori.
branch Opsional
Tipe
str
Deskripsi
Override branch
include_related_context Opsional
Tipe
bool
Default
false
Deskripsi
Sertakan konteks terkait dari simbol tetangga
seed_symbol_ids Opsional
Tipe
list[str] maxItems=20
Deskripsi
Titik awal tugas eksplisit: muncul pertama di lapisan simbol dan dipertahankan dalam jendela dependencies/related_context yang dibatasi. Lapisan graf memeringkat titik awal eksplisit dan lingkungan terdekatnya sebelum beralih ke kata kunci; kepentingan hanya menjadi penentu saat relevansinya sama. Perluasan graf memerlukan scope=all|dependencies (scope=symbols|semantic tidak pernah menjalankan traversal dependensi). Jangan sertakan parameter ini untuk pemeringkatan yang hanya berbasis kata kunci dengan kepentingan yang menurun seiring kedalaman.
seed_file_paths Opsional
Tipe
list[str] maxItems=10
Deskripsi
Titik awal eksplisit: jalur file terindeks yang persis, yang sedang dibuka atau baru saja diedit agen. Mengembalikan konten berukuran terbatas langsung dari file tersebut dan hingga 5 titik awal graf per file, mendahulukan kecocokan persis dengan nama tugas dari pencarian simbol yang dibatasi, sebelum definisi dan simbol sampingan. File tanpa simbol tetap memberikan bukti. File yang hilang dapat mengembalikan saran berlabel yang bukan merupakan titik awal. Perluasan graf memerlukan scope=all|dependencies.

Paling Cocok Untuk:

  • Konteks yang mempertimbangkan tugas, menggabungkan file yang diberikan sebagai titik awal dengan lapisan semantik, simbol, dan dependensi

Tidak Direkomendasikan Untuk:

  • Pencarian single-tool ketika tool yang lebih spesifik sudah menjawab pertanyaannya

get_file Stabil

Membaca file dari repositori yang diindeks berdasarkan jalur. Lebih baik gunakan alat file lokal untuk file di disk; gunakan ini untuk snapshot terindeks jarak jauh. Lanjutkan respons terbatas dengan metadata.next_line_start dan next_character_start. Hapus baris baru di akhir beserta penanda [truncated] hanya ketika metadata.truncated=true; jika tidak, itu mungkin teks sumber literal.

Parameter:

file_path Wajib
Tipe
str
Deskripsi
Jalur file relatif ke root repository
repository Opsional
Tipe
str
Deskripsi
Repository sebagai owner/repo[:branch]. Opsional — jangan sertakan untuk memakai default klien pada permintaan tersebut (bila disediakan) atau satu-satunya repository yang dapat diakses; berikan secara eksplisit hanya untuk menargetkan repository terindeks lain. Branch terindeks yang persis lebih diutamakan; branch yang tidak tersedia dapat beralih ke main atau satu-satunya branch yang dapat diakses. Metadata respons menampilkan identitas yang diminta dan yang benar-benar digunakan, serta memberi peringatan saat terjadi fallback tersebut.
line_start Opsional
Tipe
int minimum=1
Deskripsi
Baris awal (1-indexed)
line_end Opsional
Tipe
int minimum=1
Deskripsi
Baris akhir (1-indexed, inklusif; harus di line_start atau setelahnya)
character_start Opsional
Tipe
int minimum=0
Default
0
Deskripsi
Offset dalam unit kode UTF-16 hanya di dalam baris awal (indeks mulai dari 0). Gunakan metadata.next_character_start untuk melanjutkan baris yang baru terbaca sebagian.
branch Opsional
Tipe
str
Deskripsi
Override branch
max_tokens Opsional
Tipe
int minimum=1, maximum=50000
Default
5000
Deskripsi
Perkiraan anggaran konten (4 unit kode UTF-16 per token; bukan batas tokenizer yang persis).
include_metadata Opsional
Tipe
bool
Default
true
Deskripsi
Sertakan metadata deskriptif berkas. Metadata pemotongan dan kelanjutan selalu dikembalikan.

Paling Cocok Untuk:

  • Snapshot file jarak jauh atau terindeks (rentang baris, batas token)

Tidak Direkomendasikan Untuk:

  • Path yang sudah ada di disk lokal — gunakan Read tool lokal

Tool Sistem & Utilitas

#

repository_context Stabil

Menampilkan daftar repository yang bisa Anda cari, atau mendapatkan informasi identitas satu repository (namespace/branch, indexed_commit_sha / kesegaran index). Gunakan action:"list" jika slug repository tidak diketahui; search tool menerima slug yang sudah diketahui secara langsung atau default ke satu-satunya repository milik key Anda. list menggunakan pattern dan pagination; info membutuhkan repository dan mendukung branch serta include_statistics=true opsional.

Parameter:

action Wajib
Tipe
Literal[list, info]
Deskripsi
Aksi: list repositori tersedia atau dapatkan info repo
repository Opsional
Tipe
str
Deskripsi
Khusus info: repository dalam format owner/repo atau owner/repo:branch (wajib untuk info)
branch Opsional
Tipe
str
Deskripsi
Khusus info: override branch
pattern Opsional
Tipe
str
Deskripsi
Khusus list: substring nama repository yang tidak membedakan huruf besar/kecil
include_statistics Opsional
Tipe
bool
Default
false
Deskripsi
Hanya informasi: menyertakan jumlah data terindeks yang terbatas. Jumlah file/blob akurat; jumlah indeks yang lebih besar adalah perkiraan. Baca count_accuracy dan estimate_analyzed_at. Default false.
limit Opsional
Tipe
int minimum=1, maximum=50
Default
20
Deskripsi
Jumlah maksimum hasil per halaman tanpa cursor. Kelanjutan menggunakan ukuran halaman yang tersimpan di cursor; abaikan cursor untuk mulai dengan limit berbeda.
offset Opsional
Tipe
int minimum=0
Deskripsi
Offset yang sudah usang dan dipertahankan untuk kompatibilitas. Utamakan cursor dari pagination.next_cursor.
cursor Opsional
Tipe
str
Deskripsi
cursor buram dari pagination.next_cursor. Teruskan tanpa perubahan dan pertahankan query serta filter tetap sama. Posisi dan ukuran halamannya menggantikan offset dan limit.

Paling Cocok Untuk:

  • Membuat daftar repository yang bisa diakses
  • Menentukan identitas repositori, branch, dan kemutakhiran indeks dibandingkan dengan HEAD

Tidak Direkomendasikan Untuk:

  • Statistik seluruh namespace secara default — kirim include_statistics=true secara eksplisit, karena bisa lebih lambat daripada resolution

ask_maguyva Stabil

Dapatkan panduan alat Maguyva atau kirim laporan bug maupun permintaan fitur yang disimpan untuk pengelola Maguyva. Jangan sertakan rahasia atau data pribadi sensitif dalam umpan balik. Operasi evaluate mendukung ekspresi deterministik; utamakan perhitungan lokal atau alat lingkungan untuk matematika, hash, dan string.

Parameter:

operation Wajib
Tipe
Literal[guidance, report_bug, request_feature, evaluate]
Deskripsi
Gunakan guidance untuk bantuan alat, report_bug untuk bug, atau request_feature untuk saran. evaluate menjalankan ekspresi deterministik; utamakan perhitungan lokal.
query Opsional
Tipe
str maxLength=500
Deskripsi
Topik panduan (misalnya tool_selection, semantic_search) atau string ekspresi untuk evaluate.
description Opsional
Tipe
str minLength=1, maxLength=4000
Deskripsi
Wajib untuk report_bug dan request_feature. Umpan balik dalam bentuk bebas untuk pengelola Maguyva. Jangan pernah menyertakan rahasia atau data pribadi sensitif.
related_tool Opsional
Tipe
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]
Deskripsi
Alat Maguyva opsional paling erat kaitannya dengan umpan balik

Paling Cocok Untuk:

  • Panduan tool (operation="guidance")
  • Bug report dan feature request permanen untuk maintainer Maguyva

Tidak Direkomendasikan Untuk:

  • Perhitungan matematika, hash, atau string — utamakan perhitungan lokal atau alat lingkungan

Praktik Terbaik

#
  1. Gunakan Override Eksplisit dengan Sengaja: Jangan sertakan repository ketika klien MCP Anda menyediakan default untuk permintaan tersebut atau kunci dapat mengakses tepat satu repository; jika tidak, berikan secara eksplisit.
  2. Pilih Mode Pencarian yang Tepat: Gunakan intelligent_search dengan mode="auto" untuk sebagian besar kasus. Tentukan mode bila Anda tahu persis kebutuhan Anda.
  3. Manfaatkan Filter Bahasa: Gunakan language_filter untuk mempersempit hasil dan meningkatkan performa.
  4. Boosting GraphRAG: Boosting kepentingan GraphRAG untuk pencarian semantik nonaktif secara default (boost_by_importance=false) demi menjaga ranking tetap aman untuk agen. Kirim boost_by_importance=true untuk mengaktifkan re-ranking yang peka sentralitas untuk peninjauan arsitektur.
  5. Pencocokan Repository Tidak Peka Huruf Besar/Kecil, Bukan Fuzzy: repository_context mencocokkan nama repository tanpa membedakan huruf besar-kecil — tetapi tidak membetulkan salah ketik. Kalau identitas yang disajikan berbeda dari yang diminta, metadata.resolution_reason melaporkan "defaulted" (tidak ada branch yang diminta) atau "fallback" (branch atau repository yang diminta tidak tersedia). Field ini dihilangkan kalau permintaan cocok persis.
  6. Gabungkan Tools: Gunakan beberapa metode API bersamaan untuk analisis yang menyeluruh.
  7. Tangani Hasil Besar: Gunakan limit dan kontrol paging khusus tool (mis. line_start/line_end di get_file).
  8. Gunakan ask_maguyva untuk Panduan Tool: Panggil ask_maguyva dengan operation="guidance" dan query="tool_selection" untuk saran serta contoh pemilihan alat. Gunakan alat lokal untuk perhitungan dan transformasi string.
  9. Verifikasi Dampak Sebelum dan Sesudah Mengedit: Sebelum mengedit symbol yang dipakai bersama, panggil dependency_search dengan analysis_type="impact" (atau kirim changed_paths untuk dampak PR/diff) untuk melihat cakupan dampaknya. Setelah mengedit, set verify_after_edit=true dengan targets dan/atau changed_paths untuk pengecekan ulang yang ringkas atas graf terindeks. Pemeriksaan ini membaca graf terindeks, bukan perubahan lokal yang belum di-commit, dan tidak menggantikan pengujian lokal. Periksa indexed_commit_sha dan kemutakhiran indeks sebelum menganggap hasil sebagai bukti untuk revisi baru.

Karakteristik Performa

#
Operasi Catatan performa
Pencarian semantik Mencakup pembuatan representasi vektor kueri dan pengambilan berbasis vektor. Latensi bergantung pada kedua operasi.
Pencarian teks Pada pencarian isi secara samar, halaman yang lebih jauh mengambil lebih banyak kandidat. Persempit kueri dengan path_filter dan language_filter.
Pencarian struktural Mengueri simpul AST terindeks. Gunakan prasetel atau pola spesifik dan batasi jumlah hasil.
Pencarian dependensi Biaya berskala sesuai depth — utamakan depth="shallow" kecuali Anda butuh konteks multi-hop; per_hop_limit membatasi fan-out
Pengambilan file Baca rentang yang diperlukan dengan line_start/line_end atau max_tokens, lalu gunakan metadata kelanjutan yang dikembalikan untuk isi yang terpotong.
Konteks repository Resolusi repositori berjalan pada setiap panggilan alat. Berikan repository secara eksplisit jika memerlukan repositori tertentu.
ask_maguyva (guidance / evaluate) Berjalan di server MCP tanpa mengueri indeks repositori.

Penanganan Error

#

Respons alat memuat kolom status umum dan kolom muatan khusus alat di tingkat teratas. Pencarian mengembalikan results; get_file mengembalikan content. Kolom umum meliputi:

  • status: String — "success" atau "error". Sinyal degraded-match dan kesegaran indeks punya field sendiri: metadata.resolution_reason di bawah metadata, dan index_freshness.status di level teratas action info milik repository_context.
  • timing_ms: Waktu eksekusi alat dalam milidetik
  • applied_filters: Parameter permintaan efektif yang dicatat untuk operasi
  • error: String pesan kesalahan saat status bernilai "error"; dapat memuat panduan pemulihan.
  • metadata: Informasi tambahan tentang operasinya (routing, caching, penyesuaian parameter)
  • pagination: Ada pada respons koleksi dengan paginasi kursor — mencakup has_more dan next_cursor. Jendela pencarian berperingkat adalah hasil top-K terbatas, bukan koleksi lengkap yang dipaginasi.

Periksa field status sebelum memproses payload tool — nilainya "success" atau "error". Tangani juga error transport MCP/JSON-RPC dan validasi request, yang bisa terjadi sebelum payload tool sempat dibuat. Untuk sinyal degraded-match atau kesegaran, baca field khususnya: metadata.resolution_reason di bawah metadata, atau index_freshness.status di level teratas action info milik repository_context (known/partial/unknown/unavailable).

Memulai

#
  1. Konfigurasi Klien MCP: Arahkan klien MCP Anda ke endpoint server Maguyva
  2. Konfirmasi Akses Repository: Gunakan repository_context dengan list atau info untuk memeriksa repositori yang dapat diakses oleh kunci API
  3. Mulai Mencari: Mulai dengan intelligent_search dan jelajahi tools khusus sesuai kebutuhan
  4. Gabungkan Tools: Gunakan beberapa tools bersama untuk analisis kode menyeluruh

Untuk instruksi integrasi lebih detail, lihat panduan instalasi.

Terkait

Baca berikutnya