# Ricette

Canonical source: https://maguyva.ai/it/docs/cookbook

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

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](https://maguyva.ai/docs/mcp-api)». Per la prima configurazione, consulta «[Avvio rapido](https://maguyva.ai/docs/quickstart)».

### Scegli lo strumento giusto

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).

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.

### Installa e verifica un client

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](https://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](https://maguyva.ai/docs/installation)» (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.

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

Bloccato su chiavi, bridge o repository mancanti? [Risoluzione dei problemi](https://maguyva.ai/docs/troubleshooting).

### Chiedi prima di modificare

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.

```json
{
  "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](https://maguyva.ai/docs/mcp-api).

### Cerca e poi cambia

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.

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

Perché questo ciclo funziona: [Come funziona](https://maguyva.ai/docs/how-it-works).

### Risultati vuoti o poco dettagliati

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](https://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](https://maguyva.ai/docs/troubleshooting)».

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

Errori di installazione: [Risoluzione dei problemi](https://maguyva.ai/docs/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](https://maguyva.ai/docs/mcp-api).

Prima configurazione? Parti da [Avvio rapido](https://maguyva.ai/docs/quickstart), poi usa queste ricette per le attività quotidiane.