SAP Developers MCP

SAP Tutorial Platform

A tutorial hosting platform for developers.sap.com that replaces both Adobe Experience Manager (AEM) and the legacy Java IMS backend. Fetches tutorial markdown from the sap-tutorials GitHub organization at build time, renders static pages with SAP Fundamental Styles (Horizon theme) via Hugo, and deploys on SAP BTP Cloud Foundry behind an AppRouter with XSUAA authentication. The CAP Node.js backend provides progress tracking, event management, and all services previously handled by the Spring Boot IMS application.

Production system replacing AEM tutorial hosting, Git-based authoring interface, and Java IMS backend on developers.sap.com (April 2026).

Stack: Hugo · CAP Node.js (CDS 9.x) · SAP HANA Cloud · SAP Fundamental Styles · Vue 3 (apps) · TypeScript · SAP BTP Cloud Foundry

Folder Map

tutorials-ims/
├── approuter/                  # BTP AppRouter — serves static files + proxies to CAP via XSUAA auth
│   ├── server.js               #   Custom AppRouter wrapper (VCAP merge, serve-static, proxy fixes)
│   ├── static/                 #   Pre-built assets deployed to CF
│   │   ├── admin-ui/           #     Admin shell (sap.tnt.ToolPage) + 11 Fiori Elements components
│   │   ├── analytics-ui/       #     Analytics Explorer Vue 3 SPA bundle
│   │   ├── scanner-ui/         #     UI5 barcode scanner bundle
│   │   ├── scanner-vue/        #     Vue 3 barcode scanner bundle
│   │   ├── display-app/        #     Display App SPA bundle (event monitor dashboard)
│   │   ├── qa/                 #     QA-channel Hugo build (gated by Tutorial.Author scope)
│   │   ├── css/img/js/         #     Global stylesheets, images, shared JS injected into Hugo pages
│   │   └── (no tutorials/)     #     Tutorials served dynamically from HANA, not static files
│   └── xs-app.json             #   Route definitions (/admin-ui, /analytics-ui, /scanner-*, /tutorials, /tutorials-qa, /api, /admin, /display, /chat, /search, /build, /content)
├── app/                        # Standalone UI applications (UI5 + Vue, deployed to approuter/static/)
│   ├── admin-shell/            #   sap.tnt.ToolPage shell with side navigation + theme switching
│   ├── admin/                  #   11 Fiori Elements feature components (events, missions, groups,
│   │                           #   accomplishments, prizes, tutorials, tags, operations, accounts,
│   │                           #   changelog, joule, feedback, analytics) loaded by the shell
│   ├── analytics-explorer/     #   Vue 3 + Vite + Monaco SQL editor over AnalyticsService
│   ├── scanner/                #   UI5 barcode scanner (sap.ndc.BarcodeScanner)
│   ├── display-app/            #   Standalone event monitor dashboard (Vue 3 + Vite, Socket.IO)
│   ├── admin-annotations.cds   #   @UI/@Common annotations for all admin screens
│   └── change-tracking.cds     #   @cap-js/change-tracking config for admin entities
├── hugo-apps/                  # Vue 3 page-level islands compiled into Hugo's static JS (output: hugo/static/js/)
│   └── src/                    #   9 entry points: navigator, app-space, event-display, nav-dropdown,
│       │                       #   scanner-vue, tutorial-feedback, tutorial-rating, cmd-palette, me
│       └── shared/             #   Shared utilities, API client, types
├── hugo/                       # Hugo static site generator — tutorial pages + layouts
│   ├── assets/css|js/          #   PostCSS pipeline (Fundamental Styles Horizon) + page-level JS
│   │                           #   includes ui5-bootstrap.ts (UI5 Web Components shellbar/dialog/etc.)
│   ├── config/                 #   Hugo configuration (hugo.toml, environment overrides)
│   ├── content/
│   │   ├── tutorials/          #     Generated tutorial markdown (gitignored, from fetch-tutorials)
│   │   ├── missions/           #     Generated mission overview pages
│   │   └── groups/             #     Generated completion-path pages
│   ├── data/                   #   Site-level data files (glossary, etc.)
│   ├── i18n/                   #   en_us only (developers.sap.com is English-only)
│   └── layouts/                #   _default, tutorials, missions, groups, partials, shortcodes
├── hugo.qa.toml                # Sibling Hugo config for QA channel (strips Joule FAB, rating, etc.)
├── preview-site/               # Hugo preview-site renderer (used by srv-qa preview path)
├── db/                         # Production CAP data model — CDS schema + HANA native artifacts
│   ├── schema.cds              #   Entity definitions (Users, Tutorials, Missions, Events, etc.)
│   ├── views.cds               #   CDS views (NavigatorCatalog, SearchableItems, CompletionAnalytics, …)
│   ├── persistence.cds         #   ContentFiles + ContentManifest (gzip-compressed tutorial BLOBs)
│   ├── audit-logging.cds       #   @PersonalData annotations (Users, UserMetaData, TaskRecords)
│   ├── change-tracking.cds     #   @cap-js/change-tracking annotations
│   ├── schema-ext.cds          #   Service-layer schema extensions
│   └── src/                    #   Native HANA artifacts (.hdbsequence for legacy integer IDs)
├── db-qa/                      # QA-channel HDI container schema (peer of db/, deploys to tutorials-hana-qa)
├── srv/                        # CAP Node.js backend — production services
│   ├── server.js               #   Bootstrap: registers Express routes + jobs on cds.on('served')
│   ├── *-service.cds + .js     #   9 services: developer, admin, analytics, exports, display,
│   │                           #     consolidation, scanner, search, chat, event-stream
│   ├── ord-annotations.cds     #   Open Resource Discovery registration for all services
│   ├── handlers/               #   Express route handlers (recommendations.js)
│   ├── exports/                #   ExportsService backends (CSV/zip, XLSX, task records, etc.)
│   ├── lib/                    #   Shared business logic (~40 modules):
│   │                           #     content-store (HANA BLOB serve), embedding-* (RAG), chat-* (Joule),
│   │                           #     accomplishment-evaluator, account-merge, build-catalog,
│   │                           #     navigator-catalog, recommend, co-completion, status-calculator,
│   │                           #     mail-client, ngds-client, adobe-analytics, qrcode-handler,
│   │                           #     analytics-sql-validator (SELECT-only allowlist for runSelectQuery),
│   │                           #     feedback-salt, ip-rate-limit, ttl-cache, pipeline-log, …
│   ├── jobs/                   #   Scheduled tasks: scheduler, account-merge, cleanup,
│   │                           #     ngds-retry, embedding-reconciliation, job-lock (distributed)
│   └── templates/notification/ #   Email HTML templates (Handlebars)
├── srv-qa/                     # QA-channel CAP app (peer of srv/, deploys to tutorials-srv-qa)
│   ├── server.js               #   Mounts xsuaa-scope-middleware (Tutorial.Author gate) + preview renderer
│   └── search-service.cds      #   QA-only search projection
├── scripts/                    # Build-time scripts — fetch, parse, publish, migrate, seed
│   ├── fetch-tutorials.ts      #   Main entry: fetches markdown from GitHub, generates Hugo pages
│   ├── publish-content.ts      #   Delta-publish Hugo HTML → HANA BLOBs via /content/publish
│   ├── parsers/                #   Markdown pipeline: v1 (legacy ACCORDION) + v2 (H3) + images,
│   │                           #     options, cap, github, rules, sanitize-html, hugo-delimiters, types
│   ├── grammars/               #   TextMate grammars for syntax highlighting
│   ├── highlight-cds.ts        #   CDS syntax highlighter
│   ├── install-qa-workflows.ts #   Distribute notify-qa.yml workflow to all -Contribution repos
│   ├── verify-qa-build.ts      #   Post-build verification of QA Hugo output
│   ├── check-qa-schema-drift.ts#   Compare prod vs QA HDI schemas (CI step)
│   ├── setup-dev-data.cjs      #   Slug population + autotest cleanup against DEV HANA
│   ├── seed-*.cjs / seed-*.js  #   Various data seeding scripts
│   ├── migrate-reference-data.js   # Export/import tutorials, missions, events from Java IMS
│   ├── migrate-user-progress.js    # Export/import user progress (paged, resumable)
│   ├── migrate-from-hana.js        # Direct HANA-to-HANA migration
│   └── compare-systems.js      #   Endpoint-by-endpoint diff between Java IMS and CAP
├── test/                       # Vitest workspaces (unit, hybrid, hybrid-qa, smoke)
│   ├── unit + integration/     #   In-memory SQLite, fast, no external deps (npm test)
│   ├── lib/ + jobs/ + parsers/ #   Module-level unit tests
│   ├── hybrid/                 #   Real HANA Cloud via cds bind --exec (npm run test:hybrid)
│   ├── hybrid-qa/              #   Hybrid tests against QA HDI
│   ├── smoke/                  #   HTTP smoke tests against deployed URLs (npm run test:smoke)
│   ├── srv-qa/                 #   QA-srv-specific tests (preview, scope middleware)
│   └── a11y/                   #   Accessibility tests
├── docs/                       # Architecture references and developer documentation
│   ├── pilot-status.md         #   Pilot completion + locked production scope
│   ├── testing-endpoints.md    #   Canonical UI + API endpoint reference (auth/scope mapping)
│   ├── production-ready.md     #   Go-live checklist
│   ├── theme-variants.md       #   Building event-specific theme variants (Joule, Sapphire, TechEd)
│   ├── qa-channel-bootstrap.md #   One-time QA author-preview channel setup
│   ├── content-pipeline.md     #   Fetch → parse → Hugo → HANA pipeline deep-dive
│   ├── authentication-architecture.md, mta-deployment.md, hugo-migration.md, ai-consumption.md, …
│   ├── improvements.md, TODO.md#   Feature backlog and gap tracking (largely historic)
│   └── superpowers/specs/+plans/ # Feature specs and step-by-step implementation plans
├── .deploy/                    # MTA build + deploy artifacts
│   ├── mta.yaml                #   Main MTA descriptor (modules: approuter, srv, srv-qa, db, db-qa, destinations)
│   ├── xs-security.json        #   XSUAA scopes + role collections (Admin, MobileApp, Tutorial.Author)
│   ├── deploy-admin.sh         #   Standalone admin UI deploy helper (bypasses MTA build)
│   └── DEPLOY.md               #   Deploy procedure documentation
├── mta-mcp.yaml                # Separate MCP MTA descriptor (tutorials-mcp → module tutorials-srv-mcp, serves /mcp-auth/*; adopts main-MTA services)
├── deploy/                     # MTA extension descriptors (environment overrides)
│   ├── dev.mtaext              #   Main-MTA development overrides (instance counts, memory, srv-mcp-url)
│   ├── qa.mtaext               #   QA/staging overrides
│   ├── prod.mtaext             #   Production overrides
│   ├── mcp-dev.mtaext          #   MCP-MTA DEV overrides (tutorials-mcp-dev)
│   └── mcp-prod.mtaext         #   MCP-MTA PROD overrides (tutorials-mcp-prod)
├── .github/workflows/          # CI/CD pipelines (GitHub Actions)
│   ├── deploy.yml              #   Build MTA + deploy to BTP CF + post-deploy smoke tests
│   ├── rebuild-content.yml     #   Re-fetch tutorials + rebuild Hugo + publish HTML to HANA
│   ├── rebuild-content-qa.yml  #   QA-channel content rebuild (triggered by repository_dispatch)
│   ├── schema-drift-check.yml  #   Compare prod vs QA HDI schemas
│   └── notify-qa.yml.template  #   Template installed into every -Contribution repo
├── openspec/                   # OpenSpec change proposals + config
├── .tutorial-cache/            # Cached prod-channel GitHub markdown + metadata (gitignored)
├── .tutorial-cache-qa/         # Cached QA-channel markdown (gitignored, separate channel marker)
├── .migration-data/            # Migration export files from Java IMS (gitignored)
├── gen/                        # CDS build output (gitignored)
├── site/                       # Legacy VitePress output (deprecated, gitignored)
├── CLAUDE.md                   # Project context for Claude Code agents
├── AGENTS.md                   # Agent-specific instructions (Codex/Gemini parity)
├── package.json                # Root dependencies + npm scripts (full list: jq '.scripts' package.json)
└── vitest.config.ts            # Vitest workspace config (inline projects array)

Quick Start

Prerequisites: Node.js >= 20, npm

npm install
npm run fetch-tutorials   # Fetch tutorial markdown from GitHub + CAP catalog
cds watch                 # Start CAP server (http://localhost:4004)
npm run dev               # Hugo dev server (separate terminal)
npm run build:all         # Full production build

For full setup including hybrid HANA development, environment variables, and the script reference, see docs/developers/getting-started.md.

Scripts

Full list: jq '.scripts' package.json. The most operationally important ones:

Setup

Script	Description
npm install	Install all dependencies
npm run bind:setup	First-time hybrid env binding (CAP + approuter against real HANA)
npm run setup-dev-data	Populate slugs + clean autotest data on DEV HANA (requires cds bind)

Dev

Script	Description
cds watch	Start CAP backend with in-memory SQLite (http://localhost:4004)
npm run watch:hybrid	CAP backend bound to real HANA via --profile hybrid
npm run dev:hybrid	CAP (hybrid) + approuter together — full local stack against real HANA
npm run start:approuter	Standalone approuter (port 5000)
npm run dev	Hugo dev server with live reload (requires fetch-tutorials first)

Build

Script	Description
npm run fetch-tutorials	Fetch markdown from GitHub, parse, generate Hugo content pages
npm run discover-repos	List discoverable tutorial repos without fetching
npm run build:cds	Production CDS build
npm run build:css	PostCSS pipeline for SAP Fundamental Styles
npm run build:hugo	Hugo static site build (minified)
npm run build:apps	Build hugo-apps/ Vue islands into hugo/static/js/
npm run build:admin	Build admin-shell into app/admin-shell/dist/
npm run build:analytics-explorer	Build Analytics Explorer Vue 3 SPA
npm run build:display	Build Display App (event monitor dashboard)
npm run build:highlight	Generate CDS syntax highlighter assets
npm run generate-dark-theme	Regenerate dark-theme CSS variants
npm run validate-tutorials	Static validation of fetched tutorial markdown
npm run build:all	Full production pipeline (fetch + CSS + apps + Hugo + display)

Test

Script	Description
npm test	Unit tests (in-memory SQLite, fast)
npm run test:watch	Unit tests in watch mode
npm run test:hybrid	Hybrid tests against real HANA (requires cf login to DEV)
npm run test:hybrid:watch	Hybrid tests in watch mode
npm run test:smoke	HTTP smoke tests (set SMOKE_BASE_URL / SMOKE_SRV_URL)
npm run test:a11y	Accessibility tests
npm run test:a11y:lighthouse	Lighthouse a11y audit (lhci autorun)
npm run test:a11y:summary	Print a11y test summary
npm run test:all	All Vitest workspaces (unit + hybrid + smoke + a11y)

Content publishing

Script	Description
npm run publish-content	Delta-publish Hugo HTML → HANA BLOBs (use -- --force to bypass delta — required for prod)

QA channel (author preview)

Script	Description
npm run fetch-tutorials:qa	Fetch from *-Contribution repos only (cache: .tutorial-cache-qa/)
npm run build:qa	Hugo build with QA flag, post-build verify
npm run publish-content:qa	Force-publish to QA srv
npm run qa:full	End-to-end QA pipeline

Migration (Java IMS → CAP)

Script	Description
npm run migrate:reference	Export/import reference data from Java IMS
npm run migrate:users	Export/import user progress (paged, resumable)
npm run migrate:hana	Direct HANA-to-HANA migration
npm run compare	Compare Java IMS and CAP responses side-by-side

Environment Variables

Deploy-time variables for the MTA modules (CF env, role collections, secrets) are documented in .deploy/DEPLOY.md. The five most commonly set during local dev:

Variable	Required	Description
CAP_BASE_URL	No (default http://localhost:4004)	CAP srv URL — used by the build pipeline, publish-content, and migration scripts
GITHUB_TOKEN	No	Avoids GitHub API rate limits when fetching tutorial markdown + commit metadata
CONTENT_API_KEY	Yes (publish + srv)	Bearer token for POST /content/publish and /content/rollback; required on the srv to accept publish writes
SUBMISSION_SALT_SECRET	Yes (feedback)	IP-hash salt for /feedback/submit; bridge returns 503 if missing
IMS_AUTH_TOKEN	Yes (migrate)	Bearer token for the legacy Java IMS API during cutover

For the full list, see docs/developers/getting-started.md#environment-variables.

Runtime Architecture

See docs/developers/architecture/runtime.md for full details.

Build Architecture

See docs/developers/architecture/build.md for full details.

Joule Architecture

See docs/developers/architecture/joule.md for full details.

CAP Backend (srv/)

See docs/developers/architecture/cap-backend.md for full details.

Build Pipeline

See docs/developers/architecture/build.md#build-pipeline for full details.

Frontend Apps

See docs/developers/architecture/frontend-apps.md for full details.

Deployment

See docs/developers/operations/deployment.md for full details.

Data Migration

See docs/historic/data-migration.md for full details.

Testing

See docs/developers/operations/testing-guide.md for full details.

External Integrations

See docs/developers/reference/external-integrations.md for full details.

Key Design Decisions

See docs/developers/reference/design-decisions.md for full details.

Documentation

The full documentation set lives in docs/ and is organized by persona:

• End Users — finding tutorials, using Joule chat, progress and prizes
• Authors — writing tutorials, owning a repo group, running an event center
• Developers — architecture, operations, reference (you're probably here)
• Historic — AEM, IMS, completed migrations

Start at docs/README.md for the full index.

Licensing

Copyright 2026 SAP SE or an SAP affiliate company and tutorials-ims contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.