@linkup-ai/abap-ai 2.0.0

package/README.md

@@ -0,0 +1,384 @@
+# abap-mcp-server
+
+MCP (Model Context Protocol) Server that connects [Claude Code](https://claude.ai/code) to any SAP S/4HANA system via the ABAP Development Tools (ADT) REST API.
+
+Once configured, Claude can read, write, create, activate, search, refactor, test and deploy ABAP objects — including RAP/Fiori stacks — directly from your editor without any manual SAP GUI interaction.
+
+**55 tools** covering the full ABAP development lifecycle, powered by a **curated knowledge base** with 49 reference guides on ABAP, CDS, RAP, Fiori and CAP.
+
+---
+
+## Tools
+
+### Core ABAP Operations
+
+| Tool | Description |
+|------|-------------|
+| `abap_read` | Read source code of any ABAP object (supports class includes). For tables and structures, returns field list with types and descriptions |
+| `abap_write` | Write source code to an existing ABAP object |
+| `abap_create` | Create a new ABAP object (programs, classes, CDS views, BDEFs, SRVDs, SRVBs, etc.) |
+| `abap_activate` | Activate an object — returns syntax errors on failure |
+| `abap_check` | Check syntax without activating |
+| `abap_delete` | Delete an ABAP object (irreversible, requires transport for non-local) |
+| `abap_search` | Search objects by name with wildcard support (`*`) |
+| `abap_where_used` | List all objects that reference a given object |
+
+### Code Intelligence
+
+| Tool | Description |
+|------|-------------|
+| `abap_code_completion` | Code completion proposals at a specific position (autocomplete) |
+| `abap_navigate` | Go to Definition — navigate to the definition of a code element |
+| `abap_call_hierarchy` | Call hierarchy — who calls / who is called by a method or function |
+| `abap_element_info` | Get type info, signature and parameters for a code element at a specific position |
+| `abap_quick_fix` | List and apply quick fixes for errors/warnings in ABAP code |
+| `abap_object_structure` | List methods, attributes and interfaces of a class or interface |
+| `abap_doc` | Read ABAP Doc inline documentation for classes/methods |
+| `abap_object_documentation` | Read technical documentation of any SAP object |
+
+### Refactoring
+
+| Tool | Description |
+|------|-------------|
+| `abap_refactor_rename` | Rename a symbol (variable, method, attribute) across all references |
+| `abap_extract_method` | Extract a code selection into a new method (Extract Method refactoring) |
+| `abap_pretty_printer` | Format ABAP source code using SAP Pretty Printer |
+
+### Testing & Quality
+
+| Tool | Description |
+|------|-------------|
+| `abap_unit_test` | Run ABAP Unit tests and return results (pass/fail with details) |
+| `abap_code_coverage` | Run ABAP Unit tests with code coverage (statement-level) |
+| `abap_atc_check` | Run ATC (ABAP Test Cockpit) checks — returns findings with priority and line |
+
+### Data & SQL
+
+| Tool | Description |
+|------|-------------|
+| `abap_data_preview` | Preview data from tables or CDS views with optional WHERE, ORDER BY and column selection |
+| `abap_sql_console` | Execute arbitrary ABAP SQL (Open SQL) queries and return tabular results |
+
+### Transport Management
+
+| Tool | Description |
+|------|-------------|
+| `abap_list_transports` | List open transport requests for a user |
+| `abap_assign_transport` | Assign an existing object to a transport request |
+| `abap_create_transport` | Create a new transport request (workbench or customizing) |
+| `abap_transport_contents` | Read detailed contents of a transport request (objects, tasks, owner) |
+| `abap_release_transport` | Release a transport request (irreversible) |
+
+### CDS & Annotations
+
+| Tool | Description |
+|------|-------------|
+| `abap_cds_annotations` | List available CDS annotation definitions in the system |
+| `abap_cds_dependencies` | Dependency graph of a CDS view (what it uses and what uses it) |
+| `abap_annotation_propagation` | Check how CDS annotations propagate through the view stack |
+
+### RAP & Fiori
+
+| Tool | Description |
+|------|-------------|
+| `abap_scaffold_rap` | Create a full RAP stack with 4 scenarios: `managed` (basic), `managed_draft` (complete with draft, projections, DDLX), `unmanaged` (BAPI wrapping), `query` (custom entity) |
+| `abap_create_dcl` | Create a DCL (Data Control Language) access control object with PFCG auth, user aspect, or literal conditions |
+| `abap_create_amdp` | Create an AMDP class (procedure or table function) with SQLScript boilerplate |
+| `abap_publish_binding` | Publish a Service Binding to SAP Gateway (OData V4/V2) |
+| `abap_deploy_bsp` | Deploy a Fiori/UI5 app folder to BSP in the ABAP Repository |
+
+### DDIC & Object Types
+
+| Tool | Description |
+|------|-------------|
+| `abap_enhancement_spot` | Read enhancement spots and implementations (BAdIs, enhancement points) |
+| `abap_lock_object` | Read lock object (enqueue) definition — tables, parameters, lock mode |
+| `abap_auth_object` | Read authorization object definition — fields and check indicators |
+| `abap_number_range` | Read number range configuration — intervals, internal/external |
+| `abap_package_contents` | List all objects inside an ABAP package |
+| `abap_object_versions` | Get version history of an object (version, date, author) |
+| `abap_function_group` | List all function modules in a function group |
+| `abap_message_class` | Read all messages from a message class (T100) |
+
+### System & Repository
+
+| Tool | Description |
+|------|-------------|
+| `abap_system_info` | Auto-detect SAP system type, version, capabilities and quirks |
+| `abap_discovery` | List all ADT APIs and object types supported by the SAP system |
+| `abap_released_apis` | List released APIs (C1 contract) — essential for BTP/Cloud ABAP |
+| `abap_repository_tree` | Navigate the SAP repository tree (software components, packages) |
+
+### abapGit Integration
+
+| Tool | Description |
+|------|-------------|
+| `abap_git_repos` | List abapGit repositories linked to the SAP system |
+| `abap_git_pull` | Pull from an abapGit repository (import from Git to ABAP) |
+| `abap_git_stage` | Show staging status and push to an abapGit repository |
+
+### Debugging & Traces (Experimental)
+
+| Tool | Description |
+|------|-------------|
+| `abap_traces` | List and create ABAP traces (SAT/runtime analysis) for performance analysis |
+| `abap_breakpoints` | Manage external breakpoints (list/set/remove) |
+
+### Knowledge Base
+
+| Tool | Description |
+|------|-------------|
+| `abap_knowledge` | Curated reference guides for ABAP, CDS, RAP, Fiori and CAP — search, list and read |
+
+The knowledge base is the core differentiator of this MCP server. It provides Claude with **curated, LLM-optimized reference material** (70% code examples, 30% rules and anti-patterns) so that generated code follows best practices out of the box.
+
+**49 guides** organized in 4 domains:
+
+| Domain | Topics | Examples |
+|--------|--------|----------|
+| **ABAP Core** | 25 | Internal tables, ABAP SQL, RAP (EML, draft, feature control, numbering, unmanaged), OO, clean code, performance, unit testing, cloud development |
+| **ABAP CDS** | 6 | Annotations, associations, access control, expressions, functions, metadata extensions |
+| **Fiori / UI5** | 11 | Fiori Elements, annotations, value lists, side effects, XML views, controllers, routing, data binding, fragments, manifest, deployment |
+| **CAP (Node.js)** | 7 | CDL syntax, CQL queries, service definitions, event handlers, authentication, Fiori integration, deployment |
+
+**Three actions:**
+
+| Action | What it does | Example |
+|--------|-------------|---------|
+| `list` | Show all available topics grouped by domain | `action:'list', domain:'abap'` |
+| `search` | Keyword search with relevance scoring | `action:'search', query:'draft annotations'` |
+| `get` | Read full content of up to 5 guides | `action:'get', topics:['abap/rap-draft']` |
+
+The `abap_create` and `abap_write` tools include guidance in their descriptions nudging Claude to consult the knowledge base before generating code.
+
+---
+
+## Supported Object Types
+
+| Type | ADT Path | Description |
+|------|----------|-------------|
+| `PROG/P` | `programs/programs` | Report / Executable Program |
+| `CLAS/OC` | `oo/classes` | Global Class |
+| `FUGR/FF` | `functions/functionmodules` | Function Module |
+| `FUGR/F` | `functions/groups` | Function Group |
+| `DOMA/D` | `ddic/domains` | Domain |
+| `DTEL/D` | `ddic/dataelements` | Data Element |
+| `TABL/DT` | `ddic/tables` | Transparent Table |
+| `TABL/DS` | `ddic/structures` | Structure |
+| `TTYP/TT` | `ddic/tabletypes` | Table Type |
+| `MSAG/N` | `messageclass` | Message Class |
+| `INTF/OI` | `oo/interfaces` | Interface |
+| `DDLS/DF` | `ddic/ddl/sources` | CDS View |
+| `DDLX/MX` | `ddic/ddlx/sources` | Metadata Extension |
+| `SRVD/SRV` | `ddic/srvd/sources` | Service Definition |
+| `BDEF/BDO` | `bo/behaviordefinitions` | Behavior Definition |
+| `SRVB/SVB` | `businessservices/bindings` | Service Binding |
+| `XSLT/XT` | `transformations/xslt` | XSLT Transformation |
+| `XSLT/ST` | `transformations/simple` | Simple Transformation |
+| `ENHS/ES` | `enhancements/spots` | Enhancement Spot |
+| `ENHO/EO` | `enhancements/implementations` | Enhancement Implementation |
+| `ENQU/DL` | `ddic/lockobjects` | Lock Object |
+| `NROB/NR` | `content/numberranges` | Number Range Object |
+| `SUSO/B` | `authorization/authorizationobjects` | Authorization Object |
+
+### Reading Tables and Structures
+
+Standard SAP tables and structures (e.g. `J_1BNFDOC`, `J_1BNF_BADI_HEADER`) don't expose source code via the ADT `/source/main` endpoint. The `abap_read` tool handles this automatically:
+
+1. Tries `GET /source/main` (works for custom Z-tables in newer systems)
+2. If 404, falls back to the ADT XML metadata endpoint and parses the field definitions
+3. Returns a formatted field list with name, data type, length, and description
+
+This means you can read both custom and standard DDIC objects:
+
+```
+abap_read(object_type: "TABL/DT", object_name: "J_1BNFDOC")       → fields of a standard table
+abap_read(object_type: "TABL/DS", object_name: "J_1BNF_BADI_HEADER") → fields of a structure
+```
+
+---
+
+## Configuration
+
+The server is configured entirely via environment variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SAP_URL` | Yes | Base URL of the SAP system (e.g. `https://my-sap-host:8443`) |
+| `SAP_USER` | Yes | SAP username |
+| `SAP_PASS` | Yes | SAP password |
+| `SAP_CLIENT` | No | SAP client/mandant (default: `100`) |
+| `SAP_LANGUAGE` | No | Logon language (default: `PT`) |
+| `SAP_SYSTEM_TYPE` | No | System preset: `ON_PREMISE_S4` (default), `BTP_ABAP_ENV`, `ON_PREMISE_ECC` |
+| `SAP_TIMEOUT` | No | Request timeout in ms (default: `60000`). Increase for slow systems |
+| `NODE_TLS_REJECT_UNAUTHORIZED` | No | Set to `0` to disable SSL verification for self-signed certificates |
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+npm install -g @linkup-ai/abap-ai
+
+# 2. Activate license
+abap-ai activate LK-XXXX-XXXX-XXXX
+
+# 3. Configure SAP connection (interactive wizard)
+abap-ai init
+
+# 4. Verify
+abap-ai status
+
+# 5. Open VS Code / Claude Code → ready to use!
+```
+
+The `init` wizard tests the SAP connection, supports multiple systems (DEV, QAS, PRD), and generates `~/.claude/mcp.json` automatically.
+
+See [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) for the full step-by-step guide.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `abap-ai init` | Interactive wizard to configure SAP system connections |
+| `abap-ai activate <KEY>` | Activate product license (BYOK or All-in-One) |
+| `abap-ai status` | Show license, systems (with connection test), usage metrics and knowledge base |
+| `abap-ai systems` | List configured SAP systems |
+| `abap-ai remove <name>` | Remove a SAP system from mcp.json |
+
+### Manual Setup (alternative)
+
+If you prefer manual configuration, create `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "abap-dev": {
+      "command": "node",
+      "args": ["/path/to/abap-mcp-server/dist/index.js"],
+      "env": {
+        "SAP_URL": "https://your-sap-host:8443",
+        "SAP_CLIENT": "100",
+        "SAP_USER": "your-username",
+        "SAP_PASS": "your-password",
+        "SAP_LANGUAGE": "EN",
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+      }
+    }
+  }
+}
+```
+
+> Keep `mcp.json` in your `.gitignore` — it contains credentials.
+
+---
+
+## Deploying Fiori/UI5 Apps
+
+The `abap_deploy_bsp` tool uploads a local folder (e.g. a `dist/` build output) as a BSP application to the SAP ABAP Repository.
+
+**How it works:**
+1. Reads all files from the specified folder
+2. Creates a ZIP archive in memory
+3. Sends the ZIP (base64-encoded) to `/sap/opu/odata/UI5/ABAP_REPOSITORY_SRV/Repositories`
+4. Automatically detects if the BSP already exists (create vs update)
+
+**Example usage (via Claude):**
+> "Deploy the contents of /Users/dev/myapp/dist to BSP ZMYAPP in package $TMP"
+
+**Parameters:**
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `bsp_name` | Yes | BSP application name (max 15 chars, e.g. `ZVENDASHOJE`) |
+| `folder_path` | Yes | Absolute path to the folder with app files |
+| `package` | No | ABAP package (default: `$TMP`) |
+| `description` | No | BSP description |
+| `transport_request` | No | Transport request (required if package ≠ `$TMP`) |
+
+**After deploy, the app is available at:**
+```
+https://<sap-host>:<port>/sap/bc/ui5_ui5/sap/<bsp_name_lowercase>?sap-client=<client>
+```
+
+---
+
+## System Profile
+
+The server adapts its behavior based on the target SAP system type. A **System Profile** determines URL patterns, CDS syntax, gateway behavior, and known quirks.
+
+### Auto-detection
+
+Run `abap_system_info` (no parameters) to auto-detect the system profile. It probes ADT endpoints to determine:
+
+- **System type**: S/4HANA on-premise, BTP ABAP Environment, ECC
+- **SAP_BASIS version**: Inferred from available ADT collections
+- **ABAP platform**: Standard vs Cloud
+- **Client role**: Development, Customizing, Production
+- **Capabilities**: Code completion, call hierarchy, quick fix, extract method, code coverage, SQL console, released API catalog, abapGit
+- **Quirks**: ETag behavior, lock support, conversion exit fields
+
+### Presets
+
+Set `SAP_SYSTEM_TYPE` env var to use a preset without auto-detection:
+
+| Preset | Description |
+|--------|-------------|
+| `ON_PREMISE_S4` | S/4HANA on-premise (default) — full ADT capabilities, embedded gateway |
+| `BTP_ABAP_ENV` | BTP ABAP Environment — auto-registration, released APIs only |
+| `ON_PREMISE_ECC` | SAP ECC — limited capabilities (no CDS view entity, no RAP, no advanced refactoring) |
+
+### Profile-aware behavior
+
+| Tool | Adaptation |
+|------|-----------|
+| `abap_write` | ETag mismatch auto-retry on on-premise (extracts correct ETag from error) |
+| `abap_scaffold_rap` | Pre-checks CDS view entity support; warns about conversion exit fields |
+| `abap_publish_binding` | Pre-checks client role; skips publish on BTP (auto-registration) |
+| `abap_deploy_bsp` | Reports correct UI5 bootstrap path and OData URL for the system type |
+| `abap_sql_console` | Only available on systems with BASIS 755+ |
+| `abap_code_completion` | Available on BASIS 750+ |
+| `abap_quick_fix` | Available on BASIS 752+ |
+
+### MCP Resource
+
+The current profile is exposed as an MCP Resource at `abap://system-profile` (JSON format), giving Claude contextual awareness of the connected system.
+
+---
+
+## Authentication
+
+The server handles authentication automatically:
+
+1. On first call, performs `GET /sap/bc/adt/discovery` with `X-CSRF-Token: Fetch`
+2. Stores the session cookie and CSRF token in memory
+3. Reuses the session for all subsequent calls
+4. Automatically reconnects on HTTP 401
+
+Source writes use **ETag-based optimistic locking** (`If-Match` header) — no explicit object lock needed.
+
+---
+
+## Troubleshooting
+
+See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for a complete guide. Quick reference:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `401 Unauthorized` | Bad credentials or expired session | Check `SAP_USER`/`SAP_PASS`; auto-retry handles session expiry |
+| `SSL certificate error` | Self-signed cert | Set `NODE_TLS_REJECT_UNAUTHORIZED=0` |
+| `415 Unsupported Media Type` | SAP version too old | DDIC create needs BASIS 752+; RAP needs S/4HANA |
+| `404` on DDIC create | ECC system | DOMA/TABL/TTYP endpoints don't exist on ECC (use SE11) |
+| `409 Conflict` | Object locked | Check SM12; restart MCP server to clear stale locks |
+| `412 Precondition Failed` | ETag mismatch | Auto-handled on S/4; retry usually resolves |
+| Timeout | Slow system | Increase `SAP_TIMEOUT` (e.g. `120000` for 2 min) |
+
+### ECC Compatibility
+
+Core ABAP tools (read, write, create PROG/CLAS/INTF/FUGR, activate, check, unit test, ATC, SQL console) work on ECC (BASIS 750+). RAP/CDS/DDIC creation requires S/4HANA. See [docs/RESTRICTIONS.md](docs/RESTRICTIONS.md) for the full compatibility matrix.
+
+---
+
+## License
+
+MIT