@mcp-abap-adt/proxy 2.0.0 → 4.0.1

package/docs/USAGE.md

@@ -0,0 +1,422 @@
+# Usage Examples
+
+This document provides practical examples of using `@mcp-abap-adt/proxy`.
+
+## Installation
+
+```bash
+npm install @mcp-abap-adt/proxy
+```
+
+## Basic Usage
+
+### Starting the Proxy Server
+
+#### Using a BTP destination
+
+```bash
+# Start server with a BTP destination (matches a service-key file)
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+#### Using a Configuration File
+
+Create `mcp-proxy-config.yaml` (see [YAML Configuration Guide](./YAML_CONFIG.md)):
+
+```yaml
+transport: streamable-http
+httpPort: 3001
+btpDestination: "btp-cloud"
+logLevel: "info"
+```
+
+Start server:
+```bash
+mcp-abap-adt-proxy --config=mcp-proxy-config.yaml
+```
+
+#### Using Environment Variables
+
+```bash
+export MCP_HTTP_PORT=8080
+export LOG_LEVEL=debug
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+## Usage Scenarios
+
+### Scenario 1: BTP Authentication Mode
+
+**Use Case:** Proxy requests to an MCP server on BTP with JWT authentication
+
+**Client Configuration:**
+```json
+{
+  "mcp-abap-adt-proxy": {
+    "disabled": false,
+    "timeout": 60,
+    "type": "streamableHttp",
+    "url": "http://localhost:3001/mcp/stream/http",
+    "headers": {
+      "x-sap-destination": "btp-cloud"
+    }
+  }
+}
+```
+
+**What Happens:**
+1. Proxy receives request with `x-sap-destination` header
+2. Command line override (`--btp`) takes precedence over header if provided
+3. Uses `btpAuthBroker` with `ClientCredentialsProvider` to get BTP Cloud token from service key
+4. Gets MCP server URL from service key (`abap.url` field)
+5. Injects/overwrites `Authorization: Bearer <btp-token>` header
+6. Proxies request to MCP server URL from service key
+7. Target MCP server processes request and returns response
+8. Proxy forwards response to client
+
+**Using Command Line Overrides:**
+
+You can override headers using command line parameters:
+
+```bash
+# Override x-sap-destination with --btp
+mcp-abap-adt-proxy --btp=ai
+```
+
+Command line parameters work even if the corresponding headers are missing in the request.
+
+### Scenario 2: BTP Auth with Target URL Override
+
+**Use Case:** Authenticate with one BTP destination's service key, but forward requests
+to a different URL (e.g. direct OData testing or a non-standard MCP path).
+
+**Client Configuration:**
+```json
+{
+  "mcp-abap-adt-proxy": {
+    "disabled": false,
+    "timeout": 60,
+    "type": "streamableHttp",
+    "url": "http://localhost:3001/mcp/stream/http",
+    "headers": {
+      "x-sap-destination": "btp-cloud",
+      "x-target-url": "https://your-service.cfapps.eu10.hana.ondemand.com"
+    }
+  }
+}
+```
+
+**Or using command line:**
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud \
+  --target-url=https://your-service.cfapps.eu10.hana.ondemand.com
+```
+
+**What Happens:**
+1. Proxy gets a BTP token from the `btp-cloud` service key
+2. Injects `Authorization: Bearer <token>`
+3. Forwards the request to `x-target-url` / `--target-url` instead of the key's `abap.url`
+4. Target server processes request and returns response
+
+**Service Key Structure:**
+The service key for BTP destination should contain the MCP server URL:
+```json
+{
+  "uaa": {
+    "url": "https://your-uaa-url.com",
+    "clientid": "your-client-id",
+    "clientsecret": "your-client-secret"
+  },
+  "abap": {
+    "url": "https://your-mcp-server.com"
+  }
+}
+```
+
+The `abap.url` field is used as the MCP server URL (even though it's named "abap", it can point to any MCP server).
+
+## The management mode
+
+A second command, `mcp-abap-adt-proxy-mcp`, speaks MCP over stdio and its tools
+start and stop proxies. Use it when the client should decide which proxy runs and
+when; use `mcp-abap-adt-proxy` when you want to be proxied.
+
+```json
+{
+  "mcpServers": {
+    "abap-proxy": { "command": "mcp-abap-adt-proxy-mcp" }
+  }
+}
+```
+
+It works from the configs in `~/.config/mcp-abap-adt/proxy/` — the same files
+`--config` takes — so starting a proxy is choosing a name:
+
+| 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_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 |
+
+Two things worth knowing before you rely on it:
+
+- **The proxies live in the management process.** Closing the session — or
+  `SIGINT`, or `SIGTERM` — stops all of them. A stop cuts requests still in
+  flight after a short grace, because a streamed response never ends on its own
+  and the port has to come back.
+- **`proxy_start` proves the credential before reporting success**, so an
+  interactive login happens where you asked for it rather than inside whatever
+  tool call happens to make the first request.
+
+See [Configuration](./CONFIGURATION.md#the-management-mode) for `idleTimeoutMs`
+and what the mode deliberately ignores from a config.
+
+## Programmatic Usage
+
+### Using as a Library
+
+```typescript
+import { McpAbapAdtProxyServer } from "@mcp-abap-adt/proxy";
+
+async function main() {
+  const server = new McpAbapAdtProxyServer();
+
+  // Handle shutdown gracefully
+  process.on("SIGINT", async () => {
+    await server.shutdown();
+    process.exit(0);
+  });
+
+  await server.run();
+}
+
+main().catch(console.error);
+```
+
+### Custom Configuration
+
+```typescript
+import { McpAbapAdtProxyServer } from "@mcp-abap-adt/proxy";
+import { parseTransportConfig } from "@mcp-abap-adt/proxy/lib/transportConfig";
+
+const transportConfig = parseTransportConfig();
+const server = new McpAbapAdtProxyServer(
+  transportConfig,
+  "/path/to/custom-config.json"
+);
+
+await server.run();
+```
+
+## Transport Modes
+
+### HTTP/Streamable HTTP (Default)
+
+```bash
+mcp-abap-adt-proxy --transport=streamable-http --http-port=3001
+```
+
+### SSE (Server-Sent Events)
+
+```bash
+mcp-abap-adt-proxy --transport=sse --sse-port=3002
+```
+
+### Stdio (for MCP clients)
+
+```bash
+mcp-abap-adt-proxy --transport=stdio
+```
+
+## Advanced Configuration
+
+### Custom Retry Settings
+
+```yaml
+btpDestination: "btp-cloud"
+maxRetries: 5
+retryDelay: 2000
+requestTimeout: 120000
+```
+
+### Circuit Breaker Configuration
+
+```yaml
+btpDestination: "btp-cloud"
+circuitBreakerThreshold: 10
+circuitBreakerTimeout: 120000
+```
+
+## Integration Examples
+
+### With Cline
+
+1. Install proxy:
+```bash
+npm install -g @mcp-abap-adt/proxy
+```
+
+2. Start proxy server:
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+3. Configure Cline (`cline.json`):
+```json
+{
+  "mcpServers": {
+    "mcp-abap-adt-proxy": {
+      "disabled": false,
+      "timeout": 60,
+      "type": "streamableHttp",
+      "url": "http://localhost:3001/mcp/stream/http",
+      "headers": {
+        "x-sap-destination": "btp-cloud"
+      }
+    }
+  }
+}
+```
+
+### With Custom MCP Client
+
+```typescript
+import axios from "axios";
+
+async function callProxy(method: string, params: any) {
+  const response = await axios.post(
+    "http://localhost:3001/mcp/stream/http",
+    {
+      jsonrpc: "2.0",
+      method,
+      params,
+      id: 1,
+    },
+    {
+      headers: {
+        "Content-Type": "application/json",
+        "x-sap-destination": "btp-cloud",
+      },
+    }
+  );
+
+  return response.data;
+}
+
+// Example usage
+const result = await callProxy("tools/list", {});
+console.log(result);
+```
+
+## Service Key Setup
+
+For BTP destination-based authentication, you need to set up service keys:
+
+1. Create service key file: `btp-cloud.json`
+```json
+{
+  "uaa": {
+    "url": "https://your-uaa-url.com",
+    "clientid": "your-client-id",
+    "clientsecret": "your-client-secret"
+  },
+  "abap": {
+    "url": "https://your-mcp-server.com"
+  }
+}
+```
+
+2. Place service key in platform-specific location:
+   - **Unix**: `~/.config/mcp-abap-adt/service-keys/btp-cloud.json`
+   - **Windows**: `%USERPROFILE%\Documents\mcp-abap-adt\service-keys\btp-cloud.json`
+
+3. Use destination in proxy:
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+Or via header:
+```json
+{
+  "headers": {
+    "x-sap-destination": "btp-cloud"
+  }
+}
+```
+
+## Debugging
+
+### Enable Debug Logging
+
+```bash
+export LOG_LEVEL=debug
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+### Check Routing Decisions
+
+The proxy logs routing decisions:
+```
+[INFO] Routing decision made: { strategy: "PROXY", btpDestination: "btp-cloud" }
+```
+
+### Monitor Circuit Breaker
+
+Circuit breaker state is logged:
+```
+[WARN] Circuit breaker opened due to failures: { failures: 5, threshold: 5 }
+```
+
+## Common Patterns
+
+### Pattern 1: Development Environment
+
+```bash
+export LOG_LEVEL=debug
+export MCP_HTTP_PORT=3001
+
+mcp-abap-adt-proxy --btp=dev-btp
+```
+
+### Pattern 2: Production Environment
+
+```yaml
+# mcp-proxy-config.yaml
+transport: streamable-http
+httpPort: 3001
+btpDestination: "prod-btp"
+logLevel: "info"
+maxRetries: 5
+circuitBreakerThreshold: 10
+```
+
+### Pattern 3: Multiple Destinations
+
+Use different destination names for different environments:
+
+```json
+{
+  "headers": {
+    "x-sap-destination": "dev-btp"
+  }
+}
+```
+
+```json
+{
+  "headers": {
+    "x-sap-destination": "prod-btp"
+  }
+}
+```
+
+### Pattern 4: Using Command Line Overrides
+
+Override destination via command line (useful for development/testing):
+
+```bash
+# Use 'ai' for BTP regardless of headers
+mcp-abap-adt-proxy --btp=ai
+```
+
+This is especially useful when you want to use the same destination for all requests without modifying client configuration.

package/docs/YAML_CONFIG.md

@@ -0,0 +1,290 @@
+# YAML Configuration Guide
+
+The MCP ABAP ADT Proxy supports loading configuration from YAML or JSON files, providing a convenient alternative to command-line parameters and environment variables.
+
+## Quick Start
+
+1. Copy the example configuration file:
+   ```bash
+   cp docs/mcp-proxy-config.example.yaml mcp-proxy-config.yaml
+   ```
+   Or from the project root:
+   ```bash
+   cp mcp-proxy-config.example.yaml mcp-proxy-config.yaml
+   ```
+
+2. Customize the configuration for your environment
+
+3. Run the proxy with the config file:
+   ```bash
+   mcp-abap-adt-proxy --config=mcp-proxy-config.yaml
+   ```
+   Or use the short form:
+   ```bash
+   mcp-abap-adt-proxy -c mcp-proxy-config.yaml
+   ```
+
+## Configuration File Location
+
+There is **no auto-discovery**. The config file is loaded **only** when you pass it
+explicitly via `--config` (or `-c`):
+
+```bash
+mcp-abap-adt-proxy --config=/path/to/mcp-proxy-config.yaml
+```
+
+Both `.yaml`/`.yml` and `.json` files are supported (format is detected by extension).
+
+## Configuration Modes
+
+- **With `--config`**: configuration is loaded from the file as the baseline.
+  CLI flags (`--btp`, `--target-url`, `--unsafe`, `--browser`, `--browser-auth-port`,
+  `--header`) override matching values from the file; `--header` entries are merged
+  per key with `defaultHeaders`. Any value missing from both falls back to its
+  built-in default. The proxy logs which keys were overridden on startup.
+- **Without `--config`**: configuration comes from CLI parameters and environment
+  variables only (see [CONFIGURATION.md](./CONFIGURATION.md)). The config file is
+  not consulted.
+
+## YAML Configuration Template
+
+```yaml
+# MCP ABAP ADT Proxy Configuration
+# Load explicitly: mcp-abap-adt-proxy --config=mcp-proxy-config.yaml
+
+# Transport configuration
+transport: streamable-http  # stdio | http | streamable-http | sse
+httpPort: 3001
+httpHost: "127.0.0.1"
+ssePort: 3002
+sseHost: "127.0.0.1"
+
+# BTP destination for Cloud authorization (Authorization: Bearer token).
+# Must match a service key: ~/.config/mcp-abap-adt/service-keys/<btpDestination>.json
+btpDestination: "btp"
+
+# Target URL override (optional). Auth still comes from the service key above,
+# but requests are forwarded here instead of the key's abap.url.
+# targetUrl: "https://your-service.cfapps.eu10.hana.ondemand.com"
+
+# Default headers injected into every forwarded request.
+# Client-supplied headers take precedence over these.
+defaultHeaders:
+  x-sap-destination: "S4HANA_E19"
+
+# OAuth2 login browser
+browser: "system"      # system | headless | chrome | edge | firefox | none
+browserAuthPort: 7777  # port for the local OAuth2 callback server;
+                       # bound only while you are logging in, then released.
+                       # Pick a number no other local service listens on.
+
+# Session storage mode
+unsafe: false  # If true, persists tokens to disk. If false, uses in-memory storage (secure)
+
+# Error handling & resilience
+maxRetries: 3
+retryDelay: 1000  # milliseconds
+requestTimeout: 60000  # milliseconds
+
+# Logging
+logLevel: "info"  # debug | info | warn | error
+```
+
+## Configuration Examples
+
+### Example 1: BTP Authentication Mode
+
+```yaml
+transport: http
+httpPort: 3001
+btpDestination: "btp"
+```
+
+Run with:
+```bash
+mcp-abap-adt-proxy --config=mcp-proxy-config.yaml
+```
+
+### Example 2: BTP Auth with Target URL Override
+
+```yaml
+transport: http
+httpPort: 3001
+btpDestination: "btp"
+targetUrl: "https://your-service.cfapps.eu10.hana.ondemand.com/v1"
+```
+
+Auth tokens come from the `btp` service key, but requests are forwarded to `targetUrl` instead of the URL in the service key.
+
+### Example 3: BTP Auth with Per-User ABAP Credentials
+
+```yaml
+transport: streamable-http
+httpPort: 3001
+btpDestination: "btp"
+envFile: "secrets.env"   # resolved relative to this file's directory
+defaultHeaders:
+  x-sap-destination: "S4HANA_E19"
+  x-sap-login: "${SAP_USER}"
+  x-sap-password: "${SAP_PASSWORD}"
+```
+
+Every forwarded request gets `x-sap-destination` (unless the client supplies one)
+plus the caller's `x-sap-login` / `x-sap-password`, resolved from environment
+variables.
+
+#### Environment-variable interpolation
+
+String config values may contain `${VAR}` or `${VAR:-default}` placeholders:
+
+- Values resolve from `process.env` first, then the `envFile`, then `:-default`.
+- `process.env` overrides the same key in the `envFile`.
+- A `${VAR}` without a default that cannot be resolved fails the proxy at startup
+  with an error naming the variable.
+- `envFile` is resolved relative to the config file's directory; `--env-file <path>`
+  on the command line overrides it. There is no automatic `.env` discovery.
+- The `envFile` is user-local and must never be committed.
+
+### Example 4: SSE Transport
+
+```yaml
+transport: sse
+ssePort: 3002
+sseHost: "127.0.0.1"
+btpDestination: "btp"
+```
+
+### Example 5: Custom Error Handling
+
+```yaml
+transport: http
+httpPort: 3001
+btpDestination: "btp"
+maxRetries: 5
+retryDelay: 2000
+requestTimeout: 120000
+```
+
+## Configuration Fields Reference
+
+### Transport Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `transport` | `string` | `"streamable-http"` | Transport type: `stdio`, `http`, `streamable-http`, `sse` |
+| `httpPort` | `number` | `3001` | HTTP server port |
+| `ssePort` | `number` | `3002` | SSE server port |
+| `httpHost` | `string` | `"127.0.0.1"` | HTTP server host (loopback by default; set `0.0.0.0` to expose) |
+| `sseHost` | `string` | `"127.0.0.1"` | SSE server host (loopback by default; set `0.0.0.0` to expose) |
+
+### Destination & Headers
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `btpDestination` | `string` | `undefined` | BTP destination name (for Cloud authorization). Must match a service key file. |
+| `targetUrl` | `string` | `undefined` | Override target URL (uses auth from `btpDestination` but forwards to this URL) |
+| `defaultHeaders` | `map` | `undefined` | Headers injected into every forwarded request; client headers take precedence |
+| `envFile` | `string` | `undefined` | Path to a `.env` file (resolved relative to the config file) supplying variables for `${VAR}` interpolation; overridden by `--env-file` |
+
+### Authentication Browser
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `browser` | `string` | `"system"` | OAuth2 login browser: `system`, `headless`, `chrome`, `edge`, `firefox`, `none` |
+| `browserAuthPort` | `number` | `3333` | Port for the local OAuth2 callback server. Bound only for the duration of an interactive login, then released — see [How long the callback port is held](./CONFIGURATION.md#how-long-the-callback-port-is-held) |
+
+### Session Storage
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `unsafe` | `boolean` | `false` | If `true`, persists tokens to disk. If `false`, uses in-memory storage (secure) |
+
+### Error Handling
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `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 |
+
+### Logging
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `logLevel` | `string` | `"info"` | Log level: `debug`, `info`, `warn`, `error` |
+
+## Using YAML Config in VS Code Debugging
+
+You can use YAML configuration files when debugging in VS Code. The `launch.json` includes a configuration for this:
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "MCP Proxy (YAML Config)",
+  "program": "${workspaceFolder}/bin/mcp-abap-adt-proxy.js",
+  "args": [
+    "--config=mcp-proxy-config.yaml"
+  ],
+  "console": "integratedTerminal",
+  "env": {
+    "NODE_ENV": "development",
+    "LOG_LEVEL": "debug"
+  }
+}
+```
+
+## Security Notes
+
+- **Never commit** your `mcp-proxy-config.yaml` file to version control (it's already in `.gitignore`)
+- Use `.mcp-proxy-config.yaml` (with leading dot) for hidden configuration files
+- Service keys are stored separately in `~/.config/mcp-abap-adt/service-keys/` (Unix) or `%USERPROFILE%\Documents\mcp-abap-adt\service-keys` (Windows)
+- Set `unsafe: false` (default) to use secure in-memory session storage
+
+## Troubleshooting
+
+### Configuration file not found
+
+If you get an error that the configuration file is not found:
+1. Check that the file exists at the specified path
+2. Verify the file extension (`.yaml`, `.yml`, or `.json`)
+3. Check file permissions
+
+### Configuration values not applied
+
+Remember that command-line parameters take precedence over configuration files. If a value isn't being applied:
+1. Check if you're passing the same parameter via command line
+2. Verify the YAML syntax is correct (use a YAML validator)
+3. Check for typos in field names
+
+### YAML parsing errors
+
+If you get YAML parsing errors:
+1. Verify the YAML syntax (indentation matters!)
+2. Check for special characters that need quoting
+3. Ensure all strings are properly quoted if they contain special characters
+
+## See Also
+
+- [Configuration Guide](./CONFIGURATION.md) - General configuration documentation
+- [Usage Guide](./USAGE.md) - Command-line usage examples
+- [Client Setup Guide](./CLIENT_SETUP.md) - Setting up clients like Cline