sap-adt-commands

name	sap-adt-commands
description	Executes SAP ABAP Development Tools (ADT) REST operations for object discovery, source management, object creation, activation, testing, transport handling, history, where-used analysis, message classes, and text elements. Use when working with an SAP ABAP system and the required ADT operation is unavailable through the currently configured MCP tools.
license	Apache-2.0
compatibility	Requires network access to an SAP system with the relevant ADT services enabled. Requires Python 3.10 or newer. No prebuilt executable is distributed; contributors may optionally build one locally with the provided PyInstaller spec.
metadata	{"author":"Leo Trinh","version":"3.5.0","category":"sap-abap","repository":"leotrinh/agent-skills-for-sap"}

SAP ADT Commands

Command-line access to SAP ABAP Development Tools (ADT) REST services from an AI agent workflow. The client covers areas that many existing MCP tools do not expose: repository search, object creation, message-class and text-element maintenance, transport lifecycle, and quality checks.

Purpose

Give the agent a safe, scriptable way to inspect and modify ABAP objects on a target SAP system when no MCP tool covers the operation. Every command returns JSON so results can be routed into subsequent steps.

When to Use

Activate this skill when the user is working with an SAP ABAP system and any of the following are true:

• The task requires an ADT operation not exposed by the configured MCP tooling (search, package browsing, transport management, message-class edits, text-element edits, CDS creation, and similar).
• The user asks to inspect, create, or modify an ABAP object and only ADT REST endpoints can do it.
• The user asks for repository-level reporting, such as "list all objects owned by user X" or "which objects are inactive".

When Not to Use

Do not activate this skill when:

• An existing MCP tool already handles the requested operation. Prefer the MCP path.
• The user needs SAP GUI-only capabilities such as ATC baseline management, runtime debugging with breakpoints, ABAP dictionary DDIC screens, or update-task processing.
• The target system is a production tenant and the user has not confirmed the intent to run against production.
• The user asks the agent to type or transmit an SAP password directly.

Safety Rules

The agent must:

1. Prefer an existing MCP tool when it fully supports the requested operation.
2. Use this client only when the configured MCP tool does not support the required operation.
3. Start with read-only discovery before modifying anything.
4. Never ask the user to paste a password into the chat.
5. Never place a password directly on a generated command line.
6. Use destination-based environment resolution (--dest) when it is available.
7. Confirm the exact target object, package, transport, and system before a write operation.
8. Treat source writes, deletes, unlocks, activation, transport release, transport deletion, and object moves as sensitive operations.
9. Require explicit human authorization immediately before any destructive or hard-to-reverse operation.
10. Never infer authorization to delete or release something from a broader task description such as "clean up", "deploy", or "ship".
11. Report the exact command, the response, and any remaining risk after every operation.
12. Stop and report when ADT services, authorizations, object locks, or transport configuration prevent safe execution.
13. Never loop retries on authorization failures or malformed requests.
14. Never claim a write succeeded unless the tool response confirms it.

Tool Selection

When faced with a task, decide in this order:

1. Is there a matching MCP tool? If yes, use it.
2. Does this skill implement the operation? See Command Groups below.
3. If neither can do it, tell the user what is missing and suggest SAP GUI (SE38, SE80, SM12, SE01/SE09/SE10, SCI) or Eclipse ADT.

Do not fall through to this client "just in case". Every write here is a real change on the target system.

Connection Model

The client accepts either explicit flags (--url, --user, --pwd, --client, --lang) or a destination name:

--dest SID_CLIENT_USER_LANG

Generic example:

--dest DEV_100_DEVELOPER_EN

For --dest DEV_100_DEVELOPER_EN, the client resolves:

• url from SAP_DEV_URL
• user from SAP_DEV_DEVELOPER_USER, else the DEVELOPER part of the name
• pwd from SAP_DEV_DEVELOPER_PWD (must exist)
• client = 100
• lang = EN

The one-time setup below is performed by the human. The agent may set the URL variable when the URL is not secret, but must never set a password variable itself:

# URL — non-secret; may be scripted by the agent when known
setx SAP_DEV_URL "https://sap.example.com:44300"

# Password — set by the human only
setx SAP_DEV_DEVELOPER_PWD "<password>"

When any required variable is missing, the client returns a JSON error that names the exact setx commands to run. Treat this as a configuration issue, not a network failure.

Full details are in references/connection-and-credentials.md.

Execution Pattern

Every invocation looks like:

python $client --dest DEV_100_DEVELOPER_EN <command> [options]

Where $client holds the repo-root-relative path to the Python source:

$client = ".\skills\sap-adt-commands\scripts\adt-client.py"

The examples below assume the current working directory is the repository root. When the skill is installed by an AI client (for example via npx skills add), the on-disk layout is client-specific — resolve the installed skill directory for that client instead of assuming this path.

Do not define the client variable as a two-element string array such as $exe = "python", "scripts/adt-client.py" and then invoke it with & $exe .... That pattern relies on PowerShell array splatting, is flagged by PSScriptAnalyzer, and breaks in subtle ways when arguments contain spaces or quotes. Keep the variable as a single script path and put python on the command line explicitly, or invoke python directly without a variable.

The output is JSON on stdout. Non-zero exit codes accompany connection or runtime failures. See references/development.md for installation, dependencies, and the optional local build procedure.

Command Groups

Each group has a dedicated reference file. Load a reference only when the agent is actively working on that group.

• Discovery and inspection — read-only browsing, search, source read, metadata, where-used, history, diff. Load references/command-discovery-and-inspection.md when the task begins, before any write. Commands: discovery, search, objects, packages, packages-by-responsible, objects-by-user, reports-by-user, source, object-properties, where-used, history, diff, inactive-objects, transports, transport-contents, read-message-class, read-text-elements.

• Source and object management — writes, creations, activation, unlock, and delete. Load references/command-source-and-object-management.md when the confirmed task involves modifying or creating ABAP objects. Commands: write-source, create-package, create-program, create-class, create-interface, create-function-group, create-function-module, create-cds, create-transaction, create-message-class, activate, unlock, delete.

• Message classes and text elements — read and edit T100 messages and program text elements. Load references/command-messages-and-text-elements.md when the task involves messages or selection-screen / symbol / heading texts. Commands: read-message-class, write-messages, add-message, update-message, delete-message, read-text-elements, write-text-elements.

• Quality checks and testing — static analysis and unit tests. Load references/command-quality-and-testing.md before proposing an activation or release for changes the agent authored. Commands: , .

Recommended Workflows

Each workflow is a short sequence, not an exhaustive script. Read the relevant reference file before running write steps.

Browse and inspect

python $client --dest DEV_100_DEVELOPER_EN discovery
python $client --dest DEV_100_DEVELOPER_EN search "Z*" --type PROG/P
python $client --dest DEV_100_DEVELOPER_EN objects ZEXAMPLE_PACKAGE
python $client --dest DEV_100_DEVELOPER_EN objects-by-user DEVELOPER --type CLAS/OC
python $client --dest DEV_100_DEVELOPER_EN object-properties ZEXAMPLE_PROGRAM --type PROG/P

Read and diff source

python $client --dest DEV_100_DEVELOPER_EN source ZEXAMPLE_PROGRAM --type PROG/P
python $client --dest DEV_100_DEVELOPER_EN diff ZEXAMPLE_PROGRAM --type PROG/P
python $client --dest DEV_100_DEVELOPER_EN history ZEXAMPLE_PROGRAM --type PROG/P

Create and activate an object

python $client --dest DEV_100_DEVELOPER_EN create-package ZEXAMPLE_PACKAGE `
    --description "Example package" --superpackage ZEXAMPLE_ROOT --transport DEVK900001
python $client --dest DEV_100_DEVELOPER_EN create-program ZEXAMPLE_PROGRAM `
    --description "Example report" --package ZEXAMPLE_PACKAGE --transport DEVK900001
python $client --dest DEV_100_DEVELOPER_EN write-source ZEXAMPLE_PROGRAM `
    --text "REPORT zexample_program." --type PROG/P --transport DEVK900001
python $client --dest DEV_100_DEVELOPER_EN activate ZEXAMPLE_PROGRAM:PROG/P

Confirm each step with the human when the write is destructive or targets a tracked transport.

Manage messages

python $client --dest DEV_100_DEVELOPER_EN create-message-class ZEXAMPLE_MSAG `
    --description "Example messages" --package ZEXAMPLE_PACKAGE --transport DEVK900001
python $client --dest DEV_100_DEVELOPER_EN add-message ZEXAMPLE_MSAG --id 001 --text "No data found" --transport DEVK900001
python $client --dest DEV_100_DEVELOPER_EN update-message ZEXAMPLE_MSAG --id 001 --text "No data for selection" --transport DEVK900001
python $client --dest DEV_100_DEVELOPER_EN activate ZEXAMPLE_MSAG:MSAG/N

Manage transports

python $client --dest DEV_100_DEVELOPER_EN transports --owner DEVELOPER
python $client --dest DEV_100_DEVELOPER_EN transport-contents DEVK900001
python $client --dest DEV_100_DEVELOPER_EN create-transport --description "TICKET-1234: Feature X" --package ZEXAMPLE_PACKAGE
python $client --dest DEV_100_DEVELOPER_EN move-object ZEXAMPLE_PROGRAM:PROG/P --transport DEVK900002

Never release or delete a transport without contemporaneous human authorization.

Run quality gates

python $client --dest DEV_100_DEVELOPER_EN atc-check ZEXAMPLE_PROGRAM:PROG/P
python $client --dest DEV_100_DEVELOPER_EN abap-unit ZEXAMPLE_PROGRAM:PROG/P

An UNKNOWN gate is not a PASS. See references/command-quality-and-testing.md.

Error Handling

• If the client returns {"error": "Missing connection values ..."}, follow the connection reference; do not retry blindly.
• On HTTP 401 or 403, stop and report; do not retry with the same credentials.
• On HTTP 404 for CTS or workarea endpoints, report the endpoint absence and suggest the SAP GUI fallback (SE01, SE09, SE10, SE80).
• On HTTP 406 for message-class or text-element reads, use the client default (Accept: */*); the client already handles this.
• On any partial success from release-transport, stop and report per-task results before deciding whether to retry.

Detailed decision trees are in references/troubleshooting.md.

Bundled Resources

• scripts/adt-client.py — Python source (authoritative and only distributed entry point).
• scripts/adt-client.spec — optional PyInstaller build configuration for contributors who want to package a local executable for their own use. No prebuilt binary is committed to the default branch.
• requirements.txt — Python runtime dependencies.
• references/*.md — focused documentation for each command group.

Completion Checklist

Before reporting a task complete, verify:

• The last written object was activated, or the user explicitly asked to leave it inactive.
• Any transport that received new objects is either still open (and documented) or was released with explicit human authorization.
• object-properties or a similar read-only call confirms the final state matches the intent.
• The final response to the user includes the exact commands run, the resulting transport numbers, and any inconclusive quality-check outcomes.