Riferimento API MCP

Riferimento completo per tutti i 11 strumenti MCP di Maguyva rivolti ai clienti. Ogni strumento include parametri, indicazioni d'uso e consigli su quando è più adatto.

Panoramica dell'API#

L'API MCP di Maguyva espone attualmente 11 strumenti rivolti ai clienti in 4 categorie principali:

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, calcolo deterministico e guida

Tutti gli strumenti usano un formato dell'identificatore del repository coerente: "owner/repo:branch". Il branch è impostato su main se non specificato.

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#

Tutti gli strumenti MCP usano questo formato di identificatore del 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 linguistico#

Tutti gli strumenti di ricerca supportano il filtro dei risultati per linguaggio di programmazione:

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 linguistici funzionano su oltre 279 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 22 luglio 2026.

Strumenti di ricerca principali#

intelligent_searchStabile

Inizia qui per qualsiasi domanda sulla base di codice. Forniscigli una query in linguaggio naturale (ad esempio "come funziona l'autenticazione", "dove viene gestita la fatturazione") e si instrada automaticamente attraverso la ricerca semantica, di simboli, strutturale e di dipendenza del repository indicizzato. Preferiscilo all'agente Explore e Grep/Glob per l'esplorazione e la pianificazione: esegue la ricerca nell'intero repository indicizzato contemporaneamente invece di scansionare i file.

Parametri:

queryObbligatorio

Tipo: str
Descrizione: Query di ricerca

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

modeOpzionale

Tipo: Literal[auto, hybrid, semantic, text, structural, ast, graph]
Predefinito: auto
Descrizione: Modalità di ricerca

limitOpzionale

Tipo: int
Predefinito: 10
Descrizione: Risultati massimi in questa finestra top-K classificata

language_filterOpzionale

Tipo: str
Descrizione: Filtro lingua

path_filterOpzionale

Tipo: str
Descrizione: Filtra per prefisso del percorso file

boost_by_importanceOpzionale

Tipo: bool
Predefinito
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.

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

qualityOpzionale

Tipo: Literal[quick, balanced, thorough]
Predefinito: balanced
Descrizione: Preset qualità della ricerca

include_contentOpzionale

Tipo: bool
Predefinito: true
Descrizione: Includi il contenuto nei risultati

explain_routingOpzionale

Tipo: bool
Predefinito
Descrizione: Includi spiegazione della decisione di instradamento

importance_weightOpzionale

Tipo: float
Predefinito: 0.3
Descrizione: Peso per il potenziamento per importanza (0=nessuno, 1=intero)

orphansOpzionale

Tipo: bool
Predefinito
Descrizione: Includi simboli orfani (senza riferimenti in ingresso)

include_community_contextOpzionale

Tipo: bool
Predefinito
Descrizione: Includi simboli correlati della stessa community di codice

community_depthOpzionale

Tipo: int
Predefinito: 1
Descrizione: Profondità di espansione del contesto della community

graph_viewOpzionale

Tipo: Literal[dependency, type, data_flow, control_flow]
Predefinito: dependency
Descrizione: Vista grafo per le metriche

seed_symbol_idsOpzionale

Tipo: list[str]
Descrizione: Seeds attività Tier-1: ID dei simboli centrali per l'attività corrente. Quando impostato, riclassifica i risultati fusi in base alla prossimità del decadimento della profondità Approach A (corrispondenza seme esatta + salti sul bordo del grafico). Additivo: omettere per la classifica globale.

seed_file_pathsOpzionale

Tipo: list[str]
Descrizione: Seeds attività Tier-1: percorsi di file indicizzati che l'agente ha aperto o appena modificato. Quando impostato, riclassifica i risultati fusi in base alla prossimità del percorso con decadimento della profondità 1/(1+d) (stesso file → stessa directory → pacchetti vicini). Additivo: omettere per la classifica globale.

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`query`	`str`	Sì	-	Query di ricerca
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	No	`auto`	Modalità di ricerca
`limit`	`int`	No	`10`	Risultati massimi in questa finestra top-K classificata
`language_filter`	`str`	No	-	Filtro lingua
`path_filter`	`str`	No	-	Filtra per prefisso del percorso file
`boost_by_importance`	`bool`	No		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`	`str`	No	-	Sovrascrittura del branch
`quality`	`Literal[quick, balanced, thorough]`	No	`balanced`	Preset qualità della ricerca
`include_content`	`bool`	No	`true`	Includi il contenuto nei risultati
`explain_routing`	`bool`	No		Includi spiegazione della decisione di instradamento
`importance_weight`	`float`	No	`0.3`	Peso per il potenziamento per importanza (0=nessuno, 1=intero)
`orphans`	`bool`	No		Includi simboli orfani (senza riferimenti in ingresso)
`include_community_context`	`bool`	No		Includi simboli correlati della stessa community di codice
`community_depth`	`int`	No	`1`	Profondità di espansione del contesto della community
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Vista grafo per le metriche
`seed_symbol_ids`	`list[str]`	No	-	Seeds attività Tier-1: ID dei simboli centrali per l'attività corrente. Quando impostato, riclassifica i risultati fusi in base alla prossimità del decadimento della profondità Approach A (corrispondenza seme esatta + salti sul bordo del grafico). Additivo: omettere per la classifica globale.
`seed_file_paths`	`list[str]`	No	-	Seeds attività Tier-1: percorsi di file indicizzati che l'agente ha aperto o appena modificato. Quando impostato, riclassifica i risultati fusi in base alla prossimità del percorso con decadimento della profondità 1/(1+d) (stesso file → stessa directory → pacchetti vicini). Additivo: omettere per la classifica globale.

Il più adatto per:

Esplorazione a livello di indice o a freddo quando lo strumento giusto non è chiaro
Classificazione fusa multimodale tra ricerca semantica, testuale, strutturale e di grafo

Sconsigliato per:

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

semantic_searchStabile

Trova il codice in base al significato, non al testo esatto. Utilizzare per query concettuali come "logica dei nuovi tentativi" o "flusso di onboarding dell'utente" quando non si conosce la parola chiave o il nome del simbolo. Restituisce i blocchi di codice più rilevanti classificati in base all'importanza. Preferisce Grep quando la ricerca è concettuale.

Parametri:

queryObbligatorio

Tipo: str
Descrizione: Query di ricerca (concettuale, basata sul significato)

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

limitOpzionale

Tipo: int
Predefinito: 5
Descrizione: Risultati massimi in questa finestra top-K classificata

similarity_thresholdOpzionale

Tipo: float
Predefinito: 0.6
Descrizione: Soglia minima di similarità

language_filterOpzionale

Tipo: str
Descrizione: Filtro linguaggio (python, typescript, ecc.)

path_filterOpzionale

Tipo: str
Descrizione: Filtra per prefisso del percorso file

boost_by_importanceOpzionale

Tipo: bool
Predefinito
Descrizione: Opzionale: riclassifica in base alla centralità PageRank (disattivato per impostazione predefinita per una classifica sicura per gli agenti; attivalo per i tour architetturali)

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch (predefinito: dal parametro repository o main)

include_contentOpzionale

Tipo: bool
Predefinito: true
Descrizione: Includi il contenuto dei chunk nei risultati

graph_viewOpzionale

Tipo: Literal[dependency, type, data_flow, control_flow]
Predefinito: dependency
Descrizione: Vista grafo per le metriche

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`query`	`str`	Sì	-	Query di ricerca (concettuale, basata sul significato)
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`limit`	`int`	No	`5`	Risultati massimi in questa finestra top-K classificata
`similarity_threshold`	`float`	No	`0.6`	Soglia minima di similarità
`language_filter`	`str`	No	-	Filtro linguaggio (python, typescript, ecc.)
`path_filter`	`str`	No	-	Filtra per prefisso del percorso file
`boost_by_importance`	`bool`	No		Opzionale: riclassifica in base alla centralità PageRank (disattivato per impostazione predefinita per una classifica sicura per gli agenti; attivalo per i tour architetturali)
`branch`	`str`	No	-	Sovrascrittura del branch (predefinito: dal parametro repository o main)
`include_content`	`bool`	No	`true`	Includi il contenuto dei chunk nei risultati
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Vista grafo per le metriche

Il più adatto 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_searchStabile

Cerca nel contenuto indicizzato. Le modalità exact e regex eseguono grep sull'intero corpus di file/blob; la modalità fuzzy sul contenuto cerca nel corpus limitato dei chunk semantici. Gli ambiti file e symbol sono solo fuzzy. Usa il grep locale per una directory già presente su disco.

Parametri:

queryObbligatorio

Tipo: str
Descrizione: Pattern di testo da cercare

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

modeOpzionale

Tipo: Literal[fuzzy, exact, regex]
Predefinito: exact
Descrizione: Modalità di ricerca

search_scopeOpzionale

Tipo: Literal[content, symbols, files]
Predefinito: content
Descrizione: Cosa cercare

limitOpzionale

Tipo: int
Predefinito: 5
Descrizione: Risultati massimi restituiti in questa pagina

offsetOpzionale

Tipo: int
Descrizione: Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.

cursorOpzionale

Tipo: str
Descrizione: Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.

language_filterOpzionale

Tipo: str
Descrizione: Filtro lingua

path_filterOpzionale

Tipo: str
Descrizione: Filtra per prefisso del percorso file

case_sensitiveOpzionale

Tipo: bool
Predefinito
Descrizione: Corrispondenza sensibile alle maiuscole/minuscole

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

fuzzy_algorithmOpzionale

Tipo: Literal[hybrid, trigram, levenshtein]
Predefinito: hybrid
Descrizione: Algoritmo di matching fuzzy

thresholdOpzionale

Tipo: float
Predefinito: 0.05
Descrizione: Soglia minima di similarità per fuzzy

semantic_fallbackOpzionale

Tipo: bool
Predefinito
Descrizione: Torna alla ricerca semantica se non ci sono risultati

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`query`	`str`	Sì	-	Pattern di testo da cercare
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`mode`	`Literal[fuzzy, exact, regex]`	No	`exact`	Modalità di ricerca
`search_scope`	`Literal[content, symbols, files]`	No	`content`	Cosa cercare
`limit`	`int`	No	`5`	Risultati massimi restituiti in questa pagina
`offset`	`int`	No	-	Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
`cursor`	`str`	No	-	Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.
`language_filter`	`str`	No	-	Filtro lingua
`path_filter`	`str`	No	-	Filtra per prefisso del percorso file
`case_sensitive`	`bool`	No		Corrispondenza sensibile alle maiuscole/minuscole
`branch`	`str`	No	-	Sovrascrittura del branch
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	No	`hybrid`	Algoritmo di matching fuzzy
`threshold`	`float`	No	`0.05`	Soglia minima di similarità per fuzzy
`semantic_fallback`	`bool`	No		Torna alla ricerca semantica se non ci sono risultati

Il più adatto 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_searchStabile

Preferisci preset=functions|classes|methods|imports|variables (o pattern= libero). Trova il codice in base alla forma AST (non al testo). Filtri di livello intermedio: name_pattern, node_type, decorator, parent_child. I filtri di percorso/ltree/chiamata sono avanzati — imposta advanced=true quando li usi deliberatamente; le chiavi avanzate in formato flat restano accettate per retrocompatibilità. Fornisci almeno un selettore strutturale.

Parametri:

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

presetOpzionale

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 (definizioni di classe/struct/impl); 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.

patternOpzionale

Tipo: str
Descrizione: Pattern Free-form quando i preset sono troppo generici (rilevato automaticamente: 'def foo(' → node_type + name_pattern). Preferisci preset= per le query di tipo browse.

name_patternOpzionale

Tipo: str
Descrizione: Pattern del nome del simbolo (wildcard shell, espressione regolare POSIX delimitata o testo fuzzy; massimo 256 caratteri)

node_typeOpzionale

Tipo: str
Descrizione: Tipo di nodo AST (function_definition, class_definition, ecc.) — preferisci preset= per le forme comuni

decoratorOpzionale

Tipo: str
Descrizione: Filtro per nome del decoratore

base_classOpzionale

Tipo: str
Descrizione: Filtro per classe base

language_filterOpzionale

Tipo: str
Descrizione: Filtro lingua (python, typescript, ecc.)

limitOpzionale

Tipo: int
Predefinito: 20
Descrizione: Risultati massimi restituiti in questa pagina

offsetOpzionale

Tipo: int
Descrizione: Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.

cursorOpzionale

Tipo: str
Descrizione: Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.

path_filterOpzionale

Tipo: str
Descrizione: Filtra per prefisso del percorso file

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

query_typeOpzionale

Tipo: Literal[node_type, name_pattern, parent_child]
Descrizione: Tipo di query esplicito

parent_typeOpzionale

Tipo: str
Descrizione: Filtro per tipo di nodo padre AST

relationshipOpzionale

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_modifierOpzionale

Tipo: str
Descrizione: Filtra per modifier (export, async, static, ecc.)

advancedOpzionale

Tipo: bool
Predefinito
Descrizione: Imposta true quando si utilizzano intenzionalmente filtri avanzati di percorso, ltree o chiamate (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Per impostazione predefinita, false mantiene l'interfaccia dell'agente focalizzata sulle preimpostazioni. Le chiavi avanzate nel formato flat funzionano ancora per la compatibilità con le versioni precedenti, con un avviso sui metadati.

callee_textOpzionale

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_nameOpzionale

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_roleOpzionale

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_ancestorOpzionale

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_descendantOpzionale

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_nameOpzionale

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_depthOpzionale

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_depthOpzionale

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.

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`preset`	`Literal[functions, classes, methods, imports, variables]`	No	-	Selettore strutturale preferito. Si espande in tipi di nodo AST multilinguaggio — functions (definizioni di funzione/arrow/metodo a seconda del linguaggio); classes (definizioni di classe/struct/impl); 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`	`str`	No	-	Pattern Free-form quando i preset sono troppo generici (rilevato automaticamente: 'def foo(' → node_type + name_pattern). Preferisci preset= per le query di tipo browse.
`name_pattern`	`str`	No	-	Pattern del nome del simbolo (wildcard shell, espressione regolare POSIX delimitata o testo fuzzy; massimo 256 caratteri)
`node_type`	`str`	No	-	Tipo di nodo AST (function_definition, class_definition, ecc.) — preferisci preset= per le forme comuni
`decorator`	`str`	No	-	Filtro per nome del decoratore
`base_class`	`str`	No	-	Filtro per classe base
`language_filter`	`str`	No	-	Filtro lingua (python, typescript, ecc.)
`limit`	`int`	No	`20`	Risultati massimi restituiti in questa pagina
`offset`	`int`	No	-	Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
`cursor`	`str`	No	-	Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.
`path_filter`	`str`	No	-	Filtra per prefisso del percorso file
`branch`	`str`	No	-	Sovrascrittura del branch
`query_type`	`Literal[node_type, name_pattern, parent_child]`	No	-	Tipo di query esplicito
`parent_type`	`str`	No	-	Filtro per tipo di nodo padre AST
`relationship`	`Literal[parent, ancestor]`	No	`parent`	Per query parent_child: solo genitore diretto, o qualsiasi antenato (usa ancestor per metodi di classe annidati nel corpo di una classe)
`has_modifier`	`str`	No	-	Filtra per modifier (export, async, static, ecc.)
`advanced`	`bool`	No		Imposta true quando si utilizzano intenzionalmente filtri avanzati di percorso, ltree o chiamate (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Per impostazione predefinita, false mantiene l'interfaccia dell'agente focalizzata sulle preimpostazioni. Le chiavi avanzate nel formato flat funzionano ancora per la compatibilità con le versioni precedenti, con un avviso sui metadati.
`callee_text`	`str`	No	-	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`	`str`	No	-	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`	`str`	No	-	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`	`str`	No	-	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`	`str`	No	-	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`	`str`	No	-	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`	`int`	No	-	Avanzato — preferisci preset=functions\|classes\|methods\|imports\|variables. Profondità AST minima. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.
`max_depth`	`int`	No	-	Avanzato — preferisci preset=functions\|classes\|methods\|imports\|variables. Profondità AST massima. Imposta advanced=true quando usi intenzionalmente filtri di percorso/ltree/chiamata.

Il più adatto 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_searchStabile

Superficie principale di blast radius / grafo. Risponde a "chi chiama questo?" / "cosa usa questo?" tramite il grafo reale di call/import. Per l'impatto prima della modifica: analysis_type="dependents" oppure analysis_type="impact" (in entrata, profondità superficiale predefinita per impact), include_metrics=false per impostazione predefinita (attivalo per centrality + refactor_risk). Impatto PR/diff (P1-8): passa changed_paths e/o patch (diff unificato) — risolve i simboli per percorso e restituisce un payload compatto di dipendenti in entrata superficiali senza richiedere un nome di simbolo. Dopo una modifica, imposta verify_after_edit=true con targets e/o changed_paths per una nuova interrogazione compatta multi-root dei simboli impattati. Supporta anche dependencies, centrality e orphans. analyze_dependencies è un alias leggero per il percorso impact — preferisci questo strumento per i nuovi agenti.

Parametri:

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

queryOpzionale

Tipo: str
Descrizione: Nome del simbolo o termine di ricerca

targetOpzionale

Tipo: str
Descrizione: Nome del simbolo (alias di query)

changed_pathsOpzionale

Tipo: list[str]
Descrizione: Percorsi relativi al repository per l'impatto PR/diff (impostazione predefinita) o, con verify_after_edit=true, radici di verifica post-modifica. PR/diff: risolve i simboli per percorso e percorre i dipendenti in entrata superficiali; può essere combinato con patch=. Verifica: risolve fino a 5 simboli per percorso come radici di verifica (limitate in basso all'interno della modalità di verifica). Non richiede query/target per l'impatto PR/diff.

patchOpzionale

Tipo: str
Descrizione: Impatto PR/diff: testo patch diff/git unificato. I percorsi vengono analizzati dalle intestazioni diff --git/---/+++; stesso percorso di impatto compatto di changed_paths.

analysis_typeOpzionale

Tipo: Literal[centrality, dependencies, dependents, impact, orphans]
Predefinito: dependencies
Descrizione: Modalità di analisi. impact = blast radius (dipendenti in entrata; profondità superficiale quando depth è omesso). dependents risponde anche a impact. Quando è impostato changed_paths o patch, l'analisi è forzata sull'impatto PR/diff. centrality/orphans non richiedono un target.

depthOpzionale

Tipo: Literal[shallow, balanced, deep]
Predefinito: balanced
Descrizione: Profondità di traversata. Per analysis_type=impact e l'impatto PR/diff il valore predefinito effettivo è shallow a meno che tu non imposti depth esplicitamente.

limitOpzionale

Tipo: int
Predefinito: 20
Descrizione: Risultati massimi restituiti in questa pagina

offsetOpzionale

Tipo: int
Descrizione: Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.

cursorOpzionale

Tipo: str
Descrizione: Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.

path_filterOpzionale

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_filterOpzionale

Tipo: str
Descrizione: Filtra la risoluzione del target e i risultati di browse per linguaggio

directionOpzionale

Tipo: Literal[outgoing, incoming, both]
Descrizione: Direzione di traversata (sovrascrive l'inferenza di analysis_type)

relationship_typesOpzionale

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_pathsOpzionale

Tipo: bool
Predefinito: true
Descrizione: Predefinito true: esclude i percorsi di test, fixture, fornitore ed esempio dai risultati di traversata e centralità. Imposta false per includerli. L'analisi degli orfani applica sempre le proprie esclusioni di rumore più rigorose.

exclude_generated_pathsOpzionale

Tipo: bool
Predefinito
Descrizione: Escludi le dichiarazioni generate oltre ai percorsi di compilazione, copertura, cache, mappa di origine e artefatti minimizzati dai risultati di attraversamento

include_module_symbolsOpzionale

Tipo: bool
Predefinito
Descrizione: Per impostazione predefinita, false esclude i bordi del grafico quando from_name o to_name è il simbolo sintetico __module__ (rumore a livello di modulo). Imposta true per includere i bordi a livello di modulo nei risultati per le relazioni dipendenti e di dipendenza.

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

per_hop_limitOpzionale

Tipo: int
Descrizione: Relazioni massime per hop (1-300)

include_metricsOpzionale

Tipo: bool
Predefinito
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_detailOpzionale

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_metadataOpzionale

Tipo: bool
Predefinito
Descrizione: Includi metadati e pesi del bordo grezzo (grande). I carichi utili a impatto compatto lo lasciano fuori.

symbol_typesOpzionale

Tipo: list[str]
Descrizione: Filtra i simboli restituiti per tipo (function, class, method, ecc.)

exact_matchOpzionale

Tipo: bool
Predefinito
Descrizione: Richiedi corrispondenza esatta del nome del simbolo

find_similar_patternsOpzionale

Tipo: bool
Predefinito
Descrizione: Trova pattern di utilizzo simili

min_centralityOpzionale

Tipo: float
Predefinito: 0
Descrizione: Punteggio PageRank minimo. Le metriche vengono recuperate internamente per il filtraggio; graph_metrics viene restituito solo quando include_metrics=true.

graph_viewOpzionale

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_editOpzionale

Tipo: bool
Predefinito
Descrizione: P2-7 modalità di verifica post-modifica: interroga nuovamente il grafico dell'impatto indicizzato per i simboli modificati di recente in una risposta multi-root compatta. Richiede targets e/o changed_paths (o target/query). Impostazioni predefinite per dipendenti in entrata superficiali; i risultati riflettono il grafico indicizzato (potrebbero ritardare le modifiche in tempo reale). Se vero, ha la precedenza sull'impatto di PR/diff sullo stesso changed_paths.

targetsOpzionale

Tipo: list[str]
Descrizione: Quando verify_after_edit=true: nomi dei simboli da verificare nuovamente (chiamanti/persone a carico). Unito a target/query se forniti entrambi.

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`query`	`str`	No	-	Nome del simbolo o termine di ricerca
`target`	`str`	No	-	Nome del simbolo (alias di query)
`changed_paths`	`list[str]`	No	-	Percorsi relativi al repository per l'impatto PR/diff (impostazione predefinita) o, con verify_after_edit=true, radici di verifica post-modifica. PR/diff: risolve i simboli per percorso e percorre i dipendenti in entrata superficiali; può essere combinato con patch=. Verifica: risolve fino a 5 simboli per percorso come radici di verifica (limitate in basso all'interno della modalità di verifica). Non richiede query/target per l'impatto PR/diff.
`patch`	`str`	No	-	Impatto PR/diff: testo patch diff/git unificato. I percorsi vengono analizzati dalle intestazioni diff --git/---/+++; stesso percorso di impatto compatto di changed_paths.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	No	`dependencies`	Modalità di analisi. impact = blast radius (dipendenti in entrata; profondità superficiale quando depth è omesso). dependents risponde anche a impact. Quando è impostato changed_paths o patch, l'analisi è forzata sull'impatto PR/diff. centrality/orphans non richiedono un target.
`depth`	`Literal[shallow, balanced, deep]`	No	`balanced`	Profondità di traversata. Per analysis_type=impact e l'impatto PR/diff il valore predefinito effettivo è shallow a meno che tu non imposti depth esplicitamente.
`limit`	`int`	No	`20`	Risultati massimi restituiti in questa pagina
`offset`	`int`	No	-	Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
`cursor`	`str`	No	-	Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.
`path_filter`	`str`	No	-	Limita la risoluzione del simbolo target tramite prefisso del percorso file; le relazioni del grafo restituite possono estendersi oltre quel percorso.
`language_filter`	`str`	No	-	Filtra la risoluzione del target e i risultati di browse per linguaggio
`direction`	`Literal[outgoing, incoming, both]`	No	-	Direzione di traversata (sovrascrive l'inferenza di analysis_type)
`relationship_types`	`list[str]`	No	-	Filtra i tipi di arco (CALL, IMPORT, INHERITS_FROM, ecc.). Un elenco non vuoto sovrascrive i default di graph_view.
`exclude_test_paths`	`bool`	No	`true`	Predefinito true: esclude i percorsi di test, fixture, fornitore ed esempio dai risultati di traversata e centralità. Imposta false per includerli. L'analisi degli orfani applica sempre le proprie esclusioni di rumore più rigorose.
`exclude_generated_paths`	`bool`	No		Escludi le dichiarazioni generate oltre ai percorsi di compilazione, copertura, cache, mappa di origine e artefatti minimizzati dai risultati di attraversamento
`include_module_symbols`	`bool`	No		Per impostazione predefinita, false esclude i bordi del grafico quando from_name o to_name è il simbolo sintetico __module__ (rumore a livello di modulo). Imposta true per includere i bordi a livello di modulo nei risultati per le relazioni dipendenti e di dipendenza.
`branch`	`str`	No	-	Sovrascrittura del branch
`per_hop_limit`	`int`	No	-	Relazioni massime per hop (1-300)
`include_metrics`	`bool`	No		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`	`Literal[summary, full]`	No	`summary`	Quando include_metrics=true: summary (predefinito) restituisce segnali decisionali + refactor_risk; full restituisce il set di metriche curate più ampio
`include_edge_metadata`	`bool`	No		Includi metadati e pesi del bordo grezzo (grande). I carichi utili a impatto compatto lo lasciano fuori.
`symbol_types`	`list[str]`	No	-	Filtra i simboli restituiti per tipo (function, class, method, ecc.)
`exact_match`	`bool`	No		Richiedi corrispondenza esatta del nome del simbolo
`find_similar_patterns`	`bool`	No		Trova pattern di utilizzo simili
`min_centrality`	`float`	No	`0`	Punteggio PageRank minimo. Le metriche vengono recuperate internamente per il filtraggio; graph_metrics viene restituito solo quando include_metrics=true.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	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`	`bool`	No		P2-7 modalità di verifica post-modifica: interroga nuovamente il grafico dell'impatto indicizzato per i simboli modificati di recente in una risposta multi-root compatta. Richiede targets e/o changed_paths (o target/query). Impostazioni predefinite per dipendenti in entrata superficiali; i risultati riflettono il grafico indicizzato (potrebbero ritardare le modifiche in tempo reale). Se vero, ha la precedenza sull'impatto di PR/diff sullo stesso changed_paths.
`targets`	`list[str]`	No	-	Quando verify_after_edit=true: nomi dei simboli da verificare nuovamente (chiamanti/persone a carico). Unito a target/query se forniti entrambi.

Il più adatto per:

Analisi di blast radius/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_symbolStabile

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_nameOpzionale

Tipo: str
Descrizione: Nome del simbolo da cercare (opzionale — ometti per esplorare per metriche)

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

scopeOpzionale

Tipo: Literal[definitions, references, both]
Predefinito: both
Descrizione: Ambito di ricerca

limitOpzionale

Tipo: int
Predefinito: 15
Descrizione: Risultati massimi restituiti in questa pagina

offsetOpzionale

Tipo: int
Descrizione: Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.

cursorOpzionale

Tipo: str
Descrizione: Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.

find_similarOpzionale

Tipo: bool
Predefinito
Descrizione: Includi nomi di simboli simili

include_metricsOpzionale

Tipo: bool
Predefinito
Descrizione: Includi metriche di centralità

metrics_detailOpzionale

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_filterOpzionale

Tipo: str
Descrizione: Filtra per prefisso del percorso file

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

symbol_typeOpzionale

Tipo: Literal[function, class, variable, method, constant, module, interface, type]
Descrizione: Filtra per tipo di simbolo

high_impactOpzionale

Tipo: bool
Predefinito
Descrizione: Esplora i simboli architetturalmente importanti (ometti symbol_name). La modalità predefinita è popularity (decile PageRank più alto meno i mega-hub di utilità). Imposta high_impact_mode=risk per punti di articolazione/archi ponte.

high_impact_modeOpzionale

Tipo: Literal[popularity, risk]
Predefinito: popularity
Descrizione: Quando high_impact=true: popolarità = decile PageRank più alto meno mega-hub/moduli di utilità; rischio = punti di articolazione classificati in base a SMV bridge_count quindi k_core (rischio di refactoring strutturale, non popolarità dell'hub)

in_cycleOpzionale

Tipo: bool
Predefinito
Descrizione: Filtra solo simboli in cicli di dipendenza

exclude_test_pathsOpzionale

Tipo: bool
Predefinito: true
Descrizione: Quando navighi in base alle metriche del grafico, escludi test, fixtures, codice di terze parti ed esempi prima della classificazione. La ricerca tramite un simbolo con nome rimane invariata.

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`symbol_name`	`str`	No	-	Nome del simbolo da cercare (opzionale — ometti per esplorare per metriche)
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`scope`	`Literal[definitions, references, both]`	No	`both`	Ambito di ricerca
`limit`	`int`	No	`15`	Risultati massimi restituiti in questa pagina
`offset`	`int`	No	-	Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
`cursor`	`str`	No	-	Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.
`find_similar`	`bool`	No		Includi nomi di simboli simili
`include_metrics`	`bool`	No		Includi metriche di centralità
`metrics_detail`	`Literal[summary, full]`	No	`summary`	Quando include_metrics=true: summary (predefinito) restituisce segnali decisionali + refactor_risk; full restituisce il set di metriche curate più ampio
`path_filter`	`str`	No	-	Filtra per prefisso del percorso file
`branch`	`str`	No	-	Sovrascrittura del branch
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	No	-	Filtra per tipo di simbolo
`high_impact`	`bool`	No		Esplora i simboli architetturalmente importanti (ometti symbol_name). La modalità predefinita è popularity (decile PageRank più alto meno i mega-hub di utilità). Imposta high_impact_mode=risk per punti di articolazione/archi ponte.
`high_impact_mode`	`Literal[popularity, risk]`	No	`popularity`	Quando high_impact=true: popolarità = decile PageRank più alto meno mega-hub/moduli di utilità; rischio = punti di articolazione classificati in base a SMV bridge_count quindi k_core (rischio di refactoring strutturale, non popolarità dell'hub)
`in_cycle`	`bool`	No		Filtra solo simboli in cicli di dipendenza
`exclude_test_paths`	`bool`	No	`true`	Quando navighi in base alle metriche del grafico, escludi test, fixtures, codice di terze parti ed esempi prima della classificazione. La ricerca tramite un simbolo con nome rimane invariata.

Il più adatto 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_dependenciesStabile

Alias per il blast radius tramite dependency_search (dependents/incoming). Preferisci dependency_search con analysis_type="dependents" o "impact" per i nuovi agenti. Mantiene la forma di risposta legacy multi-hop per l'impatto (graph, connection_summary, metriche opzionali con refactor_risk). Usa graph_view per delimitare la famiglia di relazioni: dependency (predefinito), type, data_flow, control_flow.

Parametri:

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

targetObbligatorio

Tipo: str
Descrizione: Nome del simbolo da analizzare

depthOpzionale

Tipo: Literal[shallow, balanced, deep]
Predefinito: balanced
Descrizione: Profondità di analisi

limitOpzionale

Tipo: int
Predefinito: 10
Descrizione: Risultati massimi restituiti in questa pagina

offsetOpzionale

Tipo: int
Descrizione: Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.

cursorOpzionale

Tipo: str
Descrizione: Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.

directionOpzionale

Tipo: Literal[incoming, outgoing, both]
Predefinito: incoming
Descrizione: Direzione di traversata

relationship_typesOpzionale

Tipo: list[str]
Descrizione: Filtra tipi di relazione (CALL, IMPORT, INHERITS_FROM, ecc.). Sovrascrive sempre il default derivato da graph_view quando fornito.

graph_viewOpzionale

Tipo: Literal[dependency, type, data_flow, control_flow]
Predefinito: dependency
Descrizione: Vista grafo: determina sia i tipi di arco di traversata predefiniti sia le metriche utilizzate 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 solo come default di relationship_types quando relationship_types non è fornito. Corrisponde al parametro graph_view di dependency_search per coerenza tra gli strumenti.

path_filterOpzionale

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_filterOpzionale

Tipo: str
Descrizione: Filtro linguaggio

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

per_hop_limitOpzionale

Tipo: int
Descrizione: Relazioni massime per hop (1-300)

include_metricsOpzionale

Tipo: bool
Predefinito
Descrizione: Includere le metriche del grafico nei risultati, ciascuno arricchito con un blocco refactor_risk derivato ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk è "low" quando non è un punto di articolazione (nella vista selezionata), "medium" quando un punto di articolazione collega pochi bordi, "high" quando ne collega molti (soglia euristica, non validata empiricamente). Omesso per simbolo quando non esiste alcuna riga di metrica per quel simbolo/vista.

metrics_detailOpzionale

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_metadataOpzionale

Tipo: bool
Predefinito
Descrizione: Includi metadati e pesi del bordo grezzo. Disabilitato per impostazione predefinita perché i metadati dell'estrattore possono essere di grandi dimensioni; la copertura dell'arricchimento viene segnalata quando abilitata.

exclude_test_pathsOpzionale

Tipo: bool
Predefinito: true
Descrizione: Predefinito true: esclude test, dispositivo, fornitore e percorsi di esempio dai bordi del grafico restituiti. Imposta false per includerli.

include_module_symbolsOpzionale

Tipo: bool
Predefinito
Descrizione: Per impostazione predefinita, false esclude i bordi del grafico quando from_name o to_name è il simbolo sintetico __module__. Imposta true per includere i bordi a livello di modulo.

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`target`	`str`	Sì	-	Nome del simbolo da analizzare
`depth`	`Literal[shallow, balanced, deep]`	No	`balanced`	Profondità di analisi
`limit`	`int`	No	`10`	Risultati massimi restituiti in questa pagina
`offset`	`int`	No	-	Offset di compatibilità deprecato. Preferisci cursor da pagination.next_cursor.
`cursor`	`str`	No	-	Cursore opaco da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.
`direction`	`Literal[incoming, outgoing, both]`	No	`incoming`	Direzione di traversata
`relationship_types`	`list[str]`	No	-	Filtra tipi di relazione (CALL, IMPORT, INHERITS_FROM, ecc.). Sovrascrive sempre il default derivato da graph_view quando fornito.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Vista grafo: determina sia i tipi di arco di traversata predefiniti sia le metriche utilizzate 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 solo come default di relationship_types quando relationship_types non è fornito. Corrisponde al parametro graph_view di dependency_search per coerenza tra gli strumenti.
`path_filter`	`str`	No	-	Limita la risoluzione del simbolo target tramite prefisso del percorso file; le relazioni del grafo restituite possono estendersi oltre quel percorso.
`language_filter`	`str`	No	-	Filtro linguaggio
`branch`	`str`	No	-	Sovrascrittura del branch
`per_hop_limit`	`int`	No	-	Relazioni massime per hop (1-300)
`include_metrics`	`bool`	No		Includere le metriche del grafico nei risultati, ciascuno arricchito con un blocco refactor_risk derivato ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk è "low" quando non è un punto di articolazione (nella vista selezionata), "medium" quando un punto di articolazione collega pochi bordi, "high" quando ne collega molti (soglia euristica, non validata empiricamente). Omesso per simbolo quando non esiste alcuna riga di metrica per quel simbolo/vista.
`metrics_detail`	`Literal[summary, full]`	No	`summary`	Quando include_metrics=true: summary (predefinito) restituisce segnali decisionali + refactor_risk; full restituisce il set di metriche curate più ampio
`include_edge_metadata`	`bool`	No		Includi metadati e pesi del bordo grezzo. Disabilitato per impostazione predefinita perché i metadati dell'estrattore possono essere di grandi dimensioni; la copertura dell'arricchimento viene segnalata quando abilitata.
`exclude_test_paths`	`bool`	No	`true`	Predefinito true: esclude test, dispositivo, fornitore e percorsi di esempio dai bordi del grafico restituiti. Imposta false per includerli.
`include_module_symbols`	`bool`	No		Per impostazione predefinita, false esclude i bordi del grafico quando from_name o to_name è il simbolo sintetico __module__. Imposta true per includere i bordi a livello di modulo.

Il più adatto per:

Chiamanti legacy già predisposti per la sua forma di risposta (graph, connection_summary)

Sconsigliato per:

Nuovi loop di agenti — preferisci dependency_search, che condivide lo stesso nucleo di attraversamento

get_task_contextStabile

Inizi a lavorare in un'area poco familiare? Descrivi il task (es. "add SSO support", "fix the billing webhook") e ricevi in un'unica chiamata un bundle limitato di file, codice, simboli e dipendenze rilevanti. I file seed contribuiscono con contenuto indicizzato diretto anche quando non definiscono simboli. Per altri risultati, prosegui con lo strumento di ricerca specializzato per quel livello.

Parametri:

task_descriptionObbligatorio

Tipo: str
Descrizione: Descrizione dell'attività per cui serve il contesto

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

limitOpzionale

Tipo: int
Predefinito: 15
Descrizione: Elementi di contesto massimi per layer

scopeOpzionale

Tipo: Literal[semantic, symbols, dependencies, all]
Predefinito: all
Descrizione: Quali layer di contesto includere

language_filterOpzionale

Tipo: str
Descrizione: Filtro linguaggio

path_filterOpzionale

Tipo: str
Descrizione: Filtra per prefisso del percorso file

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

include_related_contextOpzionale

Tipo: bool
Predefinito
Descrizione: Includi contesto correlato dai simboli adiacenti

seed_symbol_idsOpzionale

Tipo: list[str]
Descrizione: Seed espliciti di livello 1: ID di simboli che l'agente sa essere centrali per il task (es. simboli nei file aperti). Classificati prima dei seed derivati da keyword nei layer dependencies/related_context. Aggiuntivo — omettere per il comportamento odierno basato solo su keyword.

seed_file_pathsOpzionale

Tipo: list[str]
Descrizione: Seed espliciti di livello 1: percorsi di file indicizzati che l'agente ha aperto o appena modificato. Restituisce evidenze dirette limitate sul file e risolve fino a 5 simboli per file per il contesto di grafo, inclusi documentazione e configurazione privi di simboli. Additivo — ometti per un comportamento basato solo su keyword.

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`task_description`	`str`	Sì	-	Descrizione dell'attività per cui serve il contesto
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`limit`	`int`	No	`15`	Elementi di contesto massimi per layer
`scope`	`Literal[semantic, symbols, dependencies, all]`	No	`all`	Quali layer di contesto includere
`language_filter`	`str`	No	-	Filtro linguaggio
`path_filter`	`str`	No	-	Filtra per prefisso del percorso file
`branch`	`str`	No	-	Sovrascrittura del branch
`include_related_context`	`bool`	No		Includi contesto correlato dai simboli adiacenti
`seed_symbol_ids`	`list[str]`	No	-	Seed espliciti di livello 1: ID di simboli che l'agente sa essere centrali per il task (es. simboli nei file aperti). Classificati prima dei seed derivati da keyword nei layer dependencies/related_context. Aggiuntivo — omettere per il comportamento odierno basato solo su keyword.
`seed_file_paths`	`list[str]`	No	-	Seed espliciti di livello 1: percorsi di file indicizzati che l'agente ha aperto o appena modificato. Restituisce evidenze dirette limitate sul file e risolve fino a 5 simboli per file per il contesto di grafo, inclusi documentazione e configurazione privi di simboli. Additivo — ometti per un comportamento basato solo su keyword.

Il più adatto 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_fileStabile

Leggi un file dal repository indicizzato per percorso. Preferisci lo strumento Read locale per i file su disco — usa questo per lookup cross-repo o remoti quando il file non è nella tua working tree. Supporta un intervallo di righe opzionale; prosegui una risposta troncata per token da metadata.next_line_start.

Parametri:

file_pathObbligatorio

Tipo: str
Descrizione: Percorso del file relativo alla radice del repository

repositoryOpzionale

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. La risposta indica quale repository è stato usato.

line_startOpzionale

Tipo: int
Descrizione: Linea di inizio (1-indicizzata)

line_endOpzionale

Tipo: int
Descrizione: Riga finale (1-indicizzata, inclusa; deve essere uguale o successiva a line_start)

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

max_tokensOpzionale

Tipo: int
Predefinito: 5000
Descrizione: Token massimi da restituire

include_metadataOpzionale

Tipo: bool
Predefinito: true
Descrizione: Includi i metadati del file nella risposta

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`file_path`	`str`	Sì	-	Percorso del file relativo alla radice del repository
`repository`	`str`	No	-	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. La risposta indica quale repository è stato usato.
`line_start`	`int`	No	-	Linea di inizio (1-indicizzata)
`line_end`	`int`	No	-	Riga finale (1-indicizzata, inclusa; deve essere uguale o successiva a line_start)
`branch`	`str`	No	-	Sovrascrittura del branch
`max_tokens`	`int`	No	`5000`	Token massimi da restituire
`include_metadata`	`bool`	No	`true`	Includi i metadati del file nella risposta

Il più adatto 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_contextStabile

Elenca i repository che puoi cercare, oppure ottieni le informazioni di identità su uno di essi (namespace/branch, indexed_commit_sha / aggiornamento dell'indice). Chiama con action:"list" una volta per conoscere lo slug esatto di repo accettato dagli strumenti di ricerca. (Se la tua chiave ha un solo repository, gli strumenti di ricerca lo useranno di default — puoi saltare questo passaggio.) I conteggi di file/blob/archi a livello di namespace sono opzionali tramite include_statistics=true.

Parametri:

actionObbligatorio

Tipo: Literal[list, info]
Descrizione: Azione: elenca i repo disponibili o ottieni info su un repo

repositoryOpzionale

Tipo: str
Descrizione: Repository in formato owner/repo o owner/repo:branch (obbligatorio per info)

branchOpzionale

Tipo: str
Descrizione: Sovrascrittura del branch

patternOpzionale

Tipo: str
Descrizione: Filtra la lista dei repository per pattern

include_statisticsOpzionale

Tipo: bool
Predefinito
Descrizione: Opzionale: include i conteggi dei dati indicizzati a livello di namespace (file/blob/arco). Falso per impostazione predefinita — l'identità del repository non richiede questo aggregato più lento.

limitOpzionale

Tipo: int
Predefinito: 20
Descrizione: Risultati massimi restituiti in questa pagina

offsetOpzionale

Tipo: int
Descrizione: Offset di compatibilità deprecato. Preferisco cursor da pagination.next_cursor.

cursorOpzionale

Tipo: str
Descrizione: Opaco cursor da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`action`	`Literal[list, info]`	Sì	-	Azione: elenca i repo disponibili o ottieni info su un repo
`repository`	`str`	No	-	Repository in formato owner/repo o owner/repo:branch (obbligatorio per info)
`branch`	`str`	No	-	Sovrascrittura del branch
`pattern`	`str`	No	-	Filtra la lista dei repository per pattern
`include_statistics`	`bool`	No		Opzionale: include i conteggi dei dati indicizzati a livello di namespace (file/blob/arco). Falso per impostazione predefinita — l'identità del repository non richiede questo aggregato più lento.
`limit`	`int`	No	`20`	Risultati massimi restituiti in questa pagina
`offset`	`int`	No	-	Offset di compatibilità deprecato. Preferisco cursor da pagination.next_cursor.
`cursor`	`str`	No	-	Opaco cursor da pagination.next_cursor. Passalo invariato e mantieni invariati la query e i filtri.

Il più adatto 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_maguyvaStabile

Aiuto e feedback per Maguyva. Uso principale: ottenere indicazioni sugli strumenti, oppure inviare una segnalazione di bug / una richiesta di funzionalità conservate per i maintainer di Maguyva. Non includere mai segreti o dati personali sensibili nel feedback. L'operazione evaluate resta solo per retrocompatibilità — preferisci il calcolo locale o gli strumenti host per lavori di matematica/hash/stringhe.

Parametri:

operationObbligatorio

Tipo: Literal[guidance, report_bug, request_feature, evaluate]
Descrizione: Principale: guidance, report_bug, request_feature. Solo legacy/compatibilità: evaluate (motore di espressioni deterministico; non fa parte del flusso di lavoro principale dell'agente).

queryOpzionale

Tipo: str
Descrizione: Argomento della guida (es. tool_selection, semantic_search). Solo per evaluate legacy: stringa di espressione.

descriptionOpzionale

Tipo: str
Descrizione: Obbligatorio per report_bug e request_feature. Feedback Free-form per i maintainer di Maguyva. Non includere mai segreti o dati personali sensibili.

related_toolOpzionale

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

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	Sì	-	Principale: guidance, report_bug, request_feature. Solo legacy/compatibilità: evaluate (motore di espressioni deterministico; non fa parte del flusso di lavoro principale dell'agente).
`query`	`str`	No	-	Argomento della guida (es. tool_selection, semantic_search). Solo per evaluate legacy: stringa di espressione.
`description`	`str`	No	-	Obbligatorio per report_bug e request_feature. Feedback Free-form per i maintainer di Maguyva. Non includere mai segreti o dati personali sensibili.
`related_tool`	`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]`	No	-	Strumento opzionale Maguyva più strettamente correlato al feedback

Il più adatto per:

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

Sconsigliato per:

Calcoli matematici/hash/di stringhe — l'operazione evaluate resta solo per retrocompatibilità; preferisci il calcolo locale o gli strumenti host

Best practice#

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.
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.
Sfrutta i filtri linguistici: Usa language_filter per restringere i risultati e migliorare le prestazioni.
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.
La corrispondenza dei repository non distingue le maiuscole, ma non è fuzzy: repository_context fa corrispondere i nomi dei repository senza distinguere maiuscole e minuscole — non corregge i refusi. Controlla metadata.resolution_reason sull'azione info ("exact" contro "corrected") per vedere come è stato risolto un nome.
Combina gli strumenti: Usa più metodi API insieme per un'analisi completa.
Gestisci risultati numerosi: Usa limit e i controlli di paginazione specifici dello strumento (ad esempio line_start/line_end in get_file).
Usa ask_maguyva per la guida sugli strumenti: L'operazione evaluate di ask_maguyva (hash, base64, JSON, matematica) è solo legacy / retrocompatibilità. Chiama invece ask_maguyva con operation="guidance" e query="tool_selection" per ottenere la matrice di priorità degli strumenti locali e un prontuario completo strumento per strumento.
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 degli stessi simboli.

Caratteristiche di prestazione#

Operazione	Note sulle prestazioni
Ricerca semantica	Meno di un secondo, ma include una chiamata API di embedding dal vivo ogni volta (non memorizzata nella cache) — aspettati latenza aggiuntiva oltre alla query vettoriale
Ricerca testuale	Meno di un secondo per corrispondenze esatte/regex; la ricerca fuzzy dei contenuti pagina lato client, quindi gli offset profondi costano di più — restringi con path_filter/language_filter
Ricerca strutturale	Indicizzata tramite AST — il costo scala con il volume dei risultati, non con la dimensione del repository
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	Quasi istantaneo per un singolo file — pagina i file di grandi dimensioni con line_start/line_end o max_tokens invece di un unico recupero massiccio
Contesto del repository	La risoluzione del namespace è memorizzata nella cache solo per singola richiesta, non tra le chiamate — ogni invocazione dello strumento la risolve di nuovo
ask_maguyva (guidance / evaluate)	Quasi istantaneo — viene eseguito all'interno del Worker senza chiamate al database

Gestione degli errori#

Tutti i metodi dell'API restituiscono una busta strutturata:

status: Stringa — "success" oppure "error". I segnali di corrispondenza degradata o di aggiornamento si trovano in campi annidati come metadata.resolution_reason su repository_context o metadata.index_freshness.status.
tool: Nome dello strumento che ha generato la risposta
data: Payload del risultato in caso di successo (la struttura varia in base allo strumento)
error: Oggetto errore strutturato quando status è "error" — include type, message, suggestions e recovery_actions
metadata: Informazioni aggiuntive sull'operazione (instradamento, caching, aggiustamenti dei parametri)
pagination: Presente sulle risposte con elenchi — include has_more e next_cursor

Controlla sempre il campo status prima di elaborare i risultati — può essere solo "success" o "error". Per segnali di corrispondenza degradata o di aggiornamento, leggi invece il campo annidato: metadata.resolution_reason su repository_context, oppure metadata.index_freshness.status (known/partial/unknown/unavailable).

Come iniziare#

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

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