diff --git a/.changeset/fiori-mcp-server-adp-tools.md b/.changeset/fiori-mcp-server-adp-tools.md
new file mode 100644
index 00000000000..d6a9f10936a
--- /dev/null
+++ b/.changeset/fiori-mcp-server-adp-tools.md
@@ -0,0 +1,5 @@
+---
+"@sap-ux/fiori-mcp-server": minor
+---
+
+FEAT: add ADP top-level tools (generate_adaptation_project, open_adaptation_editor, adp_controller_extension)
diff --git a/packages/fiori-mcp-server/jest.config.mjs b/packages/fiori-mcp-server/jest.config.mjs
index d7d3ac253bf..34c9309b088 100644
--- a/packages/fiori-mcp-server/jest.config.mjs
+++ b/packages/fiori-mcp-server/jest.config.mjs
@@ -5,7 +5,7 @@ export default {
     setupFilesAfterEnv: ['<rootDir>/test/jest.setup.ts'],
     modulePathIgnorePatterns: [...baseConfig.modulePathIgnorePatterns, '<rootDir>/test/data/'],
     transformIgnorePatterns: [
-        'node_modules/(?!(@huggingface|@sap-ux|@sap-ux-private|@sap/ux-specification|@sap/ux-cds-compiler-facade)/)'
+        'node_modules/(?!(@huggingface|@sap-ux|@sap-ux-private|@sap/ux-specification|@sap/ux-cds-compiler-facade|@sap-devx)/)'
     ],
     // Routes @sap/ux-cds-compiler-facade to .mjs ESM mock
     resolver: '<rootDir>/jest.resolver.cjs',
@@ -24,6 +24,7 @@ export default {
         // Stub fe-fpm-writer to prevent the CJS require chain: ux-specification → fe-fpm-writer →
         // fiori-annotation-api → @sap/ux-cds-compiler-facade which conflicts with the ESM mock
         '^@sap-ux/fe-fpm-writer$': '<rootDir>/test/__mocks__/@sap-ux/fe-fpm-writer.cjs',
+        '^@sap-ux/adp-tooling$': '<rootDir>/test/__mocks__/@sap-ux/adp-tooling.cjs',
         '^@sap/ux-specification$': '<rootDir>/test/__mocks__/@sap/ux-specification.mjs',
         ...baseConfig.moduleNameMapper,
         '^@huggingface/transformers$': '<rootDir>/test/__mocks__/@huggingface/transformers.cjs'
diff --git a/packages/fiori-mcp-server/package.json b/packages/fiori-mcp-server/package.json
index f6b11ac385a..349b56c412b 100644
--- a/packages/fiori-mcp-server/package.json
+++ b/packages/fiori-mcp-server/package.json
@@ -22,8 +22,9 @@
     "license": "Apache-2.0",
     "main": "dist/index.js",
     "scripts": {
+        "build-esbuild-base": "esbuild --bundle --platform=node --target=node20 --outdir=dist --external:vscode --external:@lancedb/lancedb --external:@xenova/transformers --external:@sap-ux/fiori-docs-embeddings  --external:@sap-ux/store --external:playwright-core --main-fields=module,main src/index.ts",
         "build-bundle": "node scripts/bundle.mjs",
-        "build-dev": "NODE_ENV=development node scripts/bundle.mjs",
+        "build-dev": "pnpm run build-esbuild-base --sourcemap=inline",
         "build-compile": "tsc --noEmit",
         "build": "npm-run-all build-compile build-bundle",
         "watch": "tsc --watch",
@@ -47,7 +48,8 @@
         "dist",
         "!dist/**/*.map",
         "assets/icon.svg",
-        "assets/icon.png"
+        "assets/icon.png",
+        "skills"
     ],
     "bin": {
         "fiori-mcp": "./dist/index.js"
@@ -82,6 +84,7 @@
         "@types/json-schema": "7.0.15",
         "@types/mem-fs": "1.1.2",
         "@types/mem-fs-editor": "7.0.1",
+        "@sap-ux/adp-tooling": "workspace:*",
         "cross-env": "10.1.0",
         "esbuild": "0.27.4",
         "i18next": "25.10.10",
@@ -89,6 +92,7 @@
         "mem-fs-editor": "9.4.0",
         "npm-run-all2": "8.0.4",
         "os-name": "4.0.1",
+        "playwright-core": "1.58.2",
         "promptfoo": "0.121.15",
         "xml-formatter": "3.7.0",
         "ts-node": "10.9.2",
diff --git a/packages/fiori-mcp-server/skills/sap-fiori-adp-controller-extension-flow/SKILL.md b/packages/fiori-mcp-server/skills/sap-fiori-adp-controller-extension-flow/SKILL.md
new file mode 100644
index 00000000000..25c2d72b5bf
--- /dev/null
+++ b/packages/fiori-mcp-server/skills/sap-fiori-adp-controller-extension-flow/SKILL.md
@@ -0,0 +1,389 @@
+---
+name: sap-fiori-adp-controller-extension-flow
+author: sap-fiori-tools
+version: 0.0.1
+description: Use when making RTA changes to a SAP Fiori adaptation project via the adaptation editor — adding/removing UI elements, changing properties, renaming labels, hiding controls, or extending controllers and fragments.
+---
+
+# ADP Controller Extension Flow
+
+Drive Runtime Authoring (RTA) in the SAP Fiori adaptation editor through the **`run_rta_workflow_step`** MCP tool exposed by `fiori-mcp-server`. The tool handles browser automation server-side; this skill orchestrates the step sequence and the AI decisions between steps.
+
+> **Tool boundary.** `run_rta_workflow_step` is a **skill-internal** dispatcher. Don't call it ad-hoc — the value of this skill is in the AI decision points between steps (control selection, action selection, payload preparation). Calling out of order will fail with a descriptive error.
+
+## Prerequisites
+
+- `fiori-mcp` server running (provides `run_rta_workflow_step`)
+- Adaptation editor URL (from the `sap-fiori-adp-project-setup` skill or user-provided)
+- A Chromium-based browser the server can launch. Resolution order:
+  1. `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` env var (absolute path to a Chromium binary)
+  2. `PLAYWRIGHT_BROWSER_CHANNEL` env var (`chrome`, `msedge`, `chrome-beta`, etc.)
+  3. System Google Chrome (default channel)
+  4. Playwright-managed Chromium (auto-fallback if 1–3 fail)
+
+### Installing fiori-mcp
+
+This skill requires the `@sap-ux/fiori-mcp-server` MCP server. It is part of the [SAP UX Tools](https://github.com/SAP/open-ux-tools) open-source project.
+
+**Install via npm:**
+
+```bash
+npm install -g @sap-ux/fiori-mcp-server
+```
+
+**Configure in your MCP client** (e.g. Claude Desktop `claude_desktop_config.json`, or VS Code `settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "fiori-mcp": {
+      "command": "npx",
+      "args": ["-y", "@sap-ux/fiori-mcp-server"]
+    }
+  }
+}
+```
+
+After adding the server, restart your MCP client. The `run_rta_workflow_step` tool should appear in the available tools list.
+
+### Chromium fallback (no system Chrome)
+
+If no system Chrome is found and no env override is set, the server falls back to Playwright's bundled Chromium. The bundle is **not** included with `playwright-core`, so it has to be installed once on the host machine:
+
+```bash
+npx playwright install chromium
+```
+
+When `start` fails with `Executable doesn't exist at .../chromium-XXXX/...`, run that command and retry. Mention to the user that the first install downloads ~120 MB and can take a minute. Subsequent runs reuse the cached browser.
+
+Detection sequence the skill should follow on a `start` failure that mentions a missing browser:
+1. Inspect the error message — if it references a missing Chromium binary, prompt the user to run `npx playwright install chromium` (or run it on their behalf if they consent).
+2. After install completes, retry `start` with the same payload.
+3. If detection still fails, ask the user to set `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` to a known Chrome/Chromium binary.
+
+## Tool Contract
+
+A single tool, dispatched by the `step` argument. Pass `payload` for steps that need it. Subsequent steps reuse the `sessionId` returned by `start`.
+
+| step | sessionId | payload | returns |
+|------|-----------|---------|---------|
+| `start` | — | `{ site: string, frameId?: string }` | `{ sessionId, rtaStarted: true }` |
+| `get_overlays` | required | — | `{ overlays: Overlay[] }` |
+| `get_actions` | required | `{ controlId }` | `{ actions: Action[] }` |
+| `get_context` | required | `{ controlId, actionId }` | `{ context }` |
+| `call_action` | required | `{ controlId, actionId, actionPayload }` | `{ success: boolean }` |
+| `save` | required | — | `{ saved: boolean }` |
+| `stop` | required | — | `{ stopped: true }` |
+
+`Overlay` = `{ overlayId, controlId, label, controlType }`.
+`Action` = `{ id, label?, payload?: [{ name, type, required?, description? }] }`.
+For the standard adaptation editor preview iframe, pass `frameId: "preview"` in the `start` payload.
+
+## Actions Reference
+
+These are the canonical RTA actions returned by `get_actions`. **Always pick by `id` from this table — never invent or guess action IDs.** If `get_actions` returns an `id` not listed here, treat it as unknown and ask the user before proceeding.
+
+### `CTX_ADDXML` — Add: Fragment
+
+Insert an XML fragment as a child of the selected control. This is the action for "add a button / field / column / section" via a fragment file.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `fragmentPath` | string | yes | Path to the fragment XML, formatted `fragments/<Name>.fragment.xml`. |
+| `targetAggregation` | string | yes | Aggregation of the parent control where the fragment is inserted (e.g. `content`, `items`, `headerContent`). Read from `get_context`. |
+| `index` | int | yes | Position within the aggregation. Use `0` for first, the current child count for "append at end". |
+
+### `CTX_EXTEND_CONTROLLER` — Extend Controller
+
+Attach a controller extension JS file to a view. Use this when fragment event handlers reference methods that need a JS implementation, or whenever the user asks for behavior changes (handlers, lifecycle hooks, formatters).
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `codeRef` | string | yes | Path to the controller extension, formatted `coding/<Name>.js`. |
+| `viewId` | string | yes | Any control id inside the view, or the view id itself. The `controlId` of the current selection works. |
+| `instanceSpecific` | boolean | no | `true` extends only this view instance; `false`/omitted extends every view that uses this controller. |
+
+### Disambiguation by intent
+
+| User intent | Action |
+|---|---|
+| "add a button / field / column / section / dialog opener" | `CTX_ADDXML` (fragment carries the new control) |
+| "make this button do X" / "open a dialog when …" / "change behavior" | `CTX_EXTEND_CONTROLLER` (handler lives in the controller extension) |
+| "add a button that opens a dialog" | **Both**, in this order: `CTX_ADDXML` for the button, then `CTX_EXTEND_CONTROLLER` for the press handler. Run as two separate iterations of Steps 4–8. |
+
+If `get_actions` returns more actions than these for a control, surface them to the user rather than picking — this skill is only authoritative for `CTX_ADDXML` and `CTX_EXTEND_CONTROLLER`.
+
+## Confidence & HITL Gating
+
+Three steps in this workflow are AI judgment calls, not deterministic lookups: control selection (Step 3), action selection (Step 5), and payload preparation (Step 7). Wrong choices at these points either edit the wrong UI or silently corrupt the change. To make HITL reliable, **rate every such decision with a self-assessed confidence in `[0, 1]`** and gate behavior on per-decision thresholds.
+
+### Confidence rubric
+
+Anchor your self-rating to evidence, not vibes:
+
+| Confidence | When to assign it |
+|---|---|
+| **0.95–1.00** | Exact, unambiguous match. Single candidate. Wording in the user's instruction maps 1:1 to one option. |
+| **0.85–0.94** | Strong match. Top candidate is clearly best; runner-up is materially worse. All required fields derived from explicit context or instructions. |
+| **0.65–0.84** | Likely match. Top candidate is plausible but the runner-up is also reasonable, or one non-critical field had to be inferred. |
+| **0.40–0.64** | Weak match. Several plausible candidates, or a required field was inferred from weak signals. |
+| **< 0.40** | No real match. Don't pick — list options and ask. |
+
+### Three bands → three behaviors
+
+| Band | Range | Behavior |
+|---|---|---|
+| **High** | ≥ high threshold | Proceed silently. Record the choice + confidence in the final summary. |
+| **Medium** | ask threshold ≤ x < high threshold | Proceed but **announce** the choice on one line: `Using <choice> (confidence 0.78). Continuing — interrupt to change.` Do not stop. |
+| **Low** | < ask threshold | **Stop and ask.** Present the top 2–3 ranked candidates with their confidences. Never guess. |
+
+### Medium-band lock-in (critical)
+
+A Medium-band announcement is a **soft commitment, not a draft**. The next tool call must use the announced choice exactly. If downstream evidence later invalidates the choice — for example, `get_actions` doesn't return the action you expected, `get_context` returns a structure that doesn't match, or the action call errors — you MUST:
+
+1. **Stop.** Do not silently switch to a different control, action, or payload. The user already saw "Using X" and is reasonably expecting X.
+2. **Report the contradiction explicitly:** what you announced, what came back, and what that means.
+3. **Ask the user how to proceed.** Offer concrete alternatives where possible (e.g. "(a) try a different control, (b) use a different action on the same control, (c) stop").
+
+Silently revising a Medium-band choice is the single worst HITL failure mode this skill protects against. The user's "interrupt to change" affordance is real-time only; once you've moved past it, ask explicitly before changing course.
+
+### Expected-action absence is a hard stop
+
+When you derived an expected action id in Step 5 from the user's intent (e.g. "add a button" → `CTX_ADDXML`) and the chosen control doesn't expose that action, **this is an ask point, not a search heuristic**. Do not silently iterate to a different control hoping the action appears. Instead:
+
+1. **Stop.** Tell the user, in plain terms, that the control they're working with doesn't support the action needed for this intent. Name the control and the missing action explicitly.
+2. **Propose a similar control if one exists.** Look at the overlay list for candidates of the same or compatible `controlType` (e.g. another `OverflowToolbar`, another `Toolbar`, the parent container) and name **one specific alternative** with the reason it's similar. Do not list five — pick the closest one.
+3. **Wait for explicit confirmation.** Do not switch controls until the user replies. If they confirm, restart from Step 4 (`get_actions`) on the new control and verify the expected action is present *before* announcing.
+4. **If no similar control is obvious**, ask the user to point at one or to clarify what they meant — don't guess.
+
+This rule has special weight when the **user explicitly named the control** (e.g. "add a button to the TableToolbar"). In that case the model must not silently substitute a different control under any circumstance — the user said which one, and a missing action means the request itself is impossible as stated, which the user must be told.
+
+This rule applies even when the chosen control was selected in the High band. A High-band control plus an unexpected action set is a higher-priority signal than the original control-selection confidence.
+
+Phrasing template:
+
+> The `<chosenControl>` (`<controlType>`) doesn't expose `<expectedAction>` — only `<actual ids>`.
+>
+> The closest similar control on this page is `<proposedControl>` (`<controlType>`), because `<reason>`. Should I switch to `<proposedControl>` and continue, or did you mean a different control?
+
+### Per-decision thresholds
+
+| Decision | High ≥ | Ask < | Reasoning |
+|---|---|---|---|
+| Step 3 — Control selection | 0.80 | 0.60 | Cheap to undo if wrong (the action will fail or look obviously wrong). |
+| Step 5 — Action selection | 0.85 | 0.65 | Few options, usually obvious; bump slightly higher because the wrong action causes a wrong *kind* of change. |
+| Step 7 — Payload preparation | 0.90 | 0.70 | **Highest risk.** Action can succeed yet produce a broken/misplaced change. Bias toward asking. |
+
+### Ambiguity overrides confidence (must ask)
+
+The Medium band is for "I know which one and the runner-up is materially worse, but not by a wide margin." It is **not** for "two candidates look interchangeable." When two or more candidates are roughly equally plausible — same `controlType`, similar labels, both reasonable matches for the user's words — that is a **disambiguation problem, not a confidence problem**. Treat it as a hard ask regardless of the score:
+
+- Two or more candidates within **0.10** confidence of each other → **stop and ask**, even if the top score is in the High band on paper.
+- "I'll pick the more conventional one" or "this is where row actions live" reasoning is not a tiebreaker — it's a guess. List the candidates and ask.
+
+Concrete example: a ListReport page has both a `TableToolbar` and a `FooterToolbar`. The user said "the toolbar." Both are `sap.m.OverflowToolbar`. Don't pick — ask.
+
+### Required-field rule (Step 7)
+
+A required field whose value cannot be derived from (a) the action's payload schema, (b) the element context, or (c) explicit user instructions **caps the whole-payload confidence at 0.55** regardless of how strong the other fields are. That puts payload prep into the "ask" band by default whenever guessing is required.
+
+### Multi-change runs
+
+When executing many changes in one session, the cumulative chance of a wrong silent decision grows. **Lower the high threshold of every decision by 0.05 once the run has > 3 changes** so that the 4th and later changes are announced more aggressively. Always re-run `get_overlays` between iterations — confidence drops if the snapshot is stale.
+
+### Reporting
+
+The final summary (Step 12) must include, per change: chosen control, action, and the confidence the model assigned to each AI decision. This makes silent high-confidence decisions auditable after the fact.
+
+## Workflow
+
+### Step 1 — Start RTA
+
+Call `run_rta_workflow_step` with `step: "start"`, payload `{ site, frameId: "preview" }`. Verify `rtaStarted: true`. Store the returned `sessionId`. On `false`, wait 3 s and retry once.
+
+### Step 2 — Get overlays
+
+Call `step: "get_overlays"`. Returns the editable controls on the page.
+
+### Step 3 — Select target control (AI decision)
+
+Match the user's instruction against the overlays:
+- "the title" → controls with `Title` or `Header` in `controlType`
+- "the table" → `sap.ui.table.Table` or `sap.m.Table`
+- "button X" → `sap.m.Button` with matching label
+- "toolbar" → `sap.m.Toolbar` or `sap.m.OverflowToolbar`
+
+**Confidence gating** (see *Confidence & HITL Gating*; thresholds: high ≥ 0.80, ask < 0.60):
+- Score every plausible overlay against the instruction; rank them; assign confidence to the top candidate using the rubric.
+- **High** → use the chosen `controlId` silently.
+- **Medium** → announce: `Using <label> (<controlType>, confidence 0.7x). Continuing — interrupt to change.`
+- **Low** or no candidates ≥ 0.40 → list the top 3 with confidences and ask.
+
+Store the chosen `controlId` and its confidence for the final summary.
+
+### Step 4 — Get actions for that control
+
+Call `step: "get_actions"`, payload `{ controlId }`. Returns the action list.
+
+### Step 5 — Select action (AI decision)
+
+Pick an action by `id` from the **Actions Reference** above. **Never invent an action id**; if `get_actions` returns an id that isn't in the reference, ask the user.
+
+Map user intent (see *Disambiguation by intent* in the reference):
+- "add a button/field/column/section" → `CTX_ADDXML`
+- "make X happen on click", "open a dialog", "change behavior" → `CTX_EXTEND_CONTROLLER`
+- "add a button that does X" → both (run as two iterations).
+
+**Confidence gating** (thresholds: high ≥ 0.85, ask < 0.65):
+- **Schema-inspection prerequisite for High band:** Before assigning ≥ 0.85, you must have read the candidate's `payload` schema (from `get_actions`) and confirmed it matches the kind of operation the user described. If you have not inspected the schema, cap confidence at **0.65** (medium → announce, do not run silently).
+- **Same-verb penalty:** If two or more candidates share a verb token in their id or label (e.g. multiple `ADD_*` actions returned), subtract **0.20** from the top candidate's confidence unless the schemas clearly distinguish them.
+- **High-band requirement:** When proceeding silently, record an `Alternatives considered:` line stating which other actions were rejected and the schema/semantic reason. If you can't articulate the discriminator, the choice isn't High.
+- If the verb doesn't map cleanly (e.g. "tweak the toolbar"), confidence is low — list the available actions with their labels and ask.
+
+Store `actionId`, the action's `payload` schema, and the confidence value.
+
+### Step 6 — Get element context
+
+Call `step: "get_context"`, payload `{ controlId, actionId }`. Returns `viewName`, `controlType`, aggregation info, etc. Used to fill structural payload fields.
+
+### Step 7 — Prepare action payload (AI decision)
+
+Build `actionPayload` from the action's `payload` schema (Step 5), the element context (Step 6), and the user's instructions. **Use the exact field names from the Actions Reference** — `fragmentPath` (not `fragmentName`), `codeRef`, `viewId`, etc.
+
+**For `CTX_ADDXML`:**
+- `fragmentPath`: `fragments/<Name>.fragment.xml` — pick `<Name>` from the user's intent (e.g. `OrderDetailsButton`). The fragment file itself is created in Step 11.
+- `targetAggregation`: from `get_context` (e.g. `content` for a Toolbar).
+- `index`: `0` for "at the beginning"; the current child count for "at the end"; ask if the user said "after the X" and the position isn't determinable from context.
+
+**For `CTX_EXTEND_CONTROLLER`:**
+- `codeRef`: `coding/<Name>.js` — `<Name>` typically matches the fragment's controller name (e.g. `OrderDetailsExt`). The JS file itself is created in Step 11.
+- `viewId`: the `controlId` of the current selection works; otherwise the view id from `get_context`.
+- `instanceSpecific`: omit unless the user explicitly asked to scope to one instance.
+
+General rules:
+- Fill structural fields from `get_context`; fill value fields from instructions.
+- Validate types match the schema (string vs int vs boolean — `index` is int, not string).
+
+**Confidence gating** (thresholds: high ≥ 0.90, ask < 0.70 — strictest of the three because a successful `call_action` with a wrong payload is the worst silent failure):
+- Per-field confidence: use the rubric. Whole-payload confidence is the **minimum** of the per-field values.
+- **Required-field rule:** a required field whose value cannot be derived from schema, context, or explicit instruction caps whole-payload confidence at **0.55** — push to the ask band even if every other field is perfect.
+- **High** → submit the payload silently.
+- **Medium** → announce the payload: `Action <actionId> with payload <JSON> (confidence 0.7x). Continuing — interrupt to change.` Continue.
+- **Low** → present the payload as a draft and ask for confirmation or corrections before calling.
+
+Store the payload + confidence for the final summary.
+
+### Step 8 — Execute action
+
+Call `step: "call_action"`, payload `{ controlId, actionId, actionPayload }`. On `success: true`, continue. On error, report and offer to retry with adjusted parameters.
+
+### Step 9 — Loop for multiple changes
+
+If the user requested multiple changes, repeat Steps 2–8 once per change (the UI may have changed, so re-run `get_overlays` between changes). If a single request implies multiple operations (e.g. "add a button that calls a function" = fragment + controller extension), execute each as a separate iteration.
+
+Create all changes before saving.
+
+### Step 10 — Save
+
+Call `step: "save"`. Returns `{ saved: true }` on success.
+
+### Step 11 — Generate fragment and controller extension content
+
+After saving, use `mcp__fiori-mcp__adp_controller_extension` to fill in the content for any fragments and controller extensions that were created.
+
+**Phase 1 — knowledge base.** Call with:
+- `appPath`: adaptation project path
+- `prompt`: describe the functionality (from user instructions)
+- (do **not** pass `aiResponse`)
+
+This returns project context, layer info, namespace rules, and existing files.
+
+**Phase 2 — write content.** Generate controller extension and fragment XML using the Phase 1 knowledge base, then call again with:
+- `appPath`: same path
+- `prompt`: same prompt
+- `aiResponse`: your generated code with `**Path:**` markers
+- `controllerName`: the controller extension name
+
+Format:
+
+```
+**Path:** webapp/changes/coding/MyExtension.js
+```javascript
+// controller extension code
+```
+
+**Path:** webapp/changes/fragments/MyFragment.fragment.xml
+```xml
+<!-- fragment code -->
+```
+```
+
+Include XML comments inside fragments for context hints:
+```xml
+<!-- viewName: <from context> -->
+<!-- controlType: <from context> -->
+<!-- targetAggregation: <from context> -->
+```
+
+### Step 12 — Cleanup
+
+Call `step: "stop"`. The server closes the session; if it was the last one, the browser shuts down too.
+
+Then kill the editor server:
+
+```
+kill <processId>
+# or by port:
+lsof -ti:<port> | xargs kill
+```
+
+Report to the user: summary of all changes made, files created, any issues encountered, **plus the confidence the model assigned to each AI decision (control selection, action selection, payload prep) for every change** — this makes silent high-confidence decisions auditable after the fact.
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| Page not loading | Wait 30 s. If still nothing, verify URL and editor server is running. |
+| `start` returns `rtaStarted: false` | Retry once after 3 s. If still false, the app may not support RTA. |
+| `get_overlays` returns empty | Wait 5 s, retry. If still empty, ask the user to confirm the editor is on the right view. |
+| Expected action id is not in the `get_actions` result | **Stop.** This is the hard-stop case from *Confidence & HITL Gating*. Do not silently switch controls or actions. Tell the user what you expected, what came back, and ask how to proceed. |
+| Action execution fails | Report error, offer retry with different params. |
+| Save fails | Report error. Inform user changes may be lost. |
+| `Unknown sessionId` error | The server was restarted between steps. Start a fresh session from Step 1. |
+| `Frontend action ... not registered` | The editor hasn't finished loading, or wrong frame. Verify `frameId: "preview"` and retry. |
+| `Executable doesn't exist at .../chromium-...` or `browserType.launch: ...` referencing a missing browser | No system Chrome and no Playwright Chromium installed. Run `npx playwright install chromium` (one-time, ~120 MB) and retry `start`. |
+| `Chromium executable not found` (custom message from the server) | Same as above — Playwright Chromium isn't installed and no system Chrome was found. Install via `npx playwright install chromium`. |
+
+## Multi-Change Strategy
+
+When the user requests multiple changes:
+1. Parse all intended changes upfront.
+2. Execute Steps 2–8 once per change, all under the same `sessionId`.
+3. Save once at the end (Step 10).
+4. If one change fails, save the successful ones and report which failed.
+5. Generate content for all fragments / extensions together in Step 11.
+6. Stop the session (Step 12) only after everything is done.
+
+## Example Session
+
+User: "Add a custom button to the object page toolbar that shows a dialog with order details."
+
+This intent maps to **two actions** (see *Disambiguation by intent*): `CTX_ADDXML` for the button, then `CTX_EXTEND_CONTROLLER` for the press handler.
+
+1. `start` with `{ site, frameId: "preview" }` → `sessionId` + `rtaStarted: true`
+2. `get_overlays` → find the toolbar control (confidence 0.88 → High → silent)
+3. `get_actions` for `controlId=<toolbar>` → confirms `CTX_ADDXML` and `CTX_EXTEND_CONTROLLER` are available
+4. **Iteration 1 — add the button:**
+   - `get_context` for `(<toolbar>, CTX_ADDXML)` → returns `viewName`, current `content` aggregation, child count
+   - Action confidence 0.92 (High; alternatives considered: only fragment-add was returned)
+   - Payload `{ fragmentPath: "fragments/OrderDetailsButton.fragment.xml", targetAggregation: "content", index: <count> }` confidence 0.91 → High
+   - `call_action` → `success: true`
+5. **Iteration 2 — add the controller extension:**
+   - `get_actions` for the same control still includes `CTX_EXTEND_CONTROLLER`
+   - `get_context` for `(<toolbar>, CTX_EXTEND_CONTROLLER)` → returns `viewId`
+   - Payload `{ codeRef: "coding/OrderDetailsExt.js", viewId: "<viewId>" }` confidence 0.93 → High
+   - `call_action` → `success: true`
+6. `save` → `saved: true`
+7. `adp_controller_extension` Phase 1 → knowledge base
+8. Generate fragment XML (`OrderDetailsButton.fragment.xml`) + controller extension (`OrderDetailsExt.js` with the press handler that opens the dialog), Phase 2 writes files
+9. `stop`, then kill the editor server. Report done — including the confidence the model assigned to each AI decision.
diff --git a/packages/fiori-mcp-server/skills/sap-fiori-adp-project-setup/SKILL.md b/packages/fiori-mcp-server/skills/sap-fiori-adp-project-setup/SKILL.md
new file mode 100644
index 00000000000..f0e92f83bf0
--- /dev/null
+++ b/packages/fiori-mcp-server/skills/sap-fiori-adp-project-setup/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: sap-fiori-adp-project-setup
+author: sap-fiori-tools
+version: 0.0.1
+description: Use when creating a new SAP Fiori adaptation project, setting up an adaptation editor, or adapting an existing Fiori app on an SAP system
+---
+
+# ADP Project Setup
+
+End-to-end workflow for creating a SAP Fiori adaptation project and launching the adaptation editor.
+
+## Prerequisites
+
+- fiori-mcp server connected (provides `mcp__fiori-mcp__*` tools)
+- User knows which SAP system and application to adapt (or will be guided)
+
+### Installing fiori-mcp
+
+This skill requires the `@sap-ux/fiori-mcp-server` MCP server. It is part of the [SAP UX Tools](https://github.com/SAP/open-ux-tools) open-source project.
+
+**Install via npm:**
+
+```bash
+npm install -g @sap-ux/fiori-mcp-server
+```
+
+**Configure in your MCP client** (e.g. Claude Desktop `claude_desktop_config.json`, or VS Code `settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "fiori-mcp": {
+      "command": "npx",
+      "args": ["-y", "@sap-ux/fiori-mcp-server"]
+    }
+  }
+}
+```
+
+After adding the server, restart your MCP client. The `mcp__fiori-mcp__*` tools should appear in the available tools list.
+
+## Workflow
+
+### Step 1: Discover Available Systems
+
+Call `mcp__fiori-mcp__list_sap_systems` to retrieve the list of configured SAP systems.
+
+Present the systems to the user. If no systems are found, inform the user they need to configure a system first (via SAP Fiori tools system store or BAS destinations).
+
+### Step 2: Gather Parameters
+
+Ask the user for:
+1. **System** — which SAP system to use (from the list)
+2. **Application** — the application ID to adapt (e.g., `sap.ui.demoapps.rta.fe`)
+3. **Target folder** — where to create the project (default: current working directory)
+4. **Project name** — optional, defaults to `app.variant`
+
+If the user does not know the application ID, suggest they check the Fiori Apps Library or their system's app index.
+
+### Step 3: Generate the Adaptation Project
+
+Call `mcp__fiori-mcp__generate_adaptation_project` with:
+- `system`: selected system name
+- `application`: the application ID
+- `appPath`: current working directory or user-specified path
+- `targetFolder`: where to generate (absolute path)
+- `projectName`: user's choice or default
+
+Optional parameters if user provides them: `namespace`, `applicationTitle`, `client`, `username`, `password`.
+
+Wait for completion. Report success or failure.
+
+### Step 4: Patch ui5.yaml for Local Proxy (DEMO ONLY)
+
+**Only if the user explicitly requests demo/local mode or mentions localhost proxy.**
+
+Read the generated `ui5.yaml` in the project root. In the `fiori-tools-proxy` middleware config, change:
+- `url` → `http://localhost:8080`
+- `version` → leave empty (remove the value)
+- Keep `path` as-is
+
+### Step 5: Launch the Adaptation Editor
+
+Call `mcp__fiori-mcp__open_adaptation_editor` with:
+- `appPath`: absolute path to the generated adaptation project root (where `package.json` resides)
+
+The tool returns:
+- `editorUrl` — full URL to open the adaptation editor
+- `processId` — background server PID
+- `port` — server port
+
+### Step 6: Report Success
+
+Present to the user:
+- Project location (absolute path)
+- Editor URL
+- Server PID and port (for cleanup)
+- Next step: "Use the `sap-fiori-adp-controller-extension-flow` skill to make RTA changes, or open the URL in your browser."
+
+## Error Handling
+
+- **No systems found:** User must configure systems first
+- **Generation fails:** Check credentials, application ID validity, system connectivity
+- **Editor launch fails:** Verify project path is correct and `package.json` exists
+- **ui5.yaml not found:** Skip patch, warn user
+
+## Cleanup
+
+The editor server runs in background. To stop it later:
+```bash
+kill <processId>
+# or by port:
+lsof -ti:<port> | xargs kill
+```
diff --git a/packages/fiori-mcp-server/src/constant.ts b/packages/fiori-mcp-server/src/constant.ts
index 46baba9d391..8fe90f1db95 100644
--- a/packages/fiori-mcp-server/src/constant.ts
+++ b/packages/fiori-mcp-server/src/constant.ts
@@ -2,6 +2,9 @@ export const LATEST_UI5_VERSION = '1.136.7';
 export const ADD_PAGE = 'add-page';
 export const DELETE_PAGE = 'delete-page';
 export const CREATE_CONTROLLER_EXTENSION_FUNCTIONALITY_ID = 'create-controller-extension';
+export const GENERATE_ADAPTATION_PROJECT_ID = 'generate-adaptation-project';
+export const ADP_CONTROLLER_EXTENSION_FUNCTIONALITY_ID = 'adp-controller-extension';
+export const OPEN_ADAPTATION_EDITOR_ID = 'open-adaptation-editor';
 export const EXTENSION_FILE_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
 
 // Telemetry event names
diff --git a/packages/fiori-mcp-server/src/server.ts b/packages/fiori-mcp-server/src/server.ts
index cfaf77aa603..02fcff585f8 100644
--- a/packages/fiori-mcp-server/src/server.ts
+++ b/packages/fiori-mcp-server/src/server.ts
@@ -20,8 +20,13 @@ import {
     downloadODataServiceMetadata,
     generateFioriAppOData,
     generateFioriAppCap,
+    generateAdaptationProject,
+    openAdaptationEditor,
+    adpControllerExtension,
+    runRtaWorkflowStep,
     tools
 } from './tools/index.js';
+import { stopBrowser } from './tools/run-rta-workflow-step/browser/index.js';
 import { TelemetryHelper, unknownTool, type TelemetryData } from './telemetry/index.js';
 import { TELEMETRY_MCP_SERVER_INITIALIZED, TELEMETRY_MCP_LIST_TOOLS } from './constant.js';
 import type {
@@ -30,7 +35,11 @@ import type {
     DocSearchInput,
     ListFioriAppsInput,
     ListFunctionalitiesInput,
-    DownloadODataServiceMetadataInput
+    DownloadODataServiceMetadataInput,
+    GenerateAdaptationProjectInput,
+    OpenAdaptationEditorInput,
+    AdpControllerExtensionInput,
+    RunRtaWorkflowStepInput
 } from './types/index.js';
 import type { GeneratorConfigOData, GeneratorConfigCAP } from './tools/schemas/index.js';
 import { logger } from './utils/logger.js';
@@ -44,6 +53,10 @@ type ToolArgs =
     | DownloadODataServiceMetadataInput
     | GeneratorConfigOData
     | GeneratorConfigCAP
+    | GenerateAdaptationProjectInput
+    | OpenAdaptationEditorInput
+    | AdpControllerExtensionInput
+    | RunRtaWorkflowStepInput
     | Record<string, unknown>;
 
 const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
@@ -107,6 +120,7 @@ export class FioriFunctionalityServer {
     private setupErrorHandling(): void {
         this.server.onerror = (error): void => logger.error(`[MCP Error] ${error}`);
         process.on('SIGINT', async () => {
+            await stopBrowser();
             await this.server.close();
             process.exit(0);
         });
@@ -273,6 +287,18 @@ Never skip steps or guess functionalityIds. Never use a functionalityId as a too
                     case 'generate_fiori_app_cap':
                         result = await generateFioriAppCap(args as GeneratorConfigCAP);
                         break;
+                    case 'generate_adaptation_project':
+                        result = await generateAdaptationProject(args as GenerateAdaptationProjectInput);
+                        break;
+                    case 'open_adaptation_editor':
+                        result = await openAdaptationEditor(args as OpenAdaptationEditorInput);
+                        break;
+                    case 'adp_controller_extension':
+                        result = await adpControllerExtension(args as AdpControllerExtensionInput);
+                        break;
+                    case 'run_rta_workflow_step':
+                        result = await runRtaWorkflowStep(args as RunRtaWorkflowStepInput);
+                        break;
                     case 'list_functionality':
                         result = await listFunctionalities(args as ListFunctionalitiesInput);
                         break;
@@ -286,7 +312,7 @@ Never skip steps or guess functionalityIds. Never use a functionalityId as a too
                         // Do not pass telemetryProperties to unknownTool
                         await TelemetryHelper.sendTelemetry(unknownTool, {}, (args as any)?.appPath);
                         throw new Error(
-                            `Unknown tool: ${name}. Try one of: search_docs, list_fiori_apps, list_sap_systems, download_odata_service_metadata, generate_fiori_app_odata, generate_fiori_app_cap, list_functionality, get_functionality_details, execute_functionality.`
+                            `Unknown tool: ${name}. Try one of: search_docs, list_fiori_apps, list_sap_systems, download_odata_service_metadata, generate_fiori_app_odata, generate_fiori_app_cap, generate_adaptation_project, open_adaptation_editor, adp_controller_extension, run_rta_workflow_step, list_functionality, get_functionality_details, execute_functionality.`
                         );
                 }
                 await TelemetryHelper.sendTelemetry(name, telemetryProperties, (args as any)?.appPath);
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/index.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/index.ts
new file mode 100644
index 00000000000..b79d9157548
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/index.ts
@@ -0,0 +1,3 @@
+export { extractFilesFromResponse, isChangeFile } from './parser.js';
+export { processAiResponse } from './processor.js';
+export { PathTraversalError, resolveWithinAppPath, writeExtractedFile } from './writer.js';
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/parser.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/parser.ts
new file mode 100644
index 00000000000..5c9858c2092
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/parser.ts
@@ -0,0 +1,79 @@
+import type { ExtractedFile } from '../types.js';
+import { logger } from '../../../utils/logger.js';
+
+const PATH_MARKER = /\*\*Path:\*\*\s*(.+)/;
+const FENCE_OPEN = /^```(\w+)?/;
+const FENCE_CLOSE = /^```\s*$/;
+
+function processOutsideBlock(
+    line: string,
+    state: { inCodeBlock: boolean; currentPath: string; currentCode: string }
+): void {
+    const pathMatch = PATH_MARKER.exec(line);
+    if (pathMatch) {
+        state.currentPath = pathMatch[1].trim();
+        return;
+    }
+    if (FENCE_OPEN.test(line)) {
+        state.inCodeBlock = true;
+        state.currentCode = '';
+    }
+}
+
+function processInsideBlock(
+    line: string,
+    state: { inCodeBlock: boolean; currentPath: string; currentCode: string },
+    codeBlocks: ExtractedFile[]
+): void {
+    if (FENCE_CLOSE.test(line)) {
+        state.inCodeBlock = false;
+        if (state.currentPath && state.currentCode.trim()) {
+            codeBlocks.push({ path: state.currentPath, code: state.currentCode.trim() });
+        }
+        state.currentPath = '';
+        state.currentCode = '';
+        return;
+    }
+    state.currentCode += line + '\n';
+}
+
+/**
+ * Parses an AI response containing markdown code blocks preceded by
+ * `**Path:** <fullFilePath>` markers and returns the extracted files. Lines
+ * outside fenced blocks are ignored. A code block without a preceding path
+ * marker is dropped.
+ *
+ * @param content Raw AI response text.
+ * @returns Files declared in the response.
+ */
+export function extractFilesFromResponse(content: string): ExtractedFile[] {
+    const codeBlocks: ExtractedFile[] = [];
+    const state = { inCodeBlock: false, currentPath: '', currentCode: '' };
+
+    for (const line of content.split('\n')) {
+        if (!state.inCodeBlock) {
+            processOutsideBlock(line, state);
+        } else {
+            processInsideBlock(line, state, codeBlocks);
+        }
+    }
+
+    if (state.inCodeBlock) {
+        logger.warn(
+            `AI response ended with an unclosed code block — content discarded for path: "${state.currentPath || '(no path)'}"`
+        );
+    }
+
+    return codeBlocks;
+}
+
+/**
+ * Returns `true` for `.change` files. The AI may emit those alongside code
+ * files but they are persisted by a separate flow, so the writer skips them.
+ *
+ * @param filePath Candidate file path or filename.
+ * @returns Whether the path looks like a flexibility change file.
+ */
+export function isChangeFile(filePath: string): boolean {
+    return filePath.toLowerCase().endsWith('.change');
+}
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/processor.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/processor.ts
new file mode 100644
index 00000000000..ebe6b1170b6
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/processor.ts
@@ -0,0 +1,79 @@
+import type { AdpControllerExtensionInput, ExecuteFunctionalityOutput } from '../../../types/index.js';
+import { logger } from '../../../utils/logger.js';
+import { buildOutput } from '../output.js';
+import { extractFilesFromResponse, isChangeFile } from './parser.js';
+import { PathTraversalError, writeExtractedFile } from './writer.js';
+
+/**
+ * Returns the input parameters with `aiResponse` stripped, so the tool
+ * envelope echoed to the caller stays compact.
+ *
+ * @param params Input parameters.
+ * @returns Echoable parameters without the (potentially large) AI response.
+ */
+function echoableParams(params: AdpControllerExtensionInput): Record<string, unknown> {
+    const { aiResponse: _aiResponse, ...rest } = params;
+    return rest;
+}
+
+/**
+ * Persists every file extracted from `aiResponse`. Skips `.change` files and
+ * stops at the first error, returning whatever changes succeeded so far in
+ * the response envelope.
+ *
+ * @param appPath Adaptation project root directory.
+ * @param aiResponse Raw AI response with `**Path:**` markers and code fences.
+ * @param params Input parameters used to build the response envelope.
+ * @returns Tool output envelope with `success`, `error`, or `skipped` status.
+ */
+export async function processAiResponse(
+    appPath: string,
+    aiResponse: string,
+    params: AdpControllerExtensionInput
+): Promise<ExecuteFunctionalityOutput> {
+    logger.info('Processing AI response to extract files');
+    const extractedFiles = extractFilesFromResponse(aiResponse);
+    logger.info(`Extracted ${extractedFiles.length} files from AI response`);
+
+    const changes: string[] = [];
+    const echo = echoableParams(params);
+
+    for (const file of extractedFiles) {
+        if (isChangeFile(file.path)) {
+            logger.debug(`Skipping change file: ${file.path}`);
+            continue;
+        }
+
+        try {
+            const relativePath = await writeExtractedFile(appPath, file);
+            changes.push(`Created ${relativePath}`);
+        } catch (error) {
+            if (error instanceof PathTraversalError) {
+                logger.error(error.message);
+                return buildOutput('error', error.message, appPath, echo);
+            }
+            const message = `Failed to write file ${file.path}: ${
+                error instanceof Error ? error.message : String(error)
+            }`;
+            logger.error(message);
+            return buildOutput('error', message, appPath, echo, changes);
+        }
+    }
+
+    if (changes.length > 0) {
+        return buildOutput(
+            'success',
+            `Successfully processed ${changes.length} file(s) for ADP controller extension`,
+            appPath,
+            echo,
+            changes
+        );
+    }
+    return buildOutput(
+        'skipped',
+        'No files were processed. Provide aiResponse parameter with code blocks to generate files.',
+        appPath,
+        echo,
+        changes
+    );
+}
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/writer.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/writer.ts
new file mode 100644
index 00000000000..2f323c27e4e
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/ai-response/writer.ts
@@ -0,0 +1,63 @@
+import { promises as FSpromises } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { logger } from '../../../utils/logger.js';
+import type { ExtractedFile } from '../types.js';
+
+/**
+ * Raised when an extracted file path resolves outside the adaptation project
+ * root. Callers convert it into an `error` tool response.
+ */
+export class PathTraversalError extends Error {
+    /**
+     * @param appPath Adaptation project root.
+     * @param requestedPath Path supplied by the AI response.
+     */
+    constructor(appPath: string, requestedPath: string) {
+        super(`File path ${requestedPath} is outside the application path ${appPath}`);
+        this.name = 'PathTraversalError';
+    }
+}
+
+/**
+ * Resolves a path supplied by the model against `appPath` and confirms it
+ * stays inside the project. Accepts absolute and relative inputs; both are
+ * resolved to absolute form and compared against `appPath` with a trailing
+ * separator so that sibling directories sharing a prefix are rejected.
+ *
+ * @param appPath Adaptation project root directory.
+ * @param requestedPath Path supplied by the AI response (slash- or
+ *   backslash-separated, absolute or relative).
+ * @returns The resolved path, expressed relative to `appPath`.
+ * @throws {PathTraversalError} If the resolved path is outside `appPath`.
+ */
+export function resolveWithinAppPath(appPath: string, requestedPath: string): string {
+    const normalizedInput = requestedPath.replaceAll('\\', '/');
+    const resolvedAppPath = resolve(appPath);
+    const resolvedFilePath = isAbsolute(normalizedInput)
+        ? resolve(normalizedInput)
+        : resolve(resolvedAppPath, normalizedInput);
+
+    const appPathWithSep = resolvedAppPath.endsWith(sep) ? resolvedAppPath : resolvedAppPath + sep;
+    if (resolvedFilePath !== resolvedAppPath && !resolvedFilePath.startsWith(appPathWithSep)) {
+        throw new PathTraversalError(appPath, requestedPath);
+    }
+    return relative(resolvedAppPath, resolvedFilePath);
+}
+
+/**
+ * Writes a single extracted file under `appPath`, creating parent
+ * directories as needed. Returns the relative path on success.
+ *
+ * @param appPath Adaptation project root directory.
+ * @param file Extracted file produced by the parser.
+ * @returns The path that was written, relative to `appPath`.
+ * @throws {PathTraversalError} If the file would be written outside the project.
+ */
+export async function writeExtractedFile(appPath: string, file: ExtractedFile): Promise<string> {
+    const relativePath = resolveWithinAppPath(appPath, file.path);
+    const fullPath = join(appPath, relativePath);
+    await FSpromises.mkdir(dirname(fullPath), { recursive: true });
+    await FSpromises.writeFile(fullPath, file.code, 'utf-8');
+    logger.info(`Created file: ${relativePath}`);
+    return relativePath;
+}
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/constants.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/constants.ts
new file mode 100644
index 00000000000..406d7599d56
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/constants.ts
@@ -0,0 +1,11 @@
+/**
+ * Extensions of files that the project scanner reads back into the
+ * knowledge-base response. Anything else is ignored.
+ */
+export const SCANNABLE_EXTENSIONS: ReadonlySet<string> = new Set(['.js', '.ts', '.xml', '.json']);
+
+/**
+ * Per-file byte cap when scanning the project. Files larger than this are
+ * skipped to keep the prompt context tidy.
+ */
+export const MAX_SCANNED_FILE_SIZE = 50 * 1024;
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/index.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/index.ts
new file mode 100644
index 00000000000..7a88dadde0b
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/index.ts
@@ -0,0 +1,2 @@
+export { adpControllerExtension } from './tool.js';
+export type { ExistingProjectFile, ExtractedFile, ProjectContext } from './types.js';
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/knowledge-base.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/knowledge-base.ts
new file mode 100644
index 00000000000..55826d9f7c3
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/knowledge-base.ts
@@ -0,0 +1,152 @@
+import type { ExecuteFunctionalityOutput } from '../../types/index.js';
+import { buildOutput } from './output.js';
+import type { ExistingProjectFile, ProjectContext } from './types.js';
+
+const KNOWLEDGE_BASE = `You are a SAPUI5 Adaptation Project expert specializing in controller extensions and xml fragments for adaptation projects.
+
+IMPORTANT RULES:
+1. For controller extensions, always use "sap/ui/core/mvc/ControllerExtension" (NOT "sap/ui/core/mvc/Controller"). Use ControllerExtension.extend() pattern for proper adaptation project architecture.
+2. Assign stable, unique IDs to all controls, elements, subcontrols, items, and sub-items even when they have a key or other identifying attribute. This is crucial for adaptation project functionality.
+3. When providing code, always provide the entire file! Do not omit parts or replace them with an ellipsis. Keep the rest of the file as-is in your reply, only touch the part that needs to be changed.
+4. Immediately before each code block belonging to a file, with no other text in between, write the full path+name of the file in the following format: **Path:** fullFilePath. It is of extreme importance to always provide this format with the word 'Path' before the file path and no other content between this line and the code block.
+
+ADAPTATION PROJECT DETECTION:
+1. Check for the manifest.appdescr_variant file under the webapp folder
+2. If present, this is an adaptation project context
+3. CRITICAL: Read the "layer" property from manifest.appdescr_variant to determine if a customer prefix is needed:
+   - If layer is "CUSTOMER_BASE": Use "customer" prefix in controller extension namespace and fragment event handlers
+   - If layer is anything else: Do NOT use "customer" prefix
+4. Read "id" property from manifest.appdescr_variant and use it as namespace for change files
+5. Use the project root folder name (folder containing webapp) for controller extension namespaces
+6. ALWAYS check the manifest.appdescr_variant file before generating code
+
+CONTROLLER EXTENSION NAMESPACE PATTERN:
+FRAGMENT FILES (XML) - Event Handler References:
+- Standard layer: press=".extension.{project-folder-name}.{controller-extension-name}.{methodName}"
+- CUSTOMER_BASE layer: press=".extension.customer.{project-folder-name}.{controller-extension-name}.{methodName}"
+- Example (standard layer): press=".extension.myapp.ControllerExt.onPressAction"
+- Example (CUSTOMER_BASE layer): press=".extension.customer.myapp.ControllerExt.onPressAction"
+- The ".extension" prefix is ONLY used in fragment XML event handlers
+- The "customer" prefix is ONLY added in fragment XML when layer is CUSTOMER_BASE
+- The {project-folder-name} must be the adaptation project root folder name (the folder above webapp)
+
+CONTROLLER EXTENSION FILES (JS/TS) - File Paths and Namespaces:
+- File path: webapp/changes/coding/{controller-extension-name}.js (NO customer prefix in file path)
+- Namespace in ControllerExtension.extend():
+  * Standard layer: ControllerExtension.extend("{project-folder}.{ControllerExtName}", {...})
+  * CUSTOMER_BASE layer: ControllerExtension.extend("customer.{project-folder}.{ControllerExtName}", {...})
+- Example (standard): ControllerExtension.extend("adapt.blog.ControllerExt", {...})
+- Example (CUSTOMER_BASE): ControllerExtension.extend("customer.adapt.blog.ControllerExt", {...})
+- The "customer" prefix is added to the extend() namespace when layer is CUSTOMER_BASE
+- Do NOT use ".extension" prefix in the controller extension namespace
+- The controller file path does NOT include "customer" - only the namespace in the code does
+
+ID & CONTROL HANDLING:
+- CRITICAL: Do NOT add an id attribute to Dialog controls in controller extension files. Dialogs should be created without an id property.
+- Preserve any provided hints (e.g., <!-- viewName: ... -->, <!-- controlType: ... -->, <!-- targetAggregation: ... -->).
+- Do not remove original comments and align your changes with the given hints.
+- Follow adaptation project naming conventions for IDs
+
+FRAGMENT CONTROL WORKFLOW:
+If the original fragment or change file contains comments such as <!-- targetAggregation: ... --> or <!-- controlType: ... -->, use these as hints for what kind of control or aggregation is expected.
+IMPORTANT: The controlType comment refers to the PARENT control that will contain the fragment content.
+- <!-- controlType --> indicates the type of the parent control (e.g., Toolbar, VBox, etc.)
+- DO NOT add the controlType as a wrapper in your fragment - only provide the inner content
+- Example: If controlType is "Toolbar", provide only the Button/content, not another Toolbar wrapper
+- Keep these comments in the generated code as they are part of the project documentation.
+1. Use <!-- controlType -->, <!-- targetAggregation --> comments to identify the fragment's context.
+2. Provide ONLY the inner content suitable for the parent control (e.g., Button for Toolbar).
+3. Do not wrap the content in the controlType - it's already the parent container.
+4. If the user requests a specific control type, verify it's suitable for the parent container. If not, inform the user why.
+5. Take specific control prompts with priority
+6. Add a stable id to each element in the fragment
+
+CONTROLLER EXTENSION WORKFLOW:
+1. Read manifest.appdescr_variant:
+   - Extract 'id' property (app variant ID) - used for change file namespace
+   - Extract 'layer' property - determines if a customer prefix is needed
+   - CUSTOMER_BASE layer requires "customer" prefix in:
+     * Fragment event handlers: press=".extension.customer.{project}.{Controller}.{method}"
+     * Controller extension namespace: ControllerExtension.extend("customer.{project}.{Controller}", {...})
+
+2. Determine project folder name:
+   - Use the adaptation project root folder name (the folder that contains webapp)
+   - This is used in both fragment event handlers and controller extension namespace
+
+3. Create controller extension file:
+   - File path: webapp/changes/coding/{ControllerExtName}.js (NO customer prefix in path)
+   - Do NOT add .controller to the file name
+   - Use sap.ui.define with "sap/ui/core/mvc/ControllerExtension" (NOT sap/ui/core/mvc/Controller)
+   - Namespace pattern:
+     * Standard layer: return ControllerExtension.extend("{project-folder}.{ControllerExtName}", {...});
+     * CUSTOMER_BASE layer: return ControllerExtension.extend("customer.{project-folder}.{ControllerExtName}", {...});
+   - Example (standard): ControllerExtension.extend("adapt.blog.ControllerExt", {...})
+   - Example (CUSTOMER_BASE): ControllerExtension.extend("customer.adapt.blog.ControllerExt", {...})
+
+4. Create XML fragment file (if needed):
+   - Add stable, unique IDs to ALL controls and sub-elements
+   - Wire event handlers with proper namespace pattern:
+     * Standard layer: press=".extension.{project-folder}.{ControllerExt}.{methodName}"
+     * CUSTOMER_BASE layer: press=".extension.customer.{project-folder}.{ControllerExt}.{methodName}"
+   - The "customer" prefix matches the controller extension namespace
+   - The ".extension" prefix is ONLY used in fragment XML event handlers
+
+5. Do not create duplicate files:
+   - Do not create a new controller extension file if one already exists for the selected view
+
+OUTPUT REQUIREMENTS:
+- Each response must be self-contained and production-ready.
+- Each file must be complete, not partial.
+- Maintain consistent namespaces and controller references.
+- Follow adaptation project structure and conventions.
+- Include comments in code only where useful to explain complex logic.
+- CRITICAL: Assign stable, unique IDs to all controls, elements, subcontrols, items, and sub-items—even when they have a key or an identifying attribute. Verify all elements have IDs before responding.`;
+
+/**
+ * Builds the progressive-disclosure response sent back when the tool is
+ * called without an `aiResponse`. The model uses the embedded knowledge base
+ * and project context to generate the next call.
+ *
+ * @param appPath Adaptation project root, echoed back so the caller can
+ *   re-invoke without re-resolving paths.
+ * @param reason Short explanation of why the tool returned context instead
+ *   of writing files.
+ * @param projectContext Optional descriptor variant context. Omitted when the
+ *   tool short-circuited before reading the manifest.
+ * @param existingFiles Optional list of files already in the project that
+ *   the model should extend rather than overwrite.
+ * @returns A tool envelope with `status: 'info'` carrying the prompt.
+ */
+export function buildKnowledgeBaseResponse(
+    appPath: string,
+    reason: string,
+    projectContext?: ProjectContext,
+    existingFiles?: ExistingProjectFile[]
+): ExecuteFunctionalityOutput {
+    let message = `${reason}\n\n`;
+    message += `=== GENERATION RULES ===\n${KNOWLEDGE_BASE}\n\n`;
+    message += `=== HOW TO CALL THIS TOOL ===\n`;
+    message += `1. Generate code following the rules above\n`;
+    message += `2. Format with markdown code blocks, each preceded by "**Path:** fullFilePath" on its own line\n`;
+    message += `3. Call this tool again with the 'aiResponse' parameter containing the generated code\n\n`;
+
+    if (projectContext) {
+        message += `=== PROJECT CONTEXT ===\n`;
+        message += `- Layer: ${projectContext.layer}\n`;
+        message += `- Variant ID: ${projectContext.variantId}\n`;
+        message += `- Project folder name: ${projectContext.projectFolderName}\n`;
+        message += `- Customer prefix required: ${projectContext.layer === 'CUSTOMER_BASE' ? 'YES' : 'NO'}\n\n`;
+    }
+
+    if (existingFiles && existingFiles.length > 0) {
+        message += `=== EXISTING PROJECT FILES ===\n`;
+        message += `IMPORTANT: The following files already exist in this project. `;
+        message += `You MUST modify these existing files rather than creating new ones. `;
+        message += `Add your new methods to the existing controller extension and update existing fragments.\n\n`;
+        for (const file of existingFiles) {
+            message += `--- ${file.relativePath} ---\n${file.content}\n\n`;
+        }
+    }
+
+    return buildOutput('info', message, appPath);
+}
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/output.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/output.ts
new file mode 100644
index 00000000000..2072c187e0e
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/output.ts
@@ -0,0 +1,38 @@
+import type { ExecuteFunctionalityOutput } from '../../types/index.js';
+import { ADP_CONTROLLER_EXTENSION_FUNCTIONALITY_ID } from '../../constant.js';
+
+/**
+ * Statuses surfaced by the `adp_controller_extension` tool.
+ */
+export type AdpControllerExtensionStatus = 'success' | 'error' | 'info' | 'skipped';
+
+/**
+ * Builds an {@link ExecuteFunctionalityOutput} envelope for the
+ * `adp_controller_extension` tool. Centralised so every code path produces an
+ * identically shaped response and the functionality id is set in one place.
+ *
+ * @param status Outcome of the call.
+ * @param message Human-readable message returned to the caller.
+ * @param appPath Adaptation project root, echoed back for the caller.
+ * @param parameters Subset of input parameters to echo back. Pass `{}` when
+ * the call short-circuited before parameters were validated.
+ * @param changes File-system changes performed during the call.
+ * @returns Tool output envelope.
+ */
+export function buildOutput(
+    status: AdpControllerExtensionStatus,
+    message: string,
+    appPath: string,
+    parameters: Record<string, unknown> = {},
+    changes: string[] = []
+): ExecuteFunctionalityOutput {
+    return {
+        functionalityId: ADP_CONTROLLER_EXTENSION_FUNCTIONALITY_ID,
+        status,
+        message,
+        parameters,
+        appPath,
+        changes,
+        timestamp: new Date().toISOString()
+    };
+}
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/context.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/context.ts
new file mode 100644
index 00000000000..2baf8bf4d1c
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/context.ts
@@ -0,0 +1,34 @@
+import { basename } from 'node:path';
+import { getVariant } from '@sap-ux/adp-tooling';
+import type { ExecuteFunctionalityOutput } from '../../../types/index.js';
+import { logger } from '../../../utils/logger.js';
+import { buildOutput } from '../output.js';
+import type { ProjectContext } from '../types.js';
+
+/**
+ * Reads the descriptor variant and assembles a {@link ProjectContext}. Errors
+ * (including a missing `manifest.appdescr_variant`) are logged and surfaced
+ * as a tool error envelope so the caller can return it as-is.
+ *
+ * @param appPath Adaptation project root directory.
+ * @returns The context on success or an error envelope on failure.
+ */
+export async function loadProjectContext(
+    appPath: string
+): Promise<{ context: ProjectContext } | { error: ExecuteFunctionalityOutput }> {
+    try {
+        const variant = await getVariant(appPath);
+        const layer = String(variant.layer ?? '');
+        const variantId = variant.id ?? '';
+        const projectFolderName = basename(appPath);
+        logger.debug(`Manifest variant - layer: ${layer}, id: ${variantId}`);
+        logger.debug(`Project folder name: ${projectFolderName}`);
+        return { context: { layer, variantId, projectFolderName } };
+    } catch (error) {
+        const message = `Failed to read manifest.appdescr_variant: ${
+            error instanceof Error ? error.message : String(error)
+        }`;
+        logger.error(message);
+        return { error: buildOutput('error', message, appPath) };
+    }
+}
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/index.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/index.ts
new file mode 100644
index 00000000000..0f2fb333d35
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/index.ts
@@ -0,0 +1,2 @@
+export { loadProjectContext } from './context.js';
+export { scanExistingProjectFiles } from './scanner.js';
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/scanner.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/scanner.ts
new file mode 100644
index 00000000000..7ac676a4485
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/project/scanner.ts
@@ -0,0 +1,70 @@
+import { existsSync, promises as FSpromises } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+import { logger } from '../../../utils/logger.js';
+import { MAX_SCANNED_FILE_SIZE, SCANNABLE_EXTENSIONS } from '../constants.js';
+import { isChangeFile } from '../ai-response/parser.js';
+import type { ExistingProjectFile } from '../types.js';
+
+/**
+ * Scans `webapp/changes` for existing controller extensions and fragments so
+ * the model can extend them rather than create duplicates. Files exceeding
+ * {@link MAX_SCANNED_FILE_SIZE} or with extensions outside
+ * {@link SCANNABLE_EXTENSIONS} are skipped, as are `.change` files.
+ *
+ * @param appPath Adaptation project root directory.
+ * @returns The collected files with paths relative to `appPath`.
+ */
+export async function scanExistingProjectFiles(appPath: string): Promise<ExistingProjectFile[]> {
+    const changesDir = join(appPath, 'webapp', 'changes');
+    if (!existsSync(changesDir)) {
+        return [];
+    }
+    const files: ExistingProjectFile[] = [];
+    await collectFiles(changesDir, appPath, files);
+    return files;
+}
+
+/**
+ * Recursively walks `dir` and appends matching files to `files`.
+ *
+ * @param dir Directory to walk.
+ * @param appPath Adaptation project root, used to compute relative paths.
+ * @param files Accumulator the helper writes into.
+ */
+async function collectFiles(dir: string, appPath: string, files: ExistingProjectFile[]): Promise<void> {
+    let entries;
+    try {
+        entries = await FSpromises.readdir(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+            await collectFiles(fullPath, appPath, files);
+            continue;
+        }
+
+        if (!entry.isFile()) {
+            continue;
+        }
+
+        const ext = extname(entry.name);
+        if (!SCANNABLE_EXTENSIONS.has(ext) || isChangeFile(entry.name)) {
+            continue;
+        }
+
+        try {
+            const stat = await FSpromises.stat(fullPath);
+            if (stat.size > MAX_SCANNED_FILE_SIZE) {
+                continue;
+            }
+            const content = await FSpromises.readFile(fullPath, 'utf-8');
+            files.push({ relativePath: relative(appPath, fullPath), content });
+        } catch {
+            logger.debug(`Could not read file: ${fullPath}`);
+        }
+    }
+}
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/tool.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/tool.ts
new file mode 100644
index 00000000000..d56eefe4c3e
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/tool.ts
@@ -0,0 +1,46 @@
+import type { AdpControllerExtensionInput, ExecuteFunctionalityOutput } from '../../types/index.js';
+import { logger } from '../../utils/logger.js';
+import { processAiResponse } from './ai-response/index.js';
+import { buildKnowledgeBaseResponse } from './knowledge-base.js';
+import { loadProjectContext, scanExistingProjectFiles } from './project/index.js';
+
+/**
+ * Processes AI-generated controller extensions and fragments for SAPUI5
+ * Adaptation Projects. When called without `aiResponse`, returns the
+ * knowledge base and project context for progressive disclosure; otherwise
+ * extracts code blocks from `aiResponse` and writes the files into the
+ * project.
+ *
+ * @param params Input parameters including `appPath`, optional `prompt`,
+ *   `aiResponse`, `controllerName`, and `viewId`.
+ * @returns The tool execution output envelope.
+ */
+export async function adpControllerExtension(params: AdpControllerExtensionInput): Promise<ExecuteFunctionalityOutput> {
+    const { appPath, prompt, aiResponse } = params;
+
+    if (!appPath) {
+        return buildKnowledgeBaseResponse(
+            appPath ?? '',
+            'Missing required parameter: appPath. Provide the absolute path to the adaptation project root directory.'
+        );
+    }
+
+    if (aiResponse?.trim()) {
+        logger.info(`Executing ADP controller extension functionality for: ${prompt}`);
+        return processAiResponse(appPath, aiResponse, params);
+    }
+
+    const contextResult = await loadProjectContext(appPath);
+    if ('error' in contextResult) {
+        return contextResult.error;
+    }
+    const projectContext = contextResult.context;
+
+    const existingFiles = await scanExistingProjectFiles(appPath);
+    logger.debug(`Found ${existingFiles.length} existing project files`);
+
+    const reason = prompt
+        ? `Prompt received: "${prompt}"\n\nNo aiResponse provided. Generate the code following the rules below, then call this tool again with the aiResponse parameter.`
+        : 'No prompt or aiResponse provided. Provide a prompt describing what to create, generate the code following the rules below, then call this tool again with the aiResponse parameter.';
+    return buildKnowledgeBaseResponse(appPath, reason, projectContext, existingFiles);
+}
diff --git a/packages/fiori-mcp-server/src/tools/adp-controller-extension/types.ts b/packages/fiori-mcp-server/src/tools/adp-controller-extension/types.ts
new file mode 100644
index 00000000000..994ce65a6fc
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/adp-controller-extension/types.ts
@@ -0,0 +1,29 @@
+/**
+ * A file extracted from an AI response: the requested write path and its
+ * source code. The `path` may be absolute or relative — the writer is
+ * responsible for normalising and sandboxing it.
+ */
+export interface ExtractedFile {
+    path: string;
+    code: string;
+}
+
+/**
+ * A file already present in the adaptation project, surfaced to the model so
+ * it can extend existing controller extensions and fragments instead of
+ * creating duplicates.
+ */
+export interface ExistingProjectFile {
+    relativePath: string;
+    content: string;
+}
+
+/**
+ * Subset of `manifest.appdescr_variant` that affects controller-extension and
+ * fragment generation.
+ */
+export interface ProjectContext {
+    layer: string;
+    variantId: string;
+    projectFolderName: string;
+}
diff --git a/packages/fiori-mcp-server/src/tools/generate-adaptation-project.ts b/packages/fiori-mcp-server/src/tools/generate-adaptation-project.ts
new file mode 100644
index 00000000000..9a266756501
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/generate-adaptation-project.ts
@@ -0,0 +1,121 @@
+import type { ExecuteFunctionalityOutput, GenerateAdaptationProjectInput } from '../types/index.js';
+import { join } from 'node:path';
+import { existsSync, promises as FSpromises } from 'node:fs';
+import { runCmd, logger } from '../utils/index.js';
+import { GENERATE_ADAPTATION_PROJECT_ID } from '../constant.js';
+
+/**
+ * Generates a new SAP Fiori adaptation project by invoking the @sap-ux/adp Yeoman generator.
+ *
+ * @param params - Input parameters for the adaptation project generation.
+ * @returns A promise resolving to the execution output.
+ */
+function safeParams(params: GenerateAdaptationProjectInput): Omit<GenerateAdaptationProjectInput, 'password'> {
+    const { password: _password, ...rest } = params;
+    return rest;
+}
+
+export async function generateAdaptationProject(
+    params: GenerateAdaptationProjectInput
+): Promise<ExecuteFunctionalityOutput> {
+    const {
+        system,
+        application,
+        appPath,
+        targetFolder,
+        projectName,
+        namespace,
+        applicationTitle,
+        client,
+        username,
+        password
+    } = params;
+
+    if (!system || !application) {
+        return {
+            functionalityId: GENERATE_ADAPTATION_PROJECT_ID,
+            status: 'Error',
+            message: 'Missing required parameters: system and application are required.',
+            parameters: safeParams(params),
+            appPath,
+            changes: [],
+            timestamp: new Date().toISOString()
+        };
+    }
+
+    const finalTargetFolder = targetFolder ?? appPath;
+
+    try {
+        const jsonInput: Record<string, string> = {
+            system,
+            application,
+            targetFolder: finalTargetFolder
+        };
+
+        if (projectName) {
+            jsonInput.projectName = projectName;
+        } else {
+            jsonInput.projectName = getDefaultProjectName(finalTargetFolder);
+        }
+        if (namespace) {
+            jsonInput.namespace = namespace;
+        }
+        if (applicationTitle) {
+            jsonInput.applicationTitle = applicationTitle;
+        }
+        if (client) {
+            jsonInput.client = client;
+        }
+        if (username) {
+            jsonInput.username = username;
+        }
+        if (password) {
+            jsonInput.password = password;
+        }
+
+        await FSpromises.mkdir(finalTargetFolder, { recursive: true });
+
+        const jsonString = JSON.stringify(jsonInput);
+        const command = `npx -y yo@4 @sap-ux/adp '${jsonString}' --force`;
+        const { stdout, stderr } = await runCmd(command, { cwd: process.cwd() });
+
+        logger.info(stdout);
+        if (stderr) {
+            logger.error(stderr);
+        }
+
+        const projectPath = join(finalTargetFolder, jsonInput.projectName);
+        return {
+            functionalityId: GENERATE_ADAPTATION_PROJECT_ID,
+            status: 'Success',
+            message: `Adaptation project generated successfully at ${projectPath}.`,
+            parameters: safeParams(params),
+            appPath: projectPath,
+            changes: [],
+            timestamp: new Date().toISOString()
+        };
+    } catch (error) {
+        logger.error(`Error generating adaptation project: ${error}`);
+        return {
+            functionalityId: GENERATE_ADAPTATION_PROJECT_ID,
+            status: 'Error',
+            message: 'Error generating adaptation project: ' + (error instanceof Error ? error.message : String(error)),
+            parameters: safeParams(params),
+            appPath,
+            changes: [],
+            timestamp: new Date().toISOString()
+        };
+    }
+}
+
+function getDefaultProjectName(basePath: string, dirName: string = 'app.variant'): string {
+    let newDir = dirName;
+    let index = 0;
+
+    while (existsSync(join(basePath, newDir))) {
+        index++;
+        newDir = `${dirName}${index}`;
+    }
+
+    return newDir;
+}
diff --git a/packages/fiori-mcp-server/src/tools/index.ts b/packages/fiori-mcp-server/src/tools/index.ts
index 426e9ed011f..7370e60d842 100644
--- a/packages/fiori-mcp-server/src/tools/index.ts
+++ b/packages/fiori-mcp-server/src/tools/index.ts
@@ -14,6 +14,10 @@ export { listSapSystems } from './list-sap-systems.js';
 export { downloadODataServiceMetadata } from './download-odata-service-metadata.js';
 export { generateFioriAppOData } from './generate-fiori-app-odata.js';
 export { generateFioriAppCap } from './generate-fiori-app-cap.js';
+export { generateAdaptationProject } from './generate-adaptation-project.js';
+export { openAdaptationEditor } from './open-adaptation-editor.js';
+export { adpControllerExtension } from './adp-controller-extension/index.js';
+export { runRtaWorkflowStep } from './run-rta-workflow-step/index.js';
 
 export const tools = [
     {
@@ -63,7 +67,7 @@ export const tools = [
                     **ALWAYS** use the Service Center MCP tool 'list_systems' first if it is available. This tool is a fallback for environments where the Service Center MCP tool is not available.
                     Also use this tool when the user asks to 'list systems', 'list backends', or any equivalent phrasing.
                     Use this tool when the user references a SAP system by name or when you need to discover available systems
-                    before calling 'download_odata_service_metadata' or generating a Fiori application.`,
+                    before calling 'download_odata_service_metadata', 'generate_adaptation_project', or generating a Fiori application.`,
         annotations: {
             title: 'List SAP Systems',
             readOnlyHint: true,
@@ -176,6 +180,94 @@ export const tools = [
         },
         inputSchema: generatorConfigCAPJson
     },
+    {
+        name: 'generate_adaptation_project',
+        description: `Generates a new SAP Fiori adaptation project by calling the @sap-ux/adp generator.
+
+        This tool requires:
+        - system: The name of the SAP system (from list_sap_systems)
+        - application: The application ID to adapt
+
+        Optional parameters: targetFolder, projectName, namespace, applicationTitle, client, username, password.
+
+        Use 'list_sap_systems' first to discover available systems.
+        The generator will be executed with the provided JSON configuration.`,
+        annotations: {
+            title: 'Generate Adaptation Project',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false
+        },
+        inputSchema: convertToSchema(Input.GenerateAdaptationProjectInputSchema)
+    },
+    {
+        name: 'open_adaptation_editor',
+        description: `Starts the adaptation editor server by running 'npx fiori run /test/adaptation-editor.html' in the adaptation project directory.
+
+        This tool:
+        - Spawns the editor server process in the background
+        - Extracts the server URL and editor path from the command output
+        - Returns the full editor URL and process ID
+        - Provides instructions on how to stop the editor process
+
+        The editor server will run independently in the background. Use the returned process ID or port to stop it if needed.`,
+        annotations: {
+            title: 'Open Adaptation Editor',
+            readOnlyHint: false,
+            idempotentHint: false,
+            openWorldHint: false
+        },
+        inputSchema: convertToSchema(Input.OpenAdaptationEditorInputSchema)
+    },
+    {
+        name: 'adp_controller_extension',
+        description: `Processes AI-generated controller extensions and fragments for SAPUI5 Adaptation Projects.
+
+        This tool:
+        - Validates that the project is an adaptation project (has manifest.appdescr_variant)
+        - Reads manifest.appdescr_variant to determine layer and namespace requirements
+        - Extracts files from the AI response (markdown code blocks with **Path:** markers)
+        - Writes controller extension files, fragments, and other code files
+        - Does NOT write change files (.change) - these are handled separately
+
+        CRITICAL: The 'aiResponse' parameter must contain pre-generated code with markdown code blocks,
+        each preceded by "**Path:** fullFilePath" on its own line.
+        Call this tool first without 'aiResponse' to receive detailed generation rules and project context.`,
+        annotations: {
+            title: 'ADP Controller Extension',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false
+        },
+        inputSchema: convertToSchema(Input.AdpControllerExtensionInputSchema),
+        outputSchema: convertToSchema(Output.ExecuteFunctionalityOutputSchema)
+    },
+    {
+        name: 'run_rta_workflow_step',
+        description: `Internal step runner for the **sap-fiori-adp-controller-extension-flow** skill. **Do not call this tool standalone.**
+        The skill orchestrates a multi-step Runtime Authoring flow (start → get_overlays → AI selects target control → get_actions → AI selects action → get_context → AI prepares payload → call_action → save → stop) and decides what each call should pass. Calling out of sequence will fail with descriptive errors but bypasses the AI decision points the skill provides.
+
+        Always go through the **sap-fiori-adp-controller-extension-flow** skill in the SAP Fiori MCP server.
+
+        Steps:
+        - **start** — payload: \`{ site: string, frameId?: string }\`. Launches the editor URL, starts RTA, returns a fresh \`sessionId\` and \`{ rtaStarted: true }\`.
+        - **get_overlays** — sessionId only. Returns \`{ overlays: Overlay[] }\` for AI control selection.
+        - **get_actions** — sessionId, payload: \`{ controlId: string }\`. Returns \`{ actions: Action[] }\`.
+        - **get_context** — sessionId, payload: \`{ controlId: string, actionId: string }\`. Returns \`{ context }\`.
+        - **call_action** — sessionId, payload: \`{ controlId: string, actionId: string, actionPayload: object }\`. Returns \`{ success: boolean }\`.
+        - **save** — sessionId only. Returns \`{ saved: boolean }\`.
+        - **stop** — sessionId only. Closes the session; if no sessions remain, the browser shuts down. Returns \`{ stopped: true }\`.`,
+        annotations: {
+            title: 'Run RTA Workflow Step (skill-internal)',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true
+        },
+        inputSchema: convertToSchema(Input.RunRtaWorkflowStepInputSchema)
+    },
     {
         name: 'list_functionality',
         description: `**(Step 1 of 3) — Use this to modify an existing SAP Fiori application.**
diff --git a/packages/fiori-mcp-server/src/tools/open-adaptation-editor.ts b/packages/fiori-mcp-server/src/tools/open-adaptation-editor.ts
new file mode 100644
index 00000000000..d8ab250a171
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/open-adaptation-editor.ts
@@ -0,0 +1,308 @@
+import type { ExecuteFunctionalityOutput, OpenAdaptationEditorInput } from '../types/index.js';
+import { spawn, type ChildProcess, exec } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { promisify } from 'node:util';
+import { logger } from '../utils/index.js';
+import { OPEN_ADAPTATION_EDITOR_ID } from '../constant.js';
+
+const TIMEOUT_MS = 30000;
+const execAsync = promisify(exec);
+
+const TCP_LISTEN_WINDOWS = /TCP\s+[\d.]+:(\d+)\s+[\d.]+\s+LISTENING\s+\d+/;
+const TCP_LISTEN_UNIX = /TCP\s+(?:[\d.]+|\[?[\da-f:]+\]?|\*):(\d+)\s+\(LISTEN\)/;
+const EDITOR_PATH_RE = /fiori run --open\s+([^\s]+)/;
+const SERVER_URL_RE = /^URL:\s*(https?:\/\/[^\s]+)/;
+
+interface EditorState {
+    editorPath: string | undefined;
+    serverUrl: string | undefined;
+    resolved: boolean;
+    spawnError: Error | undefined;
+}
+
+async function getWindowsPorts(pid: number, preferredPort?: number): Promise<number[]> {
+    const { stdout } = await execAsync(`netstat -ano | findstr ${pid}`);
+    const found: number[] = [];
+    for (const line of stdout.split('\n')) {
+        const match = TCP_LISTEN_WINDOWS.exec(line);
+        if (!match?.[1]) {
+            continue;
+        }
+        const port = Number.parseInt(match[1], 10);
+        if (Number.isNaN(port)) {
+            continue;
+        }
+        found.push(port);
+        if (preferredPort && port === preferredPort) {
+            return found;
+        }
+    }
+    return found;
+}
+
+async function getChildPids(pid: number): Promise<number[]> {
+    try {
+        const { stdout } = await execAsync(`pgrep -P ${pid}`);
+        return stdout
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .map(Number)
+            .filter((p) => !Number.isNaN(p));
+    } catch {
+        return [];
+    }
+}
+
+async function getUnixPortsForPid(checkPid: number, preferredPort?: number): Promise<number[]> {
+    const found: number[] = [];
+    try {
+        const { stdout } = await execAsync(`lsof -p ${checkPid} -iTCP -sTCP:LISTEN -n -P`);
+        for (const line of stdout.split('\n')) {
+            if (line.trim().startsWith('COMMAND')) {
+                continue;
+            }
+            const match = TCP_LISTEN_UNIX.exec(line);
+            if (!match?.[1]) {
+                continue;
+            }
+            const port = Number.parseInt(match[1], 10);
+            if (Number.isNaN(port)) {
+                continue;
+            }
+            found.push(port);
+            if (preferredPort && port === preferredPort) {
+                return found;
+            }
+        }
+    } catch {
+        // lsof may fail for some PIDs
+    }
+    return found;
+}
+
+/**
+ * Gets the actual port number that a process is listening on.
+ *
+ * @param pid Process ID to check
+ * @param preferredPort Optional port to prefer if found
+ * @returns Port number if found, undefined otherwise
+ */
+async function getPortFromPid(pid: number, preferredPort?: number): Promise<number | undefined> {
+    const isWindows = process.platform === 'win32';
+    try {
+        let foundPorts: number[];
+        if (isWindows) {
+            foundPorts = await getWindowsPorts(pid, preferredPort);
+        } else {
+            const pidsToCheck = [pid, ...(await getChildPids(pid))];
+            foundPorts = [];
+            for (const checkPid of pidsToCheck) {
+                const ports = await getUnixPortsForPid(checkPid, preferredPort);
+                foundPorts.push(...ports);
+                if (preferredPort && foundPorts.includes(preferredPort)) {
+                    break;
+                }
+            }
+        }
+        return foundPorts[0];
+    } catch (error) {
+        logger.warn(`Failed to get port from PID ${pid}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return undefined;
+}
+
+function watchStdout(childProcess: ChildProcess, state: EditorState): void {
+    if (!childProcess.stdout) {
+        return;
+    }
+    const rl = createInterface({ input: childProcess.stdout, crlfDelay: Infinity });
+    rl.on('line', (line: string) => {
+        logger.debug(`Editor output: ${line}`);
+        if (!state.editorPath) {
+            const m = EDITOR_PATH_RE.exec(line);
+            if (m?.[1]) {
+                state.editorPath = m[1];
+                logger.info(`Extracted editor path: ${state.editorPath}`);
+            }
+        }
+        if (!state.serverUrl) {
+            const m = SERVER_URL_RE.exec(line);
+            if (m?.[1]) {
+                state.serverUrl = m[1];
+                logger.info(`Extracted server URL: ${state.serverUrl}`);
+            }
+        }
+        if (state.serverUrl && state.editorPath && !state.resolved) {
+            state.resolved = true;
+            rl.close();
+        }
+    });
+    rl.on('close', () => {
+        if (!state.resolved && state.serverUrl && state.editorPath) {
+            state.resolved = true;
+        }
+    });
+}
+
+function buildKillCommands(isWindows: boolean, processId: number, port: number | undefined): string {
+    const byPid = isWindows
+        ? `Windows: taskkill /PID ${processId} /F`
+        : `Mac/Linux: kill ${processId} (or kill -9 ${processId} for force kill)`;
+    if (!port) {
+        return `To stop the editor:\n${byPid}`;
+    }
+    const byPort = isWindows
+        ? `Windows: for /f "tokens=5" %a in ('netstat -ano ^| findstr :${port}') do taskkill /PID %a /F`
+        : `Mac/Linux: kill -9 $(lsof -ti:${port})`;
+    return `To stop the editor (recommended - by port):\n${byPort}\n\nAlternative (by PID):\n${byPid}`;
+}
+
+function getPreferredPort(serverUrl: string): number | undefined {
+    try {
+        const urlObj = new URL(serverUrl);
+        if (urlObj.port) {
+            return Number.parseInt(urlObj.port, 10);
+        }
+        return urlObj.protocol === 'https:' ? 443 : 80;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Starts the adaptation editor server by spawning `npx fiori run /test/adaptation-editor.html`
+ * in the adaptation project directory.
+ *
+ * @param params - Input parameters containing the appPath.
+ * @returns A promise resolving to the execution output with editor URL and process info.
+ */
+export async function openAdaptationEditor(params: OpenAdaptationEditorInput): Promise<ExecuteFunctionalityOutput> {
+    const { appPath } = params;
+    const isWindows = process.platform === 'win32';
+
+    try {
+        const command = isWindows ? 'npx.cmd' : 'npx';
+        const args = ['fiori', 'run', '/test/adaptation-editor.html'];
+        logger.info(`Spawning editor process: ${command} ${args.join(' ')} in ${appPath}`);
+
+        const childProcess: ChildProcess = spawn(command, args, {
+            cwd: appPath,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false
+        });
+
+        const state: EditorState = {
+            editorPath: undefined,
+            serverUrl: undefined,
+            resolved: false,
+            spawnError: undefined
+        };
+
+        watchStdout(childProcess, state);
+
+        if (childProcess.stderr) {
+            const stderrRl = createInterface({ input: childProcess.stderr, crlfDelay: Infinity });
+            stderrRl.on('line', (line: string) => logger.debug(`Editor stderr: ${line}`));
+        }
+
+        childProcess.on('error', (error) => {
+            logger.error(`Editor process error: ${error.message}`);
+            if (!state.resolved) {
+                state.spawnError = error;
+                state.resolved = true;
+            }
+        });
+
+        const timeoutId = setTimeout(() => {
+            if (!state.resolved) {
+                state.resolved = true;
+                logger.warn('Timeout waiting for editor URL');
+            }
+        }, TIMEOUT_MS);
+
+        await new Promise<void>((resolve) => {
+            const checkInterval = setInterval(() => {
+                if (state.resolved) {
+                    clearInterval(checkInterval);
+                    clearTimeout(timeoutId);
+                    resolve();
+                }
+            }, 100);
+        });
+
+        if (state.spawnError) {
+            return {
+                functionalityId: OPEN_ADAPTATION_EDITOR_ID,
+                status: 'Error',
+                message: `Failed to spawn editor process: ${state.spawnError.message}`,
+                parameters: params,
+                appPath,
+                changes: [],
+                timestamp: new Date().toISOString()
+            };
+        }
+
+        if (!state.serverUrl) {
+            if (childProcess.pid) {
+                try {
+                    process.kill(childProcess.pid, 'SIGTERM');
+                } catch {
+                    /* already exited */
+                }
+            }
+            return {
+                functionalityId: OPEN_ADAPTATION_EDITOR_ID,
+                status: 'Error',
+                message: 'Timeout: Could not extract server URL from editor output within 30 seconds',
+                parameters: params,
+                appPath,
+                changes: [],
+                timestamp: new Date().toISOString()
+            };
+        }
+
+        const processId = childProcess.pid;
+        if (!processId) {
+            return {
+                functionalityId: OPEN_ADAPTATION_EDITOR_ID,
+                status: 'Error',
+                message: 'Failed to get process ID from spawned editor process',
+                parameters: params,
+                appPath,
+                changes: [],
+                timestamp: new Date().toISOString()
+            };
+        }
+
+        childProcess.unref();
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+
+        const preferredPort = getPreferredPort(state.serverUrl);
+        const port = (await getPortFromPid(processId, preferredPort)) ?? preferredPort;
+        const editorUrl = `${state.serverUrl}${state.editorPath ?? '/test/adaptation-editor.html'}`;
+        const portLine = port ? `Actual listening port: ${port}` : '';
+        const message = `Adaptation editor started successfully.\nEditor URL: ${editorUrl}\nProcess ID: ${processId}\n${portLine}\n\n${buildKillCommands(isWindows, processId, port)}`;
+
+        return {
+            functionalityId: OPEN_ADAPTATION_EDITOR_ID,
+            status: 'Success',
+            message,
+            parameters: { ...params, editorUrl, processId, ...(port && { port }) },
+            appPath,
+            changes: [],
+            timestamp: new Date().toISOString()
+        };
+    } catch (error) {
+        logger.error(`Error opening adaptation editor: ${error}`);
+        return {
+            functionalityId: OPEN_ADAPTATION_EDITOR_ID,
+            status: 'Error',
+            message: 'Error opening adaptation editor: ' + (error instanceof Error ? error.message : String(error)),
+            parameters: params,
+            appPath,
+            changes: [],
+            timestamp: new Date().toISOString()
+        };
+    }
+}
diff --git a/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/index.ts b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/index.ts
new file mode 100644
index 00000000000..6e62d4da2ed
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/index.ts
@@ -0,0 +1,2 @@
+export { callFrontendAction, defaultTransport, disconnectSite, stopBrowser } from './playwright-bridge.js';
+export type { FrontendActionResult, FrontendActionTransport } from './types.js';
diff --git a/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/playwright-bridge.ts b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/playwright-bridge.ts
new file mode 100644
index 00000000000..4cfafaf073c
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/playwright-bridge.ts
@@ -0,0 +1,290 @@
+import { chromium, type Browser, type BrowserContext, type Frame, type Page } from 'playwright-core';
+import { logger } from '../../../utils/logger.js';
+import type { FrontendActionResult, FrontendActionTransport } from './types.js';
+
+// Module-scope singleton state.
+//   `browser` — launched once and reused for the lifetime of the Node process.
+//   `browserStartPromise` — deduplicates concurrent launches so the first
+//      caller's `chromium.launch()` is awaited by everyone else.
+//   `connectionRegistry` — site URL → open page handle. One entry per editor URL.
+let browser: Browser | undefined;
+let browserStartPromise: Promise<Browser> | undefined;
+const connectionRegistry: Map<string, PageRPC> = new Map();
+
+/**
+ * Internal RPC handle for a single browser page.
+ */
+interface PageRPC {
+    /** Invoke a frontend action on this page. */
+    callFrontendAction<TReturn = unknown>(
+        actionName: string,
+        payload?: Record<string, unknown>,
+        frameId?: string
+    ): Promise<FrontendActionResult<TReturn>>;
+    /** Close the underlying Playwright page. */
+    close(): Promise<void>;
+}
+
+/**
+ * Shape of the Joule webclient bridge as exposed on the editor page's
+ * `window` object. Only the surface we use is typed.
+ */
+interface WebclientBridgeWindow {
+    sapdas?: {
+        webclientBridge?: {
+            getFrontendActions?: () => Array<{
+                frontend_action_name: string;
+                function: (arg: unknown) => unknown;
+            }>;
+        };
+    };
+}
+
+/**
+ * Wraps a Playwright `Page` in an RPC handle that invokes Joule frontend
+ * actions through `window.sapdas.webclientBridge.getFrontendActions()`.
+ *
+ * @param page The Playwright page to wrap.
+ * @param context
+ * @returns An RPC handle for the page.
+ */
+async function createPageRPC(page: Page, context: BrowserContext): Promise<PageRPC> {
+    await page.waitForFunction(() => document.readyState === 'complete', undefined, { timeout: 30000 });
+
+    const callFrontendAction: PageRPC['callFrontendAction'] = async <TReturn = unknown>(
+        actionName: string,
+        payload: Record<string, unknown> = {},
+        frameId?: string
+    ): Promise<FrontendActionResult<TReturn>> => {
+        let executionContext: Page | Frame = page;
+
+        if (frameId) {
+            let matched: Frame | undefined;
+            for (const frame of page.frames()) {
+                const element = await frame.frameElement().catch(() => undefined);
+                if (!element) {
+                    continue;
+                }
+                const id = await element.getAttribute('id');
+                if (id === frameId) {
+                    matched = frame;
+                    break;
+                }
+            }
+            if (!matched) {
+                throw new Error(`Frame with id "${frameId}" not found`);
+            }
+            executionContext = matched;
+        }
+
+        const response = await executionContext.evaluate(
+            async ({ name, p }: { name: string; p: Record<string, unknown> }) => {
+                const bridge = (window as unknown as WebclientBridgeWindow).sapdas?.webclientBridge;
+                if (!bridge?.getFrontendActions) {
+                    throw new Error('window.sapdas.webclientBridge.getFrontendActions is not available on the page');
+                }
+                const actions = bridge.getFrontendActions();
+                const entry = actions.find((a) => a.frontend_action_name === name);
+                if (!entry) {
+                    throw new Error(`Frontend action "${name}" not registered`);
+                }
+                return await entry.function(p);
+            },
+            { name: actionName, p: payload }
+        );
+        return response as FrontendActionResult<TReturn>;
+    };
+
+    const close = async (): Promise<void> => {
+        await page.close();
+        await context.close();
+    };
+
+    return { callFrontendAction, close };
+}
+
+/**
+ * Returns `true` when the error message indicates Playwright could not find
+ * the browser binary it was asked to launch (system Chrome missing, bundled
+ * Chromium not installed, channel unavailable). Used to decide whether to
+ * retry the launch with Playwright's bundled Chromium.
+ *
+ * @param error Error thrown by `chromium.launch()`.
+ * @returns Whether the launch failed due to a missing browser binary.
+ */
+function isMissingBrowserError(error: unknown): boolean {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    return (
+        message.includes("executable doesn't exist") ||
+        message.includes('executable does not exist') ||
+        message.includes('failed to find') ||
+        message.includes('not installed') ||
+        message.includes('no such file or directory')
+    );
+}
+
+const INSTALL_HINT =
+    'Chromium executable not found. Install Playwright Chromium with `npx playwright install chromium` ' +
+    '(one-time, ~120 MB), or set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH to a Chrome/Chromium binary, ' +
+    'or set PLAYWRIGHT_BROWSER_CHANNEL to a channel available on this machine.';
+
+/**
+ * Launches a singleton Chromium browser via Playwright, or returns the
+ * existing instance. Browser selection priority:
+ * 1. `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` — explicit absolute path.
+ * 2. `PLAYWRIGHT_BROWSER_CHANNEL` — Playwright channel (`chrome`, `msedge`, etc.).
+ * 3. Default: `chrome` channel (system-installed Google Chrome).
+ * 4. Fallback: Playwright's bundled Chromium (requires `npx playwright install chromium`).
+ *
+ * @returns The connected Chromium browser instance.
+ */
+async function startBrowser(): Promise<Browser> {
+    if (browser?.isConnected()) {
+        return browser;
+    }
+    if (browserStartPromise) {
+        return browserStartPromise;
+    }
+
+    const executablePath = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH;
+    const channel = process.env.PLAYWRIGHT_BROWSER_CHANNEL ?? (executablePath ? undefined : 'chrome');
+    const launchArgs = ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--start-maximized'];
+
+    browserStartPromise = (async (): Promise<Browser> => {
+        try {
+            return await chromium.launch({
+                headless: false,
+                executablePath: executablePath ?? undefined,
+                channel,
+                args: launchArgs
+            });
+        } catch (error) {
+            if (!isMissingBrowserError(error)) {
+                throw error;
+            }
+            logger.warn(
+                `Primary browser launch failed (${
+                    error instanceof Error ? error.message : String(error)
+                }); retrying with Playwright bundled Chromium.`
+            );
+            try {
+                return await chromium.launch({ headless: false, args: launchArgs });
+            } catch (fallbackError) {
+                if (isMissingBrowserError(fallbackError)) {
+                    throw new Error(INSTALL_HINT);
+                }
+                throw fallbackError;
+            }
+        }
+    })();
+
+    try {
+        browser = await browserStartPromise;
+        browser.on('disconnected', () => {
+            browser = undefined;
+            browserStartPromise = undefined;
+            connectionRegistry.clear();
+        });
+        return browser;
+    } catch (error) {
+        browserStartPromise = undefined;
+        throw error;
+    }
+}
+
+/**
+ * Invokes a Joule frontend action on the page hosting `site`. Reuses an
+ * existing page if one is registered for the site; otherwise opens a new
+ * one. Throws on transport / lookup failures; returns the frontend action
+ * result envelope (including `isSuccess === false` payloads) for the caller to inspect.
+ *
+ * @param site URL to load (typically the adaptation editor URL).
+ * @param actionName Frontend action identifier, e.g. `com.sap.ui.flex.startRTA.v1`.
+ * @param payload Object payload forwarded to the frontend action function.
+ * @param frameId Optional frame element id to scope the call to an iframe.
+ * @returns The frontend action result envelope.
+ */
+export async function callFrontendAction<TReturn = unknown>(
+    site: string,
+    actionName: string,
+    payload: Record<string, unknown> = {},
+    frameId?: string
+): Promise<FrontendActionResult<TReturn>> {
+    const activeBrowser = await startBrowser();
+    let rpc = connectionRegistry.get(site);
+
+    if (!rpc) {
+        const context = await activeBrowser.newContext({ viewport: null });
+        const page: Page = await context.newPage();
+
+        page.on('pageerror', (err) => {
+            logger.warn(`Page error for ${site}: ${err.message}`);
+        });
+
+        page.on('close', () => {
+            connectionRegistry.delete(site);
+        });
+
+        await page.goto(site, { waitUntil: 'networkidle', timeout: 60000 });
+
+        rpc = await createPageRPC(page, context);
+        connectionRegistry.set(site, rpc);
+    }
+
+    return rpc.callFrontendAction<TReturn>(actionName, payload, frameId);
+}
+
+/**
+ * Closes the page registered for `site` and removes it from the registry.
+ *
+ * @param site URL whose page should be closed.
+ */
+export async function disconnectSite(site: string): Promise<void> {
+    const rpc = connectionRegistry.get(site);
+    if (rpc) {
+        await rpc.close();
+        connectionRegistry.delete(site);
+    }
+}
+
+/**
+ * Closes every registered page and the browser itself. Safe to call when no
+ * browser is running.
+ */
+export async function stopBrowser(): Promise<void> {
+    if (!browser) {
+        return;
+    }
+
+    for (const [site, rpc] of connectionRegistry.entries()) {
+        try {
+            await rpc.close();
+        } catch {
+            // Ignore errors when closing pages.
+        }
+        connectionRegistry.delete(site);
+    }
+
+    try {
+        await browser.close();
+    } catch {
+        // Ignore errors when closing the browser.
+    }
+
+    browser = undefined;
+    browserStartPromise = undefined;
+}
+
+/**
+ * Default transport — the Playwright-backed implementation bound from this
+ * module's exports. The `rta/` layer consumes this when no transport is
+ * injected explicitly.
+ */
+export const defaultTransport: FrontendActionTransport = {
+    callFrontendAction,
+    disconnectSite,
+    stopBrowser
+};
diff --git a/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/types.ts b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/types.ts
new file mode 100644
index 00000000000..ca412ee067b
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/browser/types.ts
@@ -0,0 +1,28 @@
+/**
+ * Result envelope returned by every Joule frontend action.
+ */
+export interface FrontendActionResult<T = unknown> {
+    isSuccess: boolean;
+    payload: T | null;
+    error: { code: string; message: string | null } | null;
+}
+
+/**
+ * Transport that delivers Joule frontend action calls to the running
+ * adaptation editor. The `rta/` layer depends on this interface, not on the
+ * concrete Playwright implementation, so a fake transport can be injected
+ * for tests or a different transport plugged in without touching the command wrappers.
+ */
+export interface FrontendActionTransport {
+    /** Invoke a frontend action on the page hosting `site`. */
+    callFrontendAction<TReturn = unknown>(
+        site: string,
+        actionName: string,
+        payload?: Record<string, unknown>,
+        frameId?: string
+    ): Promise<FrontendActionResult<TReturn>>;
+    /** Close the page registered for `site`, if any. */
+    disconnectSite(site: string): Promise<void>;
+    /** Close every registered page and the underlying transport (browser). */
+    stopBrowser(): Promise<void>;
+}
diff --git a/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/index.ts b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/index.ts
new file mode 100644
index 00000000000..b4a0e4b9b6c
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/index.ts
@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto';
+
+import {
+    executeAction,
+    FrontendActionError,
+    getActions,
+    getElementContext,
+    getOverlays,
+    saveChanges,
+    startRta,
+    type EditorPage
+} from './rta/index.js';
+import { logger } from '../../utils/logger.js';
+import { defaultTransport } from './browser/index.js';
+import { STEPS, type RunRtaWorkflowStepInput, type RunRtaWorkflowStepResult } from './types.js';
+
+const sessions: Map<string, EditorPage> = new Map();
+
+/**
+ * Looks up the session record for `sessionId` and throws if it is missing.
+ *
+ * @param sessionId Session id from the input, typically returned by the `start` step.
+ * @returns The id and the matching `EditorPage`.
+ */
+function getSession(sessionId: string | undefined): { id: string; session: EditorPage } {
+    if (!sessionId) {
+        throw new Error('sessionId is required for this step');
+    }
+    const session = sessions.get(sessionId);
+    if (!session) {
+        throw new Error(`Unknown sessionId: ${sessionId}. Call the "start" step first.`);
+    }
+    return { id: sessionId, session };
+}
+
+/**
+ * Reads `key` from `payload` and asserts it is a non-empty string. The Zod
+ * schema declares `payload` as `record(string, unknown)` so the AI can pass
+ * any shape; per-step required fields are validated here instead.
+ *
+ * @param payload The step payload, possibly undefined.
+ * @param key Property name to read.
+ * @returns The string value.
+ */
+function requireString(payload: Record<string, unknown> | undefined, key: string): string {
+    const value = payload?.[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`payload.${key} is required and must be a non-empty string`);
+    }
+    return value;
+}
+
+/**
+ * Reads `key` from `payload` and asserts it is a plain object.
+ *
+ * @param payload The step payload, possibly undefined.
+ * @param key Property name to read.
+ * @returns The object value.
+ */
+function requireObject(payload: Record<string, unknown> | undefined, key: string): Record<string, unknown> {
+    const value = payload?.[key];
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`payload.${key} is required and must be an object`);
+    }
+    return value as Record<string, unknown>;
+}
+
+/**
+ * Runs one step of the RTA workflow. Dispatches by `input.step`, looks up
+ * or creates a session, and forwards to the corresponding `rta` command
+ * wrapper. Each step's return shape matches the schema in `types/input.ts`.
+ *
+ * @param input Step + sessionId + step-specific payload.
+ * @returns Step-specific result. The `start` step returns the new session id.
+ */
+export async function runRtaWorkflowStep(input: RunRtaWorkflowStepInput): Promise<RunRtaWorkflowStepResult> {
+    try {
+        switch (input.step) {
+            case 'start': {
+                const site = requireString(input.payload, 'site');
+                const frameId = typeof input.payload?.frameId === 'string' ? input.payload.frameId : undefined;
+                const result = await startRta(defaultTransport, { site, frameId });
+                const sessionId = randomUUID();
+                sessions.set(sessionId, { site, frameId });
+                return { sessionId, ...result };
+            }
+            case 'get_overlays': {
+                const { session } = getSession(input.sessionId);
+                const overlays = await getOverlays(defaultTransport, session);
+                return { overlays };
+            }
+            case 'get_actions': {
+                const { session } = getSession(input.sessionId);
+                const controlId = requireString(input.payload, 'controlId');
+                const actions = await getActions(defaultTransport, session, controlId);
+                return { actions };
+            }
+            case 'get_context': {
+                const { session } = getSession(input.sessionId);
+                const controlId = requireString(input.payload, 'controlId');
+                const actionId = requireString(input.payload, 'actionId');
+                const context = await getElementContext(defaultTransport, session, controlId, actionId);
+                return { context };
+            }
+            case 'call_action': {
+                const { session } = getSession(input.sessionId);
+                const controlId = requireString(input.payload, 'controlId');
+                const actionId = requireString(input.payload, 'actionId');
+                const actionPayload = requireObject(input.payload, 'actionPayload');
+                const ok = await executeAction(defaultTransport, session, controlId, actionId, actionPayload);
+                return { success: ok };
+            }
+            case 'save': {
+                const { session } = getSession(input.sessionId);
+                const ok = await saveChanges(defaultTransport, session);
+                return { saved: ok };
+            }
+            case 'stop': {
+                const { id } = getSession(input.sessionId);
+                sessions.delete(id);
+                if (sessions.size === 0) {
+                    await defaultTransport.stopBrowser();
+                }
+                return { stopped: true };
+            }
+            default:
+                throw new Error(`Unknown step: ${String(input.step)}. Valid steps: ${STEPS.join(', ')}`);
+        }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (error instanceof FrontendActionError) {
+            logger.warn(`Frontend action failed in step ${input.step}: ${message}`);
+        } else {
+            logger.error(`run_rta_workflow_step "${input.step}" failed: ${message}`);
+        }
+        throw error;
+    }
+}
diff --git a/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/commands.ts b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/commands.ts
new file mode 100644
index 00000000000..57f61c81afd
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/commands.ts
@@ -0,0 +1,180 @@
+import type { FrontendActionResult, FrontendActionTransport } from '../browser/index.js';
+import type { Action, EditorPage, ElementContext, Overlay } from './types.js';
+
+const ACTION_PREFIX = 'com.sap.ui.flex';
+const ACTION_VERSION = 'v1';
+
+/**
+ * Error raised when a Joule frontend action returns `isSuccess === false`.
+ */
+export class FrontendActionError extends Error {
+    public readonly code: string;
+
+    /**
+     * Constructs the error with a message like `Frontend action <actionName> failed [<code>]: <message>`.
+     *
+     * @param actionName Fully-qualified frontend action name that failed.
+     * @param code Error code from the action's result envelope, or `GENERIC_ERROR`.
+     * @param message Human-readable error message from the result envelope.
+     */
+    constructor(actionName: string, code: string, message: string | null | undefined) {
+        super(`Frontend action ${actionName} failed [${code}]: ${message ?? '(no message)'}`);
+        this.name = 'FrontendActionError';
+        this.code = code;
+    }
+}
+
+/**
+ * Builds a fully-qualified frontend action name (`com.sap.ui.flex.<name>.v1`).
+ *
+ * @param name Short action name, e.g. `startRTA`.
+ * @returns The fully-qualified action name.
+ */
+const action = (name: string): string => `${ACTION_PREFIX}.${name}.${ACTION_VERSION}`;
+
+/**
+ * Returns the result payload on success; throws `FrontendActionError` on failure.
+ *
+ * @param actionName Fully-qualified action name, used in the error message.
+ * @param result Frontend action result envelope.
+ * @returns The unwrapped payload.
+ */
+function unwrap<T>(actionName: string, result: FrontendActionResult<T>): T {
+    if (!result.isSuccess) {
+        const code = result.error?.code ?? 'GENERIC_ERROR';
+        throw new FrontendActionError(actionName, code, result.error?.message);
+    }
+    return result.payload as T;
+}
+
+/**
+ * Starts Runtime Authoring on the editor page.
+ *
+ * @param transport Transport used to deliver the call.
+ * @param page Target editor page.
+ * @returns `{ rtaStarted: true }` once RTA has started.
+ */
+export async function startRta(transport: FrontendActionTransport, page: EditorPage): Promise<{ rtaStarted: boolean }> {
+    const name = action('startRTA');
+    return unwrap(name, await transport.callFrontendAction<{ rtaStarted: boolean }>(page.site, name, {}, page.frameId));
+}
+
+/**
+ * Returns all editable overlays exposed by the running RTA instance.
+ *
+ * @param transport Transport used to deliver the call.
+ * @param page Target editor page.
+ * @returns The overlays on the page.
+ */
+export async function getOverlays(transport: FrontendActionTransport, page: EditorPage): Promise<Overlay[]> {
+    const name = action('getOverlaysInformation');
+    return unwrap(name, await transport.callFrontendAction<Overlay[]>(page.site, name, {}, page.frameId));
+}
+
+/**
+ * Returns the actions available for the given control.
+ *
+ * @param transport Transport used to deliver the call.
+ * @param page Target editor page.
+ * @param controlId UI5 control id to inspect.
+ * @returns The actions available on `controlId`.
+ */
+export async function getActions(
+    transport: FrontendActionTransport,
+    page: EditorPage,
+    controlId: string
+): Promise<Action[]> {
+    const name = action('getActions');
+    return unwrap(name, await transport.callFrontendAction<Action[]>(page.site, name, { controlId }, page.frameId));
+}
+
+/**
+ * Returns context information for a control + action combination.
+ *
+ * @param transport Transport used to deliver the call.
+ * @param page Target editor page.
+ * @param controlId UI5 control id.
+ * @param actionId Action id reported by `getActions`.
+ * @returns The element context for the action.
+ */
+export async function getElementContext(
+    transport: FrontendActionTransport,
+    page: EditorPage,
+    controlId: string,
+    actionId: string
+): Promise<ElementContext> {
+    const name = action('getContext');
+    return unwrap(
+        name,
+        await transport.callFrontendAction<ElementContext>(page.site, name, { controlId, actionId }, page.frameId)
+    );
+}
+
+/**
+ * Executes an RTA action on a control with the prepared payload.
+ *
+ * @param transport Transport used to deliver the call.
+ * @param page Target editor page.
+ * @param controlId UI5 control id.
+ * @param actionId Action id reported by `getActions`.
+ * @param payload Action-specific payload, shape determined by `getElementContext`.
+ * @returns `true` if the action was applied.
+ */
+export async function executeAction(
+    transport: FrontendActionTransport,
+    page: EditorPage,
+    controlId: string,
+    actionId: string,
+    payload: Record<string, unknown>
+): Promise<boolean> {
+    const name = action('callAction');
+    return unwrap(
+        name,
+        await transport.callFrontendAction<boolean>(page.site, name, { controlId, actionId, payload }, page.frameId)
+    );
+}
+
+/**
+ * Persists all RTA changes that have been applied so far.
+ *
+ * @param transport Transport used to deliver the call.
+ * @param page Target editor page.
+ * @returns `true` if the changes were saved.
+ */
+export async function saveChanges(transport: FrontendActionTransport, page: EditorPage): Promise<boolean> {
+    const name = action('saveChanges');
+    return unwrap(name, await transport.callFrontendAction<boolean>(page.site, name, {}, page.frameId));
+}
+
+/**
+ * Switches the running RTA instance to visualization mode.
+ *
+ * @param transport Transport used to deliver the call.
+ * @param page Target editor page.
+ * @returns `{ visualizationStarted: true }` once visualization mode is active.
+ */
+export async function startVisualization(
+    transport: FrontendActionTransport,
+    page: EditorPage
+): Promise<{ visualizationStarted: boolean }> {
+    const name = action('startVisualization');
+    return unwrap(
+        name,
+        await transport.callFrontendAction<{ visualizationStarted: boolean }>(page.site, name, {}, page.frameId)
+    );
+}
+
+/**
+ * Tears down the RTA session. With a `page`, only that site's page is closed;
+ * without one, the underlying transport (browser) stops entirely.
+ *
+ * @param transport Transport used to deliver the call.
+ * @param page Optional editor page; omit to stop the whole transport.
+ */
+export async function stopRta(transport: FrontendActionTransport, page?: EditorPage): Promise<void> {
+    if (page) {
+        await transport.disconnectSite(page.site);
+    } else {
+        await transport.stopBrowser();
+    }
+}
diff --git a/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/index.ts b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/index.ts
new file mode 100644
index 00000000000..c3f08696e27
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/index.ts
@@ -0,0 +1,12 @@
+export {
+    FrontendActionError,
+    executeAction,
+    getActions,
+    getElementContext,
+    getOverlays,
+    saveChanges,
+    startRta,
+    startVisualization,
+    stopRta
+} from './commands.js';
+export type { Action, ActionPayloadProperty, EditorPage, ElementContext, Overlay } from './types.js';
diff --git a/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/types.ts b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/types.ts
new file mode 100644
index 00000000000..02766ccc4d6
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/rta/types.ts
@@ -0,0 +1,65 @@
+/**
+ * Where an RTA command runs: the editor URL and an optional iframe id.
+ * Used both as a per-command target and as the per-session record kept by the tool dispatcher.
+ */
+export interface EditorPage {
+    /** Editor URL returned by `open_adaptation_editor`. */
+    site: string;
+    /** Optional iframe element id (e.g. `"preview"`) to scope the call to. */
+    frameId?: string;
+}
+
+/**
+ * Information about an editable UI5 control reported by Joule's
+ * `getOverlaysInformation` frontend action.
+ */
+export interface Overlay {
+    /** Unique identifier of the overlay element. */
+    overlayId: string;
+    /** UI5 control id (the underlying element). */
+    controlId: string;
+    /** Human-readable label as resolved by the design-time metadata. */
+    label: string;
+    /** UI5 control type, e.g. `sap.m.Button`. */
+    controlType: string;
+}
+
+/**
+ * Single payload property expected by an RTA action.
+ */
+export interface ActionPayloadProperty {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+}
+
+/**
+ * Available RTA action for a control as reported by `getActions`.
+ */
+export interface Action {
+    /** Action id, e.g. `rename`, `remove`, `reveal`, `move`. */
+    id: string;
+    /** Localized label resolved from the `sap.ui.rta` resource bundle. */
+    label?: string;
+    /** Action parameters; shape comes straight from the action service. */
+    payload?: ActionPayloadProperty[];
+}
+
+/**
+ * Element context reported by `getContext`. Some properties are
+ * action-specific extensions; the structural ones below are always present
+ * on success.
+ */
+export interface ElementContext {
+    /** Aggregation name on the control's parent that holds this control. */
+    parentAggregationName?: string;
+    /** Default aggregation name on this control. */
+    defaultChildAggregationName?: string;
+    /** Type expected by the default aggregation. */
+    controlType?: string;
+    /** Direct children of the default aggregation. */
+    content?: Array<{ controlId: string; label?: string }>;
+    /** Action-specific extensions are merged in at the top level. */
+    [extra: string]: unknown;
+}
diff --git a/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/types.ts b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/types.ts
new file mode 100644
index 00000000000..11caff90816
--- /dev/null
+++ b/packages/fiori-mcp-server/src/tools/run-rta-workflow-step/types.ts
@@ -0,0 +1,63 @@
+import type { Action, ElementContext, Overlay } from './rta/types.js';
+
+/**
+ * The seven steps run_rta_workflow_step accepts. Single source of truth —
+ * the Zod schema in `types/input.ts` derives its enum from this tuple, so
+ * adding a step here is the only place that needs to change.
+ */
+export const STEPS = ['start', 'get_overlays', 'get_actions', 'get_context', 'call_action', 'save', 'stop'] as const;
+
+export type Step = (typeof STEPS)[number];
+
+/**
+ * Input shape accepted by `run_rta_workflow_step`. The `payload` object
+ * carries step-specific data so the tool surface stays tidy.
+ */
+export interface RunRtaWorkflowStepInput {
+    step: Step;
+    sessionId?: string;
+    payload?: Record<string, unknown>;
+}
+
+/**
+ * Per-step result shapes. The dispatcher returns the union; each `case`
+ * inside the switch returns the matching shape, so the compiler verifies
+ * each branch produces something assignable to its slot.
+ */
+export interface StartStepResult {
+    sessionId: string;
+    rtaStarted: boolean;
+}
+
+export interface GetOverlaysStepResult {
+    overlays: Overlay[];
+}
+
+export interface GetActionsStepResult {
+    actions: Action[];
+}
+
+export interface GetContextStepResult {
+    context: ElementContext;
+}
+
+export interface CallActionStepResult {
+    success: boolean;
+}
+
+export interface SaveStepResult {
+    saved: boolean;
+}
+
+export interface StopStepResult {
+    stopped: true;
+}
+
+export type RunRtaWorkflowStepResult =
+    | StartStepResult
+    | GetOverlaysStepResult
+    | GetActionsStepResult
+    | GetContextStepResult
+    | CallActionStepResult
+    | SaveStepResult
+    | StopStepResult;
diff --git a/packages/fiori-mcp-server/src/types/index.ts b/packages/fiori-mcp-server/src/types/index.ts
index 8157d9005ea..b1286212a31 100644
--- a/packages/fiori-mcp-server/src/types/index.ts
+++ b/packages/fiori-mcp-server/src/types/index.ts
@@ -7,7 +7,11 @@ import type {
     ListFioriAppsInputSchema,
     ListFunctionalitiesInputSchema,
     DocSearchInputSchema,
-    DownloadODataServiceMetadataInputSchema
+    DownloadODataServiceMetadataInputSchema,
+    GenerateAdaptationProjectInputSchema,
+    OpenAdaptationEditorInputSchema,
+    AdpControllerExtensionInputSchema,
+    RunRtaWorkflowStepInputSchema
 } from './input.js';
 import type {
     ExecuteFunctionalityOutputSchema,
@@ -38,6 +42,10 @@ export type ExecuteFunctionalityOutput = zod.infer<typeof ExecuteFunctionalityOu
 
 export type DocSearchInput = zod.infer<typeof DocSearchInputSchema>;
 export type DownloadODataServiceMetadataInput = zod.infer<typeof DownloadODataServiceMetadataInputSchema>;
+export type GenerateAdaptationProjectInput = zod.infer<typeof GenerateAdaptationProjectInputSchema>;
+export type OpenAdaptationEditorInput = zod.infer<typeof OpenAdaptationEditorInputSchema>;
+export type AdpControllerExtensionInput = zod.infer<typeof AdpControllerExtensionInputSchema>;
+export type RunRtaWorkflowStepInput = zod.infer<typeof RunRtaWorkflowStepInputSchema>;
 export type DownloadODataServiceMetadataOutput = zod.infer<typeof FetchServiceMetadataOutputSchema>;
 export type GenerateAppOutput = zod.infer<typeof GenerateAppOutputSchema>;
 export type ListSapSystemsOutput = zod.infer<typeof ListSapSystemsOutputSchema>;
diff --git a/packages/fiori-mcp-server/src/types/input.ts b/packages/fiori-mcp-server/src/types/input.ts
index 82c2a566b25..92f6564e0d4 100644
--- a/packages/fiori-mcp-server/src/types/input.ts
+++ b/packages/fiori-mcp-server/src/types/input.ts
@@ -1,5 +1,6 @@
 import * as zod from 'zod';
 import { FunctionalityIdSchema } from './basic.js';
+import { STEPS } from '../tools/run-rta-workflow-step/types.js';
 
 /**
  * Input interface for the 'list_fiori_apps' functionality
@@ -96,3 +97,78 @@ export const DocSearchInputSchema = zod.object({
         .min(2)
         .describe('The search query for fiori elements, annotations, sapui5, fiori tools documentation')
 });
+
+export const GenerateAdaptationProjectInputSchema = zod.object({
+    system: zod.string().describe('The name of the SAP system (obtained from list_sap_systems)'),
+    application: zod.string().describe('The application ID to adapt (e.g., sap.ui.demoapps.rta.fe)'),
+    appPath: zod
+        .string()
+        .describe(
+            'Absolute path to the current working directory or target location. Used as fallback if targetFolder is not provided.'
+        ),
+    targetFolder: zod
+        .string()
+        .optional()
+        .describe(
+            'Optional absolute path to the target folder where the project will be generated. Defaults to appPath if not provided.'
+        ),
+    projectName: zod
+        .string()
+        .optional()
+        .describe('Optional name of the project. Defaults to app.variant if not provided.'),
+    namespace: zod.string().optional().describe('Optional namespace for the project'),
+    applicationTitle: zod.string().optional().describe('Optional title for the application'),
+    client: zod.string().optional().describe('Optional SAP client number'),
+    username: zod.string().optional().describe('Optional username for authentication'),
+    password: zod.string().optional().describe('Optional password for authentication')
+});
+
+export const OpenAdaptationEditorInputSchema = zod.object({
+    appPath: zod
+        .string()
+        .describe('Absolute path to the adaptation project root directory (where package.json resides).')
+});
+
+export const AdpControllerExtensionInputSchema = zod.object({
+    appPath: zod
+        .string()
+        .describe(
+            'Absolute path to the adaptation project root directory (where webapp/manifest.appdescr_variant resides).'
+        ),
+    prompt: zod
+        .string()
+        .optional()
+        .describe('Natural language prompt describing what controller extension or fragment to create'),
+    aiResponse: zod
+        .string()
+        .optional()
+        .describe(
+            'AI-generated response containing code blocks with **Path:** markers preceding each code block. Omit to receive generation rules and project context.'
+        ),
+    controllerName: zod.string().optional().describe('Desired controller extension name (without .js/.ts extension)'),
+    viewId: zod.string().optional().describe('Optional target view identifier for the controller extension')
+});
+
+export const RunRtaWorkflowStepInputSchema = zod.object({
+    step: zod
+        .enum(STEPS)
+        .describe(
+            'Which RTA workflow step to run. Each step maps to one Joule frontend action ' +
+                'on the adaptation editor page.'
+        ),
+    sessionId: zod
+        .string()
+        .optional()
+        .describe('Session identifier returned by the "start" step. Required for every step except "start" itself.'),
+    payload: zod
+        .record(zod.string(), zod.unknown())
+        .optional()
+        .describe(
+            'Step-specific arguments. ' +
+                'start: { site: string, frameId?: string }. ' +
+                'get_actions: { controlId: string }. ' +
+                'get_context: { controlId: string, actionId: string }. ' +
+                'call_action: { controlId: string, actionId: string, actionPayload: object }. ' +
+                'get_overlays / save / stop: omit.'
+        )
+});
diff --git a/packages/fiori-mcp-server/test/__mocks__/@sap-ux/adp-tooling.cjs b/packages/fiori-mcp-server/test/__mocks__/@sap-ux/adp-tooling.cjs
new file mode 100644
index 00000000000..e59f2b143c4
--- /dev/null
+++ b/packages/fiori-mcp-server/test/__mocks__/@sap-ux/adp-tooling.cjs
@@ -0,0 +1,4 @@
+'use strict';
+module.exports = {
+    getVariant: jest.fn().mockResolvedValue({})
+};
diff --git a/packages/fiori-mcp-server/test/unit/server.test.ts b/packages/fiori-mcp-server/test/unit/server.test.ts
index 64eb91dcec8..4d241c7fdaf 100644
--- a/packages/fiori-mcp-server/test/unit/server.test.ts
+++ b/packages/fiori-mcp-server/test/unit/server.test.ts
@@ -40,6 +40,10 @@ const mockListSapSystems = jest.fn<any>();
 const mockDownloadODataServiceMetadata = jest.fn<any>();
 const mockGenerateFioriAppOData = jest.fn<any>();
 const mockGenerateFioriAppCap = jest.fn<any>();
+const mockGenerateAdaptationProject = jest.fn<any>();
+const mockOpenAdaptationEditor = jest.fn<any>();
+const mockAdpControllerExtension = jest.fn<any>();
+const mockRunRtaWorkflowStep = jest.fn<any>();
 const actualTools = await import('../../src/tools/index.js');
 jest.unstable_mockModule('../../src/tools', () => ({
     ...actualTools,
@@ -51,7 +55,11 @@ jest.unstable_mockModule('../../src/tools', () => ({
     listSapSystems: mockListSapSystems,
     downloadODataServiceMetadata: mockDownloadODataServiceMetadata,
     generateFioriAppOData: mockGenerateFioriAppOData,
-    generateFioriAppCap: mockGenerateFioriAppCap
+    generateFioriAppCap: mockGenerateFioriAppCap,
+    generateAdaptationProject: mockGenerateAdaptationProject,
+    openAdaptationEditor: mockOpenAdaptationEditor,
+    adpControllerExtension: mockAdpControllerExtension,
+    runRtaWorkflowStep: mockRunRtaWorkflowStep
 }));
 
 // Dynamic imports after mocks
@@ -73,6 +81,10 @@ describe('FioriFunctionalityServer', () => {
         mockDownloadODataServiceMetadata.mockReset();
         mockGenerateFioriAppOData.mockReset();
         mockGenerateFioriAppCap.mockReset();
+        mockGenerateAdaptationProject.mockReset();
+        mockOpenAdaptationEditor.mockReset();
+        mockAdpControllerExtension.mockReset();
+        mockRunRtaWorkflowStep.mockReset();
     });
 
     // version cannot be hard coded as it will update on each new patch update
@@ -100,6 +112,10 @@ describe('FioriFunctionalityServer', () => {
             'download_odata_service_metadata',
             'generate_fiori_app_odata',
             'generate_fiori_app_cap',
+            'generate_adaptation_project',
+            'open_adaptation_editor',
+            'adp_controller_extension',
+            'run_rta_workflow_step',
             'list_functionality',
             'get_functionality_details',
             'execute_functionality'
@@ -349,6 +365,10 @@ describe('FioriFunctionalityServer', () => {
                 'download_odata_service_metadata',
                 'generate_fiori_app_odata',
                 'generate_fiori_app_cap',
+                'generate_adaptation_project',
+                'open_adaptation_editor',
+                'adp_controller_extension',
+                'run_rta_workflow_step',
                 'list_functionality',
                 'get_functionality_details',
                 'execute_functionality'
@@ -597,6 +617,100 @@ describe('FioriFunctionalityServer', () => {
             );
         });
 
+        test('generate_adaptation_project', async () => {
+            const mockResult = {
+                status: 'Success',
+                message: 'Adaptation project generated.',
+                parameters: {},
+                appPath: '/project/adapt',
+                changes: [],
+                timestamp: '2024-01-01T00:00:00.000Z'
+            };
+            mockGenerateAdaptationProject.mockResolvedValue(mockResult);
+            new FioriFunctionalityServer();
+            const onRequestCB = setRequestHandlerMock.mock.calls[2][1];
+            const result = await onRequestCB({
+                params: {
+                    name: 'generate_adaptation_project',
+                    arguments: { appPath: '/project/adapt' }
+                }
+            });
+            expect(mockGenerateAdaptationProject).toHaveBeenCalledTimes(1);
+            expect(result.structuredContent).toEqual(mockResult);
+            expect(sendTelemetryMock).toHaveBeenLastCalledWith(
+                'generate_adaptation_project',
+                {
+                    tool: 'generate_adaptation_project',
+                    mcpClientName: 'unknown-client',
+                    mcpClientVersion: 'unknown-version'
+                },
+                '/project/adapt'
+            );
+        });
+
+        test('open_adaptation_editor', async () => {
+            const mockResult = {
+                status: 'Success',
+                message: 'Adaptation editor opened.',
+                parameters: {},
+                appPath: '/project/adapt',
+                changes: [],
+                timestamp: '2024-01-01T00:00:00.000Z'
+            };
+            mockOpenAdaptationEditor.mockResolvedValue(mockResult);
+            new FioriFunctionalityServer();
+            const onRequestCB = setRequestHandlerMock.mock.calls[2][1];
+            const result = await onRequestCB({
+                params: {
+                    name: 'open_adaptation_editor',
+                    arguments: { appPath: '/project/adapt' }
+                }
+            });
+            expect(mockOpenAdaptationEditor).toHaveBeenCalledTimes(1);
+            expect(result.structuredContent).toEqual(mockResult);
+            expect(sendTelemetryMock).toHaveBeenLastCalledWith(
+                'open_adaptation_editor',
+                {
+                    tool: 'open_adaptation_editor',
+                    mcpClientName: 'unknown-client',
+                    mcpClientVersion: 'unknown-version'
+                },
+                '/project/adapt'
+            );
+        });
+
+        test('adp_controller_extension', async () => {
+            const mockResult = {
+                status: 'success',
+                message: 'Controller extension created.',
+                functionalityId: 'adp-controller-extension',
+                parameters: { appPath: '/project/adapt' },
+                appPath: '/project/adapt',
+                changes: ['Created webapp/changes/coding/MyExt.js'],
+                timestamp: '2024-01-01T00:00:00.000Z'
+            };
+            mockAdpControllerExtension.mockResolvedValue(mockResult);
+            new FioriFunctionalityServer();
+            const onRequestCB = setRequestHandlerMock.mock.calls[2][1];
+            const result = await onRequestCB({
+                params: {
+                    name: 'adp_controller_extension',
+                    arguments: { appPath: '/project/adapt', prompt: 'add a button' }
+                }
+            });
+            expect(mockAdpControllerExtension).toHaveBeenCalledTimes(1);
+            expect(result.structuredContent).toEqual(mockResult);
+            expect(sendTelemetryMock).toHaveBeenLastCalledWith(
+                'adp_controller_extension',
+                {
+                    tool: 'adp_controller_extension',
+                    mcpClientName: 'unknown-client',
+                    mcpClientVersion: 'unknown-version'
+                },
+                '/project/adapt'
+            );
+        });
+
         test('list_functionality', async () => {
             mockListFunctionalities.mockResolvedValue({
                 applicationPath: 'app1',
@@ -755,6 +869,50 @@ describe('FioriFunctionalityServer', () => {
             );
         });
 
+        test('search_docs', async () => {
+            const mockResult = { results: [] };
+            mockDocSearch.mockResolvedValue(mockResult);
+            new FioriFunctionalityServer();
+            const onRequestCB = setRequestHandlerMock.mock.calls[2][1];
+            const result = await onRequestCB({
+                params: {
+                    name: 'search_docs',
+                    arguments: { query: 'table' }
+                }
+            });
+            expect(mockDocSearch).toHaveBeenCalledTimes(1);
+            expect(result.structuredContent).toEqual(mockResult);
+        });
+
+        test('run_rta_workflow_step', async () => {
+            const mockResult = { sessionId: 'abc', rtaStarted: true };
+            mockRunRtaWorkflowStep.mockResolvedValue(mockResult);
+            new FioriFunctionalityServer();
+            const onRequestCB = setRequestHandlerMock.mock.calls[2][1];
+            const result = await onRequestCB({
+                params: {
+                    name: 'run_rta_workflow_step',
+                    arguments: { step: 'start', payload: { site: 'http://localhost' } }
+                }
+            });
+            expect(mockRunRtaWorkflowStep).toHaveBeenCalledTimes(1);
+            expect(result.structuredContent).toEqual(mockResult);
+        });
+
+        test('string result returns plain text content without structuredContent', async () => {
+            mockDocSearch.mockResolvedValue('plain text result');
+            new FioriFunctionalityServer();
+            const onRequestCB = setRequestHandlerMock.mock.calls[2][1];
+            const result = await onRequestCB({
+                params: {
+                    name: 'search_docs',
+                    arguments: { query: 'anything' }
+                }
+            });
+            expect(result.content[0].text).toBe('plain text result');
+            expect(result.structuredContent).toBeUndefined();
+        });
+
         test('Unknown tool', async () => {
             // eslint-disable-next-line no-new
             new FioriFunctionalityServer();
@@ -770,7 +928,7 @@ describe('FioriFunctionalityServer', () => {
             });
             expect(result.content).toEqual([
                 {
-                    text: 'Error: Unknown tool: unknown-tool-id. Try one of: search_docs, list_fiori_apps, list_sap_systems, download_odata_service_metadata, generate_fiori_app_odata, generate_fiori_app_cap, list_functionality, get_functionality_details, execute_functionality.',
+                    text: 'Error: Unknown tool: unknown-tool-id. Try one of: search_docs, list_fiori_apps, list_sap_systems, download_odata_service_metadata, generate_fiori_app_odata, generate_fiori_app_cap, generate_adaptation_project, open_adaptation_editor, adp_controller_extension, run_rta_workflow_step, list_functionality, get_functionality_details, execute_functionality.',
                     type: 'text'
                 }
             ]);
@@ -791,7 +949,7 @@ describe('FioriFunctionalityServer', () => {
             });
             expect(result.content).toEqual([
                 {
-                    text: 'Error: Unknown tool: unknown-tool-id2. Try one of: search_docs, list_fiori_apps, list_sap_systems, download_odata_service_metadata, generate_fiori_app_odata, generate_fiori_app_cap, list_functionality, get_functionality_details, execute_functionality.',
+                    text: 'Error: Unknown tool: unknown-tool-id2. Try one of: search_docs, list_fiori_apps, list_sap_systems, download_odata_service_metadata, generate_fiori_app_odata, generate_fiori_app_cap, generate_adaptation_project, open_adaptation_editor, adp_controller_extension, run_rta_workflow_step, list_functionality, get_functionality_details, execute_functionality.',
                     type: 'text'
                 }
             ]);
@@ -813,7 +971,7 @@ describe('FioriFunctionalityServer', () => {
             });
             expect(result.content).toEqual([
                 {
-                    text: 'Error: Unknown tool: unknown-tool-id2. Try one of: search_docs, list_fiori_apps, list_sap_systems, download_odata_service_metadata, generate_fiori_app_odata, generate_fiori_app_cap, list_functionality, get_functionality_details, execute_functionality.',
+                    text: 'Error: Unknown tool: unknown-tool-id2. Try one of: search_docs, list_fiori_apps, list_sap_systems, download_odata_service_metadata, generate_fiori_app_odata, generate_fiori_app_cap, generate_adaptation_project, open_adaptation_editor, adp_controller_extension, run_rta_workflow_step, list_functionality, get_functionality_details, execute_functionality.',
                     type: 'text'
                 }
             ]);
diff --git a/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/ai-response/parser.test.ts b/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/ai-response/parser.test.ts
new file mode 100644
index 00000000000..a0f1c887c47
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/ai-response/parser.test.ts
@@ -0,0 +1,112 @@
+import {
+    extractFilesFromResponse,
+    isChangeFile
+} from '../../../../../src/tools/adp-controller-extension/ai-response/parser.js';
+
+describe('extractFilesFromResponse', () => {
+    test('extracts a single file with a path marker and code fence', () => {
+        const content = [
+            '**Path:** webapp/changes/coding/MyExt.js',
+            '```javascript',
+            'sap.ui.define([], function () {});',
+            '```'
+        ].join('\n');
+
+        expect(extractFilesFromResponse(content)).toEqual([
+            { path: 'webapp/changes/coding/MyExt.js', code: 'sap.ui.define([], function () {});' }
+        ]);
+    });
+
+    test('extracts multiple files separated by prose', () => {
+        const content = [
+            '**Path:** webapp/changes/coding/A.js',
+            '```javascript',
+            'console.log("a");',
+            '```',
+            '',
+            'Some explanation.',
+            '',
+            '**Path:** webapp/changes/fragment/B.fragment.xml',
+            '```xml',
+            '<core:FragmentDefinition/>',
+            '```'
+        ].join('\n');
+
+        const result = extractFilesFromResponse(content);
+        expect(result).toHaveLength(2);
+        expect(result[0].path).toBe('webapp/changes/coding/A.js');
+        expect(result[1].path).toBe('webapp/changes/fragment/B.fragment.xml');
+    });
+
+    test('drops a code block without a preceding path marker', () => {
+        const content = ['```javascript', 'orphan();', '```'].join('\n');
+        expect(extractFilesFromResponse(content)).toEqual([]);
+    });
+
+    test('drops empty code blocks', () => {
+        const content = ['**Path:** webapp/empty.js', '```javascript', '   ', '```'].join('\n');
+        expect(extractFilesFromResponse(content)).toEqual([]);
+    });
+
+    test('handles fences without language hints', () => {
+        const content = ['**Path:** webapp/changes/coding/X.js', '```', 'code();', '```'].join('\n');
+        expect(extractFilesFromResponse(content)).toEqual([{ path: 'webapp/changes/coding/X.js', code: 'code();' }]);
+    });
+
+    test('returns an empty array for prose-only input', () => {
+        expect(extractFilesFromResponse('Just some explanation, no code.')).toEqual([]);
+    });
+
+    test('does not close block on a language-tagged fence inside a code block', () => {
+        const content = [
+            '**Path:** webapp/changes/coding/MyExt.js',
+            '```javascript',
+            '// Example:',
+            '// ```xml',
+            '// <Button/>',
+            '// ```',
+            'sap.ui.define([], function () {});',
+            '```'
+        ].join('\n');
+
+        const result = extractFilesFromResponse(content);
+        expect(result).toHaveLength(1);
+        expect(result[0].code).toContain('sap.ui.define');
+        expect(result[0].code).toContain('```xml');
+    });
+
+    test('ignores a Path marker that appears inside a code block', () => {
+        const content = [
+            '**Path:** webapp/changes/coding/Real.js',
+            '```javascript',
+            '// **Path:** webapp/changes/coding/Fake.js',
+            'real();',
+            '```'
+        ].join('\n');
+
+        const result = extractFilesFromResponse(content);
+        expect(result).toHaveLength(1);
+        expect(result[0].path).toBe('webapp/changes/coding/Real.js');
+        expect(result[0].code).toContain('real()');
+    });
+
+    test('returns empty array and warns when code block is unclosed at EOF', () => {
+        const content = ['**Path:** webapp/changes/coding/MyExt.js', '```javascript', 'sap.ui.define(['].join('\n');
+
+        const result = extractFilesFromResponse(content);
+        expect(result).toEqual([]);
+    });
+});
+
+describe('isChangeFile', () => {
+    test.each([
+        ['id_addCustomItem.change', true],
+        ['nested/path/foo.change', true],
+        ['CASE.CHANGE', true],
+        ['MyExt.js', false],
+        ['fragment.xml', false],
+        ['', false]
+    ])('isChangeFile(%s) === %s', (input, expected) => {
+        expect(isChangeFile(input)).toBe(expected);
+    });
+});
diff --git a/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/ai-response/writer.test.ts b/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/ai-response/writer.test.ts
new file mode 100644
index 00000000000..e018c70f071
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/ai-response/writer.test.ts
@@ -0,0 +1,72 @@
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, sep } from 'node:path';
+import {
+    PathTraversalError,
+    resolveWithinAppPath,
+    writeExtractedFile
+} from '../../../../../src/tools/adp-controller-extension/ai-response/writer.js';
+
+describe('ai-response/writer', () => {
+    let appPath: string;
+
+    beforeEach(() => {
+        appPath = mkdtempSync(join(tmpdir(), 'adp-writer-'));
+    });
+
+    afterEach(() => {
+        rmSync(appPath, { recursive: true, force: true });
+    });
+
+    describe('resolveWithinAppPath', () => {
+        test('accepts a relative path inside the project', () => {
+            expect(resolveWithinAppPath(appPath, 'webapp/changes/coding/A.js')).toBe(
+                ['webapp', 'changes', 'coding', 'A.js'].join(sep)
+            );
+        });
+
+        test('accepts an absolute path inside the project', () => {
+            const inside = join(appPath, 'webapp', 'changes', 'coding', 'A.js');
+            expect(resolveWithinAppPath(appPath, inside)).toBe(['webapp', 'changes', 'coding', 'A.js'].join(sep));
+        });
+
+        test('normalises backslashes', () => {
+            expect(resolveWithinAppPath(appPath, 'webapp\\changes\\coding\\A.js')).toBe(
+                ['webapp', 'changes', 'coding', 'A.js'].join(sep)
+            );
+        });
+
+        test('rejects an absolute path outside the project', () => {
+            expect(() => resolveWithinAppPath(appPath, '/etc/passwd')).toThrow(PathTraversalError);
+        });
+
+        test('rejects a relative path that escapes via ..', () => {
+            expect(() => resolveWithinAppPath(appPath, '../../etc/passwd')).toThrow(PathTraversalError);
+        });
+
+        test('rejects a sibling directory sharing the same prefix', () => {
+            const sibling = `${appPath}-sibling/file.js`;
+            expect(() => resolveWithinAppPath(appPath, sibling)).toThrow(PathTraversalError);
+        });
+    });
+
+    describe('writeExtractedFile', () => {
+        test('writes a file and creates parent directories', async () => {
+            const written = await writeExtractedFile(appPath, {
+                path: 'webapp/changes/coding/MyExt.js',
+                code: '// hello'
+            });
+
+            expect(written).toBe(['webapp', 'changes', 'coding', 'MyExt.js'].join(sep));
+            const writtenPath = join(appPath, 'webapp', 'changes', 'coding', 'MyExt.js');
+            expect(existsSync(writtenPath)).toBe(true);
+            expect(readFileSync(writtenPath, 'utf-8')).toBe('// hello');
+        });
+
+        test('rejects a write that escapes the project root', async () => {
+            await expect(
+                writeExtractedFile(appPath, { path: '../../escaped.js', code: '// nope' })
+            ).rejects.toBeInstanceOf(PathTraversalError);
+        });
+    });
+});
diff --git a/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/project/scanner.test.ts b/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/project/scanner.test.ts
new file mode 100644
index 00000000000..a2830adb28c
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/project/scanner.test.ts
@@ -0,0 +1,62 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { scanExistingProjectFiles } from '../../../../../src/tools/adp-controller-extension/project/scanner.js';
+import { MAX_SCANNED_FILE_SIZE } from '../../../../../src/tools/adp-controller-extension/constants.js';
+
+describe('project/scanner', () => {
+    let appPath: string;
+    let changesDir: string;
+
+    beforeEach(() => {
+        appPath = mkdtempSync(join(tmpdir(), 'adp-scanner-'));
+        changesDir = join(appPath, 'webapp', 'changes');
+        mkdirSync(changesDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        rmSync(appPath, { recursive: true, force: true });
+    });
+
+    test('returns an empty array when webapp/changes does not exist', async () => {
+        const empty = mkdtempSync(join(tmpdir(), 'adp-scanner-empty-'));
+        try {
+            expect(await scanExistingProjectFiles(empty)).toEqual([]);
+        } finally {
+            rmSync(empty, { recursive: true, force: true });
+        }
+    });
+
+    test('collects files with scannable extensions and skips others', async () => {
+        const codingDir = join(changesDir, 'coding');
+        mkdirSync(codingDir, { recursive: true });
+        writeFileSync(join(codingDir, 'A.js'), '// js');
+        writeFileSync(join(codingDir, 'B.ts'), '// ts');
+        writeFileSync(join(codingDir, 'C.xml'), '<x/>');
+        writeFileSync(join(codingDir, 'D.json'), '{}');
+        writeFileSync(join(codingDir, 'E.md'), 'skip me');
+        writeFileSync(join(changesDir, 'foo.change'), '{}');
+
+        const files = await scanExistingProjectFiles(appPath);
+        const names = files.map((f) => f.relativePath).sort();
+
+        expect(names).toEqual([
+            join('webapp', 'changes', 'coding', 'A.js'),
+            join('webapp', 'changes', 'coding', 'B.ts'),
+            join('webapp', 'changes', 'coding', 'C.xml'),
+            join('webapp', 'changes', 'coding', 'D.json')
+        ]);
+    });
+
+    test('skips files larger than MAX_SCANNED_FILE_SIZE', async () => {
+        const big = 'x'.repeat(MAX_SCANNED_FILE_SIZE + 1);
+        writeFileSync(join(changesDir, 'big.js'), big);
+        writeFileSync(join(changesDir, 'small.js'), 'tiny');
+
+        const files = await scanExistingProjectFiles(appPath);
+        const names = files.map((f) => f.relativePath);
+
+        expect(names).toContain(join('webapp', 'changes', 'small.js'));
+        expect(names).not.toContain(join('webapp', 'changes', 'big.js'));
+    });
+});
diff --git a/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/tool.test.ts b/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/tool.test.ts
new file mode 100644
index 00000000000..9331bcff415
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/adp-controller-extension/tool.test.ts
@@ -0,0 +1,199 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+jest.mock('@sap-ux/adp-tooling', () => ({
+    getVariant: jest.fn()
+}));
+
+import { getVariant } from '@sap-ux/adp-tooling';
+import { adpControllerExtension } from '../../../../src/tools/adp-controller-extension/tool.js';
+import { ADP_CONTROLLER_EXTENSION_FUNCTIONALITY_ID } from '../../../../src/constant.js';
+
+const mockedGetVariant = getVariant as jest.MockedFunction<typeof getVariant>;
+
+function createAdpProject(layer: string = 'CUSTOMER_BASE'): string {
+    const appPath = mkdtempSync(join(tmpdir(), 'adp-tool-'));
+    mockedGetVariant.mockResolvedValue({
+        layer,
+        reference: 'sap.ui.demoapps',
+        id: 'customer.adapt.demo',
+        namespace: 'apps/customer.adapt.demo',
+        content: []
+    } as never);
+    return appPath;
+}
+
+describe('adpControllerExtension', () => {
+    afterEach(() => {
+        mockedGetVariant.mockReset();
+    });
+
+    test('returns info envelope when appPath is missing', async () => {
+        const result = await adpControllerExtension({ appPath: '' } as never);
+        expect(result.status).toBe('info');
+        expect(result.functionalityId).toBe(ADP_CONTROLLER_EXTENSION_FUNCTIONALITY_ID);
+        expect(result.message).toContain('Missing required parameter: appPath');
+    });
+
+    test('returns error envelope when getVariant fails', async () => {
+        const appPath = mkdtempSync(join(tmpdir(), 'adp-tool-err-'));
+        mockedGetVariant.mockRejectedValueOnce(new Error('boom'));
+
+        try {
+            const result = await adpControllerExtension({ appPath });
+            expect(result.status).toBe('error');
+            expect(result.message).toContain('Failed to read manifest.appdescr_variant');
+            expect(result.message).toContain('boom');
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('returns knowledge base + project context when no aiResponse is provided', async () => {
+        const appPath = createAdpProject('CUSTOMER_BASE');
+        try {
+            const result = await adpControllerExtension({ appPath, prompt: 'add a button' });
+            expect(result.status).toBe('info');
+            expect(result.message).toContain('Prompt received: "add a button"');
+            expect(result.message).toContain('Layer: CUSTOMER_BASE');
+            expect(result.message).toContain('Customer prefix required: YES');
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('handles variant with undefined layer and id gracefully', async () => {
+        const appPath = mkdtempSync(join(tmpdir(), 'adp-tool-null-'));
+        mockedGetVariant.mockResolvedValue({ layer: undefined, id: undefined, content: [] } as never);
+        try {
+            const result = await adpControllerExtension({ appPath, prompt: 'test' });
+            expect(result.status).toBe('info');
+            expect(result.message).toContain('Layer: ');
+            expect(result.message).toContain('Variant ID: ');
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('writes extracted files when aiResponse is provided', async () => {
+        const appPath = createAdpProject('VENDOR');
+        const aiResponse = [
+            '**Path:** webapp/changes/coding/MyExt.js',
+            '```javascript',
+            '// extension',
+            '```',
+            '',
+            '**Path:** webapp/changes/fragments/Foo.fragment.xml',
+            '```xml',
+            '<x/>',
+            '```'
+        ].join('\n');
+
+        try {
+            const result = await adpControllerExtension({ appPath, aiResponse });
+            expect(result.status).toBe('success');
+            expect(result.changes).toHaveLength(2);
+            expect(existsSync(join(appPath, 'webapp', 'changes', 'coding', 'MyExt.js'))).toBe(true);
+            expect(readFileSync(join(appPath, 'webapp', 'changes', 'coding', 'MyExt.js'), 'utf-8')).toBe(
+                '// extension'
+            );
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('skips .change files emitted alongside code files', async () => {
+        const appPath = createAdpProject();
+        const aiResponse = [
+            '**Path:** webapp/changes/coding/MyExt.js',
+            '```javascript',
+            '// real',
+            '```',
+            '',
+            '**Path:** webapp/changes/foo.change',
+            '```json',
+            '{ "changeType": "x" }',
+            '```'
+        ].join('\n');
+
+        try {
+            const result = await adpControllerExtension({ appPath, aiResponse });
+            expect(result.status).toBe('success');
+            expect(result.changes).toHaveLength(1);
+            expect(existsSync(join(appPath, 'webapp', 'changes', 'foo.change'))).toBe(false);
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('returns skipped envelope when aiResponse contains no extractable files', async () => {
+        const appPath = createAdpProject();
+        try {
+            const result = await adpControllerExtension({ appPath, aiResponse: 'just prose, no fences' });
+            expect(result.status).toBe('skipped');
+            expect(result.changes).toEqual([]);
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('returns error envelope and stops on path traversal attempt', async () => {
+        const appPath = createAdpProject();
+        const aiResponse = ['**Path:** ../../escaped.js', '```javascript', '// nope', '```'].join('\n');
+
+        try {
+            const result = await adpControllerExtension({ appPath, aiResponse });
+            expect(result.status).toBe('error');
+            expect(result.message).toContain('outside the application path');
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('strips aiResponse from the parameters echoed back to the caller', async () => {
+        const appPath = createAdpProject();
+        const aiResponse = ['**Path:** webapp/changes/coding/MyExt.js', '```js', '// x', '```'].join('\n');
+
+        try {
+            const result = await adpControllerExtension({ appPath, aiResponse, prompt: 'p' });
+            expect(result.status).toBe('success');
+            expect(result.parameters).toEqual({ appPath, prompt: 'p' });
+            expect(JSON.stringify(result.parameters)).not.toContain('Path:');
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('includes existing files in knowledge base response when webapp/changes has content', async () => {
+        const appPath = createAdpProject('CUSTOMER_BASE');
+        const codingDir = join(appPath, 'webapp', 'changes', 'coding');
+        mkdirSync(codingDir, { recursive: true });
+        writeFileSync(join(codingDir, 'MyExt.js'), '// existing extension', 'utf-8');
+
+        try {
+            const result = await adpControllerExtension({ appPath, prompt: 'test' });
+            expect(result.status).toBe('info');
+            expect(result.message).toContain('EXISTING PROJECT FILES');
+            expect(result.message).toContain('MyExt.js');
+        } finally {
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+
+    test('returns error with Failed to write file when writeFile throws a generic error', async () => {
+        const appPath = createAdpProject();
+        const aiResponse = ['**Path:** webapp/changes/coding/MyExt.js', '```javascript', '// code', '```'].join('\n');
+        const fsMock = await import('node:fs');
+        const writeFileSpy = jest.spyOn(fsMock.promises, 'writeFile').mockRejectedValueOnce(new Error('disk full'));
+
+        try {
+            const result = await adpControllerExtension({ appPath, aiResponse });
+            expect(result.status).toBe('error');
+            expect(result.message).toContain('Failed to write file');
+        } finally {
+            writeFileSpy.mockRestore();
+            rmSync(appPath, { recursive: true, force: true });
+        }
+    });
+});
diff --git a/packages/fiori-mcp-server/test/unit/tools/generate-adaptation-project.test.ts b/packages/fiori-mcp-server/test/unit/tools/generate-adaptation-project.test.ts
new file mode 100644
index 00000000000..092bdf8369e
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/generate-adaptation-project.test.ts
@@ -0,0 +1,175 @@
+import { jest } from '@jest/globals';
+
+const mockRunCmd = jest.fn<() => Promise<{ stdout: string; stderr: string }>>();
+const mockExistsSync = jest.fn<(path: string) => boolean>();
+const mockMkdir = jest.fn<() => Promise<void>>().mockResolvedValue(undefined);
+
+const actualUtils = await import('../../../src/utils/index.js');
+jest.unstable_mockModule('../../../src/utils/index.js', () => ({
+    ...actualUtils,
+    runCmd: mockRunCmd
+}));
+
+const actualFs = await import('node:fs');
+jest.unstable_mockModule('node:fs', () => ({
+    ...actualFs,
+    default: {
+        ...actualFs,
+        existsSync: mockExistsSync,
+        promises: { ...(actualFs.promises ?? {}), mkdir: mockMkdir }
+    },
+    existsSync: mockExistsSync,
+    promises: { ...(actualFs.promises ?? {}), mkdir: mockMkdir }
+}));
+
+const { generateAdaptationProject } = await import('../../../src/tools/generate-adaptation-project.js');
+const { GENERATE_ADAPTATION_PROJECT_ID } = await import('../../../src/constant.js');
+
+describe('generateAdaptationProject', () => {
+    const baseParams = {
+        system: 'MY_SYSTEM',
+        application: 'sap.ui.demoapps.rta.fe',
+        appPath: '/workspace/projects',
+        targetFolder: '/workspace/projects',
+        username: 'admin',
+        password: 's3cr3t'
+    };
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockExistsSync.mockReturnValue(false);
+        mockRunCmd.mockResolvedValue({ stdout: 'Done', stderr: '' });
+    });
+
+    test('returns Error when system is missing', async () => {
+        const result = await generateAdaptationProject({ ...baseParams, system: '' });
+        expect(result.status).toBe('Error');
+        expect(result.message).toContain('Missing required parameters');
+        expect(result.functionalityId).toBe(GENERATE_ADAPTATION_PROJECT_ID);
+    });
+
+    test('returns Error when application is missing', async () => {
+        const result = await generateAdaptationProject({ ...baseParams, application: '' });
+        expect(result.status).toBe('Error');
+        expect(result.functionalityId).toBe(GENERATE_ADAPTATION_PROJECT_ID);
+    });
+
+    test('strips password from parameters on validation error', async () => {
+        const result = await generateAdaptationProject({ ...baseParams, system: '' });
+        expect(result.parameters).not.toHaveProperty('password');
+        expect((result.parameters as Record<string, unknown>).username).toBe('admin');
+    });
+
+    test('returns Success when runCmd succeeds', async () => {
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.status).toBe('Success');
+        expect(result.functionalityId).toBe(GENERATE_ADAPTATION_PROJECT_ID);
+    });
+
+    test('appPath on success envelope points to generated project folder', async () => {
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.appPath).toContain('app.variant');
+    });
+
+    test('message on success contains project path', async () => {
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.message).toContain('app.variant');
+        expect(result.message).toContain('generated successfully');
+    });
+
+    test('strips password from parameters on success', async () => {
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.parameters).not.toHaveProperty('password');
+    });
+
+    test('invokes yo command', async () => {
+        await generateAdaptationProject(baseParams);
+        const [command] = mockRunCmd.mock.calls[0] as [string, unknown];
+        expect(command).toContain('yo@4');
+        expect(command).toContain('@sap-ux/adp');
+    });
+
+    test('logs stderr when runCmd returns stderr output', async () => {
+        mockRunCmd.mockResolvedValue({ stdout: 'Done', stderr: 'some warning' });
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.status).toBe('Success');
+    });
+
+    test('uses explicitly supplied projectName', async () => {
+        const result = await generateAdaptationProject({ ...baseParams, projectName: 'my.custom.variant' });
+        expect(result.appPath).toContain('my.custom.variant');
+    });
+
+    test('includes optional fields namespace, applicationTitle, client, username in yo command input', async () => {
+        const params = {
+            ...baseParams,
+            namespace: 'customer.ns',
+            applicationTitle: 'My App',
+            client: '100',
+            username: 'admin'
+        };
+        await generateAdaptationProject(params);
+        const [command] = mockRunCmd.mock.calls[0] as [string, unknown];
+        expect(command).toContain('customer.ns');
+        expect(command).toContain('My App');
+        expect(command).toContain('"client":"100"');
+        expect(command).toContain('"username":"admin"');
+    });
+
+    test('falls back to appPath when targetFolder is not provided', async () => {
+        const { targetFolder: _tf, ...params } = baseParams;
+        const result = await generateAdaptationProject({ ...params, appPath: '/fallback/dir' });
+        expect(result.appPath).toContain('fallback');
+    });
+
+    test('returns Error when runCmd throws', async () => {
+        mockRunCmd.mockRejectedValue(new Error('Generator crashed'));
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.status).toBe('Error');
+        expect(result.message).toContain('Generator crashed');
+    });
+
+    test('strips password from parameters on runCmd error', async () => {
+        mockRunCmd.mockRejectedValue(new Error('crash'));
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.parameters).not.toHaveProperty('password');
+    });
+
+    test('preserves original appPath on runCmd error', async () => {
+        mockRunCmd.mockRejectedValue(new Error('crash'));
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.appPath).toBe(baseParams.appPath);
+    });
+});
+
+describe('getDefaultProjectName (via generateAdaptationProject)', () => {
+    const baseParams = {
+        system: 'MY_SYSTEM',
+        application: 'sap.ui.demoapps',
+        appPath: '/workspace',
+        targetFolder: '/workspace'
+    };
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockRunCmd.mockResolvedValue({ stdout: '', stderr: '' });
+    });
+
+    test('returns "app.variant" when directory does not exist', async () => {
+        mockExistsSync.mockReturnValue(false);
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.appPath).toMatch(/app\.variant$/);
+    });
+
+    test('returns "app.variant1" when "app.variant" already exists', async () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('app.variant'));
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.appPath).toMatch(/app\.variant1$/);
+    });
+
+    test('returns "app.variant2" when "app.variant" and "app.variant1" already exist', async () => {
+        mockExistsSync.mockImplementation((p: string) => p.endsWith('app.variant') || p.endsWith('app.variant1'));
+        const result = await generateAdaptationProject(baseParams);
+        expect(result.appPath).toMatch(/app\.variant2$/);
+    });
+});
diff --git a/packages/fiori-mcp-server/test/unit/tools/generate-fiori-app-cap-impl.test.ts b/packages/fiori-mcp-server/test/unit/tools/generate-fiori-app-cap-impl.test.ts
deleted file mode 100644
index fbba7564f55..00000000000
--- a/packages/fiori-mcp-server/test/unit/tools/generate-fiori-app-cap-impl.test.ts
+++ /dev/null
@@ -1,210 +0,0 @@
-import { jest } from '@jest/globals';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { GeneratorConfigCAPWithAPI } from '../../../src/tools/schemas/index.js';
-import { existsSync, promises as fsPromises } from 'node:fs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-const mockFindInstalledPackages = jest.fn<any>().mockResolvedValue([
-    {
-        path: 'node_modules/@sap/generator-fiori',
-        packageJsonPath: 'node_modules/@sap/generator-fiori/package.json',
-        packageInfo: {
-            name: '@sap/generator-fiori',
-            version: '1.18.5'
-        }
-    }
-]);
-jest.unstable_mockModule('@sap-ux/nodejs-utils', () => ({
-    findInstalledPackages: mockFindInstalledPackages
-}));
-
-// Mock child_process.exec
-const mockExec = jest.fn<any>();
-const actualChildProcess = await import('node:child_process');
-jest.unstable_mockModule('child_process', () => ({
-    ...actualChildProcess,
-    exec: (...args: any) => mockExec(...args)
-}));
-jest.unstable_mockModule('node:child_process', () => ({
-    ...actualChildProcess,
-    exec: (...args: any) => mockExec(...args)
-}));
-
-const { generateFioriAppCap } = await import('../../../src/tools/generate-fiori-app-cap.js');
-
-// Read package.json for version
-const packageJsonModule = await import('../../../package.json', { with: { type: 'json' } });
-const packageJson = packageJsonModule.default;
-
-const testOutputDir = join(__dirname, '../../test-output/');
-
-const paramTest: GeneratorConfigCAPWithAPI = {
-    floorplan: 'FE_LROP',
-    version: '0.2',
-    project: {
-        name: 'app1',
-        targetFolder: join(testOutputDir, 'app1'),
-        title: 'App 1',
-        description: 'Description for App 1',
-        ui5Version: '1.136.7',
-        sapux: true
-    },
-    service: {
-        servicePath: 'odata/v4/cat-service/',
-        capService: {
-            projectPath: 'zzzapp1',
-            serviceName: 'app1',
-            serviceCdsPath: 'srv/cat-service.cds',
-            capType: 'Node.js' // optional
-        }
-    },
-    entityConfig: {
-        mainEntity: {
-            entityName: 'Travel'
-        },
-        generateFormAnnotations: true,
-        generateLROPAnnotations: true
-    },
-    telemetryData: {
-        generationSourceName: '@sap-ux/fiori-mcp-server',
-        generationSourceVersion: packageJson.version
-    }
-};
-
-const mockFileWrite = (cb: (content: string) => void) => {
-    const originalWriteFile = fsPromises.writeFile;
-    fsPromises.writeFile = jest.fn<any>().mockImplementation(async (path: string, content: string) => {
-        if (path.endsWith('generator-config.json')) {
-            cb(content);
-        }
-        return originalWriteFile(path, content);
-    });
-};
-
-describe('executeFunctionality', () => {
-    test('executeFunctionality - success', async () => {
-        let generatedConfigContent: string;
-        mockExec.mockImplementation((_cmd, _opts, callback) => {
-            callback(null, 'mock stdout', 'mock stderr');
-        });
-        // Mock fs.writeFile to capture the generated config
-        mockFileWrite((content) => {
-            generatedConfigContent = content;
-        });
-        const result = await generateFioriAppCap(paramTest);
-        expect(result).toMatchObject({
-            appPath: join(testOutputDir, 'app1/app/app1'),
-            changes: [],
-            message: `Generation completed successfully: ${join(
-                testOutputDir,
-                'app1/app/app1'
-            )}. You must run \`npm install\` in ${join(testOutputDir, 'app1')} before trying to run the application.`,
-            status: 'Success'
-        });
-        expect(existsSync(join(testOutputDir, 'app1', 'default-generator-config.json'))).toBeFalsy();
-        const config = JSON.parse(generatedConfigContent!);
-        expect(config).toEqual({
-            'entityConfig': {
-                'generateFormAnnotations': true,
-                'generateLROPAnnotations': true,
-                'mainEntity': {
-                    'entityName': 'Travel'
-                }
-            },
-            'floorplan': 'FE_LROP',
-            'project': {
-                'description': 'Description for App 1',
-                'name': 'app1',
-                'sapux': true,
-                'targetFolder': join(testOutputDir, 'app1'),
-                'title': 'App 1',
-                'ui5Version': '1.136.7'
-            },
-            'service': {
-                'servicePath': 'odata/v4/cat-service/',
-                'capService': {
-                    'capType': 'Node.js',
-                    'projectPath': 'zzzapp1',
-                    'serviceCdsPath': '/srv/cat-service.cds',
-                    'serviceName': 'app1'
-                }
-            },
-            'telemetryData': {
-                'generationSourceName': '@sap-ux/fiori-mcp-server',
-                'generationSourceVersion': packageJson.version
-            },
-            'version': '0.2'
-        });
-    });
-
-    test('executeFunctionality - success with floorplan="FF_SIMPLE"', async () => {
-        let generatedConfigContent: string;
-        mockExec.mockImplementation((_cmd, _opts, callback) => {
-            callback(null, 'mock stdout', 'mock stderr');
-        });
-        // Mock fs.writeFile to capture the generated config
-        mockFileWrite((content) => {
-            generatedConfigContent = content;
-        });
-        await generateFioriAppCap({
-            ...paramTest,
-            floorplan: 'FF_SIMPLE'
-        });
-        const config = JSON.parse(generatedConfigContent!);
-        expect(config.project.sapux).toEqual(false);
-    });
-
-    test('executeFunctionality - success with floorplan="FF_SIMPLE" without service (no data source)', async () => {
-        let generatedConfigContent: string;
-        mockExec.mockImplementation((_cmd, _opts, callback) => {
-            callback(null, 'mock stdout', 'mock stderr');
-        });
-        mockFileWrite((content) => {
-            generatedConfigContent = content;
-        });
-        const result = await generateFioriAppCap({
-            floorplan: 'FF_SIMPLE',
-            project: {
-                name: 'app1',
-                targetFolder: join(testOutputDir, 'app1'),
-                title: 'App 1',
-                description: 'Description for App 1',
-                ui5Version: '1.136.7',
-                sapux: true
-            }
-        });
-        expect(result.status).toBe('Success');
-        const config = JSON.parse(generatedConfigContent!);
-        expect(config.project.sapux).toEqual(false);
-        expect(config.service).toBeUndefined();
-        expect(config.entityConfig).toBeUndefined();
-    });
-
-    test('executeFunctionality - unsuccess', async () => {
-        mockExec.mockImplementation((cmd, opts, callback) => {
-            throw new Error('Dummy');
-        });
-        const result = await generateFioriAppCap(paramTest);
-        expect(result).toMatchObject({
-            appPath: join(testOutputDir, 'app1/app/app1'),
-            changes: [],
-            message: `Error generating application: Dummy`,
-            status: 'Error'
-        });
-        expect(existsSync(join(testOutputDir, 'app1', 'default-generator-config.json'))).toBeFalsy();
-    });
-
-    test('executeFunctionality - empty parameters', async () => {
-        await expect(generateFioriAppCap({} as any)).rejects.toThrow();
-    });
-
-    test('executeFunctionality - parameters as non object', async () => {
-        await expect(generateFioriAppCap('dummy' as any)).rejects.toThrow();
-    });
-
-    test('executeFunctionality called without parameters (unexpected in real use case)', async () => {
-        await expect(generateFioriAppCap(undefined as any)).rejects.toThrow();
-    });
-});
diff --git a/packages/fiori-mcp-server/test/unit/tools/generate-fiori-app-odata-impl.test.ts b/packages/fiori-mcp-server/test/unit/tools/generate-fiori-app-odata-impl.test.ts
deleted file mode 100644
index c7be668a7f9..00000000000
--- a/packages/fiori-mcp-server/test/unit/tools/generate-fiori-app-odata-impl.test.ts
+++ /dev/null
@@ -1,430 +0,0 @@
-import { jest } from '@jest/globals';
-
-// Mock dependencies BEFORE importing the module under test
-const mockReadFile = jest.fn<any>();
-const mockMkdir = jest.fn<any>();
-const mockWriteFile = jest.fn<any>();
-const mockUnlink = jest.fn<any>();
-const mockExistsSync = jest.fn<any>();
-const actualFs = await import('node:fs');
-jest.unstable_mockModule('node:fs', () => ({
-    ...actualFs,
-    default: {
-        ...actualFs,
-        existsSync: mockExistsSync,
-        promises: {
-            readFile: mockReadFile,
-            mkdir: mockMkdir,
-            writeFile: mockWriteFile,
-            unlink: mockUnlink
-        }
-    },
-    existsSync: mockExistsSync,
-    promises: {
-        readFile: mockReadFile,
-        mkdir: mockMkdir,
-        writeFile: mockWriteFile,
-        unlink: mockUnlink
-    }
-}));
-jest.unstable_mockModule('fs', () => ({
-    ...actualFs,
-    default: {
-        ...actualFs,
-        existsSync: mockExistsSync,
-        promises: {
-            readFile: mockReadFile,
-            mkdir: mockMkdir,
-            writeFile: mockWriteFile,
-            unlink: mockUnlink
-        }
-    },
-    existsSync: mockExistsSync,
-    promises: {
-        readFile: mockReadFile,
-        mkdir: mockMkdir,
-        writeFile: mockWriteFile,
-        unlink: mockUnlink
-    }
-}));
-
-// Import the mocked fs for test assertions
-const { promises: fsPromises } = await import('node:fs');
-
-// Mock utils
-const mockCheckIfGeneratorInstalled = jest.fn<any>();
-const mockRunCmd = jest.fn<any>();
-const mockValidateWithSchema = jest.fn<any>();
-const actualUtils = await import('../../../src/utils/index.js');
-jest.unstable_mockModule('../../../src/utils', () => ({
-    ...actualUtils,
-    checkIfGeneratorInstalled: mockCheckIfGeneratorInstalled,
-    runCmd: mockRunCmd,
-    validateWithSchema: mockValidateWithSchema,
-    getDefaultExtensionFolder: jest.fn()
-}));
-
-// Mock schemas so generatorConfigOData.parse() is a passthrough
-jest.unstable_mockModule('../../../src/tools/schemas/index', () => ({
-    generatorConfigOData: { parse: (v: unknown) => v },
-    generatorConfigCAP: { parse: (v: unknown) => v },
-    generatorConfigODataJson: {},
-    generatorConfigCAPJson: {},
-    PREDEFINED_GENERATOR_VALUES: { version: '0.2', telemetryData: {}, project: { sapux: true } }
-}));
-
-const { generateFioriAppOData } = await import('../../../src/tools/generate-fiori-app-odata.js');
-
-describe('generate-fiori-ui-application execute-functionality', () => {
-    const mockAppPath = '/test/project';
-    const mockMetadata = '<?xml version="1.0" encoding="utf-8"?><edmx:Edmx>...</edmx:Edmx>';
-
-    beforeEach(() => {
-        jest.clearAllMocks();
-        mockCheckIfGeneratorInstalled.mockResolvedValue(undefined);
-        mockRunCmd.mockResolvedValue({ stdout: 'Success', stderr: '' });
-        mockValidateWithSchema.mockImplementation((schema, data) => data.appGenConfig || data);
-        mockReadFile.mockResolvedValue(mockMetadata);
-        mockMkdir.mockResolvedValue(undefined);
-        mockWriteFile.mockResolvedValue(undefined);
-        mockUnlink.mockResolvedValue(undefined);
-        mockExistsSync.mockReturnValue(true);
-    });
-
-    test('should successfully generate application with valid parameters', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        const result = await generateFioriAppOData(args);
-
-        expect(result.status).toBe('Success');
-        expect(result.message).toContain('Generation completed successfully');
-        expect(result.appPath).toContain('testapp');
-        expect(mockCheckIfGeneratorInstalled).toHaveBeenCalled();
-        expect(mockRunCmd).toHaveBeenCalled();
-    });
-
-    test('should read metadata from file', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        expect(mockReadFile).toHaveBeenCalledWith(expect.stringContaining('metadata.xml'), {
-            encoding: 'utf8'
-        });
-    });
-
-    test('should use custom metadata file path if provided', async () => {
-        const customMetadataPath = '/custom/path/metadata.xml';
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com',
-                metadataFilePath: customMetadataPath
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        expect(mockReadFile).toHaveBeenCalledWith(customMetadataPath, { encoding: 'utf8' });
-    });
-
-    test('should write generator config file', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        expect(mockWriteFile).toHaveBeenCalledWith(
-            expect.stringContaining('-generator-config.json'),
-            expect.any(String),
-            { encoding: 'utf8' }
-        );
-    });
-
-    test('should run generator command with correct parameters', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        expect(mockRunCmd).toHaveBeenCalledWith(
-            expect.stringContaining('npx -y yo@4 @sap/fiori:headless'),
-            expect.objectContaining({ cwd: mockAppPath })
-        );
-    });
-
-    test('should clean up temporary files after generation', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        expect(mockUnlink).toHaveBeenCalledTimes(2);
-        expect(mockUnlink).toHaveBeenCalledWith(expect.stringContaining('-generator-config.json'));
-        expect(mockUnlink).toHaveBeenCalledWith(expect.stringContaining('metadata.xml'));
-    });
-
-    test('should throw error when projectPath is invalid', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp'
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-        mockValidateWithSchema.mockImplementation((schema, data) => data.appGenConfig || data);
-
-        await expect(generateFioriAppOData(args)).rejects.toThrow(
-            'Please provide a valid path to the non-CAP project folder.'
-        );
-    });
-
-    test('should return error status when generation fails', async () => {
-        mockReadFile.mockRejectedValue(new Error('File not found'));
-
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        const result = await generateFioriAppOData(args);
-
-        expect(result.status).toBe('Error');
-        expect(result.message).toContain('Error generating application');
-    });
-
-    test('should set sapux to false for FF_SIMPLE floorplan', async () => {
-        const args = {
-            floorplan: 'FF_SIMPLE',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        const writeCallArgs = mockWriteFile.mock.calls[0] as string[];
-        const configContent = JSON.parse(writeCallArgs[1] as string);
-        expect(configContent.project.sapux).toBe(false);
-    });
-
-    test('should succeed for FF_SIMPLE without service (no data source)', async () => {
-        const args = {
-            floorplan: 'FF_SIMPLE',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            }
-        };
-
-        const result = await generateFioriAppOData(args);
-
-        expect(result.status).toBe('Success');
-        expect(fsPromises.readFile as jest.Mock).not.toHaveBeenCalled();
-        const writeCallArgs = (fsPromises.writeFile as jest.Mock).mock.calls[0] as string[];
-        const configContent = JSON.parse(writeCallArgs[1] as string);
-        expect(configContent.project.sapux).toBe(false);
-        expect(configContent.service).toBeUndefined();
-    });
-
-    test('should only clean up metadata file when service is provided', async () => {
-        const args = {
-            floorplan: 'FF_SIMPLE',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        // Only config file should be cleaned up, not metadata (no service)
-        expect(fsPromises.unlink as jest.Mock).toHaveBeenCalledTimes(1);
-        expect(fsPromises.unlink as jest.Mock).toHaveBeenCalledWith(expect.stringContaining('-generator-config.json'));
-    });
-
-    test('should set sapux to true for non-FF_SIMPLE floorplan', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        const writeCallArgs = mockWriteFile.mock.calls[0] as string[];
-        const configContent = JSON.parse(writeCallArgs[1] as string);
-        expect(configContent.project.sapux).toBe(true);
-    });
-
-    test('should clean up files even when generation fails', async () => {
-        mockRunCmd.mockRejectedValue(new Error('Command failed'));
-
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        expect(mockUnlink).toHaveBeenCalledTimes(2);
-    });
-
-    test('should only clean up files that exist', async () => {
-        mockExistsSync.mockReturnValueOnce(false).mockReturnValueOnce(true);
-
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        expect(mockUnlink).toHaveBeenCalledTimes(1);
-    });
-
-    test('should return timestamp in ISO format', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        const result = await generateFioriAppOData(args);
-
-        expect(result.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
-    });
-
-    test('should strip wrapping single quotes from entityName', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                name: 'testapp',
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            },
-            entityConfig: {
-                mainEntity: { entityName: "'SalesOrder'" }
-            }
-        };
-
-        await generateFioriAppOData(args);
-
-        const writeCallArgs = mockWriteFile.mock.calls[0] as string[];
-        const configContent = JSON.parse(writeCallArgs[1] as string);
-        expect(configContent.entityConfig.mainEntity.entityName).toBe('SalesOrder');
-    });
-
-    test('should use default app name when not provided', async () => {
-        const args = {
-            floorplan: 'FE_LROP',
-            project: {
-                targetFolder: mockAppPath
-            },
-            service: {
-                servicePath: '/sap/opu/odata4/service',
-                url: 'https://test.example.com'
-            }
-        };
-
-        const result = await generateFioriAppOData(args);
-
-        expect(result.appPath).toContain('default');
-    });
-});
diff --git a/packages/fiori-mcp-server/test/unit/tools/open-adaptation-editor.test.ts b/packages/fiori-mcp-server/test/unit/tools/open-adaptation-editor.test.ts
new file mode 100644
index 00000000000..a3c8310e728
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/open-adaptation-editor.test.ts
@@ -0,0 +1,441 @@
+import { jest } from '@jest/globals';
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+import type { ChildProcess } from 'node:child_process';
+
+type FakeProcess = EventEmitter &
+    Pick<ChildProcess, 'pid' | 'unref'> & {
+        stdout: Readable;
+        stderr: Readable;
+    };
+
+type LineCallback = (line: string) => void;
+
+interface FakeRl {
+    lineCallbacks: LineCallback[];
+    closeCallbacks: Array<() => void>;
+    on(event: string, cb: LineCallback | (() => void)): FakeRl;
+    close(): void;
+    emitLine(line: string): void;
+    emitClose(): void;
+}
+
+function makeFakeRl(): FakeRl {
+    return {
+        lineCallbacks: [],
+        closeCallbacks: [],
+        on(event, cb) {
+            if (event === 'line') {
+                this.lineCallbacks.push(cb as LineCallback);
+            }
+            if (event === 'close') {
+                this.closeCallbacks.push(cb as () => void);
+            }
+            return this;
+        },
+        close() {
+            this.emitClose();
+        },
+        emitLine(line) {
+            for (const cb of this.lineCallbacks) {
+                cb(line);
+            }
+        },
+        emitClose() {
+            for (const cb of this.closeCallbacks) {
+                cb();
+            }
+        }
+    };
+}
+
+let currentStdoutRl: FakeRl | null = null;
+let rlCallCount = 0;
+
+jest.unstable_mockModule('node:readline', () => ({
+    createInterface: jest.fn((_opts: unknown) => {
+        rlCallCount++;
+        const rl = makeFakeRl();
+        if (rlCallCount % 2 === 1) {
+            currentStdoutRl = rl;
+        }
+        return rl;
+    })
+}));
+
+const mockSpawn = jest.fn<() => FakeProcess>();
+const mockExec =
+    jest.fn<(cmd: string, cb: (err: Error | null, result?: { stdout: string; stderr: string }) => void) => void>();
+
+jest.unstable_mockModule('node:child_process', () => ({
+    spawn: mockSpawn,
+    exec: mockExec
+}));
+
+const { openAdaptationEditor } = await import('../../../src/tools/open-adaptation-editor.js');
+const { OPEN_ADAPTATION_EDITOR_ID } = await import('../../../src/constant.js');
+const { createInterface: mockCreateInterface } = await import('node:readline');
+
+function makeFakeProcess(pid: number | undefined): FakeProcess {
+    const proc = new EventEmitter() as FakeProcess;
+    proc.stdout = new Readable({ read() {} });
+    proc.stderr = new Readable({ read() {} });
+    proc.pid = pid;
+    proc.unref = jest.fn<() => void>();
+    return proc;
+}
+
+async function tickMs(ms: number): Promise<void> {
+    jest.advanceTimersByTime(ms);
+    await Promise.resolve();
+    await Promise.resolve();
+}
+
+describe('openAdaptationEditor', () => {
+    const appParams = { appPath: '/workspace/my-adp-project' };
+
+    beforeEach(() => {
+        (mockCreateInterface as ReturnType<typeof jest.fn>).mockClear();
+        mockSpawn.mockReset();
+        mockExec.mockReset();
+        mockExec.mockImplementation((_cmd, cb) => cb(new Error('exec not configured')));
+        currentStdoutRl = null;
+        rlCallCount = 0;
+        jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    test('returns Error with spawn message when child process emits error', async () => {
+        const fakeProc = makeFakeProcess(12345);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor(appParams);
+        fakeProc.emit('error', new Error('ENOENT: npx not found'));
+        await tickMs(200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Error');
+        expect(result.message).toContain('Failed to spawn editor process');
+        expect(result.message).toContain('ENOENT: npx not found');
+        expect(result.functionalityId).toBe(OPEN_ADAPTATION_EDITOR_ID);
+    });
+
+    test('returns Error with Timeout message when 30s expires without URL', async () => {
+        const fakeProc = makeFakeProcess(12345);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor(appParams);
+        await tickMs(30000 + 200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Error');
+        expect(result.message).toContain('Timeout');
+        expect(result.functionalityId).toBe(OPEN_ADAPTATION_EDITOR_ID);
+    });
+
+    test('returns Error mentioning process ID when spawned process has no PID', async () => {
+        const fakeProc = makeFakeProcess(undefined);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor(appParams);
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:8080');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Error');
+        expect(result.message).toContain('process ID');
+        expect(result.functionalityId).toBe(OPEN_ADAPTATION_EDITOR_ID);
+    });
+
+    test('returns Success with editorUrl and processId when URL and path are emitted', async () => {
+        const fakeProc = makeFakeProcess(9999);
+        mockSpawn.mockReturnValue(fakeProc);
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: '', stderr: '' }));
+
+        const resultPromise = openAdaptationEditor(appParams);
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:8080');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Success');
+        expect(result.functionalityId).toBe(OPEN_ADAPTATION_EDITOR_ID);
+        expect(result.message).toContain('http://localhost:8080');
+        expect(result.message).toContain('/test/adaptation-editor.html');
+        const params = result.parameters as Record<string, unknown>;
+        expect(params.editorUrl).toBe('http://localhost:8080/test/adaptation-editor.html');
+        expect(params.processId).toBe(9999);
+    });
+
+    test('falls back to default editorPath when only URL line is emitted before timeout', async () => {
+        const fakeProc = makeFakeProcess(5555);
+        mockSpawn.mockReturnValue(fakeProc);
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: '', stderr: '' }));
+
+        const resultPromise = openAdaptationEditor(appParams);
+        currentStdoutRl!.emitLine('URL: http://localhost:3000');
+        await tickMs(30000 + 200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Success');
+        const params = result.parameters as Record<string, unknown>;
+        expect(params.editorUrl as string).toContain('/test/adaptation-editor.html');
+    });
+});
+
+describe('port detection via execAsync', () => {
+    beforeEach(() => {
+        mockExec.mockReset();
+        mockSpawn.mockReset();
+        jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    async function runSuccessAndGetPort(urlLine: string, execStdout: string): Promise<Record<string, unknown>> {
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: execStdout, stderr: '' }));
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine(urlLine);
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        return result.parameters as Record<string, unknown>;
+    }
+
+    test('detects port from lsof output on Unix', async () => {
+        const lsofOutput = 'node   1234  user  TCP *:8080 (LISTEN)';
+        const params = await runSuccessAndGetPort('URL: http://localhost:8080', lsofOutput);
+        expect(params.port).toBe(8080);
+    });
+
+    test('returns preferred port when lsof output is empty', async () => {
+        const params = await runSuccessAndGetPort('URL: http://localhost:4000', '');
+        expect(params.port).toBe(4000);
+    });
+
+    test('detects child pids via pgrep and scans them for ports', async () => {
+        let callCount = 0;
+        mockExec.mockImplementation((cmd, cb) => {
+            callCount++;
+            if ((cmd as string).includes('pgrep')) {
+                cb(null, { stdout: '5678\n', stderr: '' });
+            } else if ((cmd as string).includes('5678')) {
+                cb(null, { stdout: 'node   5678  user  TCP *:3000 (LISTEN)', stderr: '' });
+            } else {
+                cb(null, { stdout: '', stderr: '' });
+            }
+        });
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:3000');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        const params = result.parameters as Record<string, unknown>;
+        expect(params.port).toBe(3000);
+    });
+
+    test('handles pgrep failure gracefully and scans only the parent pid', async () => {
+        mockExec.mockImplementation((cmd, cb) => {
+            if ((cmd as string).includes('pgrep')) {
+                cb(new Error('pgrep not found'));
+            } else {
+                cb(null, { stdout: 'node   1234  user  TCP *:9090 (LISTEN)', stderr: '' });
+            }
+        });
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:9090');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        const params = result.parameters as Record<string, unknown>;
+        expect(params.port).toBe(9090);
+    });
+
+    test('skips COMMAND header line and non-matching lines in lsof output', async () => {
+        const lsofOutput = [
+            'COMMAND  PID USER   FD   TYPE',
+            'garbage line',
+            'node   1234  user  TCP *:7777 (LISTEN)'
+        ].join('\n');
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: lsofOutput, stderr: '' }));
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:7777');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        const params = result.parameters as Record<string, unknown>;
+        expect(params.port).toBe(7777);
+    });
+
+    test('detects port from netstat output on Windows', async () => {
+        const originalPlatform = process.platform;
+        Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+        const netstatOutput = 'TCP    0.0.0.0:8080    0.0.0.0    LISTENING    1234';
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: netstatOutput, stderr: '' }));
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:8080');
+        await tickMs(200);
+        await tickMs(1200);
+
+        Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+        const result = await resultPromise;
+        const params = result.parameters as Record<string, unknown>;
+        expect(params.port).toBe(8080);
+    });
+
+    test('returns success without port when getPortFromPid throws', async () => {
+        mockExec.mockImplementation((_cmd, cb) => cb(new Error('lsof crashed')));
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:8080');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Success');
+    });
+
+    test('returns preferred port when it is found in lsof output (early return)', async () => {
+        const lsofOutput = 'node   1234  user  TCP *:4000 (LISTEN)\nnode   1234  user  TCP *:5000 (LISTEN)';
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: lsofOutput, stderr: '' }));
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:4000');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        const params = result.parameters as Record<string, unknown>;
+        expect(params.port).toBe(4000);
+    });
+
+    test('rl close event resolves when both url and path are set but resolved was not yet flipped', async () => {
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: '', stderr: '' }));
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+
+        // Emit URL and path separately then close — when close fires both are set
+        // but the line handler may not have had a chance to flip resolved yet if
+        // we emit close before the combined-check triggers
+        currentStdoutRl!.emitLine('URL: http://localhost:5000');
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitClose();
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Success');
+    });
+
+    test('returns preferred port from netstat when it matches on Windows (early return)', async () => {
+        const originalPlatform = process.platform;
+        Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+        const netstatOutput =
+            'TCP    0.0.0.0:3000    0.0.0.0    LISTENING    1234\nTCP    0.0.0.0:4000    0.0.0.0    LISTENING    1234';
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: netstatOutput, stderr: '' }));
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://localhost:3000');
+        await tickMs(200);
+        await tickMs(1200);
+
+        Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+        const result = await resultPromise;
+        const params = result.parameters as Record<string, unknown>;
+        expect(params.port).toBe(3000);
+    });
+
+    test('uses port 443 when server URL is https with no explicit port', async () => {
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: '', stderr: '' }));
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: https://localhost');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Success');
+    });
+
+    test('handles invalid server URL gracefully in getPreferredPort', async () => {
+        mockExec.mockImplementation((_cmd, cb) => cb(null, { stdout: '', stderr: '' }));
+
+        const fakeProc = makeFakeProcess(1234);
+        mockSpawn.mockReturnValue(fakeProc);
+
+        const resultPromise = openAdaptationEditor({ appPath: '/app' });
+        currentStdoutRl!.emitLine('fiori run --open /test/adaptation-editor.html');
+        currentStdoutRl!.emitLine('URL: http://[invalid');
+        await tickMs(200);
+        await tickMs(1200);
+
+        const result = await resultPromise;
+        expect(result.status).toBe('Success');
+    });
+
+    test('outer catch returns error envelope when spawn itself throws synchronously', async () => {
+        mockSpawn.mockImplementation(() => {
+            throw new Error('spawn failed synchronously');
+        });
+
+        const result = await openAdaptationEditor({ appPath: '/app' });
+        expect(result.status).toBe('Error');
+        expect(result.message).toContain('spawn failed synchronously');
+    });
+});
diff --git a/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/browser/playwright-bridge.test.ts b/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/browser/playwright-bridge.test.ts
new file mode 100644
index 00000000000..9c199aa31fc
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/browser/playwright-bridge.test.ts
@@ -0,0 +1,430 @@
+import { EventEmitter } from 'node:events';
+import type * as PlaywrightBridgeModule from '../../../../../src/tools/run-rta-workflow-step/browser/playwright-bridge.js';
+
+// --- playwright-core mock --------------------------------------------------
+
+class FakeFrameElement {
+    constructor(private readonly id: string | null) {}
+    async getAttribute(name: string): Promise<string | null> {
+        return name === 'id' ? this.id : null;
+    }
+}
+
+class FakeFrame {
+    public readonly evaluate = jest.fn<Promise<unknown>, [unknown, unknown?]>(async () => ({
+        isSuccess: true,
+        payload: 'frame',
+        error: null
+    }));
+    public readonly frameElement = jest.fn(async () => new FakeFrameElement(this.id));
+    constructor(public readonly id: string | null) {}
+}
+
+class FakePage extends EventEmitter {
+    public readonly evaluate = jest.fn<Promise<unknown>, [unknown, unknown?]>(async () => ({
+        isSuccess: true,
+        payload: 'page',
+        error: null
+    }));
+    public readonly waitForFunction = jest.fn(async () => undefined);
+    public readonly goto = jest.fn(async () => undefined);
+    public readonly close = jest.fn(async () => {
+        this.emit('close');
+    });
+    private readonly frameList: FakeFrame[];
+    constructor(frames: FakeFrame[] = []) {
+        super();
+        this.frameList = frames;
+    }
+    frames(): FakeFrame[] {
+        return this.frameList;
+    }
+}
+
+class FakeBrowser extends EventEmitter {
+    public readonly close = jest.fn(async () => {
+        this.connected = false;
+        this.emit('disconnected');
+    });
+    public readonly newPage = jest.fn();
+    public readonly newContext = jest.fn(async () => ({
+        newPage: this.newPage,
+        close: jest.fn(async () => undefined)
+    }));
+    public connected = true;
+    isConnected(): boolean {
+        return this.connected;
+    }
+}
+
+const launchMock = jest.fn();
+
+jest.unstable_mockModule('playwright-core', () => ({
+    chromium: {
+        launch: (...args: unknown[]) => launchMock(...args)
+    }
+}));
+
+// --- helpers ---------------------------------------------------------------
+
+const SITE_A = 'http://localhost:8080/a';
+const SITE_B = 'http://localhost:8080/b';
+
+function setupBrowser(pages: FakePage[]): { browser: FakeBrowser; pages: FakePage[] } {
+    const browser = new FakeBrowser();
+    let i = 0;
+    browser.newPage.mockImplementation(async () => {
+        const page = pages[i++];
+        if (!page) {
+            throw new Error('No more fake pages queued');
+        }
+        return page;
+    });
+    launchMock.mockResolvedValue(browser);
+    return { browser, pages };
+}
+
+async function loadPlaywrightBridge(): Promise<typeof PlaywrightBridgeModule> {
+    return import('../../../../../src/tools/run-rta-workflow-step/browser/playwright-bridge');
+}
+
+beforeEach(() => {
+    jest.resetModules();
+    launchMock.mockReset();
+});
+
+describe('browser/playwright-bridge', () => {
+    test('first callFrontendAction launches browser, opens page, navigates, evaluates', async () => {
+        const page = new FakePage();
+        const { browser } = setupBrowser([page]);
+        page.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: { rtaStarted: true }, error: null });
+
+        const fs = await loadPlaywrightBridge();
+        const result = await fs.callFrontendAction(SITE_A, 'com.sap.ui.flex.startRTA.v1', {});
+
+        expect(launchMock).toHaveBeenCalledTimes(1);
+        expect(browser.newPage).toHaveBeenCalledTimes(1);
+        expect(page.goto).toHaveBeenCalledWith(SITE_A, expect.objectContaining({ waitUntil: 'networkidle' }));
+        expect(page.waitForFunction).toHaveBeenCalled();
+        expect(page.evaluate).toHaveBeenCalledTimes(1);
+        expect(result).toEqual({ isSuccess: true, payload: { rtaStarted: true }, error: null });
+
+        await fs.stopBrowser();
+    });
+
+    test('reuses page on second callFrontendAction for same site', async () => {
+        const page = new FakePage();
+        const { browser } = setupBrowser([page]);
+        page.evaluate
+            .mockResolvedValueOnce({ isSuccess: true, payload: 'first', error: null })
+            .mockResolvedValueOnce({ isSuccess: true, payload: 'second', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        const r1 = await fs.callFrontendAction(SITE_A, 'a');
+        const r2 = await fs.callFrontendAction(SITE_A, 'b');
+
+        expect(launchMock).toHaveBeenCalledTimes(1);
+        expect(browser.newPage).toHaveBeenCalledTimes(1);
+        expect(page.goto).toHaveBeenCalledTimes(1);
+        expect(r1.payload).toBe('first');
+        expect(r2.payload).toBe('second');
+
+        await fs.stopBrowser();
+    });
+
+    test('page close event evicts entry and creates fresh page on next call', async () => {
+        const stalePage = new FakePage();
+        const freshPage = new FakePage();
+        const { browser } = setupBrowser([stalePage, freshPage]);
+
+        stalePage.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'first', error: null });
+        freshPage.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'second', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        await fs.callFrontendAction(SITE_A, 'a');
+
+        // Simulate page close evicting the registry entry
+        await stalePage.close();
+
+        const r2 = await fs.callFrontendAction(SITE_A, 'b');
+
+        expect(browser.newPage).toHaveBeenCalledTimes(2);
+        expect(freshPage.goto).toHaveBeenCalledTimes(1);
+        expect(r2.payload).toBe('second');
+
+        await fs.stopBrowser();
+    });
+
+    test('frameId resolves to matching frame and runs evaluate there', async () => {
+        const matchedFrame = new FakeFrame('preview');
+        const otherFrame = new FakeFrame('toolbar');
+        const page = new FakePage([otherFrame, matchedFrame]);
+        setupBrowser([page]);
+        matchedFrame.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'inside-frame', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        const result = await fs.callFrontendAction(SITE_A, 'a', {}, 'preview');
+
+        expect(matchedFrame.evaluate).toHaveBeenCalledTimes(1);
+        expect(otherFrame.evaluate).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+        expect(result.payload).toBe('inside-frame');
+
+        await fs.stopBrowser();
+    });
+
+    test('unknown frameId throws', async () => {
+        const page = new FakePage([new FakeFrame('toolbar')]);
+        setupBrowser([page]);
+
+        const fs = await loadPlaywrightBridge();
+        await expect(fs.callFrontendAction(SITE_A, 'a', {}, 'nonexistent')).rejects.toThrow(
+            'Frame with id "nonexistent" not found'
+        );
+
+        await fs.stopBrowser();
+    });
+
+    test('disconnectSite closes the page and removes the entry', async () => {
+        const page = new FakePage();
+        const { browser } = setupBrowser([page, new FakePage()]);
+        page.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'first', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        await fs.callFrontendAction(SITE_A, 'a');
+        await fs.disconnectSite(SITE_A);
+
+        expect(page.close).toHaveBeenCalledTimes(1);
+
+        await fs.callFrontendAction(SITE_A, 'b');
+        expect(browser.newPage).toHaveBeenCalledTimes(2);
+
+        await fs.stopBrowser();
+    });
+
+    test('stopBrowser closes pages and the browser, clears registry', async () => {
+        const pageA = new FakePage();
+        const pageB = new FakePage();
+        const { browser } = setupBrowser([pageA, pageB]);
+        pageA.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'a', error: null });
+        pageB.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'b', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        await fs.callFrontendAction(SITE_A, 'x');
+        await fs.callFrontendAction(SITE_B, 'y');
+        await fs.stopBrowser();
+
+        expect(pageA.close).toHaveBeenCalled();
+        expect(pageB.close).toHaveBeenCalled();
+        expect(browser.close).toHaveBeenCalledTimes(1);
+    });
+
+    test('stopBrowser is a no-op when no browser was started', async () => {
+        const fs = await loadPlaywrightBridge();
+        await expect(fs.stopBrowser()).resolves.toBeUndefined();
+        expect(launchMock).not.toHaveBeenCalled();
+    });
+
+    test('disconnected event clears registry; next call starts a fresh browser', async () => {
+        const pageA = new FakePage();
+        const { browser } = setupBrowser([pageA]);
+        pageA.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'first', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        await fs.callFrontendAction(SITE_A, 'a');
+
+        browser.connected = false;
+        browser.emit('disconnected');
+
+        const pageB = new FakePage();
+        const newBrowser = new FakeBrowser();
+        newBrowser.newPage.mockResolvedValue(pageB);
+        launchMock.mockResolvedValueOnce(newBrowser);
+        pageB.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'second', error: null });
+
+        const r2 = await fs.callFrontendAction(SITE_A, 'b');
+        expect(launchMock).toHaveBeenCalledTimes(2);
+        expect(r2.payload).toBe('second');
+
+        await fs.stopBrowser();
+    });
+
+    test('honors PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH', async () => {
+        const original = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH;
+        process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH = '/usr/bin/chromium-test';
+        try {
+            const page = new FakePage();
+            setupBrowser([page]);
+            page.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'ok', error: null });
+
+            const fs = await loadPlaywrightBridge();
+            await fs.callFrontendAction(SITE_A, 'a');
+
+            expect(launchMock).toHaveBeenCalledWith(
+                expect.objectContaining({ executablePath: '/usr/bin/chromium-test' })
+            );
+
+            await fs.stopBrowser();
+        } finally {
+            if (original === undefined) {
+                delete process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH;
+            } else {
+                process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH = original;
+            }
+        }
+    });
+
+    test('falls back to bundled Chromium when system Chrome is missing', async () => {
+        const page = new FakePage();
+        const browser = new FakeBrowser();
+        browser.newPage.mockResolvedValue(page);
+        page.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'ok', error: null });
+
+        launchMock.mockRejectedValueOnce(
+            new Error("Executable doesn't exist at /usr/bin/google-chrome (channel=chrome)")
+        );
+        launchMock.mockResolvedValueOnce(browser);
+
+        const fs = await loadPlaywrightBridge();
+        const result = await fs.callFrontendAction(SITE_A, 'a');
+
+        expect(launchMock).toHaveBeenCalledTimes(2);
+        // First attempt uses the channel; second omits it.
+        expect(launchMock.mock.calls[0][0]).toEqual(expect.objectContaining({ channel: 'chrome' }));
+        expect(launchMock.mock.calls[1][0]).not.toHaveProperty('channel');
+        expect(launchMock.mock.calls[1][0]).not.toHaveProperty('executablePath');
+        expect(result.isSuccess).toBe(true);
+
+        await fs.stopBrowser();
+    });
+
+    test('throws an install hint when both system Chrome and bundled Chromium are missing', async () => {
+        launchMock.mockRejectedValueOnce(new Error("Executable doesn't exist at /usr/bin/google-chrome"));
+        launchMock.mockRejectedValueOnce(
+            new Error("Executable doesn't exist at /Users/.cache/ms-playwright/chromium-1234/chrome-mac/Chromium.app")
+        );
+
+        const fs = await loadPlaywrightBridge();
+        await expect(fs.callFrontendAction(SITE_A, 'a')).rejects.toThrow(/npx playwright install chromium/);
+        expect(launchMock).toHaveBeenCalledTimes(2);
+    });
+
+    test('does not retry when launch fails for an unrelated reason', async () => {
+        launchMock.mockRejectedValueOnce(new Error('User data dir is locked by another process'));
+
+        const fs = await loadPlaywrightBridge();
+        await expect(fs.callFrontendAction(SITE_A, 'a')).rejects.toThrow(/locked by another process/);
+        expect(launchMock).toHaveBeenCalledTimes(1);
+    });
+
+    test('isMissingBrowserError returns false for non-Error rejection so launch is not retried', async () => {
+        launchMock.mockRejectedValueOnce('not an Error object');
+
+        const fs = await loadPlaywrightBridge();
+        await expect(fs.callFrontendAction(SITE_A, 'a')).rejects.toBe('not an Error object');
+        expect(launchMock).toHaveBeenCalledTimes(1);
+    });
+
+    test('concurrent callFrontendAction calls reuse the same browserStartPromise', async () => {
+        let resolveLaunch!: (b: FakeBrowser) => void;
+        const launchDeferred = new Promise<FakeBrowser>((resolve) => {
+            resolveLaunch = resolve;
+        });
+        launchMock.mockReturnValueOnce(launchDeferred);
+
+        const browser = new FakeBrowser();
+        const page1 = new FakePage();
+        const page2 = new FakePage();
+        let pageIdx = 0;
+        const pages = [page1, page2];
+        browser.newPage.mockImplementation(async () => pages[pageIdx++]);
+        page1.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'first', error: null });
+        page2.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'second', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        const p1 = fs.callFrontendAction(SITE_A, 'action1');
+        const p2 = fs.callFrontendAction(SITE_B, 'action2');
+
+        resolveLaunch(browser);
+        const [r1, r2] = await Promise.all([p1, p2]);
+
+        // Both calls share the same browser launch — launchMock fires only once
+        expect(launchMock).toHaveBeenCalledTimes(1);
+        // Each site gets its own page
+        expect(browser.newPage).toHaveBeenCalledTimes(2);
+        expect(r1.payload).toBe('first');
+        expect(r2.payload).toBe('second');
+
+        await fs.stopBrowser();
+    });
+
+    test('pageerror event logs a warning with the site URL', async () => {
+        const page = new FakePage();
+        setupBrowser([page]);
+        page.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'ok', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        await fs.callFrontendAction(SITE_A, 'a');
+
+        const loggerModule = await import('../../../../../src/utils/logger.js');
+        const warnSpy = jest.spyOn(loggerModule.logger, 'warn').mockImplementation(jest.fn());
+
+        page.emit('pageerror', new Error('script error'));
+
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining(SITE_A));
+
+        warnSpy.mockRestore();
+        await fs.stopBrowser();
+    });
+
+    test('frameElement() returning null skips that frame and matches by id on next frame', async () => {
+        const nullFrame = new FakeFrame(null);
+        nullFrame.frameElement.mockResolvedValueOnce(null as any);
+        const targetFrame = new FakeFrame('target');
+        const page = new FakePage([nullFrame, targetFrame]);
+        setupBrowser([page]);
+        targetFrame.evaluate.mockResolvedValueOnce({ isSuccess: true, payload: 'target-result', error: null });
+
+        const fs = await loadPlaywrightBridge();
+        const result = await fs.callFrontendAction(SITE_A, 'a', {}, 'target');
+
+        expect(targetFrame.evaluate).toHaveBeenCalledTimes(1);
+        expect(nullFrame.evaluate).not.toHaveBeenCalled();
+        expect(result.payload).toBe('target-result');
+
+        await fs.stopBrowser();
+    });
+
+    test('throws non-missing-browser error from bundled Chromium fallback', async () => {
+        launchMock.mockRejectedValueOnce(new Error("Executable doesn't exist at /usr/bin/google-chrome"));
+        launchMock.mockRejectedValueOnce(new Error('GPU process crashed'));
+
+        const fs = await loadPlaywrightBridge();
+        await expect(fs.callFrontendAction(SITE_A, 'a')).rejects.toThrow(/GPU process crashed/);
+        expect(launchMock).toHaveBeenCalledTimes(2);
+    });
+
+    test('evaluate throws when bridge is unavailable on the page', async () => {
+        const page = new FakePage();
+        setupBrowser([page]);
+        page.evaluate.mockRejectedValueOnce(
+            new Error('window.sapdas.webclientBridge.getFrontendActions is not available on the page')
+        );
+
+        const fs = await loadPlaywrightBridge();
+        await expect(fs.callFrontendAction(SITE_A, 'a')).rejects.toThrow(/getFrontendActions is not available/);
+
+        await fs.stopBrowser();
+    });
+
+    test('evaluate throws when frontend action is not registered', async () => {
+        const page = new FakePage();
+        setupBrowser([page]);
+        page.evaluate.mockRejectedValueOnce(new Error('Frontend action "unknown.action" not registered'));
+
+        const fs = await loadPlaywrightBridge();
+        await expect(fs.callFrontendAction(SITE_A, 'unknown.action')).rejects.toThrow(/not registered/);
+
+        await fs.stopBrowser();
+    });
+});
diff --git a/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/index.test.ts b/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/index.test.ts
new file mode 100644
index 00000000000..e5971441559
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/index.test.ts
@@ -0,0 +1,231 @@
+import { jest } from '@jest/globals';
+
+const mockStartRta = jest.fn<any>();
+const mockGetOverlays = jest.fn<any>();
+const mockGetActions = jest.fn<any>();
+const mockGetElementContext = jest.fn<any>();
+const mockExecuteAction = jest.fn<any>();
+const mockSaveChanges = jest.fn<any>();
+const mockStopBrowser = jest.fn<any>();
+
+jest.unstable_mockModule('../../../../src/tools/run-rta-workflow-step/rta/index.js', () => ({
+    startRta: mockStartRta,
+    getOverlays: mockGetOverlays,
+    getActions: mockGetActions,
+    getElementContext: mockGetElementContext,
+    executeAction: mockExecuteAction,
+    saveChanges: mockSaveChanges,
+    FrontendActionError: class FrontendActionError extends Error {
+        public readonly code: string;
+        constructor(actionName: string, code: string, message: string | null | undefined) {
+            super(`Frontend action ${actionName} failed [${code}]: ${message ?? '(no message)'}`);
+            this.name = 'FrontendActionError';
+            this.code = code;
+        }
+    }
+}));
+
+jest.unstable_mockModule('../../../../src/tools/run-rta-workflow-step/browser/index.js', () => ({
+    defaultTransport: {
+        callFrontendAction: jest.fn(),
+        disconnectSite: jest.fn(),
+        stopBrowser: mockStopBrowser
+    }
+}));
+
+const { runRtaWorkflowStep } = await import('../../../../src/tools/run-rta-workflow-step/index.js');
+const { FrontendActionError } = await import('../../../../src/tools/run-rta-workflow-step/rta/index.js');
+
+/**
+ * Session IDs accumulated by tests that start a session but do not stop it.
+ * The stopBrowser test drains this list so the sessions Map is empty when
+ * it runs its own start+stop sequence.
+ */
+const openSessionIds: string[] = [];
+
+async function startSession(): Promise<string> {
+    mockStartRta.mockResolvedValueOnce({ rtaStarted: true });
+    const result = (await runRtaWorkflowStep({
+        step: 'start',
+        payload: { site: 'https://example.com' }
+    })) as any;
+    openSessionIds.push(result.sessionId);
+    return result.sessionId;
+}
+
+describe('runRtaWorkflowStep', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    describe('start', () => {
+        test('throws when site is missing from payload', async () => {
+            await expect(runRtaWorkflowStep({ step: 'start', payload: {} })).rejects.toThrow(
+                'payload.site is required and must be a non-empty string'
+            );
+        });
+
+        test('returns sessionId and rtaStarted on success', async () => {
+            const sessionId = await startSession();
+            expect(typeof sessionId).toBe('string');
+            expect(sessionId.length).toBeGreaterThan(0);
+        });
+    });
+
+    describe('get_overlays', () => {
+        test('throws when sessionId is missing', async () => {
+            await expect(runRtaWorkflowStep({ step: 'get_overlays' })).rejects.toThrow('sessionId is required');
+        });
+
+        test('returns overlays on success', async () => {
+            const sessionId = await startSession();
+            const overlays = [{ id: 'ctrl1' }];
+            mockGetOverlays.mockResolvedValue(overlays);
+            const result = await runRtaWorkflowStep({ step: 'get_overlays', sessionId });
+            expect(result).toEqual({ overlays });
+        });
+    });
+
+    describe('get_actions', () => {
+        test('throws when controlId is missing', async () => {
+            const sessionId = await startSession();
+            await expect(runRtaWorkflowStep({ step: 'get_actions', sessionId, payload: {} })).rejects.toThrow(
+                'payload.controlId is required and must be a non-empty string'
+            );
+        });
+
+        test('returns actions on success', async () => {
+            const sessionId = await startSession();
+            const actions = [{ id: 'rename', name: 'Rename' }];
+            mockGetActions.mockResolvedValue(actions);
+            const result = await runRtaWorkflowStep({
+                step: 'get_actions',
+                sessionId,
+                payload: { controlId: 'ctrl1' }
+            });
+            expect(result).toEqual({ actions });
+        });
+    });
+
+    describe('get_context', () => {
+        test('throws when controlId is missing', async () => {
+            const sessionId = await startSession();
+            await expect(
+                runRtaWorkflowStep({ step: 'get_context', sessionId, payload: { actionId: 'rename' } })
+            ).rejects.toThrow('payload.controlId is required and must be a non-empty string');
+        });
+
+        test('throws when actionId is missing', async () => {
+            const sessionId = await startSession();
+            await expect(
+                runRtaWorkflowStep({ step: 'get_context', sessionId, payload: { controlId: 'ctrl1' } })
+            ).rejects.toThrow('payload.actionId is required and must be a non-empty string');
+        });
+
+        test('returns context on success', async () => {
+            const sessionId = await startSession();
+            const context = { properties: [] };
+            mockGetElementContext.mockResolvedValue(context);
+            const result = await runRtaWorkflowStep({
+                step: 'get_context',
+                sessionId,
+                payload: { controlId: 'ctrl1', actionId: 'rename' }
+            });
+            expect(result).toEqual({ context });
+        });
+    });
+
+    describe('call_action', () => {
+        test('throws when actionPayload is missing', async () => {
+            const sessionId = await startSession();
+            await expect(
+                runRtaWorkflowStep({
+                    step: 'call_action',
+                    sessionId,
+                    payload: { controlId: 'ctrl1', actionId: 'rename' }
+                })
+            ).rejects.toThrow('payload.actionPayload is required and must be an object');
+        });
+
+        test('throws when actionPayload is not an object', async () => {
+            const sessionId = await startSession();
+            await expect(
+                runRtaWorkflowStep({
+                    step: 'call_action',
+                    sessionId,
+                    payload: { controlId: 'ctrl1', actionId: 'rename', actionPayload: 'notAnObject' }
+                })
+            ).rejects.toThrow('payload.actionPayload is required and must be an object');
+        });
+
+        test('returns success true on success', async () => {
+            const sessionId = await startSession();
+            mockExecuteAction.mockResolvedValue(true);
+            const result = await runRtaWorkflowStep({
+                step: 'call_action',
+                sessionId,
+                payload: { controlId: 'ctrl1', actionId: 'rename', actionPayload: { newValue: 'foo' } }
+            });
+            expect(result).toEqual({ success: true });
+        });
+    });
+
+    describe('save', () => {
+        test('returns saved true on success', async () => {
+            const sessionId = await startSession();
+            mockSaveChanges.mockResolvedValue(true);
+            const result = await runRtaWorkflowStep({ step: 'save', sessionId });
+            expect(result).toEqual({ saved: true });
+        });
+    });
+
+    describe('stop', () => {
+        test('returns stopped true on success', async () => {
+            const sessionId = await startSession();
+            const result = await runRtaWorkflowStep({ step: 'stop', sessionId });
+            // Remove from open list since it was stopped here
+            const idx = openSessionIds.indexOf(sessionId);
+            if (idx !== -1) {
+                openSessionIds.splice(idx, 1);
+            }
+            expect(result).toEqual({ stopped: true });
+        });
+
+        test('calls stopBrowser when the last session is removed', async () => {
+            // Drain all sessions accumulated by earlier tests so the Map is empty
+            // after this test stops its own session.
+            for (const id of openSessionIds.splice(0)) {
+                try {
+                    await runRtaWorkflowStep({ step: 'stop', sessionId: id });
+                } catch {
+                    // already stopped — ignore
+                }
+            }
+            mockStopBrowser.mockClear();
+
+            mockStartRta.mockResolvedValueOnce({ rtaStarted: true });
+            const startResult = (await runRtaWorkflowStep({
+                step: 'start',
+                payload: { site: 'https://example.com' }
+            })) as any;
+
+            await runRtaWorkflowStep({ step: 'stop', sessionId: startResult.sessionId });
+            expect(mockStopBrowser).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('unknown step', () => {
+        test('throws with message containing Unknown step', async () => {
+            await expect(runRtaWorkflowStep({ step: 'not_a_real_step' as any })).rejects.toThrow('Unknown step');
+        });
+    });
+
+    describe('FrontendActionError', () => {
+        test('is re-thrown from the step handler', async () => {
+            const sessionId = await startSession();
+            const frontendError = new (FrontendActionError as any)('someAction', 'ERR_CODE', 'something failed');
+            mockGetOverlays.mockRejectedValue(frontendError);
+            await expect(runRtaWorkflowStep({ step: 'get_overlays', sessionId })).rejects.toThrow('something failed');
+        });
+    });
+});
diff --git a/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/rta/commands.test.ts b/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/rta/commands.test.ts
new file mode 100644
index 00000000000..f9c5b24b028
--- /dev/null
+++ b/packages/fiori-mcp-server/test/unit/tools/run-rta-workflow-step/rta/commands.test.ts
@@ -0,0 +1,152 @@
+import type {
+    FrontendActionResult,
+    FrontendActionTransport
+} from '../../../../../src/tools/run-rta-workflow-step/browser/types.js';
+import {
+    FrontendActionError,
+    executeAction,
+    getActions,
+    getElementContext,
+    getOverlays,
+    saveChanges,
+    startRta,
+    startVisualization,
+    stopRta
+} from '../../../../../src/tools/run-rta-workflow-step/rta/commands.js';
+
+const SITE = 'http://localhost:8080/test/adaptation-editor.html';
+const FRAME = 'preview';
+
+const ok = <T>(payload: T): FrontendActionResult<T> => ({
+    isSuccess: true,
+    payload,
+    error: null
+});
+const fail = (code: string, message: string): FrontendActionResult<never> => ({
+    isSuccess: false,
+    payload: null,
+    error: { code, message }
+});
+
+interface FakeTransport extends FrontendActionTransport {
+    callFrontendAction: jest.MockedFunction<FrontendActionTransport['callFrontendAction']>;
+    disconnectSite: jest.MockedFunction<FrontendActionTransport['disconnectSite']>;
+    stopBrowser: jest.MockedFunction<FrontendActionTransport['stopBrowser']>;
+}
+
+function createFakeTransport(): FakeTransport {
+    return {
+        callFrontendAction: jest.fn(),
+        disconnectSite: jest.fn().mockResolvedValue(undefined),
+        stopBrowser: jest.fn().mockResolvedValue(undefined)
+    };
+}
+
+describe('rta/commands', () => {
+    let transport: FakeTransport;
+
+    beforeEach(() => {
+        transport = createFakeTransport();
+    });
+
+    test('startRta calls com.sap.ui.flex.startRTA.v1 with empty payload', async () => {
+        transport.callFrontendAction.mockResolvedValueOnce(ok({ rtaStarted: true }));
+        const result = await startRta(transport, { site: SITE, frameId: FRAME });
+        expect(transport.callFrontendAction).toHaveBeenCalledWith(SITE, 'com.sap.ui.flex.startRTA.v1', {}, FRAME);
+        expect(result).toEqual({ rtaStarted: true });
+    });
+
+    test('getOverlays calls getOverlaysInformation', async () => {
+        transport.callFrontendAction.mockResolvedValueOnce(
+            ok([{ overlayId: 'o1', controlId: 'c1', label: 'L', controlType: 'sap.m.Button' }])
+        );
+        const result = await getOverlays(transport, { site: SITE });
+        expect(transport.callFrontendAction).toHaveBeenCalledWith(
+            SITE,
+            'com.sap.ui.flex.getOverlaysInformation.v1',
+            {},
+            undefined
+        );
+        expect(result).toHaveLength(1);
+    });
+
+    test('getActions wraps controlId in payload object', async () => {
+        transport.callFrontendAction.mockResolvedValueOnce(ok([{ id: 'rename' }]));
+        await getActions(transport, { site: SITE, frameId: FRAME }, 'control-1');
+        expect(transport.callFrontendAction).toHaveBeenCalledWith(
+            SITE,
+            'com.sap.ui.flex.getActions.v1',
+            { controlId: 'control-1' },
+            FRAME
+        );
+    });
+
+    test('getElementContext requires controlId and actionId in payload', async () => {
+        transport.callFrontendAction.mockResolvedValueOnce(ok({ defaultChildAggregationName: 'items', content: [] }));
+        await getElementContext(transport, { site: SITE }, 'control-1', 'rename');
+        expect(transport.callFrontendAction).toHaveBeenCalledWith(
+            SITE,
+            'com.sap.ui.flex.getContext.v1',
+            { controlId: 'control-1', actionId: 'rename' },
+            undefined
+        );
+    });
+
+    test('executeAction passes a single payload object with controlId, actionId, payload', async () => {
+        transport.callFrontendAction.mockResolvedValueOnce(ok(true));
+        await executeAction(transport, { site: SITE, frameId: FRAME }, 'control-1', 'rename', { newLabel: 'Hi' });
+        expect(transport.callFrontendAction).toHaveBeenCalledWith(
+            SITE,
+            'com.sap.ui.flex.callAction.v1',
+            { controlId: 'control-1', actionId: 'rename', payload: { newLabel: 'Hi' } },
+            FRAME
+        );
+    });
+
+    test('saveChanges calls saveChanges with empty payload', async () => {
+        transport.callFrontendAction.mockResolvedValueOnce(ok(true));
+        await saveChanges(transport, { site: SITE });
+        expect(transport.callFrontendAction).toHaveBeenCalledWith(
+            SITE,
+            'com.sap.ui.flex.saveChanges.v1',
+            {},
+            undefined
+        );
+    });
+
+    test('startVisualization calls startVisualization with empty payload', async () => {
+        transport.callFrontendAction.mockResolvedValueOnce(ok({ visualizationStarted: true }));
+        const result = await startVisualization(transport, { site: SITE });
+        expect(transport.callFrontendAction).toHaveBeenCalledWith(
+            SITE,
+            'com.sap.ui.flex.startVisualization.v1',
+            {},
+            undefined
+        );
+        expect(result).toEqual({ visualizationStarted: true });
+    });
+
+    test('an isSuccess=false result throws a FrontendActionError carrying the code', async () => {
+        transport.callFrontendAction.mockResolvedValueOnce(fail('CONTROL_NOT_FOUND', 'Control with id x not found'));
+        await expect(getActions(transport, { site: SITE }, 'x')).rejects.toMatchObject({
+            name: 'FrontendActionError',
+            code: 'CONTROL_NOT_FOUND',
+            message: expect.stringContaining('CONTROL_NOT_FOUND')
+        });
+
+        transport.callFrontendAction.mockResolvedValueOnce(fail('CONTROL_NOT_FOUND', 'Control with id x not found'));
+        await expect(getActions(transport, { site: SITE }, 'x')).rejects.toBeInstanceOf(FrontendActionError);
+    });
+
+    test('stopRta(site) disconnects only that site', async () => {
+        await stopRta(transport, { site: SITE });
+        expect(transport.disconnectSite).toHaveBeenCalledWith(SITE);
+        expect(transport.stopBrowser).not.toHaveBeenCalled();
+    });
+
+    test('stopRta() with no site stops the transport entirely', async () => {
+        await stopRta(transport);
+        expect(transport.stopBrowser).toHaveBeenCalledTimes(1);
+        expect(transport.disconnectSite).not.toHaveBeenCalled();
+    });
+});
diff --git a/packages/fiori-mcp-server/tsconfig.json b/packages/fiori-mcp-server/tsconfig.json
index d50554f9830..df36a0b8c4d 100644
--- a/packages/fiori-mcp-server/tsconfig.json
+++ b/packages/fiori-mcp-server/tsconfig.json
@@ -11,6 +11,9 @@
     "isolatedModules": false
   },
   "references": [
+    {
+      "path": "../adp-tooling"
+    },
     {
       "path": "../axios-extension"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6b65637172d..b16b99ca790 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2678,6 +2678,9 @@ importers:
       '@sap-ai-sdk/langchain':
         specifier: 2.9.0
         version: 2.9.0(@langchain/core@1.1.49(@opentelemetry/api@1.9.0)(@opentelemetry/exporter-trace-otlp-proto@0.218.0(@opentelemetry/api@1.9.0))(@opentelemetry/sdk-trace-base@2.8.0(@opentelemetry/api@1.9.0))(openai@6.39.0(ws@8.21.0)(zod@4.3.6))(ws@8.21.0))
+      '@sap-ux/adp-tooling':
+        specifier: workspace:*
+        version: link:../adp-tooling
       '@sap-ux/annotation-converter':
         specifier: 0.10.21
         version: 0.10.21
@@ -2765,9 +2768,12 @@ importers:
       os-name:
         specifier: 4.0.1
         version: 4.0.1
+      playwright-core:
+        specifier: 1.58.2
+        version: 1.58.2
       promptfoo:
         specifier: 0.121.15
-        version: 0.121.15(@cfworker/json-schema@4.1.1)(@langchain/core@1.1.49(@opentelemetry/api@1.9.0)(@opentelemetry/exporter-trace-otlp-proto@0.218.0(@opentelemetry/api@1.9.0))(@opentelemetry/sdk-trace-base@2.8.0(@opentelemetry/api@1.9.0))(openai@6.39.0(ws@8.21.0)(zod@4.3.6))(ws@8.21.0))(@swc/helpers@0.5.19)(@types/json-schema@7.0.15)(@types/node@22.13.14)(@types/pg@8.15.6)(babel-plugin-macros@3.1.0)(encoding@0.1.13)(pg@8.18.0)(playwright-core@1.60.0)(socks@2.8.7)
+        version: 0.121.15(@cfworker/json-schema@4.1.1)(@langchain/core@1.1.49(@opentelemetry/api@1.9.0)(@opentelemetry/exporter-trace-otlp-proto@0.218.0(@opentelemetry/api@1.9.0))(@opentelemetry/sdk-trace-base@2.8.0(@opentelemetry/api@1.9.0))(openai@6.39.0(ws@8.21.0)(zod@4.3.6))(ws@8.21.0))(@swc/helpers@0.5.19)(@types/json-schema@7.0.15)(@types/node@22.13.14)(@types/pg@8.15.6)(babel-plugin-macros@3.1.0)(encoding@0.1.13)(pg@8.18.0)(playwright-core@1.58.2)(socks@2.8.7)
       ts-node:
         specifier: 10.9.2
         version: 10.9.2(@swc/core@1.15.18(@swc/helpers@0.5.19))(@types/node@22.13.14)(typescript@5.9.3)
@@ -16327,6 +16333,11 @@ packages:
   platform@1.3.6:
     resolution: {integrity: sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==}
 
+  playwright-core@1.58.2:
+    resolution: {integrity: sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   playwright-core@1.60.0:
     resolution: {integrity: sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==}
     engines: {node: '>=18'}
@@ -33722,14 +33733,16 @@ snapshots:
 
   platform@1.3.6: {}
 
+  playwright-core@1.58.2: {}
+
   playwright-core@1.60.0: {}
 
-  playwright-extra@4.3.6(playwright-core@1.60.0)(playwright@1.60.0):
+  playwright-extra@4.3.6(playwright-core@1.58.2)(playwright@1.60.0):
     dependencies:
       debug: 4.4.3(supports-color@7.2.0)
     optionalDependencies:
       playwright: 1.60.0
-      playwright-core: 1.60.0
+      playwright-core: 1.58.2
     transitivePeerDependencies:
       - supports-color
     optional: true
@@ -33936,7 +33949,7 @@ snapshots:
     dependencies:
       '@babel/runtime': 7.29.2
 
-  promptfoo@0.121.15(@cfworker/json-schema@4.1.1)(@langchain/core@1.1.49(@opentelemetry/api@1.9.0)(@opentelemetry/exporter-trace-otlp-proto@0.218.0(@opentelemetry/api@1.9.0))(@opentelemetry/sdk-trace-base@2.8.0(@opentelemetry/api@1.9.0))(openai@6.39.0(ws@8.21.0)(zod@4.3.6))(ws@8.21.0))(@swc/helpers@0.5.19)(@types/json-schema@7.0.15)(@types/node@22.13.14)(@types/pg@8.15.6)(babel-plugin-macros@3.1.0)(encoding@0.1.13)(pg@8.18.0)(playwright-core@1.60.0)(socks@2.8.7):
+  promptfoo@0.121.15(@cfworker/json-schema@4.1.1)(@langchain/core@1.1.49(@opentelemetry/api@1.9.0)(@opentelemetry/exporter-trace-otlp-proto@0.218.0(@opentelemetry/api@1.9.0))(@opentelemetry/sdk-trace-base@2.8.0(@opentelemetry/api@1.9.0))(openai@6.39.0(ws@8.21.0)(zod@4.3.6))(ws@8.21.0))(@swc/helpers@0.5.19)(@types/json-schema@7.0.15)(@types/node@22.13.14)(@types/pg@8.15.6)(babel-plugin-macros@3.1.0)(encoding@0.1.13)(pg@8.18.0)(playwright-core@1.58.2)(socks@2.8.7):
     dependencies:
       '@anthropic-ai/sdk': 0.93.0(zod@4.3.6)
       '@apidevtools/json-schema-ref-parser': 15.3.1(@types/json-schema@7.0.15)
@@ -34057,7 +34070,7 @@ snapshots:
       pdf-parse: 2.4.5
       pem: 1.14.8
       playwright: 1.60.0
-      playwright-extra: 4.3.6(playwright-core@1.60.0)(playwright@1.60.0)
+      playwright-extra: 4.3.6(playwright-core@1.58.2)(playwright@1.60.0)
       read-excel-file: 9.0.10
       sharp: 0.34.5
     transitivePeerDependencies: