@mcp-abap-adt/core 2.3.0 → 2.4.0

package/docs/architecture/ARCHITECTURE.md

@@ -0,0 +1,706 @@
+# MCP ABAP ADT -- System Architecture
+
+This document provides a comprehensive architectural description of the **mcp-abap-adt** system: a multi-component, interface-driven TypeScript platform that enables AI assistants to interact with SAP ABAP systems through the ADT (ABAP Development Tools) REST API via the Model Context Protocol (MCP).
+
+---
+
+## 1. Architectural Principles
+
+### 1.1 Interface-Only Communication (IOC)
+
+All inter-package communication occurs exclusively through TypeScript interfaces defined in `@mcp-abap-adt/interfaces`. No package imports concrete implementations from another package. This is not a guideline -- it is an enforced architectural invariant.
+
+```typescript
+// Correct -- depends on interface only
+import type { ISessionStore } from '@mcp-abap-adt/interfaces';
+
+// Prohibited -- creates concrete coupling
+import { AbapSessionStore } from '@mcp-abap-adt/auth-stores';
+```
+
+### 1.2 Dependency Inversion
+
+All high-level modules depend on abstractions (interfaces), not on low-level implementations. Concrete implementations are injected at the composition root (`launcher.ts` in the main server). This ensures that every component can be tested in isolation and replaced without modifying consumers.
+
+### 1.3 Replaceable Default Implementations
+
+Every interface shipped with the system has at least one default implementation. Consumers are free to substitute any default with a custom implementation that satisfies the same interface contract. The system makes no assumptions beyond what interfaces specify.
+
+### 1.4 Separation of Concerns
+
+Each package owns exactly one responsibility:
+
+| Concern | Package |
+|:---|:---|
+| Interface contracts | `@mcp-abap-adt/interfaces` |
+| Logging abstraction | `@mcp-abap-adt/logger` |
+| Header validation | `@mcp-abap-adt/header-validator` |
+| Credential storage | `@mcp-abap-adt/auth-stores` |
+| Token orchestration | `@mcp-abap-adt/auth-broker` |
+| Token acquisition flows | `@mcp-abap-adt/auth-providers` |
+| HTTP transport to SAP | `@mcp-abap-adt/connection` |
+| ABAP object operations | `@mcp-abap-adt/adt-clients` |
+| MCP protocol adapter | `mcp-abap-adt` (main server) |
+| Authorization proxy | `@mcp-abap-adt/proxy` |
+| Client configurator | `@mcp-abap-adt/configurator` |
+
+### 1.5 Clear Runtime Contracts
+
+Every public function and method operates against well-defined input/output types. Error conditions are expressed through typed error codes (`AdtObjectErrorCodes`, `TokenProviderErrorCodes`, `StoreErrorCodes`), not raw strings. This makes error handling deterministic across all consumers.
+
+---
+
+## 2. Component Catalogue
+
+### 2.1 @mcp-abap-adt/interfaces
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Single source of truth for all TypeScript interfaces, types, enums, and error codes |
+| **Dependencies** | None (base package) |
+| **Replaceable** | N/A -- defines contracts, not implementations |
+| **Runtime role** | Type-only at runtime (compile-time contracts) |
+
+**Interface domains:**
+
+| Domain | Key Interfaces | Purpose |
+|:---|:---|:---|
+| Connection | `IAbapConnection`, `IAbapRequestOptions`, `IAdtResponse` | HTTP communication with SAP ADT |
+| Authentication | `IAuthorizationConfig`, `IConnectionConfig`, `IConfig` | Auth credential structures |
+| Token | `ITokenProvider`, `ITokenResult`, `ITokenRefresher` | Token lifecycle management |
+| Session | `ISessionStore`, `ISessionStorage`, `ISessionState` | Session persistence |
+| Service Key | `IServiceKeyStore` | Service key access |
+| ADT Objects | `IAdtObject<TConfig, TState>`, `IAdtObjectState`, `IAdtObjectConfig` | CRUD lifecycle for ABAP objects |
+| Logging | `ILogger`, `LogLevel` | Structured logging |
+| Validation | `IHeaderValidationResult`, `IValidatedAuthConfig` | Header analysis |
+| SAP Config | `ISapConfig`, `SapAuthType` | SAP system configuration |
+| Headers | `HEADER_*` constants, header group arrays | HTTP header contracts |
+
+**Generic object model** -- every ABAP object type is modeled through two generic parameters:
+
+- **`TConfig`** -- static metadata (name, package, description, transport request)
+- **`TState extends IAdtObjectState`** -- accumulated operation results (read, create, lock, activate, errors)
+
+This allows `IAdtObject<TConfig, TState>` to provide a uniform CRUD interface across all 22+ supported ABAP object types.
+
+---
+
+### 2.2 @mcp-abap-adt/logger
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Logging abstraction with two default implementations |
+| **Public interface** | `ILogger` (info, error, warn, debug) |
+| **Default implementations** | `DefaultLogger` (console-based), `PinoLogger` (structured, with fallback) |
+| **Replaceable** | Yes -- any `ILogger` implementation accepted |
+| **Runtime role** | Injected into all components that produce diagnostic output |
+| **Dependencies** | `@mcp-abap-adt/interfaces`; `pino` as optional peer dependency |
+
+`PinoLogger` dynamically loads `pino` at runtime. If pino is not installed, it silently falls back to `DefaultLogger`. Both implementations respect the `AUTH_LOG_LEVEL` environment variable and redact sensitive fields (passwords, tokens, authorization headers).
+
+---
+
+### 2.3 @mcp-abap-adt/header-validator
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Validates and normalizes incoming HTTP authorization headers |
+| **Public interface** | `IHeaderValidationResult`, `IValidatedAuthConfig` |
+| **Replaceable** | Yes |
+| **Runtime role** | Used by HTTP/SSE transport servers to extract auth parameters from request headers |
+| **Dependencies** | `@mcp-abap-adt/interfaces` |
+
+Supports prioritized authentication methods:
+
+| Priority | Method | Headers |
+|:---|:---|:---|
+| 4 (highest) | SAP Destination (AuthBroker) | `x-sap-destination` |
+| 3 | MCP Destination + JWT | `x-mcp-destination` + `x-sap-auth-type=jwt` |
+| 2 | Direct JWT | `x-sap-jwt-token` |
+| 1 | Basic Auth | `x-sap-login` + `x-sap-password` |
+| 0 | None | No valid auth |
+
+---
+
+### 2.4 @mcp-abap-adt/auth-stores
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Persistent storage for service keys and session data |
+| **Public interfaces** | `IServiceKeyStore`, `ISessionStore` |
+| **Default implementations** | `AbapServiceKeyStore`, `XsuaaServiceKeyStore`, `AbapSessionStore`, `XsuaaSessionStore` |
+| **Replaceable** | Yes -- consumers can provide any `IServiceKeyStore` / `ISessionStore` |
+| **Runtime role** | Supplies credentials and persists tokens between sessions |
+| **Dependencies** | `@mcp-abap-adt/interfaces`, `dotenv` |
+
+Service key stores read `{destination}.json` files from a configurable directory. Session stores persist authorization and connection configurations per destination. ABAP and XSUAA variants differ in JSON structure parsing, not in interface contract.
+
+---
+
+### 2.5 @mcp-abap-adt/auth-broker
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Token orchestration -- coordinates stores and providers to produce valid tokens |
+| **Public interface** | `AuthBroker` class, `ITokenRefresher` factory |
+| **Replaceable** | Yes -- any object satisfying the same method signatures |
+| **Runtime role** | Central authentication coordinator; creates `ITokenRefresher` for injection into connections |
+| **Dependencies** | `@mcp-abap-adt/interfaces` |
+
+**Token acquisition flow** (multi-step with fallback):
+
+```
+1. Check session store for cached token
+   └─ Valid? → return token
+2. Attempt token refresh via refresh_token
+   └─ Success? → persist to session store, return token
+3. Fall back to browser-based OAuth2 authorization_code flow
+   └─ Success? → persist to session store, return token
+4. Fail with typed error (BROWSER_AUTH_REQUIRED, REFRESH_ERROR, etc.)
+```
+
+`AuthBroker` accepts three injected dependencies:
+
+- `ISessionStore` (required) -- cached tokens and connection config
+- `IServiceKeyStore` (optional) -- initial credentials from service key files
+- `ITokenProvider` (required) -- handles actual token acquisition (browser OAuth, client credentials, etc.)
+
+It also produces `ITokenRefresher` instances that are injected into `JwtAbapConnection` for transparent token renewal on 401/403 responses.
+
+---
+
+### 2.6 @mcp-abap-adt/auth-providers
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Concrete token acquisition strategies |
+| **Public interface** | `ITokenProvider` (from interfaces package) |
+| **Default implementations** | `AuthorizationCodeProvider`, `ClientCredentialsProvider`, `DeviceFlowProvider`, `OidcBrowserProvider`, `OidcDeviceFlowProvider`, `OidcPasswordProvider`, `OidcTokenExchangeProvider`, `Saml2BearerProvider`, `Saml2PureProvider` |
+| **Replaceable** | Yes -- any `ITokenProvider` implementation |
+| **Runtime role** | Injected into `AuthBroker` to perform specific OAuth2/OIDC/SAML flows |
+| **Dependencies** | `@mcp-abap-adt/interfaces`, `axios`, `express`, `open` |
+
+All providers extend `BaseTokenProvider` which manages token caching, expiration tracking, and the `getTokens()` lifecycle. Each provider implements a specific grant type:
+
+| Provider | Grant Type | Use Case |
+|:---|:---|:---|
+| `AuthorizationCodeProvider` | `authorization_code` | Interactive browser-based BTP auth |
+| `ClientCredentialsProvider` | `client_credentials` | Machine-to-machine, no user context |
+| `DeviceFlowProvider` | `device_code` | Devices without browser |
+| `OidcBrowserProvider` | OIDC + browser | Generic OIDC with browser |
+| `OidcDeviceFlowProvider` | OIDC + device | Generic OIDC without browser |
+| `OidcPasswordProvider` | `password` | Resource owner password (legacy) |
+| `OidcTokenExchangeProvider` | `token_exchange` | Token exchange flows |
+| `Saml2BearerProvider` | `saml2_bearer` | SAML2 bearer assertion |
+| `Saml2PureProvider` | Pure SAML | Direct SAML authentication |
+
+---
+
+### 2.7 @mcp-abap-adt/connection
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | HTTP transport layer to SAP ADT REST API |
+| **Public interface** | `IAbapConnection` |
+| **Default implementations** | `BaseAbapConnection` (Basic auth), `JwtAbapConnection` (JWT/BTP), `SamlAbapConnection` (SAML) |
+| **Replaceable** | Yes -- any `IAbapConnection` implementation |
+| **Runtime role** | Executes HTTP requests against SAP ADT endpoints |
+| **Dependencies** | `@mcp-abap-adt/interfaces`, `axios` |
+
+**Factory function:**
+
+```typescript
+createAbapConnection(config: SapConfig, logger?: ILogger, sessionId?: string, tokenRefresher?: ITokenRefresher): IAbapConnection
+```
+
+Automatically selects the correct implementation based on `config.authType` (`basic`, `jwt`, or `saml`).
+
+**Key capabilities:**
+- CSRF token management (automatic fetch, cache, refresh on error)
+- Stateful/stateless session switching via `sap-contextid` headers
+- Cookie management for session persistence
+- Automatic token refresh on 401/403 via injected `ITokenRefresher`
+- TLS configuration respecting `NODE_TLS_REJECT_UNAUTHORIZED`
+- Retry logic for transient errors
+
+---
+
+### 2.8 @mcp-abap-adt/adt-clients
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Domain logic for ABAP object CRUD operations |
+| **Public interface** | `IAdtObject<TConfig, TState>` per object type |
+| **Default implementation** | `AdtClient` (factory), 22+ object-type handlers |
+| **Replaceable** | Yes -- via interface |
+| **Runtime role** | Called by MCP tool handlers to perform SAP operations |
+| **Dependencies** | `@mcp-abap-adt/interfaces`, `@mcp-abap-adt/logger`, `fast-xml-parser` |
+
+**AdtClient** is a factory that creates typed object handlers:
+
+```typescript
+const client = new AdtClient(connection, logger);
+const program = client.getProgram();     // → IAdtObject<IProgramConfig, IProgramState>
+const cls = client.getClass();           // → IAdtObject<IClassConfig, IClassState>
+const func = client.getFunctionModule(); // → IAdtObject<IFunctionModuleConfig, IFunctionModuleState>
+```
+
+**Supported ABAP object types** (22+): Class, Program, Interface, Domain, DataElement, Structure, Table, TableType, View, FunctionGroup, FunctionModule, Package, ServiceDefinition, BehaviorDefinition, BehaviorImplementation, MetadataExtension, Enhancement, UnitTest, CdsUnitTest, Transport Request, LocalDefinitions, LocalTypes, LocalMacros, LocalTestClass.
+
+**Operation chains** -- create and update operations are multi-step sequences:
+
+```
+Create: validate → create → check → lock → update → unlock → check → activate (optional)
+Update: lock → check → update → unlock → check → activate (optional)
+Delete: check(deletion) → delete
+Read:   single GET request
+```
+
+Each step accumulates results in `TState`, providing full audit trail of the operation.
+
+**AdtUtils** provides cross-cutting utilities: repository search, where-used analysis, package hierarchy traversal, table content queries, inactive object lists, and batch operations.
+
+---
+
+### 2.9 mcp-abap-adt (Main MCP Server)
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | MCP protocol adapter -- translates MCP tool calls into ADT client operations |
+| **Runtime role** | Primary application entry point; composition root |
+| **Transport modes** | `stdio`, `streamable-http`, `sse` |
+| **Dependencies** | All packages above + `@modelcontextprotocol/sdk`, `zod` |
+
+#### Composition Root
+
+`src/server/launcher.ts` is the composition root where all dependencies are wired:
+
+```
+launcher.ts main()
+  ├── ServerConfigManager.getConfig()         // CLI args, YAML, env vars
+  ├── Create handler groups (by exposition)   // ReadOnly, HighLevel, LowLevel, Search, System
+  ├── CompositeHandlersRegistry(groups)       // Aggregate registry
+  ├── AuthBrokerFactory                       // Per-destination auth broker management
+  └── Transport server (Stdio|Http|Sse)       // Start appropriate transport
+```
+
+#### Handler Architecture
+
+Handlers are organized into groups by access level:
+
+| Group | Purpose | Typical Tool Count |
+|:---|:---|:---|
+| `ReadOnlyHandlersGroup` | Get operations (read source, metadata) | ~10 |
+| `HighLevelHandlersGroup` | Full CRUD (Create, Update, Delete, Get) | ~90 |
+| `LowLevelHandlersGroup` | Fine-grained (lock, unlock, activate, validate) | ~40 |
+| `SearchHandlersGroup` | Repository search, where-used | ~5 |
+| `SystemHandlersGroup` | System info, discovery | ~3 |
+
+The `exposition` configuration controls which groups are active, enabling read-only deployments or full-access modes.
+
+**Handler registration flow:**
+
+```
+CompositeHandlersRegistry
+  └── for each IHandlerGroup:
+        └── BaseHandlerGroup.registerHandlers(server)
+              └── for each HandlerEntry:
+                    ├── Convert JSON Schema → Zod
+                    ├── Wrap handler with context injection
+                    └── server.registerTool(name, schema, wrappedHandler)
+```
+
+Each handler follows a uniform pattern:
+
+```typescript
+// Tool definition (static metadata)
+export const TOOL_DEFINITION = {
+  name: "GetProgram",
+  description: "Retrieve ABAP program source code",
+  inputSchema: { type: "object", properties: { program_name: { type: "string" } }, required: ["program_name"] }
+} as const;
+
+// Handler function (receives injected context)
+export async function handleGetProgram(context: HandlerContext, args: GetProgramArgs) {
+  const client = new AdtClient(context.connection, context.logger);
+  const result = await client.getProgram().read({ programName: args.program_name }, args.version || 'active');
+  return return_response(result);
+}
+```
+
+`HandlerContext` contains the `IAbapConnection` and optional `ILogger` -- injected per-request by `BaseMcpServer`.
+
+#### Transport Servers
+
+| Transport | Class | Connection Model | Session Management |
+|:---|:---|:---|:---|
+| stdio | `StdioServer` | Cached (one per server lifetime) | Single persistent session |
+| HTTP | `StreamableHttpServer` | Per-request (new server instance) | Stateless |
+| SSE | `SseServer` | Per-connection | Map by session ID |
+
+All transports extend `BaseMcpServer` which handles handler registration, connection context management, and per-request context injection.
+
+---
+
+### 2.10 @mcp-abap-adt/proxy (Auxiliary Utility)
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Authorization proxy between MCP clients and remote MCP servers on BTP |
+| **Architectural relationship** | Fully independent -- can proxy to ANY MCP server, not just mcp-abap-adt |
+| **Runtime role** | Intercepts requests, obtains JWT via XSUAA, forwards authenticated requests |
+| **Transport modes** | `stdio`, `streamable-http`, `sse` |
+| **Dependencies** | `@mcp-abap-adt/auth-broker`, `@mcp-abap-adt/auth-providers`, `@mcp-abap-adt/auth-stores`, `@mcp-abap-adt/interfaces`, `@modelcontextprotocol/sdk`, `axios` |
+
+The proxy is **not** part of the main server's runtime. It is a standalone utility for scenarios where MCP clients (Cline, Copilot, Cursor) cannot perform BTP authentication directly.
+
+**Key capabilities:**
+- JWT token management with 30-minute cache TTL
+- Multi-destination support (per-destination auth brokers)
+- Circuit breaker pattern for resilience
+- Retry with exponential backoff
+- Service key-based MCP server URL discovery
+- Request/response logging with sensitive data redaction
+- Eager authentication (browser opens on startup for stdio mode)
+
+---
+
+### 2.11 @mcp-abap-adt/configurator (Auxiliary Utility)
+
+| Attribute | Value |
+|:---|:---|
+| **Responsibility** | Automates MCP server registration in client configuration files |
+| **Architectural relationship** | Fully independent -- no runtime dependency on any other package |
+| **Supported clients** | Cline, Claude, Codex, Cursor, Copilot, Goose, Windsurf, OpenCode, Antigravity, Qwen, Crush (11 total) |
+| **Operations** | add, rm, ls, show, enable, disable, where, update, tui |
+
+A pure CLI/TUI tool that handles platform-specific and client-specific configuration file formats (JSON, YAML, TOML) across global and project scopes.
+
+---
+
+## 3. Submodule Clarification
+
+Each package is an **independent git repository** with its own version, build pipeline, test suite, and npm publication. For development convenience, packages can be aggregated using **git submodules**:
+
+```
+mcp-abap-adt/              ← Own git repo, published to npm
+mcp-abap-adt-interfaces/   ← Own git repo, published to npm
+mcp-abap-adt-clients/      ← Own git repo, published to npm
+mcp-abap-connection/       ← Own git repo, published to npm
+...                        ← Each package is independent
+```
+
+**Critical distinction:**
+
+- **Submodules are purely administrative** -- they enable synchronized development and convenient cross-package navigation, but are not required
+- **Architectural isolation remains intact** -- each package has its own `package.json`, version, build pipeline, test suite, and npm publication
+- **Submodule grouping does not equal monolith** -- consuming packages individually from npm changes nothing architecturally
+- **No package references another package's source code** -- all inter-package dependencies go through npm-published interfaces
+
+---
+
+## 4. Runtime Interaction Model
+
+### 4.1 High-Level Component Interaction
+
+```mermaid
+graph TD
+    Client["MCP Client<br/>(Claude, Cline, Copilot, Cursor)"]
+    Proxy["@mcp-abap-adt/proxy<br/>(optional auth proxy)"]
+    Server["mcp-abap-adt<br/>(MCP Server)"]
+    Registry["CompositeHandlersRegistry"]
+    Handlers["Handler Groups<br/>(ReadOnly, HighLevel, LowLevel, Search, System)"]
+    AdtClients["@mcp-abap-adt/adt-clients<br/>(AdtClient factory)"]
+    Connection["@mcp-abap-adt/connection<br/>(IAbapConnection)"]
+    AuthBroker["@mcp-abap-adt/auth-broker<br/>(AuthBroker)"]
+    Providers["@mcp-abap-adt/auth-providers<br/>(ITokenProvider)"]
+    Stores["@mcp-abap-adt/auth-stores<br/>(IServiceKeyStore, ISessionStore)"]
+    SAP["SAP ABAP System<br/>(ADT REST API)"]
+
+    Client -->|"MCP protocol<br/>(stdio/http/sse)"| Proxy
+    Client -->|"MCP protocol<br/>(stdio/http/sse)"| Server
+    Proxy -->|"Authenticated HTTP"| Server
+    Server --> Registry
+    Registry --> Handlers
+    Handlers -->|"HandlerContext"| AdtClients
+    AdtClients -->|"IAbapConnection"| Connection
+    Connection -->|"HTTP/HTTPS"| SAP
+    Connection -->|"ITokenRefresher"| AuthBroker
+    AuthBroker --> Providers
+    AuthBroker --> Stores
+    Providers -->|"OAuth2/OIDC/SAML"| SAP
+```
+
+### 4.2 Request Processing Flow (HTTP Transport)
+
+```
+1. HTTP POST /mcp/stream/http
+   └── StreamableHttpServer.createRequestHandler()
+
+2. Per-request server creation
+   └── new BaseMcpServer() instance per request
+
+3. Connection context resolution
+   ├── From x-mcp-destination header → AuthBrokerFactory.getBroker(destination)
+   ├── From x-sap-url + auth headers → Direct connection params
+   └── From default destination (startup config)
+
+4. Handler invocation
+   ├── BaseMcpServer resolves tool name → handler function
+   ├── Creates HandlerContext { connection: IAbapConnection, logger: ILogger }
+   └── Calls handler(context, args)
+
+5. ADT operation execution
+   ├── Handler creates AdtClient(connection, logger)
+   ├── Calls typed operation (e.g., client.getProgram().read(...))
+   ├── AdtClient delegates to IAbapConnection.makeAdtRequest()
+   └── Connection handles auth, CSRF, retries, session
+
+6. Response
+   └── Handler returns MCP-formatted response (text content)
+```
+
+### 4.3 Inversion of Control Boundaries
+
+The system has three distinct IoC boundaries:
+
+| Boundary | What is Inverted | Composition Point |
+|:---|:---|:---|
+| **Auth** | Token acquisition strategy | `AuthBroker` constructor receives `ITokenProvider`, `ISessionStore`, `IServiceKeyStore` |
+| **Transport** | HTTP communication with SAP | `AdtClient` constructor receives `IAbapConnection` |
+| **Handlers** | Tool behavior per transport/mode | `CompositeHandlersRegistry` receives `IHandlerGroup[]` |
+
+### 4.4 Composition Root Location
+
+`mcp-abap-adt/src/server/launcher.ts` is the single composition root for the main server. It:
+
+1. Reads configuration (CLI, YAML, env)
+2. Instantiates concrete store implementations (`AbapServiceKeyStore`, `AbapSessionStore`)
+3. Creates token providers (`AuthorizationCodeProvider`)
+4. Assembles `AuthBroker` instances via `AuthBrokerFactory`
+5. Creates handler groups with `HandlerContext`
+6. Assembles `CompositeHandlersRegistry`
+7. Starts the appropriate transport server
+
+No other file in the system creates concrete cross-package dependencies.
+
+---
+
+## 5. Extensibility Model
+
+### 5.1 Replacing Default Implementations
+
+Any interface-backed component can be replaced. The general pattern:
+
+```typescript
+// 1. Implement the interface
+class CustomSessionStore implements ISessionStore {
+  async loadSession(destination: string): Promise<IConfig | null> { /* custom logic */ }
+  async saveSession(destination: string, config: IConfig): Promise<void> { /* custom logic */ }
+  async getAuthorizationConfig(destination: string): Promise<IAuthorizationConfig | null> { /* ... */ }
+  async getConnectionConfig(destination: string): Promise<IConnectionConfig | null> { /* ... */ }
+  async setAuthorizationConfig(destination: string, config: IAuthorizationConfig): Promise<void> { /* ... */ }
+  async setConnectionConfig(destination: string, config: IConnectionConfig): Promise<void> { /* ... */ }
+}
+
+// 2. Inject at composition root
+const broker = new AuthBroker({
+  sessionStore: new CustomSessionStore(),
+  tokenProvider: new AuthorizationCodeProvider(providerConfig),
+});
+```
+
+### 5.2 Custom Authentication Logic
+
+To inject a custom authentication flow:
+
+1. **Implement `ITokenProvider`** with a `getTokens()` method that returns `ITokenResult`
+2. **Pass it to `AuthBroker`** in the composition root
+3. The rest of the system remains unchanged -- `AuthBroker` will use the custom provider for token acquisition
+
+```typescript
+class CustomTokenProvider implements ITokenProvider {
+  async getTokens(): Promise<ITokenResult> {
+    // Custom token acquisition (e.g., corporate SSO, hardware token, vault)
+    return { authorizationToken: '...', authType: 'authorization_code' };
+  }
+}
+```
+
+### 5.3 Custom Configuration Handling
+
+`ServerConfigManager` supports:
+- CLI arguments (`--transport`, `--host`, `--port`, `--conf`, `--mcp`, `--env`)
+- YAML configuration files (via `--conf <path>`)
+- Environment variables (`MCP_TRANSPORT`, `MCP_HTTP_HOST`, `MCP_HTTP_PORT`)
+
+For deeper customization, consumers can bypass `ServerConfigManager` and construct `IServerConfig` directly.
+
+### 5.4 Extending MCP Tool Behavior
+
+To add new tools:
+
+1. **Create a handler** following the existing pattern (TOOL_DEFINITION + handler function)
+2. **Create a handler group** implementing `IHandlerGroup`
+3. **Register it** via `CompositeHandlersRegistry.addHandlerGroup()`
+
+```typescript
+class CustomHandlerGroup extends BaseHandlerGroup {
+  protected groupName = 'CustomHandlers';
+
+  getHandlers(): HandlerEntry[] {
+    return [
+      {
+        toolDefinition: { name: 'CustomTool', description: '...', inputSchema: { ... } },
+        handler: (context, args) => handleCustomTool(context, args),
+      },
+    ];
+  }
+}
+
+// At composition root
+registry.addHandlerGroup(new CustomHandlerGroup(baseContext));
+```
+
+### 5.5 Architectural Guarantees
+
+- **Interface stability** -- `@mcp-abap-adt/interfaces` follows semver; breaking changes require major version bumps
+- **No hidden state** -- components do not share global mutable state (except the explicit `AuthBrokerRegistry` global for cross-package token refresh)
+- **Typed errors** -- all error conditions use typed error code constants, enabling programmatic error handling
+- **Operation auditability** -- `IAdtObjectState` accumulates every operation result, providing full trace of create/update/delete chains
+
+---
+
+## 6. Developer and Consumer Perspective
+
+### 6.1 For New ABAP Developers
+
+**Recommended entry path:**
+
+1. Start with `@mcp-abap-adt/interfaces` -- read `IAdtObject<TConfig, TState>` to understand the CRUD contract
+2. Examine one object type in `@mcp-abap-adt/adt-clients` (e.g., `src/core/program/`) to see the operation chain pattern
+3. Look at the corresponding handler in `mcp-abap-adt/src/handlers/program/` to understand how MCP tool calls map to ADT operations
+4. Study `@mcp-abap-adt/connection` to understand how HTTP requests reach SAP
+
+**Key concept:** Every ABAP object type (Class, Program, Table, etc.) follows the identical pattern: `TConfig` input, `IAdtObject` interface, `TState` accumulation. Learn one, understand all.
+
+### 6.2 Typical Usage Scenarios
+
+| Scenario | Components Used | Transport |
+|:---|:---|:---|
+| Local development with Claude Code | Main server | stdio |
+| Team deployment on BTP | Main server + proxy | HTTP |
+| Read-only monitoring | Main server (exposition=readonly) | HTTP/SSE |
+| Custom IDE integration | Main server (as npm dependency) | Embedded via `EmbeddableMcpServer` |
+| Multi-system landscape | Main server + proxy (multi-destination) | HTTP |
+
+### 6.3 SAP Consultant Integration
+
+Consultants working with customer systems typically:
+
+1. Use `@mcp-abap-adt/configurator` to set up their MCP client
+2. Configure service keys for BTP systems or basic auth for on-premise
+3. Deploy the proxy for team-shared access with centralized auth
+4. Control tool exposure via `exposition` config (readonly for auditing, full for development)
+
+### 6.4 Support Usage Patterns
+
+For troubleshooting:
+
+- Enable debug logging: `AUTH_LOG_LEVEL=debug` or `DEBUG_AUTH_LOG=true`
+- Token flow diagnostics: `AuthBroker` logs every step of the acquisition flow
+- Connection diagnostics: `AbstractAbapConnection` logs CSRF operations, retries, and session state
+- Handler diagnostics: Each handler logs operation parameters and error details
+- All sensitive data (tokens, passwords, secrets) is redacted in log output
+
+---
+
+## 7. Architecture Validation
+
+### 7.1 Architecture Style Classification
+
+**Primary style:** Component-based architecture with dependency injection
+
+**Supporting patterns:**
+- Factory pattern (`AdtClient`, `createAbapConnection`, `AuthBrokerFactory`)
+- Strategy pattern (`ITokenProvider` implementations selected at composition time)
+- Composite pattern (`CompositeHandlersRegistry` aggregates `IHandlerGroup[]`)
+- Chain of Responsibility (operation chains in `IAdtObject` implementations)
+- Template Method (`BaseTokenProvider`, `AbstractAbapConnection`, `BaseHandlerGroup`)
+
+### 7.2 Coupling Assessment
+
+| Coupling Type | Level | Evidence |
+|:---|:---|:---|
+| Interface coupling | Low | All cross-package communication through interfaces |
+| Data coupling | Low | Well-defined DTOs (`IConfig`, `ITokenResult`, `IAdtResponse`) |
+| Runtime coupling | Medium | `AuthBrokerRegistry` global for cross-package token refresh |
+| Temporal coupling | Low | No implicit ordering between components (explicit operation chains only) |
+| Build coupling | None | Each package builds independently |
+
+### 7.3 Replaceability Assessment
+
+| Component | Replaceability | Effort |
+|:---|:---|:---|
+| Logger | Full | Implement 4-method `ILogger` interface |
+| Session Store | Full | Implement `ISessionStore` (6 methods) |
+| Service Key Store | Full | Implement `IServiceKeyStore` (3 methods) |
+| Token Provider | Full | Implement `ITokenProvider` (1-2 methods) |
+| Connection | Full | Implement `IAbapConnection` (4 methods) |
+| Handler Groups | Full | Implement `IHandlerGroup` (3 methods) |
+| Auth Broker | Moderate | Replace `AuthBroker` class (non-interface, but clear method contract) |
+| Transport Server | Moderate | Extend `BaseMcpServer` and implement transport-specific logic |
+
+### 7.4 Strengths
+
+- **Strict interface isolation** prevents accidental coupling between packages
+- **Multi-auth strategy** supports Basic, JWT, SAML, OIDC, device flow -- covering on-premise through BTP cloud
+- **Operation chain model** provides atomic, auditable CRUD sequences with automatic lock/unlock
+- **Exposition control** enables deployment profiles (read-only, full CRUD, low-level)
+- **Transport flexibility** (stdio, HTTP, SSE) adapts to different client architectures
+- **22+ ABAP object types** with uniform interface -- broad coverage with consistent API
+
+### 7.5 Risks
+
+| Risk | Mitigation |
+|:---|:---|
+| `AuthBrokerRegistry` global state could cause conflicts in multi-tenant scenarios | Scoped to destination key; documented as known limitation |
+| Large handler count (~150 tools) may overwhelm AI model context | `exposition` config limits visible tools per deployment |
+| XML parsing of ADT responses is fragile across SAP versions | `fast-xml-parser` with per-object-type parsers; integration tests validate against real systems |
+| Service key files stored on filesystem | Configurable directory; `unsafe` flag controls file vs. in-memory storage |
+
+### 7.6 Recommendations
+
+1. **For new contributors:** Follow the existing handler pattern exactly -- tool definition + handler function + handler group registration. Do not introduce new cross-package dependencies.
+2. **For custom deployments:** Start with the `exposition` config and `EmbeddableMcpServer` before building custom infrastructure.
+3. **For enterprise adoption:** Use the proxy for centralized BTP authentication and the configurator for standardized client setup across teams.
+4. **For extending object type support:** Add a new module under `@mcp-abap-adt/adt-clients/src/core/{type}/` following the established pattern (types, CRUD functions, `IAdtObject` implementation).
+
+---
+
+## Appendix: Dependency Hierarchy
+
+```
+@mcp-abap-adt/interfaces (base -- no dependencies)
+│
+├── @mcp-abap-adt/logger
+│
+├── @mcp-abap-adt/header-validator
+│
+├── @mcp-abap-adt/auth-stores
+│
+├── @mcp-abap-adt/connection
+│   └── @mcp-abap-adt/adt-clients
+│
+├── @mcp-abap-adt/auth-providers
+│
+├── @mcp-abap-adt/auth-broker
+│
+└── mcp-abap-adt (main server -- composition root, consumes all)
+    ├── Depends on all packages above
+    └── @modelcontextprotocol/sdk
+
+@mcp-abap-adt/proxy (independent auxiliary -- uses auth-broker, auth-stores, auth-providers)
+
+@mcp-abap-adt/configurator (independent auxiliary -- no runtime deps on other packages)
+```