Référence de l'API MCP

Découvrez les 11 outils MCP de Maguyva, leurs paramètres et leurs usages. Consultez la réponse tools/list de votre client connecté pour connaître les arguments disponibles.

Les outils sont répartis en 4 catégories :

• Outils de recherche principaux - Fonctionnalités de recherche avancées dans votre base de code
• Outils structurels et de graphes - Requêtes AST, recherche de symboles et analyse des dépendances
• Outils d'analyse de code - Analyse approfondie du code et cartographie des relations
• Outils système et utilitaires - Contexte du dépôt, aide sur les outils et retours d’expérience

Pour les outils acceptant un dépôt, utilisez ce format d'identifiant de dépôt : "owner/repo:branch". Sans précision, la branche est main.

Omettez repository lorsque votre client MCP fournit une valeur par défaut pour la requête ou lorsque la clé permet d’accéder à un seul dépôt ; sinon, transmettez-le explicitement. Utilisez repository_context(action="info", repository="owner/repo") pour vérifier la manière dont un dépôt est résolu.

Utilisez ces formats pour préciser un dépôt :

• Avec branche: "owner/repo:branch" - ex. : "owner/repository:develop"
• Branche par défaut: "owner/repo" - utilise la branche main quand aucune branche n'est précisée "owner/repository"
• Valeur par défaut de la requête ou du dépôt unique: Omettez le dépôt lorsque le client MCP fournit une valeur par défaut pour la requête ou lorsque la clé permet d’accéder à un seul dépôt ; sinon, transmettez-le explicitement

Exemples de prompts:

Interroger un dépôt précis :     "Cherche dans owner/my-repo le middleware d'authentification"
Lister les dépôts accessibles :  "À quels dépôts cette clé Maguyva peut-elle accéder ?"
Surcharger pour une requête :    "Cherche dans owner/other-repo:develop des patterns d'auth"

Utilisez language_filter dans les modes de recherche compatibles. Pour text_pattern_search, choisissez search_scope="content" ; pour get_task_context, utilisez scope="semantic" sans points de départ ni contexte associé.

• language_filter="python" - Filtrer sur les fichiers Python uniquement
• language_filter="typescript" - Filtrer sur les fichiers TypeScript uniquement
• Sensible à la casse: Utilisez les noms de langages en minuscules
• Par défaut: Chaîne vide (aucun filtrage) - renvoie les résultats de tous les langages
• Couverture supportée: Les filtres de langage fonctionnent sur l'ensemble des 285+ langages et technologies textuelles supportés. Voir compatibilité pour la liste complète.

"Trouve le middleware d'authentification uniquement dans les fichiers Python"
"Cherche les connexions base de données en TypeScript"

Référence de l'API générée à partir du code source le 21 octobre 2026.

1. Utiliser les remplacements explicites à bon escient: Omettez le dépôt lorsque votre client MCP fournit une valeur par défaut pour la requête ou lorsque la clé permet d’accéder à un seul dépôt ; sinon, transmettez-le explicitement.
2. Choisir le bon mode de recherche: Utilisez intelligent_search avec mode="auto" pour la plupart des cas. Précisez un mode quand vous savez exactement ce dont vous avez besoin.
3. Exploiter les filtres de langage: Utilisez language_filter pour restreindre les résultats et améliorer les performances.
4. Boost GraphRAG: Le boost d'importance GraphRAG est désactivé par défaut pour la recherche sémantique (boost_by_importance=false), afin de garder le classement sûr pour les agents. Passez boost_by_importance=true pour activer le reclassement basé sur la centralité pour les visites d'architecture.
5. La correspondance de dépôt ignore la casse, mais n'est pas floue: repository_context fait correspondre les noms de dépôt sans tenir compte de la casse — il ne corrige pas les fautes de frappe. Lorsque l'identité servie diffère de celle demandée, metadata.resolution_reason indique "defaulted" (aucune branche n'a été demandée) ou "fallback" (la branche ou le dépôt demandé n'est pas disponible). Le champ est omis lorsque la demande correspond exactement.
6. Combiner les outils: Utilisez plusieurs méthodes d'API ensemble pour une analyse complète.
7. Gérer les résultats volumineux: Utilisez limit et les contrôles de pagination spécifiques à l'outil (par exemple line_start/line_end dans get_file).
8. Utiliser ask_maguyva pour l'orientation sur les outils: Appelez ask_maguyva avec operation="guidance" et query="tool_selection" pour des conseils et exemples de sélection d’outils. Utilisez vos outils locaux pour les calculs et les transformations de chaînes.
9. Vérifier l'impact avant et après l'édition: Avant de modifier un symbole partagé, appelez dependency_search avec analysis_type="impact" (ou passez changed_paths pour l'impact d'une PR/diff) afin de voir son rayon d'impact. Après l'édition, définissez verify_after_edit=true avec targets et/ou changed_paths pour une revérification compacte des mêmes symboles. Cette vérification porte sur le graphe indexé : elle ne lit pas les modifications locales non commitées et ne remplace pas les tests locaux. Vérifiez indexed_commit_sha et la fraîcheur de l’index avant de considérer les résultats comme une preuve pour une nouvelle révision.

Les réponses des outils contiennent des champs de statut communs et des champs de contenu propres à l’outil au premier niveau. Les recherches renvoient results ; get_file renvoie content. Les champs communs comprennent :

• status: Chaîne — "success" ou "error". Les signaux de correspondance dégradée et de fraîcheur ont leurs propres champs : metadata.resolution_reason sous metadata, et index_freshness.status au premier niveau de l'action info de repository_context.
• timing_ms: Durée d’exécution de l’outil en millisecondes
• applied_filters: Paramètres de requête effectivement appliqués et enregistrés pour l’opération
• error: Message d’erreur sous forme de chaîne lorsque status vaut "error" ; il peut inclure des conseils de résolution.
• metadata: Informations complémentaires sur l'opération (routage, mise en cache, ajustements de paramètres)
• pagination: Présent dans les réponses de collections paginées par curseur — inclut has_more et next_cursor. Les fenêtres de recherche classée fournissent un nombre limité de résultats top-K, pas des collections exhaustives paginées.

Vérifiez le champ status avant de traiter la charge utile d'un outil — ses valeurs sont "success" ou "error". Gérez aussi les erreurs de transport MCP/JSON-RPC et de validation de requête, qui peuvent survenir avant même qu'une charge utile ne soit produite. Pour les signaux de correspondance dégradée ou de fraîcheur, lisez plutôt le champ dédié : metadata.resolution_reason sous metadata, ou index_freshness.status au premier niveau de l'action info de repository_context (known/partial/unknown/unavailable).

1. Configurer le client MCP: Pointez votre client MCP vers le point de terminaison du serveur Maguyva
2. Confirmer l'accès au dépôt: Utilisez repository_context avec list ou info pour examiner les dépôts accessibles à la clé API
3. Commencer à rechercher: Commencez avec intelligent_search et explorez les outils spécialisés au besoin
4. Combiner les outils: Utilisez plusieurs outils ensemble pour une analyse de code complète

Pour des instructions d'intégration détaillées, voir le guide d'installation.