@abapify/adt-mcp

MCP (Model Context Protocol) server that exposes SAP ADT operations as structured tools for AI assistants, IDE integrations, and automation pipelines.

This package ships two transports:

See docs/deployment/mcp-http.md for the complete HTTP deployment guide (Docker, Okta, multi-system, troubleshooting). The rest of this README focuses on stdio.

Quick Start (stdio)

# Run via npx (no install required)
npx @abapify/adt-mcp

Configure in Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your OS:

{
  "mcpServers": {
    "adt": {
      "command": "npx",
      "args": ["@abapify/adt-mcp"]
    }
  }
}

Configure in VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json in your workspace, or to your user settings under "mcp":

{
  "servers": {
    "adt": {
      "type": "stdio",
      "command": "npx",
      "args": ["@abapify/adt-mcp"]
    }
  }
}

Configure in Cursor / Windsurf

Add to your MCP server list:

{
  "mcpServers": {
    "adt": {
      "command": "npx",
      "args": ["@abapify/adt-mcp"]
    }
  }
}

HTTP transport (since Wave 1)

adt-mcp-http is the Streamable HTTP entry-point. It targets shared / remote deployments (Docker, Kubernetes, Kiro, teams).

Minimal run:

bunx nx build adt-mcp
node packages/adt-mcp/dist/bin/adt-mcp-http.mjs --port 3000 --auth-token "$(openssl rand -hex 32)"

Minimal smoke test:

TOKEN=<your token>
curl -sf http://127.0.0.1:3000/healthz
curl -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -X POST http://127.0.0.1:3000/mcp \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"demo","version":"0"}}}'

Capture the Mcp-Session-Id response header, then call sap_connect, the tools you need, and finally sap_disconnect — or close the transport to trigger cleanup automatically.

Auth modes: none (dev / loopback), bearer (shared secret), proxy (trust x-forwarded-user from an upstream proxy), oauth (OIDC JWT validation against Okta / Entra ID / Cognito). Full flag + env matrix in docs/deployment/mcp-http.md.

Session lifecycle tools

Only available on the HTTP transport:

Transactional changesets (since Wave 3)

Bundle multiple ADT writes into a single atomic unit:

See docs/deployment/mcp-http.md#transactional-changesets for a worked example.

Connection Parameters

Every tool requires these connection parameters (passed per-call, never stored):

Security note: credentials are forwarded directly to the SAP system per request. The MCP server holds no state and persists no credentials.

Tools Reference

Discovery & System

discovery

Discover available ADT services on the SAP system. Useful for checking what endpoints the system supports before using other tools.

Parameters: connection only

Returns: JSON object with available service collections and their links.

system_info

Get SAP system and/or session information.

Parameters:

Returns:

{
  "session": { "user": "DEVELOPER", "client": "100", "language": "EN", ... },
  "system": { "systemId": "DEV", "release": "757", ... }
}

Object Repository

search_objects

Search for ABAP objects in the repository. Supports wildcards.

Parameters:

Returns:

{
  "count": 3,
  "objects": [
    { "name": "ZCL_MY_CLASS", "type": "CLAS/OC", "uri": "/sap/bc/adt/oo/classes/zcl_my_class", ... }
  ]
}

get_object

Get details about a specific ABAP object by name. Performs an exact-match search and returns the object metadata plus a list of similar objects if no exact match is found.

Parameters:

Returns:

{ "found": true, "object": { "name": "ZCL_MY_CLASS", "type": "CLAS/OC", "uri": "...", ... } }

or, when not found:

{ "found": false, "message": "Object 'FOO' not found", "similar": [...] }

Source Code

list_source_versions

List immutable ADT source-version metadata and transport provenance for every source component of one object. The result is metadata-only; it never embeds ABAP source.

get_source_version

Explicitly read one immutable source URI returned by list_source_versions or cts_transport_source_manifest. Output is bounded by maxBytes (1 MiB default, 4 MiB hard cap) and fails rather than truncating.

cts_transport_source_manifest

Build a metadata-only, component-granular exactness manifest for an ordered non-empty transport list. Every leaf reports its change kind, exactness, concrete request/task provenance, immutable base/head references when known, and a typed diagnostic when exact isolation cannot be proven.

get_source

Fetch ABAP source code for a program, class, interface, or function group. Supports version-aware reads, class includes, method-level reads, and regex grep for token-efficient source exploration.

Parameters:

Returns:

• Default: { object, bytes, source, version, include }
• method=*: { object, methodCount, methods }
• method=<name>: { object, method, startLine, endLine, bytes, source }
• grep: { object, pattern, matchCount, matches, methodContext }
• format=structured: { object, source, bytes, version, include, includes, methods }

Examples:

get_source objectName=ZCL_ORDER objectType=CLAS version=inactive
get_source objectName=ZCL_ORDER objectType=CLAS include=testclasses
get_source objectName=ZCL_ORDER objectType=CLAS method=get_name
get_source objectName=ZCL_ORDER objectType=CLAS grep="SELECT.*FROM"

Tip: Do not combine method and grep. Use grep to locate code, then method to read the full method.

update_source

Write new ABAP source code to an existing object. Internally performs the full SAP ADT lock→PUT→unlock cycle.

Parameters:

Returns:

{ "status": "updated", "object": "ZCL_MY_CLASS" }

⚠️ Always activate after updating — inactive source is not compiled and cannot be executed.

get_test_classes

Retrieve the test class definitions (FOR TESTING) embedded in an ABAP class. Returns the raw source of the testclasses include.

Parameters:

Returns: Plain ABAP source of the local test class include.

Activation & Syntax

activate_object

Activate one or more ABAP objects. Supports single-object and batch modes.

Single object mode:

Batch mode:

Returns:

{ "status": "activated", "count": 2, "objects": [{ "name": "ZCL_FOO", "type": "CLAS" }, ...] }

check_syntax

Run an ABAP syntax check on an object and return structured check messages. Uses the checkrun schema — no XML parsing in tool code.

Parameters:

Returns:

{
  "hasErrors": false,
  "hasWarnings": true,
  "reports": [
    {
      "reporter": "syntax",
      "triggeringUri": "/sap/bc/adt/oo/classes/zcl_foo",
      "checkMessageList": {
        "checkMessage": [{ "type": "W", "shortText": "Variable X is unused", ... }]
      }
    }
  ]
}

Unit Testing

run_unit_tests

Run ABAP Unit tests on an object or package and receive pass/fail counts broken down by test method.

Parameters:

Returns:

{
  "totalTests": 5,
  "passCount": 4,
  "failCount": 1,
  "errorCount": 0,
  "programs": [ ... ]
}

Package Management

list_package_objects

List ABAP objects contained in a package. Uses quickSearch with a packageName filter.

Parameters:

Returns:

{
  "packageName": "ZPACKAGE",
  "count": 12,
  "objects": [{ "name": "ZCL_FOO", "type": "CLAS/OC", ... }]
}

Change & Transport System (CTS)

cts_list_transports

List transport requests from the CTS.

Parameters:

Returns: Array of transport request descriptors.

cts_get_transport

Get details for a specific transport request.

Parameters:

Returns: Full transport descriptor including tasks and objects.

cts_create_transport

Create a new transport request.

Parameters:

cts_create_task

Create and verify a modifiable task under an existing transport request.

Parameters:

Returns: The parent transport number, created task number, normalized owner, and created status.

cts_release_transport

Release a transport request.

Parameters:

cts_delete_transport

Delete a transport request.

Parameters:

flow_checkout_tr

Reconcile an allowed local workspace to an exact transport source boundary. The tool delegates to @abapify/adt-flow; it does not run Git commands.

The JSON result contains changed, moved, removed, unchanged, descriptor, and SAP-call counts. With verifyInventory: true, it also contains refreshed inventory and per-item resolution outcomes. It never contains source bodies or credentials.

flow_index_tr

Persist inventory and unresolved-boundary descriptors for an allowed local workspace without reading or materializing source files. Unlike strict flow_checkout_tr, this tool records inexact components as omissions so a later exact checkout can retry them.

The JSON result contains transport/object descriptors and omission diagnostics; its source-call count is always zero.

ABAP Test Cockpit (ATC)

atc_run

Run ABAP Test Cockpit checks on an object or package and return the resulting findings worklist.

In destination mode, this operation requires an explicit safe_execute grant. A read grant is insufficient because SAP creates a temporary server-side worklist for the analysis.

Parameters:

Returns:

{ "status": "completed", "worklist": { ... } }

Common Workflows

Read → Edit → Save → Activate

1. get_source      objectName=ZCL_FOO objectType=CLAS
2. update_source   objectName=ZCL_FOO objectType=CLAS sourceCode="..." transport=DEVK900001
3. check_syntax    objectName=ZCL_FOO objectType=CLAS version=inactive
4. activate_object objectName=ZCL_FOO objectType=CLAS
5. run_unit_tests  objectName=ZCL_FOO objectType=CLAS

Explore a Package

1. list_package_objects packageName=ZPACKAGE
2. get_object      objectName=ZCL_FOO objectType=CLAS
3. get_source      objectName=ZCL_FOO objectType=CLAS

Quality Gate

1. check_syntax objectName=ZCL_FOO objectType=CLAS
2. atc_run      scope={"kind":"objects","objects":[{"objectType":"CLAS","objectName":"ZCL_FOO"}]}
3. run_unit_tests objectName=ZCL_FOO objectType=CLAS

Architecture

┌──────────────┐    stdio (JSON-RPC)   ┌──────────────────────────────┐
│  MCP Client  │ ◄───────────────────► │  @abapify/adt-mcp            │
│ (AI / IDE)   │                       │  McpServer (17 tools)        │
└──────────────┘                       └──────────────┬───────────────┘
                                                      │ calls
                                       ┌──────────────▼───────────────┐
                                       │  @abapify/adt-client         │
                                       │  (typed contracts via speci) │
                                       └──────────────┬───────────────┘
                                                      │ HTTP/HTTPS
                                       ┌──────────────▼───────────────┐
                                       │  SAP System (ADT REST)       │
                                       └──────────────────────────────┘

Design principles:

• No logic duplication – tools delegate to @abapify/adt-client services.
• Schema-based serialisation – request/response XML is handled via typed schemas from @abapify/adt-schemas. No manual XML building, no third-party XML parser.
• Structured JSON – every tool returns JSON, never raw console output.
• Zod validation – all tool inputs are validated before reaching the SAP system.
• Connection-per-call – each tool call creates its own ADT client; the server is stateless.

Programmatic Usage

import { createMcpServer } from '@abapify/adt-mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createMcpServer();
const transport = new StdioServerTransport();
await server.connect(transport);

Custom client factory (e.g. for testing or SSO)

import { createMcpServer } from '@abapify/adt-mcp';

const server = createMcpServer({
  clientFactory: (params) =>
    createAdtClient({
      baseUrl: params.baseUrl,
      username: params.username ?? '',
      password: params.password ?? '',
      client: params.client,
    }),
});

Testing

Integration tests use Vitest and a built-in mock ADT server that needs no SAP system.

# Run all integration tests
bunx vitest run tests/integration.test.ts

Using the mock server in your own tests

The mock ADT server lives in the private @abapify/adt-fixtures package (monorepo-only — it is not published to npm). Inside this repository the integration tests import it directly:

import { createMockAdtServer } from '@abapify/adt-fixtures';

Development

bunx nx build adt-mcp      # build
bunx nx typecheck adt-mcp  # type check
bunx nx lint adt-mcp       # lint
bunx nx test adt-mcp       # run integration tests with Vitest

Feature Parity Map