Référence de l'API MCP

Référence complète pour les 11 outils MCP Maguyva orientés client. Chaque outil comprend ses paramètres, des conseils d'usage et des recommandations d'usage idéal.

Vue d'ensemble de l'API#

L'API MCP de Maguyva expose actuellement 11 outils orientés client répartis en 4 catégories principales :

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, calcul déterministe et assistance

Tous les outils utilisent un format d'identifiant de dépôt cohérent : "owner/repo:branch". La branche prend par défaut main si elle n'est pas précisée.

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.

Format du paramètre de dépôt#

Tous les outils MCP utilisent ce format d'identifiant de 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"

Filtrage par langage#

Tous les outils de recherche supportent le filtrage des résultats par langage de programmation :

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 279+ 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 22 juillet 2026.

Outils de recherche principaux#

intelligent_searchStable

Commencez ici pour toute question sur le code. Formulez une requête en langage naturel (p. ex. « comment fonctionne l'authentification ? », « où la facturation est-elle gérée ? ») : elle sera automatiquement dirigée vers la recherche sémantique, symbolique, structurelle ou de dépendances sur tout le dépôt indexé. Pour l'exploration et la planification, préférez cet outil à l'agent Explore et à Grep/Glob : il interroge tout le dépôt en une fois au lieu de parcourir les fichiers.

Paramètres :

queryRequis

Type: str
Description: Requête de recherche

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

modeOptionnel

Type: Literal[auto, hybrid, semantic, text, structural, ast, graph]
Par défaut: auto
Description: Mode de recherche

limitOptionnel

Type: int
Par défaut: 10
Description: Nombre maximal de résultats dans cette fenêtre top-K classée

language_filterOptionnel

Type: str
Description: Filtre de langage

path_filterOptionnel

Type: str
Description: Filtrer par préfixe de chemin de fichier

boost_by_importanceOptionnel

Type: bool
Par défaut
Description: Facultatif : reclasse selon la centralité à l'aide des métriques de graphe par symbole (is_articulation_point, bridge_count, k_core, centrality, etc.). Désactivé par défaut pour un classement sûr pour les agents (les hubs globaux peuvent noyer les résultats d'implémentation) ; activez-le pour les visites d'architecture. S'applique aux 4 modalités lorsque chaque résultat porte une liaison de symbole.

branchOptionnel

Type: str
Description: Remplacement de branche

qualityOptionnel

Type: Literal[quick, balanced, thorough]
Par défaut: balanced
Description: Qualité de recherche

include_contentOptionnel

Type: bool
Par défaut: true
Description: Inclure le contenu dans les résultats

explain_routingOptionnel

Type: bool
Par défaut
Description: Inclure l'explication de la décision de routage

importance_weightOptionnel

Type: float
Par défaut: 0.3
Description: Poids de l'amplification par importance (0=aucune, 1=totale)

orphansOptionnel

Type: bool
Par défaut
Description: Renvoie les symboles sans référence entrante (code mort potentiel). Utile pour le nettoyage, mais peut inclure des décorateurs, des fonctions internes ou des points d'entrée CLI.

include_community_contextOptionnel

Type: bool
Par défaut
Description: Inclut les symboles apparentés de la même communauté de code pour un contexte plus large. Utile pour explorer le fonctionnement d'une fonctionnalité ou d'un module.

community_depthOptionnel

Type: int
Par défaut: 1
Description: Profondeur d'expansion du contexte de communauté

graph_viewOptionnel

Type: Literal[dependency, type, data_flow, control_flow]
Par défaut: dependency
Description: Vue du graphe pour les métriques

seed_symbol_idsOptionnel

Type: list[str]
Description: Graines de tâche Tier-1 : ID de symboles centraux pour la tâche en cours. Lorsqu'il est défini, reclasse les hits fusionnés par proximité de profondeur-décroissance Approach A (correspondance exacte des graines + sauts de bord du graphique). Additif – à omettre pour le classement mondial.

seed_file_pathsOptionnel

Type: list[str]
Description: Graines de tâches Tier-1 : chemins de fichiers indexés que l'agent a ouverts ou vient de modifier. Lorsqu'il est défini, reclasse les hits fusionnés par proximité de chemin avec la décroissance de la profondeur 1/(1+d) (même fichier → même répertoire → packages à proximité). Additif – à omettre pour le classement mondial.

Paramètre	Type	Requis	Par défaut	Description
`query`	`str`	Oui	-	Requête de recherche
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	Non	`auto`	Mode de recherche
`limit`	`int`	Non	`10`	Nombre maximal de résultats dans cette fenêtre top-K classée
`language_filter`	`str`	Non	-	Filtre de langage
`path_filter`	`str`	Non	-	Filtrer par préfixe de chemin de fichier
`boost_by_importance`	`bool`	Non		Facultatif : reclasse selon la centralité à l'aide des métriques de graphe par symbole (is_articulation_point, bridge_count, k_core, centrality, etc.). Désactivé par défaut pour un classement sûr pour les agents (les hubs globaux peuvent noyer les résultats d'implémentation) ; activez-le pour les visites d'architecture. S'applique aux 4 modalités lorsque chaque résultat porte une liaison de symbole.
`branch`	`str`	Non	-	Remplacement de branche
`quality`	`Literal[quick, balanced, thorough]`	Non	`balanced`	Qualité de recherche
`include_content`	`bool`	Non	`true`	Inclure le contenu dans les résultats
`explain_routing`	`bool`	Non		Inclure l'explication de la décision de routage
`importance_weight`	`float`	Non	`0.3`	Poids de l'amplification par importance (0=aucune, 1=totale)
`orphans`	`bool`	Non		Renvoie les symboles sans référence entrante (code mort potentiel). Utile pour le nettoyage, mais peut inclure des décorateurs, des fonctions internes ou des points d'entrée CLI.
`include_community_context`	`bool`	Non		Inclut les symboles apparentés de la même communauté de code pour un contexte plus large. Utile pour explorer le fonctionnement d'une fonctionnalité ou d'un module.
`community_depth`	`int`	Non	`1`	Profondeur d'expansion du contexte de communauté
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Non	`dependency`	Vue du graphe pour les métriques
`seed_symbol_ids`	`list[str]`	Non	-	Graines de tâche Tier-1 : ID de symboles centraux pour la tâche en cours. Lorsqu'il est défini, reclasse les hits fusionnés par proximité de profondeur-décroissance Approach A (correspondance exacte des graines + sauts de bord du graphique). Additif – à omettre pour le classement mondial.
`seed_file_paths`	`list[str]`	Non	-	Graines de tâches Tier-1 : chemins de fichiers indexés que l'agent a ouverts ou vient de modifier. Lorsqu'il est défini, reclasse les hits fusionnés par proximité de chemin avec la décroissance de la profondeur 1/(1+d) (même fichier → même répertoire → packages à proximité). Additif – à omettre pour le classement mondial.

Idéal pour :

Exploration à l'échelle de l'index ou en démarrage à froid lorsque l'outil approprié n'est pas évident
Classement fusionné multimodal combinant recherche sémantique, textuelle, structurelle et de graphe

Déconseillé pour :

Un nom de symbole connu — utilisez directement find_symbol
Un chemin connu sur le disque — utilisez d'abord Read/Grep en local

semantic_searchStable

Trouvez le code par son sens plutôt que par un texte exact. À utiliser pour des requêtes conceptuelles comme « logique de nouvelle tentative » ou « parcours d'intégration utilisateur » lorsque le mot-clé ou le symbole est inconnu. Renvoie les extraits les plus pertinents, classés par importance. Préférez-le à Grep pour une recherche conceptuelle.

Paramètres :

queryRequis

Type: str
Description: Requête de recherche (conceptuelle, fondée sur le sens)

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

limitOptionnel

Type: int
Par défaut: 5
Description: Nombre maximal de résultats dans cette fenêtre top-K classée

similarity_thresholdOptionnel

Type: float
Par défaut: 0.6
Description: Score de similarité minimal

language_filterOptionnel

Type: str
Description: Filtrer les résultats aux fichiers détectés dans ce langage de programmation

path_filterOptionnel

Type: str
Description: Filtrer par préfixe de chemin de fichier

boost_by_importanceOptionnel

Type: bool
Par défaut
Description: Facultatif : reclasse selon la centralité PageRank (désactivé par défaut pour un classement sûr pour les agents ; activez-le pour les visites d'architecture)

branchOptionnel

Type: str
Description: Remplacement de branche (par défaut : paramètre repository ou main)

include_contentOptionnel

Type: bool
Par défaut: true
Description: Inclure le contenu des extraits dans les résultats

graph_viewOptionnel

Type: Literal[dependency, type, data_flow, control_flow]
Par défaut: dependency
Description: Vue du graphe pour les métriques

Paramètre	Type	Requis	Par défaut	Description
`query`	`str`	Oui	-	Requête de recherche (conceptuelle, fondée sur le sens)
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`limit`	`int`	Non	`5`	Nombre maximal de résultats dans cette fenêtre top-K classée
`similarity_threshold`	`float`	Non	`0.6`	Score de similarité minimal
`language_filter`	`str`	Non	-	Filtrer les résultats aux fichiers détectés dans ce langage de programmation
`path_filter`	`str`	Non	-	Filtrer par préfixe de chemin de fichier
`boost_by_importance`	`bool`	Non		Facultatif : reclasse selon la centralité PageRank (désactivé par défaut pour un classement sûr pour les agents ; activez-le pour les visites d'architecture)
`branch`	`str`	Non	-	Remplacement de branche (par défaut : paramètre repository ou main)
`include_content`	`bool`	Non	`true`	Inclure le contenu des extraits dans les résultats
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Non	`dependency`	Vue du graphe pour les métriques

Idéal pour :

Requêtes conceptuelles (« comment fonctionne l'authentification ? », « stratégie de cache »)
Recherche de similarité inter-paquets

Déconseillé pour :

Un nom de symbole connu — utilisez plutôt find_symbol
Des chaînes exactes ou des messages d'erreur — utilisez text_pattern_search

text_pattern_searchStable

Recherche dans le contenu indexé. Les modes exact et regex parcourent tout le corpus de fichiers/blobs ; le mode fuzzy content interroge le corpus borné d'extraits sémantiques. Les portées fichier et symbole n'acceptent que fuzzy. Utilisez Grep local pour un répertoire restreint déjà présent sur le disque.

Paramètres :

queryRequis

Type: str
Description: Motif textuel

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

modeOptionnel

Type: Literal[fuzzy, exact, regex]
Par défaut: exact
Description: Mode de recherche

search_scopeOptionnel

Type: Literal[content, symbols, files]
Par défaut: content
Description: Éléments à rechercher

limitOptionnel

Type: int
Par défaut: 5
Description: Nombre maximal de résultats renvoyés sur cette page

offsetOptionnel

Type: int
Description: Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.

cursorOptionnel

Type: str
Description: Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.

language_filterOptionnel

Type: str
Description: Filtre de langage

path_filterOptionnel

Type: str
Description: Filtrer par préfixe de chemin de fichier

case_sensitiveOptionnel

Type: bool
Par défaut
Description: Sensible à la casse

branchOptionnel

Type: str
Description: Remplacement de branche

fuzzy_algorithmOptionnel

Type: Literal[hybrid, trigram, levenshtein]
Par défaut: hybrid
Description: Algorithme de correspondance approximative

thresholdOptionnel

Type: float
Par défaut: 0.05
Description: Seuil minimal de similarité pour la recherche approximative

semantic_fallbackOptionnel

Type: bool
Par défaut
Description: Revenir à la recherche sémantique en l'absence de résultat

Paramètre	Type	Requis	Par défaut	Description
`query`	`str`	Oui	-	Motif textuel
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`mode`	`Literal[fuzzy, exact, regex]`	Non	`exact`	Mode de recherche
`search_scope`	`Literal[content, symbols, files]`	Non	`content`	Éléments à rechercher
`limit`	`int`	Non	`5`	Nombre maximal de résultats renvoyés sur cette page
`offset`	`int`	Non	-	Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.
`cursor`	`str`	Non	-	Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.
`language_filter`	`str`	Non	-	Filtre de langage
`path_filter`	`str`	Non	-	Filtrer par préfixe de chemin de fichier
`case_sensitive`	`bool`	Non		Sensible à la casse
`branch`	`str`	Non	-	Remplacement de branche
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	Non	`hybrid`	Algorithme de correspondance approximative
`threshold`	`float`	Non	`0.05`	Seuil minimal de similarité pour la recherche approximative
`semantic_fallback`	`bool`	Non		Revenir à la recherche sémantique en l'absence de résultat

Idéal pour :

Chaînes exactes, messages d'erreur et regex
Correspondance floue par trigrammes pour un texte presque identique

Déconseillé pour :

Un chemin connu sur le disque — préférez Grep en local
Requêtes conceptuelles — utilisez semantic_search

Outils structurels et de graphe#

structural_searchStable

Préférez preset=functions|classes|methods|imports|variables (ou pattern= libre). Trouvez le code par sa forme AST (pas par le texte). Filtres de niveau intermédiaire : name_pattern, node_type, decorator, parent_child. Les filtres de chemin/ltree/appel sont avancés — définissez advanced=true lorsque vous les utilisez délibérément ; les clés avancées à plat restent acceptées pour la rétrocompatibilité. Fournissez au moins un sélecteur structurel.

Paramètres :

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

presetOptionnel

Type: Literal[functions, classes, methods, imports, variables]
Description: Sélecteur structurel privilégié. Se développe en types de nœuds AST multilingues — functions (définitions de fonction/flèche/méthode selon les langages) ; classes (définitions de classe/struct/impl) ; methods (définitions de méthode, et function_definition pour les langages sans nœud de méthode) ; imports (instructions import/use/include) ; variables (déclarations variable/let/const/static). À préférer à pattern/node_type libre pour les requêtes de type parcours.

patternOptionnel

Type: str
Description: Motif Free-form lorsque les préréglages sont trop grossiers (détecté automatiquement : 'def foo(' → node_type + name_pattern). Préférez preset= pour les requêtes de parcours.

name_patternOptionnel

Type: str
Description: Motif de nom de symbole (caractère générique shell, expression régulière POSIX bornée ou texte approximatif ; 256 caractères max.)

node_typeOptionnel

Type: str
Description: Type de nœud AST (function_definition, class_definition, etc.) — préférez preset= pour les formes courantes

decoratorOptionnel

Type: str
Description: Filtre par nom de décorateur

base_classOptionnel

Type: str
Description: Filtre par nom de classe de base (trouve les classes qui en héritent)

language_filterOptionnel

Type: str
Description: Filtre de langage

limitOptionnel

Type: int
Par défaut: 20
Description: Nombre maximal de résultats renvoyés sur cette page

offsetOptionnel

Type: int
Description: Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.

cursorOptionnel

Type: str
Description: Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.

path_filterOptionnel

Type: str
Description: Filtrer par préfixe de chemin de fichier

branchOptionnel

Type: str
Description: Remplacement de branche

query_typeOptionnel

Type: Literal[node_type, name_pattern, parent_child]
Description: Type de requête explicite

parent_typeOptionnel

Type: str
Description: Filtre du type de nœud AST parent

relationshipOptionnel

Type: Literal[parent, ancestor]
Par défaut: parent
Description: Pour les requêtes parent_child : parent direct uniquement, ou n'importe quel ancêtre (utilisez ancestor pour les méthodes de classe imbriquées dans le corps/bloc d'une classe)

has_modifierOptionnel

Type: str
Description: Filtrer par modificateur (export, async, static, etc.)

advancedOptionnel

Type: bool
Par défaut
Description: Définissez true lorsque vous utilisez intentionnellement des filtres de chemin, d'arbre ou d'appel avancés (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Par défaut, false maintient l'interface de l'agent concentrée sur les préréglages. Les clés avancées au format plat fonctionnent toujours pour la compatibilité ascendante, avec un avertissement de métadonnées.

callee_textOptionnel

Type: str
Description: Avancé — préférez preset=functions|classes|methods|imports|variables. Filtre de texte de l'appelé d'une expression d'appel. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

callee_nameOptionnel

Type: str
Description: Avancé — préférez preset=functions|classes|methods|imports|variables. Filtre de nom de l'appelé d'une expression d'appel. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

field_roleOptionnel

Type: str
Description: Avancé — préférez preset=functions|classes|methods|imports|variables. Filtre de rôle de champ AST. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

ltree_ancestorOptionnel

Type: str
Description: Avancé — préférez preset=functions|classes|methods|imports|variables. Filtre de chemin ancêtre AST ltree. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

ltree_descendantOptionnel

Type: str
Description: Avancé — préférez preset=functions|classes|methods|imports|variables. Filtre de chemin descendant AST ltree. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

definition_nameOptionnel

Type: str
Description: Avancé — préférez preset=functions|classes|methods|imports|variables. Filtre de nom de définition. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

min_depthOptionnel

Type: int
Description: Avancé — préférez preset=functions|classes|methods|imports|variables. Profondeur AST minimale. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

max_depthOptionnel

Type: int
Description: Avancé — préférez preset=functions|classes|methods|imports|variables. Profondeur AST maximale. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

Paramètre	Type	Requis	Par défaut	Description
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`preset`	`Literal[functions, classes, methods, imports, variables]`	Non	-	Sélecteur structurel privilégié. Se développe en types de nœuds AST multilingues — functions (définitions de fonction/flèche/méthode selon les langages) ; classes (définitions de classe/struct/impl) ; methods (définitions de méthode, et function_definition pour les langages sans nœud de méthode) ; imports (instructions import/use/include) ; variables (déclarations variable/let/const/static). À préférer à pattern/node_type libre pour les requêtes de type parcours.
`pattern`	`str`	Non	-	Motif Free-form lorsque les préréglages sont trop grossiers (détecté automatiquement : 'def foo(' → node_type + name_pattern). Préférez preset= pour les requêtes de parcours.
`name_pattern`	`str`	Non	-	Motif de nom de symbole (caractère générique shell, expression régulière POSIX bornée ou texte approximatif ; 256 caractères max.)
`node_type`	`str`	Non	-	Type de nœud AST (function_definition, class_definition, etc.) — préférez preset= pour les formes courantes
`decorator`	`str`	Non	-	Filtre par nom de décorateur
`base_class`	`str`	Non	-	Filtre par nom de classe de base (trouve les classes qui en héritent)
`language_filter`	`str`	Non	-	Filtre de langage
`limit`	`int`	Non	`20`	Nombre maximal de résultats renvoyés sur cette page
`offset`	`int`	Non	-	Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.
`cursor`	`str`	Non	-	Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.
`path_filter`	`str`	Non	-	Filtrer par préfixe de chemin de fichier
`branch`	`str`	Non	-	Remplacement de branche
`query_type`	`Literal[node_type, name_pattern, parent_child]`	Non	-	Type de requête explicite
`parent_type`	`str`	Non	-	Filtre du type de nœud AST parent
`relationship`	`Literal[parent, ancestor]`	Non	`parent`	Pour les requêtes parent_child : parent direct uniquement, ou n'importe quel ancêtre (utilisez ancestor pour les méthodes de classe imbriquées dans le corps/bloc d'une classe)
`has_modifier`	`str`	Non	-	Filtrer par modificateur (export, async, static, etc.)
`advanced`	`bool`	Non		Définissez true lorsque vous utilisez intentionnellement des filtres de chemin, d'arbre ou d'appel avancés (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Par défaut, false maintient l'interface de l'agent concentrée sur les préréglages. Les clés avancées au format plat fonctionnent toujours pour la compatibilité ascendante, avec un avertissement de métadonnées.
`callee_text`	`str`	Non	-	Avancé — préférez preset=functions\|classes\|methods\|imports\|variables. Filtre de texte de l'appelé d'une expression d'appel. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.
`callee_name`	`str`	Non	-	Avancé — préférez preset=functions\|classes\|methods\|imports\|variables. Filtre de nom de l'appelé d'une expression d'appel. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.
`field_role`	`str`	Non	-	Avancé — préférez preset=functions\|classes\|methods\|imports\|variables. Filtre de rôle de champ AST. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.
`ltree_ancestor`	`str`	Non	-	Avancé — préférez preset=functions\|classes\|methods\|imports\|variables. Filtre de chemin ancêtre AST ltree. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.
`ltree_descendant`	`str`	Non	-	Avancé — préférez preset=functions\|classes\|methods\|imports\|variables. Filtre de chemin descendant AST ltree. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.
`definition_name`	`str`	Non	-	Avancé — préférez preset=functions\|classes\|methods\|imports\|variables. Filtre de nom de définition. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.
`min_depth`	`int`	Non	-	Avancé — préférez preset=functions\|classes\|methods\|imports\|variables. Profondeur AST minimale. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.
`max_depth`	`int`	Non	-	Avancé — préférez preset=functions\|classes\|methods\|imports\|variables. Profondeur AST maximale. Définissez advanced=true lorsque vous utilisez intentionnellement des filtres de chemin/ltree/appel.

Idéal pour :

Structure au niveau AST : classes, décorateurs, presets function/method
Trouver du code par sa forme plutôt que par son texte

Déconseillé pour :

Requêtes en texte libre ou conceptuelles — utilisez semantic_search ou intelligent_search

dependency_searchStable

Surface principale de rayon d'impact / graphe. Répond à « qu'est-ce qui appelle ceci ? » / « qu'est-ce que ceci utilise ? » via le vrai graphe d'appels/imports. Pour l'impact avant modification : analysis_type="dependents" ou analysis_type="impact" (entrant, profondeur superficielle par défaut pour impact), include_metrics=false par défaut (activez-le pour la centralité + refactor_risk). Impact PR/diff (P1-8) : transmettez changed_paths et/ou patch (diff unifié) — résout les symboles par chemin et renvoie une charge utile compacte de dépendants entrants superficiels sans nécessiter de nom de symbole. Après une modification, définissez verify_after_edit=true avec targets et/ou changed_paths pour une nouvelle requête compacte multi-racine des symboles impactés. Prend aussi en charge dependencies, centrality et orphans. analyze_dependencies est un alias léger pour le chemin impact — préférez cet outil pour les nouveaux agents.

Paramètres :

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

queryOptionnel

Type: str
Description: Nom de symbole ou terme de recherche

targetOptionnel

Type: str
Description: Nom du symbole (alias de query)

changed_pathsOptionnel

Type: list[str]
Description: Chemins relatifs au dépôt pour l'impact de PR/diff (par défaut) ou, avec verify_after_edit=true, vérification post-édition des racines. PR/diff : résout les symboles par chemin et parcourt les dépendances entrantes superficielles ; peut être combiné avec patch=. Vérifier : résout jusqu'à 5 symboles par chemin en tant que racines de vérification (plafonnées en bas dans le mode de vérification). Ne nécessite pas query/target pour l'impact PR/diff.

patchOptionnel

Type: str
Description: Impact PR/diff : texte du patch diff/git unifié. Les chemins sont analysés à partir des en-têtes diff --git / --- / +++ ; même chemin d'impact compact que le changed_paths.

analysis_typeOptionnel

Type: Literal[centrality, dependencies, dependents, impact, orphans]
Par défaut: dependencies
Description: Mode d'analyse. impact = rayon d'impact (dépendants entrants ; profondeur superficielle quand depth est omis). dependents répond aussi à impact. Quand changed_paths ou patch est défini, l'analyse est forcée sur l'impact PR/diff. centrality/orphans ne nécessitent pas de target.

depthOptionnel

Type: Literal[shallow, balanced, deep]
Par défaut: balanced
Description: Profondeur de parcours. Pour analysis_type=impact et l'impact PR/diff, la valeur par défaut effective est shallow sauf si vous définissez depth explicitement.

limitOptionnel

Type: int
Par défaut: 20
Description: Nombre maximal de résultats renvoyés sur cette page

offsetOptionnel

Type: int
Description: Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.

cursorOptionnel

Type: str
Description: Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.

path_filterOptionnel

Type: str
Description: Restreint la résolution du symbole cible par préfixe de chemin de fichier ; les relations de graphe renvoyées peuvent sortir de ce chemin.

language_filterOptionnel

Type: str
Description: Filtrer la résolution de la cible et les résultats de parcours par langage

directionOptionnel

Type: Literal[outgoing, incoming, both]
Description: Direction de parcours (remplace l’inférence de analysis_type)

relationship_typesOptionnel

Type: list[str]
Description: Filtrer les types d'arête (CALL, IMPORT, INHERITS_FROM, etc.). Une liste non vide remplace les valeurs par défaut de graph_view.

exclude_test_pathsOptionnel

Type: bool
Par défaut: true
Description: Par défaut true : exclut les chemins de test, fixture, fournisseur et exemple des résultats de parcours et de centralité. Définissez false pour les inclure. L'analyse des orphelins applique toujours ses propres exclusions de bruit plus strictes.

exclude_generated_pathsOptionnel

Type: bool
Par défaut
Description: Exclure les déclarations générées ainsi que les chemins de construction, de couverture, de cache, de carte source et d'artefact minifié des résultats de traversée

include_module_symbolsOptionnel

Type: bool
Par défaut
Description: Par défaut, false exclut les bords du graphique lorsque from_name ou to_name est le symbole synthétique __module__ (bruit au niveau du module). Définissez true pour inclure les bords au niveau du module dans les résultats pour les relations dépendantes et de dépendance.

branchOptionnel

Type: str
Description: Remplacement de branche

per_hop_limitOptionnel

Type: int
Description: Nombre maximal de relations par saut (1-300)

include_metricsOptionnel

Type: bool
Par défaut
Description: Métriques de graphe facultatives sur les lignes de résultats (compactées avec refactor_risk). Les métriques sont aussi récupérées en interne quand min_centrality>0 mais ne sont renvoyées que si ce paramètre est true.

metrics_detailOptionnel

Type: Literal[summary, full]
Par défaut: summary
Description: Lorsque include_metrics=true : summary (par défaut) renvoie des signaux de décision + refactor_risk ; full renvoie le plus grand ensemble de métriques organisées

include_edge_metadataOptionnel

Type: bool
Par défaut
Description: Inclut les métadonnées brutes et les pondérations (grandes). Les charges utiles à impact compact laissent cela de côté.

symbol_typesOptionnel

Type: list[str]
Description: Filtrer les symboles renvoyés par type (function, class, method, etc.)

exact_matchOptionnel

Type: bool
Par défaut
Description: Exiger une correspondance exacte du nom de symbole (insensible à la casse). Désactive la correspondance approximative

find_similar_patternsOptionnel

Type: bool
Par défaut
Description: Trouver des motifs d’utilisation similaires

min_centralityOptionnel

Type: float
Par défaut: 0
Description: Score PageRank minimal. Les métriques sont récupérées en interne pour le filtrage ; graph_metrics n'est renvoyé que lorsque include_metrics=true.

graph_viewOptionnel

Type: Literal[dependency, type, data_flow, control_flow]
Par défaut: dependency
Description: Vue du graphe utilisée pour les valeurs par défaut des relations de parcours, les métriques et le classement de centralité ; l'analyse des orphelins est calculée sur toutes les vues

verify_after_editOptionnel

Type: bool
Par défaut
Description: Mode de vérification post-édition P2-7 : réinterrogez le graphique d'impact indexé pour les symboles récemment édités dans une réponse multi-racine compacte. Nécessite targets et/ou changed_paths (ou target/query). La valeur par défaut est les personnes à charge entrantes superficielles ; les résultats reflètent le graphique indexé (peut être en retard sur les modifications en direct). Lorsque cela est vrai, a priorité sur l'impact de PR/diff sur le même changed_paths.

targetsOptionnel

Type: list[str]
Description: Lorsque verify_after_edit=true : noms de symboles à revérifier (appelants/dépendants). Fusionné avec target/query si les deux sont fournis.

Paramètre	Type	Requis	Par défaut	Description
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`query`	`str`	Non	-	Nom de symbole ou terme de recherche
`target`	`str`	Non	-	Nom du symbole (alias de query)
`changed_paths`	`list[str]`	Non	-	Chemins relatifs au dépôt pour l'impact de PR/diff (par défaut) ou, avec verify_after_edit=true, vérification post-édition des racines. PR/diff : résout les symboles par chemin et parcourt les dépendances entrantes superficielles ; peut être combiné avec patch=. Vérifier : résout jusqu'à 5 symboles par chemin en tant que racines de vérification (plafonnées en bas dans le mode de vérification). Ne nécessite pas query/target pour l'impact PR/diff.
`patch`	`str`	Non	-	Impact PR/diff : texte du patch diff/git unifié. Les chemins sont analysés à partir des en-têtes diff --git / --- / +++ ; même chemin d'impact compact que le changed_paths.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	Non	`dependencies`	Mode d'analyse. impact = rayon d'impact (dépendants entrants ; profondeur superficielle quand depth est omis). dependents répond aussi à impact. Quand changed_paths ou patch est défini, l'analyse est forcée sur l'impact PR/diff. centrality/orphans ne nécessitent pas de target.
`depth`	`Literal[shallow, balanced, deep]`	Non	`balanced`	Profondeur de parcours. Pour analysis_type=impact et l'impact PR/diff, la valeur par défaut effective est shallow sauf si vous définissez depth explicitement.
`limit`	`int`	Non	`20`	Nombre maximal de résultats renvoyés sur cette page
`offset`	`int`	Non	-	Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.
`cursor`	`str`	Non	-	Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.
`path_filter`	`str`	Non	-	Restreint la résolution du symbole cible par préfixe de chemin de fichier ; les relations de graphe renvoyées peuvent sortir de ce chemin.
`language_filter`	`str`	Non	-	Filtrer la résolution de la cible et les résultats de parcours par langage
`direction`	`Literal[outgoing, incoming, both]`	Non	-	Direction de parcours (remplace l’inférence de analysis_type)
`relationship_types`	`list[str]`	Non	-	Filtrer les types d'arête (CALL, IMPORT, INHERITS_FROM, etc.). Une liste non vide remplace les valeurs par défaut de graph_view.
`exclude_test_paths`	`bool`	Non	`true`	Par défaut true : exclut les chemins de test, fixture, fournisseur et exemple des résultats de parcours et de centralité. Définissez false pour les inclure. L'analyse des orphelins applique toujours ses propres exclusions de bruit plus strictes.
`exclude_generated_paths`	`bool`	Non		Exclure les déclarations générées ainsi que les chemins de construction, de couverture, de cache, de carte source et d'artefact minifié des résultats de traversée
`include_module_symbols`	`bool`	Non		Par défaut, false exclut les bords du graphique lorsque from_name ou to_name est le symbole synthétique __module__ (bruit au niveau du module). Définissez true pour inclure les bords au niveau du module dans les résultats pour les relations dépendantes et de dépendance.
`branch`	`str`	Non	-	Remplacement de branche
`per_hop_limit`	`int`	Non	-	Nombre maximal de relations par saut (1-300)
`include_metrics`	`bool`	Non		Métriques de graphe facultatives sur les lignes de résultats (compactées avec refactor_risk). Les métriques sont aussi récupérées en interne quand min_centrality>0 mais ne sont renvoyées que si ce paramètre est true.
`metrics_detail`	`Literal[summary, full]`	Non	`summary`	Lorsque include_metrics=true : summary (par défaut) renvoie des signaux de décision + refactor_risk ; full renvoie le plus grand ensemble de métriques organisées
`include_edge_metadata`	`bool`	Non		Inclut les métadonnées brutes et les pondérations (grandes). Les charges utiles à impact compact laissent cela de côté.
`symbol_types`	`list[str]`	Non	-	Filtrer les symboles renvoyés par type (function, class, method, etc.)
`exact_match`	`bool`	Non		Exiger une correspondance exacte du nom de symbole (insensible à la casse). Désactive la correspondance approximative
`find_similar_patterns`	`bool`	Non		Trouver des motifs d’utilisation similaires
`min_centrality`	`float`	Non	`0`	Score PageRank minimal. Les métriques sont récupérées en interne pour le filtrage ; graph_metrics n'est renvoyé que lorsque include_metrics=true.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Non	`dependency`	Vue du graphe utilisée pour les valeurs par défaut des relations de parcours, les métriques et le classement de centralité ; l'analyse des orphelins est calculée sur toutes les vues
`verify_after_edit`	`bool`	Non		Mode de vérification post-édition P2-7 : réinterrogez le graphique d'impact indexé pour les symboles récemment édités dans une réponse multi-racine compacte. Nécessite targets et/ou changed_paths (ou target/query). La valeur par défaut est les personnes à charge entrantes superficielles ; les résultats reflètent le graphique indexé (peut être en retard sur les modifications en direct). Lorsque cela est vrai, a priorité sur l'impact de PR/diff sur le même changed_paths.
`targets`	`list[str]`	Non	-	Lorsque verify_after_edit=true : noms de symboles à revérifier (appelants/dépendants). Fusionné avec target/query si les deux sont fournis.

Idéal pour :

Analyse du rayon d'impact avant de modifier un symbole partagé
Impact PR/diff via changed_paths ou patch
Vérification après modification via verify_after_edit

Déconseillé pour :

Recherches simples de texte ou de symboles — préférez text_pattern_search ou find_symbol

Outils d'analyse de code#

find_symbolStable

Accédez à la définition et aux utilisations d'une fonction, d'une classe ou d'une variable. À utiliser lorsque vous connaissez le nom (p. ex. « getCurrentUser ») : plus rapide et plus précis que Grep, sur tout le dépôt indexé. Peut aussi renvoyer les références et les métriques d'importance.

Paramètres :

symbol_nameOptionnel

Type: str
Description: Nom du symbole à rechercher (facultatif — omettez-le pour parcourir par métriques)

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

scopeOptionnel

Type: Literal[definitions, references, both]
Par défaut: both
Description: Portée : definitions|references|both

limitOptionnel

Type: int
Par défaut: 15
Description: Nombre maximal de résultats renvoyés sur cette page

offsetOptionnel

Type: int
Description: Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.

cursorOptionnel

Type: str
Description: Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.

find_similarOptionnel

Type: bool
Par défaut
Description: Trouver des symboles similaires

include_metricsOptionnel

Type: bool
Par défaut
Description: Inclure les métriques de centralité

metrics_detailOptionnel

Type: Literal[summary, full]
Par défaut: summary
Description: Lorsque include_metrics=true : summary (par défaut) renvoie des signaux de décision + refactor_risk ; full renvoie le plus grand ensemble de métriques organisées

path_filterOptionnel

Type: str
Description: Filtrer par préfixe de chemin de fichier

branchOptionnel

Type: str
Description: Remplacement de branche

symbol_typeOptionnel

Type: Literal[function, class, variable, method, constant, module, interface, type]
Description: Filtre par type de symbole

high_impactOptionnel

Type: bool
Par défaut
Description: Parcourt les symboles architecturalement importants (omettez symbol_name). Le mode par défaut est popularity (décile PageRank supérieur moins les méga-hubs utilitaires). Définissez high_impact_mode=risk pour les points d'articulation/coupures de pont.

high_impact_modeOptionnel

Type: Literal[popularity, risk]
Par défaut: popularity
Description: Lorsque high_impact=true : popularité = premier décile de PageRank moins les méga-hubs/modules utilitaires ; risque = points d'articulation classés par SMV bridge_count puis k_core (risque de refactorisation structurelle, pas de popularité du hub)

in_cycleOptionnel

Type: bool
Par défaut
Description: Cycle uniquement

exclude_test_pathsOptionnel

Type: bool
Par défaut: true
Description: Lorsque vous parcourez les métriques du graphe, excluez les tests, les fixtures, le code tiers et les exemples avant le classement. La recherche de symboles nommés reste inchangée.

Paramètre	Type	Requis	Par défaut	Description
`symbol_name`	`str`	Non	-	Nom du symbole à rechercher (facultatif — omettez-le pour parcourir par métriques)
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`scope`	`Literal[definitions, references, both]`	Non	`both`	Portée : definitions\|references\|both
`limit`	`int`	Non	`15`	Nombre maximal de résultats renvoyés sur cette page
`offset`	`int`	Non	-	Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.
`cursor`	`str`	Non	-	Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.
`find_similar`	`bool`	Non		Trouver des symboles similaires
`include_metrics`	`bool`	Non		Inclure les métriques de centralité
`metrics_detail`	`Literal[summary, full]`	Non	`summary`	Lorsque include_metrics=true : summary (par défaut) renvoie des signaux de décision + refactor_risk ; full renvoie le plus grand ensemble de métriques organisées
`path_filter`	`str`	Non	-	Filtrer par préfixe de chemin de fichier
`branch`	`str`	Non	-	Remplacement de branche
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	Non	-	Filtre par type de symbole
`high_impact`	`bool`	Non		Parcourt les symboles architecturalement importants (omettez symbol_name). Le mode par défaut est popularity (décile PageRank supérieur moins les méga-hubs utilitaires). Définissez high_impact_mode=risk pour les points d'articulation/coupures de pont.
`high_impact_mode`	`Literal[popularity, risk]`	Non	`popularity`	Lorsque high_impact=true : popularité = premier décile de PageRank moins les méga-hubs/modules utilitaires ; risque = points d'articulation classés par SMV bridge_count puis k_core (risque de refactorisation structurelle, pas de popularité du hub)
`in_cycle`	`bool`	Non		Cycle uniquement
`exclude_test_paths`	`bool`	Non	`true`	Lorsque vous parcourez les métriques du graphe, excluez les tests, les fixtures, le code tiers et les exemples avant le classement. La recherche de symboles nommés reste inchangée.

Idéal pour :

Repérer la définition, les références et les métriques de graphe d'un symbole connu
Parcourir par centrality, high_impact ou in_cycle lorsque symbol_name est omis

Déconseillé pour :

Requêtes conceptuelles ou zones inconnues — utilisez intelligent_search ou semantic_search

analyze_dependenciesStable

Alias pour le rayon d'impact via dependency_search (dependents/incoming). Préférez dependency_search avec analysis_type="dependents" ou "impact" pour les nouveaux agents. Conserve la forme de réponse historique multi-sauts pour l'impact (graph, connection_summary, métriques facultatives avec refactor_risk). Utilisez graph_view pour limiter la famille de relations : dependency (par défaut), type, data_flow, control_flow.

Paramètres :

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

targetRequis

Type: str
Description: Nom du symbole à analyser

depthOptionnel

Type: Literal[shallow, balanced, deep]
Par défaut: balanced
Description: Profondeur d'analyse (alias pris en charge : auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)

limitOptionnel

Type: int
Par défaut: 10
Description: Nombre maximal de résultats renvoyés sur cette page

offsetOptionnel

Type: int
Description: Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.

cursorOptionnel

Type: str
Description: Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.

directionOptionnel

Type: Literal[incoming, outgoing, both]
Par défaut: incoming
Description: Sens de parcours : 'outgoing' = ce dont dépend ce symbole (ses dépendances), 'incoming' = ce qui dépend de ce symbole (ses dépendants), 'both' = contexte complet. Utilisez 'incoming' pour trouver tous les appelants/utilisateurs d'un symbole.

relationship_typesOptionnel

Type: list[str]
Description: Filtrer les types d'arêtes (CALL, IMPORT, INHERITS_FROM, etc.). Lorsqu'il est fourni, ce paramètre remplace toujours la valeur par défaut dérivée de graph_view ci-dessous.

graph_viewOptionnel

Type: Literal[dependency, type, data_flow, control_flow]
Par défaut: dependency
Description: Vue du graphe : lorsque include_metrics=true, détermine à la fois les types d'arêtes de parcours par défaut et la vue dont les métriques sont utilisées. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (par défaut), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Ne s'applique comme valeur par défaut de relationship_types que si relationship_types n'est pas fourni explicitement. Le nom de paramètre correspond au graph_view existant de dependency_search afin d'assurer la cohérence entre les outils.

path_filterOptionnel

Type: str
Description: Restreint la résolution du symbole cible par préfixe de chemin de fichier ; les relations de graphe renvoyées peuvent sortir de ce chemin.

language_filterOptionnel

Type: str
Description: Restreindre les résultats à un langage

branchOptionnel

Type: str
Description: Remplacement de branche

per_hop_limitOptionnel

Type: int
Description: Nombre maximal de relations par saut (1-300)

include_metricsOptionnel

Type: bool
Par défaut
Description: Inclure les métriques du graphe dans les résultats, chacune enrichie d'un bloc refactor_risk dérivé ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). Le risque vaut "low" si le symbole n'est pas un point d'articulation dans la vue choisie, "medium" s'il relie peu d'arêtes et "high" s'il en relie beaucoup (seuil heuristique non validé empiriquement). Le bloc est omis si aucune ligne de métriques n'existe pour ce symbole/cette vue.

metrics_detailOptionnel

Type: Literal[summary, full]
Par défaut: summary
Description: Lorsque include_metrics=true : summary (par défaut) renvoie des signaux de décision + refactor_risk ; full renvoie le plus grand ensemble de métriques organisées

include_edge_metadataOptionnel

Type: bool
Par défaut
Description: Incluez les métadonnées et les pondérations brutes. Désactivé par défaut car les métadonnées de l'extracteur peuvent être volumineuses ; la couverture d’enrichissement est signalée lorsqu’elle est activée.

exclude_test_pathsOptionnel

Type: bool
Par défaut: true
Description: Par défaut true : exclut les chemins de test, d'appareil, de fournisseur et d'exemple des bords du graphique renvoyés. Définissez false pour les inclure.

include_module_symbolsOptionnel

Type: bool
Par défaut
Description: Par défaut, false exclut les bords du graphique lorsque from_name ou to_name est le symbole synthétique __module__. Définissez true pour inclure les bords au niveau du module.

Paramètre	Type	Requis	Par défaut	Description
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`target`	`str`	Oui	-	Nom du symbole à analyser
`depth`	`Literal[shallow, balanced, deep]`	Non	`balanced`	Profondeur d'analyse (alias pris en charge : auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
`limit`	`int`	Non	`10`	Nombre maximal de résultats renvoyés sur cette page
`offset`	`int`	Non	-	Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.
`cursor`	`str`	Non	-	Curseur opaque de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.
`direction`	`Literal[incoming, outgoing, both]`	Non	`incoming`	Sens de parcours : 'outgoing' = ce dont dépend ce symbole (ses dépendances), 'incoming' = ce qui dépend de ce symbole (ses dépendants), 'both' = contexte complet. Utilisez 'incoming' pour trouver tous les appelants/utilisateurs d'un symbole.
`relationship_types`	`list[str]`	Non	-	Filtrer les types d'arêtes (CALL, IMPORT, INHERITS_FROM, etc.). Lorsqu'il est fourni, ce paramètre remplace toujours la valeur par défaut dérivée de graph_view ci-dessous.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Non	`dependency`	Vue du graphe : lorsque include_metrics=true, détermine à la fois les types d'arêtes de parcours par défaut et la vue dont les métriques sont utilisées. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (par défaut), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Ne s'applique comme valeur par défaut de relationship_types que si relationship_types n'est pas fourni explicitement. Le nom de paramètre correspond au graph_view existant de dependency_search afin d'assurer la cohérence entre les outils.
`path_filter`	`str`	Non	-	Restreint la résolution du symbole cible par préfixe de chemin de fichier ; les relations de graphe renvoyées peuvent sortir de ce chemin.
`language_filter`	`str`	Non	-	Restreindre les résultats à un langage
`branch`	`str`	Non	-	Remplacement de branche
`per_hop_limit`	`int`	Non	-	Nombre maximal de relations par saut (1-300)
`include_metrics`	`bool`	Non		Inclure les métriques du graphe dans les résultats, chacune enrichie d'un bloc refactor_risk dérivé ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). Le risque vaut "low" si le symbole n'est pas un point d'articulation dans la vue choisie, "medium" s'il relie peu d'arêtes et "high" s'il en relie beaucoup (seuil heuristique non validé empiriquement). Le bloc est omis si aucune ligne de métriques n'existe pour ce symbole/cette vue.
`metrics_detail`	`Literal[summary, full]`	Non	`summary`	Lorsque include_metrics=true : summary (par défaut) renvoie des signaux de décision + refactor_risk ; full renvoie le plus grand ensemble de métriques organisées
`include_edge_metadata`	`bool`	Non		Incluez les métadonnées et les pondérations brutes. Désactivé par défaut car les métadonnées de l'extracteur peuvent être volumineuses ; la couverture d’enrichissement est signalée lorsqu’elle est activée.
`exclude_test_paths`	`bool`	Non	`true`	Par défaut true : exclut les chemins de test, d'appareil, de fournisseur et d'exemple des bords du graphique renvoyés. Définissez false pour les inclure.
`include_module_symbols`	`bool`	Non		Par défaut, false exclut les bords du graphique lorsque from_name ou to_name est le symbole synthétique __module__. Définissez true pour inclure les bords au niveau du module.

Idéal pour :

Appelants existants déjà conçus pour sa forme de réponse (graph, connection_summary)

Déconseillé pour :

Nouvelles boucles d'agent — préférez dependency_search, qui partage le même cœur de traversée

get_task_contextStable

Vous commencez dans une zone inconnue ? Décrivez la tâche (p. ex. « ajouter la prise en charge de SSO », « corriger le webhook de facturation ») et obtenez en un seul appel un paquet borné de fichiers, code, symboles et dépendances pertinents. Les fichiers de départ apportent du contenu indexé direct même s'ils ne définissent aucun symbole. Pour plus de résultats, poursuivez avec l'outil de recherche spécialisé pour cette couche.

Paramètres :

task_descriptionRequis

Type: str
Description: Description de la tâche

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

limitOptionnel

Type: int
Par défaut: 15
Description: Nombre maximal de résultats par couche

scopeOptionnel

Type: Literal[semantic, symbols, dependencies, all]
Par défaut: all
Description: Couches de contexte à inclure. Valeurs : 'semantic', 'symbols', 'dependencies', 'all'. Par défaut : ['semantic', 'symbols', 'dependencies']

language_filterOptionnel

Type: str
Description: Filtrer les résultats aux fichiers détectés dans ce langage de programmation

path_filterOptionnel

Type: str
Description: Filtrer par préfixe de chemin de fichier

branchOptionnel

Type: str
Description: Remplacement de branche

include_related_contextOptionnel

Type: bool
Par défaut
Description: Inclure le contexte associé des symboles adjacents

seed_symbol_idsOptionnel

Type: list[str]
Description: Graines explicites de niveau 1 : identifiants de symboles que l'agent sait déjà être centraux pour la tâche (p. ex. les symboles des fichiers ouverts). Elles sont classées avant les graines dérivées des mots-clés dans les couches dependencies/related_context. Ce paramètre est additif : omettez-le pour conserver le comportement actuel fondé uniquement sur les mots-clés.

seed_file_pathsOptionnel

Type: list[str]
Description: Graines explicites de niveau 1 : chemins de fichiers indexés que l'agent a ouverts ou vient de modifier. Renvoie des preuves de fichier directes et bornées, et résout jusqu'à 5 symboles par fichier pour le contexte de graphe, y compris la documentation et la configuration sans symbole. Additif — omettez pour un comportement fondé uniquement sur les mots-clés.

Paramètre	Type	Requis	Par défaut	Description
`task_description`	`str`	Oui	-	Description de la tâche
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`limit`	`int`	Non	`15`	Nombre maximal de résultats par couche
`scope`	`Literal[semantic, symbols, dependencies, all]`	Non	`all`	Couches de contexte à inclure. Valeurs : 'semantic', 'symbols', 'dependencies', 'all'. Par défaut : ['semantic', 'symbols', 'dependencies']
`language_filter`	`str`	Non	-	Filtrer les résultats aux fichiers détectés dans ce langage de programmation
`path_filter`	`str`	Non	-	Filtrer par préfixe de chemin de fichier
`branch`	`str`	Non	-	Remplacement de branche
`include_related_context`	`bool`	Non		Inclure le contexte associé des symboles adjacents
`seed_symbol_ids`	`list[str]`	Non	-	Graines explicites de niveau 1 : identifiants de symboles que l'agent sait déjà être centraux pour la tâche (p. ex. les symboles des fichiers ouverts). Elles sont classées avant les graines dérivées des mots-clés dans les couches dependencies/related_context. Ce paramètre est additif : omettez-le pour conserver le comportement actuel fondé uniquement sur les mots-clés.
`seed_file_paths`	`list[str]`	Non	-	Graines explicites de niveau 1 : chemins de fichiers indexés que l'agent a ouverts ou vient de modifier. Renvoie des preuves de fichier directes et bornées, et résout jusqu'à 5 symboles par fichier pour le contexte de graphe, y compris la documentation et la configuration sans symbole. Additif — omettez pour un comportement fondé uniquement sur les mots-clés.

Idéal pour :

Contexte adapté à la tâche, mêlant les fichiers de départ aux couches sémantique, symbolique et de dépendances

Déconseillé pour :

Recherches à outil unique lorsqu'un outil plus spécifique répond déjà à la question

get_fileStable

Lisez un fichier du dépôt indexé par son chemin. Préférez l'outil Read local pour les fichiers présents sur le disque — utilisez celui-ci pour les recherches inter-dépôts ou distantes lorsque le fichier n'est pas dans l'arborescence de travail. Prend en charge une plage de lignes facultative ; poursuivez une réponse tronquée par les tokens à partir de metadata.next_line_start.

Paramètres :

file_pathRequis

Type: str
Description: Chemin du fichier relatif à la racine du dépôt

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.

line_startOptionnel

Type: int
Description: Ligne de début (indexée à partir de 1)

line_endOptionnel

Type: int
Description: Ligne de fin (indexée à partir de 1, incluse ; doit être supérieure ou égale à line_start)

branchOptionnel

Type: str
Description: Remplacement de branche

max_tokensOptionnel

Type: int
Par défaut: 5000
Description: Nombre maximal de tokens

include_metadataOptionnel

Type: bool
Par défaut: true
Description: Inclure les métadonnées

Paramètre	Type	Requis	Par défaut	Description
`file_path`	`str`	Oui	-	Chemin du fichier relatif à la racine du dépôt
`repository`	`str`	Non	-	Dépôt au format owner/repo[:branch]. Facultatif — omettez-le pour utiliser la valeur par défaut du client limitée à la requête (si elle est fournie) ou l’unique dépôt accessible ; transmettez-le explicitement uniquement pour cibler un autre dépôt indexé. La réponse indique le dépôt utilisé.
`line_start`	`int`	Non	-	Ligne de début (indexée à partir de 1)
`line_end`	`int`	Non	-	Ligne de fin (indexée à partir de 1, incluse ; doit être supérieure ou égale à line_start)
`branch`	`str`	Non	-	Remplacement de branche
`max_tokens`	`int`	Non	`5000`	Nombre maximal de tokens
`include_metadata`	`bool`	Non	`true`	Inclure les métadonnées

Idéal pour :

Instantanés de fichiers distants ou indexés (plages de lignes, limites de tokens)

Déconseillé pour :

Un chemin déjà présent sur le disque local — utilisez l'outil Read local

Outils système et utilitaires#

repository_contextStable

Listez les dépôts consultables, ou obtenez les informations d'identité d'un dépôt (espace de noms/branche, indexed_commit_sha / fraîcheur de l'index). Appelez avec action:"list" une fois pour connaître l'identifiant exact accepté par les outils de recherche. (Si votre clé ne donne accès qu'à un dépôt, celui-ci est utilisé par défaut — vous pouvez sauter cette étape.) Les comptes de fichiers/blobs/arêtes à l'échelle de l'espace de noms sont facultatifs via include_statistics=true.

Paramètres :

actionRequis

Type: Literal[list, info]
Description: Action : lister les dépôts disponibles ou obtenir les informations d'un dépôt

repositoryOptionnel

Type: str
Description: Dépôt au format owner/repo ou owner/repo:branch (obligatoire pour info)

branchOptionnel

Type: str
Description: Remplacement de branche

patternOptionnel

Type: str
Description: Motif de filtre

include_statisticsOptionnel

Type: bool
Par défaut
Description: Facultatif : inclut les comptes de données indexées à l'échelle de l'espace de noms (fichier/blob/arête). Faux par défaut — l'identité du dépôt ne nécessite pas cet agrégat plus lent.

limitOptionnel

Type: int
Par défaut: 20
Description: Nombre maximal de résultats renvoyés sur cette page

offsetOptionnel

Type: int
Description: Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.

cursorOptionnel

Type: str
Description: Opaque cursor de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.

Paramètre	Type	Requis	Par défaut	Description
`action`	`Literal[list, info]`	Oui	-	Action : lister les dépôts disponibles ou obtenir les informations d'un dépôt
`repository`	`str`	Non	-	Dépôt au format owner/repo ou owner/repo:branch (obligatoire pour info)
`branch`	`str`	Non	-	Remplacement de branche
`pattern`	`str`	Non	-	Motif de filtre
`include_statistics`	`bool`	Non		Facultatif : inclut les comptes de données indexées à l'échelle de l'espace de noms (fichier/blob/arête). Faux par défaut — l'identité du dépôt ne nécessite pas cet agrégat plus lent.
`limit`	`int`	Non	`20`	Nombre maximal de résultats renvoyés sur cette page
`offset`	`int`	Non	-	Compensation de compatibilité obsolète. Préférez cursor de pagination.next_cursor.
`cursor`	`str`	Non	-	Opaque cursor de pagination.next_cursor. Transmettez-le inchangé et conservez la requête et les filtres inchangés.

Idéal pour :

Lister les dépôts accessibles
Résoudre l'identité du dépôt, la branche et la fraîcheur de HEAD par rapport à l'index

Déconseillé pour :

Statistiques à l'échelle du namespace par défaut — transmettez explicitement include_statistics=true, car cela peut être plus lent que la simple résolution

ask_maguyvaStable

Aide et retours pour Maguyva. Usage principal : obtenir des conseils sur les outils, ou envoyer un rapport de bug / une demande de fonctionnalité conservés pour les mainteneurs de Maguyva. N'incluez jamais de secrets ni de données personnelles sensibles dans un retour. L'opération evaluate n'est conservée que pour la rétrocompatibilité — préférez le calcul local ou les outils hôtes pour les tâches de calcul/hachage/chaînes.

Paramètres :

operationRequis

Type: Literal[guidance, report_bug, request_feature, evaluate]
Description: Principal : guidance, report_bug, request_feature. Hérité/compatibilité uniquement : evaluate (moteur d'expressions déterministe ; ne fait pas partie du flux de travail principal de l'agent).

queryOptionnel

Type: str
Description: Sujet du guide (p. ex. tool_selection, semantic_search). Pour evaluate hérité uniquement : chaîne d'expression.

descriptionOptionnel

Type: str
Description: Obligatoire pour report_bug et request_feature. Retour Free-form destiné aux mainteneurs de Maguyva. N'incluez jamais de secrets ni de données personnelles sensibles.

related_toolOptionnel

Type: Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
Description: Outil facultatif Maguyva le plus étroitement lié au feedback

Paramètre	Type	Requis	Par défaut	Description
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	Oui	-	Principal : guidance, report_bug, request_feature. Hérité/compatibilité uniquement : evaluate (moteur d'expressions déterministe ; ne fait pas partie du flux de travail principal de l'agent).
`query`	`str`	Non	-	Sujet du guide (p. ex. tool_selection, semantic_search). Pour evaluate hérité uniquement : chaîne d'expression.
`description`	`str`	Non	-	Obligatoire pour report_bug et request_feature. Retour Free-form destiné aux mainteneurs de Maguyva. N'incluez jamais de secrets ni de données personnelles sensibles.
`related_tool`	`Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]`	Non	-	Outil facultatif Maguyva le plus étroitement lié au feedback

Idéal pour :

Conseils sur les outils (operation="guidance")
Rapports de bugs durables et demandes de fonctionnalités pour les mainteneurs de Maguyva

Déconseillé pour :

Calculs mathématiques/hash/chaînes — l'opération evaluate n'est conservée que pour la rétrocompatibilité ; préférez le calcul local ou les outils hôtes

Bonnes pratiques#

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.
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.
Exploiter les filtres de langage: Utilisez language_filter pour restreindre les résultats et améliorer les performances.
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.
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 — cela ne corrige pas les fautes de frappe. Vérifiez metadata.resolution_reason sur l'action info ("exact" contre "corrected") pour voir comment un nom a été résolu.
Combiner les outils: Utilisez plusieurs méthodes d'API ensemble pour une analyse complète.
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).
Utiliser ask_maguyva pour l'orientation sur les outils: L'opération evaluate de ask_maguyva (hash, base64, JSON, calcul) est un mode legacy / rétrocompatibilité uniquement. Appelez plutôt ask_maguyva avec operation="guidance" et query="tool_selection" pour obtenir la matrice de priorité des outils locaux et un aide-mémoire complet outil par outil.
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.

Caractéristiques de performance#

Opération	Remarques sur les performances
Recherche sémantique	Moins d'une seconde, mais inclut un appel API d'embedding en direct à chaque fois (non mis en cache) — attendez-vous à une latence supplémentaire en plus de la requête vectorielle
Recherche textuelle	Moins d'une seconde pour les correspondances exactes/regex ; la recherche floue de contenu pagine côté client, donc les décalages profonds coûtent plus cher — affinez avec path_filter/language_filter
Recherche structurelle	Indexée par AST — le coût évolue avec le volume de résultats, pas avec la taille du dépôt
Recherche de dépendances	Le coût évolue avec la profondeur — préférez depth="shallow" sauf si vous avez besoin d'un contexte multi-sauts ; per_hop_limit borne l'éventail des résultats
Récupération de fichier	Quasi instantanée pour un seul fichier — paginez les gros fichiers avec line_start/line_end ou max_tokens plutôt que de tout récupérer d'un coup
Contexte du dépôt	La résolution de l'espace de noms est mise en cache uniquement pour la requête en cours, pas entre les appels — chaque invocation d'outil la résout à nouveau
ask_maguyva (guidance / evaluate)	Quasi instantané — s'exécute dans le Worker sans appel base de données

Gestion des erreurs#

Toutes les méthodes de l'API renvoient une enveloppe structurée :

status: Chaîne — "success" ou "error". Les signaux de correspondance dégradée ou de fraîcheur se trouvent dans des champs imbriqués tels que metadata.resolution_reason sur repository_context ou metadata.index_freshness.status.
tool: Nom de l'outil qui a généré la réponse
data: Charge utile du résultat en cas de succès (la structure varie selon l'outil)
error: Objet d'erreur structuré quand status vaut "error" — inclut type, message, suggestions et recovery_actions
metadata: Informations complémentaires sur l'opération (routage, mise en cache, ajustements de paramètres)
pagination: Présent sur les réponses de liste — inclut has_more et next_cursor

Vérifiez toujours le champ status avant de traiter les résultats — il vaut uniquement "success" ou "error". Pour les signaux de correspondance dégradée ou de fraîcheur, consultez plutôt le champ imbriqué : metadata.resolution_reason sur repository_context, ou metadata.index_freshness.status (known/partial/unknown/unavailable).

Bien démarrer#

Configurer le client MCP: Pointez votre client MCP vers le point de terminaison du serveur Maguyva
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
Commencer à rechercher: Commencez avec intelligent_search et explorez les outils spécialisés au besoin
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.