sap-gui-scripting

name	sap-gui-scripting
description	SAP GUI Scripting automation — fallback when ADT cannot handle an operation. Navigates transactions, executes BDC, reads ALV grids, handles popups. Use for SPRO, SU01, SM30, SE16, SNOTE, and any transaction ADT cannot run.
trigger	["SAP GUI","GUI scripting","BDC recording","batch input","SM30","SPRO","SU01","SU53","ALV grid","dynpro navigation","ADT failed try GUI","navigate to transaction","SE16 data browser"]

SAP GUI Scripting — ADT Fallback & Transaction Automation

When ADT MCP returns "not supported", fall back to SAP GUI Scripting. Uses mario-andreschak/mcp-sap-gui (TypeScript) or kts982/mcp-sap-gui (Python).

Prerequisites

• SAP GUI installed on the machine running the MCP (no GUI on server-only hosts)
• SAP GUI Scripting enabled: RZ11 → sapgui/user_scripting → TRUE
• Environment variables set: SAPGUI_HOST, SAPGUI_USER, SAPGUI_PASSWORD, SAPGUI_CLIENT
• SHDB transaction recorder available for capturing field IDs

1. MCP Configuration

{
  "mcp-sap-gui": {
    "type": "stdio",
    "command": "node",
    "args": ["./mcp-sap-gui/dist/index.js"],
    "env": {
      "SAPGUI_HOST": "${SAPGUI_HOST}",
      "SAPGUI_USER": "${SAPGUI_USER}",
      "SAPGUI_PASSWORD": "${SAPGUI_PASSWORD}",
      "SAPGUI_CLIENT": "${SAPGUI_CLIENT}"
    }
  }
}

2. Transaction Navigation Map

• Basis/Dev: SM30 (table maint), SE16 (data browser), SPRO (customizing), SU01 (user admin), PFCG (roles), SU53 (auth check), SNOTE (notes)
• MM: MM01/MM02 (material), ME21N (PO), MIGO (goods receipt), MMBE (stock)
• SD: VA01/VA02 (orders), VL01N (delivery), VF01 (billing)
• FI: FB01 (post doc), FB02 (change doc), FS00 (GL master), F110 (auto payment)
• QM: QA01, QE01, QM01 | PP: CO01, CS01, MD04 | HCM: PA20, PA30, PA40

3. BDC / Batch Input Pattern

# BDC execution helper (illustrative snippet - adapt into your automation)
import win32com.client

def execute_bdc(session, transaction, bdcdata, mode='N'):
    """Execute BDC recording. mode: N=no display, A=all, E=errors only."""
    session.StartTransaction(transaction)
    for step in bdcdata:
        for field_name, field_value in step.get('fields', {}).items():
            try:
                session.findById(field_name).text = field_value
            except Exception as e:
                log_field_skip(field_name, str(e))
        if step.get('okcode'):
            session.findById('wnd[0]').sendVKey(step['okcode'])
    return session

# Example: SM30 table maintenance
BDC_SM30 = [
    {'fields': {'wnd[0]/usr/txtVIEW-AREA': 'ZROUTER_TMPL'},
     'okcode': '0'}  # 0 = Enter
]
session = win32com.client.Dispatch("SapGui.ScriptingCtrl")
connection = session.OpenConnection(SAPGUI_HOST)
execute_bdc(connection.Children(0), 'SM30', BDC_SM30)

4. ALV Grid Reading

# ALV grid reader (illustrative snippet)
def read_alv_grid(session, grid_id='wnd[1]/usr/cntlGRID1/shellcont/shell'):
    """Read ALV grid data. Works for MMBE, MB51, ME2M, VA05, FBL1N, KSB1."""
    grid = session.findById(grid_id)
    headers = [grid.GetColumnHeader(c) for c in range(grid.ColumnCount)]
    rows = []
    for r in range(grid.RowCount):
        rows.append({headers[c]: grid.GetCellValue(r, c)
                     for c in range(grid.ColumnCount)})
    return rows

5. Popup / Modal Handling

# Popup handler (illustrative snippet)
def handle_popup(session, button='OK'):
    """Detect and dismiss modal popup. Returns True if handled."""
    try:
        popup = session.findById('wnd[1]')
        actions = {'OK': 0, 'CANCEL': 12, 'YES': 'btn[0]', 'NO': 'btn[1]'}
        act = actions.get(button, 0)
        if isinstance(act, int):
            popup.sendVKey(act)
        else:
            popup.findById(act).press()
        return True
    except Exception:
        return False

6. ADT-First Routing Strategy

# Routing strategy (illustrative snippet - real engine: scripts/sap_router.py)
GUI_FALLBACK = [
    'SPRO', 'SM30', 'SU01', 'SU53', 'PFCG', 'SNOTE',
    'MM01', 'MM02', 'ME21N', 'MIGO', 'MMBE',
    'VA01', 'VA02', 'VL01N', 'VF01',
    'FB01', 'FB02', 'FS00', 'F110',
    'QA01', 'CO01', 'KO01', 'PA20', 'PA30'
]

def route(action, try_adt=True):
    """Route: ADT first → GUI fallback → ZROUTER RFC."""
    if try_adt and adt_supports(action):
        return {"dest": "ADT", "fallback": "sap-gui-scripting"}
    if action.upper() in GUI_FALLBACK:
        return {"dest": "SAP GUI", "mcp": "mcp-sap-gui", "tcode": action}
    return {"dest": "ZROUTER RFC"}

Pitfalls

• SAP GUI Scripting not enabled:
  • Cause: sapgui/user_scripting is FALSE in RZ11.
  • Solution: Set to TRUE via RZ11 and restart SAP GUI.
• Field IDs change across SAP versions:
  • Cause: Screen modifications in support packages shift field positions.
  • Solution: Use SHDB transaction recorder to capture correct field IDs before scripting.
• Popups break BDC navigation silently:
  • Cause: Modal window appears between steps; script tries next field on wrong screen.
  • Solution: Call handle_popup() after every sendVKey in BDC loops.
• Password hardcoded in script:
  • Cause: Developer embeds credentials for convenience.
  • Solution: Always use environment variables or secure vault — never hardcode.
• BDC mode A floods with screens in production:
  • Cause: Mode 'A' shows every screen — useful for debug, terrible for batch.
  • Solution: Use mode 'N' (no display) for production, 'E' for error-only visibility.
• No SAP GUI on server host:
  • Cause: MCP runs on Linux server without SAP GUI installed.
  • Solution: Run GUI MCP on a Windows machine with SAP GUI, or use RFC/BAPI instead.

Verification

# Primary: cross-platform Python check (recommended — works on Windows and Linux)
python scripts/check_gui_scripting.py --host "$SAPGUI_HOST"
# or: npm run gui:check

# Supplementary: bash-only MCP config check
grep -q '"mcp-sap-gui"' .mcp.json && echo "OK: MCP config found" || echo "FAIL: no config"