@imenam/mcp-http-gateway 2.0.14 → 2.0.15

package/gateway-exec.js

@@ -0,0 +1,162 @@
+import { spawn } from 'child_process';
+import path from 'path';
+
+// --- Exécution sur la machine de l'agent, à la demande d'un MCP du gateway ---
+//
+// Le relais tourne sur la machine de l'AGENT ; un MCP du gateway, lui, n'a aucun moyen
+// d'y lancer quoi que ce soit. Cette convention lui en donne un, à travers les appels
+// d'outils existants :
+//
+// 1. Pour un MCP autorisé, le relais ajoute à chaque appel l'argument réservé
+//    `_gateway_exec` : `{ version, cwd, gatewayToken }` — son dossier de lancement, et
+//    s'il détient un GATEWAY_TOKEN. Sans cet argument, le MCP sait que le relais
+//    n'exécutera rien.
+// 2. Le MCP peut répondre par une demande d'exécution au lieu d'un résultat final :
+//    `_meta["gateway/exec"] = { id, steps }`, chaque étape valant `{ command, args, cwd, env }`.
+// 3. Le relais lance les étapes dans l'ordre, sans shell, et s'arrête à la première qui
+//    échoue. `cwd` est résolu par rapport à son dossier de lancement. Dans `args` et les
+//    valeurs de `env`, il remplace `{{GATEWAY_URL}}` et `{{GATEWAY_TOKEN}}`.
+// 4. Il rappelle le même outil avec `_gateway_exec.continuation = { id, results }`, et
+//    recommence tant que le MCP renvoie une demande. L'agent ne voit que le résultat final.
+//
+//   GATEWAY_EXEC_ROUTES    Routes, dans le gateway, des MCP autorisés à exécuter, séparées
+//                          par des virgules (ex. `/github`). C'est l'interrupteur : vide,
+//                          aucun MCP n'exécute. Seul un appel vers une route listée porte
+//                          `_gateway_exec`, et une demande d'exécution venue d'une autre
+//                          route fait échouer l'appel sans rien lancer.
+//
+// Chaque commande lancée laisse une ligne sur stderr, avec ses marqueurs non remplacés :
+// ce que le gateway fait exécuter doit être lisible dans le journal de l'agent, sans que
+// le jeton y figure.
+
+export const EXEC_ARG = '_gateway_exec';
+export const EXEC_META = 'gateway/exec';
+export const EXEC_VERSION = 1;
+
+/** Nombre maximal d'allers-retours pour un même appel d'outil. */
+export const MAX_EXEC_ROUNDS = 50;
+
+/** Taille maximale conservée de la sortie standard et de la sortie d'erreur d'une étape. */
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+
+/** Forme canonique d'une route : `/github/` et `/github` désignent le même MCP. */
+export function normalizeRoute(route) {
+  return typeof route === 'string' ? route.trim().replace(/\/+$/, '') : '';
+}
+
+/**
+ * Lit la directive GATEWAY_EXEC_ROUTES.
+ * Rend les routes autorisées, et les entrées invalides (qui ne commencent pas par `/`).
+ */
+export function parseExecRoutes(raw) {
+  const entries = (raw ?? '').split(',').map((e) => e.trim()).filter(Boolean);
+  const invalid = entries.filter((e) => !/^\/\S*$/.test(e) || normalizeRoute(e) === '');
+  const routes = new Set(entries.filter((e) => !invalid.includes(e)).map(normalizeRoute));
+  return { routes, invalid };
+}
+
+/** L'argument réservé qui annonce au MCP que ce relais sait exécuter. */
+export function execAnnouncement({ cwd, gatewayToken }) {
+  return { version: EXEC_VERSION, cwd, gatewayToken: Boolean(gatewayToken) };
+}
+
+/** La demande d'exécution portée par un résultat d'outil, ou null. */
+export function execRequestOf(result) {
+  const request = result?._meta?.[EXEC_META];
+  return request && typeof request === 'object' ? request : null;
+}
+
+function substitute(value, values) {
+  return value.replace(/\{\{(GATEWAY_URL|GATEWAY_TOKEN)\}\}/g, (_, key) => {
+    const replacement = values[key];
+    if (replacement === undefined) {
+      throw new Error(`le MCP utilise {{${key}}}, mais ce relais n'en a pas (variable ${key} non définie)`);
+    }
+    return replacement;
+  });
+}
+
+function validateStep(step, index) {
+  const ok = step && typeof step.command === 'string' && step.command !== ''
+    && Array.isArray(step.args) && step.args.every((a) => typeof a === 'string')
+    && (step.cwd === undefined || typeof step.cwd === 'string')
+    && (step.env === undefined || (typeof step.env === 'object'
+      && Object.values(step.env).every((v) => typeof v === 'string')));
+  if (!ok) throw new Error(`demande d'exécution invalide : étape ${index + 1} mal formée`);
+}
+
+function collect(stream, sink) {
+  stream.on('data', (chunk) => {
+    if (sink.bytes >= MAX_OUTPUT_BYTES) {
+      sink.truncated = true;
+      return;
+    }
+    const part = chunk.subarray(0, MAX_OUTPUT_BYTES - sink.bytes);
+    sink.chunks.push(part);
+    sink.bytes += part.length;
+    if (part.length < chunk.length) sink.truncated = true;
+  });
+}
+
+function outputText(sink) {
+  const text = Buffer.concat(sink.chunks).toString('utf8');
+  return sink.truncated ? `${text}\n[sortie tronquée à ${MAX_OUTPUT_BYTES} octets]` : text;
+}
+
+function runStep(step, { root, values }) {
+  const args = step.args.map((a) => substitute(a, values));
+  const env = Object.fromEntries(
+    Object.entries(step.env ?? {}).map(([k, v]) => [k, substitute(v, values)])
+  );
+  const cwd = path.resolve(root, step.cwd ?? '.');
+
+  return new Promise((resolve) => {
+    const out = { chunks: [], bytes: 0, truncated: false };
+    const err = { chunks: [], bytes: 0, truncated: false };
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    const child = spawn(step.command, args, {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    collect(child.stdout, out);
+    collect(child.stderr, err);
+    child.on('error', (e) =>
+      settle({ code: null, stdout: outputText(out), stderr: outputText(err), error: `lancement impossible : ${e.message}` })
+    );
+    child.on('close', (code) =>
+      settle({ code, stdout: outputText(out), stderr: outputText(err) })
+    );
+  });
+}
+
+/**
+ * Exécute les étapes d'une demande, dans l'ordre, jusqu'à la première qui échoue.
+ * Rend un résultat par étape exécutée.
+ */
+export async function runExecRequest(request, { root, gatewayUrl, gatewayToken, label = '' }) {
+  if (typeof request.id !== 'string' || !Array.isArray(request.steps) || request.steps.length === 0) {
+    throw new Error("demande d'exécution invalide : identifiant ou étapes manquants");
+  }
+  request.steps.forEach(validateStep);
+
+  const values = { GATEWAY_URL: gatewayUrl, GATEWAY_TOKEN: gatewayToken };
+  const results = [];
+  for (const step of request.steps) {
+    console.error(
+      `[mcp-mode] Exécution demandée${label ? ` par ${label}` : ''} : ${step.command} ${step.args.join(' ')}` +
+        ` (dossier : ${path.resolve(root, step.cwd ?? '.')})`
+    );
+    const result = await runStep(step, { root, values });
+    results.push(result);
+    if (result.code !== 0) break;
+  }
+  return results;
+}

package/gateway-watch.js

@@ -0,0 +1,348 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { normalizeRoute } from './gateway-exec.js';
+
+// --- Veille : réveiller l'agent quand un MCP du gateway a du nouveau ---
+//
+// Le gateway ne sait que répondre : il ne pousse rien vers l'agent. Un processus veilleur,
+// lancé sur la machine de l'AGENT par l'outil `Monitor` de son hôte, appelle donc en boucle
+// un outil d'attente du MCP, à travers l'API REST du gateway. Chaque appel reste ouvert
+// jusqu'à ce que le MCP ait un événement, ou jusqu'à expiration ; chaque événement devient
+// une ligne sur la sortie du veilleur, et `Monitor` réveille l'agent à chaque ligne.
+//
+// La convention, côté MCP :
+//
+// 1. Un outil d'activation déclare dans son schéma la propriété réservée `_gateway_watch`.
+//    Le relais la retire du schéma montré à l'agent et la remplit à chaque appel :
+//    `{ version }`. Sans elle, le MCP sait qu'aucun relais ne veillera pour lui.
+// 2. L'outil d'activation répond par une spécification de veille :
+//    `_meta["gateway/watch"] = { tool, arguments, cursor, description }` — l'outil d'attente,
+//    ses arguments fixes, le point de reprise de départ, et le libellé du `Monitor`.
+// 3. Le relais dépose, sur la machine de l'agent, un fichier de veille en 0600 : l'adresse
+//    et le jeton du gateway, la route, l'outil, ses arguments et le point de reprise. Il
+//    rend à l'agent l'appel `Monitor` qui lance le veilleur sur ce fichier. Le jeton ne
+//    figure jamais dans la commande, donc jamais dans la conversation.
+// 4. Le veilleur appelle l'outil d'attente avec `cursor` et `timeout_seconds`. L'outil
+//    répond `_meta["gateway/events"] = { cursor, lines }` : une ligne par événement, et le
+//    point de reprise suivant, que le veilleur enregistre dans le fichier de veille.
+//
+// Le fichier de veille est propre au relais qui l'écrit : il est retiré à l'arrêt du relais,
+// ou, si le relais a été tué, par le prochain relais qui démarre.
+//
+//   GATEWAY_WATCH_DIR   Dossier des fichiers de veille (défaut : ~/.mcp-http-gateway/watch).
+
+export const WATCH_ARG = '_gateway_watch';
+export const WATCH_META = 'gateway/watch';
+export const EVENTS_META = 'gateway/events';
+export const WATCH_VERSION = 1;
+
+/** Durée maximale d'un `Monitor` côté hôte. */
+export const MONITOR_TIMEOUT_MS = 1_800_000;
+
+/** Attente demandée à l'outil : sous les 60 s qu'accorde le gateway à un appel d'outil. */
+const WAIT_SECONDS = 50;
+const REQUEST_TIMEOUT_MS = (WAIT_SECONDS + 40) * 1000;
+const BACKOFF_MIN_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+
+/** Échecs consécutifs au-delà desquels l'agent est prévenu que la veille est interrompue. */
+const FAILURES_BEFORE_NOTICE = 3;
+
+const SERVER_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'server.js');
+
+export function watchDir() {
+  const override = process.env.GATEWAY_WATCH_DIR?.trim();
+  return override ? path.resolve(override) : path.join(os.homedir(), '.mcp-http-gateway', 'watch');
+}
+
+/** L'outil déclare-t-il la propriété réservée qui l'inscrit à la veille ? */
+export function declaresWatch(inputSchema) {
+  return Boolean(inputSchema?.properties && WATCH_ARG in inputSchema.properties);
+}
+
+/** L'argument réservé qui annonce au MCP que ce relais veillera pour lui. */
+export function watchAnnouncement() {
+  return { version: WATCH_VERSION };
+}
+
+/** La spécification de veille portée par un résultat d'outil, ou null. */
+export function watchSpecOf(result) {
+  const spec = result?._meta?.[WATCH_META];
+  return spec && typeof spec === 'object' ? spec : null;
+}
+
+function validateSpec(spec) {
+  const ok = typeof spec.tool === 'string' && spec.tool !== ''
+    && typeof spec.cursor === 'string'
+    && (spec.arguments === undefined || (typeof spec.arguments === 'object' && !Array.isArray(spec.arguments)))
+    && (spec.description === undefined || typeof spec.description === 'string');
+  if (!ok) throw new Error('spécification de veille invalide : outil, point de reprise ou arguments mal formés');
+}
+
+function watchFilePath(route, tool) {
+  const digest = crypto.createHash('sha256').update(`${route}\n${tool}\n${process.pid}`).digest('hex').slice(0, 16);
+  return path.join(watchDir(), `${digest}.json`);
+}
+
+function presencePath(file) {
+  return file.replace(/\.json$/, '.watcher.json');
+}
+
+/** Écrit un fichier lisible par le seul utilisateur courant, sans jamais l'exposer à moitié écrit. */
+function writePrivate(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  fs.chmodSync(temporary, 0o600);
+  fs.renameSync(temporary, file);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function processExists(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/** Veilleur vivant qui suit ce fichier de veille, ou null. */
+function activeWatcher(file) {
+  const presence = readJson(presencePath(file));
+  return presence && typeof presence.pid === 'number' && processExists(presence.pid) ? presence : null;
+}
+
+/** Commande du veilleur : le même Node et le même paquet que ce relais. */
+export function watchCommand(file) {
+  const quote = (value) => `"${value.replace(/\\/g, '/')}"`;
+  return `${quote(process.execPath)} ${quote(SERVER_SCRIPT)} --watch ${quote(file)}`;
+}
+
+/** Fichiers de veille écrits par ce relais, retirés à son arrêt. */
+const written = new Set();
+
+/**
+ * Dépose le fichier de veille d'une spécification et rend le résultat à montrer à l'agent :
+ * l'appel `Monitor` à faire, ou le rappel qu'un veilleur tourne déjà.
+ */
+export function armWatch(spec, { route, gatewayUrl, gatewayToken }) {
+  validateSpec(spec);
+  const canonicalRoute = normalizeRoute(route);
+  const file = watchFilePath(canonicalRoute, spec.tool);
+  const command = watchCommand(file);
+  const description = spec.description ?? `Événements de ${canonicalRoute}`;
+
+  const watcher = activeWatcher(file);
+  if (watcher) {
+    // Le veilleur en place tient son propre point de reprise : réécrire le fichier le ferait
+    // repartir de celui du MCP et sauter les événements survenus entre-temps.
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          `Les notifications de ${canonicalRoute} sont déjà actives (veilleur armé depuis ${watcher.since}).`,
+          'Rien à faire : continuez, les événements vous interrompront d’eux-mêmes.',
+          'N’armez pas de second veilleur. Seulement si l’hôte vient de signaler que le veilleur a expiré',
+          `ou s’est arrêté, réarmez-le avec le même appel Monitor (command ${command}, timeout_ms ${MONITOR_TIMEOUT_MS}).`,
+        ].join('\n'),
+      }],
+    };
+  }
+
+  writePrivate(file, {
+    version: WATCH_VERSION,
+    gatewayUrl,
+    gatewayToken: gatewayToken ?? null,
+    route: canonicalRoute,
+    tool: spec.tool,
+    arguments: spec.arguments ?? {},
+    cursor: spec.cursor,
+    relay_pid: process.pid,
+    written_at: new Date().toISOString(),
+  });
+  written.add(file);
+  pruneOrphanWatches();
+
+  return {
+    content: [{
+      type: 'text',
+      text: [
+        `Notifications activées pour ${canonicalRoute}.`,
+        '',
+        'Dernière étape — appelez maintenant l’outil Monitor avec exactement ces arguments :',
+        `  command:     ${command}`,
+        `  description: ${description}`,
+        `  timeout_ms:  ${MONITOR_TIMEOUT_MS}`,
+        '',
+        'Tant que ce veilleur n’est pas armé, aucun événement ne vous parviendra. Une fois armé,',
+        'continuez normalement : chaque événement arrive de lui-même, une ligne par événement.',
+        '',
+        'L’hôte arrête tout Monitor au bout de 30 minutes au plus. À chaque expiration signalée,',
+        'rappelez aussitôt Monitor avec les mêmes arguments, sans rappeler l’outil d’activation :',
+        'le veilleur reprend là où il s’était arrêté.',
+      ].join('\n'),
+    }],
+  };
+}
+
+/** Retire les fichiers de veille de ce relais. Synchrone : appelable sur `exit`. */
+export function removeOwnWatches() {
+  for (const file of written) {
+    fs.rmSync(file, { force: true });
+    fs.rmSync(presencePath(file), { force: true });
+  }
+  written.clear();
+}
+
+/**
+ * Retire les fichiers de veille dont le relais n'existe plus, et les présences dont le
+ * veilleur n'existe plus : ils restent après un processus tué sans pouvoir faire son ménage.
+ */
+export function pruneOrphanWatches() {
+  const dir = watchDir();
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir)) {
+    const file = path.join(dir, entry);
+    if (entry.endsWith('.watcher.json')) {
+      const presence = readJson(file);
+      if (typeof presence?.pid !== 'number' || !processExists(presence.pid)) fs.rmSync(file, { force: true });
+      continue;
+    }
+    if (!entry.endsWith('.json')) continue;
+    const watch = readJson(file);
+    if (typeof watch?.relay_pid !== 'number' || !processExists(watch.relay_pid)) {
+      fs.rmSync(file, { force: true });
+      fs.rmSync(presencePath(file), { force: true });
+    }
+  }
+}
+
+// --- Le veilleur (server.js --watch <fichier>) ---
+
+class WatchError extends Error {
+  /** `lasting` : l'erreur ne se résoudra pas d'elle-même, l'agent doit être prévenu tout de suite. */
+  constructor(message, lasting = false) {
+    super(message);
+    this.lasting = lasting;
+  }
+}
+
+function readWatchFile(file) {
+  const watch = readJson(file);
+  if (!watch || typeof watch.gatewayUrl !== 'string' || typeof watch.route !== 'string'
+    || typeof watch.tool !== 'string' || typeof watch.cursor !== 'string') {
+    throw new Error(
+      `fichier de veille illisible ou absent : ${file}. Rappelez l’outil qui active les notifications, ` +
+        'puis armez le veilleur avec la commande qu’il renvoie.'
+    );
+  }
+  return watch;
+}
+
+/** Enregistre le point de reprise, sans recréer un fichier que le relais a retiré. */
+function saveCursor(file, cursor) {
+  const watch = readJson(file);
+  if (watch) writePrivate(file, { ...watch, cursor });
+}
+
+async function poll(watch, cursor) {
+  const label = `${watch.route}/${watch.tool}`;
+  const headers = { 'Content-Type': 'application/json' };
+  if (watch.gatewayToken) headers.Authorization = `Bearer ${watch.gatewayToken}`;
+
+  let res;
+  try {
+    res = await fetch(`${watch.gatewayUrl}${watch.route}/tools/${encodeURIComponent(watch.tool)}`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ ...watch.arguments, cursor, timeout_seconds: WAIT_SECONDS }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw new WatchError(`gateway injoignable (${err.cause?.message ?? err.message})`);
+  }
+  if (res.status === 401 || res.status === 403) {
+    throw new WatchError(`accès refusé par le gateway (HTTP ${res.status}) : vérifiez le GATEWAY_TOKEN du relais`, true);
+  }
+  if (!res.ok) throw new WatchError(`le gateway répond HTTP ${res.status} à ${label}`);
+
+  const result = await res.json();
+  if (result.isError) {
+    const detail = result.content?.map((c) => c.text).filter(Boolean).join(' ') || 'erreur sans détail';
+    throw new WatchError(`${label} a échoué : ${detail}`);
+  }
+  const events = result._meta?.[EVENTS_META];
+  if (!events || typeof events.cursor !== 'string' || !Array.isArray(events.lines)) {
+    throw new WatchError(`${label} ne renvoie pas _meta["${EVENTS_META}"] : ce n’est pas un outil de veille`, true);
+  }
+  return events;
+}
+
+/**
+ * Boucle du veilleur. Une ligne sur stdout = un événement ; journal et erreurs sur stderr.
+ * Une panne se traduit par un réessai avec temporisation croissante, jamais par une sortie :
+ * un veilleur mort est un agent qui se croit prévenu et ne l'est plus. Une panne qui dure,
+ * ou qui ne se résoudra pas seule, est annoncée une fois sur stdout.
+ */
+export async function runWatchMode(file, { write = (line) => process.stdout.write(`${line}\n`), shouldStop } = {}) {
+  if (!file) {
+    throw new Error('--watch attend le chemin du fichier de veille donné par l’outil qui active les notifications.');
+  }
+  const watch = readWatchFile(file);
+  const label = `${watch.route}/${watch.tool}`;
+
+  const presence = presencePath(file);
+  writePrivate(presence, { pid: process.pid, since: new Date().toISOString() });
+  const unmark = () => {
+    if (readJson(presence)?.pid === process.pid) fs.rmSync(presence, { force: true });
+  };
+  process.on('exit', unmark);
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => process.exit(0));
+  console.error(`[gateway-watch] Veille de ${label} via ${watch.gatewayUrl}`);
+
+  let cursor = watch.cursor;
+  let backoff = BACKOFF_MIN_MS;
+  let failures = 0;
+  let announced = false;
+  try {
+    while (!shouldStop?.()) {
+      try {
+        const events = await poll(watch, cursor);
+        if (announced) write(`[gateway-watch] ${label} : la veille a repris.`);
+        failures = 0;
+        announced = false;
+        backoff = BACKOFF_MIN_MS;
+        for (const line of events.lines) write(String(line).replace(/\s+/g, ' ').trim());
+        if (events.cursor !== cursor) {
+          cursor = events.cursor;
+          saveCursor(file, cursor);
+        }
+      } catch (err) {
+        failures++;
+        console.error(`[gateway-watch] ${err.message} — nouvel essai dans ${Math.round(backoff / 1000)} s`);
+        if (!announced && (err.lasting || failures >= FAILURES_BEFORE_NOTICE)) {
+          write(
+            `[gateway-watch] ${label} : la veille échoue (${err.message}). Elle réessaie seule ; ` +
+              'aucune notification n’arrivera tant que ça dure.'
+          );
+          announced = true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, backoff));
+        backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+      }
+    }
+  } finally {
+    unmark();
+  }
+}

package/http-relay.js

@@ -0,0 +1,93 @@
+import http from 'http';
+
+// Directive gateway déclarée par un MCP dans son bloc `env` : le MCP écoute en HTTP
+// sur 127.0.0.1:<port>, et le gateway lui relaie tel quel `<route>/http/*`.
+export const HTTP_RELAY_PORT_KEY = 'MCP_HTTP_RELAY_PORT';
+
+// En-têtes propres à un saut de connexion : jamais retransmis par un relais.
+const HOP_BY_HOP = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+  'te', 'trailer', 'transfer-encoding', 'upgrade', 'host',
+]);
+
+/**
+ * Lit la directive MCP_HTTP_RELAY_PORT d'un MCP.
+ * Absente → `{ port: null, valid: true }` ; présente mais hors 1–65535 → `valid: false`.
+ */
+export function parseRelayPort(raw) {
+  if (raw === undefined || raw === '') return { port: null, valid: true };
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return { port: null, valid: false };
+  return { port, valid: true };
+}
+
+export function relayPrefix(route) {
+  return `${route}/http`;
+}
+
+/**
+ * Indique si un chemin appartient à l'un des préfixes de relais. Ces requêtes
+ * gardent leur corps intact : il est transmis au MCP sans être lu ni décodé.
+ */
+export function isRelayPath(prefixes, reqPath) {
+  for (const prefix of prefixes) {
+    if (reqPath === prefix || reqPath.startsWith(`${prefix}/`)) return true;
+  }
+  return false;
+}
+
+function forwardedRequestHeaders(headers) {
+  const out = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (HOP_BY_HOP.has(key)) continue;
+    // Le jeton qui autorise l'accès au gateway ne concerne pas le MCP.
+    if (key === 'authorization') continue;
+    // Le gateway a déjà répondu « 100 Continue » au client.
+    if (key === 'expect') continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+function forwardedResponseHeaders(headers) {
+  const out = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (HOP_BY_HOP.has(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Middleware express, monté sur `<route>/http` : relaie la requête vers
+ * http://127.0.0.1:<port><reste du chemin>, corps et réponse transmis en flux.
+ */
+export function createHttpRelay({ name, port }) {
+  return (req, res) => {
+    const upstream = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        method: req.method,
+        path: req.url,
+        headers: forwardedRequestHeaders(req.headers),
+      },
+      (upstreamRes) => {
+        res.writeHead(upstreamRes.statusCode ?? 502, forwardedResponseHeaders(upstreamRes.headers));
+        upstreamRes.pipe(res);
+      }
+    );
+
+    upstream.on('error', (err) => {
+      console.error(`[${name}] HTTP relay error (127.0.0.1:${port}):`, err.message);
+      if (!res.headersSent) {
+        res.status(502).json({ error: `HTTP relay to "${name}" failed: ${err.message}` });
+      } else {
+        res.destroy(err);
+      }
+    });
+
+    res.on('close', () => upstream.destroy());
+    req.pipe(upstream);
+  };
+}