ADT MCP (Python)

Multi-system MCP server for reading and writing ABAP source via SAP ADT, with a local web admin to configure systems. One process serves both the MCP endpoint (/mcp) and the web admin (/).

Install (Windows)

git clone https://github.com/NhatPD-VNEXT/ADT-MCP adt-mcp
cd adt-mcp
install.bat        REM creates .venv, installs everything, verifies the import
run.bat            REM starts the server and opens the web admin

Only prerequisite: Python 3.10+ on the machine. install.bat finds it via py -3 or python and skips the Microsoft Store stub; it creates a project .venv so nothing global is touched. Flags:

Flag	Effect
--no-venv	Install into the Python already on PATH instead of .venv
--no-browser	Skip Playwright (only fine if every system uses basic auth)

Playwright is installed by default because cookie systems log in through a browser. It drives the machine's own Chrome/Edge, so there is no browser download; if neither is installed, run .venv\Scripts\python -m playwright install chromium.

Configure the new machine

systems.json and cookies/ are gitignored — they hold credentials and are never in the repo. After install.bat, pick one:

• Add the system in the web admin (run.bat → http://127.0.0.1:8765) and log in once with the browser flow. Nothing secret has to be copied.
• Copy systems.json + cookies\ by hand from a working machine (USB, password manager, internal share — not email/chat). Fix the absolute cookie_file paths afterwards, or re-login from the admin.

Until that is done the server runs and the admin opens, but list_systems reports no systems.

Install (manual / non-Windows)

cd adt-mcp
python -m pip install -e ".[refresh]"   # -e matters: config, web/ and cookies/
                                        # are read from the checkout.
                                        # [refresh] = Playwright cookie login

Run

python -m adt_mcp        # or: adt-mcp
# → http://127.0.0.1:8765  (MCP at /mcp, admin at /)

Environment variables (all optional):

Variable	Default	Purpose
ADT_MCP_PORT	8765	Port for MCP + web admin (run.bat follows it)
ADT_MCP_HOME	the checkout	Folder holding systems.json, web/, cookies/
ADT_MCP_SYSTEMS	<home>/systems.json	Explicit path to the systems config
ADT_MCP_TOOLS	full	core exposes only the essential tools
ADT_MCP_BROWSER	chrome	Browser channel for cookie login (msedge/chromium)
ADT_MCP_CDP	http://127.0.0.1:9222	Chrome DevTools endpoint for mode: "cdp"

Set ADT_MCP_HOME when the package is installed non-editable or run as a service from another working directory.

Open http://127.0.0.1:8765 to add SAP systems (URL, client, language, auth). Config is stored in systems.json (gitignored). See systems.example.json. Cookie systems can be (re)authenticated from the web admin via a browser login.

Connect Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "sap-adt": { "type": "http", "url": "http://127.0.0.1:8765/mcp" }
  }
}

Tools

Read / navigate:

• list_systems, list_package, search_objects
• get_source, get_source_by_uri, get_class_method_source, get_class_include, get_object_structure, get_package_source
• grep_package, find_references (where-used), cds_dependencies
• get_context (object + compressed dependencies: CDS/BDEF/CLAS)
• get_revisions, get_revision_source, compare_source
• syntax_check, run_unit_tests (ABAP Unit), data_preview (CDS/SQL data)
• trace_start, trace_list, trace_analyze (ABAP profiler: CPU hotspots + DB accesses)
• list_dumps, get_dump (ST22 runtime dumps: liệt kê + đọc chi tiết để phân tích lỗi)

Write (gated by safety, see below):

• update_source, update_class_include, activate
• create_object (CLAS / INTF / DDLS / DDLX / BDEF / SRVD / SRVB / TABL)
• clone_package (clone toàn bộ object của một package sang package đích, thêm suffix _VN + sửa tham chiếu chéo trong source; dry-run mặc định)

Debug (gated by allow_debug, see below):

• debug_set_breakpoint, debug_delete_breakpoint, debug_clear_breakpoints
• debug_listen, debug_poll, debug_stop_listener
• debug_attach, debug_detach
• debug_stack, debug_variables, debug_step
• run_class (IF_OO_ADT_CLASSRUN — Eclipse's F9)

Cookie maintenance: refresh_cookies_for.

Debugging

The tenant must expose the ADT debugger; check with

GET /sap/bc/adt/compatibility/graph   → COM.SAP.ADT.DEBUGGER :: userRequestDebugging

Enable it per system in systems.json — it is off by default, separately from allow_write, because run_class executes arbitrary ABAP:

"allow_debug": true,
"debug_timeout": 600,
"debug_listen_seconds": 120

The flow, in order:

debug_set_breakpoint  → statement="…" lets the server find the executable line
debug_listen          → returns at once; the listener runs in the background
run_class             → run the code WHILE the listener waits
debug_poll            → state: listening → caught
debug_attach
debug_stack / debug_variables / debug_step
debug_detach          → releases the debuggee and returns the run's output

debug_variables needs explicit names — read the source first. There is no working "list what is in scope" call on this platform: getChildVariables answers with ME alone whatever parent it is asked for.

Two things follow from how SAP works, not from choices made here:

• Run the code while the listener is waiting. A debuggee is only trapped by a listener that was already registered. debug_listen therefore returns immediately instead of blocking.
• A breakpoint freezes the HTTP request that started the code. run_class runs in the background for that reason, and the console output only arrives at debug_detach (or a later debug_poll).

Debugging a Fiori app (RAP action, determination, validation)

Nothing here runs the code — you do, by clicking in the browser. An external breakpoint is keyed on the ABAP user, so it traps any session of that user, including the OData request the Fiori UI sends.

debug_set_breakpoint  VNEXT CLAS ZBP_I_FLIGHT_013 \
                      include="implementations" statement="READ ENTITIES"
debug_listen          VNEXT seconds=600      ← wide enough to switch to the browser
      … now trigger the action in the Fiori app …
debug_poll            VNEXT                  → state: caught
debug_attach / debug_stack / debug_variables / debug_step
debug_detach          VNEXT                  → the OData request completes

run_class plays no part in this flow.

Two things decide whether it works:

• include="implementations". RAP handler code (lhc_… classes, where actions, determinations and validations live) is in the class's Local Types include. A behavior pool's /source/main is an empty shell — a breakpoint there never fires. The returned id shows where it really landed (…INCLUDE=…CCIMP.LINE_NR=131).
• Same ABAP user. The Fiori session must run as the user in /sap/bc/adt/core/http/systeminformation. A different login is a different user and is never trapped.

While you sit at the breakpoint the OData request is held open, so the Fiori UI spins and can hit its own gateway timeout — detach promptly. Leaving a breakpoint armed with no listener is not dangerous, though: measured on the tenant, the code simply runs straight through.

Cost on cloud

The ABAP session is the SAP_SESSIONID cookie, so the debugger's isolated channels each need their own login. The first debug_listen and the first run_class on a system therefore take ~20–25s while a headless login runs; afterwards the sessions are reused. Channel cookies land in cookies/<system>.debug.txt / .exec.txt and are gitignored like the rest.

Breakpoints set here are external breakpoints keyed on the ABAP user, so leaving one behind would pop the debugger open on a real session later. The server deletes everything it set when it shuts down; debug_clear_breakpoints does it on demand. The ideId is adt-mcp, distinct from Eclipse's, so your IDE breakpoints are never touched.

Write safety

Writes are off by default. Per system in systems.json:

• allow_write: true — required to enable any create/update.
• write_packages: ["Z*", "$TMP"] — target package must match (default).

Delete is intentionally not supported.

Token economy

Tool schemas are sent to the model on every turn. Set ADT_MCP_TOOLS=core to expose only the essential ~16 tools (smaller schema); default full exposes all 29. Descriptions are kept terse.

ADT_MCP_TOOLS=core python -m adt_mcp

Security

• systems.json, cookies/, *-cookies.txt hold session secrets and are gitignored — never commit them.
• The server binds 127.0.0.1 only.
• Stored passwords are plaintext. A username/password is only kept to enable headless cookie refresh (refresh_cookies_for). For real systems prefer the cookie flows that store no password:
  • mode: "browser" — log in once in a visible browser; only session cookies are saved (the persistent profile keeps SSO so re-login is rare).
  • mode: "cdp" — attach to your already-authenticated Chrome. If you must keep a password, store it in an OS keyring / secrets manager and inject it into systems.json at deploy time rather than committing it.