@imenam/mcp-http-gateway 2.0.10 → 2.0.11

package/README.md

@@ -189,9 +189,11 @@ GATEWAY_URL=http://host.docker.internal:3500 npx @imenam/mcp-http-gateway --mcp
 |---|---|---|
 | `GATEWAY_URL` | oui | Base HTTP du gateway à relayer, sans barre finale. Le relais compose lui-même ses routes REST (`/startup-exposition`, `/mcp-definitions`, `/{route}/tools`, `/{route}/tools/{outil}`) : **ne pas** y ajouter `/mcp`. |
 | `GATEWAY_TOKEN` | non | Token porteur. S'il est défini, **tous** les appels sortants du relais portent `Authorization: Bearer <token>`. Absent, aucun en-tête n'est ajouté — le comportement est exactement celui des versions antérieures. |
-| `GATEWAY_INLINE_ROOTS` | non | Dossiers depuis lesquels le relais peut lire un fichier et en transmettre le contenu (cf. [Fichiers locaux](#fichiers-locaux--lagent-nomme-le-relais-lit)). **Non renseignée, la fonction est désactivée** et un chemin part tel quel. Séparateur : `;` sous Windows, `:` ailleurs. |
+| `GATEWAY_INLINE_ROOTS` | non | Dossiers depuis lesquels le relais peut lire un fichier et en transmettre le contenu (cf. [Fichiers locaux](#fichiers-locaux--lagent-nomme-le-relais-lit)). **Non renseignée, tout appel à un outil qui déclare la paire échoue explicitement.** Séparateur : `;` sous Windows, `:` ailleurs. |
 | `GATEWAY_INLINE_EXTENSIONS` | non | Extensions autorisées, séparées par des virgules. Défaut : `.xlsx,.xls,.ods,.csv`. `*` autorise toutes les extensions. |
-| `GATEWAY_INLINE_MAX_BYTES` | non | Taille maximale d'un fichier transmis, en octets. Défaut : `8388608` (8 Mio). |
+| `GATEWAY_INLINE_MAX_BYTES` | non | Taille maximale d'un fichier transmis, en octets, dans les deux sens. Défaut : `8388608` (8 Mio). |
+| `GATEWAY_INLINE_WRITE_ROOTS` | non | Dossiers dans lesquels le relais peut écrire un fichier renvoyé par un MCP (cf. [Fichiers reçus](#fichiers-reçus--le-mcp-produit-le-relais-écrit)). **Non renseignée, la fonction est désactivée** et tout outil qui la réclame échoue explicitement. Séparateur : `;` sous Windows, `:` ailleurs. |
+| `GATEWAY_INLINE_WRITE_EXTENSIONS` | non | Extensions autorisées à l'écriture, séparées par des virgules. Défaut : `*` (toutes) — les racines restent le vrai garde-fou. |
 
 > Ces deux variables sont lues dans l'environnement du process. Le relais fait
 > `import 'dotenv/config'` : un fichier `.env` présent dans le **répertoire courant de
@@ -271,7 +273,14 @@ fermée par défaut et s'ouvre dossier par dossier :
 ```
 
 - **`GATEWAY_INLINE_ROOTS` est l'interrupteur.** Non renseignée, le relais ne lit aucun
-  fichier et se comporte exactement comme les versions antérieures.
+  fichier et **l'appel échoue** en nommant la variable à définir. Un outil qui déclare la
+  paire attend le contenu : laisser filer le chemin ferait chercher le fichier au MCP sur
+  la machine du gateway, où il ne le trouverait pas — ou pire, où il traiterait un homonyme
+  sans rien signaler. Pas de repli, pas de dégradation silencieuse.
+
+  > **Changement de comportement.** Les versions antérieures laissaient passer le chemin tel
+  > quel dans ce cas. Si un déploiement existant s'appuyait là-dessus, renseignez
+  > `GATEWAY_INLINE_ROOTS` — le message d'erreur le dit explicitement.
 - Les liens symboliques sont résolus **avant** le contrôle : un lien posé dans un dossier
   autorisé ne fait pas sortir un fichier situé ailleurs. Une remontée par `..` est refusée
   pour la même raison.
@@ -290,6 +299,55 @@ fermée par défaut et s'ouvre dossier par dossier :
 > sur la machine de l'appelant, donc personne ne peut lire son disque. Par ce chemin, un
 > agent qui veut faire lire un fichier doit en envoyer lui-même le contenu.
 
+### Fichiers reçus : le MCP produit, le relais écrit
+
+Le sens retour, symétrique du précédent. Un MCP qui *fabrique* un fichier — un export, une
+pièce jointe, un téléchargement — ne peut pas le déposer sur la machine de l'agent : le
+protocole n'offre au serveur aucune primitive pour y écrire. Un chemin de destination
+transmis tel quel ferait écrire le MCP sur **son** disque, sans que personne s'en aperçoive.
+
+Dès qu'un outil distant déclare la paire `<x>_path` / `<x>_relay`, le relais :
+
+1. retire `<x>_relay` du schéma publié à l'agent, qui ne voit qu'un dossier à nommer ;
+2. retient `<x>_path`, ne le transmet pas, et pose `<x>_relay` à `true` ;
+3. reçoit le contenu du fichier dans la réponse du MCP, l'écrit **ici**, et le retire du
+   résultat avant de le rendre à l'agent.
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["@imenam/mcp-http-gateway", "--mcp"],
+      "env": {
+        "GATEWAY_URL": "https://my-gateway.fr/jskdlf-jsfklhj",
+        "GATEWAY_TOKEN": "…",
+        "GATEWAY_INLINE_WRITE_ROOTS": "C:\\Users\\moi\\Téléchargements"
+      }
+    }
+  }
+}
+```
+
+- **`GATEWAY_INLINE_WRITE_ROOTS` est l'interrupteur**, distinct de celui de la lecture :
+  écrire est plus dangereux que lire, et n'hérite donc pas des dossiers autorisés en lecture.
+- **Non renseignée, l'appel échoue** en nommant la variable à définir. Pas de repli, pas de
+  dégradation silencieuse : mieux vaut un fichier perdu qu'un fichier écrit au mauvais endroit.
+- `<x>_path` est toujours un **dossier**, créé si besoin ; le fichier garde le nom que lui
+  donne le MCP. Le relais ne renomme jamais.
+- Si l'outil déclare aussi `<x>_overwrite`, le relais l'honore ; sinon il refuse d'écraser.
+- Les liens symboliques sont résolus avant contrôle, y compris sur le plus proche ancêtre
+  existant quand la destination n'existe pas encore.
+- **Le contenu est retiré du résultat dans tous les cas**, y compris en cas d'échec
+  d'écriture. Un fichier de 8 Mio encodé en base64 n'a rien à faire dans le contexte d'un
+  agent : ça coûte cher, et un agent qui le recopierait à la main le corromprait.
+- Chaque fichier écrit laisse une ligne sur `stderr`.
+
+> Côté MCP, cette fonction suppose que l'outil sache renvoyer son fichier en bloc
+> `resource` (avec `blob` et `name`) quand `<x>_relay` est posé. C'est le cas de
+> [`file-share-mcp`](https://www.npmjs.com/package/file-share-mcp). Un MCP qui ne déclare
+> pas la paire n'est pas concerné, et son résultat repart intact.
+
 ---
 
 ## Mode MCP distant (HTTPS / Claude.ai)

package/mcp-mode.js

@@ -146,7 +146,7 @@ function insideAllowedRoot(realPath) {
 /** Les paires `<x>_path` / `<x>_content` déclarées par le schéma d'un outil. */
 function inlinablePairs(inputSchema) {
   const props = inputSchema?.properties;
-  if (!INLINE_FILES || !props) return [];
+  if (!props) return [];
   return Object.keys(props)
     .filter((key) => key.endsWith('_content') && `${key.slice(0, -'_content'.length)}_path` in props)
     .map((contentProp) => {
@@ -161,10 +161,12 @@ function inlinablePairs(inputSchema) {
 
 /** Le schéma tel que l'agent doit le voir : sans les paramètres que le relais remplit. */
 function schemaForAgent(inputSchema) {
-  const pairs = inlinablePairs(inputSchema);
+  const pairs = [...inlinablePairs(inputSchema), ...deliverablePairs(inputSchema)];
   if (pairs.length === 0) return inputSchema;
 
-  const hidden = new Set(pairs.flatMap((p) => [p.contentProp, p.nameProp].filter(Boolean)));
+  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))
   );
@@ -195,6 +197,19 @@ function inlineFileArgs(inputSchema, args = {}, label = '') {
     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
@@ -244,11 +259,233 @@ function inlineFileArgs(inputSchema, args = {}, label = '') {
   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) {
-  if (!INLINE_FILES) return null;
+  // 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`);
@@ -345,18 +582,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   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, args ?? {}, `${proxy.route}/${proxy.toolName}`)
-        ),
+        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 await res.json();
+      return applyDeliveries(await res.json(), deliveries, label);
     }
 
     if (name === 'list_mcps') {
@@ -384,18 +621,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     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, args.arguments ?? {}, `${args.route}/${args.tool_name}`)
-        ),
+        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 await res.json();
+      return applyDeliveries(await res.json(), deliveries, label);
     }
 
     return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-http-gateway",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "type": "module",
   "description": "HTTP gateway that exposes MCP servers as REST routes — bridge between MCP and any HTTP-capable agent",
   "main": "server.js",