@mcp-abap-adt/proxy 1.2.1 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-06-02
+
+### Added
+- **Exit on incomplete authentication.** When authentication is requested but not completed — at startup (eager auth) or on a request that needs a token — the proxy now logs a categorised reason (timeout / invalid credentials / service key / network) and exits with code 1, so it can be restarted to retry (mirroring the one-shot `mcp-auth` command) instead of running in a permanently unauthenticated state. A downstream/forward error (after auth succeeds) is still returned to the client without exiting.
+
+### Changed
+- Bump `@mcp-abap-adt/auth-broker` `^1.0.5` → `^1.0.6`: the broker no longer starts a redundant second browser login after an interactive session-login failure, so the real cause (e.g. login timeout) is reported instead of a misleading `Port <n> is already in use`.
+
+## [1.4.0] - 2026-06-02
+
+### Added
+- **Manual paste login for `--browser none` / `headless`** (via `@mcp-abap-adt/auth-providers@1.1.0`). When the browser runs on a different machine than the proxy, login can be completed by opening the paste form at `http://<host>:<browser-auth-port>/` and pasting the `code` (or the whole redirected URL), or by pasting the code in the terminal — in addition to the existing automatic localhost callback.
+
+### Fixed
+- **`--browser none` now prints the authorization URL.** The per-destination `AuthorizationCodeProvider` was created without a logger, so the "Open this URL" prompt from `browserAuth` was silently dropped and login could never be completed in headless mode. The proxy now passes its logger to the provider; `auth-providers@1.1.0` additionally falls back to `stderr` when no logger is supplied.
+- **Platform-correct service-key path in `--help` and errors.** The "service key not found" hint and `--help` hard-coded the Unix `~/.config/...` path, which is wrong on Windows (`%USERPROFILE%\Documents\mcp-abap-adt\service-keys`). Both now show the real resolved directory and mention the `AUTH_BROKER_PATH` override.
+
+### Changed
+- Bump `@mcp-abap-adt/auth-providers` `^1.0.5` → `^1.1.0`.
+
+## [1.3.0] - 2026-05-28
+
+### Added
+- **CLI flags override values from `--config`** — when a config file is loaded via `--config`/`-c`, explicit CLI flags (`--btp`, `--target-url`/`--url`, `--unsafe`, `--browser`, `--browser-auth-port`, `--header`) now override matching values from the file instead of being silently dropped. `--header` entries merge with `defaultHeaders` (CLI keys win on conflict). The proxy logs which keys were overridden so the precedence is visible.
+- **`--help` / `-h`** — full CLI usage printer covering auth, browser, transport flags and the documented environment variables. Previously the proxy had no help output at all, making the `--browser none` / `--browser-auth-port` flags effectively undiscoverable.
+- **Graceful shutdown on `SIGINT` / `SIGTERM`** — the proxy now wires both signals to `shutdown()`, which closes the MCP server and HTTP listener, clears pending JWT refresh timers, drops the token cache, and releases per-destination auth brokers. Previously these resources were only released on hard process exit.
+
+### Fixed
+- `BtpProxy.dispose()` now clears the token cache and the per-destination broker map in addition to refresh timers, so a clean shutdown actually releases all auth state.
+
 ## [1.2.1] - 2026-05-26
 
 ### Security

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export declare class McpAbapAdtProxyServer {
     private config;
     private httpServer?;
     private btpProxy?;
+    private authExiting;
     constructor(transportConfig?: TransportConfig, configPath?: string);
     /**
      * Setup MCP handlers
@@ -38,6 +39,13 @@ export declare class McpAbapAdtProxyServer {
      * Start SSE server
      */
     private startSseServer;
+    /**
+     * Authentication was requested but could not be completed. Report the reason
+     * clearly, release resources, and exit(1) so the proxy is restarted (and the
+     * user gets a fresh login prompt) instead of running unauthenticated. Mirrors
+     * the one-shot `mcp-auth` command, which exits on a failed/incomplete login.
+     */
+    private fatalAuthFailure;
     /**
      * Shutdown server
      */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAqBlC;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,CAAW;gBAEhB,eAAe,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM;IAoDlE;;OAEG;IACH,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAuE1B;;OAEG;YACW,eAAe;IAgG7B;;OAEG;YACW,kBAAkB;IA8ChC;;OAEG;YACW,cAAc;IA6T5B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBhC;AAGD,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAgElC;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,WAAW,CAAS;gBAEhB,eAAe,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM;IAoDlE;;OAEG;IACH,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA2E1B;;OAEG;YACW,eAAe;IAgG7B;;OAEG;YACW,kBAAkB;IAgEhC;;OAEG;YACW,cAAc;IA6T5B;;;;;OAKG;YACW,gBAAgB;IAiC9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBhC;AAGD,eAAe,qBAAqB,CAAC"}

package/dist/index.js

@@ -18,6 +18,7 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const reverseProxy_js_1 = require("./proxy/reverseProxy.js");
 const config_js_1 = require("./lib/config.js");
 const logger_js_1 = require("./lib/logger.js");
+const stores_js_1 = require("./lib/stores.js");
 const transportConfig_js_1 = require("./lib/transportConfig.js");
 const btpProxy_js_1 = require("./proxy/btpProxy.js");
 const headerAnalyzer_js_1 = require("./router/headerAnalyzer.js");
@@ -31,6 +32,38 @@ function getBodyId(body) {
     }
     return null;
 }
+/**
+ * Classify an authentication failure into a human-readable reason so the proxy
+ * can report *why* it is exiting (timeout vs bad credentials vs network ...).
+ */
+function classifyAuthFailure(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (/timeout/i.test(msg)) {
+        return {
+            category: 'timeout',
+            reason: 'the login URL was not completed in time',
+        };
+    }
+    if (/service key|missing required fields/i.test(msg)) {
+        return {
+            category: 'service-key',
+            reason: 'service key missing or incomplete',
+        };
+    }
+    if (/invalid_client|unauthorized|\b401\b|invalid credentials/i.test(msg)) {
+        return {
+            category: 'credentials',
+            reason: 'invalid credentials — UAA rejected the client',
+        };
+    }
+    if (/ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network|ENETUNREACH/i.test(msg)) {
+        return {
+            category: 'network',
+            reason: 'network error reaching the authentication server',
+        };
+    }
+    return { category: 'other', reason: msg };
+}
 /**
  * MCP ABAP ADT Proxy Server
  */
@@ -40,6 +73,7 @@ class McpAbapAdtProxyServer {
     config;
     httpServer;
     btpProxy;
+    authExiting = false;
     constructor(transportConfig, configPath) {
         // Load config first to extract transport overrides from YAML/JSON file
         const resolvedConfigPath = configPath || (0, config_js_1.getConfigPath)();
@@ -125,20 +159,24 @@ Authorization source: BTP destination "${this.config.btpDestination}"`;
             });
             return;
         }
-        // Eager initialization of BTP authentication
+        // Eager initialization of BTP authentication. Kept in the background so the
+        // server starts listening immediately (and, for --browser none, the auth URL
+        // is printed right away). If auth is requested but never completed, exit(1)
+        // so the proxy is restarted and the user gets a fresh login prompt.
         if (this.config.btpDestination) {
+            const dest = this.config.btpDestination;
             try {
                 if (!this.btpProxy) {
                     this.btpProxy = await (0, btpProxy_js_1.createBtpProxy)(this.config);
                 }
-                // Trigger initialization (background) - this will open the browser
-                this.btpProxy.initialize(this.config.btpDestination);
             }
             catch (error) {
-                logger_js_1.logger?.error('Failed to initialize BTP proxy for eager auth', {
-                    error: error instanceof Error ? error.message : String(error),
-                });
+                await this.fatalAuthFailure(error, dest, 'startup');
+                return;
             }
+            this.btpProxy
+                .initialize(dest)
+                .catch((error) => this.fatalAuthFailure(error, dest, 'startup'));
         }
         if (this.transportConfig.type === 'streamable-http') {
             await this.startHttpServer();
@@ -246,9 +284,28 @@ Authorization source: ${authSourceObj}`;
         if (!this.btpProxy) {
             this.btpProxy = await (0, btpProxy_js_1.createBtpProxy)(this.config);
         }
+        // Authentication is separated from forwarding: an auth failure is fatal
+        // (the proxy exits so it can be restarted), while a downstream/forward error
+        // is returned to the client without killing the proxy.
+        let jwtToken;
         try {
             // Get JWT token (cached, auto-refresh)
-            const jwtToken = await this.btpProxy.getJwtToken(destination);
+            jwtToken = await this.btpProxy.getJwtToken(destination);
+        }
+        catch (authError) {
+            logger_js_1.logger?.error('Proxy request failed: authentication error', {
+                type: 'PROXY_REQUEST_AUTH_ERROR',
+                destination,
+                error: authError instanceof Error ? authError.message : String(authError),
+            });
+            if (!res.headersSent) {
+                res.writeHead(502, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Authentication failed' }));
+            }
+            await this.fatalAuthFailure(authError, destination, 'request');
+            return;
+        }
+        try {
             // Get target URL
             const targetUrl = intercepted.routingDecision.targetUrl ||
                 (await this.btpProxy.getTargetUrl(destination));
@@ -540,6 +597,37 @@ Authorization source: ${authSourceObj}`;
             });
         });
     }
+    /**
+     * Authentication was requested but could not be completed. Report the reason
+     * clearly, release resources, and exit(1) so the proxy is restarted (and the
+     * user gets a fresh login prompt) instead of running unauthenticated. Mirrors
+     * the one-shot `mcp-auth` command, which exits on a failed/incomplete login.
+     */
+    async fatalAuthFailure(error, destination, phase) {
+        if (this.authExiting)
+            return;
+        this.authExiting = true;
+        const { category, reason } = classifyAuthFailure(error);
+        const detail = error instanceof Error ? error.message : String(error);
+        logger_js_1.logger?.error('Authentication not completed — exiting', {
+            type: 'AUTH_FATAL_EXIT',
+            destination,
+            phase,
+            category,
+            reason,
+            error: detail,
+        });
+        console.error(`[MCP Proxy] ✗ Authentication failed for destination "${destination}" (${phase}): ${reason}.\n` +
+            `[MCP Proxy]   ${detail}\n` +
+            `[MCP Proxy] Exiting (code 1) so the proxy can be restarted to retry authentication.`);
+        try {
+            await this.shutdown();
+        }
+        catch {
+            // best-effort cleanup; exit regardless
+        }
+        process.exit(1);
+    }
     /**
      * Shutdown server
      */
@@ -567,9 +655,98 @@ Authorization source: ${authSourceObj}`;
 exports.McpAbapAdtProxyServer = McpAbapAdtProxyServer;
 // Export for use in bin script
 exports.default = McpAbapAdtProxyServer;
+/**
+ * Print CLI usage and exit.
+ */
+function printHelp() {
+    // Show the real, platform-specific directory where service keys are read from
+    // (Windows: %USERPROFILE%\Documents\mcp-abap-adt\service-keys; Unix: ~/.config/...)
+    const serviceKeyDir = (0, stores_js_1.getPlatformPaths)('service-keys')[0];
+    const help = `Usage: mcp-abap-adt-proxy [options]
+
+Authorization proxy for MCP clients (Cline, Claude Code, etc.) that cannot
+authenticate on their own to MCP servers deployed on SAP BTP.
+
+CONFIGURATION
+  -c, --config <path>         Load config from YAML/JSON file. CLI flags below
+                              override values from the file.
+
+AUTHENTICATION (BTP / XSUAA)
+  --btp <destination>         BTP destination name. Service key is read from
+                              ${serviceKeyDir}${require('node:path').sep}<dest>.json
+                              (override the base dir with AUTH_BROKER_PATH)
+  --target-url <url>          Override target service URL (default: from service key)
+  --url <url>                 Alias for --target-url
+  --unsafe                    Persist session/tokens to disk (default: in-memory)
+  --header <key=value>        Inject a default header into every forwarded
+                              request. Repeatable. Client-supplied headers win.
+
+BROWSER AUTHORIZATION
+  --browser <mode>            Browser used for OAuth login. One of:
+                                system   - OS default browser (default)
+                                chrome   - Google Chrome
+                                edge     - Microsoft Edge
+                                firefox  - Firefox
+                                none     - Print URL to console; complete login
+                                           via callback OR by pasting the code
+                                           (for SSH/headless/remote sessions)
+                                headless - Alias for 'none'
+  --browser-auth-port <port>  Local OAuth callback port. Must match the
+                              redirect_uri registered on XSUAA (default: 3333).
+
+  Run without auto-opening a browser (prints the URL, then completes via the
+  localhost callback, the paste form at http://<host>:<port>/, or by pasting
+  the code in the terminal):
+    mcp-abap-adt-proxy --btp <dest> --browser none --browser-auth-port 3333
+
+TRANSPORT
+  --transport <type>          stdio | streamable-http | http | sse
+                              (auto-detected from stdin TTY if not set)
+  --stdio                     Shortcut for --transport stdio
+  --http                      Shortcut for --transport streamable-http
+  --sse                       Shortcut for --transport sse
+  --http-port <port>          HTTP transport port (default: 3001)
+  --http-host <host>          HTTP transport host (default: 127.0.0.1)
+  --sse-port <port>           SSE transport port (default: 3002)
+  --sse-host <host>           SSE transport host (default: 127.0.0.1)
+
+  -h, --help                  Show this help and exit
+
+ENVIRONMENT VARIABLES
+  MCP_TRANSPORT, MCP_HTTP_PORT, MCP_HTTP_HOST, MCP_SSE_PORT, MCP_SSE_HOST,
+  LOG_LEVEL, MCP_PROXY_UNSAFE, MCP_PROXY_MAX_RETRIES, MCP_PROXY_RETRY_DELAY,
+  MCP_PROXY_REQUEST_TIMEOUT, MCP_PROXY_CIRCUIT_BREAKER_THRESHOLD,
+  MCP_PROXY_CIRCUIT_BREAKER_TIMEOUT
+
+See docs/CONFIGURATION.md for the full configuration reference.
+`;
+    process.stdout.write(help);
+}
 // Auto-start server when run directly (unless MCP_SKIP_AUTO_START is set)
 if (process.env.MCP_SKIP_AUTO_START !== 'true') {
+    if (process.argv.includes('--help') || process.argv.includes('-h')) {
+        printHelp();
+        process.exit(0);
+    }
     const server = new McpAbapAdtProxyServer();
+    // Graceful shutdown: release the OAuth callback port, MCP server, and HTTP listener.
+    let shuttingDown = false;
+    const onSignal = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger_js_1.logger?.info('Received shutdown signal, releasing resources', { signal });
+        server
+            .shutdown()
+            .catch((error) => {
+            logger_js_1.logger?.error('Error during shutdown', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .finally(() => process.exit(0));
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
     server.run().catch((error) => {
         logger_js_1.logger?.error('Fatal error while running MCP proxy server', {
             type: 'SERVER_FATAL_ERROR',

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;AAMH,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,CAqC3D;AAED;;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;AAgBD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYhC;AA4ID;;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;AAMH,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,CAyB3D;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;AAgBD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYhC;AA4ID;;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

@@ -56,24 +56,17 @@ function loadConfig(configPath) {
     // 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();
-    // If --config is provided, load ONLY from that file (no merge with command line params)
+    // If --config is provided: load from file, apply defaults, then overlay explicit CLI flags.
+    // CLI flags override YAML values (YAML is just the baseline).
     if (finalConfigPath) {
-        // Warn if other CLI parameters are also provided (they will be ignored)
-        const conflictingParams = ['--btp', '--unsafe'].filter((param) => hasArg(param));
-        if (conflictingParams.length > 0) {
-            console.warn(`Warning: --config is specified, but the following CLI parameters will be ignored: ${conflictingParams.join(', ')}. ` +
-                `Configuration will be loaded ONLY from ${finalConfigPath}. ` +
-                `To use CLI parameters, do not specify --config.`);
-        }
         try {
-            if (fs.existsSync(finalConfigPath)) {
-                const fileConfig = loadConfigFile(finalConfigPath);
-                // Apply defaults for missing values in file config
-                return applyDefaults(fileConfig);
-            }
-            else {
+            if (!fs.existsSync(finalConfigPath)) {
                 throw new Error(`Config file not found: ${finalConfigPath}`);
             }
+            const fileConfig = loadConfigFile(finalConfigPath);
+            const base = applyDefaults(fileConfig);
+            const cli = readCliOverrides();
+            return mergeCliOverrides(base, cli, finalConfigPath);
         }
         catch (error) {
             throw new Error(`Failed to load config from file ${finalConfigPath}: ${error instanceof Error ? error.message : String(error)}`);
@@ -82,6 +75,61 @@ function loadConfig(configPath) {
     // No --config provided: load ONLY from command line parameters and environment variables
     return loadFromEnv();
 }
+/**
+ * Read CLI flags that should override file/YAML configuration.
+ * Only includes keys that were explicitly provided on the command line.
+ */
+function readCliOverrides() {
+    const overrides = {};
+    const btp = getArgValue('--btp');
+    if (btp !== undefined)
+        overrides.btpDestination = btp;
+    const targetUrl = getArgValue('--target-url') ?? getArgValue('--url');
+    if (targetUrl !== undefined)
+        overrides.targetUrl = targetUrl;
+    if (hasArg('--unsafe'))
+        overrides.unsafe = true;
+    const browser = getArgValue('--browser');
+    if (browser !== undefined) {
+        overrides.browser = browser;
+    }
+    const browserAuthPortStr = getArgValue('--browser-auth-port');
+    if (browserAuthPortStr !== undefined) {
+        overrides.browserAuthPort = parseInt(browserAuthPortStr, 10);
+    }
+    const headerArgs = getAllArgValues('--header');
+    if (headerArgs.length > 0) {
+        const headers = {};
+        for (const arg of headerArgs) {
+            const eqIndex = arg.indexOf('=');
+            if (eqIndex > 0) {
+                const key = arg.substring(0, eqIndex).toLowerCase();
+                const value = arg.substring(eqIndex + 1);
+                headers[key] = value;
+            }
+        }
+        overrides.defaultHeaders = headers;
+    }
+    return overrides;
+}
+/**
+ * Merge CLI overrides on top of file-based config. Logs which keys were overridden.
+ * `defaultHeaders` is merged per-key (CLI keys override YAML keys); other fields are replaced.
+ */
+function mergeCliOverrides(base, cli, configPath) {
+    const merged = { ...base, ...cli };
+    if (cli.defaultHeaders) {
+        merged.defaultHeaders = {
+            ...(base.defaultHeaders || {}),
+            ...cli.defaultHeaders,
+        };
+    }
+    const overriddenKeys = Object.keys(cli);
+    if (overriddenKeys.length > 0) {
+        console.warn(`Note: CLI flags override values from ${configPath}: ${overriddenKeys.join(', ')}`);
+    }
+    return merged;
+}
 /**
  * Extract transport-related fields from a raw config object
  */

package/dist/proxy/btpProxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"btpProxy.d.ts","sourceRoot":"","sources":["../../src/proxy/btpProxy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAgB,MAAM,2BAA2B,CAAC;AAYrE,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AA4CnE;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAU3C;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAGD,MAAM,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,UAAU,CACN;IACZ,OAAO,CAAC,aAAa,CAA0C;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAU;gBAEZ,oBAAoB,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAqF3E;;;OAGG;IACU,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB3D;;;;OAIG;YACW,wBAAwB;IAqFtC;;OAEG;YACW,uBAAuB;IAyFrC;;;;OAIG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,MAAM,CAAC;IAiHlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;;OAGG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA6BhC;;OAEG;YACW,gBAAgB;IAU9B;;OAEG;IACI,OAAO,IAAI,IAAI;IAOtB;;;OAGG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAexD;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;;;;;;;OAgBG;YACW,iBAAiB;IAmT/B;;OAEG;IACG,YAAY,CAChB,eAAe,EAAE,YAAY,EAC7B,eAAe,EAAE,eAAe,EAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC7D,OAAO,CAAC,aAAa,CAAC;IAiLzB;;OAEG;WACiB,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;CAyB7E;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAEnB"}
+{"version":3,"file":"btpProxy.d.ts","sourceRoot":"","sources":["../../src/proxy/btpProxy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAgB,MAAM,2BAA2B,CAAC;AAYrE,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AA4CnE;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAU3C;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAGD,MAAM,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,oBAAoB,CAAa;IACzC,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,UAAU,CACN;IACZ,OAAO,CAAC,aAAa,CAA0C;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAU;gBAEZ,oBAAoB,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAqF3E;;;OAGG;IACU,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB3D;;;;OAIG;YACW,wBAAwB;IA0FtC;;OAEG;YACW,uBAAuB;IAyFrC;;;;OAIG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,YAAY,GAAE,OAAe,GAC5B,OAAO,CAAC,MAAM,CAAC;IAiHlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;;OAGG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA6BhC;;OAEG;YACW,gBAAgB;IAU9B;;OAEG;IACI,OAAO,IAAI,IAAI;IAStB;;;OAGG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAexD;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;;;;;;;OAgBG;YACW,iBAAiB;IAmT/B;;OAEG;IACG,YAAY,CAChB,eAAe,EAAE,YAAY,EAC7B,eAAe,EAAE,eAAe,EAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC7D,OAAO,CAAC,aAAa,CAAC;IAiLzB;;OAEG;WACiB,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;CA0B7E;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAEnB"}

package/dist/proxy/btpProxy.js

@@ -155,8 +155,9 @@ class BtpProxy {
                 destination,
                 error: error instanceof Error ? error.message : String(error),
             });
-            // We don't throw here to avoid crashing the server on startup,
-            // but the user will see the error in logs/stderr (via getJwtToken)
+            // Re-throw so the server can decide to exit (auth requested but not
+            // completed) instead of running in a permanently unauthenticated state.
+            throw error;
         }
     }
     /**
@@ -199,9 +200,10 @@ class BtpProxy {
             });
         }
         if (!authConfig) {
+            const serviceKeyDir = (0, stores_js_1.getPlatformPaths)('service-keys')[0];
             logger_js_1.logger?.error('Service key not found for destination', {
                 destination,
-                hint: 'Ensure service key file exists in ~/.config/mcp-abap-adt/service-keys/',
+                hint: `Ensure service key file "${destination}.json" exists in ${serviceKeyDir} (override the base dir with AUTH_BROKER_PATH)`,
             });
             // We cannot proceed without config, but we'll let it fail with a clear message
             // Or we could throw here.
@@ -213,6 +215,10 @@ class BtpProxy {
         const providerConfig = {
             browser: this.config.browser,
             redirectPort: this.config.browserAuthPort || 3333,
+            // Pass a logger so browserAuth can surface the "Open this URL" prompt in
+            // 'none'/'headless' mode. Without it, startBrowserAuth gets a null logger
+            // and silently drops the authorization URL.
+            logger: loggerAdapter,
             ...(authConfig
                 ? {
                     uaaUrl: authConfig.uaaUrl,
@@ -474,6 +480,8 @@ class BtpProxy {
             clearTimeout(timer);
         }
         this.refreshTimers.clear();
+        this.tokenCache.clear();
+        this.btpAuthBrokers.clear();
     }
     /**
      * Get the target service URL for a destination.
@@ -922,6 +930,7 @@ class BtpProxy {
                 clientSecret: 'placeholder',
                 browser: loadedConfig.browser,
                 redirectPort: loadedConfig.browserAuthPort,
+                logger: loggerAdapter,
             }),
         }, 'none', loggerAdapter);
         return new BtpProxy(defaultBtpAuthBroker, loadedConfig);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/proxy",
-  "version": "1.2.1",
+  "version": "1.5.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",
@@ -63,8 +63,8 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@mcp-abap-adt/auth-broker": "^1.0.5",
-    "@mcp-abap-adt/auth-providers": "^1.0.5",
+    "@mcp-abap-adt/auth-broker": "^1.0.6",
+    "@mcp-abap-adt/auth-providers": "^1.1.0",
     "@mcp-abap-adt/auth-stores": "^1.0.4",
     "@mcp-abap-adt/header-validator": "^0.1.8",
     "@mcp-abap-adt/interfaces": "^7.0.0",