@mcp-abap-adt/proxy 1.6.4 → 4.0.0

package/README.md

@@ -13,9 +13,10 @@ Enable local MCP clients to connect to remote MCP servers with automatic JWT tok
 
 ## Features
 
-- ✅ **JWT Token Management** - Automatic token retrieval, caching, and refresh via auth-broker
+- ✅ **One shared credential** - the token is the auth-broker's business: it caches, knows expiry and renews behind the call. The proxy holds no token of its own
 - ✅ **Service Key Based** - MCP server URL is obtained from service key for BTP destination
-- ✅ **Error Handling** - Retry logic, circuit breaker, and comprehensive error handling
+- ✅ **Transparent forwarding** - the client's headers go through as sent; the proxy answers for the `Authorization` header and nothing else
+- ✅ **Error Handling** - token acquisition is retried with exponential backoff when the failure can get better; clear messages when it cannot
 - ✅ **Multiple Transport Modes** - HTTP, SSE, and stdio support
 - ✅ **Configuration Flexibility** - Environment variables, config files, or defaults
 
@@ -40,6 +41,58 @@ mcp-abap-adt-proxy --btp=ai
 mcp-abap-adt-proxy --btp=ai --unsafe
 ```
 
+## Two commands
+
+The package installs two binaries, for two different jobs.
+
+| Command | What it is for |
+|---|---|
+| `mcp-abap-adt-proxy` | **Be** a proxy. A client points at it and its requests are authenticated and forwarded. |
+| `mcp-abap-adt-proxy-mcp` | **Manage** proxies. Speaks MCP over stdio; its tools start and stop proxies on demand. |
+
+### The management mode
+
+Register it like any other MCP server:
+
+```json
+{
+  "mcpServers": {
+    "abap-proxy": { "command": "mcp-abap-adt-proxy-mcp" }
+  }
+}
+```
+
+It works from the proxy configs you already keep:
+
+```
+~/.config/mcp-abap-adt/proxy/<name>.yaml     (Windows: Documents\mcp-abap-adt\proxy\)
+```
+
+These are the same files `mcp-abap-adt-proxy --config <file>` takes. Starting a
+proxy is therefore **choosing a name**, not assembling settings — and
+credentials stay in the config, resolved through `${VAR}` interpolation, rather
+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_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. |
+
+**The config name is the unit, not the destination.** Several configs commonly
+name the same `btpDestination` and differ in target URL and headers — a
+destination cannot tell them apart.
+
+**Every proxy runs inside the management process.** Closing the session — or
+`SIGINT`, or `SIGTERM` — stops all of them and frees their ports. This is
+deliberate: a spawned child would be orphaned by any signal the parent did not
+forward and would go on holding its HTTP and OAuth callback ports.
+
+A proxy nobody has used for 30 minutes stops itself. That is a backstop for a
+client that finished and forgot, not a substitute for `proxy_stop` — which is
+why the tool descriptions say so, and say it again beside the URL.
+
 ### Configuration
 
 The proxy supports multiple configuration methods:
@@ -156,6 +209,8 @@ The proxy uses BTP/XSUAA authentication:
 
 ## Documentation
 
+- 🚚 **[Migration to 4.0](./docs/MIGRATION-4.0.md)** — the contracts leave the umbrella, an SSE response streams and carries your headers, `getJwtToken()` is replaced, the circuit breaker is gone
+
 - **[Client Setup Guide](./docs/CLIENT_SETUP.md)** - Step-by-step setup for Cline and GitHub Copilot
 - **[Configuration Guide](./docs/CONFIGURATION.md)** - Complete configuration reference
 - **[YAML Configuration Guide](./docs/YAML_CONFIG.md)** - Using YAML/JSON configuration files
@@ -221,7 +276,6 @@ Create `mcp-proxy-config.json`:
   "httpPort": 3001,
   "logLevel": "info",
   "maxRetries": 3,
-  "circuitBreakerThreshold": 5,
   "unsafe": false
 }
 ```
@@ -234,10 +288,9 @@ See [Configuration Guide](./docs/CONFIGURATION.md) for complete options.
 
 ## Error Handling & Resilience
 
-- **Retry Logic** - Exponential backoff for failed requests
-- **Circuit Breaker** - Prevents cascading failures
-- **Token Refresh** - Automatic token refresh on expiration
-- **Connection Pooling** - Efficient resource management
+- **Retry Logic** - exponential backoff while getting a token, for failures that can get better (5xx, network). A missing service key is not one of them and fails at once, with a message naming the file to create
+- **Token Refresh** - handled by the credential, which is asked per request and renews behind the call
+- **No circuit breaker** - it guarded the buffered forward that 4.0.0 removed. The forwarding path now streams, and there is nowhere to put one without buffering the response again. `circuitBreakerThreshold` and `circuitBreakerTimeout` are still accepted so existing configs load, and do nothing
 - **Request Timeouts** - Configurable timeout handling
 
 ## Requirements
@@ -277,7 +330,25 @@ See [ROADMAP.md](./ROADMAP.md) for details.
 
 ## License
 
-MIT
+**GNU General Public License v3.0 only** (`GPL-3.0-only`).
+Earlier published versions were MIT and stay MIT — a licence change is not
+retroactive.
+
+Copyright © 2025–2026 Oleksii Kyslytsia
+
+This program is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, version 3.
+
+It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See [`LICENSE`](LICENSE) for the full text.
+
+**What this means.** Running it, and using it on your own data, carries no
+conditions at all. Distributing it, or a modified version of it, means passing on
+the same freedoms — including the source. This is a finished tool rather than a
+library to build on; the libraries it is built from are LGPL, so they can be
+linked from programs under any licence.
 
 ## Links
 

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+/**
+ * MCP ABAP ADT Proxy — management mode.
+ *
+ * Speaks MCP over stdio and exposes tools that start and stop proxies. This is
+ * the command a client registers when it wants to MANAGE proxies; a client that
+ * wants to BE proxied still points at `mcp-abap-adt-proxy`.
+ *
+ * Usage:
+ *   mcp-abap-adt-proxy-mcp [--config <file>] [--unsafe]
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  return {
+    help: args.includes('--help') || args.includes('-h'),
+    version: args.includes('--version') || args.includes('-v'),
+  };
+}
+
+function showHelp() {
+  const pkg = require('../package.json');
+  console.log(`
+MCP ABAP ADT Proxy — management mode v${pkg.version}
+
+Speaks MCP over stdio. Its tools start and stop authenticating proxies; it does
+not proxy anything itself.
+
+Usage:
+  mcp-abap-adt-proxy-mcp [options]
+
+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
+                 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
+                 one actually bound.
+  proxy_stop     Stop a proxy this session started, freeing its port and
+                 releasing its credential. Proxies belonging to other sessions
+                 are never touched.
+  proxy_status   List this session's proxies and any others on this machine.
+                 Records whose process has died are pruned when read.
+
+Where the configs live:
+  Unix:     ~/.config/mcp-abap-adt/proxy/<name>.yaml
+  Windows:  %USERPROFILE%\\Documents\\mcp-abap-adt\\proxy\\<name>.yaml
+
+  The same files 'mcp-abap-adt-proxy --config <file>' takes. Credentials stay
+  in them, resolved through \${VAR} interpolation, and are never passed
+  through a tool call.
+
+Options:
+  --config=<file>, -c     Load configuration from a YAML or JSON file
+  --env-file=<path>       Load a .env file for \${VAR} interpolation
+  --unsafe                Persist tokens to disk
+  --help, -h              Show this help message
+  --version, -v           Show version number
+
+Shutting down:
+  Every proxy runs in THIS process. Closing the session — or SIGINT, or SIGTERM
+  — stops all of them and frees their ports. A proxy nobody has used for 30
+  minutes stops itself; that is a backstop, not a substitute for proxy_stop.
+
+Registering it with a client:
+  {
+    "mcpServers": {
+      "abap-proxy": { "command": "mcp-abap-adt-proxy-mcp" }
+    }
+  }
+
+For more information, see: https://github.com/fr0ster/mcp-abap-adt-proxy
+`);
+}
+
+function main() {
+  const args = parseArgs();
+
+  if (args.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (args.version) {
+    console.log(require('../package.json').version);
+    process.exit(0);
+  }
+
+  const serverPath = path.resolve(__dirname, '../dist/mcp/cli.js');
+
+  if (!fs.existsSync(serverPath)) {
+    process.stderr.write(`[MCP Proxy] ✗ Server not found at: ${serverPath}\n`);
+    process.stderr.write(
+      `[MCP Proxy]   Make sure to build the project with 'npm run build' first.\n`,
+    );
+    process.exit(1);
+    return;
+  }
+
+  // Loaded in THIS process, never spawned — the same rule the proxy launcher
+  // follows, and it matters more here: the proxies the tools start are
+  // listeners in this process, and a spawned child would be orphaned by any
+  // signal this launcher did not forward, still holding their ports.
+  require(serverPath);
+}
+
+main();

package/dist/index.d.ts

@@ -17,6 +17,16 @@ export declare class McpAbapAdtProxyServer {
     private config;
     private httpServer?;
     private btpProxy?;
+    private builtProxyHandler?;
+    /**
+     * The request path, shared with the MCP mode. Here an authentication failure
+     * is fatal: the process exits so whatever started it can start it again with
+     * a credential that works.
+     *
+     * Built on first use rather than as a field initializer, because `config` is
+     * assigned in the constructor and a field initializer runs before that.
+     */
+    private get proxyHandler();
     private authExiting;
     constructor(transportConfig?: TransportConfig, configPath?: string);
     /**
@@ -31,10 +41,6 @@ export declare class McpAbapAdtProxyServer {
      * Start HTTP server with request interception
      */
     private startHttpServer;
-    /**
-     * Handle proxy request - get JWT token and forward transparently via reverse proxy
-     */
-    private handleProxyRequest;
     /**
      * Start SSE server
      */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,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;IAE5B,OAAO,CAAC,iBAAiB,CAAC,CAA+C;IAEzE;;;;;;;OAOG;IACH,OAAO,KAAK,YAAY,GAevB;IACD,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;IAiE7B;;OAEG;YACW,cAAc;IAiV5B;;;;;OAKG;YACW,gBAAgB;IAiC9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBhC;AAGD,eAAe,qBAAqB,CAAC"}

package/dist/index.js

@@ -11,10 +11,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpAbapAdtProxyServer = void 0;
 const node_http_1 = require("node:http");
-const interfaces_1 = require("@mcp-abap-adt/interfaces");
+const interfaces_network_1 = require("@mcp-abap-adt/interfaces-network");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const requestHandler_js_1 = require("./proxy/requestHandler.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");
@@ -73,6 +74,30 @@ class McpAbapAdtProxyServer {
     config;
     httpServer;
     btpProxy;
+    builtProxyHandler;
+    /**
+     * The request path, shared with the MCP mode. Here an authentication failure
+     * is fatal: the process exits so whatever started it can start it again with
+     * a credential that works.
+     *
+     * Built on first use rather than as a field initializer, because `config` is
+     * assigned in the constructor and a field initializer runs before that.
+     */
+    get proxyHandler() {
+        if (!this.builtProxyHandler) {
+            this.builtProxyHandler = (0, requestHandler_js_1.createProxyRequestHandler)({
+                config: this.config,
+                proxy: async () => {
+                    if (!this.btpProxy) {
+                        this.btpProxy = await (0, btpProxy_js_1.createBtpProxy)(this.config);
+                    }
+                    return this.btpProxy;
+                },
+                onAuthFailure: (error, destination) => this.fatalAuthFailure(error, destination, 'request'),
+            });
+        }
+        return this.builtProxyHandler;
+    }
     authExiting = false;
     constructor(transportConfig, configPath) {
         // Load config first to extract transport overrides from YAML/JSON file
@@ -203,39 +228,13 @@ Authorization source: BTP destination "${this.config.btpDestination}"`;
                 headers: sanitizedHeaders,
                 remoteAddress: req.socket.remoteAddress,
             });
-            // Intercept and analyze request (headers only, body is piped through)
-            const configOverrides = {
-                btpDestination: this.config.btpDestination,
-                targetUrl: this.config.targetUrl,
-            };
-            const intercepted = (0, requestInterceptor_js_1.interceptRequest)(req, undefined, configOverrides, {
-                skipHeaderValidation: true,
-            });
-            // Check routing decision
-            if (intercepted.routingDecision.strategy === headerAnalyzer_js_1.RoutingStrategy.UNKNOWN) {
-                logger_js_1.logger?.error('Routing decision failed', {
-                    type: 'ROUTING_DECISION_FAILED',
-                    reason: intercepted.routingDecision.reason,
-                });
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    error: intercepted.routingDecision.reason,
-                }));
-                return;
-            }
-            // Forward request via reverse proxy
-            logger_js_1.logger?.info('=== PROXYING REQUEST ===', {
-                type: 'PROXY_REQUEST_START',
-                btpDestination: intercepted.routingDecision.btpDestination,
-            });
             try {
-                await this.handleProxyRequest(intercepted, req, res);
+                await this.proxyHandler(req, res);
             }
             catch (error) {
                 logger_js_1.logger?.error('Failed to process request', {
                     type: 'REQUEST_PROCESS_ERROR',
                     error: error instanceof Error ? error.message : String(error),
-                    strategy: intercepted.routingDecision.strategy,
                 });
                 if (!res.headersSent) {
                     res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -270,62 +269,6 @@ Authorization source: ${authSourceObj}`;
             });
         });
     }
-    /**
-     * Handle proxy request - get JWT token and forward transparently via reverse proxy
-     */
-    async handleProxyRequest(intercepted, req, res) {
-        const destination = intercepted.routingDecision.btpDestination;
-        if (!destination) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'No BTP destination specified' }));
-            return;
-        }
-        // Ensure proxy is initialized
-        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)
-            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));
-            // Forward request transparently (inject default headers from config)
-            await (0, reverseProxy_js_1.forwardRequest)(req, res, targetUrl, jwtToken, this.config.defaultHeaders);
-        }
-        catch (error) {
-            logger_js_1.logger?.error('Proxy request failed', {
-                type: 'PROXY_REQUEST_ERROR',
-                destination,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            if (!res.headersSent) {
-                res.writeHead(502, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    error: error instanceof Error ? error.message : 'Proxy error',
-                }));
-            }
-        }
-    }
     /**
      * Start SSE server
      */
@@ -371,8 +314,8 @@ Authorization source: ${authSourceObj}`;
                 }
             }
             // Add config overrides if not present in headers
-            if (this.config.btpDestination && !headers[interfaces_1.HEADER_BTP_DESTINATION]) {
-                headers[interfaces_1.HEADER_BTP_DESTINATION] = this.config.btpDestination;
+            if (this.config.btpDestination && !headers[interfaces_network_1.HEADER_BTP_DESTINATION]) {
+                headers[interfaces_network_1.HEADER_BTP_DESTINATION] = this.config.btpDestination;
             }
             logger_js_1.logger?.debug('SSE request received', {
                 type: 'SSE_HTTP_REQUEST',
@@ -483,14 +426,15 @@ Authorization source: ${authSourceObj}`;
                 }
                 // Read request body
                 let body;
+                let rawBody;
                 try {
                     const chunks = [];
                     for await (const chunk of req) {
                         chunks.push(chunk);
                     }
                     if (chunks.length > 0) {
-                        const bodyString = Buffer.concat(chunks).toString('utf-8');
-                        body = JSON.parse(bodyString);
+                        rawBody = Buffer.concat(chunks);
+                        body = JSON.parse(rawBody.toString('utf-8'));
                     }
                 }
                 catch (error) {
@@ -532,19 +476,32 @@ Authorization source: ${authSourceObj}`;
                     }));
                     return;
                 }
-                // Handle proxy request via BtpProxy (JSON-RPC mode for SSE)
+                // Forward through the same transparent pipe the other path uses.
+                //
+                // This used to rebuild the request by hand and carry it over axios,
+                // which buffered the response and rewrapped it as a JSON-RPC envelope.
+                // The body above was already read — the JSON-RPC `id` in it is what the
+                // error envelopes below have to echo — so it is handed over rather than
+                // piped. The response still streams, which is the direction that
+                // carries an event stream.
                 try {
                     if (!this.btpProxy) {
                         this.btpProxy = await (0, btpProxy_js_1.createBtpProxy)(this.config);
                     }
-                    const proxyResponse = await this.btpProxy.proxyRequest({
-                        method: intercepted.method,
-                        url: intercepted.url,
-                        data: body,
-                        id: getBodyId(body),
-                    }, intercepted.routingDecision, intercepted.headers);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify(proxyResponse));
+                    const destination = intercepted.routingDecision.btpDestination ??
+                        this.config.btpDestination;
+                    if (!destination) {
+                        throw new Error('No BTP destination for this request');
+                    }
+                    const authorization = await this.btpProxy.getAuthorizationHeader(destination);
+                    const targetUrl = intercepted.routingDecision.targetUrl ||
+                        (await this.btpProxy.getTargetUrl(destination));
+                    await (0, reverseProxy_js_1.forwardRequest)(req, res, targetUrl, authorization, this.config.defaultHeaders, 
+                    // The bytes as they arrived, not the parse re-serialised: the
+                    // client's `content-length` is forwarded unchanged, and a
+                    // re-serialised body differs from it by whatever whitespace the
+                    // sender used.
+                    rawBody);
                 }
                 catch (error) {
                     logger_js_1.logger?.error('Failed to process SSE POST request', {

package/dist/lib/stores.d.ts

@@ -14,10 +14,31 @@ import type { IServiceKeyStore, ISessionStore } from '@mcp-abap-adt/auth-broker'
  *    - Windows: %USERPROFILE%\Documents\mcp-abap-adt\{subfolder}
  * 3. Current working directory (process.cwd())
  *
- * @param subfolder Subfolder name ('service-keys' or 'sessions')
+ * @param subfolder One of the four folders; see {@link StoreFolder}
  * @returns Array of resolved absolute paths
  */
-export declare function getPlatformPaths(subfolder?: 'service-keys' | 'sessions'): string[];
+/**
+ * The four folders the toolchain keeps under one base.
+ *
+ * `service-keys/` and `sessions/` are the auth broker's. `proxy/` holds one
+ * ready config per proxy — the files `--config` takes. `runtime/` holds a
+ * record per live proxy, so one session can see another's.
+ */
+export declare const STORE_FOLDERS: readonly ["service-keys", "sessions", "proxy", "runtime"];
+export type StoreFolder = (typeof STORE_FOLDERS)[number];
+/**
+ * THE base directory — one answer, not a search path.
+ *
+ * `AUTH_BROKER_PATH` relocates it, so all four folders move together; when it
+ * lists several, the first is the one written to. Unlike
+ * {@link getPlatformPaths}, this never falls back to the working directory: a
+ * file written beside wherever a client happened to be launched from is a file
+ * the next session will not find.
+ */
+export declare function storeBaseDir(): string;
+/** THE directory for one of the four folders. */
+export declare function storeDir(folder: StoreFolder): string;
+export declare function getPlatformPaths(subfolder?: StoreFolder): string[];
 /**
  * Get platform-specific stores
  * Returns XSUAA stores for BTP authentication:

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

@@ -1 +1 @@
-{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../src/lib/stores.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACd,MAAM,2BAA2B,CAAC;AAOnC;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,CAAC,EAAE,cAAc,GAAG,UAAU,GACtC,MAAM,EAAE,CAgEV;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,GAAE,OAAe,GAAG,OAAO,CAAC;IACxE,eAAe,EAAE,gBAAgB,CAAC;IAClC,YAAY,EAAE,aAAa,CAAC;CAC7B,CAAC,CAqBD"}
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../src/lib/stores.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACd,MAAM,2BAA2B,CAAC;AAOnC;;;;;;;;;;;;GAYG;AACH;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,2DAKhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA0BrC;AAED,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEpD;AAED,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,EAAE,CAgElE;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,GAAE,OAAe,GAAG,OAAO,CAAC;IACxE,eAAe,EAAE,gBAAgB,CAAC;IAClC,YAAY,EAAE,aAAa,CAAC;CAC7B,CAAC,CAqBD"}

package/dist/lib/stores.js

@@ -38,6 +38,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORE_FOLDERS = void 0;
+exports.storeBaseDir = storeBaseDir;
+exports.storeDir = storeDir;
 exports.getPlatformPaths = getPlatformPaths;
 exports.getPlatformStores = getPlatformStores;
 const os = __importStar(require("node:os"));
@@ -53,9 +56,61 @@ const auth_stores_1 = require("@mcp-abap-adt/auth-stores");
  *    - Windows: %USERPROFILE%\Documents\mcp-abap-adt\{subfolder}
  * 3. Current working directory (process.cwd())
  *
- * @param subfolder Subfolder name ('service-keys' or 'sessions')
+ * @param subfolder One of the four folders; see {@link StoreFolder}
  * @returns Array of resolved absolute paths
  */
+/**
+ * The four folders the toolchain keeps under one base.
+ *
+ * `service-keys/` and `sessions/` are the auth broker's. `proxy/` holds one
+ * ready config per proxy — the files `--config` takes. `runtime/` holds a
+ * record per live proxy, so one session can see another's.
+ */
+exports.STORE_FOLDERS = [
+    'service-keys',
+    'sessions',
+    'proxy',
+    'runtime',
+];
+/**
+ * THE base directory — one answer, not a search path.
+ *
+ * `AUTH_BROKER_PATH` relocates it, so all four folders move together; when it
+ * lists several, the first is the one written to. Unlike
+ * {@link getPlatformPaths}, this never falls back to the working directory: a
+ * file written beside wherever a client happened to be launched from is a file
+ * the next session will not find.
+ */
+function storeBaseDir() {
+    const envPath = process.env.AUTH_BROKER_PATH;
+    if (envPath) {
+        // Not `/[:;]/`: on Windows that splits `C:\store` into `C`, which then
+        // resolves against the working directory. The delimiter is chosen from
+        // `process.platform` rather than taken from `path.delimiter`, which is bound
+        // to the host at module load and so cannot be exercised for the other one.
+        const first = envPath
+            .split(process.platform === 'win32' ? ';' : ':')
+            .map((p) => p.trim())
+            .find((p) => p.length > 0);
+        if (first) {
+            const resolved = path.resolve(first);
+            // Pointed at one of the folders rather than the base — a plausible
+            // mistake that `getPlatformPaths` already tolerates, so this must too.
+            // Otherwise runtime records land in `.../service-keys/runtime`.
+            return exports.STORE_FOLDERS.includes(path.basename(resolved))
+                ? path.dirname(resolved)
+                : resolved;
+        }
+    }
+    const homeDir = os.homedir();
+    return process.platform === 'win32'
+        ? path.join(homeDir, 'Documents', 'mcp-abap-adt')
+        : path.join(homeDir, '.config', 'mcp-abap-adt');
+}
+/** THE directory for one of the four folders. */
+function storeDir(folder) {
+    return path.join(storeBaseDir(), folder);
+}
 function getPlatformPaths(subfolder) {
     const paths = [];
     const isWindows = process.platform === 'win32';

package/dist/mcp/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/mcp/cli.ts"],"names":[],"mappings":""}

package/dist/mcp/cli.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// src/mcp/cli.ts
+const config_js_1 = require("../lib/config.js");
+const logger_js_1 = require("../lib/logger.js");
+const server_js_1 = require("./server.js");
+/**
+ * What `bin/mcp-abap-adt-proxy-mcp.js` loads.
+ *
+ * Nothing but wiring: the bin parses `--help`/`--version` and then requires
+ * this, in the same process, so the listeners the tools start die with the
+ * session that asked for them.
+ */
+(0, server_js_1.runMcpMode)((0, config_js_1.loadConfig)()).catch((error) => {
+    logger_js_1.logger?.error('MCP mode failed to start', {
+        type: 'MCP_MODE_START_FAILED',
+        error: error instanceof Error ? error.message : String(error),
+    });
+    process.stderr.write(`[MCP Proxy] ✗ ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});