Skip to main content
Glama
abap-adt-mcp-gateway
by lusmjs
README.md
# abap-adt-mcp-gateway

[![CI](https://github.com/rogerix4/abap-adt-mcp-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/rogerix4/abap-adt-mcp-gateway/actions/workflows/ci.yml)
[![node](https://img.shields.io/badge/node-%3E%3D20.11-informational)](https://nodejs.org)
[![mcp](https://img.shields.io/badge/MCP-stdio-blue)](https://modelcontextprotocol.io)
[![tools](https://img.shields.io/badge/contract-336%20tools-informational)](#the-contract)
[![license](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

An MCP server for SAP ABAP that speaks ADT. One process serves several SAP systems at once,
advertises **three** tools instead of 336, and decides what a call may do from the mode of the
system it targets: `dev` writes, `qas` reads and tests, `prd` reads.

It talks to the documented ADT endpoints over HTTPS. No screen scraping, no GUI automation, and
nothing on the ABAP side is required unless you want the few surfaces ADT does not expose.

It mounts nothing on its own. If you want an object visible in the editor's own ABAP tree, turn
`observe` on: `abap-adt-mcp observe` prints the destination folder and the virtual path of each
object, and `abap-adt-mcp observe --mount` writes every configured destination into the editor's
workspace file. The tree itself is served by SAP's extension **ABAP Development**
(`sapse.adt-vscode`); the window reads that file on reload, and the logon inside each tree is
manual. A write asks for a tab only when the extension serves `abap:` and its log says the session
is alive, and otherwise the answer carries one `observe_note` line saying why — see
[docs/USAGE.md](./docs/USAGE.md#seeing-objects-in-the-adt-tree).

## Table of Contents

- [Why this exists](#why-this-exists)
- [Quick start](#quick-start)
- [Configure systems](#configure-systems)
- [How a call works](#how-a-call-works)
- [What each mode allows](#what-each-mode-allows)
- [The contract](#the-contract)
- [Tested against](#tested-against)
- [Requirements](#requirements)
- [What it does not do](#what-it-does-not-do)
- [Documentation](#documentation)
- [Project status](#project-status)
- [Contributing](#contributing)
- [License](#license)

## Why this exists

Three problems, one design decision each.

**A model cannot hold 336 tool schemas.** A client hands the model a bounded list — several stop at
128 — so a 336-entry `tools/list` ends with a model that believes the tools that did not fit do not
exist. This server advertises three tools and keeps the other 336 reachable by name, with their
schemas on the server, fetched only when a call needs one.

**A developer usually has more than one system.** Development, quality and production differ in one
way that matters: whether a write is allowed. Each configured system keeps its own ADT session —
own cookies, CSRF token, pinned client — alive for the life of the process, and its `mode` decides
what a tool may do there. A refusal says `MODE_FORBIDDEN` and names the mode that would have
accepted it. There is no fourth spelling of `mode`, and no setting that widens one.

**"It worked" is a claim, not a result.** ADT answers 2xx for writes that were stored but never
activated, for checks that never ran, and for objects that do not exist. Every write tool here
reads the active version back and compares it with what it sent; a check that returns no verdict is
reported as an error, not as a pass. The known [traps](docs/USAGE.md#known-traps) are listed per
endpoint.

## Quick start

Four steps: get the code, write one configuration file, register it with your client, make a call.
Nothing here needs SAP access until the last step.

### Get the code and build it

```bash
git clone https://github.com/rogerix4/abap-adt-mcp-gateway.git
cd abap-adt-mcp-gateway
npm ci
npm run build
node dist/bin.js --coverage
```

The last line answers `336/336 tools implemented`. It needs no configuration and contacts no system
— it is the check that the build is intact.

**There is no npm package yet, and `dist/` is not committed**, so `npx github:…` cannot work: the
build has to happen once on your machine. `node --version` must be 20.11 or newer (see
[Requirements](#requirements)).

### Point it at your systems

Create `adt-mcp.config.jsonc` in the directory you will start the server from (or pass
`--config <path>`). The smallest file that answers a call is
[`examples/adt-mcp.config.minimal.jsonc`](examples/adt-mcp.config.minimal.jsonc):

```jsonc
{
  "$schema": "./adt-mcp.schema.json",
  "systems": [
    {
      "id": "dev",
      "mode": "dev",
      "sid": "DEV",
      "endpoint": { "url": "https://sap.example.com:44300", "client": "100" },
      "auth": { "type": "basic", "username": "env:ADT_USER", "password": "env:ADT_PASSWORD" }
    }
  ]
}
```

Credentials are **references** (`env:`, `keychain:`, `file:`), never literals — the client's own
configuration never holds a password. Every key, every default and every layer is in
[docs/CONFIGURATION.md](docs/CONFIGURATION.md); a file that fails validation says which layer and
which key, and the server still starts so you can see that answer.

### Register it with your client

The server speaks MCP over stdio. What you write depends on the client, and only the VS Code form
was measured here — the six shapes (VS Code, Claude Desktop, Claude Code, Cursor, Codex CLI, Gemini
CLI) are in [examples/](examples/README.md), each as a file you can copy:

```json
{
  "servers": {
    "abap-adt-mcp-gateway": {
      "command": "node",
      "args": ["/absolute/path/to/abap-adt-mcp-gateway/dist/bin.js"]
    }
  }
}
```

Then restart the client — the server is its child process, so a new build or a new configuration is
only picked up when it is started again. The client shows three tools:

```text
GatewayListSystems   which systems exist, their mode, how much of the contract each allows
GatewayListTools     find a tool by group, name pattern, verb or free text
GatewayCallTool      call any tool of the contract by name
```

### Make the first call

```text
GatewayListSystems {}
```

It answers one line per configured system with its `mode` and how many of the 336 tools that mode
allows, and it contacts nothing. From there the shape is always the same: find a name, ask for its
schema, call it.

```text
GatewayListTools  { "group": "ddic" }
GatewayListTools  { "tool": "GetTable", "detail": "schema" }
GatewayCallTool   { "system": "dev", "tool": "GetTable", "arguments": { "table_name": "T000" } }
```

Diagnostics go to **stderr** (stdout carries the protocol and nothing else), so a client that shows
server logs shows them there. `node tools/scripts/mcp-status.mjs` prints which servers are running
and marks one whose process predates `dist/`. When a call refuses, read its `code` and `nextAction`
before retrying — [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) is organised by that order.

## Configure systems

`adt-mcp.config.jsonc` in the working directory (or next to the package, or at `--config <path>`).
Credentials are references, never literals.

```jsonc
{
  "$schema": "./adt-mcp.schema.json",

  // The process itself.
  "server": {
    "name": "abap-adt-mcp-gateway",
    "logLevel": "info"          // error | warn | info | debug
  },

  // ADT-client integration: `abap-adt-mcp observe`, `GetObjectUri`, and opening the object in
  // the ADT tree after a successful Create / Update. Off by default — with it on, a write also
  // starts the editor CLI.
  "observe": {
    "enabled": false,
    "openAfterWrite": true,     // request the tab after a write, never after Delete
    "codeCli": "code"           // editor CLI to start
  },

  // Used when a call omits `system`; must be one of the ids below.
  "defaultSystem": "dev",

  // Applies to every system.
  "toolPolicy": {
    "timeoutMs": 180000,        // per-request ADT timeout, in milliseconds
    "exclude": []               // names / groups / tags / globs refused everywhere; empty by default
  },

  "systems": [
    {
      "id": "dev",              // also the `system` argument; lowercase, . _ - allowed
      "label": "DEV · client 100",
      "sid": "DEV",             // sy-sysid, three characters — the ADT destination id is built from it
      "mode": "dev",            // dev | qas | prd — the only thing that decides whether a write may happen
      "endpoint": {
        "url": "https://sap.example.com:44300",
        "client": "100",        // three-digit client, "100" or 100
        "language": "EN",       // logon language, default EN
        "systemType": "onprem"  // onprem | cloud, default onprem
      },
      "auth": {
        // "type": "basic" — the only value there is; omit it
        "username": "env:ADT_USER",
        "password": "keychain:abap-adt-mcp-gateway/dev"
      },
      "rfcBackend": "soap",     // soap | odata, default soap — used by the ABAP bridge modules
      "env": {}                 // extra variables handed to the RFC bridge; usually empty
    },
    {
      "id": "prd",
      "label": "PRD · client 100",
      "sid": "PRD",
      "mode": "prd",
      // Narrowing only: naming a write tool here does not make it allowed on a prd system.
      "include": ["Get*", "ddic"],
      "endpoint": { "url": "https://sap.example.com:44300", "client": "100" },
      "auth": {
        "username": "env:ADT_USER_PRD",
        "password": "keychain:abap-adt-mcp-gateway/prd"
      }
    }
  ]
}
```

Only `systems[].id` is required. Everything else is either a default (shown above: `logLevel`
`info`, `observe` off, timeout 180 s, language `EN`, `systemType` `onprem`, `rfcBackend` `soap`) or
something you have to supply to connect at all (`endpoint.url`, `auth.username`, `auth.password`).
A system without `mode` counts as `prd`.

`env:` needs the variable set; `keychain:` needs an entry you create once. The three commands, one
per platform:

```bash
# Windows
cmdkey /add:abap-adt-mcp-gateway/dev /user:ADT_USER /pass

# macOS
security add-generic-password -s abap-adt-mcp-gateway -a dev -w

# Linux (libsecret)
secret-tool store --label="abap-adt-mcp-gateway dev" service abap-adt-mcp-gateway account dev
```

Start with `env:` if you only want the first call to work; move to `keychain:` before the
credential ends up in your shell history. The full key list is in
[docs/CONFIGURATION.md](docs/CONFIGURATION.md); unknown keys are an error, not a no-op.

## How a call works

```text
client ──stdio──▶ GatewayListTools { group: "ddic" }        → names, one line each
               ──▶ GatewayListTools { tool: "CreateTable", detail: "schema" }  → its JSON Schema
               ──▶ GatewayCallTool { tool: "CreateTable", arguments: {…}, system: "dev" }
```

The `tool` argument of `GatewayCallTool` carries an enum of every name the configured systems
allow, so a model sees the whole contract without receiving 336 schemas. If the arguments do not
match, the answer contains the schema instead of only an error.

What a name may *do* is decided per call from the target system's mode, and refused with
`MODE_FORBIDDEN`, naming the mode that would have accepted it. A name the contract does not have
answers `UNKNOWN_TOOL` — the two mistakes stay distinguishable.

## What each mode allows

| mode | actions | typical use |
|---|---|---|
| `dev` | read, data, diag, test, check, write, activate, lock, transport | development client, writable |
| `qas` | read, data, diag, test, check | quality client, nothing is written |
| `prd` | read, data, diag | production, read only |

How much of the contract each mode reaches:

| mode | tools allowed | of 336 |
|---|---|---|
| `dev` | 336 | everything |
| `qas` | 146 | reads, checks, data, diagnostics, unit tests |
| `prd` | 108 | reads, data, diagnostics |

A system without `mode` is treated as `prd`. Exactly these three values exist — there is no fourth
spelling, because this setting decides whether a production system can be written to. `include`
narrows the set for one system (group, tag, tool name or glob); `exclude` removes last and wins.
Neither can widen a mode.

Per-group counts, and what each mode allows in one group:

```bash
node tools/scripts/tool-presets.mjs
```

## The contract

336 tools in twelve groups. A group is the one home of a tool, in the listing and in the generated
reference, so a name is never described two ways.

| Group | Tools | What it reaches |
|---|---|---|
| `object-core` | 97 | programs, classes, interfaces, packages, includes, where-used, search, object structure |
| `cds-rap` | 61 | CDS views, metadata extensions, behavior definitions and implementations, service definitions and bindings |
| `ddic` | 54 | domains, data elements, tables, structures, with their check and activation |
| `ui` | 31 | screens, GUI statuses, text pools |
| `functions` | 25 | function groups and function modules |
| `testing` | 25 | ABAP Unit runs and test includes, CDS unit tests |
| `runtime-diag` | 17 | dumps, feeds, system messages, profiler traces |
| `analysis` | 11 | type information, enhancement spots and implementations, usage snippets, batch-job and transaction usage |
| `transport` | 5 | requests and tasks |
| `forms` | 5 | SmartForms: content, layout, render to PDF |
| `data` | 2 | table contents and ad-hoc SQL |
| `session-admin` | 2 | session state and profile reload |

Every tool, its group and its full argument schema are in [docs/TOOLS.md](docs/TOOLS.md), generated
from `tools/catalog.json`; `npm run verify` fails when the two drift apart.

`Low` in a name means "the caller owns the lock and the session": one tool call, one ADT request.
It is not simply the twin of the tool next to it — 89 of the 134 `*Low` tools have no high-level
sibling, and the ones that do differ in their arguments, not only in their level.

## Tested against

The table below lists what was exercised and where.

| What | Where it was verified |
|---|---|
| ADT resources, activation, locks, transports, CDS and RAP | an S/4HANA development client, logon language ZH |
| The ABAP bridge modules (`abap/`) | an ECC system on BASIS 7.54 — the sources are written for that release and encode JSON through `ZCL_JSON`, because `/ui2/cl_json` is missing there |
| Every tool in the contract | a live sweep on a development client: 336 of 336 called, in `$TMP`, cleaned up afterwards — see [docs/LIVE-TESTING.md](docs/LIVE-TESTING.md) |
| The offline suite | 467 tests over 39 files, no network: a scripted HTTP layer and `InMemoryTransport` |

SAP releases differ in small, load-bearing ways: which media type an endpoint accepts, whether a
syntax check reads the payload you hand it, whether a resource exists at all. Where a difference was
found, the code decides at runtime and [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) records
what SAP answered. If your release behaves differently, that is a bug report worth sending: include
the `status`, the root element and the SAP text.

## Requirements

- Node 20.11 or newer. `npm ci && npm run build` is the whole toolchain.
- HTTPS access to `/sap/bc/adt` on the target systems, and a user with `S_DEVELOP`.
- Optional: the ABAP modules in [abap/README.md](abap/README.md) for screens, GUI statuses, text
  elements and SmartForms — the four surfaces ADT does not expose.
- Optional: `@napi-rs/keyring` (an optional dependency) for `keychain:` credentials.

## What it does not do

- No HTTP transport. stdio only.
- No GUI, screen, or transaction automation: it drives documented ADT resources, plus the seven
  bridge modules in `abap/` for the four surfaces that have no ADT resource.
- Writes only on `mode: "dev"`. Nothing in this project will make a `qas` or `prd` system accept a
  write, and a refusal is a refusal, not a retry hint.
- No BTP ABAP environment support for the RFC-based parts: there is no `/sap/bc/soap/rfc` there.
- No logon on your behalf. The `abap:` tree's session belongs to SAP's extension; the gateway reads
  that extension's own log to know whether a tab is worth asking for, and says so in `observe_note`
  when it is not. See [troubleshooting](./docs/TROUBLESHOOTING.md#the-object-did-not-open-in-the-adt-tree).
- No source cache, no version history, no interactive debugger — see
  [what has no channel](docs/USAGE.md#what-has-no-channel).

## Documentation

Start with the map: [docs/README.md](docs/README.md). Behind it:

| Question | File |
|---|---|
| The fastest path from a clone to a first call | [examples/](examples/README.md) |
| How to drive a tool correctly: payloads, activation, locks, the traps | [docs/USAGE.md](docs/USAGE.md) |
| Every configuration key, and where the file is looked for | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) |
| Sessions, locks, concurrency, the write boundary, why the shape is this shape | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| Symptom to cause to fix | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) |
| Every tool, its group and its arguments (generated) | [docs/TOOLS.md](docs/TOOLS.md) |
| How the live sweep works, and what the last one found | [docs/LIVE-TESTING.md](docs/LIVE-TESTING.md) |
| The ABAP bridge modules | [abap/README.md](abap/README.md) |
| Working **on** this repository, with or without an AI agent | [AGENTS.md](AGENTS.md) |
| Changes per release | [CHANGELOG.md](CHANGELOG.md) |
| Reporting a vulnerability | [SECURITY.md](SECURITY.md) |
| Sending a change | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Where to ask a question | [SUPPORT.md](SUPPORT.md) |
| How we treat each other | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |

`npm run verify` runs the whole gate: catalog consistency, the private-data scan, types for `src`
**and** `tests`, the generated schema and tool reference, documentation style and links, the
coverage count and the test suite. It runs on every push in
[`.github/workflows/ci.yml`](.github/workflows/ci.yml), on Node 20 and 22, Linux and Windows.

## Project status

1.0.0 — first public release. The tool contract is frozen: a capability that is missing becomes a
new tool in a minor release, and a released name never changes meaning or shape.

Known gaps are stated, not half-implemented. `UpdateUnitTest` and `DeleteUnitTest` answer
`NOT_IMPLEMENTED` because ADT has no verb for them — measured: `PUT` and `DELETE` on
`/abapunit/runs/<id>` answer `405`, and `GET` answers `406`. The five `Validate*` verbs that check a
name that already exists answer "already exists", which is the correct verdict and not a defect.

Deliberately not planned: GUI automation, a second transport, a plugin system, and any setting that
could widen a mode.

## Contributing

Small, focused pull requests are easier to review than large ones, and a bug report carrying the SAP
text and the `status` is worth more than a fix that guesses. Rules to know before you start:
[CONTRIBUTING.md](CONTRIBUTING.md) — and for anything beyond a typo, [AGENTS.md](AGENTS.md), the
same file an AI agent working here reads.

## License

[Apache License 2.0](LICENSE): use it, fork it, change it, ship it, sell it. The licence asks for
two things and nothing else — keep the copyright and licence notices, and read the patent and
warranty clauses before you rely on it. Third-party notices are reproduced in [NOTICE](NOTICE).

Apache-2.0 is OSI-approved, so GitHub labels this repository "Apache License 2.0"; `LICENSE` is the
whole text and there is nothing to accept before you read the source.

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct stage of the workflow: discover systems, discover tools, invoke a tool. There is no plausible way to confuse listing systems with searching the contract or calling a tool, and the descriptions reinforce the boundary (find it here, then call it with GatewayCallTool).

Naming Consistency5/5

All three follow the same predictable Gateway+Verb+Noun pattern (GatewayListSystems, GatewayListTools, GatewayCallTool) with identical PascalCase and prefixing. The shared 'Gateway' prefix also clearly signals these are meta-tools rather than contract tools.

Tool Count5/5

A gateway exposing a 336-tool contract should have a minimal meta-surface, and three tools covers discovery, invocation and context. Each tool earns its place; adding more would bloat the advertised surface and defeat the gateway's purpose.

Completeness4/5

The lifecycle is closed: list systems, search the contract by group/name/verb/text, then call with schema-on-mismatch error recovery. Minor gaps exist — there is no way to pre-check whether a tool is permitted on a given system without attempting the call, and no dedicated schema/introspection tool separate from the search detail flag.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues