UI5 Version Upgrade

A migration workflow for SAPUI5/OpenUI5 projects. Use two MCP servers together:

• `mcp-sap-docs` provides ui5_version_diff, backed by a local ui5-lib-diff all-changes JSON bundle. It answers "what changed between versions?" and includes SAPUI5 What's New entries for the same range.
• SAP `@ui5/mcp-server` runs against the local project. It answers "what does this app use and what is broken?"

Do not scrape the ui5-lib-diff browser route for JSON. The browser URL with versionFrom, versionTo, and ui5Type is client-rendered. Use ui5_version_diff; it reads the local all-changes.json bundle and returns all matching structured entries. npm run setup refreshes the bundle automatically; if it is missing or stale, refresh it during setup/rebuild with npm run download:ui5-lib-diff or point UI5_LIB_DIFF_BUNDLE_PATH to a local copy. The runtime is local-only and must not rely on external requests.

UI5 MCP tools to use

Current SAP @ui5/mcp-server capabilities include:

• get_project_info: read project metadata and UI5 configuration.
• get_version_info: retrieve UI5 framework version information.
• get_guidelines: fetch UI5 coding standards and best practices.
• get_api_reference: fetch UI5 API documentation for controls/classes/methods.
• run_ui5_linter: run @ui5/linter against the app.
• run_manifest_validation: validate webapp/manifest.json.
• get_typescript_conversion_guidelines: guidance for JavaScript-to-TypeScript UI5 work.
• create_ui5_app, create_integration_card, get_integration_cards_guidelines: scaffolding/card-specific work. Use only when the user asks for creation or card work.

Inputs

Determine these before producing recommendations:

1. Project root: required for UI5 MCP project tools.
2. Current version (from_version): prefer get_project_info / get_version_info; otherwise read webapp/manifest.json, ui5.yaml, and package.json.
3. Target version (to_version): ask if absent. Use the full x.y.z form.
4. Library flavor: use SAPUI5 if the app depends on commercial libraries such as sap.ui.comp, sap.suite.*, sap.fe, sap.ui.mdc, or FLP/ushell; otherwise use OpenUI5.
5. Declared UI5 libraries: read sap.ui5.dependencies.libs and use them to focus feature/fix review.

Workflow

1. Establish scope

Call:

ui5_version_diff(library, from_version, to_version)

Summarize versionsInRange, counts, totalEntries, whatsNewTotalEntries, and any meta.notes. Keep meta.sourceDataPath and meta.generatedAt for traceability and stale-bundle checks. If the user asks about one release, call ui5_version_diff(library, version=<x.y.z>).

2. Get project facts

Call:

get_project_info(projectPath=<project root>)
get_version_info(projectPath=<project root>)
get_guidelines()

Use get_guidelines once per workflow to anchor coding recommendations. Do not repeatedly fetch broad guidelines inside loops.

3. Find deprecations actually used

Call:

ui5_version_diff(library, from_version, to_version, types=["DEPRECATED"])
run_ui5_linter(projectPath=<project root>)

Cross-reference diff deprecations with linter findings and code search. Report only confirmed or strongly suspected usage in the app. Skip deprecations that do not match the project.

For confirmed APIs, call:

get_api_reference(name=<control/class/method>)

Use this for replacement details. Do not invent replacements from memory.

4. Find removable workarounds

Search project comments and code for TODO, FIXME, workaround, BCP/ticket IDs, and symptom words. For each meaningful symptom:

ui5_version_diff(library, from_version, to_version, types=["FIX"], query=<symptom>)

If there is a matching fix, cite the entry and commit URL, then verify whether the local workaround can be removed safely.

5. Surface relevant features

For each declared UI5 library:

ui5_version_diff(library, from_version, to_version, types=["FEATURE"], ui5_library=<declared lib>)

Keep this selective. Mention features that plausibly affect the app's libraries or current code, not every framework feature.

6. Validate manifest and rerun after edits

Call:

run_manifest_validation(manifestPath=<project root>/webapp/manifest.json)
run_ui5_linter(projectPath=<project root>)

After making fixes, rerun the linter and manifest validation. Treat these tool results as stronger evidence than general release-note text.

Output

Default to one concise Markdown report:

1. Scope: flavor, from/to or single version, versions covered, counts, What's New count, source data path.
2. Required fixes: deprecated API, replacement, file:line, evidence.
3. Workarounds to remove: local workaround, matching UI5 fix, commit URL.
4. Relevant features and What's New: grouped by used UI5 library or product area.
5. Manifest and linter status: pass/fail with actionable details.
6. Edit plan: concrete changes in order.

Keep raw diff output out of the report. The tool returns all matching entries; if the result is broad, make narrower follow-up calls with types, ui5_library, or query.

Guardrails

• Prefer exact x.y.z versions. If a requested patch is unavailable, ui5_version_diff resolves it to the nearest lower available patch with the same major.minor, matching the ui5-lib-diff web app.
• For ranges, use (from_version, to_version]. For one release, use version=<x.y.z> or pass only one version field.
• If meta.notes says the requested release is newer than the local bundle, do not attempt runtime web fetches. Tell the user the setup-time bundle is stale and should be refreshed before relying on that release.
• Do not run scaffolding tools (create_ui5_app, create_integration_card) unless the user requested creation.
• Do not run project-local UI5 MCP tools without a real project path.
• Do not present every deprecation as required work. The app must use it, or the linter/code search must make it relevant.
• Prefer structured tool results and targeted filtered calls over passing broad intermediate lists through the model.

Fallbacks

• If SAP @ui5/mcp-server is unavailable, proceed with degraded coverage: use ui5_version_diff, local file inspection, and rg across webapp/**/*.{js,ts,xml,json}. Tell the user which UI5 MCP checks were skipped.
• If ui5_version_diff reports that the local bundle is missing or stale, refresh the bundle during setup/rebuild with npm run download:ui5-lib-diff in the MCP server repo or point UI5_LIB_DIFF_BUNDLE_PATH to a local copy.
• If no versions match, check version spelling and patch-level availability before concluding that there were no changes.