Construire le Code Mode pour les API avec MCP et Workers

Bonjour et bienvenue ! 👋

Cette série prolonge de manière concrète l'article Code Mode, deux outils et un MCP peuvent préserver le contexte de votre LLM. Celui-ci présentait l'idée suivante : au lieu de demander à un modèle d'orchestrer chaque appel d'outil dépendant, laissons-le écrire cette orchestration sous forme de code et renvoyer uniquement le résultat nécessaire à sa prochaine décision.

Ici, nous allons construire cette approche étape par étape. Nous commencerons par une petite transformation de fichier en local, puis nous passerons à une API décrite avec OpenAPI avant de remplacer l'évaluateur local de confiance basé sur le constructeur Function par un environnement d'exécution isolé. Nous obtiendrons un serveur MCP exécutable en local, capable de rechercher dans la spécification d'une API et d'exécuter une requête ciblée vers cette API.

Les principes fondamentaux de MCP sortent du cadre de cette série. Si vous avez besoin d'une introduction au protocole ou à la relation entre un Agent IA et un serveur MCP, commencez par Agents IA et serveur MCP au service du web agentique, en particulier son article sur le serveur MCP.

Tout au long de la série, le modèle génère des appels d'outils ou du code, le client MCP ou Agent exécute la boucle du modèle et le serveur MCP fournit les capacités. Il faut bien distinguer ces rôles : l'hôte, et non le code généré, définit les capacités disponibles.

L'idée centrale est simple. Avec des outils MCP directs, le modèle doit appeler un outil, recevoir l'intégralité du résultat intermédiaire, puis utiliser ce résultat pour décider comment appeler l'outil suivant. Avec le Code Mode, le modèle écrit l'orchestration sous forme de code. Ce code accède aux capacités dont il a besoin dans l'environnement d'exécution, et le modèle reçoit uniquement le résultat final souhaité pour poursuivre son travail.

Le Code Mode n'est pas toujours le bon choix. Les outils MCP directs restent plus simples pour les actions courtes et évidentes. L'environnement d'exécution supplémentaire devient utile lorsqu'une tâche comporte des appels dépendants, nécessite un traitement local des données ou doit parcourir une API vaste et évolutive. C'est par exemple le cas d'une spécification OpenAPI qui peut dépasser la fenêtre de contexte du modèle.

Au fil de cette série, nous allons :

1. Au-delà d'un appel d'outil à la fois : découvrir le Code Mode : construire deux outils Drive directs autour d'un fichier Markdown de test et observer comment l'intégralité de son contenu traverse le contexte du modèle avant l'appel d'outil suivant.
2. Laisser le modèle orchestrer les outils dans un environnement local : remplacer les deux outils directs par un outil code générique, exposer une façade Drive typée et introduire l'interface de l'exécuteur que les parties suivantes remplaceront. L'évaluateur local basé sur le constructeur Function est volontairement un raccourci réservé au développement de confiance, et non un bac à sable de production.
3. Rechercher dans une spécification OpenAPI sans remplir le contexte : conserver le document OpenAPI dans le serveur, résoudre ses références $ref locales et laisser le code généré effectuer ses recherches dans une façade de types compacte au lieu de renvoyer toute la spécification au modèle.
4. Appeler des API avec le Code Mode et ne renvoyer que l'essentiel : ajouter un outil execute distinct avec une fonction api.request() contrôlée par l'hôte. Nous validerons les options de la requête, appellerons l'API MarketHub locale utilisée pour les tests et renverrons une projection ciblée plutôt que la réponse complète de l'API.
5. Remplacer l'évaluateur par des Workers Cloudflare isolés : remplacer uniquement l'exécuteur par de nouveaux Workers dynamiques. La recherche s'exécutera sans accès sortant, tandis que les appels passeront par une passerelle avec une liste d'autorisations. Les identifiants resteront hors du code généré. Nous aborderons également les limites des résultats, les limites de ressources et les délais imposés par l'hôte.

Le dépôt associé, code-mode, est un manuel exécutable pour cette série. Chaque article dispose d'une branche qui représente un état complet, d'une petite évaluation et d'un diff ciblé par rapport à l'étape précédente. Je vous recommande d'extraire une branche et d'étudier l'implémentation pour mieux comprendre les concepts, car les articles ne couvriront pas chaque détail.