@mcp-abap-adt/proxy 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-09-24
+
+**The management mode can now say which credentials are available, and start a
+proxy with one.** A config says which service to reach; an environment says what
+to authenticate with. Both are chosen by name, so a client picks them without
+being told any paths.
+
+### Added
+
+- **`proxy_environments`** — lists the environments in `sessions/`, one SAP
+  system's credentials each, by the name `proxy_start` takes. Variable **names**
+  only, never values: this is read to help a client choose, and a value here
+  would be a credential in a tool result. `*.env.template` and anything that is
+  not a `.env` are left out.
+
+- **`environment` on `proxy_start`** — optional, and the reason it exists: a
+  config that references `${SAP_LOGIN}` without naming an `envFile:` of its own
+  had nowhere to get it from, so `proxy_start` failed on exactly the configs a
+  user runs with `--env-file` on the command line. A name, not a path, for the
+  same reason `config` is a name: `sessions/` sits beside `proxy/` and
+  `service-keys/`.
+
+  One `--env-file` on the management process would not have served: it overrides
+  every config's own `envFile:`, so one system's secrets would reach every other
+  system started in that session. Per call, it cannot.
+
+- `loadConfig(configPath, envFileOverride)` carries it. Precedence, most
+  specific first: this argument, then `--env-file`, then the config's own
+  `envFile:`.
+
+### Unchanged, and deliberately
+
+The management mode speaks **stdio only** — no `--transport`, and it listens on
+no port of its own. That is the whole point: the client runs it as a child
+process, and when the client goes the stdio closes and every proxy it started
+goes with it. Over HTTP it would outlive its client and leave ports and tokens
+held, which would be worse than starting proxies by hand.
+
+## [4.0.1] - 2026-09-24
+
+**A variable from an env file could be silently lost, and the failure blamed the
+variable instead of naming the file.** Both hit Windows hardest, with the same
+config and the same `.env` that work on Linux.
+
+### Fixed
+
+- **An empty environment variable no longer shadows the env file.** The lookup
+  was `process.env[key] ?? envFileMap[key]`, and `??` skips only `undefined` — so
+  a `SAP_LOGIN=` sitting in the environment beat the file the user had pointed at
+  with `--env-file`, and the header went out empty with nothing reported. Windows
+  carries variables nobody set deliberately, which is why the same files behaved
+  differently there. A real value in the environment still wins.
+
+- **The interpolation failure now names where it looked.** It said only
+  `Config references undefined env variable: SAP_LOGIN`, so three different
+  causes produced one sentence and the cause had to be guessed:
+
+  ```
+  ... looked in process.env only — no env file was given (--env-file or envFile:)
+  ... looked in process.env, then /path/e19.env, which yielded NO variables
+      (0 bytes) — check its encoding, since a UTF-16 file reads as nothing here
+  ... looked in process.env, then /path/e19.env (1: SAP_PASSWORD)
+  ```
+
+  An env file that yields nothing is still not an error — an empty `.env` is
+  legitimate, and a config may take every value from the environment. It is
+  reported by whoever then needs a variable, where it can be said usefully.
+
+### Documentation
+
+- `docs/YAML_CONFIG.md`: a Windows path in **double** quotes is a YAML escape
+  context. `envFile: "C:\Users\..."` fails to parse (`\U` is a Unicode escape)
+  and `"C:\temp\e19.env"` parses *silently wrong* (`\e` becomes 0x1B). Use
+  single quotes, no quotes, or forward slashes.
+
 ## [4.0.0] - 2026-09-24
 
 **The proxy stops re-implementing the broker, there is one forwarding path

package/README.md

@@ -76,7 +76,8 @@ than travelling through a tool call.
 | Tool | What it does |
 |---|---|
 | `proxy_configs` | Lists the configs available, by the name `proxy_start` takes. Call it first — the names cannot be guessed. |
-| `proxy_start` | Starts a proxy from one of those configs and returns the URL it bound. The **port is not taken from the config**: a free one is bound instead. |
+| `proxy_environments` | Lists the environments available — one SAP system's credentials each, by the name `proxy_start` takes. Variable NAMES only, never values. |
+| `proxy_start` | Starts a proxy from a config and, when the config needs one, an environment. Returns the URL it bound. The **port is not taken from the config**: a free one is bound instead. |
 | `proxy_stop` | Stops a proxy this session started, freeing its port and releasing its credential. Proxies started by other sessions are never touched. |
 | `proxy_status` | Lists this session's proxies and any others on this machine. Records whose process has died are pruned when read, so it cannot report a ghost. |
 

package/bin/mcp-abap-adt-proxy-mcp.js

@@ -37,7 +37,11 @@ Tools offered to the client:
   proxy_configs  List the proxy configs on this machine, by the name
                  proxy_start takes. Call this first — the names cannot be
                  guessed.
-  proxy_start    Start a proxy from one of those configs. The config supplies
+  proxy_environments
+                 List the environments — one SAP system's credentials each,
+                 from sessions/. Variable NAMES only, never values.
+  proxy_start    Start a proxy from a config plus, when the config needs one,
+                 an environment. The config supplies
                  the destination, target URL, default headers and timeouts;
                  the PORT does not come from it — a free one is bound, so
                  several proxies can run at once, and the URL returned is the

package/dist/lib/config.d.ts

@@ -27,7 +27,18 @@ export interface ProxyConfig {
  * - If --config is provided, load ONLY from that file
  * - If --config is NOT provided, load ONLY from command line parameters and environment variables
  */
-export declare function loadConfig(configPath?: string): ProxyConfig;
+export declare function loadConfig(configPath?: string, 
+/**
+ * The env file for THIS load, ahead of `--env-file` and the config's own
+ * `envFile:`.
+ *
+ * The MCP mode starts a proxy from a config plus an ENVIRONMENT chosen by
+ * name, and has no command line of its own to put `--env-file` on. One flag on
+ * the management process would not serve either: it overrides every config's
+ * own `envFile:`, so one system's secrets would reach every other system
+ * started in that session.
+ */
+envFileOverride?: string): ProxyConfig;
 /**
  * Transport-related fields from config file (not part of ProxyConfig but needed by transportConfig)
  */

package/dist/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IAEjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGxC,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAG/B,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW,CAoC3D;AAwED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,mBAAmB,CAQrB;AAkCD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYhC;AAmJD;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAUD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAoDA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IAEjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGxC,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAG/B,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,UAAU,CAAC,EAAE,MAAM;AACnB;;;;;;;;;GASG;AACH,eAAe,CAAC,EAAE,MAAM,GACvB,WAAW,CAkDb;AAwED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,mBAAmB,CAQrB;AAsCD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYhC;AAmJD;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAUD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAoDA"}

package/dist/lib/config.js

@@ -53,7 +53,18 @@ const envInterpolation_js_1 = require("./envInterpolation.js");
  * - If --config is provided, load ONLY from that file
  * - If --config is NOT provided, load ONLY from command line parameters and environment variables
  */
-function loadConfig(configPath) {
+function loadConfig(configPath, 
+/**
+ * The env file for THIS load, ahead of `--env-file` and the config's own
+ * `envFile:`.
+ *
+ * The MCP mode starts a proxy from a config plus an ENVIRONMENT chosen by
+ * name, and has no command line of its own to put `--env-file` on. One flag on
+ * the management process would not serve either: it overrides every config's
+ * own `envFile:`, so one system's secrets would reach every other system
+ * started in that session.
+ */
+envFileOverride) {
     // Get config path from parameter or command line (--config/-c)
     // Do NOT use environment variable MCP_PROXY_CONFIG - only explicit --config parameter
     const finalConfigPath = configPath || getConfigPath();
@@ -65,10 +76,18 @@ function loadConfig(configPath) {
                 throw new Error(`Config file not found: ${finalConfigPath}`);
             }
             const fileConfig = loadConfigFile(finalConfigPath);
-            const envFilePath = resolveEnvFilePath(fileConfig, finalConfigPath);
+            const envFilePath = resolveEnvFilePath(fileConfig, finalConfigPath, envFileOverride);
             const envFileMap = envFilePath ? (0, envInterpolation_js_1.loadEnvFile)(envFilePath) : {};
             const lookup = (0, envInterpolation_js_1.buildLookup)(envFileMap);
-            const interpolated = (0, envInterpolation_js_1.interpolateConfig)(fileConfig, lookup);
+            const keys = Object.keys(envFileMap);
+            const sources = !envFilePath
+                ? 'process.env only — no env file was given (--env-file or envFile:)'
+                : keys.length === 0
+                    ? `process.env, then ${envFilePath}, which yielded NO variables ` +
+                        `(${fs.statSync(envFilePath).size} bytes) — check its encoding, ` +
+                        `since a UTF-16 file reads as nothing here, and that lines look like KEY=value`
+                    : `process.env, then ${envFilePath} (${keys.length}: ${keys.join(', ')})`;
+            const interpolated = (0, envInterpolation_js_1.interpolateConfig)(fileConfig, lookup, '', sources);
             delete interpolated.envFile;
             const base = applyDefaults(interpolated);
             const cli = readCliOverrides();
@@ -166,7 +185,11 @@ function loadConfigFile(filePath) {
  * cwd); otherwise the YAML `envFile` field, resolved relative to the config
  * file's directory. Returns undefined when neither is set.
  */
-function resolveEnvFilePath(rawConfig, configPath) {
+function resolveEnvFilePath(rawConfig, configPath, override) {
+    // Most specific first: this call, then the command line, then what the config
+    // says about itself.
+    if (override !== undefined)
+        return path.resolve(override);
     const cliEnvFile = getArgValue('--env-file');
     if (cliEnvFile !== undefined)
         return path.resolve(cliEnvFile);

package/dist/lib/envInterpolation.d.ts

@@ -8,14 +8,16 @@
  * default when one is given. A ${VAR} without a default that resolves to
  * undefined throws, naming the variable and the field it came from.
  */
-export declare function interpolateString(input: string, lookup: (key: string) => string | undefined, fieldPath: string): string;
+export declare function interpolateString(input: string, lookup: (key: string) => string | undefined, fieldPath: string, 
+/** Where values were looked for, named in the failure. */
+sources?: string): string;
 /**
  * Recursively interpolate all string values in a parsed config object.
  * Objects/arrays are walked; non-string scalars are returned unchanged.
  * The field path (e.g. `defaultHeaders.x-sap-password`) is threaded through for
  * error messages.
  */
-export declare function interpolateConfig(value: unknown, lookup: (key: string) => string | undefined, path?: string): unknown;
+export declare function interpolateConfig(value: unknown, lookup: (key: string) => string | undefined, path?: string, sources?: string): unknown;
 /**
  * Parse a .env file into a flat map. Throws if the path is given but missing —
  * a specified-yet-absent secret source is a configuration error, not a no-op.
@@ -23,6 +25,16 @@ export declare function interpolateConfig(value: unknown, lookup: (key: string)
 export declare function loadEnvFile(envFilePath: string): Record<string, string>;
 /**
  * Build a lookup over process.env (highest priority) then the parsed .env map.
+ *
+ * An EMPTY environment variable does not count as a value. It used to: `??`
+ * skips only `undefined`, so a `SAP_LOGIN=` sitting in the environment won
+ * against the env file the user had explicitly pointed at with `--env-file`,
+ * and the header went out empty with nothing reported. Windows carries
+ * variables nobody set deliberately, which is why the same config and the same
+ * `.env` behaved differently there.
+ *
+ * A real value in the environment still wins — that is the documented
+ * precedence, and it is how a one-off override is meant to work.
  */
 export declare function buildLookup(envFileMap: Record<string, string>): (key: string) => string | undefined;
 //# sourceMappingURL=envInterpolation.d.ts.map

package/dist/lib/envInterpolation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envInterpolation.d.ts","sourceRoot":"","sources":["../../src/lib/envInterpolation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC3C,SAAS,EAAE,MAAM,GAChB,MAAM,CAiBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC3C,IAAI,SAAK,GACR,OAAO,CAiBT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKvE;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAGrC"}
+{"version":3,"file":"envInterpolation.d.ts","sourceRoot":"","sources":["../../src/lib/envInterpolation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC3C,SAAS,EAAE,MAAM;AACjB,0DAA0D;AAC1D,OAAO,SAAgB,GACtB,MAAM,CAsBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC3C,IAAI,SAAK,EACT,OAAO,SAAgB,GACtB,OAAO,CAsBT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAQrC"}

package/dist/lib/envInterpolation.js

@@ -50,7 +50,9 @@ const PLACEHOLDER = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
  * default when one is given. A ${VAR} without a default that resolves to
  * undefined throws, naming the variable and the field it came from.
  */
-function interpolateString(input, lookup, fieldPath) {
+function interpolateString(input, lookup, fieldPath, 
+/** Where values were looked for, named in the failure. */
+sources = 'process.env') {
     return input.replace(PLACEHOLDER, (_match, name, defaultVal) => {
         const value = lookup(name);
         const isEmpty = value === undefined || value === '';
@@ -58,7 +60,12 @@ function interpolateString(input, lookup, fieldPath) {
             return isEmpty ? defaultVal : value;
         }
         if (value === undefined) {
-            throw new Error(`Config references undefined env variable: ${name} (referenced in ${fieldPath})`);
+            // Naming where it looked, because the old message named only the
+            // variable — so a file never read, a file read empty, and a value
+            // shadowed by the environment all produced the same sentence and the
+            // cause had to be guessed.
+            throw new Error(`Config references undefined env variable: ${name} ` +
+                `(referenced in ${fieldPath}; looked in ${sources})`);
         }
         return value;
     });
@@ -69,17 +76,17 @@ function interpolateString(input, lookup, fieldPath) {
  * The field path (e.g. `defaultHeaders.x-sap-password`) is threaded through for
  * error messages.
  */
-function interpolateConfig(value, lookup, path = '') {
+function interpolateConfig(value, lookup, path = '', sources = 'process.env') {
     if (typeof value === 'string') {
-        return interpolateString(value, lookup, path || '(root)');
+        return interpolateString(value, lookup, path || '(root)', sources);
     }
     if (Array.isArray(value)) {
-        return value.map((item, i) => interpolateConfig(item, lookup, `${path}[${i}]`));
+        return value.map((item, i) => interpolateConfig(item, lookup, `${path}[${i}]`, sources));
     }
     if (value !== null && typeof value === 'object') {
         const out = {};
         for (const [key, val] of Object.entries(value)) {
-            out[key] = interpolateConfig(val, lookup, path ? `${path}.${key}` : key);
+            out[key] = interpolateConfig(val, lookup, path ? `${path}.${key}` : key, sources);
         }
         return out;
     }
@@ -93,11 +100,31 @@ function loadEnvFile(envFilePath) {
     if (!fs.existsSync(envFilePath)) {
         throw new Error(`env file not found: ${envFilePath}`);
     }
+    // Not an error when it yields nothing: an empty `.env` is legitimate, and a
+    // config may take every value from the environment. But the emptiness is
+    // reported by whoever needs a variable — see the `sources` note threaded into
+    // the interpolation failure, which names the file, its size and its key count.
     return dotenv.parse(fs.readFileSync(envFilePath, 'utf-8'));
 }
 /**
  * Build a lookup over process.env (highest priority) then the parsed .env map.
+ *
+ * An EMPTY environment variable does not count as a value. It used to: `??`
+ * skips only `undefined`, so a `SAP_LOGIN=` sitting in the environment won
+ * against the env file the user had explicitly pointed at with `--env-file`,
+ * and the header went out empty with nothing reported. Windows carries
+ * variables nobody set deliberately, which is why the same config and the same
+ * `.env` behaved differently there.
+ *
+ * A real value in the environment still wins — that is the documented
+ * precedence, and it is how a one-off override is meant to work.
  */
 function buildLookup(envFileMap) {
-    return (key) => process.env[key] ?? envFileMap[key];
+    return (key) => {
+        const fromEnvironment = process.env[key];
+        if (fromEnvironment !== undefined && fromEnvironment !== '') {
+            return fromEnvironment;
+        }
+        return envFileMap[key];
+    };
 }

package/dist/mcp/environments.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One environment: a `.env` beside the configs, holding one SAP system's
+ * credentials.
+ *
+ * A config names the service to reach; an environment names the credentials to
+ * reach it with. They are separate because several configs commonly point at one
+ * system — four of the configs in practice all want `e19` — and one config can
+ * be run against different systems.
+ */
+export interface EnvironmentEntry {
+    /** The file name without its extension — what a client asks for. */
+    name: string;
+    file: string;
+    /**
+     * Which variables it defines. Names only, never values: this is read to help
+     * a client choose, and a value here would be a credential in a tool result.
+     */
+    variables: string[];
+}
+/** Where the environments live, beside `proxy/` and `service-keys/`. */
+export declare function environmentDir(): string;
+/**
+ * The environments on disk.
+ *
+ * One that cannot be read is still listed, with no variables beside it — hiding
+ * it would make "no such environment" the answer for a file sitting right there.
+ */
+export declare function listEnvironments(dir?: string): EnvironmentEntry[];
+/**
+ * The file an environment name refers to.
+ *
+ * A name, never a path: `sessions/` sits beside `proxy/` and `service-keys/`,
+ * and the value comes from a language model.
+ */
+export declare function resolveEnvironment(name: string, dir?: string): string;
+//# sourceMappingURL=environments.d.ts.map

package/dist/mcp/environments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environments.d.ts","sourceRoot":"","sources":["../../src/mcp/environments.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,wEAAwE;AACxE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAyB,GAC7B,gBAAgB,EAAE,CAgCpB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAyB,GAC7B,MAAM,CAmBR"}

package/dist/mcp/environments.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.environmentDir = environmentDir;
+exports.listEnvironments = listEnvironments;
+exports.resolveEnvironment = resolveEnvironment;
+// src/mcp/environments.ts
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const stores_js_1 = require("../lib/stores.js");
+/** Where the environments live, beside `proxy/` and `service-keys/`. */
+function environmentDir() {
+    return (0, stores_js_1.storeDir)('sessions');
+}
+/**
+ * The environments on disk.
+ *
+ * One that cannot be read is still listed, with no variables beside it — hiding
+ * it would make "no such environment" the answer for a file sitting right there.
+ */
+function listEnvironments(dir = environmentDir()) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    const entries = [];
+    for (const name of (0, node_fs_1.readdirSync)(dir).sort()) {
+        // `.env` exactly: this leaves out `e19.env.template`, whose extension is
+        // `.template`, along with notes and anything else kept in the folder.
+        if (path.extname(name).toLowerCase() !== '.env')
+            continue;
+        const file = path.join(dir, name);
+        try {
+            if (!(0, node_fs_1.statSync)(file).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const entry = {
+            name: path.basename(name, '.env'),
+            file,
+            variables: [],
+        };
+        try {
+            for (const line of (0, node_fs_1.readFileSync)(file, 'utf-8').split(/\r?\n/)) {
+                const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+                if (match)
+                    entry.variables.push(match[1]);
+            }
+        }
+        catch {
+            // Listed with no variables. Whoever starts a proxy with it gets the real
+            // failure, against a name the caller chose.
+        }
+        entries.push(entry);
+    }
+    return entries;
+}
+/**
+ * The file an environment name refers to.
+ *
+ * A name, never a path: `sessions/` sits beside `proxy/` and `service-keys/`,
+ * and the value comes from a language model.
+ */
+function resolveEnvironment(name, dir = environmentDir()) {
+    if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+        throw new Error(`Invalid environment name "${name}": it must be a name from ${dir}, not a path.`);
+    }
+    const available = listEnvironments(dir);
+    const found = available.find((entry) => entry.name === name || path.basename(entry.file) === name);
+    if (found)
+        return found.file;
+    const known = available.map((entry) => entry.name).join(', ');
+    throw new Error(known
+        ? `No environment named "${name}" in ${dir}. Available: ${known}`
+        : `No environments found in ${dir}.`);
+}

package/dist/mcp/tools.d.ts

@@ -24,5 +24,5 @@ export interface ProxyTool {
     inputSchema: z.ZodRawShape;
     handler: (args: Record<string, unknown>) => Promise<ToolResult>;
 }
-export declare function createProxyTools(supervisor: ProxySupervisor, configDir?: string): ProxyTool[];
+export declare function createProxyTools(supervisor: ProxySupervisor, configDir?: string, envDir?: string): ProxyTool[];
 //# sourceMappingURL=tools.d.ts.map

package/dist/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,QAGc,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACjE;AAMD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,eAAe,EAC3B,SAAS,GAAE,MAAyB,GACnC,SAAS,EAAE,CA2Jb"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,QAGc,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACjE;AAMD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,eAAe,EAC3B,SAAS,GAAE,MAAyB,EACpC,MAAM,GAAE,MAAyB,GAChC,SAAS,EAAE,CAmMb"}

package/dist/mcp/tools.js

@@ -6,6 +6,7 @@ exports.createProxyTools = createProxyTools;
 const zod_1 = require("zod");
 const config_js_1 = require("../lib/config.js");
 const configs_js_1 = require("./configs.js");
+const environments_js_1 = require("./environments.js");
 const supervisor_js_1 = require("./supervisor.js");
 /**
  * The thing the client has to keep being told.
@@ -23,8 +24,30 @@ exports.SHUTDOWN_REMINDER = 'When you are finished with this proxy, call proxy_s
 const text = (body) => ({
     content: [{ type: 'text', text: body }],
 });
-function createProxyTools(supervisor, configDir = (0, configs_js_1.proxyConfigDir)()) {
+function createProxyTools(supervisor, configDir = (0, configs_js_1.proxyConfigDir)(), envDir = (0, environments_js_1.environmentDir)()) {
     return [
+        {
+            name: 'proxy_environments',
+            title: 'List the environments available',
+            description: 'List the environments on this machine, by the name proxy_start takes. ' +
+                'An environment is one SAP system\u2019s credentials; a config says which ' +
+                'service to reach, an environment says what to authenticate with. ' +
+                'Several configs commonly want the same environment. Variable NAMES are ' +
+                'shown, never their values.',
+            inputSchema: {},
+            handler: async () => {
+                const environments = (0, environments_js_1.listEnvironments)(envDir);
+                if (environments.length === 0) {
+                    return text(`No environments found in ${envDir}.`);
+                }
+                return text([
+                    `Environments in ${envDir}:`,
+                    ...environments.map((e) => `  ${e.name}${e.variables.length ? ` — ${e.variables.join(', ')}` : ' — (none readable)'}`),
+                    '',
+                    'Pass one to proxy_start as "environment" when the config uses ${VAR}.',
+                ].join('\n'));
+            },
+        },
         {
             name: 'proxy_configs',
             title: 'List the proxy configs available',
@@ -56,7 +79,7 @@ function createProxyTools(supervisor, configDir = (0, configs_js_1.proxyConfigDi
         {
             name: 'proxy_start',
             title: 'Start an authenticating proxy',
-            description: 'Start a local proxy from one of the configs proxy_configs lists. The ' +
+            description: 'Start a local proxy from a config and, when the config needs one, an environment. The ' +
                 'config supplies the destination, target URL, default headers and ' +
                 'timeouts — including any credentials, which stay in the config and ' +
                 'are never passed through here. The port is NOT taken from the config: ' +
@@ -66,6 +89,10 @@ function createProxyTools(supervisor, configDir = (0, configs_js_1.proxyConfigDi
                 config: zod_1.z
                     .string()
                     .describe('Name of a proxy config, as proxy_configs lists it (for example "nvcr_d24").'),
+                environment: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Name of an environment, as proxy_environments lists it (for example "e19"). Supplies the ${VAR} values the config references. Needed when the config names no envFile of its own — proxy_configs marks those.'),
                 idleTimeoutMs: zod_1.z
                     .number()
                     .optional()
@@ -74,14 +101,19 @@ function createProxyTools(supervisor, configDir = (0, configs_js_1.proxyConfigDi
             handler: async (args) => {
                 const name = String(args.config);
                 const file = (0, configs_js_1.resolveProxyConfig)(name, configDir);
+                const environment = args.environment;
+                const envFile = environment
+                    ? (0, environments_js_1.resolveEnvironment)(environment, envDir)
+                    : undefined;
                 const started = await supervisor.start({
                     name,
-                    config: (0, config_js_1.loadConfig)(file),
+                    config: (0, config_js_1.loadConfig)(file, envFile),
                     idleTimeoutMs: args.idleTimeoutMs,
                 });
                 return text([
                     `Proxy running at ${started.url}`,
                     `  config:      ${started.name}`,
+                    `  environment: ${environment ?? "(the config's own, or the environment)"}`,
                     `  instanceId:  ${started.instanceId}`,
                     `  destination: ${started.destination}`,
                     '',

package/docs/CLIENT_SETUP.md

@@ -243,7 +243,8 @@ It works from the configs in `~/.config/mcp-abap-adt/proxy/` — the same files
 | Tool | |
 |---|---|
 | `proxy_configs` | the names available; call it first, they cannot be guessed |
-| `proxy_start` | starts one on a **free port** and returns the URL bound |
+| `proxy_environments` | the environments available — one SAP system's credentials each. Variable names only, never values |
+| `proxy_start` | starts one on a **free port** and returns the URL bound. Takes `environment` when the config uses `${VAR}` and names no `envFile` |
 | `proxy_stop` | frees the port and releases the credential; never touches another session's proxy |
 | `proxy_status` | this session's proxies and everyone else's, dead records pruned on read |
 

package/docs/USAGE.md

@@ -155,7 +155,8 @@ It works from the configs in `~/.config/mcp-abap-adt/proxy/` — the same files
 | Tool | |
 |---|---|
 | `proxy_configs` | the names available; call it first, they cannot be guessed |
-| `proxy_start` | starts one on a **free port** and returns the URL bound |
+| `proxy_environments` | the environments available — one SAP system's credentials each. Variable names only, never values |
+| `proxy_start` | starts one on a **free port** and returns the URL bound. Takes `environment` when the config uses `${VAR}` and names no `envFile` |
 | `proxy_stop` | frees the port and releases the credential; never touches another session's proxy |
 | `proxy_status` | this session's proxies and everyone else's, dead records pruned on read |
 

package/docs/YAML_CONFIG.md

@@ -206,6 +206,23 @@ requestTimeout: 120000
 | `maxRetries` | `number` | `3` | Maximum number of retry attempts |
 | `retryDelay` | `number` | `1000` | Delay between retries (milliseconds) |
 | `requestTimeout` | `number` | `60000` | Request timeout (milliseconds) |
+### Windows paths must not go in double quotes
+
+In YAML, a double-quoted string is an **escape context**, and a Windows path is
+full of backslashes. Measured with the parser this package uses:
+
+| written as | result |
+|---|---|
+| `envFile: "C:\Users\me\e19.env"` | **fails** — `expected hexadecimal character`, because `\U` starts a Unicode escape |
+| `envFile: "C:\temp\e19.env"` | **silently wrong** — `\e` becomes the escape character `0x1B`, so the path points nowhere |
+| `envFile: 'C:\Users\me\e19.env'` | correct |
+| `envFile: C:\Users\me\e19.env` | correct |
+| `envFile: "C:/Users/me/e19.env"` | correct |
+
+The second row is the dangerous one: it does not fail, it resolves to a path that
+does not exist. Forward slashes are the safest form — Node accepts them on
+Windows, and they carry no meaning inside quotes.
+
 | ~~`circuitBreakerThreshold`~~ | `number` | — | **No effect since 4.0.0.** Still accepted so existing files load; the circuit breaker guarded the buffered forward that release removed |
 | ~~`circuitBreakerTimeout`~~ | `number` | — | **No effect since 4.0.0.** As above |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/proxy",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "MCP proxy server for SAP ABAP ADT - proxies local requests to cloud-llm-hub with JWT authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",