@imenam/mcp-http-gateway 2.0.14 → 2.0.15

package/mcp-mode.js

@@ -1,647 +1,722 @@
-#!/usr/bin/env node
-import 'dotenv/config';
-import fs from 'fs';
-import path from 'path';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import {
-  ListToolsRequestSchema,
-  CallToolRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js';
-
-const GATEWAY_URL = process.env.GATEWAY_URL?.replace(/\/$/, '');
-if (!GATEWAY_URL) {
-  console.error('[mcp-mode] GATEWAY_URL environment variable is required');
-  process.exit(1);
-}
-
-// Token porteur optionnel. Utile quand le gateway n'est pas joint en direct mais à
-// travers un frontal qui authentifie (hub mcp-gateway-manager, reverse-proxy…).
-//
-// ATTENTION — `import 'dotenv/config'` ci-dessus charge le `.env` du **répertoire
-// courant de l'agent**, pas celui du gateway. dotenv n'écrase jamais une variable
-// déjà présente dans l'environnement : le bloc `env` de la config MCP l'emporte
-// donc toujours. En revanche, si le bloc `env` ne définit PAS GATEWAY_TOKEN, un
-// `.env` traînant dans le projet de l'agent peut en fournir un. C'est le
-// comportement historique (GATEWAY_URL est dans le même cas), on ne le change pas.
-//
-// Le token n'est JAMAIS journalisé, même tronqué.
-const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN?.trim() || undefined;
-
-/**
- * En-têtes d'un appel sortant du relais.
- *
- * Sans GATEWAY_TOKEN, rien n'est ajouté et l'appel part exactement comme avant —
- * la rétrocompatibilité avec les déploiements existants est stricte.
- */
-function gatewayHeaders(base) {
-  const headers = { ...base };
-  if (GATEWAY_TOKEN) headers.Authorization = `Bearer ${GATEWAY_TOKEN}`;
-  return Object.keys(headers).length > 0 ? headers : undefined;
-}
-
-/** Le seul point de sortie HTTP du relais : tout appel au gateway passe par ici. */
-function gatewayFetch(path, init = {}) {
-  const headers = gatewayHeaders(init.headers);
-  return fetch(`${GATEWAY_URL}${path}`, headers ? { ...init, headers } : init);
-}
-
-/** Un refus d'authentification mérite mieux qu'un `HTTP 401` nu. */
-function isAuthStatus(status) {
-  return status === 401 || status === 403;
-}
-
-function authErrorText(status) {
-  return GATEWAY_TOKEN
-    ? `Accès refusé par le gateway (HTTP ${status}) : le GATEWAY_TOKEN fourni est invalide, ` +
-        `révoqué, ou ne correspond pas à cette gateway. Régénérez-le puis mettez à jour la ` +
-        `variable GATEWAY_TOKEN dans la configuration de ce serveur MCP.`
-    : `Accès refusé par le gateway (HTTP ${status}) : aucun GATEWAY_TOKEN n'est défini alors ` +
-        `que ${GATEWAY_URL} en exige un. Ajoutez GATEWAY_TOKEN dans le bloc « env » de la ` +
-        `configuration de ce serveur MCP.`;
-}
-
-/** Message d'erreur d'un appel outil — inchangé hors 401/403. */
-function gatewayErrorText(status, body) {
-  return isAuthStatus(status) ? authErrorText(status) : `Gateway error ${status}: ${body}`;
-}
-
-/** Message d'une erreur relancée — inchangé hors 401/403. */
-function gatewayThrowText(status) {
-  return isAuthStatus(status) ? authErrorText(status) : `HTTP ${status}`;
-}
-
-// --- Fichiers : le relais lit, l'agent ne fait que nommer ---
-//
-// Le relais tourne sur la machine de l'AGENT ; le MCP, lui, tourne sur la machine du
-// gateway. Un chemin de fichier transmis tel quel ne veut donc rien dire à l'arrivée :
-// le MCP cherche le fichier chez lui et ne le trouve pas.
-//
-// La règle : dès qu'un outil distant déclare une paire `<x>_path` / `<x>_content`, le
-// relais lit le fichier ICI, l'encode en base64 et envoie le CONTENU. Le paramètre
-// `<x>_content` (et `<x>_name`, s'il existe) est retiré du schéma publié à l'agent :
-// l'agent ne fournit qu'un chemin, et n'a aucun arbitrage à faire.
-//
-// Rien ne se déclenche sur un outil qui n'expose pas cette paire : un `output_path`
-// seul reste un chemin, interprété côté gateway comme avant.
-//
-// Le chemin vient de l'agent : il n'est donc PAS digne de confiance. Trois garde-fous,
-// tous configurables dans le bloc « env » de ce serveur MCP :
-//
-//   GATEWAY_INLINE_ROOTS       Dossiers dont un fichier peut sortir. C'est l'interrupteur :
-//                              non renseigné, le relais ne lit aucun fichier et l'appel
-//                              ÉCHOUE — laisser filer le chemin ferait chercher le fichier
-//                              au MCP sur la machine du gateway, où il trouverait un
-//                              homonyme ou rien du tout, sans rien signaler.
-//                              Séparateur : « ; » sous Windows, « : » ailleurs.
-//   GATEWAY_INLINE_EXTENSIONS  Extensions autorisées (défaut : toutes). Les racines restent
-//                              le vrai garde-fou.
-//   GATEWAY_INLINE_MAX_BYTES   Taille maximale d'un fichier transmis (défaut : 8 Mio).
-//
-// Chaque fichier réellement transmis laisse une ligne sur stderr : ce que l'agent fait
-// sortir de la machine doit être lisible dans le journal de l'agent.
-
-/** Les racines autorisées, résolues une fois pour toutes au démarrage. */
-const INLINE_ROOTS = (process.env.GATEWAY_INLINE_ROOTS ?? '')
-  .split(path.delimiter)
-  .map((entry) => entry.trim())
-  .filter(Boolean)
-  .map((entry) => {
-    const resolved = path.resolve(entry);
-    try {
-      return fs.realpathSync(resolved);
-    } catch {
-      console.error(`[mcp-mode] GATEWAY_INLINE_ROOTS : dossier introuvable, ignoré — ${resolved}`);
-      return null;
-    }
-  })
-  .filter(Boolean);
-
-const INLINE_EXTENSIONS = (process.env.GATEWAY_INLINE_EXTENSIONS ?? '*')
-  .split(',')
-  .map((entry) => entry.trim().toLowerCase())
-  .filter(Boolean);
-
-const INLINE_ANY_EXTENSION = INLINE_EXTENSIONS.includes('*');
-
-// 8 Mio : encodé en base64 le corps pèse ~10,7 Mio, sous le plafond de 16 Mio que le hub
-// applique quand il journalise les corps de requête.
-const INLINE_MAX_BYTES =
-  Number.parseInt(process.env.GATEWAY_INLINE_MAX_BYTES ?? '', 10) || 8 * 1024 * 1024;
-
-const INLINE_FILES = INLINE_ROOTS.length > 0;
-
-if (INLINE_FILES) {
-  console.error(
-    `[mcp-mode] Transmission du contenu des fichiers activée depuis : ${INLINE_ROOTS.join(', ')} ` +
-      `(extensions : ${INLINE_ANY_EXTENSION ? 'toutes' : INLINE_EXTENSIONS.join(' ')})`
-  );
-}
-
-/** Le fichier est-il à l'intérieur d'une racine autorisée ? Liens symboliques résolus. */
-function insideAllowedRoot(realPath) {
-  return INLINE_ROOTS.some((root) => {
-    const rel = path.relative(root, realPath);
-    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
-  });
-}
-
-/** Les paires `<x>_path` / `<x>_content` déclarées par le schéma d'un outil. */
-function inlinablePairs(inputSchema) {
-  const props = inputSchema?.properties;
-  if (!props) return [];
-  return Object.keys(props)
-    .filter((key) => key.endsWith('_content') && `${key.slice(0, -'_content'.length)}_path` in props)
-    .map((contentProp) => {
-      const stem = contentProp.slice(0, -'_content'.length);
-      return {
-        pathProp: `${stem}_path`,
-        contentProp,
-        nameProp: `${stem}_name` in props ? `${stem}_name` : null,
-      };
-    });
-}
-
-/** Le schéma tel que l'agent doit le voir : sans les paramètres que le relais remplit. */
-function schemaForAgent(inputSchema) {
-  const inbound = inlinablePairs(inputSchema);
-  const pairs = [...inbound, ...deliverablePairs(inputSchema)];
-  if (pairs.length === 0) return inputSchema;
-
-  const hidden = new Set(
-    pairs.flatMap((p) => [p.contentProp, p.nameProp, p.relayProp].filter(Boolean))
-  );
-  const properties = Object.fromEntries(
-    Object.entries(inputSchema.properties).filter(([key]) => !hidden.has(key))
-  );
-
-  // Le caractère obligatoire d'un `<x>_path` est celui que le MCP déclare, dans les deux
-  // sens. Un chemin optionnel veut dire quelque chose : à l'aller, que l'outil accepte
-  // aussi sa donnée autrement (un texte passé en ligne, par exemple) ; au retour, qu'il
-  // sait quoi faire sans destination. Sans `<x>_path`, le relais ne fait rien.
-  const required = (inputSchema.required ?? []).filter((key) => !hidden.has(key));
-
-  return { ...inputSchema, properties, required };
-}
-
-/**
- * Remplace chaque `<x>_path` par le contenu du fichier lu sur la machine de l'agent.
- *
- * Tout refus est explicite : l'agent doit savoir pourquoi son fichier ne part pas,
- * sans avoir à deviner s'il s'agit d'une absence, d'un type ou d'une interdiction.
- */
-function inlineFileArgs(inputSchema, args = {}, label = '') {
-  const pairs = inlinablePairs(inputSchema);
-  if (pairs.length === 0) return args;
-
-  const out = { ...args };
-  for (const { pathProp, contentProp, nameProp } of pairs) {
-    const filePath = out[pathProp];
-    if (typeof filePath !== 'string' || filePath === '') continue;
-
-    // Un outil qui déclare la paire attend le CONTENU : il tourne sur la machine du
-    // gateway, où le chemin de l'agent ne désigne rien — ou pire, désigne un homonyme
-    // qu'il traiterait sans broncher. Laisser filer le chemin serait une dégradation
-    // silencieuse ; on refuse en nommant la variable à renseigner.
-    if (!INLINE_FILES) {
-      throw new Error(
-        `Transmission de fichier impossible : aucun dossier de lecture autorisé. L'outil ` +
-          `attend le contenu du fichier (paramètre ${pathProp}), mais il tourne sur la machine ` +
-          `du gateway et ne peut pas lire la vôtre. Renseignez GATEWAY_INLINE_ROOTS dans le ` +
-          `bloc « env » de la configuration de ce serveur MCP.`
-      );
-    }
-
-    const resolved = path.resolve(filePath);
-
-    // realpath avant tout contrôle : sans ça, un lien symbolique placé dans une racine
-    // autorisée ferait sortir n'importe quel fichier de la machine.
-    let real;
-    let stat;
-    try {
-      real = fs.realpathSync(resolved);
-      stat = fs.statSync(real);
-    } catch {
-      throw new Error(
-        `Fichier introuvable sur la machine de l'agent : ${resolved} (paramètre ${pathProp}).`
-      );
-    }
-    if (!stat.isFile()) {
-      throw new Error(`${resolved} n'est pas un fichier (paramètre ${pathProp}).`);
-    }
-    if (!insideAllowedRoot(real)) {
-      throw new Error(
-        `Lecture refusée : ${real} est hors des dossiers autorisés (${INLINE_ROOTS.join(', ')}). ` +
-          `Déplacez le fichier dans l'un d'eux, ou ajoutez son dossier à GATEWAY_INLINE_ROOTS ` +
-          `dans la configuration de ce serveur MCP.`
-      );
-    }
-    const ext = path.extname(real).toLowerCase();
-    if (!INLINE_ANY_EXTENSION && !INLINE_EXTENSIONS.includes(ext)) {
-      throw new Error(
-        `Lecture refusée : l'extension « ${ext || '(aucune)'} » n'est pas autorisée ` +
-          `(autorisées : ${INLINE_EXTENSIONS.join(' ')}, via GATEWAY_INLINE_EXTENSIONS).`
-      );
-    }
-    if (stat.size > INLINE_MAX_BYTES) {
-      throw new Error(
-        `Fichier trop volumineux à transmettre : ${real} pèse ${stat.size} octets, ` +
-          `la limite est de ${INLINE_MAX_BYTES} (GATEWAY_INLINE_MAX_BYTES).`
-      );
-    }
-
-    out[contentProp] = fs.readFileSync(real).toString('base64');
-    if (nameProp) out[nameProp] = path.basename(real);
-    delete out[pathProp];
-
-    console.error(
-      `[mcp-mode] Fichier transmis${label ? ` à ${label}` : ''} : ${real} (${stat.size} octets)`
-    );
-  }
-  return out;
-}
-
-// --- Fichiers : le MCP produit, le relais écrit ---
-//
-// Le sens retour, symétrique du précédent. `inlineFileArgs` ne réécrit que les arguments
-// à l'aller ; un fichier produit par le MCP, lui, n'a aucun moyen d'atteindre la machine
-// de l'agent : le protocole n'offre au serveur aucune primitive pour y écrire.
-//
-// La règle : dès qu'un outil distant déclare une paire `<x>_path` / `<x>_relay`, le relais
-// retient le chemin, annonce sa présence au MCP en posant `<x>_relay` à true, et ne
-// transmet PAS `<x>_path` — qui ne désignerait rien à l'arrivée. Le MCP répond alors avec
-// le contenu du fichier, que le relais écrit ICI, à l'emplacement retenu.
-//
-// Le contenu ne ressort JAMAIS vers l'agent : le relais le retire du résultat, qu'il ait
-// réussi ou non à écrire. Un fichier de 8 Mio encodé en base64 n'a rien à faire dans le
-// contexte d'un agent, et rien ne justifie de l'y déverser « au cas où » : l'appel échoue,
-// le fichier est perdu, l'agent recommence.
-//
-// Sans relais dans la chaîne — MCP lancé en stdio à côté de l'agent — `<x>_relay` reste
-// absent : les deux machines n'en font qu'une, et le MCP écrit lui-même à `<x>_path`.
-//
-// Écrire est plus dangereux que lire : la fonction a donc sa propre racine autorisée,
-// et n'hérite pas de celle de la lecture.
-//
-//   GATEWAY_INLINE_WRITE_ROOTS       Dossiers où un fichier peut être déposé. C'est
-//                                    l'interrupteur : non renseigné, aucune livraison
-//                                    n'a lieu et l'appel échoue en le disant.
-//   GATEWAY_INLINE_WRITE_EXTENSIONS  Extensions autorisées (défaut : toutes). Les racines
-//                                    restent le vrai garde-fou.
-//   GATEWAY_INLINE_MAX_BYTES         Plafond de taille, partagé avec la lecture.
-
-const WRITE_ROOTS = (process.env.GATEWAY_INLINE_WRITE_ROOTS ?? '')
-  .split(path.delimiter)
-  .map((entry) => entry.trim())
-  .filter(Boolean)
-  .map((entry) => {
-    const resolved = path.resolve(entry);
-    try {
-      return fs.realpathSync(resolved);
-    } catch {
-      console.error(`[mcp-mode] GATEWAY_INLINE_WRITE_ROOTS : dossier introuvable, ignoré — ${resolved}`);
-      return null;
-    }
-  })
-  .filter(Boolean);
-
-const WRITE_EXTENSIONS = (process.env.GATEWAY_INLINE_WRITE_EXTENSIONS ?? '*')
-  .split(',')
-  .map((entry) => entry.trim().toLowerCase())
-  .filter(Boolean);
-
-const WRITE_ANY_EXTENSION = WRITE_EXTENSIONS.includes('*');
-
-if (WRITE_ROOTS.length > 0) {
-  console.error(
-    `[mcp-mode] Écriture des fichiers reçus activée vers : ${WRITE_ROOTS.join(', ')} ` +
-      `(extensions : ${WRITE_ANY_EXTENSION ? 'toutes' : WRITE_EXTENSIONS.join(' ')})`
-  );
-}
-
-/** Les paires `<x>_path` / `<x>_relay` déclarées par le schéma d'un outil. */
-function deliverablePairs(inputSchema) {
-  const props = inputSchema?.properties;
-  if (!props) return [];
-  return Object.keys(props)
-    .filter((key) => key.endsWith('_relay') && `${key.slice(0, -'_relay'.length)}_path` in props)
-    .map((relayProp) => {
-      const stem = relayProp.slice(0, -'_relay'.length);
-      return {
-        pathProp: `${stem}_path`,
-        relayProp,
-        overwriteProp: `${stem}_overwrite` in props ? `${stem}_overwrite` : null,
-      };
-    });
-}
-
-/**
- * Le chemin de destination, résolu et vérifié contre les racines autorisées.
- *
- * `destDir` est toujours un dossier et `fileName` le nom que le MCP donne au fichier :
- * le relais ne renomme jamais. Passer `fileName` vide ne vérifie que le dossier — ce
- * qu'on fait à l'aller, pour échouer avant d'avoir fait voyager les octets pour rien.
- *
- * Le fichier n'existe pas encore : impossible d'appeler `realpath` dessus. On résout
- * donc les liens du plus proche ancêtre existant, sans quoi un lien symbolique déposé
- * dans une racine autorisée permettrait d'écrire n'importe où sur la machine.
- */
-function resolveWriteTarget(destDir, fileName = '') {
-  const resolved = fileName
-    ? path.resolve(destDir, path.basename(fileName))
-    : path.resolve(destDir);
-
-  let existing = path.dirname(resolved);
-  const trailing = [path.basename(resolved)];
-  while (!fs.existsSync(existing)) {
-    const parent = path.dirname(existing);
-    if (parent === existing) {
-      throw new Error(`Destination inatteignable sur la machine de l'agent : ${resolved}.`);
-    }
-    trailing.unshift(path.basename(existing));
-    existing = parent;
-  }
-
-  const real = path.join(fs.realpathSync(existing), ...trailing);
-
-  const inside = WRITE_ROOTS.some((root) => {
-    const rel = path.relative(root, real);
-    // Un dossier de destination PEUT être la racine elle-même ; un fichier, non.
-    if (rel === '') return fileName === '';
-    return !rel.startsWith('..') && !path.isAbsolute(rel);
-  });
-  if (!inside) {
-    throw new Error(
-      `Écriture refusée : ${real} est hors des dossiers autorisés (${WRITE_ROOTS.join(', ')}). ` +
-        `Choisissez une destination dans l'un d'eux, ou ajoutez son dossier à ` +
-        `GATEWAY_INLINE_WRITE_ROOTS dans la configuration de ce serveur MCP.`
-    );
-  }
-
-  const ext = path.extname(real).toLowerCase();
-  if (fileName && !WRITE_ANY_EXTENSION && !WRITE_EXTENSIONS.includes(ext)) {
-    throw new Error(
-      `Écriture refusée : l'extension « ${ext || '(aucune)'} » n'est pas autorisée ` +
-        `(autorisées : ${WRITE_EXTENSIONS.join(' ')}, via GATEWAY_INLINE_WRITE_EXTENSIONS).`
-    );
-  }
-
-  return real;
-}
-
-/**
- * Retire `<x>_path` des arguments et pose `<x>_relay`, pour que le MCP renvoie le
- * contenu au lieu de tenter une écriture qui atterrirait sur SA machine.
- */
-function prepareDeliveries(inputSchema, args = {}) {
-  const pairs = deliverablePairs(inputSchema);
-  if (pairs.length === 0) return { args, deliveries: [] };
-
-  const out = { ...args };
-  const deliveries = [];
-  for (const { pathProp, relayProp, overwriteProp } of pairs) {
-    const destPath = out[pathProp];
-    if (typeof destPath !== 'string' || destPath === '') continue;
-
-    if (WRITE_ROOTS.length === 0) {
-      throw new Error(
-        `Livraison de fichier impossible : aucun dossier d'écriture autorisé. Le MCP tourne ` +
-          `sur la machine du gateway et ne peut pas écrire sur la vôtre. Renseignez ` +
-          `GATEWAY_INLINE_WRITE_ROOTS dans le bloc « env » de la configuration de ce ` +
-          `serveur MCP avec le ou les dossiers où déposer les fichiers reçus.`
-      );
-    }
-
-    // Vérification du dossier seul : le nom du fichier n'est connu qu'au retour.
-    resolveWriteTarget(destPath);
-    deliveries.push({
-      destDir: destPath,
-      overwrite: overwriteProp ? out[overwriteProp] === true : false,
-    });
-    out[relayProp] = true;
-    delete out[pathProp];
-  }
-  return { args: out, deliveries };
-}
-
-/**
- * Écrit les fichiers renvoyés par le MCP et purge le résultat de leur contenu.
- *
- * Le contenu est retiré dans tous les cas, y compris en cas d'échec d'écriture : c'est
- * la seule garantie qu'un base64 ne finira jamais dans le contexte de l'agent.
- */
-function applyDeliveries(result, deliveries, label = '') {
-  if (deliveries.length === 0) return result;
-
-  const blocks = Array.isArray(result?.content) ? result.content : [];
-  const blobs = blocks.filter((b) => b?.type === 'resource' && typeof b.resource?.blob === 'string');
-  const kept = blocks.filter((b) => !blobs.includes(b));
-
-  if (result?.isError) return { ...result, content: kept.length > 0 ? kept : blocks };
-
-  const notes = [];
-  deliveries.forEach((delivery, i) => {
-    const blob = blobs[i];
-    if (!blob) {
-      notes.push(`Aucun contenu renvoyé par le MCP pour ${delivery.destDir} : rien n'a été écrit.`);
-      return;
-    }
-    let target = delivery.destDir;
-    try {
-      const fileName = blob.resource.name || path.basename(new URL(blob.resource.uri).pathname);
-      if (!fileName) throw new Error("le MCP n'a pas nommé le fichier renvoyé");
-      target = resolveWriteTarget(delivery.destDir, fileName);
-
-      const data = Buffer.from(blob.resource.blob, 'base64');
-      if (data.length > INLINE_MAX_BYTES) {
-        throw new Error(
-          `fichier trop volumineux : ${data.length} octets, la limite est de ` +
-            `${INLINE_MAX_BYTES} (GATEWAY_INLINE_MAX_BYTES)`
-        );
-      }
-      if (!delivery.overwrite && fs.existsSync(target)) {
-        throw new Error('la destination existe déjà');
-      }
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, data);
-      notes.push(`Fichier écrit : ${target} (${data.length} octets).`);
-      console.error(
-        `[mcp-mode] Fichier reçu${label ? ` de ${label}` : ''} : ${target} (${data.length} octets)`
-      );
-    } catch (err) {
-      notes.push(`Échec de l'écriture dans ${target} : ${err.message}.`);
-    }
-  });
-
-  const failed = notes.some((note) => note.startsWith('Échec') || note.startsWith('Aucun'));
-  return {
-    ...result,
-    content: [...kept, { type: 'text', text: notes.join('\n') }],
-    ...(failed ? { isError: true } : {}),
-  };
-}
-
-/** Schémas des outils d'une route, mis en cache — nécessaires pour `call_tool`. */
-const routeSchemas = new Map();
-
-async function toolSchema(route, toolName) {
-  // Toujours récupéré, même si l'inlining en lecture est désactivé : c'est le schéma qui
-  // révèle une paire `<x>_path` / `<x>_relay`, et la manquer ferait repartir un chemin
-  // de destination vers le MCP distant, qui écrirait alors sur SA machine sans le dire.
-  if (!routeSchemas.has(route)) {
-    try {
-      const res = await gatewayFetch(`${route}/tools`);
-      const list = res.ok ? await res.json() : [];
-      routeSchemas.set(route, new Map(list.map((t) => [t.name, t.inputSchema])));
-    } catch {
-      routeSchemas.set(route, new Map());
-    }
-  }
-  return routeSchemas.get(route).get(toolName) ?? null;
-}
-
-// --- MCP Server ---
-
-// Le gateway (mode serveur HTTP) peut être paramétré (EXPOSE_AT_AGENT_STARTUP) pour
-// pré-exposer les outils de certains MCP directement à l'agent. La config vit uniquement
-// sur le serveur : ce bridge se contente de récupérer ces outils et de les publier, de
-// façon transparente. En cas d'échec (ancien gateway sans la route, gateway protégé par
-// OAuth, etc.), on continue sans pré-exposition.
-async function fetchProxyTools() {
-  try {
-    const res = await gatewayFetch('/startup-exposition');
-    if (!res.ok) {
-      // La pré-exposition reste optionnelle : on n'interrompt pas le démarrage.
-      // Mais un 401/403 ici annonce que TOUS les appels seront refusés — le dire
-      // maintenant évite de chercher plus tard. Sans le token, évidemment.
-      if (isAuthStatus(res.status)) console.error(`[mcp-mode] ${authErrorText(res.status)}`);
-      return [];
-    }
-    const { proxyTools } = await res.json();
-    return proxyTools ?? [];
-  } catch {
-    return [];
-  }
-}
-
-const proxyTools = await fetchProxyTools();
-if (proxyTools.length) {
-  console.error(`[mcp-mode] ${proxyTools.length} proxy tool(s) exposed directly from gateway`);
-}
-
-const server = new Server(
-  { name: 'mcp-http-gateway-mcp', version: '1.0.0' },
-  { capabilities: { tools: {} } }
-);
-
-const tools = [
-  {
-    name: 'list_mcps',
-    description: 'List all MCPs available on the gateway with their route and description.',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'list_tools',
-    description: 'List all tools available for a given MCP route.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        route: { type: 'string', description: 'MCP route as returned by list_mcps (e.g. "/documentor")' },
-      },
-      required: ['route'],
-    },
-  },
-  {
-    name: 'call_tool',
-    description: 'Call a tool on a given MCP route.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        route:     { type: 'string', description: 'MCP route (e.g. "/documentor")' },
-        tool_name: { type: 'string', description: 'Tool name to call' },
-        arguments: { type: 'object', description: 'Arguments to pass to the tool' },
-      },
-      required: ['route', 'tool_name'],
-    },
-  },
-];
-
-const proxyIndex = new Map(proxyTools.map(t => [t.name, t]));
-const allTools = [
-  ...tools,
-  ...proxyTools.map(({ name, description, inputSchema }) => ({
-    name,
-    description,
-    inputSchema: schemaForAgent(inputSchema),
-  })),
-];
-
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }));
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args = {} } = request.params;
-
-  try {
-    const proxy = proxyIndex.get(name);
-    if (proxy) {
-      const label = `${proxy.route}/${proxy.toolName}`;
-      const { args: outArgs, deliveries } = prepareDeliveries(proxy.inputSchema, args ?? {});
-      const res = await gatewayFetch(`${proxy.route}/tools/${proxy.toolName}`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(inlineFileArgs(proxy.inputSchema, outArgs, label)),
-      });
-      if (!res.ok) {
-        const text = await res.text();
-        return { content: [{ type: 'text', text: gatewayErrorText(res.status, text) }], isError: true };
-      }
-      return applyDeliveries(await res.json(), deliveries, label);
-    }
-
-    if (name === 'list_mcps') {
-      const res = await gatewayFetch('/mcp-definitions');
-      if (!res.ok) throw new Error(gatewayThrowText(res.status));
-      const definitions = await res.json();
-      const text = definitions
-        .map(m => `- ${m.id} (route: ${m.route})${m.description ? ` — ${m.description}` : ''}`)
-        .join('\n');
-      return { content: [{ type: 'text', text }] };
-    }
-
-    if (name === 'list_tools') {
-      const res = await gatewayFetch(`${args.route}/tools`);
-      if (!res.ok) throw new Error(gatewayThrowText(res.status));
-      const toolsList = await res.json();
-      routeSchemas.set(args.route, new Map(toolsList.map((t) => [t.name, t.inputSchema])));
-      // Même règle que pour les outils pré-exposés : l'agent ne doit pas découvrir
-      // les paramètres de contenu, c'est le relais qui les remplit.
-      const text = JSON.stringify(
-        toolsList.map((t) => (t.inputSchema ? { ...t, inputSchema: schemaForAgent(t.inputSchema) } : t))
-      );
-      return { content: [{ type: 'text', text }] };
-    }
-
-    if (name === 'call_tool') {
-      const schema = await toolSchema(args.route, args.tool_name);
-      const label = `${args.route}/${args.tool_name}`;
-      const { args: outArgs, deliveries } = prepareDeliveries(schema, args.arguments ?? {});
-      const res = await gatewayFetch(`${args.route}/tools/${args.tool_name}`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(inlineFileArgs(schema, outArgs, label)),
-      });
-      if (!res.ok) {
-        const text = await res.text();
-        return { content: [{ type: 'text', text: gatewayErrorText(res.status, text) }], isError: true };
-      }
-      return applyDeliveries(await res.json(), deliveries, label);
-    }
-
-    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
-  } catch (err) {
-    return { content: [{ type: 'text', text: `Request failed: ${err.message}` }], isError: true };
-  }
-});
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
+#!/usr/bin/env node
+import 'dotenv/config';
+import fs from 'fs';
+import path from 'path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  EXEC_ARG, MAX_EXEC_ROUNDS, parseExecRoutes, normalizeRoute, execAnnouncement, execRequestOf, runExecRequest,
+} from './gateway-exec.js';
+import {
+  WATCH_ARG, declaresWatch, watchAnnouncement, watchSpecOf, armWatch, removeOwnWatches, pruneOrphanWatches,
+} from './gateway-watch.js';
+
+const GATEWAY_URL = process.env.GATEWAY_URL?.replace(/\/$/, '');
+if (!GATEWAY_URL) {
+  console.error('[mcp-mode] GATEWAY_URL environment variable is required');
+  process.exit(1);
+}
+
+// Token porteur optionnel. Utile quand le gateway n'est pas joint en direct mais à
+// travers un frontal qui authentifie (hub mcp-gateway-manager, reverse-proxy…).
+//
+// ATTENTION — `import 'dotenv/config'` ci-dessus charge le `.env` du **répertoire
+// courant de l'agent**, pas celui du gateway. dotenv n'écrase jamais une variable
+// déjà présente dans l'environnement : le bloc `env` de la config MCP l'emporte
+// donc toujours. En revanche, si le bloc `env` ne définit PAS GATEWAY_TOKEN, un
+// `.env` traînant dans le projet de l'agent peut en fournir un. C'est le
+// comportement historique (GATEWAY_URL est dans le même cas), on ne le change pas.
+//
+// Le token n'est JAMAIS journalisé, même tronqué.
+const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN?.trim() || undefined;
+
+/**
+ * En-têtes d'un appel sortant du relais.
+ *
+ * Sans GATEWAY_TOKEN, rien n'est ajouté et l'appel part exactement comme avant —
+ * la rétrocompatibilité avec les déploiements existants est stricte.
+ */
+function gatewayHeaders(base) {
+  const headers = { ...base };
+  if (GATEWAY_TOKEN) headers.Authorization = `Bearer ${GATEWAY_TOKEN}`;
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
+/** Le seul point de sortie HTTP du relais : tout appel au gateway passe par ici. */
+function gatewayFetch(path, init = {}) {
+  const headers = gatewayHeaders(init.headers);
+  return fetch(`${GATEWAY_URL}${path}`, headers ? { ...init, headers } : init);
+}
+
+/** Un refus d'authentification mérite mieux qu'un `HTTP 401` nu. */
+function isAuthStatus(status) {
+  return status === 401 || status === 403;
+}
+
+function authErrorText(status) {
+  return GATEWAY_TOKEN
+    ? `Accès refusé par le gateway (HTTP ${status}) : le GATEWAY_TOKEN fourni est invalide, ` +
+        `révoqué, ou ne correspond pas à cette gateway. Régénérez-le puis mettez à jour la ` +
+        `variable GATEWAY_TOKEN dans la configuration de ce serveur MCP.`
+    : `Accès refusé par le gateway (HTTP ${status}) : aucun GATEWAY_TOKEN n'est défini alors ` +
+        `que ${GATEWAY_URL} en exige un. Ajoutez GATEWAY_TOKEN dans le bloc « env » de la ` +
+        `configuration de ce serveur MCP.`;
+}
+
+/** Message d'erreur d'un appel outil — inchangé hors 401/403. */
+function gatewayErrorText(status, body) {
+  return isAuthStatus(status) ? authErrorText(status) : `Gateway error ${status}: ${body}`;
+}
+
+/** Message d'une erreur relancée — inchangé hors 401/403. */
+function gatewayThrowText(status) {
+  return isAuthStatus(status) ? authErrorText(status) : `HTTP ${status}`;
+}
+
+// --- Fichiers : le relais lit, l'agent ne fait que nommer ---
+//
+// Le relais tourne sur la machine de l'AGENT ; le MCP, lui, tourne sur la machine du
+// gateway. Un chemin de fichier transmis tel quel ne veut donc rien dire à l'arrivée :
+// le MCP cherche le fichier chez lui et ne le trouve pas.
+//
+// La règle : dès qu'un outil distant déclare une paire `<x>_path` / `<x>_content`, le
+// relais lit le fichier ICI, l'encode en base64 et envoie le CONTENU. Le paramètre
+// `<x>_content` (et `<x>_name`, s'il existe) est retiré du schéma publié à l'agent :
+// l'agent ne fournit qu'un chemin, et n'a aucun arbitrage à faire.
+//
+// Rien ne se déclenche sur un outil qui n'expose pas cette paire : un `output_path`
+// seul reste un chemin, interprété côté gateway comme avant.
+//
+// Le chemin vient de l'agent : il n'est donc PAS digne de confiance. Trois garde-fous,
+// tous configurables dans le bloc « env » de ce serveur MCP :
+//
+//   GATEWAY_INLINE_ROOTS       Dossiers dont un fichier peut sortir. C'est l'interrupteur :
+//                              non renseigné, le relais ne lit aucun fichier et l'appel
+//                              ÉCHOUE — laisser filer le chemin ferait chercher le fichier
+//                              au MCP sur la machine du gateway, où il trouverait un
+//                              homonyme ou rien du tout, sans rien signaler.
+//                              Séparateur : « ; » sous Windows, « : » ailleurs.
+//   GATEWAY_INLINE_EXTENSIONS  Extensions autorisées (défaut : toutes). Les racines restent
+//                              le vrai garde-fou.
+//   GATEWAY_INLINE_MAX_BYTES   Taille maximale d'un fichier transmis (défaut : 8 Mio).
+//
+// Chaque fichier réellement transmis laisse une ligne sur stderr : ce que l'agent fait
+// sortir de la machine doit être lisible dans le journal de l'agent.
+
+/** Les racines autorisées, résolues une fois pour toutes au démarrage. */
+const INLINE_ROOTS = (process.env.GATEWAY_INLINE_ROOTS ?? '')
+  .split(path.delimiter)
+  .map((entry) => entry.trim())
+  .filter(Boolean)
+  .map((entry) => {
+    const resolved = path.resolve(entry);
+    try {
+      return fs.realpathSync(resolved);
+    } catch {
+      console.error(`[mcp-mode] GATEWAY_INLINE_ROOTS : dossier introuvable, ignoré — ${resolved}`);
+      return null;
+    }
+  })
+  .filter(Boolean);
+
+const INLINE_EXTENSIONS = (process.env.GATEWAY_INLINE_EXTENSIONS ?? '*')
+  .split(',')
+  .map((entry) => entry.trim().toLowerCase())
+  .filter(Boolean);
+
+const INLINE_ANY_EXTENSION = INLINE_EXTENSIONS.includes('*');
+
+// 8 Mio : encodé en base64 le corps pèse ~10,7 Mio, sous le plafond de 16 Mio que le hub
+// applique quand il journalise les corps de requête.
+const INLINE_MAX_BYTES =
+  Number.parseInt(process.env.GATEWAY_INLINE_MAX_BYTES ?? '', 10) || 8 * 1024 * 1024;
+
+const INLINE_FILES = INLINE_ROOTS.length > 0;
+
+if (INLINE_FILES) {
+  console.error(
+    `[mcp-mode] Transmission du contenu des fichiers activée depuis : ${INLINE_ROOTS.join(', ')} ` +
+      `(extensions : ${INLINE_ANY_EXTENSION ? 'toutes' : INLINE_EXTENSIONS.join(' ')})`
+  );
+}
+
+/** Le fichier est-il à l'intérieur d'une racine autorisée ? Liens symboliques résolus. */
+function insideAllowedRoot(realPath) {
+  return INLINE_ROOTS.some((root) => {
+    const rel = path.relative(root, realPath);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+  });
+}
+
+/** Les paires `<x>_path` / `<x>_content` déclarées par le schéma d'un outil. */
+function inlinablePairs(inputSchema) {
+  const props = inputSchema?.properties;
+  if (!props) return [];
+  return Object.keys(props)
+    .filter((key) => key.endsWith('_content') && `${key.slice(0, -'_content'.length)}_path` in props)
+    .map((contentProp) => {
+      const stem = contentProp.slice(0, -'_content'.length);
+      return {
+        pathProp: `${stem}_path`,
+        contentProp,
+        nameProp: `${stem}_name` in props ? `${stem}_name` : null,
+      };
+    });
+}
+
+/** Le schéma tel que l'agent doit le voir : sans les paramètres que le relais remplit. */
+function schemaForAgent(inputSchema) {
+  const inbound = inlinablePairs(inputSchema);
+  const pairs = [...inbound, ...deliverablePairs(inputSchema)];
+  const watching = declaresWatch(inputSchema);
+  if (pairs.length === 0 && !watching) return inputSchema;
+
+  // `_gateway_watch` est rempli par le relais, jamais par l'agent (voir gateway-watch.js).
+  const hidden = new Set([
+    ...pairs.flatMap((p) => [p.contentProp, p.nameProp, p.relayProp].filter(Boolean)),
+    ...(watching ? [WATCH_ARG] : []),
+  ]);
+  const properties = Object.fromEntries(
+    Object.entries(inputSchema.properties).filter(([key]) => !hidden.has(key))
+  );
+
+  // Le caractère obligatoire d'un `<x>_path` est celui que le MCP déclare, dans les deux
+  // sens. Un chemin optionnel veut dire quelque chose : à l'aller, que l'outil accepte
+  // aussi sa donnée autrement (un texte passé en ligne, par exemple) ; au retour, qu'il
+  // sait quoi faire sans destination. Sans `<x>_path`, le relais ne fait rien.
+  const required = (inputSchema.required ?? []).filter((key) => !hidden.has(key));
+
+  return { ...inputSchema, properties, required };
+}
+
+/**
+ * Remplace chaque `<x>_path` par le contenu du fichier lu sur la machine de l'agent.
+ *
+ * Tout refus est explicite : l'agent doit savoir pourquoi son fichier ne part pas,
+ * sans avoir à deviner s'il s'agit d'une absence, d'un type ou d'une interdiction.
+ */
+function inlineFileArgs(inputSchema, args = {}, label = '') {
+  const pairs = inlinablePairs(inputSchema);
+  if (pairs.length === 0) return args;
+
+  const out = { ...args };
+  for (const { pathProp, contentProp, nameProp } of pairs) {
+    const filePath = out[pathProp];
+    if (typeof filePath !== 'string' || filePath === '') continue;
+
+    // Un outil qui déclare la paire attend le CONTENU : il tourne sur la machine du
+    // gateway, où le chemin de l'agent ne désigne rien — ou pire, désigne un homonyme
+    // qu'il traiterait sans broncher. Laisser filer le chemin serait une dégradation
+    // silencieuse ; on refuse en nommant la variable à renseigner.
+    if (!INLINE_FILES) {
+      throw new Error(
+        `Transmission de fichier impossible : aucun dossier de lecture autorisé. L'outil ` +
+          `attend le contenu du fichier (paramètre ${pathProp}), mais il tourne sur la machine ` +
+          `du gateway et ne peut pas lire la vôtre. Renseignez GATEWAY_INLINE_ROOTS dans le ` +
+          `bloc « env » de la configuration de ce serveur MCP.`
+      );
+    }
+
+    const resolved = path.resolve(filePath);
+
+    // realpath avant tout contrôle : sans ça, un lien symbolique placé dans une racine
+    // autorisée ferait sortir n'importe quel fichier de la machine.
+    let real;
+    let stat;
+    try {
+      real = fs.realpathSync(resolved);
+      stat = fs.statSync(real);
+    } catch {
+      throw new Error(
+        `Fichier introuvable sur la machine de l'agent : ${resolved} (paramètre ${pathProp}).`
+      );
+    }
+    if (!stat.isFile()) {
+      throw new Error(`${resolved} n'est pas un fichier (paramètre ${pathProp}).`);
+    }
+    if (!insideAllowedRoot(real)) {
+      throw new Error(
+        `Lecture refusée : ${real} est hors des dossiers autorisés (${INLINE_ROOTS.join(', ')}). ` +
+          `Déplacez le fichier dans l'un d'eux, ou ajoutez son dossier à GATEWAY_INLINE_ROOTS ` +
+          `dans la configuration de ce serveur MCP.`
+      );
+    }
+    const ext = path.extname(real).toLowerCase();
+    if (!INLINE_ANY_EXTENSION && !INLINE_EXTENSIONS.includes(ext)) {
+      throw new Error(
+        `Lecture refusée : l'extension « ${ext || '(aucune)'} » n'est pas autorisée ` +
+          `(autorisées : ${INLINE_EXTENSIONS.join(' ')}, via GATEWAY_INLINE_EXTENSIONS).`
+      );
+    }
+    if (stat.size > INLINE_MAX_BYTES) {
+      throw new Error(
+        `Fichier trop volumineux à transmettre : ${real} pèse ${stat.size} octets, ` +
+          `la limite est de ${INLINE_MAX_BYTES} (GATEWAY_INLINE_MAX_BYTES).`
+      );
+    }
+
+    out[contentProp] = fs.readFileSync(real).toString('base64');
+    if (nameProp) out[nameProp] = path.basename(real);
+    delete out[pathProp];
+
+    console.error(
+      `[mcp-mode] Fichier transmis${label ? ` à ${label}` : ''} : ${real} (${stat.size} octets)`
+    );
+  }
+  return out;
+}
+
+// --- Fichiers : le MCP produit, le relais écrit ---
+//
+// Le sens retour, symétrique du précédent. `inlineFileArgs` ne réécrit que les arguments
+// à l'aller ; un fichier produit par le MCP, lui, n'a aucun moyen d'atteindre la machine
+// de l'agent : le protocole n'offre au serveur aucune primitive pour y écrire.
+//
+// La règle : dès qu'un outil distant déclare une paire `<x>_path` / `<x>_relay`, le relais
+// retient le chemin, annonce sa présence au MCP en posant `<x>_relay` à true, et ne
+// transmet PAS `<x>_path` — qui ne désignerait rien à l'arrivée. Le MCP répond alors avec
+// le contenu du fichier, que le relais écrit ICI, à l'emplacement retenu.
+//
+// Le contenu ne ressort JAMAIS vers l'agent : le relais le retire du résultat, qu'il ait
+// réussi ou non à écrire. Un fichier de 8 Mio encodé en base64 n'a rien à faire dans le
+// contexte d'un agent, et rien ne justifie de l'y déverser « au cas où » : l'appel échoue,
+// le fichier est perdu, l'agent recommence.
+//
+// Sans relais dans la chaîne — MCP lancé en stdio à côté de l'agent — `<x>_relay` reste
+// absent : les deux machines n'en font qu'une, et le MCP écrit lui-même à `<x>_path`.
+//
+// Écrire est plus dangereux que lire : la fonction a donc sa propre racine autorisée,
+// et n'hérite pas de celle de la lecture.
+//
+//   GATEWAY_INLINE_WRITE_ROOTS       Dossiers où un fichier peut être déposé. C'est
+//                                    l'interrupteur : non renseigné, aucune livraison
+//                                    n'a lieu et l'appel échoue en le disant.
+//   GATEWAY_INLINE_WRITE_EXTENSIONS  Extensions autorisées (défaut : toutes). Les racines
+//                                    restent le vrai garde-fou.
+//   GATEWAY_INLINE_MAX_BYTES         Plafond de taille, partagé avec la lecture.
+
+const WRITE_ROOTS = (process.env.GATEWAY_INLINE_WRITE_ROOTS ?? '')
+  .split(path.delimiter)
+  .map((entry) => entry.trim())
+  .filter(Boolean)
+  .map((entry) => {
+    const resolved = path.resolve(entry);
+    try {
+      return fs.realpathSync(resolved);
+    } catch {
+      console.error(`[mcp-mode] GATEWAY_INLINE_WRITE_ROOTS : dossier introuvable, ignoré — ${resolved}`);
+      return null;
+    }
+  })
+  .filter(Boolean);
+
+const WRITE_EXTENSIONS = (process.env.GATEWAY_INLINE_WRITE_EXTENSIONS ?? '*')
+  .split(',')
+  .map((entry) => entry.trim().toLowerCase())
+  .filter(Boolean);
+
+const WRITE_ANY_EXTENSION = WRITE_EXTENSIONS.includes('*');
+
+if (WRITE_ROOTS.length > 0) {
+  console.error(
+    `[mcp-mode] Écriture des fichiers reçus activée vers : ${WRITE_ROOTS.join(', ')} ` +
+      `(extensions : ${WRITE_ANY_EXTENSION ? 'toutes' : WRITE_EXTENSIONS.join(' ')})`
+  );
+}
+
+/** Les paires `<x>_path` / `<x>_relay` déclarées par le schéma d'un outil. */
+function deliverablePairs(inputSchema) {
+  const props = inputSchema?.properties;
+  if (!props) return [];
+  return Object.keys(props)
+    .filter((key) => key.endsWith('_relay') && `${key.slice(0, -'_relay'.length)}_path` in props)
+    .map((relayProp) => {
+      const stem = relayProp.slice(0, -'_relay'.length);
+      return {
+        pathProp: `${stem}_path`,
+        relayProp,
+        overwriteProp: `${stem}_overwrite` in props ? `${stem}_overwrite` : null,
+      };
+    });
+}
+
+/**
+ * Le chemin de destination, résolu et vérifié contre les racines autorisées.
+ *
+ * `destDir` est toujours un dossier et `fileName` le nom que le MCP donne au fichier :
+ * le relais ne renomme jamais. Passer `fileName` vide ne vérifie que le dossier — ce
+ * qu'on fait à l'aller, pour échouer avant d'avoir fait voyager les octets pour rien.
+ *
+ * Le fichier n'existe pas encore : impossible d'appeler `realpath` dessus. On résout
+ * donc les liens du plus proche ancêtre existant, sans quoi un lien symbolique déposé
+ * dans une racine autorisée permettrait d'écrire n'importe où sur la machine.
+ */
+function resolveWriteTarget(destDir, fileName = '') {
+  const resolved = fileName
+    ? path.resolve(destDir, path.basename(fileName))
+    : path.resolve(destDir);
+
+  let existing = path.dirname(resolved);
+  const trailing = [path.basename(resolved)];
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) {
+      throw new Error(`Destination inatteignable sur la machine de l'agent : ${resolved}.`);
+    }
+    trailing.unshift(path.basename(existing));
+    existing = parent;
+  }
+
+  const real = path.join(fs.realpathSync(existing), ...trailing);
+
+  const inside = WRITE_ROOTS.some((root) => {
+    const rel = path.relative(root, real);
+    // Un dossier de destination PEUT être la racine elle-même ; un fichier, non.
+    if (rel === '') return fileName === '';
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+  });
+  if (!inside) {
+    throw new Error(
+      `Écriture refusée : ${real} est hors des dossiers autorisés (${WRITE_ROOTS.join(', ')}). ` +
+        `Choisissez une destination dans l'un d'eux, ou ajoutez son dossier à ` +
+        `GATEWAY_INLINE_WRITE_ROOTS dans la configuration de ce serveur MCP.`
+    );
+  }
+
+  const ext = path.extname(real).toLowerCase();
+  if (fileName && !WRITE_ANY_EXTENSION && !WRITE_EXTENSIONS.includes(ext)) {
+    throw new Error(
+      `Écriture refusée : l'extension « ${ext || '(aucune)'} » n'est pas autorisée ` +
+        `(autorisées : ${WRITE_EXTENSIONS.join(' ')}, via GATEWAY_INLINE_WRITE_EXTENSIONS).`
+    );
+  }
+
+  return real;
+}
+
+/**
+ * Retire `<x>_path` des arguments et pose `<x>_relay`, pour que le MCP renvoie le
+ * contenu au lieu de tenter une écriture qui atterrirait sur SA machine.
+ */
+function prepareDeliveries(inputSchema, args = {}) {
+  const pairs = deliverablePairs(inputSchema);
+  if (pairs.length === 0) return { args, deliveries: [] };
+
+  const out = { ...args };
+  const deliveries = [];
+  for (const { pathProp, relayProp, overwriteProp } of pairs) {
+    const destPath = out[pathProp];
+    if (typeof destPath !== 'string' || destPath === '') continue;
+
+    if (WRITE_ROOTS.length === 0) {
+      throw new Error(
+        `Livraison de fichier impossible : aucun dossier d'écriture autorisé. Le MCP tourne ` +
+          `sur la machine du gateway et ne peut pas écrire sur la vôtre. Renseignez ` +
+          `GATEWAY_INLINE_WRITE_ROOTS dans le bloc « env » de la configuration de ce ` +
+          `serveur MCP avec le ou les dossiers où déposer les fichiers reçus.`
+      );
+    }
+
+    // Vérification du dossier seul : le nom du fichier n'est connu qu'au retour.
+    resolveWriteTarget(destPath);
+    deliveries.push({
+      destDir: destPath,
+      overwrite: overwriteProp ? out[overwriteProp] === true : false,
+    });
+    out[relayProp] = true;
+    delete out[pathProp];
+  }
+  return { args: out, deliveries };
+}
+
+/**
+ * Écrit les fichiers renvoyés par le MCP et purge le résultat de leur contenu.
+ *
+ * Le contenu est retiré dans tous les cas, y compris en cas d'échec d'écriture : c'est
+ * la seule garantie qu'un base64 ne finira jamais dans le contexte de l'agent.
+ */
+function applyDeliveries(result, deliveries, label = '') {
+  if (deliveries.length === 0) return result;
+
+  const blocks = Array.isArray(result?.content) ? result.content : [];
+  const blobs = blocks.filter((b) => b?.type === 'resource' && typeof b.resource?.blob === 'string');
+  const kept = blocks.filter((b) => !blobs.includes(b));
+
+  if (result?.isError) return { ...result, content: kept.length > 0 ? kept : blocks };
+
+  const notes = [];
+  deliveries.forEach((delivery, i) => {
+    const blob = blobs[i];
+    if (!blob) {
+      notes.push(`Aucun contenu renvoyé par le MCP pour ${delivery.destDir} : rien n'a été écrit.`);
+      return;
+    }
+    let target = delivery.destDir;
+    try {
+      const fileName = blob.resource.name || path.basename(new URL(blob.resource.uri).pathname);
+      if (!fileName) throw new Error("le MCP n'a pas nommé le fichier renvoyé");
+      target = resolveWriteTarget(delivery.destDir, fileName);
+
+      const data = Buffer.from(blob.resource.blob, 'base64');
+      if (data.length > INLINE_MAX_BYTES) {
+        throw new Error(
+          `fichier trop volumineux : ${data.length} octets, la limite est de ` +
+            `${INLINE_MAX_BYTES} (GATEWAY_INLINE_MAX_BYTES)`
+        );
+      }
+      if (!delivery.overwrite && fs.existsSync(target)) {
+        throw new Error('la destination existe déjà');
+      }
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, data);
+      notes.push(`Fichier écrit : ${target} (${data.length} octets).`);
+      console.error(
+        `[mcp-mode] Fichier reçu${label ? ` de ${label}` : ''} : ${target} (${data.length} octets)`
+      );
+    } catch (err) {
+      notes.push(`Échec de l'écriture dans ${target} : ${err.message}.`);
+    }
+  });
+
+  const failed = notes.some((note) => note.startsWith('Échec') || note.startsWith('Aucun'));
+  return {
+    ...result,
+    content: [...kept, { type: 'text', text: notes.join('\n') }],
+    ...(failed ? { isError: true } : {}),
+  };
+}
+
+// --- Exécution sur la machine de l'agent (voir gateway-exec.js) ---
+
+const { routes: EXEC_ROUTES, invalid: EXEC_INVALID_ROUTES } = parseExecRoutes(process.env.GATEWAY_EXEC_ROUTES);
+if (EXEC_INVALID_ROUTES.length > 0) {
+  console.error(
+    `[mcp-mode] GATEWAY_EXEC_ROUTES : route(s) invalide(s) ${EXEC_INVALID_ROUTES.map((r) => `"${r}"`).join(', ')} ` +
+      `(attendu : des routes du gateway séparées par des virgules, ex. /github)`
+  );
+  process.exit(1);
+}
+
+/** Dossier de lancement du relais, fixé par l'agent qui l'a démarré. */
+const EXEC_ROOT = process.cwd();
+
+if (EXEC_ROUTES.size > 0) {
+  console.error(
+    `[mcp-mode] Exécution de commandes activée pour les MCP ${[...EXEC_ROUTES].join(', ')}, depuis : ${EXEC_ROOT}`
+  );
+}
+
+/**
+ * Appelle un outil du gateway et traite ses demandes d'exécution jusqu'au résultat final.
+ * Rend le résultat de l'outil, ou un résultat d'erreur si le gateway refuse l'appel.
+ */
+async function callRemoteTool(route, toolName, body, label) {
+  const execAllowed = EXEC_ROUTES.has(normalizeRoute(route));
+  const announcement = execAllowed
+    ? execAnnouncement({ cwd: EXEC_ROOT, gatewayToken: GATEWAY_TOKEN })
+    : null;
+  let payload = announcement ? { ...body, [EXEC_ARG]: announcement } : body;
+
+  for (let round = 0; ; round++) {
+    const res = await gatewayFetch(`${route}/tools/${toolName}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      return { content: [{ type: 'text', text: gatewayErrorText(res.status, text) }], isError: true };
+    }
+    const result = await res.json();
+    const request = execRequestOf(result);
+    if (!request) return result;
+
+    if (!announcement) {
+      throw new Error(
+        `${label} demande une exécution sur cette machine, mais la route ${normalizeRoute(route)} n'est pas ` +
+          `dans GATEWAY_EXEC_ROUTES : rien n'a été exécuté.`
+      );
+    }
+    if (round >= MAX_EXEC_ROUNDS) {
+      throw new Error(`${label} a dépassé ${MAX_EXEC_ROUNDS} demandes d'exécution pour un même appel.`);
+    }
+    const results = await runExecRequest(request, {
+      root: EXEC_ROOT,
+      gatewayUrl: GATEWAY_URL,
+      gatewayToken: GATEWAY_TOKEN,
+      label,
+    });
+    payload = { [EXEC_ARG]: { ...announcement, continuation: { id: request.id, results } } };
+  }
+}
+
+/**
+ * Appelle un outil distant avec les conventions du relais : fichiers transmis dans les deux
+ * sens, et veille armée quand l'outil l'a déclarée et répond par une spécification.
+ */
+async function relayToolCall(route, toolName, schema, args, label) {
+  const { args: outArgs, deliveries } = prepareDeliveries(schema, args);
+  const inlined = inlineFileArgs(schema, outArgs, label);
+  const watching = declaresWatch(schema);
+  const body = watching ? { ...inlined, [WATCH_ARG]: watchAnnouncement() } : inlined;
+  const result = await callRemoteTool(route, toolName, body, label);
+  const spec = watching && !result.isError ? watchSpecOf(result) : null;
+  if (spec) return armWatch(spec, { route, gatewayUrl: GATEWAY_URL, gatewayToken: GATEWAY_TOKEN });
+  return applyDeliveries(result, deliveries, label);
+}
+
+/** Schémas des outils d'une route, mis en cache — nécessaires pour `call_tool`. */
+const routeSchemas = new Map();
+
+async function toolSchema(route, toolName) {
+  // Toujours récupéré, même si l'inlining en lecture est désactivé : c'est le schéma qui
+  // révèle une paire `<x>_path` / `<x>_relay`, et la manquer ferait repartir un chemin
+  // de destination vers le MCP distant, qui écrirait alors sur SA machine sans le dire.
+  if (!routeSchemas.has(route)) {
+    try {
+      const res = await gatewayFetch(`${route}/tools`);
+      const list = res.ok ? await res.json() : [];
+      routeSchemas.set(route, new Map(list.map((t) => [t.name, t.inputSchema])));
+    } catch {
+      routeSchemas.set(route, new Map());
+    }
+  }
+  return routeSchemas.get(route).get(toolName) ?? null;
+}
+
+// --- MCP Server ---
+
+// Le gateway (mode serveur HTTP) peut être paramétré (EXPOSE_AT_AGENT_STARTUP) pour
+// pré-exposer les outils de certains MCP directement à l'agent. La config vit uniquement
+// sur le serveur : ce bridge se contente de récupérer ces outils et de les publier, de
+// façon transparente. En cas d'échec (ancien gateway sans la route, gateway protégé par
+// OAuth, etc.), on continue sans pré-exposition.
+async function fetchProxyTools() {
+  try {
+    const res = await gatewayFetch('/startup-exposition');
+    if (!res.ok) {
+      // La pré-exposition reste optionnelle : on n'interrompt pas le démarrage.
+      // Mais un 401/403 ici annonce que TOUS les appels seront refusés — le dire
+      // maintenant évite de chercher plus tard. Sans le token, évidemment.
+      if (isAuthStatus(res.status)) console.error(`[mcp-mode] ${authErrorText(res.status)}`);
+      return [];
+    }
+    const { proxyTools } = await res.json();
+    return proxyTools ?? [];
+  } catch {
+    return [];
+  }
+}
+
+const proxyTools = await fetchProxyTools();
+if (proxyTools.length) {
+  console.error(`[mcp-mode] ${proxyTools.length} proxy tool(s) exposed directly from gateway`);
+}
+
+const server = new Server(
+  { name: 'mcp-http-gateway-mcp', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+const tools = [
+  {
+    name: 'list_mcps',
+    description: 'List all MCPs available on the gateway with their route and description.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'list_tools',
+    description: 'List all tools available for a given MCP route.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        route: { type: 'string', description: 'MCP route as returned by list_mcps (e.g. "/documentor")' },
+      },
+      required: ['route'],
+    },
+  },
+  {
+    name: 'call_tool',
+    description: 'Call a tool on a given MCP route.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        route:     { type: 'string', description: 'MCP route (e.g. "/documentor")' },
+        tool_name: { type: 'string', description: 'Tool name to call' },
+        arguments: { type: 'object', description: 'Arguments to pass to the tool' },
+      },
+      required: ['route', 'tool_name'],
+    },
+  },
+];
+
+const proxyIndex = new Map(proxyTools.map(t => [t.name, t]));
+const allTools = [
+  ...tools,
+  ...proxyTools.map(({ name, description, inputSchema }) => ({
+    name,
+    description,
+    inputSchema: schemaForAgent(inputSchema),
+  })),
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    const proxy = proxyIndex.get(name);
+    if (proxy) {
+      const label = `${proxy.route}/${proxy.toolName}`;
+      return await relayToolCall(proxy.route, proxy.toolName, proxy.inputSchema, args ?? {}, label);
+    }
+
+    if (name === 'list_mcps') {
+      const res = await gatewayFetch('/mcp-definitions');
+      if (!res.ok) throw new Error(gatewayThrowText(res.status));
+      const definitions = await res.json();
+      const text = definitions
+        .map(m => `- ${m.id} (route: ${m.route})${m.description ? ` — ${m.description}` : ''}`)
+        .join('\n');
+      return { content: [{ type: 'text', text }] };
+    }
+
+    if (name === 'list_tools') {
+      const res = await gatewayFetch(`${args.route}/tools`);
+      if (!res.ok) throw new Error(gatewayThrowText(res.status));
+      const toolsList = await res.json();
+      routeSchemas.set(args.route, new Map(toolsList.map((t) => [t.name, t.inputSchema])));
+      // Même règle que pour les outils pré-exposés : l'agent ne doit pas découvrir
+      // les paramètres de contenu, c'est le relais qui les remplit.
+      const text = JSON.stringify(
+        toolsList.map((t) => (t.inputSchema ? { ...t, inputSchema: schemaForAgent(t.inputSchema) } : t))
+      );
+      return { content: [{ type: 'text', text }] };
+    }
+
+    if (name === 'call_tool') {
+      const schema = await toolSchema(args.route, args.tool_name);
+      const label = `${args.route}/${args.tool_name}`;
+      return await relayToolCall(args.route, args.tool_name, schema, args.arguments ?? {}, label);
+    }
+
+    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Request failed: ${err.message}` }], isError: true };
+  }
+});
+
+// L'agent arrête le relais en fermant son entrée standard : la sortie retire les fichiers
+// de veille, qui contiennent le jeton. Ceux d'un relais tué sont retirés au démarrage suivant.
+pruneOrphanWatches();
+process.on('exit', removeOwnWatches);
+process.stdin.on('end', () => process.exit(0));
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => process.exit(0));
+
+const transport = new StdioServerTransport();
+await server.connect(transport);