Vai al contenuto

Ricette

Ricette pratiche per il lavoro quotidiano Maguyva MCP. Ogni ricetta nomina gli strumenti e la sequenza, non un riferimento completo ai parametri. Per i parametri dello strumento, utilizzare Riferimento API MCP. Per la prima configurazione, utilizzare Quickstart.

Scegli lo strumento giusto#

La maggior parte delle domande iniziano con una chiamata. Incrementare solo quando la prima risposta è troppo ampia o troppo sottile.

  • intelligent_search: inizia da qui per qualsiasi domanda sulla base di codice in linguaggio naturale; percorre la ricerca semantica, di simboli, strutturale e di dipendenza.
  • find_symbol: conosci già la funzione, la classe o il nome della variabile.
  • dependency_search: raggio di esplosione: chiamanti, persone a carico 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 selezione dell'utensile e sull'utilizzo di Maguyva (nessuna mutazione del repository).

Installa e verifica un client#

Ottieni Maguyva nel tuo client MCP e conferma la connessione con un elenco di repository reali.

  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 utilizzando Guida all'installazione (plug-in Claude Code o configurazione remota nativa per Cursor, VS Code, Windsurf, 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.

Bloccato su chiavi, bridge o repository mancanti? Troubleshooting.

Chiedi prima di modificare#

Simboli della mappa e raggio di esplosione prima di modificare il codice condiviso. Gli strumenti Maguyva non modificano i tuoi repository: informano 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 delle dipendenze/dell'impatto (o passa i percorsi modificati per l'impatto in stile PR) in modo da vedere il raggio dell'esplosione.
  4. Aprire i file citati (lettura locale per file su disco; get_file per percorsi remoti/tra repository) e confermare il piano rispetto al codice reale.
  5. Dopo la modifica, ricontrolla gli stessi simboli con dependency_search (inclusa la verifica post-modifica quando il tuo client supporta i flag di verifica) in modo che i chiamanti risolvano ancora come previsto.

Parametri completi: Riferimento API MCP.

Cerca e poi cambia#

Un ciclo agente predefinito: esplora → simboli pin → modifica con prove.

  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 con i filtri della lingua o del percorso quando la prima finestra è rumorosa.
  3. Promuovi risultati promettenti a 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.

Perché questo ciclo funziona: Come funziona.

Risultati vuoti o sottili#

Quando gli strumenti non restituiscono nulla di utile, correggi la risoluzione e l'indicizzazione prima di riscrivere la query per sempre.

  1. Confermare che il repository sia connesso e che abbia terminato l'indicizzazione in app.maguyva.ai.
  2. Controlla la stringa del repository: "owner/repo" utilizza il ramo predefinito; "owner/repo:branch" blocca un ramo. La corrispondenza non fa distinzione tra maiuscole e minuscole, non è confusa: 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. Omettere repository solo quando il client MCP fornisce una richiesta predefinita o la chiave può accedere esattamente a un repository; altrimenti passalo esplicitamente.
  5. Riprovare con una query più specifica, un nome di simbolo noto tramite find_symbol o un filtro lingua/percorso. Se la connessione stessa viene interrotta, utilizzare Troubleshooting.

Errori di installazione: Troubleshooting.

Lavora su più repository#

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.

Nuovo su Maguyva? Cammina prima su Quickstart, poi torna qui per i loop del secondo giorno.

Prossimi passi#