# Eclipse mode

In the Eclipse mode the MCP server runs inside Eclipse ADT. The server uses the ADT session of each connected ABAP
project. The server asks for no password and stores no password.

## 1. Prerequisites

- Eclipse 2024-03 or later with SAP ADT is installed.
- Eclipse runs on Java 21 or later. ADT 3.63.0 needs Java 21.
- The Eclipse workspace has an ABAP project. You can log on to the project.
- An MCP client is installed, for example Claude Code or Codex.

## 2. Install from the update site

<!-- external-only:start -->
The update site is available at two places. Both places carry the same version.
<!-- external-only:end -->
The feature "EPOD ADT MCP Server"
installs two bundles: `com.epod.adt.mcp.core` and `com.epod.adt.mcp.plugin`.

<!-- external-only:start -->
### External update site (no sign-in)

1. In Eclipse, select **Help > Install New Software...**.
2. Click **Add...**.
3. In **Location**, enter `https://git.epod.dev/erhan/epod-adt-mcp-updatesite/raw/branch/main/`.
4. Select **EPOD ADT MCP Server** in the list.
5. Click **Next**.
6. Accept the license and complete the wizard.
7. Restart Eclipse when Eclipse asks for it.

<!-- external-only:end -->
### Internal update site (SAP developers)

The internal host gives files only to a browser with a sign-in. Eclipse cannot sign in. Install from a local clone.

1. Clone the repository:

       git clone https://github.tools.sap/GLOFINDEFICA/epod-adt-mcp-updatesite.git

2. In Eclipse, select **Help > Install New Software...**.
3. Click **Add...**.
4. Click **Local...**.
5. Select the cloned folder. The folder holds `compositeContent.xml`.
6. Select **EPOD ADT MCP Server** in the list.
7. Click **Next**.
8. Accept the license and complete the wizard.
9. Restart Eclipse when Eclipse asks for it.

### Install with dropins (not tested)

CAUTION: Nobody tested this way with the two bundles of version 2.6.0. Use the update site if you can.

1. Get the two jars `com.epod.adt.mcp.core_<version>.jar` and `com.epod.adt.mcp.plugin_<version>.jar`. The folder
   `<version>/plugins/` of the update site holds them.
2. Copy both jars into the folder `dropins/` of the Eclipse installation.
3. Restart Eclipse.

## 3. Start the server

1. Select **Window > Show View > Other...**.
2. Select **ABAP MCP Server > ABAP MCP Server**.
3. Click **Open**.
4. In the project table, select your ABAP project.
5. Click **Connect**. To connect all ABAP projects of the workspace, click **Connect All**.

   The tab **Log** shows `Connected 1 of 1 systems.` The column **Status** of the project shows `● Connected`.

6. Click **Start Server**.

   The tab **Log** shows `MCP server started on http://127.0.0.1:3000` and the client configuration block. The
   button changes to **Stop Server**.

The server accepts connections from `127.0.0.1` only. Other computers cannot reach it.

To start the server at each connect, turn on **Auto-start server on connect** in the preferences (section 10).

## 4. The token

The server makes a token at the first start. The server stores the token in the Eclipse preferences of the
workspace. The server uses the same token after a restart of Eclipse.

CAUTION: The token gives access to your ABAP systems with your logon. Do not put the token into a file that other
persons can read. Do not commit the token to git.

- Click **Copy client config** to copy the client configuration block with the token. The button works only while
  the server runs.
- Click **Regenerate token** when the token leaks. The old token stops working at once. Update each MCP client with
  the new token.

## 5. Connect an MCP client

Each request to `/mcp` needs the header `Authorization: Bearer <token>`. In the commands below, replace `<token>`
with the token from the view. The examples use the name `epod-abap-mcp` for the client configuration. The name is
free.

### Claude Code

CAUTION: The command puts the token into the history of your shell. Remove the line from the history after the
command.

1. Run this command for your user:

       claude mcp add --transport http --scope user epod-abap-mcp http://127.0.0.1:3000/mcp --header "Authorization: Bearer <token>"

2. Run `claude mcp list`. The list shows `epod-abap-mcp`.

To use the server in one project folder only, put this block into the file `.mcp.json` in that folder:

```json
{
  "mcpServers": {
    "epod-abap-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

CAUTION: Add `.mcp.json` to the `.gitignore` file of the project. The file holds the token.

### Codex

Codex reads the token from an environment variable.

1. Add the client configuration:

       codex mcp add epod-abap-mcp --url http://127.0.0.1:3000/mcp --bearer-token-env-var EPOD_ABAP_MCP_TOKEN

2. Set the variable in the terminal that starts Codex:

       export EPOD_ABAP_MCP_TOKEN='<token>'

3. Start Codex in the same terminal.

`codex mcp list` shows `epod-abap-mcp` with the auth `Bearer token`.

The second way is a header in `~/.codex/config.toml`:

```toml
[mcp_servers.epod-abap-mcp]
url = "http://127.0.0.1:3000/mcp"
http_headers = { Authorization = "Bearer <token>" }
```

### Other MCP clients

Use the block that **Copy client config** copies:

```json
{
  "mcpServers": {
    "abap-adt": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

The block names the entry `abap-adt`. The name is free. The block uses the type `streamable-http`.
Claude Code uses the type `http` for the same server. Use the type that your MCP client documents for a Streamable
HTTP server.

## 6. Check the connection

1. Open `http://127.0.0.1:3000/health` in a browser.

   The page shows `"status": "ok"` and the version.

2. In the MCP client, ask for the tool `sap_list_systems`.

   The answer lists the connected ABAP projects with their access mode.

## 7. Several ABAP projects

Each tool has the parameter `systemId`. The value is the name of the ABAP project.

- With one connected project, the server uses that project. `systemId` is optional.
- With two or more connected projects, each tool call needs `systemId`. Tell the MCP client which project to use.

The MCP client sees the names of the connected projects in the description of `systemId`.

## 8. Access mode

Each connected system has an access mode: `write` or `read-only`. A new connection starts in `write`. The column
**Mode** of the project table shows the mode.

1. Select the project in the table.
2. Click **Toggle Read-Only**.

   The tab **Log** shows `System <name> is now read-only.`

A read-only system refuses these 12 tools and sends no write request to SAP: `sap_push_source`, `sap_push_source_from_file`,
`sap_push_element`, `sap_push_message`, `sap_push_fields`, `sap_create_object`, `sap_activate`, `sap_lock`,
`sap_unlock`, `sap_transport_create`, `sap_transport_release`, and `sap_quick_fix`. `sap_quick_fix` without `fix`
only lists the proposals and works on a read-only system. All other tools work. The view stores the mode
for each project. The mode stays after a restart of Eclipse.

## 9. Security log

The server writes each server start, server stop, tool call, and refused request to the file `mcp-security.log`.
Each line is one JSON object. The log holds no token and no ABAP source.

1. Click **Open log folder** in the view.

   The folder `<workspace>/.metadata/.plugins/com.epod.adt.mcp.plugin/` opens.

The file rotates at 5 MB. The server keeps 5 archives. The detail level is a preference (section 10).

## 10. Preferences

Select **Window > Preferences...**. Select the page **ABAP MCP Server**.

| Field | Default | Effect |
|---|---|---|
| MCP Server Port | 3000 | The server uses the port at the next start. Change the URL in each MCP client too. |
| Auto-start server on connect | off | The server starts when you connect a project. |
| Security log detail level | Full | The value `Reduced` removes the object name and the time from a tool-call line. |

## 11. Update

<!-- external-only:start -->
- External update site: select **Help > Check for Updates**.
<!-- external-only:end -->
- Internal update site: run `git pull` in the clone. Then repeat the install of section 2.

The token and the access modes stay after an update.

## 12. Uninstall

1. Click **Stop Server** in the view.
2. Remove the client configuration from each MCP client:

       claude mcp remove epod-abap-mcp --scope user
       codex mcp remove epod-abap-mcp

3. Open **Installation Details** from the About dialog of Eclipse.
4. On the page of the installed software, select **EPOD ADT MCP Server**.
5. Click **Uninstall...** and complete the wizard.
6. Restart Eclipse.

The token stays in the file `<workspace>/.metadata/.plugins/org.eclipse.core.runtime/.settings/com.epod.adt.mcp.plugin.prefs`.
Delete the file to remove the token.

## 13. Errors

| Symptom | Cause | Action |
|---|---|---|
| The MCP client gets HTTP 401. | The client sends no token, or an old token. | Click **Copy client config** and update the client configuration. |
| The MCP client gets HTTP 403 with the text `Forbidden`. | The request has an `Origin` header, or a `Host` header that is not local. A browser sends such a request. | Use an MCP client. The server refuses requests from a web page. |
| The tab **Log** shows `ERROR: Connect to at least one ABAP project before starting the server.` | No project is connected. | Connect a project. Click **Start Server**. |
| The tab **Log** shows `ERROR: Failed to start server:` and a reason. | An example is a port that another program uses. | Set another port in the preferences. Update the URL in each MCP client. |
| A tool returns `The destination with ID <name> is not registered.` | The ABAP project has no logon after a restart of Eclipse. | Log on to the project in Eclipse. Call the tool again. |
| A tool returns `Multiple systems connected. Specify 'systemId'.` | Two or more projects are connected. | Tell the MCP client the project name. |
| A tool returns `System <name> is set to read-only.` | The project is read-only. | Click **Toggle Read-Only**, or use another project. |