generator-mtaproject

Features

The MTA Project generator provides a single entry point to generate a fully configured, deployable SAP CAP MTA project — including a sample data model, SAP Fiori applications, SAP BTP security configuration, multi-target Cloud Foundry deployment, GitHub Actions CI/CD pipelines, and an optional MCP server for AI-assisted data queries.

The generator is built on top of Yeoman, @sap/cds-dk and @sap/generator-fiori, and orchestrates these tools into one guided, question-based workflow.

Overview

• Choose between a Full MTA (HANA-backed) and a Lean MTA (HANA-free, no persistent database — for subaccounts without hana-td) right at the start of the wizard
• Freely configurable project name
• Optional sample schema, data and CAP service, with a ready-to-use sample data model (ID, title, author, stock, price, currency, genre, publishedDate, discontinued)
  • In Lean mode, the sample entity is generated as a virtual (@cds.persistence.skip) entity backed by an in-memory JavaScript handler instead of a database table
• Optional services with sample roles (user, admin), with mock users in package.json
• Optional cds add components (Full mode):
  • hana
  • xsuaa (with XSAPPNAME and tenant mode)
  • html5-repo
  • mta (with optional srv-api destination and xs-app.json destination check)
  • workzone-standard
  • approuter (with automatic xs-app.json generation)
• Generate any number of SAP Fiori apps using the official @sap/fiori generator
  • Optional CSRF protection activation across all generated apps
  • Optional sample UI5 view with a table bound to the sample OData service
  • Automatic detection and correction of OData version 4.01 in manifest.json
• Optional MCP server for the sample service, with a ready-to-use opencode configuration for local, natural-language data queries
• Automatic deployment to multiple SAP BTP / Cloud Foundry targets (org/space)
  • Interactive multi-select of which configured targets to build and deploy for
  • SSO or username/password login, shared or per-target credentials
  • Automatic sanitization of organization names containing spaces when building the XSUAA xsappname per target (spaces are replaced with underscores)
  • Automatic redeploy after redirect URIs are added to xs-security.json
• Automatic maintenance of redirect URIs in xs-security.json
• Automatic generation of a project README.md containing service URLs, application URLs, target-specific information, and next steps
• Configuration files can be saved and reused later (--configFile)
• Create multiple GitHub Actions workflow files for CI/CD deployment to SAP BTP/Cloud Foundry via GitHub-hosted runners
  • Fail-fast Cloud Foundry login before the build step, with annotated error reporting
  • timeout-minutes safety net and per-target concurrency group
  • Tool version output (cf --version, mbt --version) for easier troubleshooting
• secrets.sh / secrets.ps1 scripts to create GitHub secrets via the GitHub CLI
• Guided local Git repository initialization (git init, add, initial commit)
• Guided GitHub repository creation via the GitHub CLI (gh), including organization selection, visibility, secret creation, push, and watching the triggered workflow run

Prerequisites

The following tools must be installed and available on your PATH:

• Node.js
• Yeoman — npm install -g yo
• SAP CDS Development Kit — npm install -g @sap/cds-dk
• SAP Fiori generator — npm install -g @sap/generator-fiori
• Cloud Foundry CLI (cf), logged in to your target SAP BTP subaccount
• MTA Build Tool (mbt) — npm install -g mbt
• MultiApps CLI Plugin for cf deploy
• (optional, for the GitHub integration steps) GitHub CLI (gh), authenticated via gh auth login
• (optional, only if you plan to query the sample service through natural language) opencode — see Installing opencode below

npm install -g yo
npm install -g @sap/cds-dk
npm install -g @sap/generator-fiori

Windows only: make must be installed, otherwise the generator will fail during mbt build, before deployment can happen.

A dedicated video tutorial showing how to install the required SAP CLI tools is available here: youtu.be/4gPXgPQLRsg

Installing opencode

opencode is an open-source, terminal-native AI coding agent with built-in MCP support (official site · official GitHub repository). It is entirely optional and only needed if you want to query the generated sample service using natural language.

# macOS or Linux (Homebrew)
brew install opencode

# Windows (Chocolatey)
choco install opencode

# Windows (winget)
winget install opencode-ai.opencode

# Any OS (npm)
npm install -g opencode-ai@latest

An official Visual Studio Code extension is also available. It does not run opencode inside VS Code itself — it simply opens and controls opencode inside a VS Code-integrated terminal panel. Because of that, running opencode directly in any terminal (integrated or standalone) gives you the exact same experience without installing the extension.

Installation

Install the generator globally from npm:

npm install -g generator-mtaproject

After installation, verify that Yeoman recognizes the generator:

yo

Make sure mtaproject is listed among the available generators.

Launch the generator

Start a new project

yo mtaproject

Reuse a previously saved configuration

yo mtaproject --configFile <saved-config-file>

Example:

yo mtaproject --configFile myproject-config.json

Note: Input prompts may occasionally not accept keystrokes right away. If this happens, press Enter once — input then works normally. If the generator appears stuck for more than a minute, the terminal may have been paused by an accidental keypress; press Backspace a few times, or Enter once, to resolve this.

Generator Wizard Steps

1. Project mode

The very first question decides the overall architecture of the project:

• Full MTA — includes a HANA database, the sample schema, and a persisted sample service. This is the classic, full-featured mode.
• Lean MTA — skips HANA and the database schema entirely. Intended for SAP BTP subaccounts that don't have a hana-td (Trial/Free-Tier) plan available, since HANA typically incurs cost. The sample service still works exactly the same from an OData/Fiori perspective — it is simply backed by an in-memory JavaScript handler (@cds.persistence.skip entities) instead of a database table.

Choosing Lean MTA automatically skips the HANA question later in the wizard; every other question (roles, XSUAA, Fiori apps, deployment, GitHub Actions, MCP server) remains available exactly as in Full mode.

2. Project settings

• Project name — Required. Must not already exist in the current folder.
• Sample schema, data and service — Optional. If enabled, further asks for:
  • Service name (e.g. Catalog) — letters, numbers, -/_ only, must not start with a digit
  • Entity name (e.g. Books)
  • DB namespace (e.g. my.bookshop) — only asked in Full mode
  • A sample entity with ID, title, author, stock, price, currency, genre, publishedDate and discontinued fields is generated, along with matching sample data (in Full mode as a CSV file under db/data/, in Lean mode as an in-memory array in the service handler)

3. Roles & mock users

• Add services with sample roles (user, admin) — Optional. Generates a role-aware service definition instead of the plain version, and automatically enables XSUAA (see below). The user role gets read-only access; the admin role gets full CRUD access (including delete, which is explicitly restricted for the user role via OData capability annotations).
• Add mock users for your roles in package.json — Optional. If enabled:
  • Password for the mock user and admin accounts
  • Option to assign both user and admin roles to the mock admin account
  • Automatically configures cds.requires.auth for [development] (mocked) and [production] (XSUAA)

4. SAP BTP building blocks

(Full mode only, except XSUAA/HTML5 Repository/App Router/MTA which apply to both modes)

• HANA DB — Adds cds add hana --for production. Skipped automatically in Lean mode.
• XSUAA Security — Adds cds add xsuaa --for production; automatically forced on if roles were added in step 3
  • XSAPPNAME
  • Tenant mode: Shared or Dedicated
  • Organization names containing spaces are automatically sanitized (spaces replaced with underscores) when the resulting xsappname is written into mta.yaml for each deployment target
• HTML5 Repository — Adds cds add html5-repo
• MTA descriptor — Adds cds add mta
  • Destination for the OData service — Adds a srv-api destination entry to mta.yaml
  • Check/correct xs-app.json destinations — Ensures all generated Fiori apps route OData calls through srv-api
• SAP Work Zone standard modules — Adds cds add workzone-standard
• App Router — Adds cds add approuter; generates app/router/xs-app.json automatically if both HTML5 Repository and XSUAA are enabled

5. SAP Fiori applications

The generator repeatedly launches the official @sap/fiori generator, so you can add as many applications as you need — SAP Fiori Elements or SAPUI5 freestyle, all OData V4.

After the Fiori apps have been generated:

• CSRF protection — Optional, activates csrfProtection: true on all XSUAA-authenticated routes in every generated app's xs-app.json
• Sample view with a table — Optional, for freestyle UI5 apps, inserts a ready-to-use list view showing all fields of the sample OData entity
• OData 4.01 check & auto-correction — Detects and optionally corrects manifest.json files that declare OData version 4.01 (known to cause issues with SAP Build Work Zone) back to 4.0

6. MCP server & opencode integration

Optional. Applies to both Full and Lean mode.

The generator can add an MCP server on top of your sample service, exposing it as a tool that AI agents such as opencode can query using natural language.

• Add an MCP server for the sample service — Optional. Generates the MCP-enabled CDS annotation for your service, using @cap-js/mcp.
• Generate an opencode.json configuration — Optional. Writes an opencode.json file into the project root, pre-configured for the default local cds watch address (http://localhost:4004).

Local use only. The generated opencode.json is configured for local cds watch testing only. If your local server runs on a different port or host, you'll need to adjust opencode.json manually. This configuration does not apply to the deployed Cloud Foundry version of your service — the deployed MCP endpoint is protected by XSUAA, which opencode does not support out of the box as a client authentication method. The deployed MCP server can still be safely consumed by other services running securely within your BTP subaccount (e.g. a future internal AI agent or automation service that can perform an XSUAA-authenticated call).

About the MCP service annotation: The CDS file that exposes your service via MCP also carries a natural-language instruction/description for the AI agent — this is where you describe what the exposed data means, and can add explicit exclusion rules for sensitive or irrelevant fields. For example:

service CatalogService @(
  mcp: {
    name: 'catalog',
    description: 'Lists all books in the catalog, including stock, price and genre. Do not reveal the author field in any response.'
  }
)

This lets you shape what the AI agent is allowed to surface from the data, without having to remove or hide the field from the service itself.

Example prompts, once opencode is running inside the generated project:

What are the 3 most expensive books?

Create a list of books that need to be reordered so that every book still in
production (i.e. not discontinued) has at least 20 units in stock.

Which genres are represented in the catalog, and how many books are in each?

Note: Each natural-language prompt typically results in two requests to your local server: one to fetch the service's MCP description/instructions (so the agent understands what the data means and which fields are off-limits), and a second one to actually query the data needed to answer the question.

7. Cloud Foundry deployment targets

• Auto deployment to Cloud Foundry — Optional. If enabled:
  • Same credentials for every target? — Use one cf login for all targets, or per-target credentials
  • Login method — SSO (browser-based) or username/password, with optional custom API endpoint
  • Target selection — Interactively choose one or more Org/Space combinations from cf orgs / cf spaces; already-configured spaces are filtered out automatically
  • Which targets to build for — When multiple deployment targets are configured, select which of them to actually build and deploy for in this run via a multi-select prompt
  • Redeploy after redirect URI update — After the first deployment, the generator writes the resulting app routes into xs-security.json as redirect URIs. Optionally triggers a second, automatic deployment so the XSUAA service picks up the updated redirect URIs. Defaults to off if GitHub Actions is also enabled, since the CI/CD pipeline will handle this instead.

8. GitHub Actions CI/CD

• Add GitHub Actions workflow for deployment — Optional. For each configured deployment target, you can define:
  • Workflow name and filename
  • Target branch (default main)
  • Cloud Foundry API endpoint and Node.js version (shared across all workflows)
  • GitHub secret names for the Cloud Foundry username and password

Each workflow file is generated under .github/workflows/ and:

• Runs on ubuntu-latest, with a timeout-minutes safety net and a concurrency group per org/space (queues overlapping deployments instead of cancelling or running them in parallel)
• Is clearly structured into three phases: container setup (checkout, Node.js, Java, Cloud Foundry CLI, MultiApps plugin), deployment prep (Cloud Foundry login, npm ci, mbt install), and deployment (mbt build + cf deploy)
• Performs the Cloud Foundry login first, before the (potentially long) build step — so a bad credential fails fast instead of wasting build time
• Reports a clear, annotated error if the login step specifically fails, pointing at the two secret names to check
• Prints a short success confirmation after deployment completes

Example generated workflow (simplified):

# Auto-generated by generator-mtaproject — safe to edit, not overwritten on regeneration
name: Deploy to my-org - PROD
on:
  push:
    branches: [ "main" ]
  workflow_dispatch:
concurrency:
  group: deploy-my-org-PROD
  cancel-in-progress: false
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v5
      # ... Node.js, Java, Cloud Foundry CLI, MultiApps plugin ...
      - name: Cloud Foundry login
        id: cf_login
        run: cf login -a https://api.cf.eu10.hana.ondemand.com -o my-org -s PROD ...
      - name: Report login failure
        if: steps.cf_login.outcome == 'failure'
        run: echo "::error::Cloud Foundry login failed. Check that the secrets CF_USERNAME and CF_PASSWORD are set correctly."
      # ... npm ci, mbt build --mtar archive.mtar ...
      - name: Deploy
        run: cf deploy mta_archives/*.mtar
      - name: Deployment successful
        run: echo "✅ Deployment to org my-org, space PROD completed successfully."

9. Git & GitHub repository setup

If the GitHub CLI is detected on your machine, the generator offers to finish the loop end-to-end:

• Create a local Git repository — git init, git add ., and an initial commit (custom commit message, default Initial Commit). The commit includes the full generated README.md.
• Create a GitHub repository — Choose an organization from gh org list (or -no organisation- for your personal account), pick a repository name, and choose public/private. Runs gh repo create <name> --source=. --private|--public.
• Create the GitHub secrets now — Runs gh secret set <name> for each Cloud Foundry username/password secret referenced by your workflows.
• Push and watch — Optionally git push right away, with a note that this may trigger an immediate CI/CD deployment, followed by an optional gh run watch to follow the triggered workflow run live.

Regardless of your answers above, secrets.sh (bash) and secrets.ps1 (PowerShell) are always generated, so the GitHub secrets can be (re-)created manually at any time using the GitHub CLI:

./secrets.sh

If the GitHub CLI is not available, the generator simply lists the required secret names for you to create manually in the repository settings.

Useful gh commands for the generated project

Beyond what the generator runs for you automatically, these gh commands are useful for day-to-day work on the generated repository and its CI/CD pipeline:

| Command | Purpose | |---|---| | gh run watch | Watch the most recent workflow run live in your terminal | | gh run view | Pick a run from a list and view its details | | gh run view --web | Open a workflow run in the browser | | gh run list | List recent GitHub Actions runs | | gh repo view --web | Open the repository in the browser | | gh repo create <name> --private | Create a new GitHub repository (use --public for a public one); add an org prefix, e.g. SUPORTIS-AG/<name>, to create it under an organization | | gh repo create <name> --source=. --private --push | Create a repository from the current folder, including remote setup and an initial push | | gh repo delete <name> | Delete a GitHub repository | | gh secret set <name> | Create or update a repository secret |

Configuration Files

At the end of the prompting phase, you can save your answers to a JSON configuration file:

yo mtaproject --configFile customer-a-config.json

Benefits:

• Reuse a configuration to regenerate an equivalent project later
• Standardize project setups across a team
• Resume a generator run that was interrupted partway through — already-answered questions are skipped on the next run with the same config file

What gets generated

Project structure

• Full CAP project (db/, srv/, app/), MTA descriptor (mta.yaml), and (if selected) xs-security.json
  • In Lean mode, db/ contains no schema — the sample entity lives entirely in srv/
• One or more SAP Fiori applications under app/
• opencode.json — MCP client configuration for local testing, if the MCP server option was selected
• .github/workflows/*.yml — one CI/CD workflow per deployment target
• secrets.sh / secrets.ps1 — helper scripts to (re-)create GitHub secrets
• README.md — project-specific documentation (see below)

Auto-generated project README.md

The generated project's own README.md (not this file — the one inside your new project) includes:

• Deployed routes per target
• Application IDs of all generated Fiori apps
• Full service and application URLs per target
• A Next Steps section covering role-collection assignment, Elements/UI5 app customization, Work Zone Launchpad configuration, redeployment, and a checklist of files worth customizing (xs-security.json, mta.yaml, manifest.json, package.json, per-app readme.md)
• The list of GitHub Actions workflows and the GitHub secrets they expect

Hints

At the end of a run, the generator prints hints relevant to your choices, e.g.:

• A reminder to protect app/router/xs-app.json manually if you added an App Router without HTML5 Repository or XSUAA
• A reminder that role collections need to be assigned to users, since roles were configured
• A reminder to check OData version 4.01 occurrences if you chose not to auto-correct them
• How to reuse your saved configuration file

Technologies

• Node.js
• Yeoman
• SAP CAP
• SAP HANA (Full mode)
• SAP BTP / Cloud Foundry
• SAP Fiori / SAPUI5
• MTA / MultiApps CLI Plugin
• XSUAA
• App Router
• MCP (@cap-js/mcp) / opencode
• GitHub Actions
• GitHub CLI (gh)

License

MIT

History

• 0.1.1 — Initial release with core features
• 0.1.2 — Automatic deployment and redirect URI maintenance
• 0.1.3 — CI/CD push to npmjs.com
• 0.1.4 — Bugfixes (logs, deployment), add README
• 0.1.5 — Use console.log() instead of this.log() for better output formatting
• 0.1.6 — Service name adjustment, roles (xs-security.json and service), mock users in package.json
• 0.1.7 — Bugfixes (redirect URIs without App Router), OData version 4.01 check in manifest.json
• 0.1.8 — Destination for OData service in mta.yaml, sample UI5 view, Next Steps in generated project README
• 0.1.9 — Renamed role collections in mta.yaml
• 0.1.10 — CI/CD fixes
• 0.1.11 — Already-selected spaces are filtered out when choosing further deployment targets
• 0.1.12 — Automatic redeployment after adding redirect URIs to xs-security.json
• 0.1.13 — Additional console output
• 0.1.14 — GitHub Actions workflow file generation
• 0.1.15 — secrets.sh / secrets.ps1 for creating secrets via the GitHub CLI
• 0.1.16 — Git init and GitHub repository & secrets creation
• 0.1.17 — Use v5 actions for Node.js & Java (Node.js 24 support)
• 0.1.18 — Initial commit now includes the complete README.md; notes on resuming an interrupted generator run
• 0.1.19 — Optimized GitHub Actions workflow: fail-fast Cloud Foundry login, timeout-minutes, concurrency group, tool version output, English step names, git push + gh run watch follow-up
• 0.2.1 — Two project modes (Full and Lean), bugfix (deployment target selection), sanitized organization names (spaces replaced) in xsappname per target in mta.yaml, workflow file fix
• 0.2.2 — Added optional MCP server for the sample service, with generated opencode.json for local natural-language queries
• 0.2.3 - New Readme