@mcp-abap-adt/core 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -2,9 +2,29 @@
 
 ## [Unreleased]
 
-## [2.2.1] - 2026-02-10
+## [2.2.3] - 2026-02-10
+### Added
+- **Docs**: Added dedicated Terminology and Authentication guides, with links from README.
+
+### Changed
+- **README**: Reworked first-screen content and links to emphasize configurator usage and destinations.
+- **Docs structure**: Moved GitHub configuration README into deployment docs and fixed internal links.
+- **Client configuration docs**: Linked to the configurator repo and usage guide.
+
+## [2.2.2] - 2026-02-10
+### Added
+- **Client support**: Added OpenCode and Copilot configuration support.
+- **Claude config**: Added `.mcp.json` project configuration and docs.
+- **Configurator options**: Added URL, headers, and timeout options in `mcp-abap-adt-configure`.
+
 ### Changed
 - **Configurator split**: Removed `mcp-abap-adt-configure` from core. Use `@mcp-abap-adt/configurator` (repo: `mcp-abap-adt-conf`) with `mcp-conf` instead.
+- **Codex/Goose handling**: Improved transport handling and timeout defaults for non-stdio transports.
+- **Default-disabled entries**: Updated JSON config handling and docs to keep new entries disabled by default.
+- **Streamable HTTP**: Refactored server handling for per-request connections.
+
+### Fixed
+- **Goose config**: Corrected enabled state handling in `writeGooseConfig`.
 
 ## [2.2.0] - 2026-02-09
 ### Added

package/README.md

@@ -1,18 +1,36 @@
 # mcp-abap-adt: Your Gateway to ABAP Development Tools (ADT)
 
-<a href="https://glama.ai/mcp/servers/@fr0ster/mcp-abap-adt">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/@fr0ster/mcp-abap-adt/badge" />
-</a>
+This project provides a server that allows you to interact with SAP ABAP systems using the Model Context Protocol (MCP). It connects AI clients to real ADT capabilities: read, analyze, and modify ABAP artifacts with a consistent, secure interface.
 
-> **Acknowledgment**: This project was originally inspired by [mario-andreschak/mcp-abap-adt](https://github.com/mario-andreschak/mcp-abap-adt). We started with the core concept and then evolved it into an independent project with our own architecture and features.
+**Why teams use it:**
+- Works with **on‑prem** and **BTP** ABAP systems
+- **Destination‑based auth** (service keys) so you stop pasting tokens everywhere
+- Multiple transports: **stdio**, **HTTP**, **SSE**
+- Rich tool surface for ABAP objects, metadata, transports, and search
 
-This project provides a server that allows you to interact with SAP ABAP systems using the Model Context Protocol (MCP). Think of it as a bridge that lets tools like [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) (a VS Code extension) talk to your ABAP system and retrieve information like source code, table structures, and more.
+**Authorization & Destinations (Important):** A *destination* is the filename of a service key stored locally. You place service keys in the service-keys directory, and use `--mcp=<destination>` to select which one to use. This is the primary auth model for on‑prem and BTP systems. See [Authentication & Destinations](docs/user-guide/AUTHENTICATION.md).
 
-## Configure Clients Fast (Recommended)
+You can configure MCP clients either manually (JSON/TOML) or via the configurator CLI (`@mcp-abap-adt/configurator`, repo: [`mcp-abap-adt-conf`](https://github.com/fr0ster/mcp-abap-adt-conf)).
 
-Use the configurator to generate client config files instead of hand‑editing JSON/TOML:
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Architecture](#architecture)
+3. [Quick Start](#quick-start)
+4. [Terminology](#terminology)
+5. [Authorization & Destinations](#authorization--destinations)
+6. [Registries](#registries)
+7. [Features](#features)
+8. [Documentation](#documentation)
+9. [Dependencies](#dependencies)
+10. [Running the Server](#running-the-server)
+
+## Getting Started
+
+Install the server and configure your client using the configurator:
 
 ```bash
+npm install -g @mcp-abap-adt/core
 npm install -g @mcp-abap-adt/configurator
 
 # stdio (destination)
@@ -22,7 +40,23 @@ mcp-conf --client cline --name abap --mcp TRIAL
 mcp-conf --client copilot --name abap --transport http --url http://localhost:3000/mcp/stream/http --header x-mcp-destination=trial
 ```
 
-Full usage: `docs/CLIENT_INSTALLERS.md` in the `mcp-abap-adt-conf` repo.
+Full configurator usage (separate repo): [CLIENT_INSTALLERS.md](https://github.com/fr0ster/mcp-abap-adt-conf/tree/main/docs/CLIENT_INSTALLERS.md).
+
+## Terminology
+
+**Destination**: a local service key filename. You store service keys in the service-keys directory, and pass the filename (without extension) via `--mcp=<destination>` to select which system to use.
+
+See [docs/user-guide/TERMINOLOGY.md](docs/user-guide/TERMINOLOGY.md) for the full list.
+
+## Authorization & Destinations
+
+Destination-based auth is the default. Drop service keys into the service-keys folder and use the filename as your destination:
+
+```bash
+mcp-abap-adt --transport=stdio --mcp=TRIAL
+```
+
+For full details (paths, `.env`, direct headers), see [Authentication & Destinations](docs/user-guide/AUTHENTICATION.md).
 
 ## Architecture
 
@@ -52,13 +86,19 @@ await server.connect(transport);
 ## Quick Start
 
 1. **Install server**: See [Installation Guide](docs/installation/INSTALLATION.md)
-2. **Configure client (auto)**: Use `mcp-conf` from `@mcp-abap-adt/configurator` (repo: `mcp-abap-adt-conf`)
+2. **Configure client (auto)**: Use `mcp-conf` from `@mcp-abap-adt/configurator` (repo: [`mcp-abap-adt-conf`](https://github.com/fr0ster/mcp-abap-adt-conf), docs: [CLIENT_INSTALLERS.md](https://github.com/fr0ster/mcp-abap-adt-conf/tree/main/docs/CLIENT_INSTALLERS.md))
 3. **Configure client (manual)**: See [Client Configuration](docs/user-guide/CLIENT_CONFIGURATION.md)
 4. **Use**: See [Available Tools](docs/user-guide/AVAILABLE_TOOLS.md)
 
-## MCP Registry
+## Registries
 
-Published in the official MCP Registry. See `docs/deployment/MCP_REGISTRY.md` for full details.
+Published in the official MCP Registry and listed on Glama.ai.
+
+- MCP Registry: [docs/deployment/MCP_REGISTRY.md](docs/deployment/MCP_REGISTRY.md)
+- Glama.ai:
+  <a href="https://glama.ai/mcp/servers/@fr0ster/mcp-abap-adt">
+    <img width="380" height="200" src="https://glama.ai/mcp/servers/@fr0ster/mcp-abap-adt/badge" />
+  </a>
 
 ## Features
 
@@ -85,17 +125,21 @@ Published in the official MCP Registry. See `docs/deployment/MCP_REGISTRY.md` fo
 ## Documentation
 
 ### For Users
-- **[Installation Guide](docs/installation/INSTALLATION.md)** - Installation instructions for all platforms
-- **[Client Configuration](docs/user-guide/CLIENT_CONFIGURATION.md)** - How to configure MCP clients
-- **Configurator**: `@mcp-abap-adt/configurator` (repo: `mcp-abap-adt-conf`) provides the `mcp-conf` CLI to auto-configure clients.
+- **[Docs Index](docs/README.md)** - Full documentation index
+- **[Installation Guide](docs/installation/README.md)** - Installation overview and platform guides
+- **[User Guide](docs/user-guide/README.md)** - End-user docs (auth, config, tools)
+- **[Authentication & Destinations](docs/user-guide/AUTHENTICATION.md)** - Destination-based auth and service keys
+- **[Handlers Management](docs/user-guide/HANDLERS_MANAGEMENT.md)** - Enable/disable handler groups
+- **Configurator**: `@mcp-abap-adt/configurator` (repo: [`mcp-abap-adt-conf`](https://github.com/fr0ster/mcp-abap-adt-conf)) provides the `mcp-conf` CLI to auto-configure clients
 - **[Available Tools](docs/user-guide/AVAILABLE_TOOLS.md)** - Complete list of available MCP tools
 
 ### For Administrators
-- **[Installation Guide](docs/installation/INSTALLATION.md)** - Platform-specific installation guides
+- **[Deployment Docs](docs/deployment/README.md)** - MCP Registry, Docker, release notes
+- **[Server Configuration](docs/configuration/YAML_CONFIG.md)** - YAML config reference
 
 ### For Developers
-- **[Architecture Documentation](docs/architecture/)** - System architecture and design decisions
-- **[Development Documentation](docs/development/)** - Testing guides and development resources
+- **[Architecture Documentation](docs/architecture/README.md)** - System architecture and design decisions
+- **[Development Documentation](docs/development/README.md)** - Testing guides and development resources
 - **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
 
 ## Dependencies
@@ -107,6 +151,9 @@ This project uses two npm packages:
 
 These packages are automatically installed via `npm install` and are published to npm.
 
+---
+
+
 ## Running the Server
 
 ### Global Installation (Recommended)
@@ -184,11 +231,13 @@ SAP_JWT_TOKEN=your-jwt-token
 npm install -g @mcp-abap-adt/connection
 
 # Generate .env file from service key JSON
-sap-abap-auth auth -k path/to/service-key.json
+mcp-auth auth -k path/to/service-key.json
 ```
 
 This will automatically create/update `.env` file with JWT tokens and connection details.
 
+**Claude recommendation:** place the service key in the service-keys directory and use `--mcp=<destination>` (avoid manual JWT tokens).
+
 ### Command-Line Options
 
 **Authentication:**
@@ -246,3 +295,7 @@ npm run docs:tools
 ## Contributors
 
 Thank you to all contributors! See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the complete list.
+
+---
+
+**Acknowledgment**: This project was originally inspired by [mario-andreschak/mcp-abap-adt](https://github.com/mario-andreschak/mcp-abap-adt). We started with the core concept and then evolved it into an independent project with our own architecture and features.

package/docs/README.md

@@ -17,6 +17,7 @@ Complete installation instructions for different platforms and environments.
 Documentation for end users: configuration, usage, and available tools.
 
 - `CLIENT_CONFIGURATION.md` - How to configure MCP clients to connect to the server
+- `AUTHENTICATION.md` - Destination-based auth, service key locations, and header-based auth
 - Configurator (auto-config): `@mcp-abap-adt/configurator` (repo: `mcp-abap-adt-conf`)
 - `AVAILABLE_TOOLS.md` - Complete list of available MCP tools and their descriptions
 - `CLI_OPTIONS.md` - Complete command-line options reference
@@ -26,6 +27,14 @@ Documentation for server configuration options.
 
 - `YAML_CONFIG.md` - YAML configuration file guide (alternative to command-line arguments)
 
+### [deployment/](deployment/) - Deployment & Releases
+Documentation for deployment, Docker, and release flow.
+
+- `README.md` - Deployment docs index
+- `MCP_REGISTRY.md` - MCP Registry publishing
+- `DOCKER.md` - Docker deployment guide
+- `RELEASE.md` - Release process
+
 ### [architecture/](architecture/) - For Developers
 Technical documentation about the system architecture, design decisions, and internal structure.
 
@@ -48,12 +57,20 @@ Documentation for developers: testing, development guides, and internal document
 
 - **Getting Started**: [Installation Guide](installation/INSTALLATION.md)
 - **User Configuration**: [Client Configuration](user-guide/CLIENT_CONFIGURATION.md)
+- **Authentication**: [Destinations & Auth](user-guide/AUTHENTICATION.md)
+- **Terminology**: [Project Terms](user-guide/TERMINOLOGY.md)
+- **Handlers Management**: [Handler Groups](user-guide/HANDLERS_MANAGEMENT.md)
 - **Server Configuration**: [YAML Config](configuration/YAML_CONFIG.md) | [CLI Options](user-guide/CLI_OPTIONS.md)
 - **Deployment**: [MCP Registry](deployment/MCP_REGISTRY.md) | [Docker](deployment/DOCKER.md)
 - **Available Tools**: [Tools List](user-guide/AVAILABLE_TOOLS.md)
 - **Architecture**: [Stateful Sessions](architecture/STATEFUL_SESSION_GUIDE.md) | [Architecture Docs](architecture/README.md)
 - **Development**: [Development Documentation](development/)
 
+## 📦 Artifacts
+
+- `adt-discovery.xml` - ADT discovery snapshot
+- `discovery.json` - ADT discovery JSON snapshot
+
 ## 📝 Package-Specific Documentation
 
 Package-specific documentation is available in the respective npm packages:

package/docs/architecture/README.md

@@ -41,6 +41,7 @@ Handlers are organized into logical groups for flexible composition:
 - **[STATEFUL_SESSION_GUIDE.md](STATEFUL_SESSION_GUIDE.md)** - Stateful ADT request flow for lock/update/unlock operations
 - **[TOOLS_ARCHITECTURE.md](TOOLS_ARCHITECTURE.md)** - MCP tools architecture and handler structure, explaining how tools are organized and how `TOOL_DEFINITION` works
 - **[CONNECTION_ISOLATION.md](CONNECTION_ISOLATION.md)** - Connection isolation architecture, explaining how per-session connection isolation prevents data mixing between clients (version 1.1.10+)
+- **[HANDLER_EXPORTER.md](HANDLER_EXPORTER.md)** - Legacy handler exporter usage
 
 ## Related Documentation
 

package/docs/deployment/GITHUB_ACTIONS.md

@@ -0,0 +1,122 @@
+# GitHub Configuration
+
+This directory contains GitHub-specific configuration files.
+
+## Workflows
+
+### 🚀 Release Workflow (`workflows/release.yml`)
+
+Automatically creates GitHub releases when you push a version tag.
+
+**Trigger:** Push tags matching `v*.*.*` (e.g., `v1.1.0`, `v2.0.0`)
+
+**What it does:**
+1. Checks out code with submodules
+2. Sets up Node.js 18
+3. Installs dependencies
+4. Builds the project
+5. Runs tests (non-blocking)
+6. Creates npm package (.tgz)
+7. Creates GitHub Release
+8. Uploads package as release asset
+9. Generates release notes
+
+**Usage:**
+```bash
+# Bump version
+npm version patch  # 1.1.0 -> 1.1.1
+
+# Create and push tag
+git tag v1.1.1
+git push origin main
+git push origin v1.1.1
+```
+
+### ✅ CI Workflow (`workflows/ci.yml`)
+
+Runs continuous integration tests on every push and PR.
+
+**Trigger:** 
+- Push to `main` or `develop` branches
+- Pull requests to `main` or `develop`
+
+**What it does:**
+1. Tests on multiple OS (Ubuntu, macOS, Windows)
+2. Tests on multiple Node.js versions (18, 20)
+3. Builds and tests the project
+4. Verifies package creation
+5. Tests package installation
+
+### 📦 Publish to npm (`workflows/publish-npm.yml`)
+
+Optional workflow for publishing to npm registry.
+
+**Trigger:** Manual (workflow_dispatch)
+
+**Setup required:**
+1. Set `private: false` in package.json
+2. Add NPM_TOKEN to repository secrets
+3. Get token from https://www.npmjs.com/settings/[username]/tokens
+
+## Release Process
+
+See [docs/deployment/RELEASE.md](../docs/deployment/RELEASE.md) for detailed release instructions.
+
+### Quick Release
+
+```bash
+# 1. Bump version
+npm version minor  # or patch, major
+
+# 2. Commit
+git add package.json package-lock.json
+git commit -m "chore: release v1.2.0"
+
+# 3. Tag and push
+git tag v1.2.0
+git push origin main --tags
+```
+
+## Secrets Configuration
+
+Currently no secrets are required for basic releases.
+
+**Optional (for npm publishing):**
+- `NPM_TOKEN` - npm authentication token
+
+**Built-in secrets used:**
+- `GITHUB_TOKEN` - Automatically provided by GitHub Actions
+
+## Permissions
+
+Workflows use these permissions:
+- `contents: write` - Required for creating releases
+- `GITHUB_TOKEN` - Automatically scoped by GitHub
+
+## Troubleshooting
+
+**Release workflow didn't trigger:**
+- Ensure tag starts with `v` (e.g., `v1.0.0`)
+- Check tag was pushed: `git push origin v1.0.0`
+- Verify workflow file is in `main` branch
+
+**Release failed:**
+- Check GitHub Actions logs
+- Common issues:
+  - Build errors
+  - Test failures (should be non-blocking)
+  - Permission errors (check GITHUB_TOKEN)
+
+**CI tests failing:**
+- Check specific OS/Node.js version matrix
+- Tests are allowed to fail without blocking
+- Package creation must succeed
+
+## Workflow Status Badges
+
+Add to README.md:
+
+```markdown
+[![Release](https://github.com/fr0ster/mcp-abap-adt/actions/workflows/release.yml/badge.svg)](https://github.com/fr0ster/mcp-abap-adt/actions/workflows/release.yml)
+[![CI](https://github.com/fr0ster/mcp-abap-adt/actions/workflows/ci.yml/badge.svg)](https://github.com/fr0ster/mcp-abap-adt/actions/workflows/ci.yml)
+```

package/docs/deployment/README.md

@@ -52,5 +52,5 @@ See [RELEASE.md](./RELEASE.md) for detailed instructions.
 ## Related Documentation
 
 - [Installation Guide](../installation/INSTALLATION.md) - Installation for development
-- [CI/CD Configuration](../../.github/README.md) - GitHub Actions workflows
+- [CI/CD Configuration](GITHUB_ACTIONS.md) - GitHub Actions workflows
 - [User Guide](../user-guide/README.md) - Using the server

package/docs/development/README.md

@@ -5,11 +5,20 @@ This directory contains documentation for developers: testing guides, developmen
 ## Files
 
 - **[ASSISTANT_GUIDELINES.md](ASSISTANT_GUIDELINES.md)** - Guidelines for AI assistants working on this project
+- **[ISSUE_ROADMAP_SYSTEM.md](ISSUE_ROADMAP_SYSTEM.md)** - Roadmap organization and issue tracking workflow
+- **[TEST_CONFIG_YAML_GUIDE.md](TEST_CONFIG_YAML_GUIDE.md)** - Test configuration reference
 - **[TEST_SYSTEM_SETUP.md](TEST_SYSTEM_SETUP.md)** - Guide for setting up test systems
-- **[SYNC_OPTIONAL_PARAMS.md](SYNC_OPTIONAL_PARAMS.md)** - Tool to sync optional parameters from adt-clients TypeScript interfaces
-- **[DetectObjectTypeListTools.md](DetectObjectTypeListTools.md)** - Documentation for object type detection tools
-- **[HANDLERS_COVERAGE.md](HANDLERS_COVERAGE.md)** - Analysis of low-level handlers coverage and implementation status
-- **[TEST_LOGGING_ROADMAP.md](roadmaps/TEST_LOGGING_ROADMAP.md)** - Test logging storage and rotation policy
+
+## Roadmaps
+
+- `roadmaps/HANDLER_BUILD_ERRORS_ROADMAP.md`
+- `roadmaps/INFRASTRUCTURE_HANDLERS.md`
+- `roadmaps/MCP_SERVER_REFACTORING_ROADMAP.md`
+- `roadmaps/TEST_LOGGING_ROADMAP.md`
+- `roadmaps/TEST_REFACTORING_ROADMAP.md`
+- `roadmaps/TODO_ROADMAP.md`
+- `roadmaps/USAGE_DOCUMENTATION_ROADMAP.md`
+- `roadmaps/parameter_passing_unit_tests_roadmap.md`
 
 ## Test Documentation
 

package/docs/installation/INSTALLATION.md

@@ -51,7 +51,7 @@ After installation, you'll have access to:
 **For JWT authentication with service keys**, install the connection package separately:
 ```bash
 npm install -g @mcp-abap-adt/connection
-sap-abap-auth auth -k path/to/service-key.json
+mcp-auth auth -k path/to/service-key.json
 ```
 
 **Get help on available options:**
@@ -80,7 +80,7 @@ For JWT authentication (SAP BTP) with service key:
 npm install -g @mcp-abap-adt/connection
 
 # Generate .env file from service key JSON
-sap-abap-auth auth -k path/to/service-key.json
+mcp-auth auth -k path/to/service-key.json
 
 # This automatically creates/updates .env file with JWT tokens
 ```
@@ -88,7 +88,7 @@ sap-abap-auth auth -k path/to/service-key.json
 **Run the server:**
 ```bash
 # Default HTTP mode (uses auth-broker by default, even if .env exists)
-# Note: auth-broker is only available for HTTP/streamable-http transport
+# Note: auth-broker is available for stdio/SSE via `--mcp=<destination>` and for HTTP via destination headers
 mcp-abap-adt
 
 # Force use of auth-broker (service keys), ignore .env file
@@ -282,7 +282,7 @@ mcp-abap-adt --transport=sse --sse-port=3001
 **For JWT authentication with service keys**, install separately:
 ```bash
 npm install -g @mcp-abap-adt/connection
-sap-abap-auth auth -k path/to/service-key.json
+mcp-auth auth -k path/to/service-key.json
 ```
 
 #### Local Installation (Project-specific)

package/docs/installation/README.md

@@ -5,12 +5,14 @@ This directory contains installation guides for the MCP ABAP ADT Server.
 ## Files
 
 - **[INSTALLATION.md](INSTALLATION.md)** - Main installation guide with platform-specific quick links
+- **[CLINE_CONFIGURATION.md](CLINE_CONFIGURATION.md)** - Cline client configuration examples
 - **[platforms/](platforms/)** - Platform-specific installation guides
   - `INSTALL_WINDOWS.md` - Windows installation using PowerShell and winget
   - `INSTALL_MACOS.md` - macOS installation using Homebrew
   - `INSTALL_LINUX.md` - Linux installation using package managers
+- **[examples/README.md](examples/README.md)** - Example client configurations
+  - `SERVICE_KEY_SETUP.md` - Service key setup for destination-based auth
 
 ## Quick Start
 
 See the main [INSTALLATION.md](INSTALLATION.md) file for a complete overview and quick start instructions for your platform.
-

package/docs/installation/examples/README.md

@@ -82,7 +82,7 @@ Use `cline-http-service-key-npx-config.json` for destination-based authenticatio
    **Note**: 
    - The `--auth-broker` flag forces use of auth-broker (service keys), ignoring any `.env` file
    - By default (without `--env` or `--auth-broker`), the server uses `.env` from current directory if it exists, otherwise uses auth-broker
-   - Auth-broker is only available for HTTP/streamable-http transport (not for stdio/SSE)
+   - Auth-broker is available for stdio/SSE via `--mcp=<destination>` and for HTTP via destination headers
 
 3. **Use config** with destination header:
    ```json

package/docs/user-guide/AUTHENTICATION.md

@@ -0,0 +1,61 @@
+# Authentication & Destinations
+
+The server supports multiple auth flows. The primary (and recommended) model is **destination-based authentication** using service keys.
+
+## Destinations
+
+A **destination** is simply the **filename** of a service key stored in the service-keys directory.
+
+- Put service keys here:
+  - Linux/macOS: `~/.config/mcp-abap-adt/service-keys`
+  - Windows: `%APPDATA%\mcp-abap-adt\service-keys`
+- The filename (without extension) becomes the destination name.
+
+Example:
+
+```
+~/.config/mcp-abap-adt/service-keys/TRIAL.json
+```
+
+Use it like this:
+
+```bash
+mcp-abap-adt --transport=stdio --mcp=TRIAL
+```
+
+The server will load the matching service key and manage tokens automatically.
+
+## .env Authentication
+
+You can also provide credentials via `.env`:
+
+- In the current directory: `.env`
+- Or explicitly: `--env /path/to/.env`
+
+This is useful for quick local testing or when you do not want to store service keys.
+
+### Generate .env from Service Key
+
+```bash
+npm install -g @mcp-abap-adt/connection
+mcp-auth auth -k path/to/service-key.json
+```
+
+This writes JWT details to `.env`.
+
+**Claude recommendation:** for Claude, prefer service keys in `service-keys` and use `--mcp=<destination>` instead of manual tokens.
+
+## HTTP/SSE Headers
+
+For HTTP/SSE transports, you can supply auth per request using headers:
+
+- JWT: `x-sap-url`, `x-sap-client`, `x-sap-auth-type=jwt`, `x-sap-jwt-token`
+- Basic: `x-sap-url`, `x-sap-client`, `x-sap-login`, `x-sap-password`
+
+Header-based auth is useful for proxy setups or dynamic routing.
+
+## Related Docs
+
+- Client setup: `docs/user-guide/CLIENT_CONFIGURATION.md`
+- Service key example: `docs/installation/examples/SERVICE_KEY_SETUP.md`
+- Server CLI options: `docs/user-guide/CLI_OPTIONS.md`

package/docs/user-guide/CLIENT_CONFIGURATION.md

@@ -2,6 +2,9 @@
 
 This guide explains how to configure MCP clients to connect to the `mcp-abap-adt` server.
 
+If you prefer not to edit JSON/TOML by hand, use the configurator CLI:
+`@mcp-abap-adt/configurator` (repo: [`mcp-abap-adt-conf`](https://github.com/fr0ster/mcp-abap-adt-conf), docs: [CLIENT_INSTALLERS.md](https://github.com/fr0ster/mcp-abap-adt-conf/tree/main/docs/CLIENT_INSTALLERS.md)).
+
 ## Overview
 
 The `mcp-abap-adt` server supports multiple transport modes:
@@ -80,7 +83,7 @@ The server processes the following HTTP headers (as checked in `applyAuthHeaders
 - For **JWT authentication**: `x-sap-url`, `x-sap-auth-type`, and `x-sap-jwt-token` are required. `x-sap-refresh-token` is optional for automatic token refresh.
 - For **basic authentication**: `x-sap-url`, `x-sap-auth-type`, `x-sap-login`, and `x-sap-password` are required.
 - For **destination-based authentication**: Use `x-sap-destination` or `x-mcp-destination` header. URL is automatically derived from the service key, so `x-sap-url` is not required (and will be ignored if provided). Service keys must be stored in platform-specific locations (see [Destination-Based Authentication](#destination-based-authentication) section).
-- For automatic token refresh, you only need `x-sap-refresh-token`. Client ID and Client Secret are **not needed** for refresh - they are only required for initial token generation via `sap-abap-auth` CLI tool (part of `@mcp-abap-adt/connection` package) or service keys.
+- For automatic token refresh, you only need `x-sap-refresh-token`. Client ID and Client Secret are **not needed** for refresh - they are only required for initial token generation via `mcp-auth` CLI tool (part of `@mcp-abap-adt/connection` package) or service keys.
 
 
 ## Basic Authentication
@@ -572,7 +575,7 @@ The server supports automatic token refresh when `x-sap-refresh-token` is provid
 
 The connection will automatically refresh expired tokens when a 401/403 error is detected. The refresh happens transparently without requiring manual intervention.
 
-**Note:** For automatic token refresh, you only need the refresh token. Client ID and Client Secret are **not needed** for refresh - they are only required for initial token generation via `sap-abap-auth` CLI tool (part of `@mcp-abap-adt/connection` package).
+**Note:** For automatic token refresh, you only need the refresh token. Client ID and Client Secret are **not needed** for refresh - they are only required for initial token generation via `mcp-auth` CLI tool (part of `@mcp-abap-adt/connection` package).
 
 ## Examples
 

package/docs/user-guide/README.md

@@ -57,11 +57,16 @@ See [Installation Guide](../installation/INSTALLATION.md) for full instructions.
 
 - **[CLIENT_CONFIGURATION.md](CLIENT_CONFIGURATION.md)** - Guide for configuring MCP clients to connect to the server, including HTTP header configuration for dynamic SAP connection setup
 - **[AVAILABLE_TOOLS.md](AVAILABLE_TOOLS.md)** - Complete list of all available MCP tools with descriptions and usage examples (auto-generated from handler definitions)
+- **[AUTHENTICATION.md](AUTHENTICATION.md)** - Destination-based auth, service key locations, and header-based auth
+- **[TERMINOLOGY.md](TERMINOLOGY.md)** - Project-specific terminology
+- **[HANDLERS_MANAGEMENT.md](HANDLERS_MANAGEMENT.md)** - Enable/disable handler groups and exposure
 
 ## Getting Started
 
 1. **Install the server**: Choose package or source installation above
-2. **Configure your client**: See [CLIENT_CONFIGURATION.md](CLIENT_CONFIGURATION.md) for setup instructions
+2. **Configure your client**:
+   - **Auto (recommended)**: Use the configurator (`@mcp-abap-adt/configurator`, repo: `mcp-abap-adt-conf`)
+   - **Manual**: See [CLIENT_CONFIGURATION.md](CLIENT_CONFIGURATION.md) for JSON/TOML examples
 3. **Explore available tools**: See [AVAILABLE_TOOLS.md](AVAILABLE_TOOLS.md) for a complete list of tools you can use
 
 ## Package Tree Output

package/docs/user-guide/TERMINOLOGY.md

@@ -0,0 +1,38 @@
+# Terminology
+
+This project uses a few terms in specific ways. If a term below is used differently in other tools, prefer the definitions here.
+
+## Destination
+
+A **destination** is the **filename** of a service key stored in the local `service-keys` directory. Example:
+
+```
+~/.config/mcp-abap-adt/service-keys/TRIAL.json
+```
+
+Use it with `--mcp=TRIAL` or the `x-mcp-destination` header.
+
+## Service Key
+
+A JSON file downloaded from SAP BTP (XSUAA credentials). The filename becomes the destination name. The server reads it to obtain service URL and OAuth details.
+
+## Auth Broker
+
+The internal component that loads service keys, manages sessions/tokens, and provides connection configs. When `--mcp` is used, auth-broker is enabled automatically.
+
+## Session Store
+
+Storage for OAuth sessions/tokens created by auth-broker. By default sessions are in-memory unless `--unsafe` or `--auth-broker-path` is used.
+
+## Transport
+
+The protocol used between MCP client and server:
+
+- `stdio` — local process stdio
+- `http` / `streamableHttp` — HTTP POST JSON endpoint
+- `sse` — server-sent events + POST messages
+
+## Headers vs .env
+
+For HTTP/SSE, SAP connection can be provided per request using headers (e.g., `x-sap-url`, `x-sap-auth-type`, `x-sap-jwt-token`). For stdio, use `.env` or `--mcp` destinations.
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mcp-abap-adt/core",
   "mcpName": "io.github.fr0ster/mcp-abap-adt",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {