# SAP WebGUI MCP

Experimental, standalone MCP server for **approved SAP WebGUI reads over BTP principal propagation**.
It reuses `@arc-mcp/xsuaa-auth` for XSUAA OAuth and BTP Destination/Connectivity integration.
It is separate from ARC-1 and does not extend ARC-1's twelve tools.

**Status:** implemented PoC with local automated tests. The earlier operator-driven WebGUI/PP spike
worked against SAP; this packaged browser adapter has **not yet been qualified against live SAP**.
Live reads are disabled by default. Do not deploy it as a production service yet.

## Try the local demo

Requires Node **22.18+** and npm. From this checkout:

```sh
npm ci
npm run build
npm start -- --demo
```

Connect a Streamable HTTP MCP client to `http://127.0.0.1:8080/mcp`. Demo mode binds only to
loopback, uses no SAP credentials or browser, and labels every result `synthetic_fixture`.
Use `WEBGUI_PORT=8081` to select another port. The transport is HTTP, not stdio.

After publication, the equivalent command is `npx @arc-mcp/sap-webgui-mcp@next --demo`.
That command is a publishing target, not a claim that the package is already available.

## Tools

| Tool | Input | Result and boundary |
| --- | --- | --- |
| `WebGUIStatus` | `{}` | Mode, approved objects and limits. Does not prove SAP connectivity. |
| `WebGUIRead` | `{"kind":"table","name":"SCARR"}` | DDIC fields for a fully visible table, selected data-element/domain technical attributes, or displayed main source. One isolated session per call. |

Read kinds: `table`, `data_element`, `domain`, `source`. An administrator must approve each
exact kind/name pair and map each verified principal to its expected SAP user. No generic
transaction commands, click tools, arbitrary URLs, report execution, SQL, table data or changes
are exposed. A paged/ambiguous screen fails closed. `complete` refers only to the named coverage
in the result; it does not mean every DDIC tab or source include was read.

SAP text and source are untrusted data, not instructions for the model.

## Live BTP setup

Read [the runbook](docs/runbook.md) before enabling reads. Required components are a dedicated
XSUAA binding, Destination and Connectivity bindings, an HTTPS public MCP route, a
`PrincipalPropagation`/`OnPremise` destination, SCC HTTPS certificate propagation to SAP,
a reviewed display-only SAP role, and the policy in `config/policy.example.json`.

The example policy contains **no approved principals**. Copy it into ignored `local/`, fill it
from verified claims, and set `WEBGUI_POLICY_FILE` to that file. Never paste tokens into the policy.
Keep `WEBGUI_ENABLE_LIVE_READS=false` until the qualification plan authorizes the named run.

Chromium is an explicit installation step, not an npm postinstall side effect:

```sh
npm run install:browsers
```

The runtime requires Chromium's sandbox. Linux additionally needs the Playwright system
dependencies. CF/container sandbox compatibility is an open qualification gate.

## Development and publishing

```sh
npm run check             # Biome, strict TypeScript, unit/MCP tests, build, package smoke
npm run test:spikes       # archived research regression tests; no SAP calls
npm run test:browser      # Chromium against synthetic local fixtures; no SAP calls
npm audit
```

Husky/lint-staged use Biome; commitlint enforces conventional commits. GitHub workflows include
CI, CodeQL, dependency review, Dependabot, release-please and npm trusted publishing with
provenance. The npm channel is `next` while production gates remain open.
See [publishing](docs/publishing.md) for the one-time repository/npm setup.

## Continue without the original conversation

Start at **[docs/HANDOFF.md](docs/HANDOFF.md)**. It links the evidence ledger, architecture,
authorization design, prioritized spike plan and reproducible runbook. Sanitized historical
notes and their original test harness live under `docs/research/` and `research/spikes/`.
Operator-specific lab details are in ignored `local/`; they are never part of Git or npm.

License: MIT. Unaffiliated with SAP; no claim of SAP-supported browser automation.