arc-1 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Alice Vinogradova and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# arc1 — SAP ADT MCP Server
+
+**ARC-1 (ABAP Relay Connector) — Enterprise-ready proxy between AI clients and SAP systems.**
+
+arc1 is a TypeScript MCP server (distributed as an npm package and Docker image) that implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) and translates AI tool calls into [SAP ABAP Development Tools (ADT)](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/about-abap-development-tools) REST API requests. It works with Claude, GitHub Copilot, VS Code, and any MCP-compatible client.
+
+> **This repository** ([marianfoo/arc-1](https://github.com/marianfoo/arc-1)) is the actively maintained fork, continued from the original [oisee/vibing-steampunk](https://github.com/oisee/vibing-steampunk).
+
+![Vibing ABAP Developer](./media/vibing-steampunk.png)
+
+## Why arc1?
+
+| | [abap-adt-api](https://github.com/marcellourbani/abap-adt-api) | [mcp-abap-adt](https://github.com/mario-andreschak/mcp-abap-adt) | **arc1** |
+|---|:---:|:---:|:---:|
+| npm package + Docker image | — | — | **Y** |
+| Read-only mode / package whitelist | — | — | **Y** |
+| Transport controls (CTS safety) | — | — | **Y** |
+| HTTP Streamable transport (Copilot Studio) | — | — | **Y** |
+| 11 intent-based tools (~5K schema tokens) | — | — | **Y** |
+| Method-level read/edit (95% token reduction) | — | — | **Y** |
+| Context compression (7–30x) | — | — | **Y** |
+| Works with 8+ MCP clients | — | — | **Y** |
+
+As an **admin**, you control what the AI can and cannot do:
+- Restrict to read-only, specific packages, or whitelisted operations
+- Require transport assignments before any write
+- Block free-form SQL execution
+- Allow or deny individual operation types per deployment
+
+## Quick Start
+
+```bash
+# Run directly with npx (no install needed)
+npx arc-1 --url https://your-sap-host:44300 --user YOUR_USER
+
+# Or install globally
+npm install -g arc-1
+arc1 --url https://your-sap-host:44300 --user YOUR_USER
+
+# Or use Docker
+docker run -e SAP_URL=https://host:44300 -e SAP_USER=dev -e SAP_PASSWORD=secret \
+  ghcr.io/marianfoo/arc-1
+```
+
+## Connect Your Client
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sap": {
+      "command": "npx",
+      "args": ["-y", "arc-1"],
+      "env": {
+        "SAP_URL": "https://your-sap-host:44300",
+        "SAP_USER": "your-username",
+        "SAP_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add `.mcp.json` to your project root:
+
+```json
+{
+  "mcpServers": {
+    "sap": {
+      "command": "npx",
+      "args": ["-y", "arc-1"],
+      "env": {
+        "SAP_URL": "https://your-sap-host:44300",
+        "SAP_USER": "your-username",
+        "SAP_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot / VS Code (HTTP Streamable)
+
+Start arc1 as an HTTP server, then point your MCP client to it:
+
+```bash
+SAP_URL=https://host:44300 SAP_USER=dev SAP_PASSWORD=secret \
+  npx arc-1 --transport http-streamable --port 3000
+```
+
+Add to VS Code / Copilot MCP config:
+
+```json
+{
+  "mcpServers": {
+    "sap": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+HTTP Streamable is also the transport for **Copilot Studio** (Microsoft Power Platform integrations).
+
+### Other MCP Clients (Gemini CLI, OpenCode, Goose, Qwen, …)
+
+All MCP clients that support stdio work out of the box — just point them at `npx arc-1`.
+
+## Tools
+
+arc1 exposes 11 intent-based tools (~5K schema tokens):
+
+| Tool | What it does |
+|------|-------------|
+| **SAPRead** | Read ABAP source, table data, CDS views, message classes, class info |
+| **SAPSearch** | Find objects by name with wildcards |
+| **SAPWrite** | Create/update ABAP source code with auto lock/unlock |
+| **SAPActivate** | Activate (publish) ABAP objects |
+| **SAPNavigate** | Go-to-definition, find references, code completion |
+| **SAPQuery** | Execute ABAP SQL queries against SAP tables |
+| **SAPTransport** | CTS transport management (list, create, release) |
+| **SAPContext** | Compressed dependency context for LLM efficiency |
+| **SAPLint** | ABAP lint and code quality checks |
+| **SAPDiagnose** | Runtime errors (short dumps), profiler traces, SQL traces |
+| **SAPManage** | System feature probing and status |
+
+Full tool reference: **[docs/tools.md](docs/tools.md)**
+
+## Token Efficiency
+
+**Method-level surgery** — read or edit a single method, not the whole class:
+
+```
+SAPRead(type="CLAS", name="ZCL_CALCULATOR", include="implementations")
+SAPWrite(action="update", type="CLAS", name="ZCL_CALCULATOR", source="...")
+```
+
+Up to 20x fewer tokens vs full-class round-trips.
+
+**Context compression** — `SAPContext` auto-appends public API signatures of all referenced classes and interfaces (7–30x compression). One call = source + full dependency context.
+
+## Admin Controls (Safety)
+
+Configure what the AI is allowed to do before deployment:
+
+```bash
+# Read-only mode — no writes at all
+arc1 --read-only
+
+# Restrict to specific packages (wildcards supported)
+arc1 --allowed-packages "ZPROD*,$TMP"
+
+# Block free-form SQL
+arc1 --block-free-sql
+
+# Whitelist operation types (R=Read, S=Search, Q=Query, …)
+arc1 --allowed-ops "RSQ"
+```
+
+Full safety reference:
+
+| Flag / Env | Default | Effect |
+|---|:---:|---|
+| `--read-only` / `SAP_READ_ONLY` | false | Block all write operations |
+| `--block-free-sql` / `SAP_BLOCK_FREE_SQL` | false | Block `RunQuery` execution |
+| `--allowed-ops` / `SAP_ALLOWED_OPS` | (all) | Whitelist operation types |
+| `--disallowed-ops` / `SAP_DISALLOWED_OPS` | (none) | Blacklist operation types |
+| `--allowed-packages` / `SAP_ALLOWED_PACKAGES` | (all) | Restrict to packages (wildcards: `Z*,$TMP`) |
+
+## Configuration
+
+Priority order: CLI flags > environment variables > `.env` file > defaults.
+
+```bash
+# Basic
+arc1 --url https://host:44300 --user admin --password secret
+
+# Cookie auth (SSO / Fiori Launchpad)
+arc1 --url https://host:44300 --cookie-file cookies.txt
+```
+
+Full configuration reference: **[CLAUDE.md](CLAUDE.md#configuration)**
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [docs/architecture.md](docs/architecture.md) | System architecture with Mermaid diagrams |
+| [docs/tools.md](docs/tools.md) | Complete tool reference (11 intent-based tools) |
+| [docs/mcp-usage.md](docs/mcp-usage.md) | AI agent usage guide & workflow patterns |
+| [docs/sap-trial-setup.md](docs/sap-trial-setup.md) | SAP BTP trial setup |
+| [docs/docker.md](docs/docker.md) | Docker deployment |
+| [docs/roadmap.md](docs/roadmap.md) | Planned features |
+| [CLAUDE.md](CLAUDE.md) | AI development guidelines (codebase structure, patterns) |
+
+## Development
+
+```bash
+npm ci                    # install dependencies
+npm run build             # TypeScript → dist/
+npm test                  # unit tests (no SAP system required)
+npm run test:integration  # integration tests (skipped if no SAP vars set)
+```
+
+See [CLAUDE.md](CLAUDE.md) for codebase structure and contribution guidelines.
+
+## Credits
+
+| Project | Author | Contribution |
+|---------|--------|--------------|
+| [abap-adt-api](https://github.com/marcellourbani/abap-adt-api) | Marcello Urbani | TypeScript ADT library, definitive API reference |
+| [mcp-abap-adt](https://github.com/mario-andreschak/mcp-abap-adt) | Mario Andreschak | First MCP server for ABAP ADT |
+| [abaplint](https://github.com/abaplint/abaplint) | Lars Hvam | ABAP parser/linter (used via @abaplint/core) |
+
+## License
+
+MIT

package/bin/arc1.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+// ARC-1 — ABAP Relay Connector
+// CLI entry point — delegates to compiled TypeScript
+//
+// Why a thin JS wrapper instead of direct dist/ reference:
+// The MCP SDK's stdio transport requires the entry process to own stdin/stdout.
+// Using a direct require() (not spawn) ensures no intermediate process layer
+// that could interfere with the JSON-RPC stream.
+// (Learned from fr0ster/mcp-abap-adt bin/mcp-abap-adt.js)
+
+import('../dist/index.js');

package/dist/adt/btp.d.ts

@@ -0,0 +1,122 @@
+/**
+ * BTP Destination Service integration for ARC-1.
+ *
+ * When running on SAP BTP Cloud Foundry, this module:
+ * 1. Parses VCAP_SERVICES to extract service binding credentials
+ * 2. Fetches SAP connection details from the BTP Destination Service
+ * 3. Configures an HTTP proxy through the Cloud Connector (Connectivity Service)
+ *
+ * The flow mirrors the Go implementation in pkg/adt/btp.go:
+ * - Parse VCAP_SERVICES → get destination/connectivity/xsuaa credentials
+ * - Call Destination Service API → get SAP URL, user, password
+ * - Create axios proxy config → route through Cloud Connector
+ * - Inject Proxy-Authorization header → connectivity service JWT token
+ *
+ * Token caching: Both destination and connectivity tokens are cached
+ * and refreshed 60 seconds before expiry to avoid request failures.
+ */
+/** BTP service binding credentials parsed from VCAP_SERVICES */
+export interface BTPConfig {
+    xsuaaUrl: string;
+    xsuaaClientId: string;
+    xsuaaSecret: string;
+    destinationUrl: string;
+    destinationClientId: string;
+    destinationSecret: string;
+    destinationTokenUrl: string;
+    connectivityProxyHost: string;
+    connectivityProxyPort: string;
+    connectivityClientId: string;
+    connectivitySecret: string;
+    connectivityTokenUrl: string;
+}
+/** Resolved destination from BTP Destination Service */
+export interface Destination {
+    Name: string;
+    URL: string;
+    Authentication: string;
+    ProxyType: string;
+    User: string;
+    Password: string;
+    'sap-client'?: string;
+}
+/** Proxy configuration for axios — used by AdtHttpClient */
+export interface BTPProxyConfig {
+    host: string;
+    port: number;
+    protocol: string;
+    /** Returns a fresh connectivity proxy JWT token (cached, auto-refreshed) */
+    getProxyToken: () => Promise<string>;
+}
+/**
+ * Parse VCAP_SERVICES environment variable to extract BTP service credentials.
+ * Returns null if not running on BTP (VCAP_SERVICES not set).
+ */
+export declare function parseVCAPServices(): BTPConfig | null;
+/**
+ * Look up a destination from the BTP Destination Service.
+ * Returns SAP URL, credentials, and proxy type.
+ */
+export declare function lookupDestination(btpConfig: BTPConfig, destinationName: string): Promise<Destination>;
+/**
+ * Create a proxy configuration for routing through the Cloud Connector.
+ *
+ * Returns a BTPProxyConfig with a token getter that caches the connectivity
+ * JWT and auto-refreshes it 60 seconds before expiry.
+ */
+export declare function createConnectivityProxy(btpConfig: BTPConfig): BTPProxyConfig | null;
+/**
+ * Per-user authentication tokens returned by Destination Service
+ * when called with X-User-Token header.
+ *
+ * For PrincipalPropagation destinations, the Destination Service
+ * generates a SAML assertion containing the user identity and returns
+ * it as the SAP-Connectivity-Authentication header value.
+ */
+export interface PerUserAuthTokens {
+    /** SAP-Connectivity-Authentication header value (SAML assertion for Cloud Connector) */
+    sapConnectivityAuth?: string;
+    /** Any Bearer token returned by the Destination Service */
+    bearerToken?: string;
+    /** PP Option 1: jwt-bearer exchanged token for Proxy-Authorization (recommended approach) */
+    ppProxyAuth?: string;
+}
+/**
+ * Look up a destination with the user's JWT token for principal propagation.
+ *
+ * This is the key API for per-user SAP authentication:
+ * 1. Caller passes the user's JWT (from XSUAA/OIDC)
+ * 2. Destination Service validates the JWT and generates auth tokens
+ * 3. For PrincipalPropagation destinations: returns SAP-Connectivity-Authentication header
+ * 4. For OAuth2SAMLBearerAssertion destinations: returns a Bearer token
+ *
+ * The returned tokens are per-user and typically valid for 5-10 minutes.
+ *
+ * Reference: SAP Destination Service REST API "Find Destination" endpoint
+ * https://api.sap.com/api/SAP_CP_CF_Connectivity_Destination/resource/Find_a_Destination
+ */
+export declare function lookupDestinationWithUserToken(btpConfig: BTPConfig, destinationName: string, userJwt: string): Promise<{
+    destination: Destination;
+    authTokens: PerUserAuthTokens;
+}>;
+/**
+ * Resolve BTP destination and connectivity proxy.
+ * Called on startup when SAP_BTP_DESTINATION env var is set.
+ *
+ * Returns the resolved SAP connection config to override defaults.
+ */
+export declare function resolveBTPDestination(destinationName: string): Promise<{
+    url: string;
+    username: string;
+    password: string;
+    client: string;
+    proxy: BTPProxyConfig | null;
+}>;
+/**
+ * Get the app's public URL from VCAP_APPLICATION.
+ *
+ * CF sets VCAP_APPLICATION with application_uris containing the app's
+ * public route. Returns the first URI as an https URL.
+ */
+export declare function getAppUrl(): string | undefined;
+//# sourceMappingURL=btp.d.ts.map

package/dist/adt/btp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"btp.d.ts","sourceRoot":"","sources":["../../ts-src/adt/btp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,gEAAgE;AAChE,MAAM,WAAW,SAAS;IAExB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IAGpB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAG5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACtC;AAeD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,SAAS,GAAG,IAAI,CAgEpD;AAkCD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA8B3G;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,cAAc,GAAG,IAAI,CA2BnF;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,SAAS,EACpB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,WAAW,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,iBAAiB,CAAA;CAAE,CAAC,CAsMtE;AAID;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CAC9B,CAAC,CAgBD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAc9C"}