mcp-pilotage

🇫🇷 Français · 🇬🇧 English

Serveur MCP en lecture seule qui cartographie tous les dépôts git présents sur la machine. Un agent IA branché dans n'importe lequel d'entre eux découvre seul l'écosystème complet : inventaire, pile technique, état git en direct, fichiers de contexte et recherche transverse, sans explication préalable.

Node / TypeScript, SDK MCP officiel, transport stdio, strictement en lecture seule. Les descriptions des outils et les réponses sont rédigées en français.

Ce qu'il résout

Quand une quinzaine de dépôts vivent côte à côte, un agent qui démarre dans l'un d'eux ne sait rien des autres. Ce serveur lui donne, en un appel, la liste des projets, leur rôle, leur pile technique, leur état git en direct, et de quoi fouiller tous les projets d'un coup.

L'inventaire vient d'un scan du disque à chaque appel (avec un cache court), pas d'un fichier de configuration. Il ne peut donc pas devenir faux quand un projet est créé, renommé ou supprimé.

Related MCP server: AI Developer Workspace MCP Server

Les outils exposés

Garanties de sécurité

Le serveur est en lecture seule par construction :

• aucun outil n'écrit, ne crée, ne supprime ni ne renomme de fichier ;

• aucune commande git modifiante n'est utilisée, ni add, ni commit, ni push, ni checkout, ni fetch, ni reset. Seuls rev-parse, log, status, branch, rev-list et config --get sont appelés ;

• aucun accès réseau ;

• suivi_agents ne lit que la fin des journaux de session (jamais le fichier entier, jamais un message complet restitué) et interroge la liste des processus et la charge du processeur par Get-CimInstance (Win32_Process, Win32_Processor) : il ne tue aucun processus, ne change aucune priorité, n'écrit rien ;

• les lectures restent confinées aux racines configurées, et un garde-fou refuse tout chemin qui sortirait du projet ciblé ;

• les fichiers de secrets (.env, .env.*, *.env, *.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*) ne sont jamais fouillés par chercher_partout, y compris dans les dossiers hors git et sans ripgrep. Avec ripgrep, les .gitignore sont en plus respectés.

Prérequis

• Node.js 18 ou plus

• git dans le PATH

• ripgrep facultatif : détecté dans le PATH, puis dans l'installation de VS Code. Sans lui, la recherche bascule sur un repli en Node, plus lent.

• Windows pour la section Processus de suivi_agents (elle passe par PowerShell). Sur les autres systèmes, cette section renvoie un message d'indisponibilité, le reste fonctionne.

Installation

git clone https://github.com/fmenguy/mcp-pilotage.git
cd mcp-pilotage
npm install
npm run build

Le point d'entrée compilé est dist/index.js. Le plus simple est de cloner ce dépôt à côté des autres (par exemple dans D:\git) : sans réglage, le serveur scanne le dossier qui le contient.

Brancher le serveur

Dans Claude Code, pour l'avoir dans tous les projets d'un coup :

claude mcp add pilotage --scope user -- node D:/git/mcp-pilotage/dist/index.js

Ou dépôt par dépôt, avec --scope project, ce qui revient à créer un .mcp.json à la racine du dépôt :

{
  "mcpServers": {
    "pilotage": {
      "command": "node",
      "args": ["D:/git/mcp-pilotage/dist/index.js"]
    }
  }
}

Adapter le chemin à l'endroit où le dépôt a été cloné. N'importe quel client MCP en stdio fonctionne de la même façon.

Configuration facultative

Tout est pilotable par variables d'environnement, dans le bloc env du .mcp.json ou avec -e sur claude mcp add. Aucune n'est obligatoire.

Exemple avec plusieurs racines :

claude mcp add pilotage --scope user -e "PILOTAGE_RACINES=D:/git;E:/autres-projets" -- node D:/git/mcp-pilotage/dist/index.js

Le dossier d'usage de l'API Claude

usage_ia_claude lit deux sortes de fichiers, déposés à la main, et ne les modifie jamais :

• un export CSV des tokens par mois, nommé claude_api_tokens_AAAA_MM.csv (export de la console Claude) ;

• un fichier factures.csv, tenu à la main, car les factures mélangent abonnement et usage mesuré et ne se déduisent pas des tokens.

Le dossier usage/ de ce dépôt est ignoré par git : on peut y déposer ses fichiers sans risque de les publier, ou pointer ailleurs avec PILOTAGE_DOSSIER_USAGE. Sans fichier, l'outil répond qu'il n'a trouvé aucun export et indique le dossier attendu.

Conventions d'écriture

Deux registres cohabitent volontairement dans le code et dans les réponses :

• Les identifiants restent en ASCII : noms d'outils (apercu_ecosysteme), noms de paramètres (rafraichir, seulement_modifies), clés JSON des résultats (depots_git, resultat_tronque). C'est une convention de sérialisation stable, sur laquelle un appelant peut s'appuyer sans se soucier des accents.

• Tout ce qui se lit est écrit en français correct, entièrement accentué : descriptions des outils, descriptions des paramètres, titres et en-têtes du markdown généré, messages d'état et d'erreur, valeurs de repli.

Les filtres textuels (filtre, famille) comparent sans tenir compte des accents ni de la casse : Ecriture et romans et Écriture et romans donnent le même résultat, mais la valeur renvoyée reste toujours la forme correcte.

Le contenu extrait des fichiers des projets (rôles déduits d'un CLAUDE.md ou d'un README) est restitué tel quel, sans retouche.

Performances observées

Mesures relevées sur une machine Windows avec 20 projets (17 dépôts git et 3 dossiers hors git) :

Les dossiers node_modules, .git, dist, build, .astro, venv, __pycache__ et une vingtaine d'autres ne sont jamais parcourus.

Développement

npm run dev                     # exécution directe des sources via tsx
npm run build                   # compilation TypeScript vers dist/
npm test                        # client MCP stdio qui appelle chaque outil et chronomètre (nécessite npm run build)
node tests/suivi-agents.mjs [minutes] [filtre] [detail]   # appelle seulement suivi_agents sur les vrais journaux
node tests/verif-accents.mjs    # contrôle de l'accentuation et de l'encodage UTF-8

tests/client-test.mjs démarre le serveur compilé, liste les outils et exerce chaque outil avec des paramètres réels sur ce dépôt lui-même, y compris un cas d'erreur (projet inexistant). C'est le moyen le plus rapide de vérifier une modification.

tests/verif-accents.mjs affiche les descriptions complètes telles qu'un modèle les reçoit, compte les caractères accentués, contrôle les points de code du markdown généré et vérifie que les fichiers source sont en UTF-8 sans BOM.

Organisation du code

src/
  index.ts            point d'entrée, transport stdio, enregistrement des outils
  config.ts           configuration, variables d'environnement, motifs de secrets
  core/
    fichiers.ts       parcours et lectures tolérantes aux erreurs, glob maison
    depots.ts         scan des racines, cache, résolution d'un projet par nom
    stack.ts          détection de la pile technique et de la famille
    cerveau.ts        repérage et lecture des documents de contexte
    git.ts            état git en lecture seule
    recherche.ts      recherche transverse, ripgrep avec repli Node
    usage.ts          lecture et agrégation des exports de tokens et des factures
    agents.ts         journaux Codex, Claude Code et Vibe (fin de fichier seulement), processus vivants
  outils/             définition des outils MCP exposés
  utils/reponse.ts    formatage des réponses et garde-fou anti-plantage
tests/                client de test MCP, essai de suivi_agents, contrôle des accents

Licence

MIT, voir LICENSE.

Auteur : François Menguy, fmenguy.fr.

mcp-pilotage (English)

🇬🇧 English · 🇫🇷 Français

A read-only MCP server that maps every git repository on your machine. An AI agent opened in any one of them can discover the whole ecosystem on its own: inventory, tech stack, live git status, context files and cross-repository search, with no briefing needed.

Node / TypeScript, official MCP SDK, stdio transport, strictly read only. Tool descriptions and answers are written in French; tool and parameter names are ASCII identifiers.

The problem it solves

With fifteen or so repositories side by side, an agent that starts in one of them knows nothing about the others. This server gives it, in a single call, the list of projects, their purpose, their tech stack, their live git status, and a way to search all of them at once.

The inventory comes from a disk scan on every call (with a short cache), not from a configuration file. It cannot go stale when a project is created, renamed or deleted.

Tools

Safety guarantees

The server is read only by design:

• no tool writes, creates, deletes or renames a file;

• no git command that changes anything is used: no add, commit, push, checkout, fetch or reset. Only rev-parse, log, status, branch, rev-list and config --get are called;

• no network access;

• suivi_agents only reads the tail of session logs (never the whole file, never a full message returned) and queries the process list and CPU load through Get-CimInstance (Win32_Process, Win32_Processor): it kills no process, changes no priority, writes nothing;

• reads stay inside the configured roots, and a guard rejects any path that would escape the target project;

• secret files (.env, .env.*, *.env, *.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*) are never searched by chercher_partout, including in non-git folders and without ripgrep. With ripgrep, .gitignore files are honored as well.

Prerequisites

• Node.js 18 or later

• git on the PATH

• ripgrep, optional: looked up on the PATH, then in the VS Code installation. Without it, search falls back to a slower Node implementation.

• Windows for the Processes section of suivi_agents (it goes through PowerShell). On other systems that section reports it is unavailable; everything else works.

Installation

git clone https://github.com/fmenguy/mcp-pilotage.git
cd mcp-pilotage
npm install
npm run build

The compiled entry point is dist/index.js. The simplest setup is to clone this repository next to your other ones (for example in D:\git): with no configuration, the server scans the folder that contains it.

Hooking it up

In Claude Code, to get it in every project at once:

claude mcp add pilotage --scope user -- node D:/git/mcp-pilotage/dist/index.js

Or per repository with --scope project, which amounts to a .mcp.json at the repository root:

{
  "mcpServers": {
    "pilotage": {
      "command": "node",
      "args": ["D:/git/mcp-pilotage/dist/index.js"]
    }
  }
}

Adjust the path to wherever you cloned the repository. Any stdio MCP client works the same way.

Optional configuration

Everything is driven by environment variables, in the env block of .mcp.json or with -e on claude mcp add. None is required.

Example with several roots:

claude mcp add pilotage --scope user -e "PILOTAGE_RACINES=D:/git;E:/other-projects" -- node D:/git/mcp-pilotage/dist/index.js

The Claude API usage folder

usage_ia_claude reads two kinds of files, dropped in by hand, and never modifies them:

• a monthly CSV export of tokens, named claude_api_tokens_YYYY_MM.csv (exported from the Claude console);

• a factures.csv file (invoices), kept by hand, because invoices mix subscription and metered usage and cannot be derived from token counts.

This repository's usage/ folder is ignored by git, so you can drop your files there without any risk of publishing them, or point elsewhere with PILOTAGE_DOSSIER_USAGE. With no files, the tool replies that it found no export and gives the expected folder.

Writing conventions

Two registers coexist on purpose in the code and in the answers:

• Identifiers stay ASCII: tool names (apercu_ecosysteme), parameter names (rafraichir, seulement_modifies), JSON result keys (depots_git, resultat_tronque). It is a stable serialization convention callers can rely on without worrying about accents.

• Everything meant to be read is proper, fully accented French: tool descriptions, parameter descriptions, titles and headers of the generated markdown, status and error messages, fallback values.

Text filters (filtre, famille) ignore accents and case: Ecriture et romans and Écriture et romans give the same result, but the returned value always keeps the correct spelling.

Content extracted from project files (purposes taken from a CLAUDE.md or a README) is returned as is, untouched.

Observed performance

Measured on a Windows machine with 20 projects (17 git repositories and 3 non-git folders):

node_modules, .git, dist, build, .astro, venv, __pycache__ and about twenty other folders are never walked.

Development

npm run dev                     # runs the sources directly via tsx
npm run build                   # compiles TypeScript to dist/
npm test                        # stdio MCP client that calls every tool and times it (needs npm run build first)
node tests/suivi-agents.mjs [minutes] [filter] [detail]   # calls only suivi_agents on the real logs
node tests/verif-accents.mjs    # checks accents and UTF-8 encoding

tests/client-test.mjs starts the compiled server, lists the tools and exercises each one with real parameters against this repository itself, including an error case (unknown project). It is the quickest way to check a change.

tests/verif-accents.mjs prints the full descriptions as a model receives them, counts accented characters, checks the code points of the generated markdown and verifies that source files are UTF-8 without BOM.

Code layout

src/
  index.ts            entry point, stdio transport, tool registration
  config.ts           configuration, environment variables, secret file patterns
  core/
    fichiers.ts       error-tolerant traversal and reads, home-made glob
    depots.ts         root scanning, cache, project lookup by name
    stack.ts          tech stack and family detection
    cerveau.ts        locating and reading context documents
    git.ts            read-only git status
    recherche.ts      cross-repository search, ripgrep with Node fallback
    usage.ts          reading and aggregating token exports and invoices
    agents.ts         Codex, Claude Code and Vibe logs (tail only), live processes
  outils/             MCP tool definitions
  utils/reponse.ts    response formatting and crash guard
tests/                MCP test client, suivi_agents probe, accent check

License

MIT, see LICENSE.

Author: François Menguy, fmenguy.fr.