# Developer Tools

This directory contains utility scripts for development and maintenance of the MCP ABAP ADT server.

## Available Tools

### 0. Runtime Debug Explorer

**`debug-runtime-explorer.js`** - Interactive research script for debugger/trace runtime APIs.

**Purpose:** Rapidly validate a real debug workflow against trial/on-prem systems:
- Prepare probe class via `AdtClient.getClass()`
- Add/update local ABAP Unit test include
- Run baseline test execution (without debugger)
- Explore debugger runtime operations step-by-step

**Usage:**
```bash
node tools/debug-runtime-explorer.js
```

**Required env vars:**
- `SAP_URL`
- `SAP_AUTH_TYPE` (`basic` or `xsuaa`)
- For `basic`: `SAP_USERNAME`, `SAP_PASSWORD`
- For `xsuaa`: `SAP_JWT_TOKEN`

**Optional env vars:**
- `DEBUG_PROBE_CLASS` (default autogenerated `ZCL_MCP_DBG_*`)
- `DEBUG_PROBE_PACKAGE` (default `$TMP`)
- `DEBUG_PROBE_TRANSPORT` (optional)
- `DEBUG_PROBE_TEST_CLASS` (default `LTC_DEBUG_PROBE`)
- `DEBUG_PROBE_VERBOSE=true` for request-level debug logs

**When to use:**
- Before writing automated runtime tests for debugger/trace tools
- During endpoint discovery and compatibility checks in trial systems
- To reproduce debug session issues interactively

---

### 0.5 Runtime Profiling + Dumps Explorer

**`runtime-profiling-dumps-explorer.js`** - Interactive script for profiling and dump analysis via `AdtClient`/`AdtRuntimeClient`/`AdtExecutor`.

**Purpose:**
- Initialize connection via:
  - `--mcp=<destination>` (AuthBroker)
  - `--env=<name>` (loads `~/.config/mcp-abap-adt/sessions/<name>.env`)
  - `--env-path=<path>` (explicit env file path)
- Create or update executable ABAP class for profiling
- Run executable object with profiling (`class` via `AdtExecutor`)
- List profiler trace files and optionally read trace data (`hitlist`/`statements`/`dbaccesses`)
- List dumps (ABAP user filter is required) and optionally read selected dump details

**Note:** This tool is class-focused for profiling run. No direct run-endpoint calls are used.

**Usage:**
```bash
# AuthBroker destination mode
node tools/runtime-profiling-dumps-explorer.js --mcp=TRIAL

# Session env by name (loads ~/.config/mcp-abap-adt/sessions/trial.env)
node tools/runtime-profiling-dumps-explorer.js --env=trial

# Explicit env path
node tools/runtime-profiling-dumps-explorer.js --env-path=/path/to/.env
```

**Optional args:**
- `--abap-user=CB9980000423` (default ABAP user filter for dumps/traces menu)
- `--package=ZMY_PACKAGE` (default package hint for class/report create/update prompt)
- `--auth-broker-path=/path/to/storage`
- `--browser-auth-port=3101`
- `--browser=system`
- `--verbose`

**ABAP user resolution for filters:**
1. `--abap-user` (highest priority)
2. `mcp-abap-adt-clients` system info helper (`getSystemInformation`, field `userName`)
3. Connection fallback (basic username)

---

### 0.6 MCP CRUD Smoke Runner

**`mcp-crud-smoke.js`** - MCP client script that validates real CRUD via running MCP server transport (HTTP/SSE/stdio) using `tests/test-config.yaml`.

**Purpose:**
- Reproduce real client/server integration (instead of direct handler invocation)
- Run `CreateProgram -> GetProgram -> UpdateProgram -> GetProgram -> DeleteProgramLow`
- Use normal YAML test cases (`create_program.test_cases`) with package/transport defaults
- Detect transport-level/config/session issues that integration handler tests can miss

**Usage:**
```bash
# Recommended: connect to already running HTTP MCP server
npm run smoke:mcp:crud -- --transport=http

# Target specific case
npm run smoke:mcp:crud -- --case=builder_program --fail-fast

# Avoid object name collisions
npm run smoke:mcp:crud -- --suffix=SMOKE01
```

If CLI flags are omitted, defaults are taken from `tests/test-config.yaml` -> `environment.integration_hard_mode` (`transport`, `http_url`, `sse_url`, `stdio_command`, `env_path`).

---

### 0.7 MCP CRUD Matrix Runner

**`mcp-crud-matrix.js`** - Wrapper over `mcp-crud-smoke.js` that runs the same YAML-driven CRUD smoke tests across multiple transports.

**Default mode:**
- runs only one protocol from `tests/test-config.yaml` -> `environment.integration_hard_mode.transport`
- override with `--protocol=http|sse|stdio`

**Optional matrix mode (explicit only):**
- use `--protocols=http,sse,stdio` when you intentionally need all protocols

**Usage:**
```bash
# Run one protocol from YAML (recommended)
npm run smoke:mcp:matrix

# Force single protocol
npm run smoke:mcp:matrix -- --protocol=sse

# Explicit full matrix (opt-in)
npm run smoke:mcp:matrix -- --protocols=http,sse,stdio

# Single YAML case with fail-fast
npm run smoke:mcp:matrix -- --case=builder_program --fail-fast
```

HTTP/SSE URLs default to `tests/test-config.yaml` -> `environment.integration_hard_mode`.

---

### 1. Documentation Generator

**`generate-tools-docs.js`** - Automatically generates tool documentation from handler files.

**Purpose:** Creates `doc/user-guide/AVAILABLE_TOOLS.md` by extracting `TOOL_DEFINITION` from all handler files.

**Usage:**
```bash
npm run docs:tools
# or
node tools/generate-tools-docs.js [--help]
```

**What it does:**
- Scans all handler files in `src/handlers/`
- Extracts `TOOL_DEFINITION` from each handler
- Groups tools by category (Programs, Tables, Enhancements, etc.)
- Generates markdown documentation with:
  - Tool descriptions
  - Parameter lists with types and descriptions
  - Example JSON for each tool
  - Special notes (e.g., ABAP Cloud limitations)

**Output:** `doc/user-guide/AVAILABLE_TOOLS.md`

**When to use:**
- After adding new tools
- After updating tool descriptions
- Before releasing a new version
- To keep documentation in sync with code

---

### 2. TOOL_DEFINITION Helper

**`update-handlers-with-tool-definitions.js`** - Helps add `TOOL_DEFINITION` to handler files.

**Purpose:** Checks handler files and assists in adding `TOOL_DEFINITION` exports if missing.

**Usage:**
```bash
node tools/update-handlers-with-tool-definitions.js [--help]
```

**What it does:**
- Scans all handler files in `src/handlers/`
- Checks if each handler has `TOOL_DEFINITION`
- If missing, suggests a basic `TOOL_DEFINITION` based on:
  - Handler function name
  - JSDoc comments (if available)
- Adds the definition to the file

**⚠️ Important:** Auto-generated `TOOL_DEFINITION` is incomplete! You must:
- Review and update the description
- Complete `inputSchema.properties` to match handler parameters
- Set the `required` array correctly
- Add default values if needed

**When to use:**
- When creating a new handler file
- When migrating old handlers to new architecture
- To verify all handlers have `TOOL_DEFINITION`

**Best practice:** Manually add `TOOL_DEFINITION` following existing patterns. Use this script only as a starting point.

---

### 3. SAP ABAP Authentication CLI

The authentication utility is now provided by the `@mcp-abap-adt/connection` package.

## Requirements

- Node.js (>= 14.x)
- Service key file in JSON format from SAP BTP ABAP Environment

## Creating a Service Key

1. Log in to SAP BTP Cockpit
2. Go to your ABAP Environment (or Trial)
3. Select "Service Keys" (or create a service instance if you don't have one yet)
4. Create a new Service Key with the required parameters
5. Copy the JSON data and save it to a file (e.g., `abap-service-key.json`)

## Usage

```bash
# Using the CLI tool from @mcp-abap-adt/connection package
npx sap-abap-auth auth -k path/to/service-key.json

# Or if installed globally
sap-abap-auth auth -k path/to/service-key.json
```

## Result

The CLI utility will:

1. Read the service key file
2. Obtain an OAuth2 JWT token via XSUAA (or use basic)
3. Extract the URL and client of the SAP ABAP system
4. Update the `.env` file with the required values for JWT (xsuaa) or basic authentication, including refresh token and UAA credentials
5. Display the operation status in the console

## Example service key file structure

```json
{
  "uaa": {
    "clientid": "...",
    "clientsecret": "...",
    "url": "https://...",
    "tokenendpoint": "https://..."
  },
  "abap": {
    "url": "https://...",
    "sapClient": "100"
  },
  "endpoints": {
    "api": "https://..."
  }
}
```

## Example .env for JWT (xsuaa) and basic

```
SAP_URL=https://your-abap-url
SAP_CLIENT=100
SAP_AUTH_TYPE=xsuaa
SAP_JWT_TOKEN=your_jwt_token_here
SAP_REFRESH_TOKEN=your_refresh_token_here
SAP_UAA_URL=https://your-uaa-url
SAP_UAA_CLIENT_ID=your_client_id
SAP_UAA_CLIENT_SECRET=your_client_secret
# or for basic
# SAP_AUTH_TYPE=basic
# SAP_USERNAME=your_username
# SAP_PASSWORD=your_password
```

## For developers

- The authentication CLI tool is available via `npx sap-abap-auth` (from `@mcp-abap-adt/connection` package).
- The MCP server automatically uses JWT or basic according to the .env.
- The server supports refresh token in HTTP headers (`X-SAP-Refresh-Token`, `SAP-Refresh-Token`, or `X-Refresh-Token`) for dynamic token updates.
