Langkau ke kandungan

Rujukan API MCP

Terokai 11 alat MCP Maguyva, parameternya dan masa yang sesuai untuk menggunakan setiap alat. Semak respons tools/list daripada klien yang tersambung untuk mengetahui argumen yang tersedia.

Gambaran Keseluruhan API

#

Alat disusun dalam 4 kategori:

  • Alat Carian Teras - Keupayaan carian termaju merentas pangkalan kod anda
  • Alat Struktur & Graf - Pertanyaan AST, carian simbol, dan analisis kebergantungan
  • Alat Analisis Kod - Analisis kod mendalam dan pemetaan hubungan
  • Alat Sistem & Utiliti - Konteks repositori, panduan alat dan maklum balas

Bagi alat yang menerima repositori, gunakan format pengenal repositori ini: "owner/repo:branch". Cabang lalai ialah main jika tidak dinyatakan.

Abaikan repository apabila klien MCP anda memberikan lalai untuk permintaan tersebut atau apabila kunci boleh mengakses tepat satu repositori; jika tidak, berikannya secara eksplisit. Gunakan repository_context(action="info", repository="owner/repo") untuk memeriksa cara repositori dikenal pasti.

Format Parameter Repositori

#

Gunakan format ini apabila menentukan repositori:

  • Dengan branch: "owner/repo:branch" - cth., "owner/repository:develop"
  • Branch lalai: "owner/repo" - menggunakan branch main apabila branch tidak dinyatakan "owner/repository"
  • Lalai permintaan atau satu-satunya repositori: Abaikan repositori apabila klien MCP memberikan lalai untuk permintaan tersebut atau apabila kunci boleh mengakses tepat satu repositori; jika tidak, berikannya secara eksplisit

Contoh prompt:

Tanya tentang repo tertentu:         "Cari middleware pengesahan dalam owner/my-repo"
Senaraikan repo yang boleh diakses:  "Repositori apakah yang boleh diakses oleh kunci Maguyva ini?"
Gantikan untuk satu pertanyaan:      "Cari corak auth dalam owner/other-repo:develop"

Penapisan Bahasa

#

Gunakan language_filter dalam mod carian yang menyokongnya. Untuk text_pattern_search, pilih search_scope="content"; untuk get_task_context, gunakan scope="semantic" tanpa titik permulaan atau konteks berkaitan.

  • language_filter="python" - Tapis kepada fail Python sahaja
  • language_filter="typescript" - Tapis kepada fail TypeScript sahaja
  • Peka huruf besar/kecil: Gunakan nama bahasa huruf kecil
  • Lalai: String kosong (tiada penapisan) - mengembalikan hasil daripada semua bahasa
  • Liputan disokong: Penapis bahasa berfungsi merentas keseluruhan 285+ bahasa dan teknologi berasaskan teks yang disokong. Lihat keserasian untuk senarai penuh. 
"Cari middleware pengesahan dalam fail Python sahaja"
"Cari sambungan pangkalan data dalam TypeScript"

Rujukan API dijana daripada kod sumber pada 21 Oktober 2026.

Alat Carian Teras

#

intelligent_search Stabil

Mulakan di sini untuk sebarang soalan tentang pangkalan kod. Tetapan lalai auto/balanced menghalakan pertanyaan yang dikenal pasti dengan keyakinan tinggi sebagai carian definisi kepada carian berstruktur, soalan tentang rujukan atau kesan kepada graf, dan soalan tentang padanan tepat kepada carian teks. Soalan lain menggunakan makna semantik dan teks yang diindeks. Gunakan mode=hybrid atau auto dengan quality=thorough untuk meminta keempat-empat modaliti carian. Mod yang dipilih secara eksplisit mengatasi tetapan quality. language_filter mengecualikan graf daripada auto/hybrid dan ditolak apabila mode=graph dipilih secara eksplisit. Utamakan alat ini berbanding Grep/Glob apabila anda belum mengetahui laluannya.

Parameter:

query Wajib
Jenis
str minLength=1
Penerangan
Pertanyaan carian
repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
mode Pilihan
Jenis
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Lalai
auto
Penerangan
Mod carian
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
10
Penerangan
Bilangan maksimum keputusan dalam tetingkap top-K yang disusun ini
language_filter Pilihan
Jenis
str
Penerangan
Penapis bahasa
path_filter Pilihan
Jenis
str
Penerangan
Menapis calon carian mengikut awalan laluan fail. Nod jiran dalam graf dan konteks komuniti yang dilampirkan mungkin merangkumi fail di luar awalan ini.
boost_by_importance Pilihan
Jenis
bool
Lalai
false
Penerangan
Pilihan: susun semula mengikut kepusatan menggunakan metrik graf bagi setiap simbol (is_articulation_point, bridge_count, k_core, centrality, dll.). Dimatikan secara lalai supaya pemeringkatan selamat untuk ejen (hab global boleh menenggelamkan hasil pelaksanaan sebenar); aktifkan untuk penerokaan seni bina. Terpakai pada kesemua 4 modaliti apabila setiap hasil mempunyai pautan kepada simbol.
branch Pilihan
Jenis
str
Penerangan
Gantikan cawangan
quality Pilihan
Jenis
Literal[quick, balanced, thorough]
Lalai
balanced
Penerangan
Pratetap kualiti carian
include_content Pilihan
Jenis
bool
Lalai
true
Penerangan
Sertakan kandungan dalam hasil carian
explain_routing Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan penjelasan keputusan penghalaan
importance_weight Pilihan
Jenis
float minimum=0, maximum=1
Lalai
0.3
Penerangan
Berat untuk meningkatkan kepentingan (0=tiada, 1=penuh)
orphans Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan simbol yatim (tiada rujukan masuk)
include_community_context Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan simbol berkaitan daripada komuniti kod yang sama
community_depth Pilihan
Jenis
int minimum=1, maximum=3
Lalai
1
Penerangan
Kedalaman pengembangan konteks komuniti
graph_view Pilihan
Jenis
Literal[dependency, type, data_flow, control_flow]
Lalai
dependency
Penerangan
Paparan graf untuk metrik
seed_symbol_ids Pilihan
Jenis
list[str] maxItems=20
Penerangan
Titik mula tugas Tier-1: ID simbol yang penting kepada tugas semasa. Apabila ditetapkan, hasil gabungan disusun semula mengikut kedekatan Approach A dengan pemberat yang berkurang mengikut kedalaman (padanan titik mula tepat + bilangan langkah pada edge graf). Bersifat tambahan — abaikan untuk pemeringkatan global.
seed_file_paths Pilihan
Jenis
list[str] maxItems=10
Penerangan
Titik mula tugas Tier-1: laluan fail terindeks yang dibuka atau baru sahaja disunting oleh ejen. Apabila ditetapkan, hasil gabungan disusun semula mengikut kedekatan laluan dengan pemberat yang berkurang mengikut kedalaman pada kadar 1/(1+d) (fail yang sama → direktori yang sama → pakej berdekatan). Bersifat tambahan — abaikan untuk pemeringkatan global.

Sesuai Untuk:

  • Penerokaan seluruh indeks atau permulaan tanpa konteks apabila alat yang betul tidak jelas
  • Pemeringkatan gabungan pelbagai mod merentasi semantik, teks, struktur, dan graf

Tidak Disyorkan Untuk:

  • Nama simbol yang diketahui — gunakan find_symbol terus
  • Laluan yang diketahui pada cakera — gunakan Read/Grep setempat dahulu

semantic_search Stabil

Cari kod berdasarkan makna, bukan teks tepat. Gunakan untuk pertanyaan konseptual seperti 'logik percubaan semula' atau 'aliran pengenalan pengguna' apabila kata kunci atau nama simbol tidak diketahui. Mengembalikan cebisan berkaitan dengan kepelbagaian fail yang terhad; pemeringkatan semula mengikut kepentingan graf boleh diaktifkan melalui boost_by_importance. Utamakan berbanding Grep bagi carian konseptual.

Parameter:

query Wajib
Jenis
str minLength=1
Penerangan
Pertanyaan carian (konseptual, berasaskan makna)
repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
5
Penerangan
Bilangan maksimum keputusan dalam tetingkap top-K yang disusun ini
similarity_threshold Pilihan
Jenis
float minimum=0, maximum=1
Lalai
0.6
Penerangan
Skor persamaan minimum
language_filter Pilihan
Jenis
str
Penerangan
Penapis bahasa (python, typescript, dsb.)
path_filter Pilihan
Jenis
str
Penerangan
Tapis mengikut awalan laluan fail
boost_by_importance Pilihan
Jenis
bool
Lalai
false
Penerangan
Pilihan: peringkatkan semula mengikut kepentingan graf ternormal bagi setiap simbol (dimatikan secara lalai; dihadkan kepada 1.5 kali keserupaan).
branch Pilihan
Jenis
str
Penerangan
Gantikan cabang (lalai: daripada parameter repositori atau main)
include_content Pilihan
Jenis
bool
Lalai
true
Penerangan
Sertakan kandungan ketulan dalam hasil carian
graph_view Pilihan
Jenis
Literal[dependency, type, data_flow, control_flow]
Lalai
dependency
Penerangan
Paparan graf untuk metrik

Sesuai Untuk:

  • Pertanyaan konsep ("bagaimana pengesahan berfungsi?", "strategi cache")
  • Carian persamaan merentas pakej

Tidak Disyorkan Untuk:

  • Nama simbol yang diketahui — gunakan find_symbol sebagai gantinya
  • Rentetan tepat atau mesej ralat — gunakan text_pattern_search

text_pattern_search Stabil

Cari kandungan berindeks. exact dan regex menggunakan grep pada seluruh korpus fail/blob; fuzzy content mencari dalam korpus cebisan semantik yang terhad. Skop file dan symbol hanya menggunakan trigram — mode=exact lalai ditukar kepada fuzzy. Kawalan bahasa, huruf besar/kecil dan ambang tersuai memerlukan skop content. Penapis laluan fail menggunakan tetingkap calon terhad dan melaporkan liputan tidak lengkap. Gunakan Grep setempat untuk direktori kecil yang sudah ada pada cakera.

Parameter:

query Wajib
Jenis
str minLength=1
Penerangan
Corak teks untuk dicari
repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
mode Pilihan
Jenis
Literal[fuzzy, exact, regex]
Lalai
exact
Penerangan
Mod carian. Regex menjalankan sintaks lanjutan/POSIX PostgreSQL; gunakan \y untuk sempadan perkataan (\b bermaksud backspace). Corak juga melalui pengesah keselamatan JavaScript, jadi binaan khusus PostgreSQL seperti bendera (?i) inline ditolak; gunakan case_sensitive sebaliknya.
search_scope Pilihan
Jenis
Literal[content, symbols, files]
Lalai
content
Penerangan
Apa yang hendak dicari
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
5
Penerangan
Bilangan maksimum hasil setiap halaman tanpa cursor. Sambungan menggunakan saiz halaman yang disimpan dalam cursor; abaikan cursor untuk mula dengan limit yang berbeza.
offset Pilihan
Jenis
int minimum=0
Penerangan
Offset keserasian yang sudah lapuk. Utamakan cursor daripada pagination.next_cursor.
cursor Pilihan
Jenis
str
Penerangan
cursor legap daripada pagination.next_cursor. Sampaikan tanpa perubahan dan kekalkan query serta penapis tidak berubah. Kedudukan dan saiz halamannya mengatasi offset dan limit.
language_filter Pilihan
Jenis
str
Penerangan
Penapis bahasa
path_filter Pilihan
Jenis
str
Penerangan
Tapis mengikut awalan laluan fail
case_sensitive Pilihan
Jenis
bool
Lalai
false
Penerangan
Padanan peka huruf besar/kecil
branch Pilihan
Jenis
str
Penerangan
Gantikan cawangan
fuzzy_algorithm Pilihan
Jenis
Literal[hybrid, trigram, levenshtein]
Lalai
hybrid
Penerangan
Algoritma padanan kabur
threshold Pilihan
Jenis
float minimum=0, maximum=1
Lalai
0.05
Penerangan
Ambang kesamaan minimum untuk fuzzy
semantic_fallback Pilihan
Jenis
bool
Lalai
false
Penerangan
Cuba semantic search selepas halaman lexical pertama kosong; metadata.fallback_status membezakan status sandaran used, empty dan unavailable.

Sesuai Untuk:

  • Rentetan tepat, mesej ralat, dan regex
  • Padanan trigram fuzzy untuk teks hampir sepadan

Tidak Disyorkan Untuk:

  • Laluan yang diketahui pada cakera — utamakan Grep setempat
  • Pertanyaan konsep — gunakan semantic_search

Alat Struktur & Graf

#

structural_search Stabil

Utamakan preset=functions|classes|methods|imports|variables (atau pattern= bebas). Cari kod mengikut struktur AST, bukan teks. Penapis peringkat pertengahan: name_pattern, node_type, decorator, parent_child. Penapis laluan/ltree/panggilan ialah penapis lanjutan; tetapkan advanced=true apabila menggunakannya dengan sengaja. Tanpanya, penapis lanjutan tetap digunakan dengan amaran metadata. Berikan sekurang-kurangnya satu pemilih struktur.

Parameter:

repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
preset Pilihan
Jenis
Literal[functions, classes, methods, imports, variables]
Penerangan
Pemilih struktur yang disyorkan. Dikembangkan kepada jenis nod AST merentas bahasa — functions (takrif function/arrow/method merentas bahasa); classes (pengisytiharan class/struct/interface, badan jenis dan pelaksanaan); methods (takrif method dan function_definition bagi bahasa tanpa nod method); imports (pernyataan import/use/include); variables (pengisytiharan variable/let/const/static). Utamakan ini berbanding pattern/node_type bebas untuk pertanyaan penerokaan.
pattern Pilihan
Jenis
str
Penerangan
pattern bebas mengisi selector yang hilang (pengesanan automatik: 'def foo(' → node_type + name_pattern). Boleh digabungkan dengan preset; selector jelas diutamakan. Gunakan preset= untuk pertanyaan penerokaan.
name_pattern Pilihan
Jenis
str maxLength=256
Penerangan
Corak nama simbol (wildcard shell, regex POSIX terhad, atau teks anggaran; maksimum 256 aksara)
node_type Pilihan
Jenis
str
Penerangan
Jenis node AST (function_definition, class_definition, dll.) — utamakan preset= untuk bentuk lazim
decorator Pilihan
Jenis
str
Penerangan
Penapis nama decorator
base_class Pilihan
Jenis
str
Penerangan
Penapis kelas asas
language_filter Pilihan
Jenis
str
Penerangan
Penapis bahasa (python, typescript, dsb.)
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
20
Penerangan
Bilangan maksimum hasil setiap halaman tanpa cursor. Sambungan menggunakan saiz halaman yang disimpan dalam cursor; abaikan cursor untuk mula dengan limit yang berbeza.
offset Pilihan
Jenis
int minimum=0
Penerangan
Offset keserasian yang sudah lapuk. Utamakan cursor daripada pagination.next_cursor.
cursor Pilihan
Jenis
str
Penerangan
cursor legap daripada pagination.next_cursor. Sampaikan tanpa perubahan dan kekalkan query serta penapis tidak berubah. Kedudukan dan saiz halamannya mengatasi offset dan limit.
path_filter Pilihan
Jenis
str
Penerangan
Tapis mengikut awalan laluan fail
branch Pilihan
Jenis
str
Penerangan
Gantikan cawangan
query_type Pilihan
Jenis
Literal[node_type, name_pattern, parent_child]
Penerangan
Jenis pertanyaan eksplisit
parent_type Pilihan
Jenis
str
Penerangan
Penapis jenis nod AST induk
relationship Pilihan
Jenis
Literal[parent, ancestor]
Lalai
parent
Penerangan
Untuk pertanyaan parent_child: induk langsung sahaja, atau mana-mana nenek moyang (gunakan ancestor untuk kaedah kelas bersarang di bawah badan/blok kelas)
has_modifier Pilihan
Jenis
str
Penerangan
Tapis mengikut pengubah suai (export, async, static, dsb.)
advanced Pilihan
Jenis
bool
Lalai
false
Penerangan
Tetapkan true apabila sengaja menggunakan penapis laluan/ltree/panggilan lanjutan (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Apabila false, penapis lanjutan yang diberikan tetap digunakan dengan amaran metadata. Utamakan preset= untuk pertanyaan struktur biasa.
callee_text Pilihan
Jenis
str
Penerangan
Lanjutan — utamakan preset=functions|classes|methods|imports|variables. Tapis teks sasaran dalam ungkapan panggilan. Tetapkan advanced=true apabila sengaja menggunakan penapis laluan/ltree/panggilan.
callee_name Pilihan
Jenis
str
Penerangan
Lanjutan — utamakan preset=functions|classes|methods|imports|variables. Tapis nama sasaran dalam ungkapan panggilan. Tetapkan advanced=true apabila sengaja menggunakan penapis laluan/ltree/panggilan.
field_role Pilihan
Jenis
str
Penerangan
Lanjutan — utamakan preset=functions|classes|methods|imports|variables. Tapis peranan medan AST. Tetapkan advanced=true apabila sengaja menggunakan penapis laluan/ltree/panggilan.
ltree_ancestor Pilihan
Jenis
str
Penerangan
Lanjutan — utamakan preset=functions|classes|methods|imports|variables. Tapis laluan ltree nod leluhur AST. Tetapkan advanced=true apabila sengaja menggunakan penapis laluan/ltree/panggilan.
ltree_descendant Pilihan
Jenis
str
Penerangan
Lanjutan — utamakan preset=functions|classes|methods|imports|variables. Tapis laluan ltree nod keturunan AST. Tetapkan advanced=true apabila sengaja menggunakan penapis laluan/ltree/panggilan.
definition_name Pilihan
Jenis
str
Penerangan
Lanjutan — utamakan preset=functions|classes|methods|imports|variables. Tapis nama takrif. Tetapkan advanced=true apabila sengaja menggunakan penapis laluan/ltree/panggilan.
min_depth Pilihan
Jenis
int
Penerangan
Lanjutan — utamakan preset=functions|classes|methods|imports|variables. Kedalaman AST minimum. Tetapkan advanced=true apabila sengaja menggunakan penapis laluan/ltree/panggilan.
max_depth Pilihan
Jenis
int
Penerangan
Lanjutan — utamakan preset=functions|classes|methods|imports|variables. Kedalaman AST maksimum. Tetapkan advanced=true apabila sengaja menggunakan penapis laluan/ltree/panggilan.

Sesuai Untuk:

  • Struktur peringkat AST: class, decorator, preset function/method
  • Mencari kod mengikut bentuk, bukan teks

Tidak Disyorkan Untuk:

  • Pertanyaan teks bebas atau konsep — gunakan semantic_search atau intelligent_search

dependency_search Stabil

Alat utama untuk lingkungan impak dan graf. Menjawab «apa yang memanggil ini?» dan «apa yang digunakan oleh ini?» melalui graf panggilan/import sebenar. Untuk impak sebelum suntingan: analysis_type="dependents" atau analysis_type="impact" (arah masuk, kedalaman cetek secara lalai untuk impact), dengan include_metrics=false secara lalai (aktifkan untuk kepusatan dan refactor_risk). dependents/impact menyertakan production_callers secara lalai: lokasi penggunaan produksi yang unik mengikut jenis (call, instantiate, value_reference untuk fungsi yang dihantar sebagai nilai), serta lokasi IMPORT, tanpa ujian dan dengan tahap keyakinan EXTRACTED/INFERRED — bukan sekadar himpunan metrik. Impak PR/diff: hantarkan changed_paths dan/atau patch (perbezaan bersepadu); menentukan simbol bagi setiap laluan dan memulangkan data ringkas tentang komponen bergantung arah masuk pada kedalaman cetek tanpa memerlukan nama simbol. Selepas suntingan, tetapkan verify_after_edit=true dengan targets dan/atau changed_paths untuk pertanyaan semula ringkas dari berbilang akar bagi simbol terjejas. Turut menyokong dependencies, centrality dan orphans. analyze_dependencies menggunakan penelusuran yang sama untuk analisis impak berbilang langkah.

Parameter:

repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
query Pilihan
Jenis
str
Penerangan
Nama simbol atau istilah carian
target Pilihan
Jenis
str
Penerangan
Nama simbol (alias untuk pertanyaan)
symbol_id Pilihan
Jenis
UUID
Penerangan
Pilih kemunculan tertentu menggunakan UUID daripada calon yang sepadan dengan nama dalam query/target selepas penapisan mengikut ruang nama, laluan dan bahasa. Gunakan ID yang dikembalikan oleh find_symbol atau hasil alternatif graf. Hanya untuk traversal dengan nama yang ditetapkan; ID di luar julat calon yang terhad akan menghasilkan ralat.
changed_paths Pilihan
Jenis
list[str] maxItems=50
Penerangan
Laluan fail tepat yang relatif kepada repo untuk impak PR/diff (lalai) atau, dengan verify_after_edit=true, titik mula pengesahan selepas suntingan. Laluan yang tidak dapat diselesaikan mungkin mengembalikan cadangan berlabel; fail yang dicadangkan tidak akan menjadi akar impak. PR/diff: tanpa maklumat baris, menelusuri definisi peringkat atas bagi setiap laluan (yang dieksport dahulu, mengikut susunan fail) dan melaporkan changed_lines_unknown; hantar patch= untuk simbol yang berubah pada peringkat baris. Pengesahan: sehingga 5 definisi peringkat atas bagi setiap laluan sebagai akar pengesahan (dihadkan lebih rendah dalam mod pengesahan). Tidak memerlukan query/target untuk impak PR/diff.
patch Pilihan
Jenis
str maxLength=500000
Penerangan
Impak PR/diff: teks tampalan unified diff / git patch. Laluan diambil daripada pengepala diff --git / --- / +++; baris hunk (sisi lama = commit yang diindeks) dipetakan kepada fungsi/kaedah/kelas yang melingkunginya, lalu ditelusuri untuk mendapatkan dependen yang tepat, public_api_changed dan pemanggil yang tidak disentuh oleh diff.
head_commit Pilihan
Jenis
str pattern=^[0-9a-fA-F]{7,64}$
Penerangan
SHA commit bagi kod yang anda tanyakan (git rev-parse HEAD, atau commit asas bagi patch). complete:true memerlukan indeks berada pada commit ini dan dibina oleh resolver semasa; jika tidak, ia kekal complete:false dengan index_stale / index_freshness_unverified / index_built_by_older_resolver, dan index_basis.statement menyatakan dalam skop apa jawapan itu lengkap. Baris 'base-commit:' dalam patch (git format-patch --base) juga membekalkannya.
analysis_type Pilihan
Jenis
Literal[centrality, dependencies, dependents, impact, orphans]
Lalai
dependencies
Penerangan
Mod analisis. impact = lingkungan impak (dependents arah masuk; depth shallow apabila depth tidak dinyatakan). dependents turut menjawab impact. Apabila changed_paths atau patch ditetapkan, analisis dipaksa menjadi impak PR/diff. centrality/orphans tidak memerlukan target. orphans ialah calon kod yang tidak digunakan, bukan bukti bahawa ia selamat dibuang; sahkan rujukannya dalam kod sumber.
depth Pilihan
Jenis
Literal[shallow, balanced, deep]
Penerangan
Kedalaman lintasan. Lalai ialah balanced; impact dan PR/diff impact lalai kepada shallow. depth yang dinyatakan secara jelas menggantikan lalai ini. Mod pengesahan sentiasa menggunakan shallow.
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
20
Penerangan
Bilangan maksimum hasil setiap halaman tanpa cursor. Sambungan menggunakan saiz halaman yang disimpan dalam cursor; abaikan cursor untuk mula dengan limit yang berbeza.
offset Pilihan
Jenis
int minimum=0
Penerangan
Offset keserasian yang sudah lapuk. Utamakan cursor daripada pagination.next_cursor.
cursor Pilihan
Jenis
str
Penerangan
cursor legap daripada pagination.next_cursor. Sampaikan tanpa perubahan dan kekalkan query serta penapis tidak berubah. Kedudukan dan saiz halamannya mengatasi offset dan limit.
path_filter Pilihan
Jenis
str
Penerangan
Mengehadkan penentuan simbol sasaran mengikut awalan laluan fail; hubungan graf yang dikembalikan boleh melangkaui laluan tersebut
language_filter Pilihan
Jenis
str
Penerangan
Tapis penentuan sasaran dan hasil penerokaan mengikut bahasa
direction Pilihan
Jenis
Literal[outgoing, incoming, both]
Penerangan
Arah lintasan (mengatasi inferens analysis_type)
relationship_types Pilihan
Jenis
list[str]
Penerangan
Tapis jenis edge (CALL, IMPORT, INHERITS_FROM, dll.). Senarai yang tidak kosong akan menggantikan lalai graph_view.
exclude_test_paths Pilihan
Jenis
bool
Lalai
true
Penerangan
Lalai true: mengecualikan laluan ujian, fixture, vendor, dan contoh daripada hasil penelusuran dan kepusatan. Tetapkan false untuk menyertakannya. Analisis simbol tanpa rujukan masuk hanya mematuhi tetapan ini jika backend yang digunakan menyokongnya; jika tidak, ia mengekalkan pengecualian data tidak relevan yang lebih ketat miliknya sendiri dan melaporkan pelarasan tersebut.
exclude_generated_paths Pilihan
Jenis
bool
Lalai
false
Penerangan
Kecualikan pengisytiharan janaan serta laluan binaan, liputan, cache, peta sumber dan artifak yang dikecilkan daripada hasil penelusuran
include_module_symbols Pilihan
Jenis
bool
Lalai
false
Penerangan
Secara lalai, false mengecualikan tepi graf apabila from_name atau to_name ialah simbol __module__ sintetik (data peringkat modul yang tidak relevan). Tetapkan true untuk memasukkan tepi peringkat modul dalam hasil dependen/kebergantungan.
include_isolated Pilihan
Jenis
bool
Penerangan
Untuk analisis simbol tanpa rujukan masuk sahaja. Lalai false. Tetapkan true untuk turut memulangkan simbol tanpa baris metrik graf (tiada sebarang tepi graf di mana-mana). Selagi exclude_test_paths bernilai true, simbol lembaran gaya/penanda/data (CSS, HTML, ...), pengisytiharan .d.ts dan laluan test/fixture/vendor/example kekal dikecualikan jika backend menyokongnya, melainkan language_filter menamakan bahasa tersebut; sifat literal objek TypeScript masih boleh muncul sebagai fungsi terpencil.
exclude_exported Pilihan
Jenis
bool
Lalai
false
Penerangan
Untuk simbol yatim sahaja. Lalai false: simbol yang dieksport (API awam) yang tidak digunakan dalam repositori dipulangkan dengan is_exported=true. Tetapkan true untuk calon dalaman sahaja.
branch Pilihan
Jenis
str
Penerangan
Gantikan cawangan
per_hop_limit Pilihan
Jenis
int minimum=1, maximum=300
Penerangan
Bilangan maksimum hubungan bagi setiap langkah (1-300)
include_metrics Pilihan
Jenis
bool
Lalai
false
Penerangan
Metrik graf pilihan pada baris hasil (diringkaskan bersama refactor_risk). Metrik turut diambil secara dalaman apabila min_centrality>0 tetapi tidak dikembalikan melainkan ini true.
metrics_detail Pilihan
Jenis
Literal[summary, full]
Lalai
summary
Penerangan
Apabila include_metrics=true: summary (lalai) mengembalikan isyarat keputusan + refactor_risk; full mengembalikan set metrik susun atur yang lebih besar
include_edge_metadata Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan metadata tepi mentah dan pemberat (besar). Muatan impak padat meninggalkan perkara ini.
symbol_types Pilihan
Jenis
list[str]
Penerangan
Menapis symbol yang dikembalikan mengikut jenis (function, class, method, dll). Tidak disokong dalam analisis orphan; gunakan path_filter atau language_filter di sana sebagai gantinya. Senarai kosong tidak mengenakan sebarang penapis jenis.
exact_match Pilihan
Jenis
bool
Lalai
false
Penerangan
Memerlukan padanan nama simbol yang tepat
find_similar_patterns Pilihan
Jenis
bool
Lalai
false
Penerangan
Cari corak penggunaan yang serupa
min_centrality Pilihan
Jenis
float minimum=0
Lalai
0
Penerangan
Skor PageRank minimum untuk penelusuran simbol bernama dan analisis kesan PR/diff. Ambang positif tidak disokong dalam mod semak imbas centrality/orphans. Metrik diambil secara dalaman untuk penapisan; graph_metrics hanya dikembalikan apabila include_metrics=true. Diabaikan oleh verify_after_edit, yang menggunakan kawalan padat yang tetap.
graph_view Pilihan
Jenis
Literal[dependency, type, data_flow, control_flow]
Lalai
dependency
Penerangan
Paparan graf yang digunakan untuk lalai hubungan penelusuran, metrik, dan pemeringkatan kepusatan; analisis simbol tanpa rujukan masuk dikira merentas semua paparan
verify_after_edit Pilihan
Jenis
bool
Lalai
false
Penerangan
Menanya semula graf impact yang diindeks untuk symbol yang disunting dalam satu respons berbilang akar yang padat. Memerlukan targets dan/atau changed_paths (atau target/query). Menggunakan lintasan shallow tetap dan bajet padat; kawalan depth/limit/cursor/metrics tidak terpakai. Secara lalai mengembalikan incoming dependents; hasil mencerminkan graf yang diindeks (mungkin ketinggalan berbanding suntingan langsung). Apabila true, ia diutamakan berbanding PR/diff impact untuk changed_paths yang sama.
targets Pilihan
Jenis
list[str] maxItems=15
Penerangan
Apabila verify_after_edit=true: nama simbol untuk disahkan semula (pemanggil/komponen bergantung). Digabungkan dengan target/query jika kedua-duanya diberikan.

Sesuai Untuk:

  • Analisis lingkungan impak sebelum menyunting simbol kongsi
  • Impak PR/diff melalui changed_paths atau patch
  • Pengesahan selepas suntingan melalui verify_after_edit

Tidak Disyorkan Untuk:

  • Carian teks atau simbol yang mudah — gunakan text_pattern_search atau find_symbol

Alat Analisis Kod

#

find_symbol Stabil

Lompat ke tempat fungsi, kelas atau pembolehubah ditakrifkan dan digunakan. Gunakan apabila anda mengetahui nama (cth. "getCurrentUser") — lebih pantas dan lebih tepat daripada Grep, dan ia merangkumi keseluruhan repo yang diindeks. Secara pilihan mengembalikan rujukan dan metrik kepentingan.

Parameter:

symbol_name Pilihan
Jenis
str
Penerangan
Nama simbol untuk dicari (pilihan — abaikan untuk menyemak imbas berdasarkan metrik)
repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
scope Pilihan
Jenis
Literal[definitions, references, both]
Lalai
both
Penerangan
Skop carian; references memerlukan symbol_name yang tidak kosong.
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
15
Penerangan
Bilangan maksimum hasil setiap halaman tanpa cursor. Sambungan menggunakan saiz halaman yang disimpan dalam cursor; abaikan cursor untuk mula dengan limit yang berbeza.
offset Pilihan
Jenis
int minimum=0
Penerangan
Offset keserasian yang sudah lapuk. Utamakan cursor daripada pagination.next_cursor.
cursor Pilihan
Jenis
str
Penerangan
cursor legap daripada pagination.next_cursor. Sampaikan tanpa perubahan dan kekalkan query serta penapis tidak berubah. Kedudukan dan saiz halamannya mengatasi offset dan limit.
find_similar Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan nama simbol yang serupa
include_metrics Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan metrik kepusatan
metrics_detail Pilihan
Jenis
Literal[summary, full]
Lalai
summary
Penerangan
Apabila include_metrics=true: summary (lalai) mengembalikan isyarat keputusan + refactor_risk; full mengembalikan set metrik susun atur yang lebih besar
path_filter Pilihan
Jenis
str
Penerangan
Tapis mengikut awalan laluan fail
branch Pilihan
Jenis
str
Penerangan
Gantikan cawangan
symbol_type Pilihan
Jenis
str minLength=1
Penerangan
Tapis mengikut jenis simbol yang diindeks, cth. function, class, struct, enum atau trait. Gunakan jenis yang dikembalikan oleh hasil simbol; jenis berbeza mengikut bahasa.
high_impact Pilihan
Jenis
bool
Lalai
false
Penerangan
Layari symbol yang penting dari segi seni bina (abaikan symbol_name). Mod default ialah popularity (desil PageRank teratas tolak utility mega-hub). Tetapkan high_impact_mode=risk untuk articulation/bridge cut-vertex.
high_impact_mode Pilihan
Jenis
Literal[popularity, risk]
Lalai
popularity
Penerangan
Apabila high_impact=true: popularity = desil PageRank teratas tanpa mega-hab utiliti/modul; risk = titik artikulasi diperingkat mengikut SMV bridge_count kemudian k_core (risiko struktur ketika refactor, bukan populariti hab)
in_cycle Pilihan
Jenis
bool
Lalai
false
Penerangan
Menapis symbol yang keahlian kitaran kebergantungannya direkodkan.
exclude_test_paths Pilihan
Jenis
bool
Lalai
true
Penerangan
Apabila menyemak imbas mengikut metrik graf, kecualikan ujian, fixtures, kod pihak ketiga dan contoh sebelum kedudukan. Carian mengikut simbol bernama tidak berubah.
reference_views Pilihan
Jenis
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
Penerangan
Paparan graf yang sisi masuknya mengisi references/reference_count (scope references/both). Lalai ["dependency", "type"]: panggilan, import, eksport, rujukan, penginstansan, pewarisan, penggantian, penghias dan penggunaan jenis. Jika data_flow tidak dipilih, penggunaan data_flow yang diselesaikan dengan tepat (panggil balik, pengendali, kunci isihan) dipulangkan secara berasingan sebagai value_references/value_reference_count, tanpa padanan yang disimpulkan daripada nama sahaja. Tambah data_flow atau control_flow, atau berikan ["all"] untuk semua jenis dan peringkat sisi. Keluarga paparannya sama seperti graph_view dalam dependency_search.
relationship_types Pilihan
Jenis
list[str]
Penerangan
Jenis sisi rujukan yang dinyatakan secara jelas (CALL, IMPORT, READS dan sebagainya). Senarai yang tidak kosong menggantikan reference_views.

Sesuai Untuk:

  • Menentukan takrif, rujukan, dan metrik graf bagi simbol yang diketahui
  • Menyemak imbas mengikut centrality, high_impact, atau in_cycle apabila symbol_name ditinggalkan

Tidak Disyorkan Untuk:

  • Pertanyaan konsep atau kawasan tidak diketahui — gunakan intelligent_search atau semantic_search

analyze_dependencies Stabil

Analisis lingkungan impak menggunakan penelusuran yang sama seperti dependency_search (dependents/incoming). Utamakan dependency_search dengan analysis_type="dependents" atau "impact" untuk analisis impak. Memulangkan respons impak berbilang langkah dengan graph, connection_summary dan metrik pilihan bersama refactor_risk. connection_summary mengira tepi yang terhad kepada keluarga hubungan bagi akar yang dipilih, sebelum sebarang penapisan ujian atau laluan. Medan lama incoming_production/outgoing_production bermaksud tepi bukan modul, termasuk ujian; ia bukan kiraan pemanggil pengeluaran. Gunakan graph_view untuk mengehadkan keluarga hubungan: dependency (lalai), type, data_flow, control_flow.

Parameter:

repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
target Wajib
Jenis
str minLength=1
Penerangan
Nama simbol untuk dianalisis
symbol_id Pilihan
Jenis
UUID
Penerangan
Pilih kemunculan tertentu menggunakan UUID daripada calon target selepas penapisan mengikut ruang nama, laluan dan bahasa; ID di luar julat calon yang terhad akan menghasilkan ralat.
depth Pilihan
Jenis
Literal[shallow, balanced, deep]
Lalai
balanced
Penerangan
Kedalaman analisis
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
10
Penerangan
Bilangan maksimum hasil setiap halaman tanpa cursor. Sambungan menggunakan saiz halaman yang disimpan dalam cursor; abaikan cursor untuk mula dengan limit yang berbeza.
offset Pilihan
Jenis
int minimum=0
Penerangan
Offset keserasian yang sudah lapuk. Utamakan cursor daripada pagination.next_cursor.
cursor Pilihan
Jenis
str
Penerangan
cursor legap daripada pagination.next_cursor. Sampaikan tanpa perubahan dan kekalkan query serta penapis tidak berubah. Kedudukan dan saiz halamannya mengatasi offset dan limit.
direction Pilihan
Jenis
Literal[incoming, outgoing, both]
Lalai
incoming
Penerangan
Arah lintasan
relationship_types Pilihan
Jenis
list[str]
Penerangan
Menapis jenis edge (CALL, IMPORT, INHERITS_FROM, dll). Senarai yang tidak kosong menggantikan lalai graph_view; senarai kosong menggunakan lalai tersebut.
graph_view Pilihan
Jenis
Literal[dependency, type, data_flow, control_flow]
Lalai
dependency
Penerangan
Paparan graf: menentukan kedua-dua jenis edge lintasan lalai dan metrics paparan mana yang digunakan apabila include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (lalai), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Digunakan sebagai lalai relationship_types apabila relationship_types ditinggalkan atau kosong. Sepadan dengan nama parameter graph_view sedia ada dependency_search, demi konsistensi antara alat.
path_filter Pilihan
Jenis
str
Penerangan
Mengehadkan penentuan simbol sasaran mengikut awalan laluan fail; hubungan graf yang dikembalikan boleh melangkaui laluan tersebut
language_filter Pilihan
Jenis
str
Penerangan
Penapis bahasa
branch Pilihan
Jenis
str
Penerangan
Gantikan cawangan
per_hop_limit Pilihan
Jenis
int minimum=1, maximum=300
Penerangan
Bilangan maksimum hubungan bagi setiap langkah (1-300)
include_metrics Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan metrik graf dalam hasil, setiap satu diperkaya dengan blok refactor_risk terbitan ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk ialah "low" apabila bukan titik artikulasi (dalam paparan yang dipilih), "medium" apabila titik artikulasi merapatkan beberapa tepi, "high" apabila merapatkan banyak (ambang heuristik, tidak disahkan secara empirik). Diabaikan setiap simbol apabila tiada baris metrik wujud untuk simbol/pandangan itu.
metrics_detail Pilihan
Jenis
Literal[summary, full]
Lalai
summary
Penerangan
Apabila include_metrics=true: summary (lalai) mengembalikan isyarat keputusan + refactor_risk; full mengembalikan set metrik susun atur yang lebih besar
include_edge_metadata Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan metadata tepi mentah dan pemberat. Dilumpuhkan secara lalai kerana metadata pengekstrak boleh menjadi besar; liputan pengayaan dilaporkan apabila didayakan.
exclude_test_paths Pilihan
Jenis
bool
Lalai
true
Penerangan
Lalai true: kecualikan laluan ujian, fixture, vendor dan contoh daripada edge graf yang dikembalikan. Tetapkan false untuk menyertakannya.
include_module_symbols Pilihan
Jenis
bool
Lalai
false
Penerangan
Secara lalai, false mengecualikan tepi graf apabila from_name atau to_name ialah simbol __module__ sintetik. Tetapkan true untuk memasukkan tepi peringkat modul.
head_commit Pilihan
Jenis
str pattern=^[0-9a-fA-F]{7,64}$
Penerangan
SHA commit bagi kod yang anda tanyakan (git rev-parse HEAD, atau commit asas bagi patch). complete:true memerlukan indeks berada pada commit ini dan dibina oleh resolver semasa; jika tidak, ia kekal complete:false dengan index_stale / index_freshness_unverified / index_built_by_older_resolver, dan index_basis.statement menyatakan dalam skop apa jawapan itu lengkap. Baris 'base-commit:' dalam patch (git format-patch --base) juga membekalkannya.

Sesuai Untuk:

  • Analisis impak berbilang langkah apabila anda memerlukan medan respons graph dan connection_summary

Tidak Disyorkan Untuk:

  • Analisis impak umum: utamakan dependency_search untuk penelusuran fleksibel dan semakan berbilang akar

get_task_context Stabil

Memulakan kerja di kawasan yang tidak biasa? Terangkan tugas (cth. "tambah sokongan SSO", "betulkan webhook pengebilan") dan dapatkan, dalam satu panggilan, bungkusan terhad fail, kod, symbol dan kebergantungan yang berkaitan. Fail yang diberikan sebagai seed menyumbang kandungan yang diindeks secara langsung walaupun ia tidak mentakrifkan sebarang symbol. Lapisan yang gagal akan dilabel; kegagalan pengambilan sepenuhnya mengembalikan ralat alat. Untuk lebih banyak hasil, teruskan dengan alat carian khusus untuk lapisan tersebut.

Parameter:

task_description Wajib
Jenis
str minLength=1
Penerangan
Penerangan tentang tugas yang memerlukan konteks
repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
15
Penerangan
Hasil maksimum setiap lapisan
scope Pilihan
Jenis
Literal[semantic, symbols, dependencies, all]
Lalai
all
Penerangan
Lapisan konteks yang hendak disertakan
language_filter Pilihan
Jenis
str
Penerangan
Penapis bahasa: memerlukan scope=semantic tanpa titik mula eksplisit atau konteks berkaitan; indeks lapisan lain tidak dapat menguatkuasakan bahasa.
path_filter Pilihan
Jenis
str
Penerangan
Awalan laluan fail untuk akar dapatan semantik dan kata kunci. Benih eksplisit mungkin berada di luar awalan ini; konteks graf mungkin merentasi sempadan direktori.
branch Pilihan
Jenis
str
Penerangan
Gantikan cawangan
include_related_context Pilihan
Jenis
bool
Lalai
false
Penerangan
Sertakan konteks berkaitan daripada simbol bersebelahan
seed_symbol_ids Pilihan
Jenis
list[str] maxItems=20
Penerangan
Benih tugas eksplisit: muncul dahulu dalam lapisan simbol dan dikekalkan dalam tetingkap dependencies/related_context yang terhad. Lapisan graf memeringkat benih eksplisit dan kejiranan terdekatnya sebelum berundur kepada kata kunci; kepentingan hanya memutuskan apabila kerelevanan sama. Pengembangan graf memerlukan scope=all|dependencies (scope=symbols|semantic tidak pernah menjalankan penelusuran kebergantungan). Abaikan untuk pemeringkatan yang hanya menggunakan kata kunci mengikut kepentingan yang menurun mengikut kedalaman.
seed_file_paths Pilihan
Jenis
list[str] maxItems=10
Penerangan
Titik mula eksplisit: laluan fail terindeks yang tepat, sedang dibuka atau baru sahaja disunting oleh ejen. Memulangkan bukti fail secara langsung dalam skop terhad dan sehingga 5 benih graf bagi setiap fail, dengan mendahulukan padanan tepat nama tugas daripada carian simbol yang terhad sebelum takrif dan simbol sampingan. Fail tanpa simbol tetap membekalkan bukti. Fail yang hilang mungkin mengembalikan cadangan berlabel yang bukan benih. Pengembangan graf memerlukan scope=all|dependencies.

Sesuai Untuk:

  • Konteks berasaskan tugas yang menggabungkan fail titik mula dengan lapisan semantik, simbol, dan kebergantungan

Tidak Disyorkan Untuk:

  • Carian satu alat apabila alat yang lebih khusus sudah menjawab soalan tersebut

get_file Stabil

Membaca fail daripada repositori yang diindeks mengikut laluan. Utamakan alat fail tempatan untuk fail pada cakera; gunakan ini untuk snapshot yang diindeks jauh. Teruskan respons terhad dengan metadata.next_line_start dan next_character_start. Alihkan baris baharu akhir dan penanda [truncated] hanya apabila metadata.truncated=true; jika tidak, ia mungkin teks sumber literal.

Parameter:

file_path Wajib
Jenis
str
Penerangan
Laluan fail relatif kepada akar repositori
repository Pilihan
Jenis
str
Penerangan
Repositori sebagai owner/repo[:branch]. Pilihan — abaikan untuk menggunakan lalai klien bagi permintaan tersebut (jika diberikan) atau satu-satunya repositori yang boleh diakses; berikan secara eksplisit hanya untuk menyasarkan repo berindeks yang lain. Cawangan berindeks yang sepadan tepat diutamakan; cawangan yang tidak tersedia mungkin beralih semula kepada main atau satu-satunya cawangan yang boleh diakses. Metadata respons menunjukkan identiti yang diminta dan identiti sebenar yang digunakan, serta memberi amaran apabila peralihan semula ini berlaku.
line_start Pilihan
Jenis
int minimum=1
Penerangan
Baris mula (berindeks dari 1)
line_end Pilihan
Jenis
int minimum=1
Penerangan
Baris akhir (1-indexed, inklusif; mesti pada atau selepas line_start)
character_start Pilihan
Jenis
int minimum=0
Lalai
0
Penerangan
Ofset dalam unit kod UTF-16 hanya dalam baris permulaan (indeks bermula dari 0). Gunakan metadata.next_character_start untuk menyambung baris yang dibaca sebahagiannya.
branch Pilihan
Jenis
str
Penerangan
Gantikan cawangan
max_tokens Pilihan
Jenis
int minimum=1, maximum=50000
Lalai
5000
Penerangan
Anggaran bajet kandungan (4 unit kod UTF-16 bagi setiap token; bukan had tokenizer yang tepat).
include_metadata Pilihan
Jenis
bool
Lalai
true
Penerangan
Sertakan metadata deskriptif fail. Metadata pemotongan dan sambungan sentiasa dikembalikan.

Sesuai Untuk:

  • Salinan fail jauh atau terindeks (julat baris, had token)

Tidak Disyorkan Untuk:

  • Laluan yang sudah ada pada cakera setempat — gunakan alat Read setempat

Alat Sistem & Utiliti

#

repository_context Stabil

Menyenaraikan repository yang boleh anda cari, atau mendapatkan maklumat identiti bagi satu repository (namespace/branch, indexed_commit_sha / kesegaran indeks). Gunakan action:"list" apabila slug repository tidak diketahui; alat carian menerima slug yang diketahui secara terus atau menggunakan secara lalai satu-satunya repository kunci anda. list menggunakan pattern dan penomboran halaman; info memerlukan repository dan menyokong branch serta include_statistics=true pilihan.

Parameter:

action Wajib
Jenis
Literal[list, info]
Penerangan
Tindakan: list untuk menyenaraikan repo yang tersedia atau info untuk mendapatkan maklumat repo
repository Pilihan
Jenis
str
Penerangan
Khas untuk info: repository dalam format owner/repo atau owner/repo:branch (diperlukan untuk info)
branch Pilihan
Jenis
str
Penerangan
Khas untuk info: gantikan cawangan
pattern Pilihan
Jenis
str
Penerangan
Khas untuk list: substring nama repository, tidak sensitif huruf besar/kecil
include_statistics Pilihan
Jenis
bool
Lalai
false
Penerangan
Untuk maklumat sahaja: termasuk kiraan data terindeks terhad. Kiraan file/blob adalah tepat; kiraan indeks yang lebih besar adalah anggaran. Baca count_accuracy dan estimate_analyzed_at. Lalai false.
limit Pilihan
Jenis
int minimum=1, maximum=50
Lalai
20
Penerangan
Bilangan maksimum hasil setiap halaman tanpa cursor. Sambungan menggunakan saiz halaman yang disimpan dalam cursor; abaikan cursor untuk mula dengan limit yang berbeza.
offset Pilihan
Jenis
int minimum=0
Penerangan
Ofset keserasian yang tidak lagi disyorkan. Utamakan cursor daripada pagination.next_cursor.
cursor Pilihan
Jenis
str
Penerangan
cursor legap daripada pagination.next_cursor. Sampaikan tanpa perubahan dan kekalkan query serta penapis tidak berubah. Kedudukan dan saiz halamannya mengatasi offset dan limit.

Sesuai Untuk:

  • Menyenaraikan repositori yang boleh diakses
  • Menentukan identiti repositori, cabang, dan kemutakhiran HEAD berbanding indeks

Tidak Disyorkan Untuk:

  • Statistik merentas namespace secara lalai — hantar include_statistics=true secara eksplisit, kerana ia mungkin lebih perlahan daripada penentuan identiti repositori

ask_maguyva Stabil

Dapatkan panduan alat Maguyva atau hantar laporan pepijat/permintaan ciri yang disimpan untuk penyelenggara Maguyva. Jangan sesekali sertakan rahsia atau data peribadi sensitif dalam maklum balas. Operasi evaluate menyokong ungkapan deterministik; utamakan pengiraan setempat atau alat persekitaran hos bagi kerja matematik, cincangan dan rentetan.

Parameter:

operation Wajib
Jenis
Literal[guidance, report_bug, request_feature, evaluate]
Penerangan
Gunakan guidance untuk bantuan alat, report_bug untuk pepijat atau request_feature untuk cadangan. evaluate menjalankan ungkapan deterministik; utamakan pengiraan setempat untuk perkiraan.
query Pilihan
Jenis
str maxLength=500
Penerangan
Topik panduan (contohnya tool_selection, semantic_search) atau rentetan ungkapan untuk evaluate.
description Pilihan
Jenis
str minLength=1, maxLength=4000
Penerangan
Diperlukan untuk report_bug dan request_feature. Maklum balas bentuk bebas untuk penyelenggara Maguyva. Jangan sesekali sertakan rahsia atau data peribadi sensitif.
related_tool Pilihan
Jenis
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]
Penerangan
Alat Maguyva pilihan yang paling berkait rapat dengan maklum balas

Sesuai Untuk:

  • Panduan alat (operation="guidance")
  • Laporan pepijat dan permintaan ciri yang disimpan untuk penyelenggara Maguyva

Tidak Disyorkan Untuk:

  • Pengiraan matematik, cincangan dan rentetan: utamakan pengiraan setempat atau alat persekitaran hos

Amalan Terbaik

#
  1. Gunakan Penggantian Eksplisit Dengan Sengaja: Abaikan repositori apabila klien MCP anda memberikan lalai untuk permintaan tersebut atau apabila kunci boleh mengakses tepat satu repositori; jika tidak, berikannya secara eksplisit.
  2. Pilih Mod Carian yang Betul: Gunakan intelligent_search dengan mode="auto" untuk kebanyakan kes. Tentukan mod apabila anda tahu dengan tepat apa yang anda perlukan.
  3. Manfaatkan Penapis Bahasa: Gunakan language_filter untuk mengecilkan hasil carian dan meningkatkan prestasi.
  4. Peningkatan GraphRAG: Peningkatan kepentingan GraphRAG untuk carian semantik dilumpuhkan secara lalai (boost_by_importance=false) untuk memastikan susunan kekal selamat untuk ejen. Hantar boost_by_importance=true untuk mendayakan penyusunan semula peka-kesentralan bagi lawatan seni bina.
  5. Padanan Repositori Tidak Peka Huruf Besar/Kecil, Bukan Fuzzy: repository_context memadankan nama repositori tanpa mengira huruf besar atau kecil — tetapi ia tidak membetulkan salah taip. Apabila identiti yang disajikan berbeza daripada yang diminta, metadata.resolution_reason melaporkan "defaulted" (tiada cabang diminta) atau "fallback" (cabang atau repositori yang diminta tidak tersedia). Medan ini ditinggalkan apabila permintaan sepadan dengan tepat.
  6. Gabungkan Alat: Gunakan berbilang kaedah API bersama-sama untuk analisis komprehensif.
  7. Mengendalikan Hasil yang Besar: Gunakan limit dan kawalan halaman khusus alat (contohnya line_start/line_end dalam get_file).
  8. Gunakan ask_maguyva untuk Panduan Alat: Panggil ask_maguyva dengan operation="guidance" dan query="tool_selection" untuk nasihat pemilihan alat dan contoh. Gunakan alat setempat bagi pengiraan dan transformasi rentetan.
  9. Sahkan Kesan Sebelum dan Selepas Menyunting: Sebelum menyunting simbol kongsi, panggil dependency_search dengan analysis_type="impact" (atau hantarkan changed_paths untuk impak PR/diff) bagi melihat lingkungan impaknya. Selepas suntingan, tetapkan verify_after_edit=true dengan targets dan/atau changed_paths untuk semakan semula ringkas graf terindeks. Ini tidak membaca perubahan setempat yang belum dikomit atau menggantikan ujian setempat. Semak indexed_commit_sha dan kemutakhiran indeks sebelum menganggap hasil sebagai bukti untuk versi kod baharu.

Ciri Prestasi

#
Operasi Nota prestasi
Carian semantik Merangkumi penjanaan perwakilan vektor pertanyaan dan pengambilan vektor. Kependaman bergantung pada kedua-dua operasi.
Carian teks Dalam carian kandungan anggaran, halaman yang lebih jauh mengambil lebih banyak calon. Sempitkan pertanyaan dengan path_filter dan language_filter.
Carian struktur Membuat pertanyaan terhadap nod AST terindeks. Gunakan pratetap atau corak tertentu dan hadkan bilangan hasil.
Carian kebergantungan Kos berskala mengikut depth — utamakan depth="shallow" melainkan anda memerlukan konteks multi-hop; per_hop_limit mengehadkan fan-out
Pengambilan fail Baca julat yang diperlukan dengan line_start/line_end atau max_tokens dan gunakan metadata sambungan yang dipulangkan untuk kandungan terpotong.
Konteks repositori Repositori ditentukan bagi setiap panggilan alat. Hantarkan repository secara jelas apabila anda memerlukan repositori tertentu.
ask_maguyva (guidance / evaluate) Berjalan dalam pelayan MCP tanpa membuat pertanyaan terhadap indeks repositori.

Pengendalian Ralat

#

Respons alat mengandungi medan status umum dan medan data khusus alat pada peringkat teratas. Carian mengembalikan results; get_file mengembalikan content. Medan umum termasuk:

  • status: Rentetan — "success" atau "error". Isyarat padanan terjejas dan kesegaran indeks mempunyai medan tersendiri: metadata.resolution_reason di bawah metadata, dan index_freshness.status di aras teratas tindakan info bagi repository_context.
  • timing_ms: Masa pelaksanaan alat yang telah berlalu dalam milisaat
  • applied_filters: Parameter permintaan sebenar yang direkodkan untuk operasi
  • error: Rentetan mesej ralat apabila status ialah "error"; mungkin merangkumi panduan pemulihan.
  • metadata: Maklumat tambahan mengenai operasi (routing, caching, pelarasan parameter)
  • pagination: Hadir pada respons koleksi berhalaman berasaskan kursor — merangkumi has_more dan next_cursor. Tetingkap carian berperingkat ialah hasil top-K yang terhad, bukan koleksi berhalaman yang menyeluruh.

Semak medan status sebelum memproses muatan sesuatu alat — nilainya ialah "success" atau "error". Tangani juga ralat pengangkutan MCP/JSON-RPC dan pengesahan permintaan, yang boleh berlaku sebelum sebarang muatan alat terhasil. Bagi isyarat padanan terjejas atau kesegaran, baca medan khususnya: metadata.resolution_reason di bawah metadata, atau index_freshness.status di aras teratas tindakan info bagi repository_context (known/partial/unknown/unavailable).

Bermula

#
  1. Konfigurasikan klien MCP: Halakan klien MCP anda ke endpoint pelayan Maguyva
  2. Sahkan akses repositori: Gunakan repository_context dengan "list" atau "info" untuk memeriksa repositori yang tersedia kepada kunci API
  3. Mulakan carian: Mulakan dengan intelligent_search dan terokai alat khusus apabila diperlukan
  4. Gabungkan alat: Gunakan beberapa alat bersama-sama untuk analisis kod yang menyeluruh

Untuk arahan integrasi terperinci, lihat panduan pemasangan.

Berkaitan

Baca seterusnya