From cbc2aae33a2dbd736371746d2d98fbb36e25e48d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 11:25:01 +0000 Subject: [PATCH] README: point at the documentation page instead of carrying it What MCP means here, the three setup levels, registering the server with each client and the loop the tools are meant to be used in now live at https://abap2ui5.github.io/docs/advanced/mcp_server.html, written for somebody who has not set up an MCP server before. What stays here is the quick start, the tool table, the operational notes that only matter once it is running, and how to work on the repository. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01YM2A6eh3sX7ssGDuagbSGG --- README.md | 216 +++++++++++++++++------------------------------------- 1 file changed, 68 insertions(+), 148 deletions(-) diff --git a/README.md b/README.md index bf8d88d..59ffc26 100644 --- a/README.md +++ b/README.md @@ -13,117 +13,45 @@ examples -> app_guide -> validate_view + screenshot_view -> deploy_app -> build_ The agent writes an ABAP class, validates the view **and looks at a picture of it** in seconds, deploys it, boots it in a real browser and looks at the -running app — then iterates. The two ways of seeing it cost three orders of -magnitude apart: `screenshot_view` renders the reconstructed view with no -backend at all, `run_app` boots the transpiled app and needs a build first. -Everything runs locally on infrastructure that already guards the abap2UI5 -ecosystem in CI: the abaplint transpiler + open-abap runtime, the framework's -express shim, the [samples-controls](https://github.com/abap2UI5/samples-controls) build -and boot gates, and the [abap2UI5-linter](https://github.com/abap2UI5/linter) -validation core. +running app — then iterates. Everything runs locally on infrastructure that +already guards the abap2UI5 ecosystem in CI: the abaplint transpiler + +open-abap runtime, the framework's express shim, the +[samples-controls](https://github.com/abap2UI5/samples-controls) build and boot +gates, and the [linter](https://github.com/abap2UI5/linter) validation core. -## Setup +## Documentation -The tools need different things, so you can stop at the level you need. Each -step adds the ones below it. +**→ [The MCP server, in full](https://abap2ui5.github.io/docs/advanced/mcp_server.html)** +— what MCP means here, the three setup levels and what each one buys, how to +register the server with your client, every tool with what the agent gets from +it, and the loop they are meant to be used in. -### Level 1 — validate and SEE views (~3 MB, a minute) +**→ [Building with AI](https://abap2ui5.github.io/docs/get_started/ai.html)** — +the whole AI setup in rising order of effort. This server is the top rung; the +cheaper ones matter first. -`validate_view` and `screenshot_view`, the two tools you reach for most: they -reconstruct the view your ABAP builds, check it against the UI5 API and -photograph it. No SAP system, no backend, no transpile — seconds per answer. +## Quick start -(`screenshot_view` additionally needs the linter's render runtime and a -browser: `npm i -D @abap2ui5/render-runtime && npx playwright install chromium` -in the linter checkout. `validate_view`'s property gate needs neither.) +Level 1 — `validate_view` and `screenshot_view`, the two tools most work +happens at (~3 MB, a minute): ```sh -git clone https://github.com/abap2UI5/linter # AI_VIEW_CHECK_HOME +git clone https://github.com/abap2UI5/linter # AI_VIEW_CHECK_HOME git clone https://github.com/abap2UI5/mcp-server cd linter && npm ci && cd ../mcp-server && npm ci ``` -The other tools answer with an actionable message naming what is missing -rather than failing — the server starts either way. - -### Level 2 — the catalogues and deploying (~110 MB) - -`examples`, `capabilities`, `app_guide`, `scaffold_app`, `generation_rules`, -`pitfalls`, `scope_of`, `deploy_app`. - -```sh -git clone https://github.com/abap2UI5/abap2UI5 # A2UI5_HOME -git clone https://github.com/abap2UI5/samples-controls # SAMPLES_CONTROLS_HOME -git clone https://github.com/abap2UI5/samples # SAMPLES_HOME -git clone https://github.com/abap2UI5/samples-stack # SAMPLES_STACK_HOME -cd abap2UI5 && npm ci && cd ../samples-controls && npm ci -``` - -`examples` needs only the clones — no install — and it is the cheapest useful -thing here: it answers *"has somebody already built a value help / a tree / -navigation between two apps"* out of **614 working apps in three repositories**, -and hands back a class to read rather than a snippet to trust. - -| repository | what it answers | -|---|---| -| `samples` (152) | the patterns, on a bare abap2UI5 install | -| `samples-controls` (430) | how a specific UI5 **control** is expressed — the demo kit, rebuilt | -| `samples-stack` (32) | the same, for apps that need OData, RAP, APC or the launchpad | - -Any one of the three is enough to start: a missing clone is reported in the -answer, not fatal. The neighbouring question, *"can abap2UI5 express this UI5 -control **at all**"*, is `capabilities`, out of samples-controls' -`CAPABILITIES.md`. Neither answers the other. - -### Level 3 — see the app (a browser, and time) - -`build_backend` + `run_app`: the screenshot loop. - -```sh -npx playwright install chromium -``` - -Then one `build_backend { mode: "full" }`, which transpiles the framework and -the corpus to Node. **Budget tens of minutes for that first build** — every -later one is incremental (~1–2 min). It is the slowest thing here by far, and -it is what buys an agent the ability to look at what it built. - -> **If you set this up earlier:** the corpus repository was `ai-demokit`, then -> `abap2UI5-api`, and is `samples-controls` today. Nothing needs changing — an -> existing checkout is still found under any of the three directory names, and -> `AI_DEMOKIT_HOME` is still read alongside `SAMPLES_CONTROLS_HOME`. - -### Register it with your client - -**Claude Code:** +Register it with Claude Code: ```sh claude mcp add abap2ui5 -- node /path/to/mcp-server/server.mjs ``` -**Cursor** (`.cursor/mcp.json`), **VS Code** (`.vscode/mcp.json`), **Claude -Desktop** (`claude_desktop_config.json`) and anything else that reads the -standard stdio shape: - -```json -{ - "mcpServers": { - "abap2ui5": { - "command": "node", - "args": ["/path/to/mcp-server/server.mjs"], - "env": { - "AI_VIEW_CHECK_HOME": "/path/to/linter", - "A2UI5_HOME": "/path/to/abap2UI5", - "SAMPLES_CONTROLS_HOME": "/path/to/samples-controls" - } - } - } -} -``` - -The three `env` entries are only needed if the checkouts are not siblings of -`mcp-server`; drop the ones you stopped short of. VS Code wants the same object -under a top-level `"servers"` key rather than `"mcpServers"`. +Cursor, VS Code and Claude Desktop take the standard stdio shape — the +[documentation](https://abap2ui5.github.io/docs/advanced/mcp_server.html#registering-it-with-your-client) +has the JSON, and the two further levels (the sample catalogues and deploying, +then the headless build-and-boot loop). A tool whose prerequisites are missing +answers with a message naming what it needs; the server starts either way. The [abap2UI5 VS Code extension](https://github.com/abap2UI5/vscode-extension) registers this server for you, and adds a second one of its own for the tools @@ -133,66 +61,58 @@ that need a real SAP system. | Tool | What it does | |---|---| -| `capabilities` | Query the verified capability map (samples-controls CAPABILITIES.md, parsed live — no drift). Ask before assuming a UI5 feature is impossible: `{ query: "tree binding" }`, `{ status: "not-expressible" }` | -| `app_guide` | **How to build an app**, live from the framework checkout (abap2UI5 `docs/agents/building-apps.md`): app class template, lifecycle, the view-builder chain, binding, events, popups, navigation, portability. Whole guide by default; `{ section: "5" }` or `{ query: "popup" }` narrows it | -| `scaffold_app` | **The files a new project starts from**, live from abap2UI5/app-template: both gate configs with the framework pinned, the CI workflow, the abapGit metadata, an `AGENTS.md` briefing and a working app class with its sidecar. `{ class: "zcl_my_app" }` renames it throughout — the ABAP, the sidecar's `CLSNAME` and the file names, which is the part that decides whether the object activates. Returns files to write; writes nothing itself | -| `generation_rules` | The rulebook for **porting a UI5 demo-kit sample** into the samples-controls corpus. A different job from `app_guide` — it assumes an input sample and the corpus' naming | -| `pitfalls` | The catalogues of defects **a green CI does not catch**, parsed live from the abap2UI5 checkout: `{ area: "abap" }` (abapGit round trip and import, activation, extended check, downport/transpiler, runtime) and `{ area: "view" }` (names the 1.71 floor does not have, layout that only works on a newer release, views that fail to *load*). Every entry is a defect that actually shipped, with its evidence. `validate_view` decides what a rule can decide — this is the rest | -| `scope_of` | In/out-of-scope verdict for UI5 controls (since <= 1.71, not deprecated) | -| `validate_view` | **Seconds, not minutes**: static property gate + headless render via abap2UI5-linter, from ABAP source or raw XML — run this after writing, before deploying. Findings come with a severity, a message and the line/column in the source you passed in, plus what each rule that fired MEANS (`explain: true` for the full paragraph) — no web search to interpret a finding. Judged by your project's own `abap2ui5lint.jsonc`: pass `{ project_dir: "/path/to/your/repo" }`, or let it take the directory the server runs in | -| `deploy_app` | Write `.clas.abap` + abapGit sidecar into the gitignored sandbox `src/zz_dev/` (in the samples-controls checkout), then abaplint it. Any customer-namespace class name — `zcl_my_app` as much as `z2ui5_cl_my_app` | -| `build_backend` | Rebuild the transpiled Node backend. `mode: auto` is **incremental** after the first full build (~1-2 min per iteration); `mode: full` runs the complete e2e-build | -| `screenshot_view` | **See the view in seconds**, from source, with no build and no backend: reconstructed, rendered against the local OpenUI5 runtime and returned as an image. Several viewports in one session (`{ sizes: ["390x844", "1280x900"] }`), any theme, and `model` for preview data. What it cannot show is anything that only exists at runtime — that is `run_app` | -| `run_app` | Boot any app class headless (`?app_start=`), return boot status, real page errors (benign UI5 noise filtered) and a full-page **screenshot as an image**. The RUNNING app, so it needs a `build_backend` first | +| `capabilities` | Whether abap2UI5 can express a UI5 feature at all, from the verified capability map | +| `app_guide` | How to build an app, live from the framework checkout | +| `scaffold_app` | The files a new project starts from, live from app-template; `{ class: … }` renames throughout, sidecar `CLSNAME` included | +| `examples` | Search the three sample catalogues — answers with a class to read, never a snippet to trust | +| `generation_rules` | The rulebook for porting a UI5 demo-kit sample into samples-controls | +| `pitfalls` | The defects a green run does not catch: `{ area: "abap" }` and `{ area: "view" }` | +| `scope_of` | In/out-of-scope verdict for a UI5 control | +| `validate_view` | The linter's gates in seconds, judged by your project's own `abap2ui5lint.jsonc` | +| `screenshot_view` | See the view in seconds — no build, no backend | +| `deploy_app` | Write the class + abapGit sidecar into the gitignored sandbox, then abaplint it | +| `build_backend` | Rebuild the transpiled Node backend; incremental after the first full build | +| `run_app` | Boot an app headless: status, real page errors, and a **screenshot** | | `backend` | `status` / `start` / `stop` / `restart` of the local express backend | -| `remove_app` | Delete a dev app from the sandbox (or list the deployed ones) | - -`run_app` works for new dev apps and equally for the existing samples-controls -ports and `z2ui5_cl_smpc_app_overview` — useful as a reference: "run the closest -existing port, look at it, then build mine". - -## The intended agent loop - -1. `capabilities { query: ... }` — check the feature is expressible (and how) - before writing a line of ABAP. -2. `app_guide` — once per session, before writing any ABAP. (`generation_rules` - instead, if the job is porting a named demo-kit sample.) -3. `scaffold_app` — when the user wants a project of their own, not a class to - paste into one that exists. -4. Write the class, then `validate_view` **and** `screenshot_view` — the - findings and the picture, both in seconds and neither needing a build. Most - iterations should end here. -5. `deploy_app` — abaplint against the full framework context. -6. `build_backend` — incremental after the first full build. -7. `run_app` — read the errors, **look at the screenshot**. Edit, validate, - deploy, build, run again. -8. `pitfalls` before you call it done — the defects no gate here can see: what - the class does on a *real* system (abapGit import, activation, the extended - check) and what the view does on the *oldest* one. A green loop is not the - same as a shipped app. +| `remove_app` | Delete a dev app from the sandbox, or list the deployed ones | + +`screenshot_view` and `run_app` answer the same question at three orders of +magnitude apart: the first photographs the reconstructed **view** with no +backend, the second the **running app** after a build. Most iterations should +end at the first. ## Notes -- **Dev sandbox:** deployed apps land in the samples-controls checkout's gitignored - `src/zz_dev/` — nothing an agent deploys can leak into a commit. Promote a - finished app by moving it into a real package deliberately. +- **Dev sandbox:** deployed apps land in the samples-controls checkout's + gitignored `src/zz_dev/` — nothing an agent deploys can leak into a commit. - **Port:** the backend listens on 3000 (`A2UI5_MCP_PORT` overrides). - **Timeouts:** every spawned child is killed (whole process tree) when it exceeds its limit — lint/scope 5 min, build 30 min by default; `A2UI5_MCP_LINT_TIMEOUT_MS`, `A2UI5_MCP_SCOPE_TIMEOUT_MS` and `A2UI5_MCP_BUILD_TIMEOUT_MS` override (values in ms). -- **UI5 sources:** modules are served from the samples-controls checkout's - `@openui5` packages, so booting needs no network. The built theme CSS is - not in those packages — with network access it loads from the CDN (styled - screenshots); without, apps render unstyled but structurally complete. - `A2UI5_MCP_OFFLINE=1` forces the hermetic behaviour. -- **Chromium:** uses the Playwright-managed browser; if absent, falls back to - a system chromium (`A2UI5_MCP_CHROMIUM` overrides the executable path). -- **Real system deployment** stays what it is today: abapGit. This server is - the inner dev loop; the real-system half already exists in the +- **UI5 sources** are served from the samples-controls checkout's `@openui5` + packages, so booting needs no network. The built theme CSS is not in those + packages — with network access it loads from the CDN (styled screenshots); + without, apps render unstyled but structurally complete. `A2UI5_MCP_OFFLINE=1` + forces the hermetic behaviour. +- **Chromium:** uses the Playwright-managed browser; if absent, falls back to a + system chromium (`A2UI5_MCP_CHROMIUM` overrides the executable path). +- **If you set this up earlier:** the corpus repository was `ai-demokit`, then + `abap2UI5-api`, and is `samples-controls` today. Nothing needs changing — an + existing checkout is still found under any of the three directory names, and + `AI_DEMOKIT_HOME` is still read alongside `SAMPLES_CONTROLS_HOME`. +- **Real-system deployment** stays what it is today: abapGit. This server is + the inner dev loop; the real-system half lives in the [VS Code extension](https://github.com/abap2UI5/vscode-extension), whose own - MCP server exposes it as `run_app_on_system` (launch URL + auth proxy). Both - servers are registered in the same editor window, which is why that tool is - not called `run_app`: this one builds and boots the transpiled sandbox, that - one runs a class on a system, and an agent has to be able to tell them - apart. + MCP server exposes it as `run_app_on_system`. Both servers are registered in + the same editor window, which is why that tool is not called `run_app`. + +## Working on this repository + +```sh +npm ci +npm test +``` + +`AGENTS.md` carries the conventions, `CONTRIBUTING.md` and `RELEASING.md` the +rest of the workflow.