Setup

Setup

A Note on Updates

The Dashboard Web UI now includes an automated Upgrade Assistant that checks database schema version state, lists applied/pending incremental schema upgrades, and offers a fresh database reinstallation path (which recreates the database schemas while preserving connection credentials in .sap_credentials.json).

0. Prerequisites

• Node.js (https://nodejs.org)
• git
• AI IDE with MCP support
• SAP system to connect to
• Windows 10+ x64 / - linux/amd64 (expected to work on modern glibc-based distributions as Ubuntu 22.04+, Debian 12+, RHEL...)

1. Registering the Bridge

Note: Every AI IDE slightly differs in how it handles MCP server and skill registration. Read the documentation of your AI IDE or ask your AI agent to help you with the registration process.

The sap-bridge operates as an orchestrator-agnostic MCP server, fully supporting modern AI IDEs and clients.

It uses standard process stdio pipelines to communicate with your AI securely and silently in the background.

To register the bridge into your orchestrator's MCP config file, assign the absolute path to sap-bridge (found in bin folder) or follow your AI IDE's documentation.

Windows

{
  "mcpServers": {
    "sap-bridge": {
      "command": "C:\\absolute\\path\\to\\sap-bridge.exe",
      "args": [],
      "env": {}
    }
  }
}

Linux

{
  "mcpServers": {
    "sap-bridge": {
      "command": "/absolute/path/to/sap-bridge",
      "args": [],
      "env": {}
    }
  }
}

macOS

{
  "mcpServers": {
    "sap-bridge": {
      "command": "/absolute/path/to/sap-bridge-darwin-[arm64|amd64]",
      "args": [],
      "env": {}
    }
  }
}

2. Setting Up Workspace

Copy the sap-dev skill folder into your workspace folder (or into a global skill storage). In the workspace, it's typically .agents/skills/. The global skill storage is IDE dependent.

Another way to use the skill documents across multiple folders is a symbolic link.

• on Windows (in Admin mode):

New-Item -ItemType SymbolicLink -Path "<your_workspace>\.agents\skills\sap-dev" -Value "<reference_location_of_the_skill>\sap-dev"

• on Linux and Mac:

ln -s "<reference_location_of_the_skill>\sap-dev" "<your_workspace>\.agents\skills\sap-dev"

3. Setting Up Credentials

1. Ask your AI Agent for the current URL of the dashboard (it will run sap_bridge_status MCP tool and return http://127.0.0.1:<some_local_port>).
2. Open the provided URL in your standard Web Browser.
3. If this is your first time securely booting the Bridge, the Dashboard will check the prerequisites and automatically prompt you to establish your Master Password. This will generate .sap_credentials.json at the root of your workspace folder. The credentials, master password hash, and vault state are completely isolated per workspace context.
4. Once your Web UI encryption is initialized, you can add SAP system connections.

• You can toggle system visibility (to the agent) and writability on the fly.
• Additional controls will be shown depending on the chosen connection type and whether the password should be injected at runtime.

4. Setting Up RPC Proxy (Optional)

Some tools (like sap_read_screen) cannot reuse an existing ADT endpoint and rely on ABAP logic. To make them work, you must deploy the ABAP RPC proxy components to your SAP system and configure an ICF node.

1. Deploy Proxy Components:
   • Open the SAP-Bridge Web Dashboard and click the Upgrade tab in the sidebar.
   • Select your target SAP system from the dropdown and click Check Status.
   • Check the boxes for the core RPC interface/classes:
     • zcl_sap_dev_object_hdlr.clas.abap (Unified Abstract Object Handler Base Class)
     • zcl_sap_dev_rpc.clas.abap (and its .locals_def/.locals_imp includes)
     • zcl_sap_dev_rpc_ext.clas.abap (and its .locals_def/.locals_imp includes)
   • Under Deployment Settings, specify the target package (defaults to $TMP). If using a transportable package, enter a valid Transport Request (Task) number.
   • Click Deploy & Activate Selected. The assistant will automatically create, lock, upload, and activate the objects on the backend in the correct dependency order.
2. Create ICF Node:
   • Open SAP GUI and run transaction SICF.
   • Navigate to /default_host/sap/bc.
   • Create a new sub-element named zsapdevrpc (or any custom path).
   • In the Handler List tab, enter the extension class ZCL_SAP_DEV_RPC_EXT (which inherits from ZCL_SAP_DEV_RPC and allows subclassing custom translation handlers).
   • Save and Activate the ICF node.
3. Enable in Dashboard: Open the SAP-Bridge Web Dashboard, edit your connection, click the Agent Settings icon (file with a gear), and check the RPC Proxy Enabled checkbox. If you used a custom ICF path, specify it in the Agent RPC Path field (defaults to /sap/bc/zsapdevrpc).

5. Setting Up WebGUI Deep Linking (Optional)

To enable deep-linking to specific line numbers and subroutines directly from the ATC Findings table in the Web UI to the SAP WebGUI, you must deploy a custom helper program and transaction code:

1. Deploy Navigation Program: In the Web Dashboard's Upgrade tab, check the box for z_navigate_to_line.prog.abap, configure target package details, and click Deploy & Activate Selected (or manually upload the code from references/z_navigate_to_line.prog.abap in your IDE).
2. Create Transaction Code: Create a transaction code named exactly Z_SAP_DEV_NAV in SE93.
   • Choose Program and selection screen (report transaction).
   • Enter your deployed program name (e.g. Z_NAVIGATE_TO_LINE) and selection screen 1000.
   • Under GUI Support, check SAP GUI for HTML (WebGUI) and save.
3. Automatic Detection: The Web UI dynamically checks if transaction Z_SAP_DEV_NAV is registered on the SAP backend. If available, the screen-share deep-linking buttons will automatically appear next to your ATC findings in the Actions column. No manual dashboard configuration is required.