# Recettes

Canonical source: https://maguyva.ai/fr/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).

Recettes pratiques pour le travail quotidien Maguyva MCP. Chaque recette nomme les outils et la séquence – et non une référence complète des paramètres. Pour les paramètres d'outil, utilisez la [Référence API MCP](https://maguyva.ai/docs/mcp-api). Pour une première configuration, utilisez le [Démarrage rapide](https://maguyva.ai/docs/quickstart).

### Choisissez le bon outil

La plupart des questions commencent par un seul appel. N'approfondissez la recherche que si la première réponse est trop générale ou manque d'informations.

- `intelligent_search` — commencez ici pour une question en langage naturel sur la base de code. Par défaut, auto/balanced oriente les questions de définition dont l’intention est identifiée avec confiance vers la recherche structurelle, les questions de références ou d’impact vers le graphe et les recherches de correspondance exacte vers le texte. Les autres questions utilisent le sens sémantique et le texte indexé. Utilisez mode=hybrid ou auto avec quality=thorough pour solliciter les quatre modalités de recherche. Un mode explicite prend le pas sur quality.
- `find_symbol` — vous connaissez déjà le nom de la fonction, de la classe ou de la variable.
- `dependency_search` — rayon d'impact : code appelant, code dépendant ou impact avant (et après) une modification.
- `get_task_context` — zone inconnue ; un ensemble limité de fichiers, de symboles et de dépendances pour une description de tâche.
- `repository_context` – répertorie les référentiels accessibles ou inspecte la façon dont un nom de référentiel est résolu.
- `ask_maguyva` avec `operation="guidance"` — aide locale sur la sélection des outils et l'utilisation de Maguyva (pas de mutation de repo).

Les blocs JSON sont des entrées pour MCP tools/call. Remplacez owner/repo ainsi que les noms de branche et de symbole par les valeurs de votre dépôt.

### Installer et vérifier un client

Intégrez Maguyva à votre client MCP et confirmez la connexion en obtenant une liste réelle de dépôts.

1. Créez une clé API dans [app.maguyva.ai](https://app.maguyva.ai) (les clés commencent par `mgv_`).
2. Connectez et indexez au moins un référentiel GitHub que vous comprenez déjà.
3. Configurez votre client à l'aide du [Guide d'installation](https://maguyva.ai/docs/installation) (plug-in Claude Code ou configuration distante native pour Cursor, VS Code, Devin Desktop, Zed et autres).
4. Demandez à votre agent "Quels référentiels ai-je connectés ?" — cela teste l'authentification et `repository_context` de bout en bout.
5. Posez une vraie question sur ce dépôt dont vous pouvez noter la réponse. Vous devriez voir les chemins de fichiers et les numéros de ligne de l’arborescence indexée.

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

Coincé sur des clés, des ponts ou des dépôts manquants ? [Dépannage](https://maguyva.ai/docs/troubleshooting).

### Demandez avant de modifier

Cartographiez les symboles et le rayon d'impact avant de modifier le code partagé. Les outils Maguyva ne modifient pas vos dépôts : ils éclairent la modification que votre client applique localement.

1. Si vous connaissez le nom du symbole, appelez `find_symbol` pour accéder aux définitions et aux utilisations.
2. Si vous disposez uniquement d'une description de tâche (« ajouter SSO », « corriger le webhook de facturation »), commencez par `get_task_context` ou `intelligent_search`.
3. Avant de modifier un symbole partagé, appelez `dependency_search` avec une analyse dependents/impact du code qui dépend de ce symbole ou de son impact (ou transmettez les chemins modifiés pour une analyse d’impact de type PR) afin de voir le rayon d'impact.
4. Ouvrez les fichiers cités (lecture locale pour les fichiers sur le disque ; `get_file` pour les chemins distants/cross-repo) et confirmez le plan par rapport au code réel.
5. Après la modification, revérifiez les mêmes symboles avec `dependency_search`, en utilisant verify_after_edit=true et targets ou changed_paths. Cet appel lit le graphe indexé, pas les modifications locales non commitées : vérifiez indexed_commit_sha et la fraîcheur de l’index avant d’y voir une preuve pour la nouvelle révision, et exécutez les tests locaux.

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

Paramètres complets : [Référence API MCP](https://maguyva.ai/docs/mcp-api).

### Rechercher, puis modifier

Une boucle d'agent par défaut : explorer → épingler les symboles → modifier sur la base de preuves.

1. Commencez par `intelligent_search` et une requête en langage clair (« comment fonctionne l'expiration de session », « où se trouve la logique de nouvelle tentative »).
2. Affinez avec des filtres de langage ou de chemin si les premiers résultats sont trop bruités. language_filter exclut le graphe d’auto/hybrid ; une requête auto orientée uniquement vers le graphe se rabat sur la recherche sémantique et textuelle. Le mode graphe explicite est refusé avec language_filter. Consultez routing_decision.modalities_used pour voir le plan de recherche sélectionné ; warnings n’apparaît que si le serveur a émis un avertissement.
3. Approfondissez les résultats prometteurs avec `find_symbol` ou `dependency_search` au lieu de poser à nouveau la même question vague.
4. Utilisez `get_file` uniquement lorsque vous avez besoin d'un chemin indexé spécifique qui ne se trouve pas sur le disque.
5. Modifiez dans vos outils clients habituels. Maguyva est destiné à la découverte et à la vérification, pas à l'écriture.

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

Pourquoi cette boucle fonctionne : [Comment ça marche](https://maguyva.ai/docs/how-it-works).

### Résultats vides ou insuffisants

Lorsque les outils ne renvoient rien d'utile, corrigez la résolution du dépôt et l'indexation plutôt que de reformuler la requête sans fin.

1. Confirmez que le référentiel est connecté et que l'indexation est terminée dans [app.maguyva.ai](https://app.maguyva.ai).
2. Vérifiez la chaîne du référentiel : `"owner/repo"` utilise la branche par défaut ; `"owner/repo:branch"` épingle une branche. La correspondance n'est pas sensible à la casse et n'est pas floue : les fautes de frappe ne se corrigent pas automatiquement.
3. Appelez `repository_context` avec `action="info"` et inspectez les métadonnées de résolution (par exemple `metadata.resolution_reason`).
4. Omettez `repository` uniquement lorsque votre client MCP fournit une valeur par défaut pour la requête ou que la clé peut accéder à exactement un référentiel ; sinon, transmettez-le explicitement.
5. Réessayez avec une requête plus spécifique, un nom de symbole connu via `find_symbol` ou un filtre de langage/chemin. Si la connexion elle-même est interrompue, utilisez [Dépannage](https://maguyva.ai/docs/troubleshooting).

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

Échecs de configuration : [Dépannage](https://maguyva.ai/docs/troubleshooting).

### Travailler sur plusieurs référentiels

Ciblez le bon référentiel indexé lorsqu'une clé peut en voir plusieurs.

1. Appelez `repository_context` avec `action="list"` une fois pour connaître les slugs exacts que votre clé peut rechercher.
2. Transmettez `repository` explicitement sur les outils de recherche et de symboles lorsque vous avez besoin d'un référentiel autre que celui par défaut (par exemple `"owner/other-repo"` ou `"owner/other-repo:develop"`).
3. Gardez une question = un référentiel, sauf si vous comparez intentionnellement les dépôts lors d'appels séparés.
4. Utilisez `get_file` lorsque le fichier réside dans un référentiel indexé qui n'est pas votre arborescence de travail actuelle.
5. N'oubliez pas : les outils ne réécrivent jamais dans GitHub – le contexte multi-dépôt est uniquement destiné à la lecture et à la planification.

Détails du format du référentiel : [Référence API MCP](https://maguyva.ai/docs/mcp-api).

Première configuration ? Commencez par [Démarrage rapide](https://maguyva.ai/docs/quickstart), puis utilisez ces recettes pour vos tâches quotidiennes.