@mcp-abap-adt/lib

v10.2.0

Published

8 days ago

ADT tool handlers and an embeddable MCP server for SAP ABAP. The standalone server is @mcp-abap-adt/core.

0High
0Medium
0Low

fr0ster

abap sap adt mcp model-context-protocol mcp-server abap-cloud sap-btp xsuaa jwt-auth service-key crud

mcp-abap-adt: Your Gateway to ABAP Development Tools (ADT)

mcp-abap-adt is an MCP server for ABAP ADT in SAP ECC/S/4HANA (on-premise) and SAP BTP ABAP Cloud systems. It gives agents controlled access to real ABAP repositories through ADT, so analysis and changes are grounded in system data instead of assumptions. It is built for AI-assisted pair programming (AIPNV: AI Pairing, Not Vibing), not autopilot vibe coding.

Primary workflows:

Deep ABAP analysis: where-used, object metadata, repository navigation, object structure, semantic analysis, dependency and impact exploration.
High-level ABAP development: rapid CRUD and iterative updates for RAP and classic ABAP artifacts (classes, interfaces, function groups/modules, programs, DDIC, CDS/view/service artifacts), validated through ADT flows.

Why teams use it:

Full CRUD (not read-only): create, read, update, and delete ABAP artifacts
Works with On-Premise (ECC/S/4HANA), ABAP Cloud (BTP), and Legacy systems (BASIS < 7.50)
JWT/XSUAA, service key (destination-based), and RFC authorization
Multiple transports: stdio, HTTP, SSE
Rich tool surface for ABAP objects, metadata, transports, and search

Authorization & Destinations (Important): A destination is the filename of a service key stored locally. You place service keys in the service-keys directory, and use --mcp=<destination> to select which one to use. This is the primary auth model for on‑prem and BTP systems. See Authentication & Destinations.

You can configure MCP clients either manually (JSON/TOML) or via the configurator CLI (@mcp-abap-adt/configurator, repo: mcp-abap-adt-conf).

Getting Started

Install the server and configure your client using the configurator:

npm install -g @mcp-abap-adt/core
npm install -g @mcp-abap-adt/configurator

# stdio (destination)
mcp-conf --client cline --name abap --mcp TRIAL

# HTTP (streamable HTTP)
mcp-conf --client copilot --name abap --transport http --url http://localhost:3000/mcp/stream/http --mcp trial

Full configurator usage (separate repo): CLIENT_INSTALLERS.md.

Terminology

Destination: a local service key filename. You store service keys in the standard service-keys directory, and pass the filename (without extension) via --mcp=<destination> to select which system to use.

See docs/user-guide/TERMINOLOGY.md for the full list.

Authorization & Destinations

Destination-based auth is the default. Drop service keys into the standard platform folder and use the filename as your destination:

mcp-abap-adt --transport=stdio --mcp=TRIAL

Standard service key paths:

Unix (Linux/macOS): ~/.config/mcp-abap-adt/service-keys/<destination>.json
Windows: %USERPROFILE%\\Documents\\mcp-abap-adt\\service-keys\\<destination>.json

For full details (paths, .env, direct headers), see Authentication & Destinations.

Architecture

The project ships as two packages, because the two usage patterns want different licences. Embedding the tools in a network service should not drag in the obligations of a server that service never runs.

| Package | Licence | What it is | |---|---|---| | @mcp-abap-adt/lib | Apache-2.0 | The ADT tool handlers and the embeddable MCP server. No transport: the host supplies one. | | @mcp-abap-adt/core | AGPL-3.0-only | The standalone server — stdio, SSE and streamable HTTP, the launcher and the mcp-abap-adt CLI. Depends on the library. |

Install @mcp-abap-adt/core to run a server. Install @mcp-abap-adt/lib to embed the tools in your own application.

1. Standalone MCP Server (Default)

Run as a standalone MCP server with stdio, HTTP, or SSE transport:

mcp-abap-adt                           # stdio (default)
mcp-abap-adt --transport=http          # HTTP mode
mcp-abap-adt --transport=sse           # SSE mode

2. Embeddable Server (For Integration)

Embed MCP server into existing applications (e.g., SAP CAP/CDS, Express). This needs @mcp-abap-adt/lib only — not the AGPL server:

npm install @mcp-abap-adt/lib

import {
  EmbeddableMcpServer,
  NoDedupStrategy, // optional: expose both Read<X> and Get<X>
} from '@mcp-abap-adt/lib/embeddable';

const server = new EmbeddableMcpServer({
  connection,              // Your AbapConnection instance
  logger,                  // Optional logger
  exposition: ['readonly', 'high'],  // Handler groups to expose
  // Default hides Read<X> when Get<X> is exposed (ReadVsGetDedupStrategy).
  // Pass NoDedupStrategy to expose both variants instead.
  // readOnlyDedupStrategy: new NoDedupStrategy(),
});
await server.connect(transport);

See Handlers Management → EmbeddableMcpServer dedup strategies for how readonly tools are deduped against high/low/compact, how to opt out with NoDedupStrategy, and how to plug a custom IReadOnlyDedupStrategy for role-based rules.

Quick Start

Install server: See Installation Guide
Configure client (auto): Use mcp-conf from @mcp-abap-adt/configurator (repo: mcp-abap-adt-conf, docs: CLIENT_INSTALLERS.md)
Configure client (manual): See Client Configuration
Use:

Use Cases

Impact analysis / where-used before changes: map object usage and probable blast radius.
Dependency audit: inspect links across classes, interfaces, DDIC, CDS/views, and RAP artifacts.
Migration and cleanup prep: extract repository facts to plan refactoring or cloud-readiness work.
RAP and ABAP iterative development: create/update artifacts quickly with ADT-backed operations.
Automated documentation and RAG ingestion: pull structured facts from ABAP systems for downstream tooling.

Target Users

ABAP developers and ABAP architects
RAP developers
Team leads and tech leads who need fast repository visibility
Teams building RAG/agent workflows for SAP landscapes

Capabilities (High-Level Focus)

Key examples of high-value workflows and tools:

Repository and impact analysis: GetWhereUsed, DescribeByList, GetObjectStructure, GetObjectInfo, SearchObject, GetPackageTree, GetPackageContents
Code and semantic introspection: GetAbapAST, GetAbapSemanticAnalysis, GetIncludesList
RAP development: CreateBehaviorDefinition, UpdateBehaviorDefinition, CreateBehaviorImplementation, UpdateBehaviorImplementation, CreateServiceDefinition, UpdateServiceDefinition, CreateMetadataExtension, UpdateMetadataExtension
CDS/View development: CreateView, UpdateView, GetView, DeleteView
ABAP OO CRUD: CreateClass, UpdateClass, GetClass, DeleteClass, CreateInterface, UpdateInterface, GetInterface, DeleteInterface
Function module/group CRUD: CreateFunctionGroup, UpdateFunctionGroup, GetFunctionGroup, DeleteFunctionGroup, CreateFunctionModule, UpdateFunctionModule, GetFunctionModule, DeleteFunctionModule
Transport and activation support: CreateTransport, GetTransport, ActivateObject

Registries

Published in the official MCP Registry and listed on Glama.ai.

MCP Registry: docs/deployment/MCP_REGISTRY.md
Glama.ai:

Features

🏗️ Domain Management: GetDomain, CreateDomain, UpdateDomain - Create, retrieve, and update ABAP domains
📊 Data Element Management: GetDataElement, CreateDataElement, UpdateDataElement - Create, retrieve, and update ABAP data elements
📦 Table Management: GetTable, CreateTable, GetTableContents - Create and retrieve ABAP database tables with data preview
🏛️ Structure Management: GetStructure, CreateStructure - Create and retrieve ABAP structures
👁️ View Management: GetView, CreateView, UpdateView - Create and manage CDS Views and Classic Views
🎓 Class Management: GetClass, CreateClass, UpdateClass - Create, retrieve, and update ABAP classes
📝 Program Management: GetProgram, CreateProgram, UpdateProgram - Create, retrieve, and update ABAP programs
🔧 Behavior Definition (BDEF) Management: GetBehaviorDefinition, CreateBehaviorDefinition, UpdateBehaviorDefinition - Create and manage ABAP Behavior Definitions with support for Managed, Unmanaged, Abstract, and Projection types
📋 Metadata Extension (DDLX) Management: CreateMetadataExtension, UpdateMetadataExtension - Create and manage ABAP Metadata Extensions
⚡ Activation: ActivateObject - Universal activation for any ABAP object
🚚 Transport Management: CreateTransport, GetTransport - Create and retrieve transport requests
🔍 Enhancement Analysis: GetEnhancements, GetEnhancementImpl, GetEnhancementSpot - Enhancement discovery and analysis
📋 Include Management: GetIncludesList - Recursive include discovery
🔍 System Tools: GetInactiveObjects - Monitor inactive objects waiting for activation
🧪 Runtime Diagnostics: RuntimeCreateProfilerTraceParameters, RuntimeListProfilerTraceFiles, RuntimeGetProfilerTraceData, RuntimeGetDumpById - Profiling and dump analysis with JSON payloads
📡 Runtime Feeds: RuntimeListFeeds, RuntimeListSystemMessages, RuntimeGetGatewayErrorLog - Feed reader (dumps, system messages, gateway errors), SM02 system messages, Gateway error log
🚀 SAP BTP Support: JWT/XSUAA authentication with browser-based token helper
🔑 Destination-Based Authentication: Service key-based authentication with automatic token management (see Client Configuration)
💾 Freestyle SQL: GetSqlQuery - Execute custom SQL queries via ADT Data Preview API

ℹ️ ABAP Cloud limitation: Direct ADT data preview of database tables is blocked by SAP BTP backend policies. The server returns a descriptive error when attempting such operations. On-premise systems continue to support data preview.

Documentation

For Users

Docs Index - Full documentation index
Installation Guide - Installation overview and platform guides
User Guide - End-user docs (auth, config, tools)
Authentication & Destinations - Destination-based auth and service keys
Handlers Management - Enable/disable handler groups
Configurator: @mcp-abap-adt/configurator (repo: mcp-abap-adt-conf) provides the mcp-conf CLI to auto-configure clients
Tools by level

For Administrators

Deployment Docs - MCP Registry, Docker, release notes
Server Configuration - YAML config reference

For Developers

Architecture Documentation - System architecture and design decisions
Development Documentation - Testing guides and development resources
CHANGELOG.md - Version history and changes

Dependencies

This project uses two npm packages:

@mcp-abap-adt/connection – connection/auth/session layer
@mcp-abap-adt/adt-clients – Builder-first ADT clients

These packages are automatically installed via npm install and are published to npm.

Running the Server

Global Installation (Recommended)

After installing globally with npm install -g, you can run from any directory:

# Show help
mcp-abap-adt --help

# Default stdio mode (for MCP clients; requires .env file or --mcp parameter)
mcp-abap-adt

# stdio mode (explicit; default when --transport is omitted)
mcp-abap-adt --transport=stdio

# HTTP mode on custom port (HTTP requires --transport=http)
mcp-abap-adt --transport=http --port=8080

# Use stdio mode with auth-broker (--mcp parameter)
mcp-abap-adt --transport=stdio --mcp=TRIAL

# Use env destination from platform sessions store
mcp-abap-adt --env=trial

# Use explicit .env file path
mcp-abap-adt --env-path=/path/to/my.env

# SSE mode (requires .env file or --mcp parameter)
mcp-abap-adt --transport=sse --port=3001

# SSE mode with auth-broker (--mcp parameter)
mcp-abap-adt --transport=sse --mcp=TRIAL

Development Mode

# Build and run locally
npm run build
npm start

# HTTP mode
npm run start:http

# SSE mode
npm run start:sse

Environment Configuration

Env resolution:

--env-path=<path|file> (or MCP_ENV_PATH) for explicit .env file.
- Absolute path: used as-is.
- Relative path or file name only (e.g. my.env): resolved from current working directory.
--env=<destination> for destination file in standard sessions store:
- Unix: ~/.config/mcp-abap-adt/sessions/<destination>.env
- Windows: %USERPROFILE%\\Documents\\mcp-abap-adt\\sessions\\<destination>.env
Fallback to .env in current working directory.

Example .env file:

SAP_URL=https://your-sap-system.com
SAP_CLIENT=100
SAP_AUTH_TYPE=basic
SAP_USERNAME=your-username
SAP_PASSWORD=your-password

For JWT authentication (SAP BTP):

SAP_URL=https://your-btp-system.com
SAP_CLIENT=100
SAP_AUTH_TYPE=jwt
SAP_JWT_TOKEN=your-jwt-token

For RFC connection:

SAP_URL=https://your-legacy-system.com
SAP_CLIENT=100
SAP_AUTH_TYPE=basic
SAP_USERNAME=your-username
SAP_PASSWORD=your-password
SAP_CONNECTION_TYPE=rfc

See RFC Setup Guide for prerequisites (SAP NW RFC SDK).

For client certificate (mTLS) authentication — on-prem HTTP only:

SAP_URL=https://your-sap-system.com
SAP_AUTH_TYPE=certificate

# PEM format (provide both files):
SAP_CERT_PATH=/path/to/client.crt
SAP_CERT_KEY_PATH=/path/to/client.key

# Or PKCS#12 format (alternative to PEM):
# SAP_CERT_PFX_PATH=/path/to/client.pfx
# SAP_CERT_PASSPHRASE=your-passphrase

For Kerberos (SPNEGO) authentication — on-prem HTTP only:

SAP_URL=https://your-sap-system.com
SAP_AUTH_TYPE=kerberos

# Optional: explicit SPN (default: HTTP@<host>)
# [email protected]
# Optional: service class used to derive the SPN when SAP_KERBEROS_SPN is unset (default: HTTP)
# SAP_KERBEROS_SERVICE=HTTP

Certificate auth notes:

Identifies the client via mTLS — no SAP_USERNAME / SAP_PASSWORD required.
Provide either PEM files (SAP_CERT_PATH + SAP_CERT_KEY_PATH) or a PKCS#12 file (SAP_CERT_PFX_PATH), not both.
On-prem HTTP connections only (SAP_CONNECTION_TYPE=rfc is not supported).

Kerberos auth notes:

Requires a valid Kerberos ticket on the host before starting the server. Obtain one with kinit or a keytab.
The optional kerberos npm package must be installed (needs GSSAPI dev libs on Linux / build tools on Windows): npm i kerberos.
No SAP_USERNAME / SAP_PASSWORD required — identity comes from the TGT.
Both auth types bypass the auth-broker; use .env directly.
NTLM is hard-rejected: if the SAP system offers NTLM instead of Kerberos/SPNEGO, the connection fails with a clear error rather than silently downgrading. Ensure the system accepts Kerberos (SPNEGO) for your user.

⚠️ Help wanted — not yet validated on a live system. Certificate and Kerberos auth pass full unit coverage but have not been tested against a real SAP system. If you have on-prem client-certificate or Kerberos/SPNEGO SSO, please try it and open an issue with results — especially whether Kerberos succeeds with a single-leg Negotiate token or your system needs mutual-auth continuation.

Generate .env from Service Key (JWT):

# Install the connection package globally (one-time setup)
npm install -g @mcp-abap-adt/connection

# Generate .env file from service key JSON
mcp-auth auth -k path/to/service-key.json

This will automatically create/update .env file with JWT tokens and connection details.

.env comments rule: only full-line comments are supported (lines that start with #).
Inline comments are not parsed, so keep comments on separate lines.

Claude recommendation: place the service key in the service-keys directory and use --mcp=<destination> (avoid manual JWT tokens).

Command-Line Options

Authentication:

--auth-broker - Force use of auth-broker (service keys), ignore .env file
--auth-broker-path=<path> - Custom path for auth-broker service keys and sessions
--browser-auth-port=<port> - Override OAuth browser callback port (default: 5000 for HTTP, 4000 for SSE, 4001 for stdio)
--connection-type=<http|rfc> - SAP connection transport: http (default) or rfc
--unsafe - Enable file-based session storage (persists tokens to disk). By default, sessions are stored in-memory (secure, lost on restart)

When --mcp=<destination> is specified, automatic fallback loading of ./.env is skipped.

Examples:

# Use auth-broker with file-based session storage (persists tokens)
mcp-abap-adt --auth-broker --unsafe

# Use auth-broker with in-memory session storage (default, secure)
mcp-abap-adt --auth-broker

# Custom path for service keys and sessions
mcp-abap-adt --auth-broker --auth-broker-path=~/prj/tmp/ --unsafe

See Client Configuration for complete configuration options.

Handler logging switches

AUTH_LOG_LEVEL=error|warn|info|debug — sets base log level for handler logger; DEBUG_AUTH_LOG=true also enables debug.
HANDLER_LOG_SILENT=true — fully disables handler logging.
DEBUG_CONNECTORS=true — verbose connection logging in high-level handlers.
DEBUG_HANDLERS=true — enables verbose logs for selected read-only/system handlers.

Development

Testing

npm test

Test logging switches

TEST_LOG_LEVEL=error|warn|info|debug — controls test logger verbosity (DEBUG_TESTS/DEBUG_ADT_TESTS/DEBUG_CONNECTORS force debug).
TEST_LOG_FILE=/tmp/adt-tests.log — writes test logs to a file (best-effort).
TEST_LOG_SILENT=true — disables test logging pipeline (console output muted).
TEST_LOG_COLOR=true — adds colored/prefixed tags to test log lines.
All console.* in tests are routed through the test logger with a [test] prefix.

Building

npm run build

Developer Tools

# Generate tool documentation
npm run docs:tools

# See tools/README.md for more developer utilities

Contributors

Thank you to all contributors! See CONTRIBUTORS.md for the complete list.

Acknowledgment: This project was originally inspired by mario-andreschak/mcp-abap-adt. We started with the core concept and then evolved it into an independent project with our own architecture and features.

License

Two packages, two licences. Which one applies depends on which you install.

| Package | Licence | | |---|---|---| | @mcp-abap-adt/lib | Apache-2.0 | LICENSE, NOTICE | | @mcp-abap-adt/core | AGPL-3.0-only | server/LICENSE |

Both are published from this repository with one command, in the order the dependency requires:

npm run release:dry        # rehearses both, touches nothing
npm run release:publish    # @mcp-abap-adt/lib, then @mcp-abap-adt/core

release:publish skips a version already on the registry, so re-running after a failure resumes rather than starting over. It aborts on the first failure instead of publishing the server on top of a library that is not there.

Note that npm publish and npm run are different commands. npm publish release asks npm to publish a package named release, which is somebody else's package on the registry.

Both are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

What this means. Running either, on your own data, carries no conditions.

Embedding the library in your own application carries no obligation to open your application: Apache-2.0 asks for the notice and the licence text to travel with it, and nothing more.

Distributing the standalone server, or running a modified version of it as a network service, means passing on the same freedoms under AGPL section 13 — including the source. That is why the two are separate packages: installing the library never puts the server in your dependency tree.

The libraries underneath are LGPL-3.0-only — @mcp-abap-adt/adt-clients, connection, interfaces and logger — and the library links them at runtime. LGPL does not reach your own code, but its terms do travel with those four packages whatever this project is licensed as. Plan for that, not for the notice on this repository.

Other terms are possible. Apache-2.0 is what the library is offered under publicly, not the only way it can be offered. The copyright holder may license the same code separately to a party who needs different terms; that takes nothing away from anyone who received it under Apache-2.0, which is permanent. CONTRIBUTORS.md records what keeps that option open, including the rule that no LGPL code from the packages underneath is ever copied into this tree.

History. Releases through 8.13.0 were MIT and stay MIT; 9.x was GPL-3.0-only. A licence change is not retroactive — anyone may still take an earlier release under the licence it carried. See CONTRIBUTORS.md for the full account of how the relicensing was lawful.