π§ SAP AI Development Toolkit
Build, test, and deliver ABAP with AI that understands your SAP landscape.
Get started β Meet the agents Β·
Connect your SAP systems Β·
Explore the tools
## From a prompt to SAP-ready work
SAP AI Dev Toolkit connects your AI coding assistant to the SAP development tools available for each selected destination. Agents can inspect ABAP and CDS, propose changes, run checks, and return the evidenceβwithout losing sight of which SAP system each operation targets.
Agent chat β destination-scoped MCP β SAP runtime + configured route (BAS, CF, or local SAP GUI) β SAP ADT β your SAP system results and diagnostics flow back along the same path
Explore β Build β Verify β Prepare for delivery
## β‘ Quick start
Run the setup wizard without a global install:
```sh
npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
```
Interactive setup configures the selected destinations, then asks which AI harnesses should receive the bundled agents and skills. This prompt is part of `--setup`, so it still appears when `--ignore-scripts` skips npm lifecycle scripts. Without an interactive terminal, assets install for GitHub Copilot by default.
Prefer a persistent global install instead?
```sh
npm install --global sap-ai-dev-toolkit
sap-ai-dev --setup
```
To also add optional full-stack SAP companion MCP servers for Fiori, UI5, CAP, and browser validation, run:
```sh
sap-ai-dev --setup --tools
```
After setup, connect a selected BAS destination or local SAP GUI system from your MCP-capable editor:
1. Open the Command Palette.
2. Run **MCP: List Servers**.
3. Start the server named after your selected destination (the lowercase slug, for example `demo-abap` for destination `DEMO_ABAP`).
4. In your AI assistant's chat, choose the best-fit bundled agent from the agent picker (GitHub Copilot, Claude Code, and opencode install the agents) or invoke the matching Pi prompt template (`/sap-solution-architect`, `/abap-developer`, `/abap-runtime-debugger`, `/rap-service-developer`, `/hana-cloud-hdi-specialist`, `/sap-integration-architect`, or `/sap-integration-developer`): **SAP Solution Architect**, **ABAP Developer**, **ABAP Runtime Debugger**, **RAP Service Developer**, **HANA Cloud/HDI Specialist**, **SAP Integration Architect**, or **SAP Integration Developer**.
5. In the Chat tools picker, enable the server for that destination.
6. Ask the agent to inspect, build, test, or verify something in your SAP landscape.
Use the attached destination-prefixed tools directly in chat. Do not launch `sap-ai-dev` or handcraft MCP JSON-RPC in a terminal to discover or call them.
**Prerequisite:** Node.js 20 or newer. The pinned runtime ships with the package; no Go toolchain is installed or required.
## π€ Available agents and skills
**Agents:** Seven user-invocable custom agents are included. Select the best fit from the agent picker in your harness's chat (GitHub Copilot, Claude Code, or opencode), or use the matching Pi prompt command, as shown in Quick start. Harnesses without custom agents (OpenAI Codex, Cursor, Gemini CLI, OMP, Cline, Roo Code, Windsurf / Devin Desktop) get the same workflows as skills, for example `sap-integration-architect` and `integration-suite-delivery`.
| | Agent | Best for |
| --- | --- | --- |
| π§ | **SAP Solution Architect** | System investigation, SAP standard/API recommendations, Clean Core and side-by-side design, and SDLC orchestration through implementation handoffs and validation gates |
| π§βπ» | **ABAP Developer** | General ABAP, CDS, and RAP implementation, validation, and transport-preparation tasks |
| π | **ABAP Runtime Debugger** | Runtime incidents, application logs, debugger sessions, and performance symptoms; call relationships are derived from source inspection |
| π | **RAP Service Developer** | RAP business objects, behavior implementations, projections, service definitions, service bindings, and OData validation |
| ποΈ | **HANA Cloud/HDI Specialist** | Read-only HANA Cloud container inspection, CAP/HDI artifact generation, local validation, and user-run deployment handoffs |
| ποΈ | **SAP Integration Architect** | SAP Integration Suite design: API Management vs Cloud Integration vs both, connectivity, per-hop security, error handling, and an approved build plan |
| π | **SAP Integration Developer** | Building that plan with the Integration Suite companion: iFlows, value mappings, security material, deployment and monitoring in CPI; API providers, proxies, policies, products and key value maps in APIM |
**Included skills:** `abap-development` Β· `abap-testing-quality` Β· `cds-development` Β· `rap-development` Β· `abap-debugging` Β· `abap-runtime-analysis` Β· `rap-service-delivery` Β· `sap-standard-api-analysis` Β· `clean-core-extensibility` Β· `sap-sdlc-orchestration` Β· `sap-transport-release` Β· `hana-cloud-inspection` Β· `hana-cloud-native-development` Β· `hana-cloud-validation` Β· `sap-integration-architect` Β· `integration-suite-delivery`
Agents and skills install for the harnesses you pick during global installation: a multi-select offers GitHub Copilot and Claude Code pre-checked, plus OpenAI Codex, Cursor, Gemini CLI, opencode, Pi Coding Agent, Oh My Pi (OMP), Cline, Roo Code, and Windsurf / Devin Desktop. In non-interactive installs they are installed for GitHub Copilot only; run `sap-ai-dev --setup` afterwards to configure destinations or local SAP GUI systems. Repository-scoped installation instructions appear below.
## β¨ Your SAP development cockpit, inside your AI assistant
`sap-ai-dev-toolkit` installs `sap-ai-dev`, discovers your BAS destinations or local SAP GUI systems, and exposes a curated SAP development toolset through MCP. Instead of manually switching between chat, terminal commands, repository searches, ADT screens, and SAP checks, describe the outcome you want and let the appropriate bundled agent coordinate the available tools.
π¬ Request β π Inspect β π§ Reason β π§βπ» Implement β π§ͺ Verify β π Report
The workflow covers ABAP, CDS, RAP, repository analysis, table and query access, testing, ATC, application logs, transports, and controlled source changes. The live MCP tool list remains the source of truth for what your connected SAP system and active runtime mode expose.
## π Feature highlights
| | Feature | What it gives you |
| --- | --- | --- |
| π€ | **AI-driven ABAP development** | Describe the outcome; a task-fit agent coordinates inspection, implementation, validation, and a clear report. |
| π§ | **Destination-aware by design** | Discover BAS destinations or local SAP GUI systems and connect each MCP server to one selected SAP system. |
| π | **Understand before editing** | Trace source, callers, definitions, package contents, dependencies, and CDS impact in one workflow. |
| 𧩠| **CDS + RAP development** | Explore models and dependencies, then build RAP business objects and services with system context. |
| ποΈ | **Ground decisions in SAP data** | Inspect DDIC structures, read table contents, and run controlled ABAP SQL queries. |
| βοΈ | **Read-only HANA Cloud inspection** | Inspect an environment-bound HDI schema, object metadata, and capped query results without exposing deployment credentials. |
| βοΈ | **Edit ABAP safely** | Update supported source, stage reviewed change sets, create transport requests, and run syntax checks before requested activation. |
| β
| **Quality built into the flow** | Pair local ABAP linting with SAP syntax checks, ABAP Unit, ATC, editor diagnostics, and formatting. |
| π | **Debug with system context** | Investigate dumps, traces, application logs, runtime failures, capabilities, and installed components. |
| π | **Transport-aware workflows** | Check request and lock context before preparing a change; create transports only when authorized. |
| π§Ύ | **Reviewable change sets** | Stage multi-object diffs and re-read each source before an explicitly requested apply. |
| π | **Transport readiness evidence** | Bring request, dependency, inactive-object, test, and ATC results together in one report. |
| π§ | **ABAP Cloud migration assessment** | Check SAP API release evidence in batches and focus review on recognized unreleased APIs. |
| π | **Reusable RAP smoke suites** | Turn OData metadata into repeatable GET checks with saved assertions. |
| π©Ί | **Connection Doctor** | Find setup issues across destination reachability, runtime startup, SAP system info, and tool discovery. |
| π§ͺ | **Offline playground** | Try the agents and workflows locally with sample SAP data; demo changes disappear on exit. |
| π | **Controlled SAP state changes** | State-changing actions require a known target and an explicit request; SAP authorizations still apply. |
| 𧱠| **Destination isolation** | Each generated MCP server is tied to its own `SAP_AI_DEV_TOOLKIT_DESTINATION`, helping prevent accidental cross-system execution. |
| π‘οΈ | **Credential-safe configuration** | Credentials, cookies, usernames, passwords, and raw destination payloads are not written into MCP configuration. |
The catalog below covers source inspection, data, editing, quality, transports, logs, and multi-step development workflows. Availability can vary by SAP system and runtime mode, so the live `tools/list` response is authoritative.
## π What can the agent do?
### π§βπ» Build and refactor
- ABAP reports, classes, interfaces, and function groups
- CDS definitions and dependency-aware changes
- RAP business objects and services
- Focused source edits with syntax validation
### π Understand your SAP codebase
- Search repository objects and packages
- Find definitions and references
- Compare implementations
- Inspect class metadata and dependencies
- Run CDS forward and reverse impact analysis
### π§ͺ Validate quality
- ABAP Unit
- ATC checks
- SAP syntax checks
- Local `abaplint`
- BAS editor and LSP diagnostics
- Pretty-print source
### π’ Work with the live SAP system
- Read DDIC structures and table content
- Execute ABAP SQL queries
- Inspect system and component information
- Read SLG1 application logs
- Review and create transport requests
## π§ Seven agents, sixteen focused skills
The package ships with seven custom agents plus sixteen task-focused Agent Skills:
| | Skill | Best for |
| --- | --- | --- |
| π§βπ» | `abap-development` | Implementing and refactoring ABAP reports, classes, interfaces, and function groups |
| β
| `abap-testing-quality` | ABAP Unit, lint, LSP diagnostics, SAP syntax checks, and ATC |
| 𧩠| `cds-development` | CDS modeling, dependency inspection, and consumer impact analysis |
| π | `rap-development` | RAP business objects and service development |
| π§ | `sap-standard-api-analysis` | SAP standard capability, released API, CDS/RAP/OData, and fit-gap analysis before custom development |
| 𧱠| `clean-core-extensibility` | Clean Core, released extensibility, and side-by-side extension design with risk classification |
| π | `sap-sdlc-orchestration` | Requirement-to-release lifecycle planning, delegated implementation, quality gates, validation, and handover |
| π | `abap-debugging` | Dumps, logs, traces, and runtime failure diagnosis |
| π¬ | `abap-runtime-analysis` | Incident triage, debugger state, and performance analysis; call relationships come from source inspection |
| π | `rap-service-delivery` | RAP service activation, publication, OData validation, and end-to-end runtime checks |
| π | `sap-transport-release` | Dependency checks and transport preparation; release itself is intentionally unavailable here |
| π | `hana-cloud-inspection` | Verify the selected HANA Cloud binding and inspect bounded HDI catalog/data results |
| 𧱠| `hana-cloud-native-development` | Generate CAP-owned CDS models or required native HDI artifacts without duplicating generated sources |
| β
| `hana-cloud-validation` | Run local CAP/HANA builds and prepare a reviewed, user-run deployment handoff |
| ποΈ | `sap-integration-architect` | Integration Suite pattern choice, connectivity, per-hop security, naming/versioning rules, and an approvable build plan |
| π | `integration-suite-delivery` | Building iFlows, API proxies, gateway policies, API products and key value maps step by step, deploying, and troubleshooting with message logs |
## πΊοΈ How it fits together
Each selected BAS destination becomes its own isolated MCP server identity. The MCP client discovers the live tools and schemas, the add-on routes calls to the correct runtime process, and the process reaches SAP ADT through the selected BAS destination.
## π§° Optional full-stack companion MCP servers
ABAP/RAP backend access is provided by this add-on's BAS proxy. For end-to-end SAP development, setup can also add managed companion MCP entries for frontend, CAP, browser validation, and read-only HANA inspection:
```sh
sap-ai-dev --setup --tools
```
The companion entries are optional and are launched through `npx` only when the MCP client starts them. They are marked as managed by `sap-ai-dev-toolkit`, so rerunning setup can update or remove them without touching unrelated MCP servers. The HANA and Integration Suite companions use `--ignore-scripts` so the toolkit postinstall wizard cannot run during MCP startup.
| MCP entry | Package | Launches | Use when the agent needs to |
| --- | --- | --- | --- |
| `sap-fiori-tools` | `@sap-ux/fiori-mcp-server` | `fiori-mcp` | Generate or adapt Fiori elements/freestyle apps, annotations, and SAP Fiori UX artifacts |
| `ui5-tools` | `@ui5/mcp-server` | `ui5mcp` | Inspect SAPUI5/OpenUI5 projects, manifests, routing, views, controllers, and UI5-specific issues |
| `cap-tools` | `@cap-js/mcp-server` | `cds-mcp` | Inspect CAP CDS models, services, entities, actions, and local CAP application structure |
| `browser-validation` | `@playwright/mcp` | `playwright-mcp` | Open BAS previews, smoke-test Fiori/UI flows, collect screenshots, and verify browser runtime behavior |
| `hana-cloud-inspector` | `sap-ai-dev-toolkit` | `sap-ai-hana` | Inspect a bound HANA Cloud HDI schema using read-only catalog tools and capped row reads |
| `integration-suite` | `sap-ai-dev-toolkit` | `sap-ai-integration` | Build, deploy, undeploy, and monitor Cloud Integration content (iFlows, value mappings, script collections, security material, Partner Directory) and manage API Management providers, proxies, policies, products, and key value maps |
Recommended profiles:
- **RAP + Fiori:** select your BAS destination plus `sap-fiori-tools`, `ui5-tools`, and `browser-validation`.
- **CAP on BTP:** select `cap-tools`, `sap-fiori-tools`, `ui5-tools`, and `browser-validation`.
- **CAP + HANA Cloud:** select `cap-tools` and `hana-cloud-inspector`; provide the inspector's read-only connection through MCP-host environment variables.
- **UI-only:** select `sap-fiori-tools`, `ui5-tools`, and optionally `browser-validation`.
### HANA Cloud/HDI inspector
Select `hana-cloud-inspector` in the optional companion-server setup, then start it from **MCP: List Servers**. The process reads its connection from the MCP host's environment; setup never copies HANA credentials into `mcp.json`. Make sure variables are available to the BAS/VS Code MCP host process (not only to a later terminal session), then reload/restart the MCP host if needed.
Use either:
- A dedicated read-only VCAP binding with `credentials.host`, `port`, `user`, `password`, and `schema` in `VCAP_SERVICES`; optionally set `HANA_RO_VCAP_SERVICE` to the exact VCAP service key and `HANA_RO_BINDING` to the binding/instance name when selection is ambiguous.
- Explicit `HANA_RO_HOST`, `HANA_RO_PORT`, `HANA_RO_USER`, `HANA_RO_PASSWORD`, and `HANA_RO_SCHEMA` variables. `HANA_RO_TRUST_STORE` is optional; TLS and certificate verification are always enabled.
The configured identity must be a separate least-privileged read-only HANA user. The server rejects bindings that offer only HDI deployment credentials and never falls back to `hdi_user`/`hdi_password`. Its tools are limited to connection identity, object listing/descriptions, and parameterized row reads capped at 200 rows; credential-like columns are blocked, and there is no arbitrary SQL, DDL/DML, grant, deployment, or undeploy tool. Use the existing project deployment workflow yourself after reviewing the exact generated artifact diff and target. The SAP HANA Node.js driver is provided under the SAP Developer License Agreement.
### Integration Suite (Cloud Integration + API Management)
Every interactive `sap-ai-dev --setup` asks **"Add the SAP Integration Suite tools?"** right before it writes the MCP configuration. The step shows which of CPI and APIM have credentials (never the secrets themselves). Enter means **yes** when credentials were found and **no** otherwise; type `y` or `n` to override. An existing `integration-suite` entry is kept without asking. With `--tools`, the choice is part of the companion checkbox instead, and when nothing is detected the setup menu also offers **Set up only the SAP Integration Suite tools**.
To set up only this server, run **`sap-ai-dev --setup-integration`**. In both routes the credential step:
1. **Checks detected credentials online.** It signs in and runs one read-only request per tool area (packages, deployed artifacts, message logs, security material, number ranges, Partner Directory, data stores, JMS; API proxies, providers, products, key value maps, virtual hosts, and policy readiness, which exports an existing API proxy bundle the way `apim_attach_api_proxy_policies` does). Each area is marked β, β (missing role) or β (not available on the tenant or plan, or no proxy exists yet to test the export with).
2. **Uses the logged-in Cloud Foundry space (default when `cf` is logged in).** It finds the Process Integration Runtime instance with plan `api` (`it-rt`) and the API Management instance with plan `apiportal-apiaccess`, lets you choose when there are several, and reuses or creates one service key named `sap-ai-dev-integration` on it. The key is then verified and saved like a pasted one. Roles are fixed on the instance, so when the key signs in but lacks roles, or a side has no instance, the wizard offers to create a dedicated instance (`sap-ai-dev-integration-cpi` with `AuthGroup_Administrator`, `AuthGroup_BusinessExpert`, `AuthGroup_IntegrationDeveloper`, `AuthGroup_TenantPartnerDirectoryConfigurator`, `AccessAllAccessPoliciesArtifacts`; `sap-ai-dev-integration-apim` with `APIPortal.Administrator`). It never does this without your `y`.
3. **Lets you paste a service key.** Paste a CPI key (Process Integration Runtime, plan `api`) or an APIM key (API Management, plan `apiportal-apiaccess`), either as JSON (multi-line paste works; input is hidden) or as the path to the downloaded `.json` file. The key is verified the same way before it is saved.
4. **Saves only what the server needs.** The URL, token URL, client id and secret go to `~/.config/sap-ai-dev-toolkit/integration-suite.json`, readable only by you. The secret is never printed and never written to `mcp.json`. A key that cannot sign in is saved only if you confirm.
Environment credentials take precedence over a saved key. Re-check at any time with `sap-ai-integration --check`, or ask the agent to call `integration_connection_info` with `verify: true`. Configure CPI, APIM, or both; per side the first match wins:
- Explicit `CPI_URL`, `CPI_TOKEN_URL`, `CPI_CLIENT_ID`, `CPI_CLIENT_SECRET` (or the `APIM_*` equivalents).
- `CPI_SERVICE_KEY` / `APIM_SERVICE_KEY` containing the service-key JSON: a Process Integration Runtime `api` plan key (ClientId/Secret) for CPI, an API Management `apiportal-apiaccess` key for APIM. Certificate-based keys are rejected.
- One `VCAP_SERVICES` binding of service `it-rt` / `apimanagement-apiportal`; override the label with `CPI_VCAP_SERVICE` / `APIM_VCAP_SERVICE` and select an instance with `CPI_BINDING` / `APIM_BINDING`.
- The key saved by `sap-ai-dev --setup-integration` (lowest precedence).
CPI needs the roles `WorkspacePackagesRead`, `WorkspacePackagesEdit`, `WorkspacePackagesConfigure`, `WorkspaceArtifactsDeploy`, and `MonitoringDataRead` for packages, iFlows, deployment and message logs; security material, number ranges, Partner Directory, data stores, and JMS tools additionally need the matching `api`-plan roles for those areas (for example `DataStoresAndQueuesRead` and `AuthGroup_TenantPartnerDirectoryConfigurator`), and a missing role surfaces as an HTTP 403 in the tool error. APIM needs `APIPortal.Administrator`. Writes are limited to create, update, configure, deploy, and undeploy, each gated by an exact confirmation string such as `CREATE IFLOW ` or `UPDATE API PROXY POLICIES `; there are no delete tools. Passwords, client secrets, and key value map values are write-only: tools accept them and never return them. Anything without a dedicated tool can be read through `cpi_odata_get` / `apim_odata_get`. Run `sap-ai-integration --help` for the full variable list.
`npm run test:live:integration` runs the end-to-end scenarios against a real tenant. It **creates and deploys** packages, iFlows, API providers, proxies, products, key value maps, user credentials, number ranges, and Partner Directory parameters suffixed with `RUN` (required, unique per run), so use a non-production subaccount. Scenarios that call iFlows over HTTP also need `CPI_RUNTIME_SERVICE_KEY`, a Process Integration Runtime `integration-flow` key with role `ESBMessaging.send`; the companion server itself never uses that key.
## π‘ Example requests
Once the destination server is enabled in your chat's tools picker, ask for outcomes instead of manually orchestrating individual SAP operations:
> Find every reference to `ZCL_ORDER`, explain the impact of changing method `CREATE_ORDER`, and show me the callers before editing anything.
> Fix the defect in `ZCL_PRICING`, add or update ABAP Unit coverage, run syntax checks and the available tests, and summarize exactly what passed or was skipped.
> Inspect the dependencies and downstream consumers of this CDS view and tell me what would be affected by renaming the field.
> Read company codes from `T001` for this destination and return `BUKRS`, `BUTXT`, `WAERS`, and `LAND1`.
> Inspect the HANA HDI container attached to this workspace, describe the relevant tables, and show at most 20 rows for the columns needed to explain the issue. Do not change database state.
> Check the current object's transport context, prepare the change for transport, but do not release anything.
## π Enterprise-friendly safety model
| Guardrail | Behavior |
| --- | --- |
| π― **Explicit target** | SAP changes only proceed when the destination and required target details are known. |
| π¦ **Explicit state change** | Activation, service publication, and transport creation happen only when requested and authorized. |
| π§ͺ **Verification first** | The agent uses available lint, syntax, unit-test, ATC, and diagnostics workflows and reports what actually ran. |
| π **SAP authorization remains authoritative** | The add-on does not bypass backend SAP permissions. |
| π **Curated SAP tool surface** | The proxy exposes the same curated developer-lifecycle set for every destination, plus local workflow tools; SAP authorizations and runtime safety checks still apply. |
| 𧱠**Per-destination isolation** | Generated MCP entries are scoped to a single `SAP_AI_DEV_TOOLKIT_DESTINATION`. |
| π **Credential-aware setup** | BAS authentication material stays in Destination configuration. Local SAP GUI setup writes VS Code input prompts for SAP user/password instead of raw credentials. |
.bak` (exclusive create, so reruns never overwrite an earlier backup; symlinked configs keep their link). `sap-ai-dev --doctor` stays strict and reports such files instead of rewriting them β run `sap-ai-dev --setup` to heal.
- Local SAP GUI discovery reads the Windows landscape files and registry, and setup can write a Windows / smart card SSO entry that signs in through Microsoft Edge; see the βLocal machine SAP GUI supportβ section below.
If you previously installed an earlier package, remove it before installing this one:
```sh
npm uninstall --global bas-mcp-addon
npm install --global sap-ai-dev-toolkit
sap-ai-dev --setup
```
The guided setup can also offer companion MCP entries with `sap-ai-dev --setup --tools`:
| Server | npm package | Best for |
| --- | --- | --- |
| SAP Fiori tools | `@sap-ux/fiori-mcp-server` | Fiori elements/freestyle apps, annotations, and UX guidance |
| UI5 tools | `@ui5/mcp-server` | SAPUI5/OpenUI5 project inspection, help, and lint/project support |
| CAP tools | `@cap-js/mcp-server` | CAP CDS/service model inspection and CAP app development |
| Browser validation | `@playwright/mcp` | Fiori/UI smoke tests, screenshots, and browser runtime validation |
The installer handles runtime provisioning automatically:
- Uses the package's bundled runtime executable for the current platform, verified against the npm-published `dist/checksums.txt`. When the bundled asset is missing (an interrupted install, an antivirus quarantine, or a git checkout without `dist/`), a checksum-anchored download from the matching GitHub release is the fallback; MCP server startup runs it too, because npx entries skip install scripts.
- No Go toolchain is downloaded or required at install time; Go is only used by the repository's own build script.
Setup detects where it is running. With `H2O_URL` set, it treats the environment as SAP Business Application Studio and opens a checkbox picker for BAS destinations, with no destinations selected by default: every row starts with an empty box `[ ]`. Use **Space** to tick a destination (`[β]`) and **Enter** to confirm; the line under the list always names the next key to press. Press **a** to toggle all destinations (select all if any are unchecked; otherwise clear the selection). Pressing **Enter** with nothing selected asks for a second **Enter**, because confirming with none selected removes this add-on's managed MCP entries. When the `cf` CLI 8.18 or newer is authenticated to a targeted space, setup first offers an optional import from that space's Destination service; type **y** then **Enter** to include it, or press **Enter** to skip. Accepted CF and BAS destinations appear together in the picker.
Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint or a complete ABAP client catalog, so setup asks for the SAP client or comma-separated clients to configure for each selected system (for example `100,200`), proposes an ADT URL from the SAP GUI host and instance when it can, and asks you to confirm or edit that value. Multiple entered clients create separate isolated MCP entries, one per system/client pair. Local SAP GUI MCP server keys use the SAP system ID and client (for example `t4d-100`) instead of the longer SAP GUI description, while `SAP_AI_DEV_TOOLKIT_DESTINATION` still preserves the display name. When the ADT URL uses an IP address, setup automatically inspects the SAP HTTPS certificate, extracts DNS subjectAltName entries, and offers to enable secure TLS self-healing with a simple yes/no confirmation; you do not need to type certificate names. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup offers Windows / smart card SSO (the default) instead, which writes `SAP_AUTH_MODE=sso` without username/password prompts. At server start, the runtime opens Microsoft Edge on the ADT URL; Edge completes the login the same way it does in your browser (smart card certificate and PIN, Kerberos, or company SAML/Entra login), and the session is cached and refreshed automatically. SSO entries need an ADT URL with a host name, not an IP address. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config, and you should run `sap-ai-dev --setup` afterwards.
### π₯οΈ Local machine SAP GUI support
Local setup is intended for developers running the MCP server from their own workstation rather than SAP Business Application Studio.
Supported discovery and runtime behavior:
- **Discovery sources:** SAP GUI landscape XML and `saplogon.ini` style configuration on macOS and Windows. Setup de-duplicates entries, ignores incomplete DIAG records, and shows the discovered SAP systems in the same checkbox picker used for BAS destinations.
- **Client selection:** SAP GUI entries may contain one default client but cannot reliably list every ABAP client available through ADT. Setup asks for one or more 3-digit clients per selected system; enter comma-separated values such as `100,200` to create separate MCP servers for each client.
- **ADT endpoint derivation:** SAP GUI entries usually contain DIAG/router information, not the HTTP(S) ADT endpoint. Setup derives the common ADT port from the SAP instance when possible, for example instance `00` β `https://host:44300`, and asks for confirmation only when configuring the selected entry.
- **Credential handling:** username/password local entries use VS Code MCP input prompts (`${input:...}`) at server start. Plain SAP credentials are not written to `mcp.json`.
- **Login methods:** local entries use either username/password or Windows / smart card SSO. SSO sets `SAP_SSO=true` for the runtime, which drives Microsoft Edge for the login and re-opens an Edge window only when the cached session can no longer be refreshed silently.
- **IP-address HTTPS self-healing:** if the confirmed ADT URL is `https://:` and the certificate is issued to DNS names, setup reads the certificate DNS SANs automatically and stores them as `SAP_TLS_SERVER_NAMES`. At runtime a loopback proxy dials the IP address but verifies TLS against those discovered DNS names, trying them one by one. Certificate verification stays enabled; there is no `--insecure` mode.
- **Private CAs:** if the SAP HTTPS certificate chains to an internal CA that is not trusted by the local Node runtime, set `SAP_TLS_CA_FILE` or `SAP_AI_DEV_TOOLKIT_TLS_CA_FILE` to a PEM CA bundle. This adds trust roots for the self-healing proxy without disabling certificate validation.
- **Redirect and request safety:** local loopback proxies reject cross-origin forward-form requests and rewrite same-origin SAP redirects back through the loopback listener, so the runtime stays on the safe route.
Typical local setup flow:
```sh
sap-ai-dev --setup
```
1. Select the discovered SAP GUI system with **Space** and confirm with **Enter**. If no SAP GUI entries are found, setup offers the manual entry wizard: enter a system name, ADT URL, client(s), and login mode instead.
2. Confirm the detected/default SAP client, or enter multiple clients such as `100,200`.
3. Accept the proposed ADT URL when it is correct, or edit it if your landscape exposes ADT through a different HTTP(S) host/port.
4. If setup discovers certificate DNS names for an IP-based HTTPS URL, accept the yes/no TLS self-healing prompt.
5. Choose Windows / smart card SSO or username/password when the prompt is available.
6. Start each generated MCP server from VS Code's **MCP: List Servers** command.
The same postinstall offers the bundled agents and skills for several AI coding harnesses in a checkbox picker. **GitHub Copilot** and **Claude Code** start pre-checked, so pressing **Enter** alone installs both; **Space** selects or deselects a harness, **a** toggles all eleven, and confirming with none selected skips the step without changing files. When MCP setup succeeds, generated managed MCP servers are also mirrored into selected harnesses with documented user-level JSON configuration (Claude Code, Cursor, Gemini CLI, Pi Coding Agent, OMP, and Windsurf / Devin Desktop). GitHub Copilot continues to use the VS Code/BAS MCP configuration written during setup. With no interactive terminal, the assets are installed for GitHub Copilot only; set `SAP_AI_DEV_TOOLKIT_HARNESSES` to a comma-separated list of harness ids (`github-copilot`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `opencode`, `pi-coding-agent`, `omp`, `cline`, `roo-code`, `windsurf`) to choose non-interactively.
Some current npm versions also require install hooks to be approved. If npm reports that `sap-ai-dev-toolkit`'s `postinstall` was blocked, allow it during a fresh install with `npm install --global --allow-scripts=sap-ai-dev-toolkit sap-ai-dev-toolkit`, or run `sap-ai-dev --setup` from an interactive terminal after installation.
The setup report uses icons and terminal colors; set `NO_COLOR=1` to disable ANSI colors. Long-running steps (BAS destination discovery, ADT probes, runtime provisioning, `--doctor` checks) show an animated progress line so the terminal never looks stuck; it appears only on interactive terminals and is disabled automatically on CI β set `SAP_AI_DEV_TOOLKIT_DISABLE_SCAN_ANIMATION=true` to turn it off. The table is a weather report, not a bouncer: green **PASS** means the ADT probe responded, red **FAIL** means it failed, and yellow **SKIPPED** means it was skipped. Probe failures do not block MCP registration or startup for destinations you select.
Run `sap-ai-dev --setup` later to change the destination selection or remove generated destination entries. Run `sap-ai-dev --setup --tools` to also choose optional companion tools. Generated destination entries use the global `sap-ai-dev` command when it is on `PATH`; otherwise (for example after a pure npx setup) they automatically launch the pinned package version through `npx`, routed through `cmd /c npx` on Windows so every MCP host can spawn them. Pass `--npx` to force the npx launcher even when a global command exists; companion tools already use `npx` with their own npm packages.
If a setup step is skipped or fails, rerun it from an interactive terminal:
```sh
sap-ai-dev --setup
```
To configure without a global install, run the guided setup directly through npm:
```sh
npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
```
This lists discovered systems in the same checkbox picker, with nothing selected by default. Use **Space** to choose destinations, **Enter** to confirm, **a** to toggle all (select all if any are unchecked; otherwise clear the selection), and **m** to configure an undiscovered system manually in the manual entry wizard; configured systems join the picker pre-selected. Because no global `sap-ai-dev` command is on `PATH`, it writes MCP entries that launch the pinned package version through npx β through `cmd /c npx` on Windows, which is the form VS Code, Claude Code, and Cursor can spawn there. `--ignore-scripts` avoids running the install-time wizard a second time; add `--npx` to force this launcher shape even when the toolkit is installed globally. After setup, in BAS or VS Code run **MCP: List Servers**, select each chosen destination, and choose **Start Server**.
For a non-interactive installation or a platform without a published runtime asset, provide a trusted binary override:
```sh
SAP_AI_DEV_TOOLKIT_BINARY=/path/to/runtime-executable npm install --global sap-ai-dev-toolkit
```
At the end of a global install, the color-coded summary shows the MCP config path, each generated entry name, destination/client/authentication, launch command, and environment key names (not values). The installer does not open an editor automatically; in BAS/VS Code:
1. Open the Command Palette.
2. Run **MCP: List Servers**.
3. Select the generated server name shown in the report and choose **Start Server**.
4. Use **MCP: Open User Configuration** to inspect or edit the generated entries. Each entry is isolated to its destination.
.md` (frontmatter reduced to `name` and `description`) | `$HOME/.claude.json` |
| OpenAI Codex | `$HOME/.agents/skills/` | β | Not changed automatically |
| Cursor | `$HOME/.cursor/skills/` | β | `$HOME/.cursor/mcp.json` |
| Gemini CLI | `$HOME/.gemini/skills/` | β | `$HOME/.gemini/settings.json` |
| opencode | `$XDG_CONFIG_HOME/opencode/skills/` (default `$HOME/.config/opencode/skills/`) | `$XDG_CONFIG_HOME/opencode/agents/.md` (as subagents) | Not changed automatically |
| Pi Coding Agent | `$PI_CODING_AGENT_DIR/skills/` (default `$HOME/.pi/agent/skills/`) | `$PI_CODING_AGENT_DIR/prompts/.md` (as `/` prompt commands) | `$PI_CODING_AGENT_DIR/mcp.json` (default `$HOME/.pi/agent/mcp.json`) |
| Oh My Pi (OMP) | `$HOME/.omp/agent/skills/` (overridden by `PI_CONFIG_DIR` or `PI_CODING_AGENT_DIR`) | β | `$HOME/.omp/agent/mcp.json` (same overrides) |
| Cline | `$HOME/.cline/skills/` | β | Not changed automatically |
| Roo Code | `$HOME/.roo/skills/` | β | Not changed automatically |
| Windsurf / Devin Desktop | `$XDG_CONFIG_HOME/devin/skills/` (default `$HOME/.config/devin/skills/`); Windows: `$HOME/.codeium/windsurf/skills/` | β | `$XDG_CONFIG_HOME/devin/mcp_config.json` (default `$HOME/.config/devin/mcp_config.json`); Windows: `%APPDATA%\devin\mcp_config.json` |
All 14 skills use the portable `SKILL.md` format and are installed verbatim. The 5 agents use Copilot's `.agent.md` format, so they are installed as native custom agents for harnesses with a custom-agent mechanism (GitHub Copilot, Claude Code, opencode), with frontmatter adapted where needed. Pi receives equivalent prompt templates (`/abap-developer`, `/sap-solution-architect`, and so on) because Pi exposes reusable personas through prompts rather than a separate custom-agent file type. Selecting several harnesses duplicates the small markdown payloads on disk.
MCP auto-wiring preserves unrelated servers in each harness config and replaces only entries previously managed by `sap-ai-dev-toolkit`. Generated entries carry `SAP_AI_DEV_TOOLKIT_MANAGED=true` in their server environment so future reinstalls can reconcile them without touching user-owned MCP servers.
These user-level customizations are available across workspaces opened by the same OS user (or the same BAS user in a dev space). The harness may need a window reload to discover new files. A non-interactive postinstall or setup run installs for GitHub Copilot only; override with `SAP_AI_DEV_TOOLKIT_HARNESSES` (comma-separated harness ids). `npm install --ignore-scripts` skips postinstall, but running `sap-ai-dev --setup` still offers harness installation after destination setup.
On reinstall or package upgrade, unchanged add-on-managed files are updated per harness. Existing customizations and files edited since the previous install are preserved; postinstall reports paths that need manual review instead of overwriting them.
### ποΈ Add the agents and skills to a repository
To commit repository-scoped customizations, copy the packaged files from the installed package without overwriting existing files:
```sh
ADDON_ROOT="$(npm root -g)/sap-ai-dev-toolkit"
mkdir -p .github/agents .github/skills
cp -n "$ADDON_ROOT/.github/agents/"*.agent.md .github/agents/
cp -Rn "$ADDON_ROOT/.github/skills/." .github/skills/
```
Review skipped or conflicting files and merge changes manually. `LintABAP` analyzes caller-supplied source in memory; it does not read workspace files. Editor diagnostics are separate from MCP tools and do not appear in `tools/list`.
.dest/sap/bc/adt/discovery` through the BAS proxy. HTTP 2xx, 401, and 403 mean the ADT endpoint is reachable; other responses and network errors are reported but do not exclude a discovered destination from the selection list.
`WebIDEEnabled`, `WebIDEUsage`, `HTML5.DynamicDestination`, and returned host fields are BAS metadata, not filters used by this probe.
See SAP Help: **Create a Destination to Connect to SAP Business Application Studio** and **Creating a Destination to an ABAP System for BAS**.
### π Generated MCP server entry
One selected system, one isolated stdio MCP entry. Here's the shape:
```json
{
"type": "stdio",
"command": "sap-ai-dev",
"env": {
"H2O_URL": "https://bas.example.com",
"SAP_AI_DEV_TOOLKIT_DESTINATION": "DEMO_ABAP",
"SAP_ALLOW_TRANSPORTABLE_EDITS": "true"
},
"BAS_EXT": "true"
}
```
The MCP protocol `serverInfo.name` is the lowercased destination slug, so each wizard-generated destination has its own identity instead of the shared `sap-ai-dev-toolkit` name.
Credentials, cookies, SAP usernames, passwords, and raw BAS destination payloads are not written to the MCP configuration.
### βοΈ MCP configuration location
The configuration path is selected in this order:
1. `SAP_AI_DEV_MCP_CONFIG`, when set.
2. `SAP_AI_DEV_TOOLKIT_MCP_CONFIG`, when set.
3. An existing MCP user configuration detected automatically.
4. The default MCP user configuration location.
Set `SAP_AI_DEV_MCP_CONFIG` to use a specific configuration file:
```sh
SAP_AI_DEV_MCP_CONFIG="/path/to/mcp.json" sap-ai-dev --setup
```
The file must be strict JSON with an object-valued `servers` property. Existing malformed or incompatible files are rejected without overwriting them.
### π οΈ Commands
| Need | Command |
| --- | --- |
| See options without starting the MCP server | `sap-ai-dev --help` |
| Walk through setup interactively | `sap-ai-dev --setup` |
| See discovered systems and probe results | `sap-ai-dev --list-destinations` |
| Get the same report in machine-readable, redacted form | `sap-ai-dev --list-destinations --json` |
| Check availability without starting the server | `sap-ai-dev --check` |
With `H2O_URL` set, the normal command starts the MCP proxy. Each generated entry supplies one `SAP_AI_DEV_TOOLKIT_DESTINATION`, so each server stays in its own lane and exposes only its selected SAP system.
The proxy exposes a curated subset of upstream tools, plus local `LintABAP`, destination-scoped workflow tools, and the convenience `GetApplicationLog` mapping when the SAP router is available. Hidden upstream tools remain available only behind local workflow chaining where required; they are not advertised or directly callable through the proxy. The runtime can also be invoked directly outside BAS with an explicit command argument.
Without `H2O_URL`, generated local SAP GUI entries start a destination-scoped local MCP server. In an interactive local terminal with no arguments, `sap-ai-dev` starts local setup. Other non-setup arguments are passed directly to the installed runtime executableβno BAS proxy detour.
### π How an MCP tool call reaches SAP
`sap-ai-dev` is an MCP stdio server and destination router, not a terminal command for individual SAP operations. No shell incantations needed: your MCP client discovers the tools, picks one for the chat request, and sends the call over stdio.
Each generated MCP server entry is named with the lowercased destination slug: `DEMO_ABAP` becomes `demo-abap`. Because every generated entry is scoped to exactly one destination, tool names carry no redundant prefix β they are plain lowercase snake_case (`get_source`, `run_query`, `lint_abap`); the server name already states which SAP system it targets. Only when one server fronts several destinations (manual multi-destination startup) does each name gain its destination slug (`demo-abap_run_query`) to stay unambiguous. Lowercase names are deliberate: BAS and VS Code derive chat tool references from the server and tool names and only bind lowercase identifiers, so mixed-case names show up in the tools picker but never bind to the chat session. Use the exact names shown by your MCP client; punctuation can change during slugification.
Upgrading from an earlier release that wrote mixed-case entry names (for example `ActionS4D` or `cf:::`)? Re-run `sap-ai-dev --setup` to replace legacy entries β this is the only migration path for Cloud Foundry entries β or run `sap-ai-dev --doctor` to rename BAS entries in place. Then reload the BAS window and start a new chat; an existing chat keeps its stale tool binding. If setup reports that the lowercase name already exists and is not managed by this package, rename or remove that user-owned server entry first.
The proxy keeps upstream tool descriptions and input schemas, then adds the destination label. `LintABAP` and the workflow tools are implemented locally; they use the schemas shown by `tools/list` and call only the destination attached to their name. Linting operates on submitted source in memory. The live `tools/list` result remains the source of truth for the installed runtime's exact schemas.
_lint_abap`). It accepts caller-supplied source files with `object.type.extension` filenames; config is optional and, when present, is the full abaplint configuration rather than a merge with defaults.
```json
{
"files": [
{
"filename": "zdemo.prog.abap",
"source": "REPORT zdemo.\nWRITE 'Hello'."
}
]
}
```
`files` must be a nonempty array of `{ "filename": string, "source": string }` entries. The basename follows `..`, such as `zcl_demo.clas.abap`. If the code depends on other objects, include those sources in the same `files` array; the tool does not resolve `config.dependencies`, read local files, make network requests, or contact SAP.
The single text item in the MCP result contains JSON: `{ "status": "clean" | "issues", "filesChecked": number, "issueCount": number, "errors": number, "warnings": number, "infos": number, "issues": [...] }`. Each issue reports filename, rule, severity, message, and start/end positions with line and column. Lint findingsβincluding Error-severity findingsβare reports, not MCP tool-call errors.
### 𧩠Review and delivery workflows
These local tools are namespaced by destination. Change-set tools appear when the runtime exposes `GetSource` and `WriteSource`; transport and Clean Core tools appear when their underlying checks exist. RAP suite tools use the selected destination's proxy route.
| Tool | Behavior |
| --- | --- |
| `PrepareABAPChangeSet` | Stage up to 12 full-source `WriteSource` changes and return line diffs plus SHA-256 fingerprints. Proposals stay in MCP process memory. |
| `ApplyABAPChangeSet` | Re-read each object and write only when its source still matches the reviewed version. It stops on conflicts or errors and reports partial application; it does not roll back SAP writes. |
| `UpdateTable` | Compare the current Z/Y table DDL with reviewed source, then update and activate through VSP's source-hash check under lock. Requires exact confirmation. |
| `DeleteEmptyDDLS` | Delete only a blank Z/Y DDLS shell after checking its source and requiring exact confirmation; generic `DeleteObject` remains hidden. |
| `CheckTransportReadiness` | Run a caller-selected bundle of transport, dependency, inactive-object, ABAP Unit, and ATC checks. Completed calls may still contain findings. |
| `PlanABAPCloudMigration` | Batch `GetAPIReleaseState` checks for ADT object URIs and prioritize recognized unreleased APIs ahead of unknown and released states. SAP evidence stays attached. |
| `GenerateRAPRegressionSuite` | Read `$metadata` and return reusable JSON with a metadata check and one `$top=1` GET for each entity set. |
| `RunRAPRegressionSuite` | Run the saved suite with GET requests, expected status/content-type checks, and optional JSON-path assertions. Requests stay under the same `/sap/opu/odata` service root; response bodies are capped at 2 MiB. |
For a change set, pass the exact `GetSource` arguments and observed full source for each object, plus exact `WriteSource` arguments containing the replacement source. Each source is limited to 128 KiB and 1,000 lines so the full diff can be reviewed. Review every diff before calling `ApplyABAPChangeSet`. Each object is checked immediately before its write; a change after that read can still race the write because the runtime does not expose compare-and-write here.
For a transport report, include exactly one `GetTransport` check whose `transport` matches `transport_id`, then add applicable dependency, inactive-object, ABAP Unit, or ATC checks. Each uses the exact arguments in the live upstream schema.
For an ABAP Cloud assessment, get object URIs from `SearchObject` and pass them to `PlanABAPCloudMigration`. It reports release evidence; it does not guess replacement APIs. Save the JSON from `GenerateRAPRegressionSuite` and pass it to `RunRAPRegressionSuite` after relevant service changes.
`sap-ai-dev --doctor` probes each discovered destination, checks that each managed MCP entry still matches its selected BAS destination, starts the runtime, lists MCP tools, and calls `GetSystemInfo` directly when that tool is exposed. It repairs only tagged toolkit-owned BAS entries that can be verified against complete destination discovery; it does not add destinations, remove stale or third-party entries, or overwrite malformed configuration. `--doctor --json` reports redacted diagnostics and exits unsuccessfully when a required check fails.
`tools/list` confirms what this MCP server exposes; it does not prove that VS Code attached the server to the active chat. Start the selected destination in **MCP: List Servers**, enable it in the Chat tools picker, and reload/reselect the agent if the host binding is stale. This add-on cannot inspect or repair another MCP server's registration or a host-wide tool budget.
`sap-ai-dev --demo` starts an isolated server with sample ABAP objects, test and ATC results, a sample transport, and synthetic OData metadata and rows. Source edits and transport creation stay in process memory and disappear on exit. The demo does not discover or contact BAS or SAP destinations.
### π Find and understand ABAP objects
| Tool | What it does |
| --- | --- |
| `GetSource` | Read source for programs, classes, interfaces, function modules and groups, includes, CDS, and supported RAP/DDIC objects. |
| `SearchObject` | Find repository objects by name or wildcard query. |
| `GrepObjects` | Search regular expressions across specified object URLs. |
| `GrepPackages` | Search regular expressions in one or more packages, optionally including subpackages. |
| `FindDefinition` | Locate a symbol's definition from source text and a position. |
| `FindReferences` | Find references to an object or a symbol. |
| `GetContext` | Summarize public signatures of source dependencies for code review. |
| `CompareSource` | Compare two objects and return a unified diff. |
| `GetClassInfo` | Inspect class methods, attributes, interfaces, and inheritance metadata. |
| `GetPackage` | Read package details. |
| `GetAPIReleaseState` | Check whether an object is released for S/4HANA Clean Core / ABAP Cloud development; use the URI returned by `SearchObject`. |
| `GetFunctionGroup` | Read function-group source. |
| `GetFunction`, `GetClass`, `GetClassComponents`, `GetClassInclude`, `GetProgram`, `GetInclude`, `GetInterface` | Read supported object-specific source or metadata views. |
| `ListDependencies` | List dependencies for impact and transport-readiness planning. |
| `GetInactiveObjects` | List objects changed by the current user but not yet activated. |
| `UI5ListApps`, `UI5GetApp`, `UI5GetFileContent` | List UI5/Fiori apps in the ABAP repository and read their files. Read-only: the ADT filestore cannot deploy apps, so deploy them with SAP Fiori tools. |
### ποΈ Read SAP tables and metadata
| Tool | What it does |
| --- | --- |
| `GetTable` | Read an ABAP Dictionary table's structure. |
| `GetTableContents` | Read table rows, optionally with an ABAP SQL filter and row limit. |
| `RunQuery` | Run a freestyle ABAP SQL query against the SAP database. |
| `GetCDSDependencies` | Follow a CDS view's forward dependencies to its sources. |
| `GetCDSImpactAnalysis` | Find downstream consumers of a CDS view (reverse dependencies). |
| `GetCDSElementInfo` | Read CDS element names, types, annotations, and semantic metadata. |
`RunQuery` uses ABAP SQL, not generic SQL. Use `max_rows` instead of `LIMIT`; for ordering use `ASCENDING` or `DESCENDING`, not `ASC` or `DESC`.
SAP authorizations and the destination's available APIs still apply.
### βοΈ Create, update, and activate
| Tool | What it does |
| --- | --- |
| `WriteSource` | Create or update supported ABAP source objects; detects create versus update in upsert mode. |
| `EditSource` | Replace a specific source fragment; syntax checking is enabled by default. |
| `PrepareABAPChangeSet` | Stage reviewed full-source diffs for up to 12 `WriteSource` changes. |
| `ApplyABAPChangeSet` | Re-read each staged object and apply reviewed writes when the source still matches. |
| `SyntaxCheck` | Ask SAP to syntax-check source before saving or activation. |
| `Activate` | Activate one named ABAP object. |
| `ActivateMultiple` | Activate related objects together while resolving mutual dependencies, such as an include and its main program. |
| `CreateObject` | Create a new object, including RAP service bindings (`SRVB/SVB`; pass `binding_version` `V4` for Fiori Elements V4 apps, because the default is V2). |
| `PublishServiceBinding` | Publish an activated service binding as an OData service; V2 and V4 bindings are both supported. |
| `UnpublishServiceBinding` | Withdraw a published service binding. |
The write, activation, and publication tools change SAP state. Confirm the target, package, and transport before using them. `EditSource` performs a focused replacement; its default syntax check prevents saving when syntax errors are reported.
### β
Test and inspect the system
| Tool | What it does |
| --- | --- |
| `RunUnitTests` | Run ABAP Unit tests for an object; dangerous and long-running tests are excluded by default. |
| `RunATCCheck` | Run an ABAP Test Cockpit check and return findings. |
| `GetSystemInfo` | Read system ID, SAP release, kernel, and database details. |
| `GetInstalledComponents` | List installed software components and versions. |
| `GetFeatures` | Probe optional system capabilities, including RAP/OData, AMDP debugging, UI5/BSP, and CTS transports. |
| `GetConnectionInfo` | Show the connected user, client, URL, mode, and feature-probe summary for the current destination session. |
| `PrettyPrint` | Format ABAP source text without saving it to SAP. |
### π Inspect and create transports
| Tool | What it does |
| --- | --- |
| `ListTransports` | List a user's transport requests with optional status, type, source, date, and grouping filters. |
| `GetUserTransports` | Read and group a user's transport requests and tasks; supports organizer filters and source selection. |
| `GetTransport` | Read a transport request's details, objects, and tasks. |
| `GetTransportInfo` | Find eligible transports and lock status for an ABAP object or package. |
| `LockObject` | Lock an ABAP repository object in SAP. |
| `UnlockObject` | Unlock an ABAP repository object in SAP. |
| `CreateTransport` | Create a transport request. |
| `CheckTransportReadiness` | Collect a whitelisted bundle of transport, dependency, inactive-object, ABAP Unit, and ATC evidence. |
`LockObject` and `UnlockObject` are state-changing tools; the proxy does not retry them after a child crash to avoid duplicate side effects.
Transport release and deletion are not exposed by the curated proxy surface; release or delete transports outside this add-on after review.
The proxy enables transport support and permits source edits in transportable packages through generated MCP entries. Runtime safety checks and SAP authorizations still apply.
### π Read SAP application logs (SLG1)
| Tool | What it does |
| --- | --- |
| `GetApplicationLog` | Extract newest-first application log entries, optionally including message details and texts. |
- Filter by program, user, object, subobject, from, and to.
- `max_results` defaults to 100. Date-only `to` values include the full day.
- `messages: true` adds BALDAT details and T100 message text; otherwise, the tool returns log headers only.
- The proxy maps this convenience tool to the single upstream `SAP(action="analyze", type="application_log")` operation. The general-purpose `SAP` router itself is hidden from direct calls.
The proxy intentionally limits the child process tool surface. Object deletion, broad trace surfaces, arbitrary SAP router/RFC calls, debugger helper/delete-breakpoint routes, UI5 repository writes, and transport release/delete tools are hidden from direct MCP calls. The curated debugger tools (`SetBreakpoint`, `GetBreakpoints`, `DebuggerAttach`, `DebuggerGetStack`, `DebuggerGetVariables`, `DebuggerStep`, and `DebuggerDetach`) remain available when supported by the runtime and target system. Direct runtime invocation without `H2O_URL` retains its full tool surface; in an interactive local terminal, use an explicit command argument because plain `sap-ai-dev` starts local setup.
### π Ready to put the tools to work from chat?
1. Start the generated server in BAS with **MCP: List Servers**.
2. In the Chat tools picker, enable the server for the destination you want.
3. Ask for the operation in plain language. The MCP client sends `tools/call`; no need to type a tool such as `GetSource` into a terminal.
4. Check the response in chat. For source edits, ask for a syntax check and tests before activation when that matches your workflow.
For a quick table readβsay, company codes from `T001`βselect the destination's `RunQuery` tool (exposed as `run_query`; `demo-abap_run_query` only on a multi-destination server) and pass:
```json
{
"sql_query": "SELECT BUKRS, BUTXT, WAERS, LAND1 FROM T001",
"max_rows": 100
}
```
The same request can be expressed to an MCP client as:
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "run_query",
"arguments": {
"sql_query": "SELECT BUKRS, BUTXT, WAERS, LAND1 FROM T001",
"max_rows": 100
}
}
}
```
Use the name returned by `tools/list` instead of copying the example name. For a plain table read, `GetTableContents` requires `table_name` and accepts `max_rows`; `RunQuery` requires `sql_query` and accepts `max_rows` or `all_rows`.
To read a class implementation, select `GetSource` and pass:
```json
{
"object_type": "CLAS",
"name": "ZCL_ORDER",
"include": "implementations"
}
```
The MCP client discovers the schemas; callers do not need to memorize every argument. For example, `GetSource` requires `object_type` and `name`, while `GrepPackages` requires `packages` and `pattern`. Inspect the live schema before calling an unfamiliar tool.
### π Inspect installed servers and tools
| What to inspect | How |
| --- | --- |
| Add-on command options | `sap-ai-dev --help` |
| BAS destinations and probe status | `sap-ai-dev --list-destinations --json` (BAS only) |
| Destination availability only | `sap-ai-dev --check` |
| Generated server names and destination mapping | **MCP: Open User Configuration**; look for lowercase slug entries (for BAS, for example `demo-abap`; for local SAP GUI, system/client slugs such as `t4d-100`) whose `SAP_AI_DEV_TOOLKIT_DESTINATION` names the BAS destination or local SAP GUI system. |
| Running server | **MCP: List Servers**; select the server and choose **Start Server**. |
| Tools and exact schemas | Expand that server in the Chat tools picker. The MCP host requests `tools/list`, whose entries include `name`, `description`, and `inputSchema`; the agent should call those tools through chat, not reproduce the protocol in a terminal. |
| Runtime and tool-call logs | Select the MCP server in the Output view. Startup, call lifecycle, and child stderr logs are written to stderr; child MCP log notifications are forwarded to the client. Tool arguments and result contents are not logged. |
| Installed package version | `npm list --global sap-ai-dev-toolkit` |
If the server is running but an agent reports that SAP tools are unavailable, verify that the same chat is in Agent mode, the generated server is enabled in that chat's tools picker, and concrete names such as `s4h_get_system_info` are listed. All generated server and tool names are lowercase; a mixed-case entry such as `ActionS4D` is a pre-upgrade leftover that chat cannot bind β rerun setup or `--doctor` as described above to migrate it. Reselect the agent or start a new chat if the tool binding is stale, then inspect the MCP server's Output log for startup or `tools/list` errors. Do not try to work around a missing chat binding by starting the server or handcrafting JSON-RPC from the terminal.
After MCP initialization, the host internally sends a request like this; agents should not reproduce it in the terminal:
```json
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
```
The response contains a `tools` array. A `RunQuery` entry resembles this excerpt; the actual description may include more detail:
```json
{
"name": "run_query",
"description": "Execute an ABAP SQL query [destination: DEMO_ABAP]",
"inputSchema": {
"type": "object",
"properties": {
"sql_query": { "type": "string" },
"max_rows": { "type": "number" },
"all_rows": { "type": "boolean" }
},
"required": ["sql_query"]
}
}
```
`--list-destinations` reports discovery and probe status; it does not list the MCP tools. Use the MCP client tool picker or its `tools/list` inspection for that. stdout is reserved for MCP protocol messages while the server is running, so do not pipe the normal server command to a shell JSON formatter.
### π§ Environment variables
| Variable | Purpose |
| --- | --- |
| `H2O_URL` | BAS endpoint used to discover destinations. Required for BAS discovery. |
| `SAP_AI_DEV_TOOLKIT_DESTINATION` | Comma-separated destination allowlist for normal runtime discovery. Setup clears this temporarily so it can display all eligible systems. |
| `SAP_AI_DEV_TOOLKIT_MODE` | Runtime mode (`expert` by default; `focused` omits `ActivateMultiple`, `GetUserTransports`, and `GetTransportInfo`). The proxy exposes its curated tool subset and local workflow tools, including `LintABAP`. |
| `SAP_ALLOW_TRANSPORTABLE_EDITS` | Generated MCP entries set this to `true` to permit source edits in transportable packages; runtime safety checks and SAP authorizations still apply. |
| `SAP_AUTH_MODE=sso` | Local SAP GUI entry mode for Windows / smart card SSO. Runtime starts the SAP process with `SAP_SSO=true`, which signs in through Microsoft Edge and caches the session per system and client. Older `windows-sso`, `browser-saml`, and `saml-password` entries are treated as `sso`. |
| `SAP_TLS_SERVER_NAMES` / `SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES` | Comma-separated local SAP GUI TLS self-healing names, normally auto-discovered during setup from the SAP HTTPS certificate when `SAP_URL` uses an IP address. Runtime tries them one by one while keeping certificate validation enabled. |
| `SAP_TLS_SERVER_NAME` / `SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME` | Single-name compatibility form of the local SAP GUI TLS self-healing override. Prefer the auto-discovered plural variable written by setup. |
| `SAP_TLS_CA_FILE` / `SAP_AI_DEV_TOOLKIT_TLS_CA_FILE` | Optional PEM CA bundle for the local TLS self-healing proxy when the SAP HTTPS certificate chains to a private CA that is not in the OS/Node trust store. Certificate verification remains enabled. |
| `SAP_AI_DEV_TOOLKIT_HTTP_PROXY` | Egress proxy for BAS discovery and probe traffic. Takes precedence over `HTTP_PROXY`/`http_proxy`; unset means the default BAS proxy for `.dest` hosts, empty means direct. |
| `SAP_AI_DEV_TOOLKIT_REQUEST_TIMEOUT_MS` | Per-request timeout for calls forwarded to a runtime process (default 600000 = 10 minutes; `0` disables). A stalled request fails with a timeout error; the process is left running. |
| `SAP_AI_DEV_MCP_CONFIG` | Explicit MCP configuration path; highest precedence. |
| `SAP_AI_DEV_TOOLKIT_MCP_CONFIG` | Branded compatibility alias for the MCP configuration path. |
| `SAP_AI_DEV_TOOLKIT_BINARY` | Trusted prebuilt runtime executable; skips binary provisioning. |
| `SAP_AI_DEV_TOOLKIT_BINARY_URL` | Alternate runtime binary download URL (checksum-verified). |
| `SAP_AI_DEV_TOOLKIT_RELEASE_BASE_URL` | Override the base URL that runtime binaries are downloaded from. |
| `SAP_AI_DEV_TOOLKIT_CACHE_DIR` | Runtime binary cache directory. |
| `BAS_CF_SPACE_GUID`, `BAS_CF_DESTINATION_INSTANCE_GUID`, `BAS_CF_DESTINATION_INSTANCE`, `BAS_CF_DESTINATION_KEY`, `BAS_CF_DESTINATION_NAME`, `BAS_CF_CONNECTIVITY_INSTANCE_GUID`, `BAS_CF_CONNECTIVITY_INSTANCE`, `BAS_CF_CONNECTIVITY_KEY` | Written into generated Cloud Foundry destination entries; they reference service instances and key **names** (never credentials). |
| `GO_BINARY` | Explicit Go executable for the repository-only runtime build script; not used during installation. |
| `SAP_AI_DEV_TOOLKIT_SKIP_PROBE=true` | Skip destination probes; useful for controlled diagnostics or fixtures. |
| `HTTP_PROXY` / `HTTPS_PROXY` | BAS proxy settings used for destination-list requests, destination probing, and child processes. |
| `NO_PROXY` | Proxy bypass list for BAS destination-list requests; `.dest` hosts remain routed through the BAS proxy. |
#### Self-healing modes
Runtime processes connect to each configured destination URL directly. BAS destination authentication remains selected through the configured proxy-auth path; Cloud Foundry on-premise destinations continue through the separate Connectivity proxy.
Child crash recovery restarts a failed runtime process, re-initializes it, re-registers tools, and retries the interrupted `tools/call` once before surfacing an error. State-changing tools are not retried.
Existing installs retain support for legacy environment aliases. The setup wizard writes new MCP entries with the `SAP_AI_DEV_TOOLKIT_*` names.
#### Server logging
Every observable event β startup banner (version, PID, runtime executable), destination discovery, runtime session initialization, each JSON-RPC request with its id, every tool call with duration and outcome, self-healing restarts, and errors β is logged twice: to **stderr** with ISO timestamps (visible when the server runs in a terminal or in hosts that surface stderr), and to the host's **MCP server output channel** as standard `notifications/message` log notifications (VS Code/BAS and Claude Code render these under the server's output). Log notifications start at `info`; send `logging/setLevel` with `debug` (or higher) from the client to adjust what reaches the channel β stderr always receives everything. Credentials, cookies, and tokens are redacted.
-.bak` and replaced; the backup path is printed in the setup warning. On older versions, re-save the file as UTF-8 without BOM (VS Code: "Change File Encoding β Save with Encoding β UTF-8") and rerun `sap-ai-dev --setup`.
If automatic runtime provisioning fails, check network access and the package's supported platform. You can install Go manually or set `GO_BINARY` as an explicit fallback. A trusted prebuilt executable can be supplied with `SAP_AI_DEV_TOOLKIT_BINARY`.
## π§βπ» Development
Run the built-in Node.js test suite:
```sh
npm test
```
The package repository is [grknylmz/sap-ai-dev-toolkit](https://github.com/grknylmz/sap-ai-dev-toolkit).
## π Publishing to npm
The package publisher reads `NPM_PUBLISH_TOKEN` from the root `.env` file (already gitignored) or from the environment. Create `.env` with a publish-capable npm token:
```sh
NPM_PUBLISH_TOKEN=npm_...
```
- `npm run publish:npm` publishes the version already set in `package.json`.
- To publish a patch bump, run `npm run publish:npm -- --patch`; it updates `package.json` and `package-lock.json` before publishing. If publishing fails after the bump, retry without `--patch`.
- npm's `prepublishOnly` hook builds the pinned runtime binaries for all platforms (including the Go toolchain if missing) and refuses to ship a tarball whose `dist/checksums.txt` does not list all five assets; it guards `npm run publish:npm` and a plain `npm publish` alike. Pass `--skip-build` to republish an already-built `dist/` without rebuilding.
- Preview the package without publishing, changing its version, or building with `npm run publish:npm -- --dry-run`.
- GitHub Actions runs the test suite on pushes to `main` and pull requests. A push to `main` that changes the `package.json` version runs the same checks, builds the runtime binaries, publishes that version to npm, and creates a `v` GitHub release with generated notes and the binaries plus `checksums.txt` attached for the download fallback.
- The publish workflow uses the `NPM_PUBLISH_TOKEN` GitHub repository secret. Verify it with `gh secret list`; the token value is never stored in the repository.
The token is not printed or stored in the repository.
## π Acknowledgements and licenses
The original SAP AI Development Toolkit code and project changes are copyright (c) 2026 Gurkan Yilmaz and released under the MIT License. Everyone may use, copy, modify, distribute, sublicense, and sell copies, provided the copyright and license notices are retained; the software is provided without warranty. See `LICENSE`. Bundled third-party components retain their own licenses and notices in `NOTICE` and `LICENSE-APACHE-2.0.txt`.
The bundled runtime and its dependencies retain their original licenses and required attribution. The package includes the applicable notices and license texts in `LICENSE`, `NOTICE`, and `LICENSE-APACHE-2.0.txt`.
License sources:
- `LICENSE`
- `NOTICE`
- Apache License 2.0
