@ui5/mcp-server 0.1.0

package/resources/docs/1.136.7/index.json

@@ -0,0 +1,58 @@
+[
+  {
+    "shortIdentifier": "0187ea5",
+    "identifier": "0187ea5e2eff4166b0453b9dcc8fc64f",
+    "uri": "https://ui5.sap.com/1.136.7/topic/0187ea5e2eff4166b0453b9dcc8fc64f",
+    "title": "Component Metadata",
+    "filePath": "0187ea5e2eff4166b0453b9dcc8fc64f.md"
+  },
+  {
+    "shortIdentifier": "00737d6",
+    "identifier": "00737d6c1b864dc3ab72ef56611491c4",
+    "uri": "https://ui5.sap.com/1.136.7/topic/00737d6c1b864dc3ab72ef56611491c4",
+    "title": "Best Practices for Loading Modules",
+    "filePath": "00737d6c1b864dc3ab72ef56611491c4.md"
+  },
+  {
+    "shortIdentifier": "28fcd55",
+    "identifier": "28fcd55b04654977b63dacbee0552712",
+    "uri": "https://ui5.sap.com/1.136.7/topic/28fcd55b04654977b63dacbee0552712",
+    "title": "Best Practices for Developers",
+    "filePath": "28fcd55b04654977b63dacbee0552712.md"
+  },
+  {
+    "shortIdentifier": "a87ca84",
+    "identifier": "a87ca843bcee469f82a9072927a7dcdb",
+    "uri": "https://ui5.sap.com/1.136.7/topic/a87ca843bcee469f82a9072927a7dcdb",
+    "title": "Deprecated Themes and Libraries",
+    "filePath": "a87ca843bcee469f82a9072927a7dcdb.md"
+  },
+  {
+    "shortIdentifier": "676b636",
+    "identifier": "676b636446c94eada183b1218a824717",
+    "uri": "https://ui5.sap.com/1.136.7/topic/676b636446c94eada183b1218a824717",
+    "title": "Use Asynchronous Loading",
+    "filePath": "676b636446c94eada183b1218a824717.md"
+  },
+  {
+    "shortIdentifier": "fe1a6db",
+    "identifier": "fe1a6dba940e479fb7c3bc753f92b28c",
+    "uri": "https://ui5.sap.com/1.136.7/topic/fe1a6dba940e479fb7c3bc753f92b28c",
+    "title": "Content Security Policy",
+    "filePath": "fe1a6dba940e479fb7c3bc753f92b28c.md"
+  },
+  {
+    "shortIdentifier": "b0fb4de",
+    "identifier": "b0fb4de7364f4bcbb053a99aa645affe",
+    "uri": "https://ui5.sap.com/1.136.7/topic/b0fb4de7364f4bcbb053a99aa645affe",
+    "title": "Handling Events in XML Views",
+    "filePath": "b0fb4de7364f4bcbb053a99aa645affe.md"
+  },
+  {
+    "shortIdentifier": "032be2c",
+    "identifier": "032be2cb2e1d4115af20862673bedcdb",
+    "uri": "https://ui5.sap.com/1.136.7/topic/032be2cb2e1d4115af20862673bedcdb",
+    "title": "Test Starter",
+    "filePath": "032be2cb2e1d4115af20862673bedcdb.md"
+  }
+]

package/resources/guidelines.md

@@ -0,0 +1,104 @@
+# UI5 Development Guidelines
+
+> *This document outlines the fundamental rules and best practices an AI agent must follow when developing or modifying SAPUI5 projects. Adherence to these guidelines is critical for creating modern, maintainable, and performant applications.*
+
+## 1. Coding Guidelines
+
+- **NEVER** use global variables to access UI5 framework objects (e.g., `sap.m.Button`). Instead, explicitly declare all dependencies, so that they are loaded asynchronously before your code executes.
+  - in JavaScript: Using `sap.ui.define` at the top of the file (which also registers the file as a UI5 module) or dynamically using `sap.ui.require`
+  - in TypeScript: Using ES6 `import` statements
+  - in XML:
+    - For controls it is sufficient to declare the corresponding XML tag (e.g. `<m:Button></m:Button>`). The XML Template engine will load the corresponding resource automatically.
+    - However, when referring to programmatic API like formatters or types, those must be "imported" using a `core:require` directive
+    - Example
+      ```xml
+       <ObjectListItem
+          core:require="{
+              Currency: 'sap/ui/model/type/Currency'
+          }"
+          title="{invoice>Quantity} x {invoice>ProductName}"
+          number="{
+              parts: [
+                  'invoice>ExtendedPrice',
+                  'view>/currency'
+              ],
+              type: 'Currency',
+              formatOptions: {
+                  showMeasure: false
+              }
+          }"
+          numberUnit="{view>/currency}"/>
+      ```
+    - Find more information on the UI5 documentation page "Require Modules in XML View and Fragment"
+- **ALWAYS** use the `sap/ui/core/ComponentSupport` module to initialize a UI5 application/component in an HTML page
+  - Example:
+    ```html
+    <!-- index.html -->
+    <script id="sap-ui-bootstrap"
+      src="resources/sap-ui-core.js"
+      data-sap-ui-on-init="module:sap/ui/core/ComponentSupport"
+      data-sap-ui-async="true"
+      data-sap-ui-resource-roots='{ "my.app": "./" }'
+      data-...="...">
+    </script>
+    ```
+  - Find more information on the UI5 documentation page "Declarative API for Initial Components"
+- **ALWAYS** use data binding in views to connect UI controls to data or i18n models.
+  - When binding data from OData services, **NEVER** use custom formatters for standard data types (e.g., dates, numbers, currencies). The built-in types handle these cases automatically.
+- When making changes to `*.properties` files, **ALWAYS** apply the changes to all relevant locales. This ensures consistency across different language versions of the application.
+  - **Example:** If you add a new key to `i18n.properties`, also add it to existing translation files like e.g `i18n_en.properties`, `i18n_de.properties`, etc.
+- **NEVER** use inline script in HTML
+  - All application logic must reside in dedicated JS or TS files. Inline `<script>` would violate the recommended CSP settings for UI5 applications.
+  - Find more information on the UI5 documentation page "Content Security Policy"
+
+### TypeScript: Special Handling for Control Event Handlers
+
+- **Rule:** For any control event handler, import and use the specific event type from the control's module. The type is typically named `<ControlName>$<EventName>Event`. Notice the "Event" suffix.
+- **Example:** For the `press` event of `sap.m.Button`, use `import {Button$PressEvent} from "sap/m/Button"`.
+  - The event handler then may look like this: `onPress(event: Button$PressEvent): void { [...]`.
+- **Benefit:** This provides static type checking and autocompletion for event parameters (e.g., `event.getParameter(...)`) without needing manual casting or comments.
+- **Version Compatibility:**
+    - **UI5 >= 1.115.0:** This feature is available and **MUST** be used.
+    - **UI5 < 1.115.0:** These specific types are **NOT** available. Use the generic `import Event from "sap/ui/base/Event"` as the fallback type.
+
+**Example (UI5 >= 1.115.0):**
+
+```ts
+// Import the specific event type from the control's module
+import { Table$RowSelectionChangeEvent } from "sap/ui/table/Table";
+import Table from "sap/ui/table/Table";
+
+// ... inside a controller class
+public onRowSelectionChange(event: Table$RowSelectionChangeEvent): void {
+    // Correctly typed: getParameter is known and its return value can be inferred
+    const selectedContext = event.getParameter("rowContext");
+    // ...
+}
+```
+
+## 2. Tooling and Environment Interaction
+
+An AI agent must understand how to use and interpret the standard UI5 development tools, primarily through the available MCP tools.
+
+- **API Lookup:** To get information on UI5 controls and APIs, **ALWAYS** use the `get_api_reference` tool. This provides direct access to the official UI5 API Reference. Provide it with a path to the current project and it will provide the correct API reference for the UI5 version in use.
+- **Code Validation:** To identify issues, **ALWAYS** use the `run_ui5_linter` tool. It detects deprecated APIs, accessibility issues, and other potential bugs.
+- **Code Fixes:** To apply fixes suggested by the linter, always confirm with the user first. Then use the `fix` parameter of the `run_ui5_linter` tool. This will automatically correct _some_ of the identified issues. The tool can also provide context information that can be used to manually fix the remaining issues when tasked to do so.
+- **Local Server Behavior:** When interacting with the UI5 CLI's development server, understand that it does **NOT** serve a default index file. You **MUST ALWAYS** reference files by their full path when using the browser (e.g., `http://localhost:8080/index.html`, not `http://localhost:8080/`).
+
+## 3. CAP (Cloud Application Programming Model) Integration
+
+When creating a new UI5 project within a CAP project, a specific set of rules apply to ensure seamless integration.
+
+- **Project Location:** **ALWAYS** create UI5 projects within the `app/` directory of the CAP project root.
+- **Service Information:**
+  - If CDS tools are available to you, **ALWAYS** use them to get information about the definitions, services and their endpoints.
+  - If no CDS tools are available to you, **ALWAYS** run `cds compile '*'` to get information about the definitions and `cds compile '*' --to serviceinfo` to get information about the services and their endpoints.
+- **Service Integration:** When creating the UI5 project, **ALWAYS** provide the absolute OData V4 service URL and the target entity set when prompted by the tooling.
+- **Plugin Installation:** **ALWAYS** run `npm i -D cds-plugin-ui5` in the CAP project root directory to ensure the latest version of `cds-plugin-ui5` is installed. This plugin automatically handles serving the UI5 applications.
+- **Running the Server:**
+    - **NEVER** run a separate `ui5 serve` or `npm start` command inside the UI5 project folder.
+    - **ALWAYS** run `cds watch` (or `cds run`) from the **root** of the CAP project. This single command serves both the backend services and all UI5 applications.
+- **Data Connection:**
+    - **NEVER** configure a `ui5-middleware-simpleproxy` in the `ui5.yaml` file to connect to the local CAP service.
+    - **Why:** The `cds watch` command ensures the UI and the service are served from the same origin (`http://localhost:4004`), making a proxy unnecessary.
+- **Accessing the App:** Check the CAP launch page (typically `http://localhost:4004`) for a list of available services and links to the UI5 applications.

package/resources/migrationGuides/deprecated-controller-factory.md

@@ -0,0 +1,116 @@
+# Guide for Migrating the Deprecated `sap.ui.controller` Function
+
+> *This guide provides instructions for AI-based development tools to perform a critical API migration in SAPUI5 projects. The focus is on replacing the deprecated `sap.ui.controller` with modern, asynchronous-friendly equivalents.*
+
+## 1. Core Concepts of the Migration
+
+The global function `sap.ui.controller` was used for two distinct purposes: defining a controller class and synchronously instantiating a controller. Both use cases are now deprecated and must be replaced to align with modern UI5 development standards, which emphasize Asynchronous Module Definition (AMD) for improved performance and modularity.
+
+The migration path involves these primary steps:
+
+1. **Adopt `sap.ui.define`:** All controller definitions must be wrapped in a `sap.ui.define` block. This ensures that dependencies, like the base controller, are loaded asynchronously before the controller module is executed.
+2. **Import `sap/ui/core/mvc/Controller`:** The modern base class for all controllers must be explicitly imported.
+3. **Choose the Correct Replacement:**
+    * To **define a controller class**, use `Controller.extend()`. This is the most common use case and is typically found in `.controller.js` files.
+    * To **create an instance of a controller** programmatically (a less common scenario), use the factory function `Controller.create()`. This function returns a `Promise`.
+
+## 2. Migration Scenarios
+
+### Scenario A: Defining a Controller Class (Most Common)
+
+This scenario applies to the standard definition of a view's controller. The goal is to convert the old `sap.ui.controller()` definition into a modern AMD-style module that returns a controller class.
+
+**Key Characteristics of "Before" Code:**
+
+* Uses `sap.ui.controller('my.name.space.ControllerName', { ... });`
+* The code is often in the global scope, not inside a `sap.ui.define`.
+* Contains lifecycle methods like `onInit`, `onAfterRendering`, etc.
+
+#### Migration Steps
+
+1. Wrap the entire code in a `sap.ui.define` call.
+2. Add `"sap/ui/core/mvc/Controller"` to the dependency array.
+3. Pass a corresponding argument (e.g., `Controller`) to the factory function.
+4. Replace `sap.ui.controller(...)` with `return Controller.extend(...)`.
+5. It's a best practice to add `"use strict";` as the first statement inside the factory function. This should only be done if this practice is done in other controller files in the project.
+
+
+#### Example: Controller Class Migration
+
+**Before:**
+
+```js
+sap.ui.controller('myApp.controller.Main', {
+    onInit: function () {
+        // Initialization code
+    },
+    onPress: function () {
+        // Button press handler
+    },
+});
+```
+
+**After:**
+
+```js
+sap.ui.define([
+    "sap/ui/core/mvc/Controller"
+], (Controller) => {
+    "use strict";
+
+    return Controller.extend("myApp.controller.Main", {
+        onInit() {
+            // Initialization code
+        },
+        onPress() {
+            // Button press handler
+        },
+    });
+});
+```
+
+### Scenario B: Instantiating a Controller Programmatically
+
+This is a rarer use case where a controller instance is created manually in application logic, often for use without a corresponding view (e.g., a "headless" controller for managing application-wide logic).
+
+**Key Characteristics of "Before" Code:**
+
+* Uses `var oController = sap.ui.controller('my.name.space.ControllerName');`
+* The call is intended to immediately return a controller object.
+
+#### Migration Steps
+
+1. The modern replacement `Controller.create()` is **asynchronous** and returns a `Promise`. This is a critical change from the old synchronous API.
+2. Any code that relies on the controller instance must be placed within an `async` function and use the `await` keyword, or use the `.then()` Promise chain.
+3. The `Controller.create()` factory takes an object with a `name` property for the controller to be instantiated.
+
+#### Example: Controller Instance Migration
+
+**Before:**
+
+```js
+function createController() {
+    return sap.ui.controller('myApp.controller.Main');
+}
+const oController = createController();
+...
+```
+
+**After (using `async/await`):**
+
+The calling code must be adapted to handle the asynchronous operation.
+
+```js
+async function createController() {
+    return await Controller.create({name: "myApp.controller.Main"});
+}
+const oController = await createController();
+...
+```
+
+### Important Considerations for the Agent
+
+* **Do not confuse `extend` and `create`**. `extend` is for defining a controller class blueprint. `create` is for manufacturing an object from that blueprint. The vast majority of migrations will involve `Controller.extend`.
+* **Respect Asynchronicity:** When encountering `Controller.create`, the agent must recognize the shift from synchronous to asynchronous programming. Simply replacing the call is not enough; the surrounding logic must be adapted to wait for the `Promise` to resolve. This might involve converting the enclosing function to an `async` function.
+* **Base Controllers:** If a controller is already using `sap.ui.define` but extending a custom base controller, ensure the path to the base controller is correct in the dependency array and that the base controller itself is properly defined using `Controller.extend`.
+* For more information, search the UI5 documentation for the topic "Controller".

package/resources/migrationGuides/deprecated-getLibraryResourceBundle.md

@@ -0,0 +1,62 @@
+# Guide for Migrating `Core.getLibraryResourceBundle` to `Lib.getResourceBundleFor`
+
+> *This guide provides instructions for AI-based development tools to perform a critical API migration in SAPUI5 projects. The focus is on replacing the deprecated call `sap.ui.getCore().getLibraryResourceBundle` with the modern API `Lib.getResourceBundleFor`.*
+
+## 1. Core Concepts of the Migration
+
+The legacy method `sap.ui.getCore().getLibraryResourceBundle` provided access to a library's resource bundle. This API is deprecated in favor of a new API located in the `sap/ui/core/Lib` module.
+
+The migration involves three key changes:
+
+1. **Switching Modules:** Instead of accessing the global `Core` object, the dedicated `sap/ui/core/Lib` module must be imported.
+2. **Use the new API**: Replace any call of `sap.ui.getCore().getLibraryResourceBundle` with `Lib.getResourceBundleFor`.
+3. **Mandatory Library Name:** The new API requires a library name. The old API would default to `"sap.ui.core"` if no argument was provided. This case must be handled explicitly during migration.
+
+## 2. Migration Steps
+
+To replace the module, follow these steps:
+
+1. Import module `sap/ui/core/Lib` in the corresponding `sap.ui.define` dependency array.
+2. Replace `sap.ui.getCore().getLibraryResourceBundle` with `Lib.getResourceBundleFor`.
+    * **Explicitly Handle the Default Case:** If you encounter `getLibraryResourceBundle()` with no arguments, you **must** replace it with `Lib.getResourceBundleFor("sap.ui.core")`. Do not assume a default.
+    * **Validate the Library Name:** The provided name must refer to a standard UI5 library that includes a `manifest.json` file. The API does not support resolving resource bundles for sub-components of libraries or arbitrary module paths.
+    * Both APIs are synchronous, so no asynchronous handling needs to be added.
+
+#### Example: Library Name is Provided
+
+**Before:**
+
+```js
+sap.ui.define([
+    "sap/ui/core/mvc/Controller"
+], (Controller) => {
+    "use strict";
+
+    return Controller.extend("myApp.controller.Main", {
+        onSomeAction() {
+            var oResourceBundle = sap.ui.getCore().getLibraryResourceBundle("sap.m");
+            var sText = oResourceBundle.getText("myI18nKey");
+            // ...
+        }
+    });
+});
+```
+
+**After:**
+
+```js
+sap.ui.define([
+    "sap/ui/core/mvc/Controller",
+    "sap/ui/core/Lib" // <-- Add new dependency
+], (Controller, Lib) => { // <-- Add Lib to function arguments
+    "use strict";
+
+    return Controller.extend("myApp.controller.Main", {
+        onSomeAction() {
+            const oResourceBundle = Lib.getResourceBundleFor("sap.m");
+            const sText = oResourceBundle.getText("myI18nKey");
+            // ...
+        }
+    });
+});
+```

package/resources/migrationGuides/deprecated-jquery-sap-require.md

@@ -0,0 +1,141 @@
+# Guide for Migrating `jQuery.sap.declare` and `jQuery.sap.require`
+
+> *This guide provides instructions for AI-based development tools to migrate legacy SAPUI5 dependency management. The focus is on replacing the deprecated, synchronous functions `jQuery.sap.declare` and `jQuery.sap.require` with the modern, asynchronous `sap.ui.define` and `sap.ui.require` APIs. This migration is exclusively for JavaScript-based UI5 projects.*
+
+## 1. Core Migration Principles
+
+The legacy `jQuery.sap` namespace provided a synchronous way to declare modules and manage dependencies. This is now deprecated in favor of the standard Asynchronous Module Definition (AMD) syntax used by UI5, which improves performance and code modularity.
+
+The migration follows these key principles:
+
+1. **From `declare` to File-Based Modules:** `jQuery.sap.declare("my.module.name")` is obsolete. In modern UI5, the module's name is inferred from its path in the project structure. The `declare` statement should be removed entirely.
+2. **From `require` to `define` Dependencies:** Dependencies, typically listed at the top of a file with `jQuery.sap.require(...)`, must be converted into an array of dependencies in a `sap.ui.define` call.
+3. **Module Export:** The core object defined in the file (e.g., a controller, a helper class) must be the **return value** of the `sap.ui.define` factory function.
+4. **Dependency Notation:** The module name notation must change from dot-separated (`"sap.m.Button"`) to path-separated (`"sap/m/Button"`).
+5. **Dynamic Loading:** For dependencies required dynamically or conditionally (e.g. inside a function or if-clause), the global `jQuery.sap.require` is replaced by the asynchronous `sap.ui.require`.
+
+For more information, search the UI5 documentation on the topic "Modules and Dependencies".
+
+## 2. Pre-Migration Analysis: Rules for the Agent
+
+Before modifying a file, the agent must perform these checks to prevent incorrect migrations:
+
+* **Rule 1: Detect Existing `sap.ui.define`:**
+    * **Condition:** The file already contains a `sap.ui.define` wrapper.
+    * **Action:** Do **not** wrap the file again. Instead, find any remaining `jQuery.sap.require` calls within the file and merge their dependencies into the existing `sap.ui.define` array.
+* **Rule 2: Identify a Single, Clear Module Export:**
+    * **Condition:** The file contains multiple `jQuery.sap.declare` calls, or defines multiple distinct classes/objects at the top level (e.g., multiple `.extend` calls), or has no clear object to `return`.
+    * **Action:** **Abort migration for this file.** These complex legacy files require manual review. A valid candidate for migration typically has one primary purpose, such as defining a single controller or helper class.
+* **Rule 3: JavaScript Only:**
+    * **Condition:** The project or file is identified as TypeScript (`.ts`).
+    * **Action:** **Abort migration.** TypeScript uses standard ES module `import`/`export` syntax, and this migration logic does not apply.
+
+## 3. Migration Scenarios
+
+### Scenario A: Standard Module Definition (Most Common)
+
+This scenario covers files that declare a single module and its static dependencies. The goal is to convert the entire file into a `sap.ui.define` block.
+
+#### Example A.1: Legacy Module with `jQuery.sap.declare`
+
+**Before:**
+
+```js
+jQuery.sap.declare("my.app.util.Formatter");
+jQuery.sap.require("sap.ui.core.format.DateFormat");
+
+my.app.util.Formatter = { // Note: This is an example of creating a global object
+    formatDate: function(oDate) {
+        var oDateFormat = sap.ui.core.format.DateFormat.getDateTimeInstance();
+        return oDateFormat.format(oDate);
+    }
+};
+```
+
+**After:**
+
+The migration wraps the code, converts the dependency, and returns the Formatter object.
+
+```js
+sap.ui.define([
+    "sap/ui/core/format/DateFormat" // <-- Dependency converted to path notation
+], (DateFormat) => { // <-- Dependency passed as argument
+    "use strict";
+
+    // The object is now returned instead of being assigned to a global variable
+    return {
+        formatDate(oDate) {
+            const oDateFormat = DateFormat.getDateTimeInstance();
+            return oDateFormat.format(oDate);
+        }
+    };
+});
+```
+
+#### Example A.2: Legacy Controller Definition
+
+**Before:**
+
+```js
+// Note: Some legacy files might omit jQuery.sap.declare
+jQuery.sap.require("my.app.controller.BaseController");
+
+my.app.controller.BaseController.extend("my.app.controller.Main", {
+    onInit: function() {
+      // [...]
+    }
+});
+```
+
+**After:**
+
+The migration identifies the base class from the `.extend` call as a dependency.
+
+```js
+sap.ui.define([
+    "my/app/controller/BaseController" // <-- Dependency from .extend()
+], (BaseController) => {
+    "use strict";
+
+    // The result of the .extend() call is returned
+    return BaseController.extend("my.app.controller.Main", {
+        onInit() {
+          // [...]
+        }
+    });
+});
+```
+
+### Scenario B: Dynamic Dependency Loading
+
+This scenario applies when `jQuery.sap.require` is used inside a function to load a dependency on demand. This must be replaced with the asynchronous `sap.ui.require`.
+
+**Before:**
+
+```js
+// In some controller method...
+onOpenDialog() {
+    // Dependency is loaded synchronously just before it is needed
+    jQuery.sap.require("sap.m.MessageBox");
+    sap.m.MessageBox.show("This is a dynamically loaded message box!");
+}
+```
+
+**After:**
+
+The consuming function must be adapted to handle the asynchronous loading by using a callback.
+
+```js
+onOpenDialog() {
+    // Use sap.ui.require with a callback
+    sap.ui.require(["sap/m/MessageBox"], (MessageBox) => {
+        MessageBox.show("This is a dynamically loaded message box!");
+    });
+}
+```
+
+## 4. Post-Migration Step: Re-run UI5 Linter
+
+After the file is successfully wrapped in `sap.ui.define`, further detections as well as automated fixes may become possible.
+
+**Action:** Execute the UI5 linter again, if requested before, with the auto-fix functionality enabled again. It can often resolve further issues now that a proper module definition is in place.

package/resources/migrationGuides/deprecated-messagePage.md

@@ -0,0 +1,162 @@
+# Guide for Migrating the Deprecated `sap/m/MessagePage` Control
+
+> *This guide provides instructions for AI-based development tools to migrate the deprecated `sap.m.MessagePage` to the modern and more flexible `sap.m.IllustratedMessage` control.*
+
+## 1. Core Concept: From a Static Page to a Flexible Component
+
+The `sap.m.MessagePage` was a monolithic control designed to display a full-screen message. It is deprecated in favor of `sap.m.IllustratedMessage`, which offers a more flexible and modern user experience.
+
+The key differences are:
+* **Illustrations over Icons:** `IllustratedMessage` uses rich SVG illustrations (`illustrationType`) instead of simple font icons (`icon`).
+* **Structured Content:** Content is more structured. There is a dedicated slot for a description and an `additionalContent` aggregation for custom controls like buttons, which were previously handled by specific properties.
+* **Flexibility:** `IllustratedMessage` is not a full "page" but a component that can be used more flexibly within various layouts.
+
+## 2. Pre-Migration Analysis & Rules
+
+Before modifying code, the agent must verify the migration's feasibility.
+
+* **Rule 1: JavaScript Implementation Check**
+    * **Condition:** The `MessagePage` has complex custom logic associated with it in the controller that goes beyond simple property setting or event handling (e.g., dynamically replacing aggregations).
+    * **Action:** **Abort migration.** A complex implementation requires manual refactoring. This automated guide is intended for declaratively used or simply configured controls.
+
+## 3. Property and Aggregation Mapping
+
+This table provides the definitive mapping from `MessagePage` to `IllustratedMessage`. The agent must follow these rules precisely.
+
+| Old `MessagePage` Property/Aggregation | New `IllustratedMessage` Property/Aggregation | Migration Rule / Action                                                                                                                                                                                            |
+| :------------------------------------- | :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`                                | `title`                                       | **Direct Mapping:** Transfer the value directly.                                                                                                                                                                 |
+| `text` & `description`                 | `description`                                 | **Combine:** Concatenate the `text` and `description` properties, separated by a newline (`\n`). If only one is present, use it directly. Set the result to the new `description`.                                  |
+| `icon`                                 | `illustrationType`                            | **Semantic Mapping & Fallback:** Map the `sap-icon://` to a `sap.m.IllustratedMessageType` enum value. Use a generic fallback if no clear semantic match is found. See **Section 4** for mapping strategy. |
+| `titleLevel`                           | (Does not exist)                              | **Remove:** This property has no equivalent and must be removed.                                                                                                                                                   |
+| `showNavButton` & `navButtonPress`     | `additionalContent` aggregation               | **Create Button:** If `showNavButton` is `true` OR `navButtonPress` is defined, create a `sap.m.Button` inside the `additionalContent` aggregation. Assign the `navButtonPress` handler to the button's `press` event. |
+| `buttons` (aggregation)      | `additionalContent` aggregation               | **Move Content:** Move any controls from the `buttons` aggregation directly into the `additionalContent` aggregation.                                                                                      |
+| `customText` (aggregation)             | `additionalContent` aggregation               | **Move Content:** Move any controls from the `customText` aggregation directly into the `additionalContent` aggregation.                         |
+| `customDescription` (aggregation)      | `additionalContent` aggregation               | **Move Content:** Move any controls from the `customDescription` aggregation directly into the `additionalContent` aggregation.                                                                                      |
+
+## 4. Icon-to-Illustration Mapping Strategy
+
+The `icon` property (`sap-icon://...`) does not have a one-to-one mapping to `illustrationType`. The agent must use the following strategy:
+
+1. **Attempt Semantic Match:** Look for an illustration that matches the icon's meaning.
+2. **Use Fallback:** If no clear match is found, use a generic, context-appropriate illustration as a fallback.
+
+Use the `sap.m.IllustratedMessageType` enum to access the available illustrations. **Note:** In XML views, the string value of the enum needs to be used, e.g., `"sapIllus-Achievement"`.
+
+The following is a table of commonly used illustration types and their string value
+
+| Enum    | String Value  |
+| :--------------------- | :------------------------ |
+| sap.m.IllustratedMessageType.NoData   | `sapIllus-NoData` |
+| sap.m.IllustratedMessageType.NoEntries   | `sapIllus-NoEntries` |
+| sap.m.IllustratedMessageType.PageNotFound   | `sapIllus-PageNotFound` |
+| sap.m.IllustratedMessageType.UnableToLoad   | `sapIllus-UnableToLoad` |
+| sap.m.IllustratedMessageType.NoSearchResults   | `sapIllus-NoSearchResults` |
+| sap.m.IllustratedMessageType.KeyTask  (indicates the success of a task)  | `sapIllus-KeyTask` |
+
+Check the API reference of `sap.m.IllustratedMessageType` for the full list of available illustrations. Make sure not to use any that are marked as deprecated.
+
+## 5. Migration Scenario: XML View
+
+### Example
+
+This comprehensive example demonstrates the combination of text and the creation of the navigation button.
+
+**Before:**
+
+```xml
+<mvc:View
+  xmlns="sap.m"
+  xmlns:mvc="sap.ui.core.mvc">
+    <MessagePage
+        id="notFoundPage"
+        title="{i18n>notFoundTitle}"
+        text="{i18n>notFoundText}"
+        description="{i18n>notFoundDescription}"
+        icon="sap-icon://error"
+        showNavButton="true"
+        navButtonPress=".onNavBack" />
+</mvc:View>
+```
+
+**After:**
+
+```xml
+<mvc:View
+  xmlns="sap.m"
+  xmlns:mvc="sap.ui.core.mvc">
+    <IllustratedMessage
+        id="notFoundPage"
+        title="{i18n>notFoundTitle}"
+        description="{i18n>notFoundText} {i18n>notFoundDescription}"
+        illustrationType="sapIllus-NoData">
+        <!-- The navigation button is now explicitly created in additionalContent -->
+        <additionalContent>
+            <Button text="{i18n>backButtonText}" press=".onNavBack" />
+        </additionalContent>
+    </IllustratedMessage>
+</mvc:View>
+```
+
+## 6. Migration Scenario: JavaScript Instantiation
+
+### Example
+
+**Before:**
+
+```javascript
+sap.ui.define([
+    "sap/m/MessagePage",
+    "sap/ui/core/mvc/Controller"
+], (MessagePage, Controller) => {
+    "use strict";
+    return Controller.extend("my.app.Controller", {
+        createMyPage: function() {
+            const oPage = new MessagePage({
+                title: "An Error Occurred",
+                text: "The requested data could not be loaded.",
+                icon: "sap-icon://error",
+                showNavButton: true,
+                navButtonPress: this.onNavBack.bind(this)
+            });
+            return oPage;
+        }
+    });
+});
+```
+
+**After:**
+
+```javascript
+sap.ui.define([
+    "sap/m/IllustratedMessage",
+    "sap/m/Button",
+    "sap/m/library",
+    "sap/ui/core/mvc/Controller"
+], (IllustratedMessage, Button, mobileLibrary, Controller) => {
+    "use strict";
+
+    // For illustrationType enum
+    const { IllustratedMessageType } = mobileLibrary;
+
+    return Controller.extend("my.app.Controller", {
+        createMyPage: function() {
+            const oMessage = new IllustratedMessage({
+                title: "An Error Occurred",
+                description: "The requested data could not be loaded.", // text becomes description
+                illustrationType: IllustratedMessageType.UnableToLoad // Mapped from icon
+            });
+
+            // Button is created and added to aggregation
+            const oNavButton = new Button({
+                text: "Back", // Note: text must be provided
+                press: this.onNavBack.bind(this)
+            });
+
+            oMessage.addAdditionalContent(oNavButton);
+
+            return oMessage;
+        }
+    });
+});
+```