@mcp-abap-adt/proxy 1.6.4 → 4.0.0

package/docs/MIGRATION-4.0.md

@@ -0,0 +1,125 @@
+# Migration to 4.0
+
+Two things changed that a consumer can see, and one that only a programmatic
+consumer can. Everything else in this release is internal.
+
+If you run the proxy from a config file and point a client at it, **read §1 and
+stop there** — that is very likely all that applies to you.
+
+## 1. Dependencies: the contracts moved out of the umbrella
+
+`@mcp-abap-adt/interfaces` is gone from this package's dependencies. The
+contracts now come from the packages they live in:
+
+```
+@mcp-abap-adt/interfaces           ^7.0.0 → removed
+@mcp-abap-adt/interfaces-network     (new) → ^2.0.0   every HTTP header constant
+@mcp-abap-adt/interfaces-auth        (new) → ^1.2.0   ITokenRefresher
+@mcp-abap-adt/interfaces-auth-sap    (new) → ^1.0.0   IAuthorizationConfig
+@mcp-abap-adt/connection             (new) → ^9.2.0   TokenAuthProvider
+```
+
+The sibling packages moved with them — `auth-broker` to `^2.2.0` (a major),
+`auth-providers` `^2.2.2`, `auth-stores` `^1.2.0`, `header-validator` `^0.3.0`,
+`logger` `^0.4.0` — because each has left the umbrella too. Nothing in this
+package's tree asks for `@mcp-abap-adt/interfaces` any more.
+
+**What you do:** if you install this package and nothing else, nothing. If your
+own code imported a contract type and happened to resolve it through this
+package's tree, install the package that now declares it. The old name still
+exists on npm and still re-exports everything, but every one of those exports is
+marked `@deprecated`.
+
+## 2. An SSE response streams, and carries your headers
+
+This only matters if you use `transport: sse`. The `streamable-http` and `stdio`
+transports are unaffected.
+
+The SSE transport used to rebuild each request by hand, carry it over axios,
+buffer the whole answer and rewrap it as a JSON-RPC envelope. It now goes through
+the same transparent pipe as every other transport. Three consequences:
+
+**The response arrives as it is produced**, not all at once at the end. This is
+the point of the change.
+
+**Your headers reach the target.** The old path forwarded none of them and
+imposed two of its own:
+
+```
+Accept:       application/json, application/x-ndjson, text/event-stream
+Content-Type: application/json
+```
+
+It no longer does. The proxy is transparent and answers for the `Authorization`
+header only. If your target requires a particular `Accept`, put it in that
+proxy's `defaultHeaders`, where it is your choice and visible in your config:
+
+```yaml
+defaultHeaders:
+  accept: "application/json, text/event-stream"
+```
+
+A header your client sends always wins over `defaultHeaders`.
+
+**The upstream path is your client's path.** The old SSE path had three branches:
+with `targetUrl` set it used base + your client's path; with a service-key URL
+already containing `/mcp` it used that URL as-is and *discarded* your client's
+path; otherwise it appended `/mcp/stream/http`. Now it is always base + your
+client's path.
+
+**What you do:** if your config sets `targetUrl`, nothing — that is the branch
+the old code took and it behaved the same way. If it relies on the service key's
+own `abap.url`, set `targetUrl` explicitly to the URL you actually want.
+
+## 3. `BtpProxy.getJwtToken()` is replaced, not renamed
+
+Only for code that imports `BtpProxy` directly.
+
+```ts
+// before
+const token = await proxy.getJwtToken(destination);
+forward(req, res, url, token);          // composed `Bearer ${token}` itself
+
+// after
+const authorization = await proxy.getAuthorizationHeader(destination);
+forward(req, res, url, authorization);  // a complete header VALUE, or null
+```
+
+`getAuthorizationHeader()` answers the whole header value — `Bearer <token>` — or
+`null` where the credential is not a header at all, which a certificate is not.
+Pass it through as it stands: composing `Bearer` around it sends
+`Bearer Bearer <token>`, and turning `null` into `''` sends an empty
+`Authorization`, which is a different claim from having none.
+
+Gone with it: `proxyRequest()`, `buildProxyRequest()`, and the `ProxyRequest` /
+`ProxyResponse` types. They described the envelope the axios path built; there is
+no envelope any more.
+
+## 4. The circuit breaker is gone
+
+It guarded the buffered forward. The forwarding path streams, and a breaker there
+would mean buffering the response again — the thing being fixed. A target that
+keeps failing now fails visibly on every request instead of being
+short-circuited.
+
+`circuitBreakerThreshold`, `circuitBreakerTimeout` and
+`MCP_PROXY_CIRCUIT_BREAKER_*` are still read, so existing configuration loads
+unchanged. They do nothing.
+
+Retry is unaffected and still applies to getting a token: 5xx and network
+failures are retried with exponential backoff. A missing service key is not
+retried — it answers at once, naming the file to create.
+
+## What did not change
+
+The routing rules, `x-sap-destination` / `--btp`, `x-target-url` /
+`--target-url`, `defaultHeaders`, `${VAR}` interpolation, `envFile`, the service
+key layout, the transports on offer, and every configuration key except the two
+named above.
+
+## New, and entirely optional
+
+A second command, `mcp-abap-adt-proxy-mcp`, speaks MCP over stdio and its tools
+start and stop proxies from the configs in `~/.config/mcp-abap-adt/proxy/`.
+Nothing about the existing command changes because it exists — see
+[Usage](./USAGE.md#the-management-mode).

package/docs/ROUTING_LOGIC.md

@@ -0,0 +1,126 @@
+# Routing Logic Specification
+
+## Overview
+
+The proxy routes requests to MCP servers (local or on BTP) and handles BTP/XSUAA authentication.
+
+## Key Principles
+
+1. **No .env files in proxy**: Proxy should NOT use `.env` files for connection configuration. Only destinations via auth-broker (service key files) are used.
+2. **Validation only for destination**: Proxy validates only the `x-sap-destination` header. Other headers are passed directly to MCP server.
+3. **Destination priority**: Destination can be specified via command-line parameter (`--btp`) or header (`x-sap-destination`). Parameter takes precedence.
+4. **Header passthrough**: All other headers (except `x-sap-destination`) are passed directly to MCP server without validation.
+
+## Routing Scenarios
+
+### Scenario 1: BTP MCP Server (`--btp`)
+
+**Configuration:**
+- `--btp=<btp-destination>` (or header `x-sap-destination`) - BTP destination for authentication
+
+**Behavior:**
+- MCP server URL: From BTP destination service key (`abap.url` field)
+- **BTP Authentication**: Uses `btpAuthBroker` with `ClientCredentialsProvider` to get BTP Cloud token
+  - Token obtained from BTP destination service key (contains `uaa.url`, `uaa.clientid`, `uaa.clientsecret`)
+  - Injects/overwrites `Authorization: Bearer <token>` header
+
+**Use Case:** Production/cloud deployment with MCP server on BTP
+
+**Example:**
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud
+```
+
+### Scenario 2: BTP MCP Server with explicit target URL (`--btp` + `--target-url`)
+
+**Configuration:**
+- `--btp=<btp-destination>` (or header `x-sap-destination`) - BTP destination for authentication
+- `--target-url=<url>` (or header `x-target-url`) - Override the target URL
+
+**Behavior:**
+- MCP server URL: From `--target-url` (overrides the `abap.url` from the service key)
+- **BTP Authentication**: Auth token still comes from the `--btp` destination service key
+  - Injects/overwrites `Authorization: Bearer <token>` header
+
+**Use Case:** Auth comes from one service key, but requests must go to a different URL
+(e.g. direct OData testing or a non-standard MCP path)
+
+**Example:**
+```bash
+mcp-abap-adt-proxy --btp=btp-cloud \
+  --target-url=https://mcp-server.cfapps.eu10.hana.ondemand.com
+```
+
+> **Note:** Direct unauthenticated routing via `--mcp-url` / `x-mcp-url` has been
+> **removed**. A BTP destination (`--btp` or `x-sap-destination`) is required; without
+> it the proxy cannot resolve a target or obtain a token.
+
+## Header Mapping
+
+### Validated Headers
+
+| Header | Source | Description |
+|--------|--------|-------------|
+| `x-sap-destination` | Request header or `--btp` parameter | BTP destination name for authentication |
+
+**Note:** This is the ONLY header that proxy validates. All other headers are passed directly to MCP server.
+
+### Headers Added by Proxy
+
+| Source | Target Header | Description |
+|--------|---------------|-------------|
+| BTP destination token (via `btpAuthBroker` with `ClientCredentialsProvider`) | `Authorization: Bearer <token>` | For MCP server on BTP (when `x-sap-destination` or `--btp` is provided) |
+
+### Headers Passed Through
+
+All headers from the original request (except `x-sap-destination`) are passed directly to MCP server without modification. This includes any custom headers the MCP server might need.
+
+## Current Implementation Analysis
+
+### What Works Correctly
+
+1. **BTP AuthBroker architecture**: `btpAuthBroker` with `ClientCredentialsProvider` for BTP destinations (service keys with `uaa` section)
+2. **BTP destination handling**: Correctly gets token from BTP destination using `btpAuthBroker` for MCP server authorization
+3. **Service key store**: `XsuaaServiceKeyStore` correctly reads service keys for BTP destinations
+4. **Command-line overrides**: `--btp`, `--target-url` work as expected
+5. **Header passthrough**: Original headers are preserved and forwarded to MCP server
+6. **Platform path resolution**: Correctly determines service key and session paths for Unix and Windows
+
+## Testing Scenarios
+
+### Test 1: BTP MCP with explicit target URL
+```bash
+# Start proxy
+mcp-abap-adt-proxy --btp=btp-cloud \
+  --target-url=https://mcp-server.cfapps.eu10.hana.ondemand.com
+
+# Send request with headers
+curl -X POST http://localhost:3001/mcp/stream/http \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+**Expected:**
+- Request forwarded to the `--target-url` value with `Authorization: Bearer <btp-token>`
+
+### Test 2: BTP MCP with BTP Destination
+```bash
+# Start proxy
+mcp-abap-adt-proxy --btp=btp-cloud
+
+# Send request
+curl -X POST http://localhost:3001/mcp/stream/http \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+**Expected:**
+- MCP server receives: `Authorization: Bearer <btp-token>` (from BTP destination)
+- MCP server URL obtained from BTP destination service key
+
+## Summary
+
+The proxy supports flexible routing:
+- **BTP Authentication Mode**: Use `--btp` for BTP authentication, MCP URL from service key
+- **Explicit URL Mode**: Use `--btp` + `--target-url` for BTP auth with an overridden target URL
+- **No .env files**: Only use destinations via auth-broker, never .env files