@imenam/simple-scraper 1.0.18 → 1.0.19

package/README.md

@@ -90,6 +90,23 @@ PUPPETEER_DEVICE_SCALE_FACTOR=1
 # APP_GROUP=Scraping
 ```
 
+### The process environment wins over `.env`
+
+Any variable already set in the environment of the process that starts this MCP
+(a shell `export`, a `claude_desktop_config.json` `env` block, or a supervisor
+such as `@imenam/mcp-gateway-manager`) **takes precedence over the same key in
+this repository's `.env`**. This is dotenv's default behaviour, and the usual
+Unix convention: the caller wins.
+
+The `.env` is still reloaded on the fly — the GUI writes to it and the change is
+picked up without restarting the server — but that reload can no longer clobber
+what the caller injected. Concretely, an `APP_GROUP=Scraping` line in this
+`.env` no longer overrides an `APP_GROUP` passed in by a supervisor; it only
+applies when nobody passed one.
+
+To change a variable that the caller provides, change it where the caller sets
+it; editing `.env` will have no effect on that key.
+
 ## Usage with Claude Desktop
 
 Add the following to your `claude_desktop_config.json`. Full example with all available options:

package/dist/env-precedence.js

@@ -0,0 +1,51 @@
+/**
+ * Chargement du `.env` du dépôt, sans jamais écraser l'environnement du process.
+ *
+ * ## Le problème
+ *
+ * Ce MCP rechargeait son `.env` avec `dotenv.config({ override: true })`, au
+ * démarrage et à chaque `reloadEnv` du `GuiLauncher`. C'est délibéré : la GUI
+ * écrit dans le `.env` et le code relit la valeur sans redémarrer le process.
+ * Sans `override`, dotenv ignore toute clé déjà présente dans `process.env` —
+ * donc la deuxième lecture ne verrait jamais rien changer.
+ *
+ * Mais `override: true` écrase **aussi** ce qu'un superviseur a injecté. Quand
+ * le hub `mcp-gateway-manager` lance ce MCP en lui passant `APP_GROUP`,
+ * `PROXY_URL` ou `APP_PATH_PREFIX` dans son bloc `env`, le `.env` du dépôt
+ * reprenait la main et l'injection échouait **silencieusement**.
+ *
+ * ## La règle appliquée ici
+ *
+ * Une variable **déjà présente dans l'environnement du process au démarrage**
+ * l'emporte sur le `.env` du dépôt — c'est le comportement par défaut de dotenv,
+ * et la convention de tout l'écosystème Unix : l'appelant gagne.
+ *
+ * L'`override` n'est pas supprimé pour autant, il est **restreint** : il reste
+ * entier pour toutes les variables que le process n'a pas héritées, c'est-à-dire
+ * exactement celles que l'interface graphique édite dans le `.env`. On ne perd
+ * donc pas le rechargement à chaud, on l'empêche seulement de piétiner
+ * l'appelant.
+ *
+ * L'instantané est pris à l'évaluation de ce module : il doit donc être importé
+ * avant tout appel à `dotenv.config`.
+ */
+import dotenv from 'dotenv';
+/** Environnement du process **avant** tout chargement de `.env`. */
+const inherited = Object.freeze(Object.fromEntries(Object.entries(process.env).filter((entry) => typeof entry[1] === 'string')));
+/** La variable vient-elle de l'appelant (superviseur, shell) plutôt que du `.env` ? */
+export function isInheritedFromProcess(key) {
+    return Object.prototype.hasOwnProperty.call(inherited, key);
+}
+/**
+ * Charge un fichier `.env` en écrasant les valeurs déjà lues depuis ce fichier,
+ * mais **jamais** celles héritées de l'environnement du process.
+ */
+export function loadEnvFile(options) {
+    // Le résultat peut être absent quand dotenv est remplacé par un test double.
+    const result = dotenv.config({ ...options, override: true });
+    for (const key of Object.keys(result?.parsed ?? {})) {
+        const value = inherited[key];
+        if (value !== undefined)
+            process.env[key] = value;
+    }
+}

package/dist/index.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import dotenv from 'dotenv';
+// Importé AVANT tout appel à dotenv : ce module prend l'instantané de
+// l'environnement hérité du process, qui doit primer sur le `.env` du dépôt.
+import { loadEnvFile } from './env-precedence.js';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -21,11 +23,14 @@ if (process.argv.slice(2).includes('--claude-setup-mcp')) {
     const { runSetupMcp } = await import('./cli/setup-mcp.js');
     process.exit(runSetupMcp({ cwd: process.cwd(), force: process.argv.slice(2).includes('--force') }));
 }
-dotenv.config({ path: envPath, override: true });
+// `override` restreint : la GUI peut toujours éditer le `.env` et voir l'effet
+// sans redémarrage, mais une variable injectée par un superviseur (`PROXY_URL`,
+// `APP_GROUP`, `APP_PATH_PREFIX`…) reste intacte. Voir ./env-precedence.ts.
+loadEnvFile({ path: envPath });
 setupLogging('MASTER');
 const launcher = new GuiLauncher({
     guiPath: path.join(__dirname, 'gui.js'),
-    reloadEnv: () => dotenv.config({ path: envPath, override: true }),
+    reloadEnv: () => loadEnvFile({ path: envPath }),
     onMessage: (msg) => {
         if (msg.type === 'STOP') {
             process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/simple-scraper",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "MCP server for web scraping and JavaScript execution using Puppeteer",
   "type": "module",
   "main": "dist/index.js",