Ricette

Ricette pratiche per il lavoro quotidiano con Maguyva MCP. Ogni ricetta indica gli strumenti e la sequenza da seguire, non tutti i parametri. Per i parametri degli strumenti, consulta «Riferimento API MCP». Per la prima configurazione, consulta «Avvio rapido».

I blocchi JSON sono gli input di MCP tools/call. Sostituisci owner/repo, il nome del branch e i nomi dei simboli con i valori del tuo repository.

La maggior parte delle domande richiede inizialmente una sola chiamata. Approfondisci solo quando la prima risposta è troppo generica o poco dettagliata.

• intelligent_search — inizia da qui per una domanda in linguaggio naturale 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.
• find_symbol: conosci già la funzione, la classe o il nome della variabile.
• dependency_search — raggio d'impatto: chiamanti, componenti dipendenti o impatto prima (e dopo) una modifica.
• get_task_context — zona sconosciuta; un insieme delimitato di file, simboli e dipendenze per la descrizione di un'attività.
• repository_context: elenca i repository accessibili o controlla come si risolve il nome di un repository.
• ask_maguyva con operation="guidance" — guida locale sulla scelta degli strumenti e sull'utilizzo di Maguyva (nessuna modifica al repository).

Integra Maguyva nel tuo client MCP e verifica la connessione ottenendo l'elenco effettivo dei repository.

1. Crea una chiave API in app.maguyva.ai (le chiavi iniziano con mgv_).
2. Connetti e indicizza almeno un repository GitHub che già conosci.
3. Collega il tuo client seguendo la sezione «Guida all'installazione» (plugin Claude Code oppure configurazione remota integrata per Cursor, VS Code, Devin Desktop, Zed e altri).
4. Chiedi al tuo agente "Quali repository ho collegato?", verificando così dall’inizio alla fine l’autenticazione e repository_context.
5. Fai una domanda reale su quel repository di cui puoi valutare la risposta. Dovresti vedere i percorsi dei file e i numeri di riga dall'albero indicizzato.

{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}

Bloccato su chiavi, bridge o repository mancanti? Risoluzione dei problemi.

Mappa i simboli e il raggio d'impatto prima di modificare il codice condiviso. Gli strumenti Maguyva non modificano i tuoi repository: forniscono le informazioni su cui basare la modifica che il tuo client applica localmente.

1. Se conosci il nome del simbolo, chiama find_symbol per approdare alle definizioni e agli usi.
2. Se hai solo una descrizione dell'attività ("aggiungi SSO", "correggi il webhook di fatturazione"), inizia con get_task_context o intelligent_search.
3. Prima di modificare un simbolo condiviso, chiama dependency_search con l'analisi dependents/impact (componenti dipendenti e impatto della modifica), oppure passa i percorsi modificati per un'analisi dell'impatto in stile PR, così da vedere il raggio d'impatto.
4. Apri i file citati (lettura locale per i file su disco; get_file per percorsi remoti o in altri repository) e verifica il piano rispetto al codice reale.
5. Dopo la modifica, ricontrolla gli stessi simboli con dependency_search usando verify_after_edit=true e targets o changed_paths. Lo strumento legge il grafo indicizzato, non le modifiche locali non ancora registrate in un commit: controlla indexed_commit_sha e l'aggiornamento dell'indice prima di considerarlo una prova relativa alla nuova revisione, ed esegui i test locali.

{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}

Parametri completi: Riferimento API MCP.

Un ciclo di lavoro tipico dell'agente: esplora → individua i simboli precisi → modifica sulla base delle evidenze.

1. Inizia con intelligent_search e una query in linguaggio semplice ("come funziona la scadenza della sessione", "dov'è la logica dei nuovi tentativi").
2. Restringi la ricerca con filtri per linguaggio o percorso quando il primo gruppo di risultati contiene troppo rumore. language_filter esclude il grafo da auto/hybrid; una query auto indirizzata solo al grafo ripiega sulla ricerca semantica e testuale. La modalità graph esplicita con language_filter viene rifiutata. Consulta routing_decision.modalities_used per vedere il piano di ricerca selezionato; warnings è presente solo quando il server ha emesso un avviso.
3. Approfondisci i risultati promettenti con find_symbol o dependency_search invece di porre nuovamente la stessa domanda vaga.
4. Utilizza get_file solo quando è necessario un percorso indicizzato specifico che non si trova sul disco.
5. Modifica nei normali strumenti client. Maguyva serve per la scoperta e la verifica, non per la scrittura.

{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}

Perché questo ciclo funziona: Come funziona.

Quando gli strumenti non restituiscono nulla di utile, verifica la risoluzione del repository e l'indicizzazione prima di continuare a riscrivere la query all'infinito.

1. Conferma che il repository sia connesso e che abbia terminato l'indicizzazione in app.maguyva.ai.
2. Controlla la stringa del repository: "owner/repo" usa il branch predefinito; "owner/repo:branch" specifica un branch preciso. La corrispondenza non distingue maiuscole e minuscole, ma non è approssimativa: gli errori di battitura non vengono corretti automaticamente.
3. Chiama repository_context con action="info" e controlla i metadati della risoluzione (ad esempio metadata.resolution_reason).
4. Ometti repository solo quando il client MCP fornisce un repository predefinito per la richiesta o la chiave può accedere esattamente a un repository; altrimenti passalo esplicitamente.
5. Riprova con una query più specifica, un nome di simbolo noto tramite find_symbol o un filtro per linguaggio o percorso. Se la connessione stessa non funziona, consulta la sezione «Risoluzione dei problemi».

{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}

Errori di installazione: Risoluzione dei problemi.

Scegli come target il repository indicizzato corretto quando una chiave può vederne più di uno.

1. Chiama repository_context con action="list" una volta per scoprire gli slug esatti che la tua chiave può cercare.
2. Passa repository esplicitamente sugli strumenti di ricerca e simboli quando hai bisogno di un repository non predefinito (ad esempio "owner/other-repo" o "owner/other-repo:develop").
3. Mantieni una domanda = un repository a meno che non confronti intenzionalmente tra repository in chiamate separate.
4. Utilizza get_file quando il file si trova in un repository indicizzato che non è l'albero di lavoro corrente.
5. Ricorda: gli strumenti non riscrivono mai su GitHub: il contesto multi-repo è solo per la lettura e la pianificazione.

Dettagli sul formato del repository: Riferimento API MCP.

• Avvio rapido — chiave, indice, connessione, prima risposta verificata
• Guida all'installazione — configurazione MCP per ciascun client
• Riferimento API MCP — ogni strumento, parametro per parametro
• Risoluzione dei problemi — Errori di chiave API, bridge e repository