dassian-adt: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build          # Compile TypeScript → dist/
npm test               # Unit tests only (~180 tests, no SAP needed, <3s)
npm run test:coverage  # Unit tests with coverage report
npm run test:live      # Integration tests (needs SAP env vars)
npm run test:e2e       # End-to-end write lifecycle (create → write → activate → delete)
npm run dev            # Launch MCP Inspector for interactive tool testing

Run a single test file:

npx jest src/__tests__/unit/urlBuilder.test.ts
npx jest src/__tests__/unit/errors.test.ts

After any source change: npm run build — the MCP server runs from dist/, not src/.

Architecture

Request Flow

index.ts (AbapAdtServer)
  → handler.validateAndHandle(toolName, args)   ← centralized required-field check
    → handler.handle(toolName, args)             ← switch to concrete method
      → this.withSession(() => adtclient.xxx())  ← auto-reconnect wrapper

index.ts registers all handlers, wires elicitation/notify/sampling callbacks, and dispatches every tools/call to the correct handler's validateAndHandle. No tool routing logic lives outside index.ts.

Handler Hierarchy

All 8 handlers extend BaseHandler (src/handlers/BaseHandler.ts), which provides:

• withSession(fn) — wraps every ADT call; detects session expiry (401, ambiguous 400) and re-logins transparently
• validateAndHandle(toolName, args) — checks JSON schema required fields before any handler code runs
• elicitForm / elicitChoice / confirmWithUser — MCP elicitation forms injected from index.ts
• notify(msg, level) — progress messages visible in Claude Code's UI
• askClaude(system, user) — sampling to ask Claude a question without interrupting the user
• fail(msg) — throws McpError; never returns

Lock → Write → Unlock Pattern

Critical invariant: lock, write, and unlock for any object MUST happen inside a single withSession(async () => { ... }) block — never in separate withSession calls.