pi-mcp-adapter : brancher des serveurs MCP sur Pi sans saturer la fenêtre de contexte
Token-efficient MCP adapter for Pi coding agent
En bref
- De quoi s’agit-il ?
- Un adaptateur TypeScript sous licence MIT qui remplace les définitions d'outils MCP par un unique outil proxy d'environ 200 tokens, avec démarrage paresseux des serveurs. Utile si vous accumulez les serveurs MCP dans Pi, inutile si vous n'en utilisez qu'un.
- À qui s’adresse-t-il ?
- À adopter si vous faites tourner plusieurs serveurs MCP dans Pi et que le budget de contexte est votre contrainte principale. À éviter si vous n'avez qu'un serveur ou si vous dépendez d'un hôte non pris en charge.
- Puis-je l’utiliser commercialement ?
- Oui. MIT est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 1 jour.
- En quel langage est-il écrit ?
- Principalement TypeScript, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le coût caché des définitions d'outils MCP
Le README pose le problème en une phrase : une seule définition de serveur MCP peut consommer plus de 10 000 tokens, et cette dépense est engagée que vous appeliez les outils ou non. Le raisonnement est attribué à Mario Zechner dans un billet intitulé why you might not need MCP, dont la conclusion, telle que résumée ici, est de se passer de MCP et d'écrire de petites CLI. L'adaptateur prend la position inverse sur la conclusion tout en acceptant le diagnostic : l'écosystème MCP contient des bases de données, des navigateurs et des API difficiles à remplacer par un script, mais le coût d'entrée en tokens n'est pas une fatalité. Le public visé est donc précis. Il s'agit de quelqu'un qui utilise déjà Pi comme agent de codage, qui a accumulé plusieurs serveurs MCP, et pour qui la fenêtre de contexte est une ressource mesurée. Si vous n'avez qu'un serveur et qu'il tient dans votre budget, l'adaptateur ajoute une couche d'indirection sans rien résoudre.
Un outil proxy à la place de dizaines de définitions
Le mécanisme central tient dans un seul outil nommé mcp. Au lieu d'exposer chaque fonction d'un serveur comme un outil distinct, l'adaptateur enregistre cet outil unique, décrit comme pesant environ 200 tokens, et laisse l'agent découvrir ce dont il a besoin à la demande. Le README montre la séquence en deux appels. D'abord une recherche, mcp({ search: "screenshot" }), qui renvoie le nom de l'outil correspondant avec ses paramètres, ici chrome_devtools_take_screenshot avec format en énumération png, jpeg, webp, fullPage en booléen. Ensuite l'exécution, mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } }). Le champ args accepte un objet JSON ou une chaîne JSON, l'objet étant présenté comme préférable lorsque le modèle le gère de façon fiable, la chaîne restant supportée pour les fournisseurs qui exigent des schémas plus simples. Deux appels remplacent donc 26 outils dans le contexte. Le point important est que la recherche et la description fonctionnent sur des métadonnées mises en cache, sans connexion active au serveur.
Démarrage paresseux et cache de métadonnées
Les serveurs sont lazy by default selon le README : ils ne se connectent pas avant que vous appeliez réellement l'un de leurs outils. C'est ce qui rend le coût réel proportionnel à l'usage plutôt qu'à la configuration. Le compromis est assumé et visible : l'adaptateur doit conserver un cache des métadonnées d'outils pour que la recherche et la description répondent sans connexion live. Cela implique un décalage possible entre le cache et l'état réel d'un serveur, notamment après une mise à jour du serveur lui-même. Le README signale d'ailleurs qu'après avoir modifié le drapeau disabled, il faut exécuter /reload pour que les surfaces d'outils enregistrées soient rafraîchies. Autrement dit, la cohérence du cache n'est pas automatique, elle dépend d'une action de l'utilisateur. C'est une limite de conception à garder en tête si vous modifiez souvent la liste de vos serveurs.
Installation et fichier de configuration minimal
L'installation passe par le gestionnaire de Pi : pi install npm:pi-mcp-adapter, suivi d'un redémarrage de Pi. Le README mentionne aussi un pont tiers, pi2dsh, pour exécuter l'adaptateur non modifié dans un environnement DeepSeek Harness. La configuration recommandée pour un projet est le fichier .mcp.json, avec une entrée mcpServers contenant par exemple command npx et args ["-y", "chrome-devtools-mcp@1.6.0"]. Pour un usage global, le chemin partagé est ~/.config/mcp/mcp.json. Si vous n'avez encore rien configuré, la commande /mcp setup propose de créer un fichier de projet ou global, d'ajouter un serveur connu ou d'inspecter ce que l'adaptateur a détecté. En terminal, pi-mcp-adapter init scanne les configurations propres à d'autres hôtes et ajoute les imports de compatibilité manquants dans le répertoire d'agent Pi, ~/.pi/agent/mcp.json par défaut, ou $PI_CODING_AGENT_DIR/mcp.json lorsque cette variable est définie. Le README précise que l'adaptateur lit automatiquement les fichiers MCP standard, sans configuration supplémentaire.
Six couches de configuration et une précédence à connaître
La partie la plus délicate du projet est l'ordre de résolution des fichiers. Le README en donne la liste, les entrées tardives gagnant : ~/.config/mcp/mcp.json, puis ~/.agents/mcp.json, puis ~/.agents/mcp/mcp.json, puis le mcp.json du répertoire d'agent Pi, puis .mcp.json, puis .pi/mcp.json. Les commandes /mcp disable <server> et /mcp enable <server> n'écrivent que le champ disabled dans .pi/mcp.json, la couche de plus haute précédence. Activer supprime le drapeau de projet lorsque les couches inférieures sont actives, ou écrit false lorsqu'il faut surcharger une source inférieure désactivée. Le fichier source n'est jamais réécrit et les identifiants ne sont jamais copiés. Une nuance importante : les configurations fournies en mémoire via createMcpAdapter({ config }) sont isolées et ne lisent ni n'écrivent cette surcharge de projet, ce qui rend ces commandes indisponibles dans ce mode. La découverte des configurations d'hôtes est désactivée par défaut, settings.hostConfigDiscovery valant "off". La valeur "prompt" permet une détection sans activation, "on" active la découverte de repli, et pi-mcp-adapter init --discover-host-configs fait la même chose en ligne de commande. Ces configurations d'hôte ont une précédence inférieure à toutes les sources partagées et propres à Pi, et la découverte ne lance jamais silencieusement des commandes depuis ces fichiers.
Plugins d'agent et ce que le README ne dit pas
L'adaptateur peut charger des serveurs MCP depuis des paquets Agent Plugins lorsque vous listez des répertoires dans settings.agentPluginPaths, par exemple ./plugins/acme-tools. Chaque répertoire doit contenir un plugin.json valide conforme à Agent Plugins 1.0. Le texte fourni s'arrête au milieu de cette section, donc tout ce qui suit concernant les plugins n'est pas vérifiable ici. Plus généralement, le README ne documente pas de politique de compatibilité entre versions de l'adaptateur et versions des serveurs MCP, ni de procédure de migration entre les versions 2.31.0, 2.32.0 et 2.32.1 publiées en août et septembre 2026. Le rythme de publication est rapide, trois versions en une semaine environ, ce qui suggère un projet actif mais aussi une surface mouvante. La licence est MIT, ce qui autorise la réutilisation et la redistribution sous réserve de conserver l'avis de copyright et le texte de licence. Ce n'est pas un avis juridique : si vous redistribuez l'adaptateur dans un produit, faites vérifier les obligations de mention par votre service compétent.
Face à une CLI maison
L'alternative réelle n'est pas un autre adaptateur, c'est la recommandation d'origine du billet cité : écrire de petites CLI et les exposer à l'agent comme des commandes. La différence d'approche est nette. Une CLI maison ne coûte que la définition de l'outil que vous écrivez, vous contrôlez exactement son schéma, et il n'y a ni cache de métadonnées à rafraîchir ni couche de précédence entre six fichiers. En échange, vous perdez l'accès aux serveurs MCP existants, vous devez maintenir vous-même l'authentification et la gestion d'erreurs, et chaque nouvel usage demande du code. pi-mcp-adapter prend le pari inverse : garder l'écosystème MCP intact et déplacer l'effort vers une résolution de configuration plus complexe. Le choix dépend donc de ce que vous possédez déjà. Si vos serveurs MCP sont un navigateur et une base de données que vous appelez tous les jours, la CLI maison demande plus de travail que l'adaptateur. Si vous appelez un seul outil une fois par semaine, l'adaptateur est une dépendance supplémentaire pour un gain de contexte marginal.
Conclusion éditoriale
À adopter si vous faites tourner plusieurs serveurs MCP dans Pi et que le budget de contexte est votre contrainte principale. À éviter si vous n'avez qu'un serveur ou si vous dépendez d'un hôte non pris en charge. Avant d'installer, vérifiez la précédence de vos fichiers MCP existants et confirmez que settings.hostConfigDiscovery est bien à "off" par défaut, car aucun fichier d'hôte n'est lu sans action explicite.
Notes de la communauté