project-graph-mcp aide les agents d’AI à voir l’architecture du projet sans tokens superflus

Une nouvelle méthode a émergé pour que les agents IA naviguent rapidement dans du code inconnu : project-graph-mcp construit un graphe structurel du projet et le retourne en JSON compressé. Au lieu de lire des dizaines de fichiers en séquence, un agent reçoit une carte de l'architecture, voit les dépendances et se plonge ensuite dans les zones nécessaires.

Comment fonctionne le serveur

L'idée clé derrière project-graph-mcp est le soi-disant squelette du projet. Le serveur analyse le code source, recueille des informations sur les fichiers, classes, fonctions, importations et appels, puis retourne tout cela dans une structure compacte. Selon l'auteur, la compression atteint 10 à 50 fois, permettant au modèle de comprendre l'architecture globale sans consommer un contexte énorme. Cette approche est particulièrement utile pour les IDEs d'agents et les orchestrateurs qui doivent décider rapidement quel fichier lire, où déléguer les sous-tâches et comment les modules sont liés.

La compression atteint 10 à 50 fois.

Au départ, l'outil fonctionnait uniquement avec JavaScript via le parser AST Acorn, mais dans la version 1.1, il a reçu le support de TypeScript, Python et Go. Pour les nouveaux langages, l'auteur a choisi une approche basée sur regex : elle est plus simple, plus légère et ne nécessite pas de charger de lourdes bibliothèques externes juste pour la navigation basique du code. En même temps, tous les parsers sont standardisés vers la même sortie — des listes de classes, fonctions, importations et appels — pour que l'agent fonctionne avec le même modèle de projet quel que soit la pile technologique.

Quels problèmes résout-il

Le projet ne se termine pas avec un seul graphe. Le serveur inclut des outils d'analyse intégrés qui permettent non seulement la navigation mais aussi l'identification rapide des zones problématiques. L'agent peut comprendre quelles sections de code sont potentiellement mortes, où une fonction s'est développée à une taille inconfortable et quelle chaîne d'appels suit une demande du middleware au rendu ou au gestionnaire API. Cela fait que le serveur est plus qu'une simple carte du projet — c'est un outil de diagnostic technique initial.

• `get_dead_code` trouve les fonctions et modules non utilisés
• `get_complexity` évalue la complexité cyclomatique
• `get_large_files` identifie les fichiers candidats à la refactorisation
• `get_call_chain` montre le chemin entre les fonctions liées
• Health Score agrège les résultats des vérifications en une note de 0 à 100

De plus, project-graph-mcp inclut des listes de vérification de tests via les annotations JSDoc `@test` et `@expect`. Un agent peut recevoir une liste de vérifications ouvertes, écrire du code puis marquer les tests comme réussis. Cela fonctionne comme un pont entre la navigation du projet et le cycle de développement réel : d'abord le modèle comprend la structure de l'application, puis effectue des modifications et vérifie immédiatement le comportement attendu. Pour les piles typiques, il existe aussi des règles intégrées : 11 ensembles avec 86 conventions pour React, Vue, Express, TypeScript et Symbiote.js.

Intégration et sécurité

L'outil est conçu comme une partie d'un framework d'agent plus large. L'auteur décrit un scénario où l'agent principal dans l'IDE demande d'abord le squelette du projet, puis délègue les tâches individuelles aux workers de fond via agent-pool-mcp. Chaque worker exécute le même serveur localement et invoque `expand`, `deps` et d'autres méthodes pour des sections de code spécifiques. De cette façon, l'orchestrateur ne tire pas de fichiers inutiles dans le contexte et peut distribuer le travail plus rapidement entre les modèles avec différentes spécialisations.

Du point de vue de l'implémentation, la barrière à l'entrée est basse : Node.js 18+ est requis, le serveur s'exécute via `npx`, pèse 132 KB, se compose de 47 fichiers et n'a aucune dépendance externe. La version 1.2.0 est déjà disponible sur npm. Les auteurs ont également spécifiquement abordé la sécurité. Tous les chemins passent la validation via `resolve` et `startsWith`, donc l'agent ne peut pas s'échapper du répertoire de travail. Tenter d'accéder à quelque chose comme `../../etc/passwd` retourne une erreur. Pour les outils MCP qui lisent les fichiers et dépendances, une telle protection est critique.

Ce que cela signifie

Les agents IA passent progressivement de l'autocomplétion simple à la compréhension de l'architecture de projets entiers. project-graph-mcp est intéressant parce qu'il résout un problème pratique de contexte : au lieu de centaines de lignes de code, le modèle obtient une carte système compacte et fonctionne plus précisément. Pour les équipes qui construisent leurs propres agents IA pour le développement, ce n'est plus une expérience mais une couche d'infrastructure tout à fait pratique. Si de tels serveurs MCP deviennent standard, le développement basé sur les agents fera face à moins de limites de token et plus souvent sera limité par la qualité de la logique d'ingénierie elle-même.