guniweb-sap-mcp 0.2.2 → 0.3.0

package/README.md

@@ -67,7 +67,7 @@ graph TB
 - **Three Transport Modes** -- stdio, Streamable HTTP, SSE
 - **API Key Protection** -- Secure HTTP transport with Bearer token
 - **Docker Ready** -- Docker Compose for n8n + SAP MCP sidecar
-- **1143 Tests** -- Unit, integration, E2E with CI/CD via GitHub Actions
+- **1267 Tests** -- Unit, integration, E2E with CI/CD via GitHub Actions
 
 ## Quick Start
 
@@ -159,6 +159,79 @@ Clients that *require* a session id — they read `mcp-session-id` from the init
 
 The legacy `--transport sse` mode is different: it keeps a per-connection session and expects a `?sessionId=` query parameter on `/messages`. Prefer `http` for new setups.
 
+#### Several SAP systems: `destinations.json`
+
+The `SAP_*` variables describe **one** SAP system. To run one server against several — a production system next to a test client, or several customers' systems behind one n8n — put the connections into a `destinations.json` and point the server at it:
+
+```bash
+guniweb-sap-mcp --transport http --port 8808 --destinations /config/destinations.json
+# or: SAP_MCP_DESTINATIONS=/config/destinations.json
+```
+
+```json
+{
+  "version": 1,
+  "destinations": {
+    "default": {
+      "baseUrl": "https://s4prod.example.com",
+      "authType": "basic",
+      "username": "MCP_USER",
+      "password": "${S4PROD_PASSWORD}",
+      "sapClient": "100"
+    },
+    "s4test": {
+      "baseUrl": "https://s4test.example.com",
+      "authType": "basic",
+      "username": "MCP_USER",
+      "password": "${S4TEST_PASSWORD}",
+      "sapClient": "200"
+    }
+  }
+}
+```
+
+- **One entry = one connection.** Every entry accepts exactly the fields the `SAP_*` variables accept (`authType` and its credentials, `sapClient`, `baseUrl`) — all seven authentication types work per destination.
+- **Secrets stay out of the file.** Any string may contain `${VARIABLE}`; it is resolved from the environment at load time (Docker secrets, `.env`). A placeholder that cannot be resolved makes the file invalid — an empty password would otherwise surface as a misleading `401` from SAP.
+- **Hot reload.** The file is watched; a change is picked up on the next request, no restart. `kill -HUP <pid>` forces a reload. An invalid file **never** replaces the running configuration — the error is logged and the last valid one stays in force.
+- **Backwards compatible.** Without `--destinations` nothing changes: the `SAP_*` variables are the single destination `default`. With the file, `SAP_*` (if set) is added as `default` unless the file defines one — so an installation can migrate without a gap.
+- **Which destination answers?** Without a token: the one named `default` (or the only one). With a token: the token's destination — see below.
+
+**Tokens: one Bearer value per n8n credential selects the system.** The n8n MCP Client sends exactly one `Authorization` header, so a token does two jobs at once — it authenticates the request and picks the destination. SAP passwords never leave the server; n8n only holds the token.
+
+```json
+{
+  "version": 1,
+  "destinations": { "s4prod": { "...": "..." }, "s4test": { "...": "..." } },
+  "tokens": [
+    { "hash": "sha256:9f2c…", "destination": "s4prod", "label": "n8n prod workflows" },
+    { "hash": "sha256:1a7e…", "destination": "s4test", "label": "n8n dev", "revoked": false }
+  ]
+}
+```
+
+- The file holds only the **SHA-256 hash**; the plain token (`gsm_<destination>_<random>`) is printed **once** by `tokens issue` and cannot be recovered afterwards. Put it into an n8n **Bearer Auth** credential on the MCP Client node. As soon as at least one token exists, requests without a valid token get `401` — `--api-key` keeps working alongside and serves the `default` destination.
+- Lookup is constant-time over all entries; `"revoked": true` disables a token on the next request (hot reload, no restart). After 10 failed attempts within a minute the client address gets `429` with `Retry-After` — also for a valid token — as a brake on guessing (a reverse proxy with a real rate limit is still the right place for that). Tokens are never written to the log; rejections are logged with address and reason.
+**Managing the file — no hand-editing needed.** The same binary carries the admin commands; every command validates the result exactly like the server does before writing (never leaves an unloadable file), writes atomically, and a running server picks the change up on the next request:
+
+```bash
+export SAP_MCP_DESTINATIONS=/config/destinations.json      # or --destinations <path> on each call
+
+guniweb-sap-mcp destinations add s4prod --base-url https://s4prod.example.com --auth-type basic \
+    --username MCP_USER --password '${S4PROD_PASSWORD}' --sap-client 100
+guniweb-sap-mcp destinations add legacy --from-env         # copy the current SAP_* environment (migration)
+guniweb-sap-mcp destinations list                          # names, URLs, auth type, client, token count — never secrets
+
+guniweb-sap-mcp tokens issue s4prod --label "n8n prod" --read-only --tiers core,odata
+#   → prints the plain token ONCE on stdout (everything else goes to stderr, so TOKEN=$(…) works)
+guniweb-sap-mcp tokens list                                # label, destination, hash prefix, policy, status
+guniweb-sap-mcp tokens revoke "n8n prod"                   # by label or ≥ 8 hex chars of the hash
+guniweb-sap-mcp destinations remove s4test [--force]       # refuses while tokens point at it, unless --force
+```
+
+`--set field=value` covers any auth type (`--auth-type oauth2 --set clientId=… --set clientSecret='${BTP_SECRET}' --set tokenServiceUrl=…`); `${ENV_VAR}` values are checked against the current environment (`--allow-missing-env` to skip, e.g. when the variable only exists inside the container). In Docker, run the commands inside the container so they see the same file and environment: `docker compose exec sap-mcp guniweb-sap-mcp tokens issue s4prod`.
+
+- **Per-token permissions** — `"policy": { "readOnly": true, "tiers": ["core", "odata"] }`. A policy only ever *restricts*: `readOnly: true` hides the write tools for that token even when the server runs with `--allow-write` (`readOnly: false` cannot open a read-only server), and `tiers` is a ceiling — tiers outside it are invisible for that token and `sap_enable_tools` cannot switch them on. `tools/list` is filtered per request, so an agent on a read-only token never sees `sap_create` in the first place.
+
 ### 4. Use with n8n
 
 1. Add an **AI Agent** node with an **MCP Client Tool** sub-node