Vai al contenuto

Riferimento API MCP

Esplora 11 strumenti MCP di Maguyva, i loro parametri e quando usarli. Consulta la risposta tools/list del client connesso per gli argomenti disponibili.

Panoramica dell'API

#

Gli strumenti sono organizzati in 4 categorie:

  • Strumenti di ricerca principali - Funzionalità di ricerca avanzate nel tuo codebase
  • Strumenti strutturali e di grafo - Query AST, ricerca di simboli e analisi delle dipendenze
  • Strumenti di analisi del codice - Analisi approfondita del codice e mappatura delle relazioni
  • Strumenti di sistema e utilità - Contesto del repository, guida agli strumenti e feedback

Per gli strumenti che accettano un repository, usa questo formato dell'identificatore del repository: "owner/repo:branch". Se non specificato, il branch predefinito è main.

Ometti repository quando il tuo client MCP fornisce un default per la richiesta o la chiave può accedere a un solo repository; altrimenti passalo esplicitamente. Usa repository_context(action="info", repository="owner/repo") per ispezionare come viene risolto un repository.

Formato del parametro repository

#

Usa questi formati quando specifichi un repository:

  • Con branch: "owner/repo:branch" - es., "owner/repository:develop"
  • Branch predefinito: "owner/repo" - utilizza il branch main quando non è specificato alcun branch "owner/repository"
  • Predefinito della richiesta o unico repository: Ometti repository quando il client MCP fornisce un valore predefinito per la richiesta o la chiave può accedere a un solo repository; altrimenti passalo esplicitamente.

Esempi di prompt:

Chiedi di un repository specifico:  "Cerca il middleware di autenticazione in owner/my-repo"
Elenca i repo accessibili:          "A quali repository può accedere questa chiave Maguyva?"
Sovrascrivi per una singola query:  "Cerca pattern di autenticazione in owner/other-repo:develop"

Filtro per linguaggio

#

Usa language_filter nelle modalità di ricerca supportate. Per text_pattern_search scegli search_scope="content"; per get_task_context usa scope="semantic" senza punti di partenza o contesto correlato.

  • language_filter="python" - Filtra solo i file Python
  • language_filter="typescript" - Filtra solo i file TypeScript
  • Sensibile a maiuscole/minuscole: Usa nomi di linguaggio in minuscolo
  • Predefinito: Stringa vuota (nessun filtro) - restituisce risultati da tutti i linguaggi
  • Copertura supportata: I filtri per linguaggio funzionano su oltre 285 linguaggi e tecnologie basate su testo supportati. Vedi compatibilità per l'elenco completo. 
"Trova il middleware di autenticazione solo nei file Python"
"Cerca connessioni al database in TypeScript"

Riferimento API generato dal sorgente il 21 ottobre 2026.

Strumenti di ricerca principali

#

intelligent_search Stabile

Inizia da qui per qualsiasi domanda sulla base di codice. L'impostazione predefinita auto/balanced indirizza le query riconosciute con alta confidenza come ricerche di definizioni alla ricerca strutturale, le domande su riferimenti o impatto al grafo e quelle su corrispondenze esatte alla ricerca testuale. Le altre domande utilizzano il significato semantico e il testo indicizzato. Usa mode=hybrid oppure auto con quality=thorough per richiedere tutte e quattro le modalità di ricerca. Una modalità scelta esplicitamente ha la precedenza su quality. language_filter esclude il grafo da auto/hybrid e viene rifiutato quando si sceglie esplicitamente mode=graph. Preferisci questo strumento a Grep/Glob quando non conosci già il percorso.

Parametri:

query Obbligatorio
Tipo
str minLength=1
Descrizione
Query di ricerca
repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
mode Opzionale
Tipo
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Predefinito
auto
Descrizione
Modalità di ricerca
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
10
Descrizione
Numero massimo di risultati in questa finestra top-K ordinata per pertinenza
language_filter Opzionale
Tipo
str
Descrizione
Filtro lingua
path_filter Opzionale
Tipo
str
Descrizione
Filtra i candidati della ricerca per prefisso del percorso file. I nodi vicini nel grafo e il contesto di comunità allegato possono includere file al di fuori di questo prefisso.
boost_by_importance Opzionale
Tipo
bool
Predefinito
false
Descrizione
Opzionale: riclassifica in base alla centralità usando le metriche di grafo per simbolo (is_articulation_point, bridge_count, k_core, centrality, ecc.). Disattivato per impostazione predefinita per una classifica sicura per gli agenti (gli hub globali possono sommergere i risultati di implementazione); attivalo per i tour architetturali. Si applica a tutte e 4 le modalità quando ogni risultato porta un collegamento a un simbolo.
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch
quality Opzionale
Tipo
Literal[quick, balanced, thorough]
Predefinito
balanced
Descrizione
Preset qualità della ricerca
include_content Opzionale
Tipo
bool
Predefinito
true
Descrizione
Includi il contenuto nei risultati
explain_routing Opzionale
Tipo
bool
Predefinito
false
Descrizione
Includi spiegazione della decisione di instradamento
importance_weight Opzionale
Tipo
float minimum=0, maximum=1
Predefinito
0.3
Descrizione
Peso del potenziamento per importanza (0=nessuno, 1=massimo)
orphans Opzionale
Tipo
bool
Predefinito
false
Descrizione
Includi simboli orfani (senza riferimenti in ingresso)
include_community_context Opzionale
Tipo
bool
Predefinito
false
Descrizione
Includi simboli correlati della stessa community di codice
community_depth Opzionale
Tipo
int minimum=1, maximum=3
Predefinito
1
Descrizione
Profondità di espansione del contesto della community
graph_view Opzionale
Tipo
Literal[dependency, type, data_flow, control_flow]
Predefinito
dependency
Descrizione
Vista grafo per le metriche
seed_symbol_ids Opzionale
Tipo
list[str] maxItems=20
Descrizione
Punti di partenza del task Tier-1: ID dei simboli centrali per il task corrente. Se specificati, riordinano i risultati combinati in base alla prossimità secondo Approach A, con peso decrescente all'aumentare della distanza (corrispondenza esatta con il simbolo iniziale + passaggi lungo gli archi del grafo). Funzionalità aggiuntiva: ometti il parametro per mantenere l'ordinamento globale.
seed_file_paths Opzionale
Tipo
list[str] maxItems=10
Descrizione
Punti di partenza del task Tier-1: percorsi di file indicizzati che l'agente ha aperto o appena modificato. Se specificati, riordinano i risultati combinati in base alla vicinanza dei percorsi, con peso decrescente 1/(1+d) (stesso file → stessa directory → pacchetti vicini). Funzionalità aggiuntiva: ometti il parametro per mantenere l'ordinamento globale.

Ideale per:

  • Esplorazione a livello di indice o a freddo quando lo strumento giusto non è chiaro
  • Ordinamento multimodale che combina ricerca semantica, testuale, strutturale e nel grafo

Sconsigliato per:

  • Un nome di simbolo noto — usa direttamente find_symbol
  • Un percorso noto su disco — usa prima Read/Grep in locale

semantic_search Stabile

Trova codice per significato, non per testo esatto. Usalo per query concettuali come «logica dei tentativi» o «percorso iniziale dell'utente» quando non conosci parola chiave o nome del simbolo. Restituisce frammenti pertinenti con diversità dei file limitata; il riordinamento per importanza nel grafo si attiva tramite boost_by_importance. Preferiscilo a Grep nelle ricerche concettuali.

Parametri:

query Obbligatorio
Tipo
str minLength=1
Descrizione
Query di ricerca (concettuale, basata sul significato)
repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
5
Descrizione
Numero massimo di risultati in questa finestra top-K ordinata per pertinenza
similarity_threshold Opzionale
Tipo
float minimum=0, maximum=1
Predefinito
0.6
Descrizione
Soglia minima di similarità
language_filter Opzionale
Tipo
str
Descrizione
Filtro linguaggio (python, typescript, ecc.)
path_filter Opzionale
Tipo
str
Descrizione
Filtra per prefisso del percorso file
boost_by_importance Opzionale
Tipo
bool
Predefinito
false
Descrizione
Attivazione facoltativa: riordina per importanza normalizzata di ogni simbolo nel grafo (disattivato per impostazione predefinita; limite di 1,5 volte la similarità).
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch (predefinito: dal parametro repository o main)
include_content Opzionale
Tipo
bool
Predefinito
true
Descrizione
Includi il contenuto dei chunk nei risultati
graph_view Opzionale
Tipo
Literal[dependency, type, data_flow, control_flow]
Predefinito
dependency
Descrizione
Vista grafo per le metriche

Ideale per:

  • Query concettuali ("come funziona l'autenticazione?", "strategia di caching")
  • Ricerca di similarità tra pacchetti

Sconsigliato per:

  • Un nome di simbolo noto — usa find_symbol al suo posto
  • Stringhe esatte o messaggi di errore — usa text_pattern_search

text_pattern_search Stabile

Cerca nei contenuti indicizzati. exact e regex applicano grep all'intero corpus di file/blob; fuzzy content cerca nel corpus limitato di frammenti semantici. Gli ambiti file e symbol supportano solo trigrammi: il valore predefinito mode=exact viene convertito in fuzzy. I controlli di lingua, maiuscole/minuscole e soglia personalizzata richiedono l'ambito content. Il filtro dei percorsi usa una finestra limitata di candidati e segnala la copertura incompleta. Usa Grep locale per una directory circoscritta già su disco.

Parametri:

query Obbligatorio
Tipo
str minLength=1
Descrizione
Pattern di testo da cercare
repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
mode Opzionale
Tipo
Literal[fuzzy, exact, regex]
Predefinito
exact
Descrizione
Modalità di ricerca. Regex esegue la sintassi avanzata/POSIX di PostgreSQL; usa \y per i confini di parola (\b significa backspace). I pattern passano anche attraverso un validatore di sicurezza JavaScript, quindi i costrutti esclusivi di PostgreSQL come i flag (?i) inline vengono rifiutati; usa invece case_sensitive.
search_scope Opzionale
Tipo
Literal[content, symbols, files]
Predefinito
content
Descrizione
Cosa cercare
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
5
Descrizione
Numero massimo di risultati per pagina senza cursor. La continuazione usa la dimensione di pagina memorizzata in cursor; ometti cursor per iniziare con un limit diverso.
offset Opzionale
Tipo
int minimum=0
Descrizione
Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
cursor Opzionale
Tipo
str
Descrizione
cursor opaco proveniente da pagination.next_cursor. Passalo invariato e mantieni invariati query e i filtri. La sua posizione e la dimensione di pagina hanno la precedenza su offset e limit.
language_filter Opzionale
Tipo
str
Descrizione
Filtro lingua
path_filter Opzionale
Tipo
str
Descrizione
Filtra per prefisso del percorso file
case_sensitive Opzionale
Tipo
bool
Predefinito
false
Descrizione
Corrispondenza sensibile alle maiuscole/minuscole
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch
fuzzy_algorithm Opzionale
Tipo
Literal[hybrid, trigram, levenshtein]
Predefinito
hybrid
Descrizione
Algoritmo di matching fuzzy
threshold Opzionale
Tipo
float minimum=0, maximum=1
Predefinito
0.05
Descrizione
Soglia minima di similarità per fuzzy
semantic_fallback Opzionale
Tipo
bool
Predefinito
false
Descrizione
Tenta una ricerca semantica dopo una prima pagina lessicale vuota; metadata.fallback_status distingue gli stati di fallback used, empty e unavailable.

Ideale per:

  • Stringhe esatte, messaggi di errore e regex
  • Corrispondenza fuzzy a trigrammi per testo quasi corrispondente

Sconsigliato per:

  • Un percorso noto su disco — preferisci Grep in locale
  • Query concettuali — usa semantic_search

Strumenti strutturali e a grafo

#

structural_search Stabile

Preferisci preset=functions|classes|methods|imports|variables (o pattern= libero). Trova codice in base alla struttura AST, non al testo. Filtri intermedi: name_pattern, node_type, decorator, parent_child. I filtri di percorso/ltree/chiamata sono avanzati: imposta advanced=true quando li usi consapevolmente. Altrimenti vengono applicati con un avviso nei metadati. Fornisci almeno un selettore strutturale.

Parametri:

repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
preset Opzionale
Tipo
Literal[functions, classes, methods, imports, variables]
Descrizione
Selettore strutturale preferito. Si espande in tipi di nodo AST multilinguaggio — functions (definizioni di funzione/arrow/metodo a seconda del linguaggio); classes (dichiarazioni di classe/struct/interfaccia, corpi di tipo e implementazioni); methods (definizioni di metodo, e function_definition per i linguaggi senza nodo metodo); imports (istruzioni import/use/include); variables (dichiarazioni variable/let/const/static). Da preferire a pattern/node_type libero per query di tipo browse.
pattern Opzionale
Tipo
str
Descrizione
Un pattern libero completa i selettori mancanti (rilevamento automatico: 'def foo(' → node_type + name_pattern). Può essere combinato con preset; i selettori espliciti hanno la precedenza. Per le query di esplorazione è preferibile preset=.
name_pattern Opzionale
Tipo
str maxLength=256
Descrizione
Pattern del nome del simbolo (wildcard shell, espressione regolare POSIX delimitata o testo fuzzy; massimo 256 caratteri)
node_type Opzionale
Tipo
str
Descrizione
Tipo di nodo AST (function_definition, class_definition, ecc.) — preferisci preset= per le forme comuni
decorator Opzionale
Tipo
str
Descrizione
Filtro per nome del decoratore
base_class Opzionale
Tipo
str
Descrizione
Filtro per classe base
language_filter Opzionale
Tipo
str
Descrizione
Filtro lingua (python, typescript, ecc.)
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
20
Descrizione
Numero massimo di risultati per pagina senza cursor. La continuazione usa la dimensione di pagina memorizzata in cursor; ometti cursor per iniziare con un limit diverso.
offset Opzionale
Tipo
int minimum=0
Descrizione
Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
cursor Opzionale
Tipo
str
Descrizione
cursor opaco proveniente da pagination.next_cursor. Passalo invariato e mantieni invariati query e i filtri. La sua posizione e la dimensione di pagina hanno la precedenza su offset e limit.
path_filter Opzionale
Tipo
str
Descrizione
Filtra per prefisso del percorso file
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch
query_type Opzionale
Tipo
Literal[node_type, name_pattern, parent_child]
Descrizione
Tipo di query esplicito
parent_type Opzionale
Tipo
str
Descrizione
Filtro per tipo di nodo padre AST
relationship Opzionale
Tipo
Literal[parent, ancestor]
Predefinito
parent
Descrizione
Per query parent_child: solo genitore diretto, o qualsiasi antenato (usa ancestor per metodi di classe annidati nel corpo di una classe)
has_modifier Opzionale
Tipo
str
Descrizione
Filtra per modifier (export, async, static, ecc.)
advanced Opzionale
Tipo
bool
Predefinito
false
Descrizione
Imposta true quando usi intenzionalmente filtri avanzati di percorso/ltree/chiamata (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Quando è false, i filtri avanzati forniti vengono applicati con un avviso nei metadati. Preferisci preset= per le query strutturali comuni.
callee_text Opzionale
Tipo
str
Descrizione
Avanzato — preferisci preset=functions|classes|methods|imports|variables. Filtro sul testo del chiamato in una call expression. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.
callee_name Opzionale
Tipo
str
Descrizione
Avanzato — preferisci preset=functions|classes|methods|imports|variables. Filtro sul nome del chiamato in una call expression. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.
field_role Opzionale
Tipo
str
Descrizione
Avanzato — preferisci preset=functions|classes|methods|imports|variables. Filtro sul ruolo del campo AST. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.
ltree_ancestor Opzionale
Tipo
str
Descrizione
Avanzato — preferisci preset=functions|classes|methods|imports|variables. Filtro sul percorso antenato AST ltree. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.
ltree_descendant Opzionale
Tipo
str
Descrizione
Avanzato — preferisci preset=functions|classes|methods|imports|variables. Filtro sul percorso discendente AST ltree. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.
definition_name Opzionale
Tipo
str
Descrizione
Avanzato — preferisci preset=functions|classes|methods|imports|variables. Filtro sul nome della definizione. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.
min_depth Opzionale
Tipo
int
Descrizione
Avanzato — preferisci preset=functions|classes|methods|imports|variables. Profondità AST minima. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.
max_depth Opzionale
Tipo
int
Descrizione
Avanzato — preferisci preset=functions|classes|methods|imports|variables. Profondità AST massima. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.

Ideale per:

  • Struttura a livello di AST: classi, decoratori, preset di function/method
  • Trovare codice in base alla forma anziché al testo

Sconsigliato per:

  • Query in testo libero o concettuali — usa semantic_search o intelligent_search

dependency_search Stabile

Strumento principale per raggio d'impatto e grafi. Risponde a «cosa chiama questo?» e «cosa usa questo?» tramite il grafo reale di chiamate e importazioni. Per l'impatto prima di una modifica: analysis_type="dependents" o analysis_type="impact" (in entrata, profondità ridotta predefinita per impact), con include_metrics=false per impostazione predefinita (attivalo per centralità e refactor_risk). dependents/impact includono production_callers per impostazione predefinita: punti d’uso unici in produzione per tipo (call, instantiate, value_reference per funzioni passate come valori), più i punti IMPORT, esclusi i test, con livello di fiducia EXTRACTED/INFERRED — non un semplice elenco di metriche. Impatto PR/diff: passa changed_paths e/o patch (diff unificato); risolve i simboli per percorso e restituisce dati compatti sui componenti dipendenti in entrata a profondità ridotta, senza richiedere un nome di simbolo. Dopo una modifica, imposta verify_after_edit=true con targets e/o changed_paths per una nuova query compatta da più radici sui simboli interessati. Supporta anche dependencies, centrality e orphans. analyze_dependencies usa lo stesso attraversamento per l'analisi d'impatto su più passaggi.

Parametri:

repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
query Opzionale
Tipo
str
Descrizione
Nome del simbolo o termine di ricerca
target Opzionale
Tipo
str
Descrizione
Nome del simbolo (alias di query)
symbol_id Opzionale
Tipo
UUID
Descrizione
Seleziona tramite UUID una specifica occorrenza tra i candidati del nome indicato in query/target, dopo aver filtrato per namespace, percorso e linguaggio. Usa un ID restituito da find_symbol o dai risultati alternativi del grafo. Solo per attraversamenti con un nome indicato; un ID fuori dalla finestra limitata di candidati genera un errore.
changed_paths Opzionale
Tipo
list[str] maxItems=50
Descrizione
Percorsi di file esatti relativi al repository per l'impatto PR/diff (impostazione predefinita) o, con verify_after_edit=true, punti di partenza per la verifica dopo una modifica. I percorsi non risolti possono restituire suggerimenti etichettati; i file suggeriti non diventano mai punti di partenza per l'impatto. PR/diff: senza informazioni sulle righe, percorre le definizioni di primo livello di ogni percorso (prima quelle esportate, in ordine di file) e segnala changed_lines_unknown; passa patch= per ottenere i simboli modificati a livello di riga. Verifica: fino a 5 definizioni di primo livello per percorso come punti di partenza della verifica (con un limite massimo più basso in modalità di verifica). Non richiede query/target per l'impatto PR/diff.
patch Opzionale
Tipo
str maxLength=500000
Descrizione
Impatto PR/diff: testo in formato unified diff / git patch. I percorsi provengono dalle intestazioni diff --git / --- / +++; le righe degli hunk (lato vecchio = il commit indicizzato) vengono associate a funzioni, metodi e classi che le contengono, poi percorsi per ottenere i dipendenti esatti, public_api_changed e i chiamanti che il diff non tocca.
head_commit Opzionale
Tipo
str pattern=^[0-9a-fA-F]{7,64}$
Descrizione
SHA del commit del codice su cui stai facendo la domanda (git rev-parse HEAD, oppure il commit base della patch). complete:true richiede che l'indice sia a questo commit e sia stato costruito dal resolver attuale; altrimenti resta complete:false con index_stale / index_freshness_unverified / index_built_by_older_resolver, e index_basis.statement indica entro quali limiti la risposta è completa. Lo fornisce anche la riga 'base-commit:' di una patch (git format-patch --base).
analysis_type Opzionale
Tipo
Literal[centrality, dependencies, dependents, impact, orphans]
Predefinito
dependencies
Descrizione
Modalità di analisi. impact = raggio d'impatto (componenti dipendenti raggiunti tramite relazioni in entrata; profondità ridotta quando depth è omesso). Anche dependents risponde alle domande sull'impatto. Quando è impostato changed_paths o patch, viene forzata l'analisi dell'impatto PR/diff. centrality/orphans non richiedono un target. Gli orphans sono candidati a codice inutilizzato, non la prova che si possa rimuovere in sicurezza; verifica i riferimenti nel codice sorgente.
depth Opzionale
Tipo
Literal[shallow, balanced, deep]
Descrizione
Profondità di traversata. Il valore predefinito è balanced; impact e PR/diff impact usano shallow per impostazione predefinita. Un depth esplicito sovrascrive questi valori predefiniti. La modalità di verifica usa sempre shallow.
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
20
Descrizione
Numero massimo di risultati per pagina senza cursor. La continuazione usa la dimensione di pagina memorizzata in cursor; ometti cursor per iniziare con un limit diverso.
offset Opzionale
Tipo
int minimum=0
Descrizione
Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
cursor Opzionale
Tipo
str
Descrizione
cursor opaco proveniente da pagination.next_cursor. Passalo invariato e mantieni invariati query e i filtri. La sua posizione e la dimensione di pagina hanno la precedenza su offset e limit.
path_filter Opzionale
Tipo
str
Descrizione
Limita la risoluzione del simbolo target tramite prefisso del percorso file; le relazioni del grafo restituite possono estendersi oltre quel percorso.
language_filter Opzionale
Tipo
str
Descrizione
Filtra la risoluzione del target e i risultati di browse per linguaggio
direction Opzionale
Tipo
Literal[outgoing, incoming, both]
Descrizione
Direzione di traversata (sovrascrive l'inferenza di analysis_type)
relationship_types Opzionale
Tipo
list[str]
Descrizione
Filtra i tipi di arco (CALL, IMPORT, INHERITS_FROM, ecc.). Un elenco non vuoto sovrascrive i default di graph_view.
exclude_test_paths Opzionale
Tipo
bool
Predefinito
true
Descrizione
Valore predefinito true: esclude i percorsi di test, fixture, codice di terze parti ed esempi dai risultati di attraversamento e centralità. Imposta false per includerli. L'analisi dei simboli orfani ne tiene conto solo dove il backend distribuito lo supporta; altrimenti mantiene le proprie esclusioni del rumore, più restrittive, e segnala l'adattamento.
exclude_generated_paths Opzionale
Tipo
bool
Predefinito
false
Descrizione
Esclude dai risultati di attraversamento le dichiarazioni generate e i percorsi di build, report di copertura dei test, cache, source map e artefatti minificati
include_module_symbols Opzionale
Tipo
bool
Predefinito
false
Descrizione
Valore predefinito false: esclude gli archi in cui from_name o to_name è il simbolo sintetico __module__ (rumore a livello di modulo). Imposta true per includere gli archi a livello di modulo nei risultati dependents/dependencies.
include_isolated Opzionale
Tipo
bool
Descrizione
Solo per i simboli orfani. Valore predefinito false. Imposta true per restituire anche i simboli privi di una riga nelle metriche del grafo (nessun arco nel grafo). Finché exclude_test_paths è true, i simboli di fogli di stile, markup e dati (CSS, HTML, ...), le dichiarazioni .d.ts e i percorsi test/fixture/vendor/example restano esclusi dove il backend lo supporta, a meno che language_filter non indichi quel linguaggio; le proprietà dei letterali oggetto TypeScript possono comunque comparire come funzioni isolate.
exclude_exported Opzionale
Tipo
bool
Predefinito
false
Descrizione
Solo per i simboli orfani. Predefinito false: i simboli esportati (API pubblica) non usati nel repository vengono restituiti con is_exported=true. Imposta true per ottenere solo candidati interni.
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch
per_hop_limit Opzionale
Tipo
int minimum=1, maximum=300
Descrizione
Relazioni massime per hop (1-300)
include_metrics Opzionale
Tipo
bool
Predefinito
false
Descrizione
Metriche di grafo opzionali sulle righe di risultato (compattate con refactor_risk). Le metriche vengono recuperate internamente anche quando min_centrality>0, ma restituite solo se questo è true.
metrics_detail Opzionale
Tipo
Literal[summary, full]
Predefinito
summary
Descrizione
Quando include_metrics=true: summary (predefinito) restituisce segnali decisionali + refactor_risk; full restituisce il set di metriche curate più ampio
include_edge_metadata Opzionale
Tipo
bool
Predefinito
false
Descrizione
Include i metadati grezzi e i pesi degli archi (potenzialmente voluminosi). Le risposte compatte sull'impatto mantengono questa opzione disattivata.
symbol_types Opzionale
Tipo
list[str]
Descrizione
Filtra i simboli restituiti per tipo (function, class, method, ecc.). Non è supportato nell'analisi orphan; in quel caso usa path_filter o language_filter. Un elenco vuoto non applica alcun filtro per tipo.
exact_match Opzionale
Tipo
bool
Predefinito
false
Descrizione
Richiedi corrispondenza esatta del nome del simbolo
find_similar_patterns Opzionale
Tipo
bool
Predefinito
false
Descrizione
Trova pattern di utilizzo simili
min_centrality Opzionale
Tipo
float minimum=0
Predefinito
0
Descrizione
Punteggio PageRank minimo per l'attraversamento di simboli con nome e per l'analisi d'impatto di PR/diff. Le soglie positive non sono supportate nelle modalità di esplorazione centrality/orphans. Le metriche vengono recuperate internamente per il filtraggio; graph_metrics viene restituito solo quando include_metrics=true. Viene ignorato da verify_after_edit, che usa controlli compatti fissi.
graph_view Opzionale
Tipo
Literal[dependency, type, data_flow, control_flow]
Predefinito
dependency
Descrizione
Vista grafo usata per i default delle relazioni di traversata, le metriche e la classifica di centralità; l'analisi degli orfani è calcolata su tutte le viste
verify_after_edit Opzionale
Tipo
bool
Predefinito
false
Descrizione
Ripete l'interrogazione del grafo di impatto indicizzato per i simboli modificati in un'unica risposta compatta multi-radice. Richiede targets e/o changed_paths (oppure target/query). Usa una traversata shallow fissa e budget compatti; i controlli depth/limit/cursor/metrics non si applicano. Per impostazione predefinita restituisce incoming dependents; i risultati riflettono il grafo indicizzato (possono essere in ritardo rispetto alle modifiche live). Se true, ha la precedenza su PR/diff impact per gli stessi changed_paths.
targets Opzionale
Tipo
list[str] maxItems=15
Descrizione
Quando verify_after_edit=true: nomi dei simboli da verificare nuovamente (chiamanti/componenti dipendenti). Vengono uniti a target/query se sono specificati entrambi.

Ideale per:

  • Analisi del raggio d'impatto prima di modificare un simbolo condiviso
  • Impatto PR/diff tramite changed_paths e/o patch
  • Verifica dopo la modifica tramite verify_after_edit

Sconsigliato per:

  • Ricerche semplici di testo o simboli — preferisci text_pattern_search o find_symbol

Strumenti di analisi del codice

#

find_symbol Stabile

Vai al punto in cui una funzione, classe o variabile è definita e usata. Usalo quando conosci il nome (es. "getCurrentUser") — più veloce e preciso di Grep e copre l'intero repo indicizzato. Restituisce opzionalmente riferimenti e metriche di importanza.

Parametri:

symbol_name Opzionale
Tipo
str
Descrizione
Nome del simbolo da cercare (opzionale — ometti per esplorare per metriche)
repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
scope Opzionale
Tipo
Literal[definitions, references, both]
Predefinito
both
Descrizione
Ambito di ricerca; references richiede un symbol_name non vuoto.
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
15
Descrizione
Numero massimo di risultati per pagina senza cursor. La continuazione usa la dimensione di pagina memorizzata in cursor; ometti cursor per iniziare con un limit diverso.
offset Opzionale
Tipo
int minimum=0
Descrizione
Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
cursor Opzionale
Tipo
str
Descrizione
cursor opaco proveniente da pagination.next_cursor. Passalo invariato e mantieni invariati query e i filtri. La sua posizione e la dimensione di pagina hanno la precedenza su offset e limit.
find_similar Opzionale
Tipo
bool
Predefinito
false
Descrizione
Includi nomi di simboli simili
include_metrics Opzionale
Tipo
bool
Predefinito
false
Descrizione
Includi metriche di centralità
metrics_detail Opzionale
Tipo
Literal[summary, full]
Predefinito
summary
Descrizione
Quando include_metrics=true: summary (predefinito) restituisce segnali decisionali + refactor_risk; full restituisce il set di metriche curate più ampio
path_filter Opzionale
Tipo
str
Descrizione
Filtra per prefisso del percorso file
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch
symbol_type Opzionale
Tipo
str minLength=1
Descrizione
Filtra per tipo di simbolo indicizzato, ad es. function, class, struct, enum o trait. Usa il tipo restituito da un risultato di simbolo; il tipo varia in base al linguaggio.
high_impact Opzionale
Tipo
bool
Predefinito
false
Descrizione
Esplora i simboli importanti dal punto di vista architetturale (ometti symbol_name). La modalità predefinita è popularity (decile superiore per PageRank, esclusi i mega-hub di utilità). Imposta high_impact_mode=risk per i vertici di articolazione che collegano parti del grafo.
high_impact_mode Opzionale
Tipo
Literal[popularity, risk]
Predefinito
popularity
Descrizione
Quando high_impact=true: popularity = decile superiore per PageRank, esclusi mega-hub e moduli di utilità; risk = punti di articolazione ordinati prima per SMV bridge_count, poi per k_core (rischio strutturale del refactoring, non popolarità degli hub)
in_cycle Opzionale
Tipo
bool
Predefinito
false
Descrizione
Filtra i simboli con appartenenza registrata a un ciclo di dipendenze.
exclude_test_paths Opzionale
Tipo
bool
Predefinito
true
Descrizione
Quando esplori in base alle metriche del grafo, esclude test, fixture, codice di terze parti ed esempi prima dell'ordinamento; la ricerca per nome del simbolo resta invariata
reference_views Opzionale
Tipo
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
Descrizione
Viste del grafo i cui archi entranti popolano references/reference_count (scope references/both). Predefinito ["dependency", "type"]: chiamate, importazioni, esportazioni, riferimenti, istanziazioni, ereditarietà, ridefinizioni, decoratori e uso dei tipi. Se data_flow non è selezionato, gli usi data_flow risolti esattamente (callback, gestori, chiavi di ordinamento) vengono restituiti separatamente come value_references/value_reference_count, senza corrispondenze dedotte dal solo nome. Aggiungi data_flow o control_flow, oppure passa ["all"] per tutti i tipi e livelli di arco. Le stesse famiglie di viste di graph_view in dependency_search.
relationship_types Opzionale
Tipo
list[str]
Descrizione
Tipi espliciti di archi di riferimento (CALL, IMPORT, READS ecc.). Una lista non vuota sostituisce reference_views.

Ideale per:

  • Individuare la definizione, i riferimenti e le metriche di grafo di un simbolo noto
  • Esplorare per centrality, high_impact o in_cycle quando symbol_name viene omesso

Sconsigliato per:

  • Query concettuali o aree sconosciute — usa intelligent_search o semantic_search

analyze_dependencies Stabile

Analizza il raggio d'impatto usando lo stesso attraversamento di dependency_search (dependents/incoming). Preferisci dependency_search con analysis_type="dependents" o "impact" per l'analisi d'impatto. Restituisce una risposta d'impatto su più passaggi con graph, connection_summary e metriche opzionali con refactor_risk. connection_summary conta, per la radice scelta, gli archi limitati alla famiglia di relazioni, prima di qualsiasi filtro su test o percorsi. I campi legacy incoming_production/outgoing_production indicano archi non di modulo, test compresi; non sono conteggi di chiamanti di produzione. Usa graph_view per delimitare la famiglia di relazioni: dependency (predefinita), type, data_flow, control_flow.

Parametri:

repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
target Obbligatorio
Tipo
str minLength=1
Descrizione
Nome del simbolo da analizzare
symbol_id Opzionale
Tipo
UUID
Descrizione
Seleziona tramite UUID una specifica occorrenza tra i candidati di target, dopo aver filtrato per namespace, percorso e linguaggio; gli ID fuori dalla finestra limitata di candidati generano un errore.
depth Opzionale
Tipo
Literal[shallow, balanced, deep]
Predefinito
balanced
Descrizione
Profondità di analisi
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
10
Descrizione
Numero massimo di risultati per pagina senza cursor. La continuazione usa la dimensione di pagina memorizzata in cursor; ometti cursor per iniziare con un limit diverso.
offset Opzionale
Tipo
int minimum=0
Descrizione
Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
cursor Opzionale
Tipo
str
Descrizione
cursor opaco proveniente da pagination.next_cursor. Passalo invariato e mantieni invariati query e i filtri. La sua posizione e la dimensione di pagina hanno la precedenza su offset e limit.
direction Opzionale
Tipo
Literal[incoming, outgoing, both]
Predefinito
incoming
Descrizione
Direzione di traversata
relationship_types Opzionale
Tipo
list[str]
Descrizione
Filtra i tipi di arco (CALL, IMPORT, INHERITS_FROM, ecc.). Un elenco non vuoto sovrascrive i valori predefiniti di graph_view; un elenco vuoto usa quei valori predefiniti.
graph_view Opzionale
Tipo
Literal[dependency, type, data_flow, control_flow]
Predefinito
dependency
Descrizione
Vista del grafo: determina sia i tipi di arco attraversati per impostazione predefinita sia le metriche di quale vista vengono usate quando include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (predefinito), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Applicato come valore predefinito di relationship_types quando relationship_types è omesso o vuoto. Corrisponde al nome del parametro graph_view già esistente in dependency_search, per coerenza tra gli strumenti.
path_filter Opzionale
Tipo
str
Descrizione
Limita la risoluzione del simbolo target tramite prefisso del percorso file; le relazioni del grafo restituite possono estendersi oltre quel percorso.
language_filter Opzionale
Tipo
str
Descrizione
Filtro linguaggio
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch
per_hop_limit Opzionale
Tipo
int minimum=1, maximum=300
Descrizione
Relazioni massime per hop (1-300)
include_metrics Opzionale
Tipo
bool
Predefinito
false
Descrizione
Include nei risultati le metriche del grafo, arricchite con un blocco refactor_risk derivato ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk è "low" se il simbolo non è un punto di articolazione nella vista selezionata, "medium" se è un punto di articolazione che collega pochi archi, "high" se ne collega molti (soglia euristica, non validata empiricamente). Il blocco di metriche viene omesso per i simboli per cui non esiste una riga di metriche relativa a quella vista.
metrics_detail Opzionale
Tipo
Literal[summary, full]
Predefinito
summary
Descrizione
Quando include_metrics=true: summary (predefinito) restituisce segnali decisionali + refactor_risk; full restituisce il set di metriche curate più ampio
include_edge_metadata Opzionale
Tipo
bool
Predefinito
false
Descrizione
Include i metadati grezzi e i pesi degli archi. Disattivato per impostazione predefinita perché i metadati dell'estrattore possono essere voluminosi; quando è attivo, viene indicata la copertura dell'arricchimento.
exclude_test_paths Opzionale
Tipo
bool
Predefinito
true
Descrizione
Valore predefinito true: esclude dagli archi del grafo restituiti i percorsi di test, fixture, codice di terze parti ed esempi. Imposta false per includerli.
include_module_symbols Opzionale
Tipo
bool
Predefinito
false
Descrizione
Valore predefinito false: esclude gli archi in cui from_name o to_name è il simbolo sintetico __module__. Imposta true per includere gli archi a livello di modulo.
head_commit Opzionale
Tipo
str pattern=^[0-9a-fA-F]{7,64}$
Descrizione
SHA del commit del codice su cui stai facendo la domanda (git rev-parse HEAD, oppure il commit base della patch). complete:true richiede che l'indice sia a questo commit e sia stato costruito dal resolver attuale; altrimenti resta complete:false con index_stale / index_freshness_unverified / index_built_by_older_resolver, e index_basis.statement indica entro quali limiti la risposta è completa. Lo fornisce anche la riga 'base-commit:' di una patch (git format-patch --base).

Ideale per:

  • Analisi d'impatto su più passaggi quando servono i campi di risposta graph e connection_summary

Sconsigliato per:

  • Analisi d'impatto generale: preferisci dependency_search per attraversamenti flessibili e controlli con più radici

get_task_context Stabile

Stai iniziando a lavorare in un'area che non conosci? Descrivi il compito (ad es. "aggiungi supporto SSO", "correggi il webhook di fatturazione") e ottieni, con un'unica chiamata, un pacchetto limitato di file, codice, simboli e dipendenze pertinenti. I file forniti come seed contribuiscono con contenuto indicizzato direttamente anche se non definiscono alcun simbolo. I layer falliti vengono etichettati; un fallimento totale del recupero restituisce un errore dello strumento. Per altri risultati, continua con lo strumento di ricerca specializzato per quel layer.

Parametri:

task_description Obbligatorio
Tipo
str minLength=1
Descrizione
Descrizione dell'attività per cui serve il contesto
repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
15
Descrizione
Elementi di contesto massimi per layer
scope Opzionale
Tipo
Literal[semantic, symbols, dependencies, all]
Predefinito
all
Descrizione
Quali layer di contesto includere
language_filter Opzionale
Tipo
str
Descrizione
Filtro della lingua: richiede scope=semantic senza punti di partenza espliciti né contesto correlato; gli indici degli altri livelli non possono imporre la lingua.
path_filter Opzionale
Tipo
str
Descrizione
Prefisso del percorso file per le radici di recupero semantico e per parole chiave. I punti di partenza espliciti possono trovarsi al di fuori di questo prefisso; il contesto del grafo può attraversare i confini delle directory.
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch
include_related_context Opzionale
Tipo
bool
Predefinito
false
Descrizione
Includi contesto correlato dai simboli adiacenti
seed_symbol_ids Opzionale
Tipo
list[str] maxItems=20
Descrizione
Punti di partenza espliciti del task: compaiono per primi nel livello dei simboli e vengono mantenuti all'interno della finestra limitata dependencies/related_context. I livelli del grafo ordinano i punti di partenza espliciti e il loro vicinato più prossimo prima di ripiegare sulle parole chiave; l'importanza decide solo a parità di pertinenza. L'espansione del grafo richiede scope=all|dependencies (scope=symbols|semantic non esegue mai l'attraversamento delle dipendenze). Ometti il parametro per un ordinamento basato solo su parole chiave, per importanza decrescente con la profondità.
seed_file_paths Opzionale
Tipo
list[str] maxItems=10
Descrizione
Punti di partenza espliciti: percorsi esatti di file indicizzati che l'agente ha aperto o appena modificato. Restituisce un insieme limitato di contenuti direttamente dai file e fino a 5 punti di partenza del grafo per file, dando la precedenza alle corrispondenze esatte con il nome del task provenienti da una ricerca di simboli limitata, prima delle definizioni e dei simboli incidentali. Anche i file privi di simboli forniscono elementi probanti. I file mancanti possono restituire suggerimenti etichettati che non sono punti di partenza. L'espansione del grafo richiede scope=all|dependencies.

Ideale per:

  • Contesto consapevole del task che unisce i file seed a livelli semantici, di simboli e di dipendenze

Sconsigliato per:

  • Ricerche con un singolo strumento quando uno strumento più specifico risponde già alla domanda

get_file Stabile

Legge un file dal repository indicizzato tramite percorso. Preferisci gli strumenti per file locali per i file su disco; usa questo per gli snapshot indicizzati remoti. Continua le risposte limitate con metadata.next_line_start e next_character_start. Rimuovi il ritorno a capo finale e il marcatore [truncated] solo quando metadata.truncated=true; altrimenti potrebbe essere testo sorgente letterale.

Parametri:

file_path Obbligatorio
Tipo
str
Descrizione
Percorso del file relativo alla radice del repository
repository Opzionale
Tipo
str
Descrizione
Repository come owner/repo[:branch]. Facoltativo — ometti per usare il default del client a livello di richiesta (quando fornito) o l'unico repository accessibile; passalo esplicitamente solo per indirizzare un repo indicizzato diverso. Vengono preferiti i branch indicizzati esattamente corrispondenti; un branch non disponibile può ripiegare su main o sull'unico branch accessibile. I metadati della risposta mostrano l'identità richiesta e quella effettivamente risolta, con un avviso in caso di questo ripiego.
line_start Opzionale
Tipo
int minimum=1
Descrizione
Linea di inizio (1-indicizzata)
line_end Opzionale
Tipo
int minimum=1
Descrizione
Riga finale (1-indicizzata, inclusa; deve essere uguale o successiva a line_start)
character_start Opzionale
Tipo
int minimum=0
Predefinito
0
Descrizione
Offset in unità di codice UTF-16 solo all'interno della riga iniziale (indice da 0). Usa metadata.next_character_start per proseguire una riga letta parzialmente.
branch Opzionale
Tipo
str
Descrizione
Sovrascrittura del branch
max_tokens Opzionale
Tipo
int minimum=1, maximum=50000
Predefinito
5000
Descrizione
Budget approssimativo del contenuto (4 unità di codice UTF-16 per token; non un limite esatto del tokenizer).
include_metadata Opzionale
Tipo
bool
Predefinito
true
Descrizione
Include i metadati descrittivi del file. I metadati di troncamento e continuazione vengono sempre restituiti.

Ideale per:

  • Snapshot di file remoti o indicizzati (intervalli di righe, limiti di token)

Sconsigliato per:

  • Un percorso già presente sul disco locale — usa lo strumento Read locale

Strumenti di sistema e utilità

#

repository_context Stabile

Elenca i repository che puoi cercare, oppure ottiene informazioni identificative su uno di essi (namespace/branch, indexed_commit_sha / aggiornamento dell'indice). Usa action:"list" quando lo slug del repository è sconosciuto; gli strumenti di ricerca accettano direttamente uno slug noto oppure usano per impostazione predefinita l'unico repository della tua chiave. list usa pattern e paginazione; info richiede repository e supporta branch e include_statistics=true opzionale.

Parametri:

action Obbligatorio
Tipo
Literal[list, info]
Descrizione
Azione: elenca i repo disponibili o ottieni info su un repo
repository Opzionale
Tipo
str
Descrizione
Solo per info: repository nel formato owner/repo o owner/repo:branch (obbligatorio per info)
branch Opzionale
Tipo
str
Descrizione
Solo per info: sovrascrittura del branch
pattern Opzionale
Tipo
str
Descrizione
Solo per list: sottostringa del nome del repository, senza distinzione tra maiuscole e minuscole
include_statistics Opzionale
Tipo
bool
Predefinito
false
Descrizione
Solo informativo: include conteggi limitati dei dati indicizzati. I conteggi file/blob sono esatti; i conteggi dell'indice più grandi sono stime. Consulta count_accuracy ed estimate_analyzed_at. Predefinito false.
limit Opzionale
Tipo
int minimum=1, maximum=50
Predefinito
20
Descrizione
Numero massimo di risultati per pagina senza cursor. La continuazione usa la dimensione di pagina memorizzata in cursor; ometti cursor per iniziare con un limit diverso.
offset Opzionale
Tipo
int minimum=0
Descrizione
Offset di compatibilità deprecato. Usa preferibilmente cursor con il valore restituito in pagination.next_cursor.
cursor Opzionale
Tipo
str
Descrizione
cursor opaco proveniente da pagination.next_cursor. Passalo invariato e mantieni invariati query e i filtri. La sua posizione e la dimensione di pagina hanno la precedenza su offset e limit.

Ideale per:

  • Elencare i repository accessibili
  • Risolvere l'identità del repository, il branch e l'aggiornamento di HEAD rispetto all'indice

Sconsigliato per:

  • Statistiche a livello di namespace per impostazione predefinita — passa esplicitamente include_statistics=true, poiché può essere più lento della sola risoluzione

ask_maguyva Stabile

Ottieni indicazioni sugli strumenti Maguyva oppure invia una segnalazione di bug o una richiesta di funzionalità, conservata per i responsabili di Maguyva. Non includere mai segreti o dati personali sensibili nel feedback. L'operazione evaluate supporta espressioni deterministiche; preferisci il calcolo locale o gli strumenti dell'ambiente per matematica, hash e stringhe.

Parametri:

operation Obbligatorio
Tipo
Literal[guidance, report_bug, request_feature, evaluate]
Descrizione
Usa guidance per la guida agli strumenti, report_bug per i bug o request_feature per i suggerimenti. evaluate esegue espressioni deterministiche; preferisci il calcolo locale per i calcoli.
query Opzionale
Tipo
str maxLength=500
Descrizione
Argomento della guida (ad esempio tool_selection, semantic_search) oppure una stringa di espressione per evaluate.
description Opzionale
Tipo
str minLength=1, maxLength=4000
Descrizione
Obbligatorio per report_bug e request_feature. Feedback in testo libero per i manutentori di Maguyva. Non includere mai segreti o dati personali sensibili.
related_tool Opzionale
Tipo
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]
Descrizione
Strumento opzionale Maguyva più strettamente correlato al feedback

Ideale per:

  • Indicazioni sugli strumenti (operation="guidance")
  • Segnalazioni di bug durature e richieste di funzionalità per i maintainer di Maguyva

Sconsigliato per:

  • Calcoli matematici, hash e stringhe: preferisci il calcolo locale o gli strumenti dell'ambiente

Best practice

#
  1. Usa le sovrascritture esplicite con criterio: Ometti il repository quando il tuo client MCP fornisce un default per la richiesta o la chiave può accedere a un solo repository; altrimenti passalo esplicitamente.
  2. Scegli la modalità di ricerca giusta: Usa intelligent_search con mode="auto" nella maggior parte dei casi. Specifica una modalità quando sai esattamente cosa ti serve.
  3. Sfrutta i filtri per linguaggio: Usa language_filter per restringere i risultati e migliorare le prestazioni.
  4. Potenziamento GraphRAG: Il potenziamento per importanza di GraphRAG è disattivato per impostazione predefinita per la ricerca semantica (boost_by_importance=false), per mantenere il ranking sicuro per gli agenti. Passa boost_by_importance=true per abilitare il riordinamento basato sulla centralità nei tour architetturali.
  5. La corrispondenza dei repository non distingue le maiuscole, ma non è fuzzy: repository_context confronta i nomi dei repository senza distinguere maiuscole e minuscole, ma non corregge i refusi. Quando l'identità restituita è diversa da quella richiesta, metadata.resolution_reason riporta "defaulted" (nessun branch richiesto) oppure "fallback" (il branch o il repository richiesto non è disponibile). Il campo viene omesso quando la richiesta corrisponde esattamente.
  6. Combina gli strumenti: Usa più metodi API insieme per un'analisi completa.
  7. Gestisci risultati numerosi: Usa limit e i controlli di paginazione specifici dello strumento (ad esempio line_start/line_end in get_file).
  8. Usa ask_maguyva per la guida sugli strumenti: Chiama ask_maguyva con operation="guidance" e query="tool_selection" per consigli sulla scelta degli strumenti ed esempi. Usa gli strumenti locali per calcoli e trasformazioni di stringhe.
  9. Verifica l'impatto prima e dopo la modifica: Prima di modificare un simbolo condiviso, chiama dependency_search con analysis_type="impact" (oppure passa changed_paths per l'impatto di una PR/diff) per vedere il suo raggio d'impatto. Dopo la modifica, imposta verify_after_edit=true con targets e/o changed_paths per un ricontrollo compatto del grafo indicizzato. Non legge le modifiche locali non ancora registrate in un commit e non sostituisce i test locali. Controlla indexed_commit_sha e l'aggiornamento dell'indice prima di considerare i risultati una prova relativa a una nuova revisione.

Caratteristiche di prestazione

#
Operazione Note sulle prestazioni
Ricerca semantica Include la generazione dell'embedding della query e il recupero vettoriale. La latenza dipende da entrambe le operazioni.
Ricerca testuale Nella ricerca approssimata nei contenuti, le pagine più profonde recuperano più candidati. Restringi la query con path_filter e language_filter.
Ricerca strutturale Interroga i nodi AST indicizzati. Usa una preimpostazione o un pattern specifico e limita il numero di risultati.
Ricerca delle dipendenze Il costo scala con la profondità — preferisci depth="shallow" a meno che tu non abbia bisogno di contesto multi-hop; per_hop_limit limita l'espansione
Recupero file Leggi l'intervallo necessario con line_start/line_end o max_tokens e usa i metadati di continuazione restituiti per i contenuti troncati.
Contesto del repository La risoluzione del repository viene eseguita per ogni chiamata a uno strumento. Passa repository esplicitamente quando ti serve un repository specifico.
ask_maguyva (guidance / evaluate) Viene eseguito nel server MCP senza interrogare l'indice del repository.

Gestione degli errori

#

Le risposte degli strumenti contengono campi di stato comuni e campi dati specifici dello strumento al livello principale. Le ricerche restituiscono results; get_file restituisce content. I campi comuni includono:

  • status: Stringa — "success" o "error". I segnali di corrispondenza degradata e di freschezza hanno campi propri: metadata.resolution_reason sotto metadata e index_freshness.status al primo livello dell'azione info di repository_context.
  • timing_ms: Tempo trascorso per l'esecuzione dello strumento, in millisecondi
  • applied_filters: Parametri effettivi della richiesta registrati per l'operazione
  • error: Stringa del messaggio di errore quando status è "error"; può includere indicazioni per il ripristino.
  • metadata: Informazioni aggiuntive sull'operazione (instradamento, caching, aggiustamenti dei parametri)
  • pagination: Presente nelle risposte di raccolte paginate tramite cursore: include has_more e next_cursor. Le finestre di ricerca ordinate sono risultati top-K limitati, non raccolte paginate esaustive.

Controlla il campo status prima di elaborare il payload di uno strumento: i suoi valori sono "success" o "error". Gestisci anche gli errori di trasporto MCP/JSON-RPC e di validazione della richiesta, che possono verificarsi prima ancora che venga prodotto un payload. Per i segnali di corrispondenza degradata o di freschezza leggi invece il campo dedicato: metadata.resolution_reason sotto metadata, oppure index_freshness.status al primo livello dell'azione info di repository_context (known/partial/unknown/unavailable).

Come iniziare

#
  1. Configura il client MCP: Punta il tuo client MCP all'endpoint del server Maguyva
  2. Conferma l'accesso ai repository: Usa repository_context con action="list" o action="info" per ispezionare i repository accessibili dalla chiave API
  3. Inizia a cercare: Inizia con intelligent_search ed esplora gli strumenti specializzati secondo necessità
  4. Combina gli strumenti: Usa più strumenti insieme per un'analisi del codice completa

Per istruzioni di integrazione dettagliate, vedi la guida all'installazione.

Correlati

Da leggere