Passer au contenu

Recettes

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 le Référence API MCP. Pour une première configuration, utilisez le Quickstart.

Choisissez le bon outil#

La plupart des questions commencent par un seul appel. N'escaladez que lorsque la première réponse est trop large ou trop fine.

  • intelligent_search — commencez ici pour toute question sur la base de code en langage naturel ; il traverse la recherche sémantique, de symboles, structurelle et de dépendance.
  • find_symbol — vous connaissez déjà le nom de la fonction, de la classe ou de la variable.
  • dependency_search — rayon d'impact : appelants, personnes à charge 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).

Installer et vérifier un client#

Obtenez Maguyva dans votre client MCP et confirmez la connexion avec une véritable liste de référentiels.

  1. Créez une clé API dans 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. Câblez votre client à l'aide du Guide d'installation (plug-in Claude Code ou configuration distante native pour Cursor, VS Code, Windsurf, Zed et autres).
  4. Demandez à votre agent "Quels référentiels ai-je connectés ?" — qui exerce 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.

Coincé sur des clés, des ponts ou des dépôts manquants ? Troubleshooting.

Demandez avant de modifier#

Cartographiez les symboles et rayon d'impact avant de modifier le code partagé. Les outils Maguyva ne modifient pas vos référentiels : ils informent 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 des dépendances/impact (ou transmettez les chemins modifiés pour un impact de style 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 (y compris la vérification post-édition lorsque votre client prend en charge les indicateurs de vérification) afin que les appelants soient toujours résolus comme prévu.

Paramètres complets : Référence API MCP.

Rechercher, puis modifier#

Une boucle d'agent par défaut : explorer → symboles d'épingle → modifier avec des 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 langue ou de chemin lorsque la première fenêtre est bruyante.
  3. Faites la promotion des hits prometteurs vers 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.

Pourquoi cette boucle fonctionne : Comment ça marche.

Résultats vides ou minces#

Lorsque les outils ne renvoient rien d'utile, corrigez la résolution et l'indexation avant de réécrire définitivement la requête.

  1. Confirmez que le référentiel est connecté et que l'indexation est terminée dans 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 demande par défaut 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 langue/chemin. Si la connexion elle-même est interrompue, utilisez Troubleshooting.

Échecs de configuration : 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.

Nouveau sur Maguyva ? Marchez d'abord sur Quickstart, puis revenez ici pour les boucles du deuxième jour.

Prochaines étapes#