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

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.

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

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

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

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

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.

{
  "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.

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.

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

Pourquoi cette boucle fonctionne : Comment ça marche.

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

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

Échecs de configuration : Dépannage.

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.

• Démarrage rapide — clé, index, connexion, première réponse notée
• Guide d'installation — configuration MCP par client
• Référence API MCP — chaque outil, paramètre par paramètre
• Dépannage — Échecs de la clé API, du pont et du référentiel