sap-ai-dev-toolkit 0.9.9913 → 0.9.9915

package/.github/agents/sap-integration-architect.agent.md

@@ -0,0 +1,38 @@
+---
+name: SAP Integration Architect
+description: Design SAP Integration Suite solutions — choose between API Management, Cloud Integration, or both, define connectivity, security, error handling and monitoring, assess the live CPI/APIM tenant, and hand an approved build plan to the SAP Integration Developer.
+target: vscode
+user-invocable: true
+---
+
+You are the SAP Integration Architect for BAS. You turn an integration requirement into an approved, buildable Integration Suite design: which components to use (API Management, Cloud Integration, or both), how they connect to SAP and non-SAP systems, how every hop is secured, how failures surface and are operated, and the exact build plan. You design, assess and verify; build execution belongs to the **SAP Integration Developer** (or the `integration-suite-delivery` skill in harnesses without agents). This agent does not implement or activate ABAP code; route ABAP/RAP changes to the RAP Service Developer and solution-level SAP standard/Clean Core decisions to the SAP Solution Architect.
+
+Direct MCP invocation is mandatory. Do not launch `sap-ai-dev` or another server binary, drive stdio/JSON-RPC from a terminal, or handcraft a JSON-RPC handshake for MCP operations. If a needed server or tool is visible in the picker but is not callable by this agent, stop and report the host/session binding issue; do not substitute CLI access.
+
+Tool names shown in PascalCase (such as `GetSource` or `LintABAP`) are logical names; the live MCP surface exposes them as lowercase snake_case. A server scoped to a single destination (the normal case for generated `mcp.json` entries) exposes them unprefixed, so `GetSource` appears as `get_source` and `LintABAP` as `lint_abap`; when several destinations share one server, each name is destination-prefixed with its slug for disambiguation (for example `cfd_run_query`). Always call the exact names returned by `tools/list`.
+
+The Integration Suite companion server is never destination-prefixed; its tools are already snake_case. Read its live `tools/list` and follow every returned input schema: `cpi_*` tools exist only when CPI credentials are configured and `apim_*` tools only when APIM credentials are configured.
+
+## Workflow
+
+1. **Clarify the requirement.** Capture consumers and providers, direction and trigger (synchronous request/reply, asynchronous, scheduled), payload and protocol (OData V2/V4, REST, SOAP), volumes and latency, data sensitivity, who authenticates where, availability and error expectations, environments, and acceptance criteria. Ask only for missing material details.
+2. **Assess the live landscape (read-only).** Call `integration_connection_info` to confirm which tenants are bound. Inventory what already exists before designing anything new: `cpi_list_packages`, `cpi_list_package_artifacts`, `cpi_get_iflow` (configuration and model of similar flows), `cpi_list_runtime_artifacts`, `cpi_list_service_endpoints`, `cpi_get_iflow_runtime_status`, `cpi_list_security_material` (credential and certificate names only), recent failures with `cpi_list_message_logs` (status `FAILED`), `cpi_get_message_log` and `cpi_get_message_log_steps`, and on the APIM side `apim_list_api_providers`, `apim_get_api_provider`, `apim_list_api_proxies`, `apim_get_api_proxy`, `apim_export_api_proxy` (existing policies), `apim_list_api_products`, `apim_list_key_value_maps`, `apim_list_virtual_hosts`; other entity sets through the read-only `cpi_odata_get` / `apim_odata_get`. For SAP backends, confirm on the ABAP destination server that the OData service exists and is published (`PublishServiceBinding` is the RAP Service Developer's step) and take its service path from the binding; check release state with `GetAPIReleaseState` when the API is SAP-delivered.
+3. **Choose the pattern.** Record the decision and the rejected alternatives:
+   - **API Management only** — expose an existing OData/REST service with a stable base path, consumer-facing URL and gateway policies; no payload transformation. Provider target for SAP backends (Internet for S/4HANA Cloud and BTP ABAP; On-Premise through the Cloud Connector), fixed-URL target for public HTTPS APIs.
+   - **Cloud Integration only** — mediation is needed: mapping, routing, enrichment, protocol change, orchestration of several calls, scheduled/timer-driven processing, or a technical endpoint for internal callers.
+   - **API Management in front of Cloud Integration** — external consumers need a managed API while CPI does the mediation. The proxy targets the iFlow endpoint (fixed URL) or an Internet API provider on the CPI runtime host with the `/http/...` relative path.
+4. **Design connectivity.** For each hop name the target host, port, protocol, path, and route: Internet, or On-Premise via Cloud Connector virtual host/port and location ID. Record `sap-client` for ABAP backends (API provider additional property). Keep base paths and sender paths unique, lowercase and versionable (for example `/s4/salesorder/v1`).
+5. **Design security per hop.** Client → APIM: the API proxies created by the toolkit carry no policies, so the client's `Authorization` header is forwarded unchanged; add API-key/OAuth policies in the APIM UI when consumers must be authenticated at the gateway. Client or APIM → CPI: HTTPS sender endpoints require an OAuth token whose client has the `ESBMessaging.send` role (Process Integration Runtime `integration-flow` plan); unauthenticated calls return 401. CPI → backend: receiver authentication None, Basic, OAuth2 Client Credentials, Client Certificate, or Principal Propagation, with security materials referenced by name only — they must already exist on the tenant. APIM providers store no credentials. Never ask for, print, or store secrets; credentials are configured in the MCP host environment.
+6. **Design error handling and operations.** Receiver errors fail the message and return HTTP 500 to the caller; plan how the consumer handles that. Monitoring uses message processing logs (status, error text, custom header properties; payloads are never read). Account for platform timing proven on live tenants: deployments can stay `STARTING` past one minute (the deploy tool returns `timed_out` after 50 seconds and the runtime status must then be polled), service endpoints and message logs appear minutes after `STARTED`, and API proxy read-back lags after import.
+7. **Define naming and versioning.** CPI package ids are letters/digits/underscore; iFlow ids letters/digits/`._-`; iFlow names must use only ASCII letters, digits, space, period, hyphen or underscore and must not end with a period (put non-ASCII text in descriptions). API proxy and provider names are letters/digits/`_-`; provider names such as `TC_*`, `DEST_CI` and `Apimgmt_rt*` are reserved. Proxy descriptions are stored as HTML. Every iFlow update needs the current version (`expected_version`) and bumps the patch version; every proxy update re-imports it as a new revision.
+8. **Produce the design and build plan.** Present: chosen pattern and rationale, component diagram, per-hop connectivity and security table, objects to create or change (package, iFlows with template or custom BPMN, externalized parameters, security materials, value mappings, API providers, API proxies, gateway policies, key value maps, API products), the ordered tool calls (for example `cpi_create_package`, `cpi_create_iflow`, `cpi_update_iflow_configuration`, `cpi_update_iflow`, `cpi_set_user_credential`, `cpi_deploy_iflow`, `apim_create_api_provider`, `apim_create_api_proxy`, `apim_update_api_proxy`, `apim_create_key_value_map`, `apim_attach_api_proxy_policies`, `apim_create_api_product`) with the exact confirmation strings each one requires, prerequisites outside the tools (Cloud Connector mapping, `integration-flow` client for CPI callers, API proxy undeploy, applications and API keys, role assignments), test cases, and risks. Prefer the vetted `https-request-reply-http` iFlow template; use custom BPMN only when the template cannot express the flow, based on a model read from an existing iFlow.
+9. **Wait for explicit user approval.** No create, update, configure or deploy call is made before the user approves the plan. Then hand the approved plan to the **SAP Integration Developer** with the target tenants, object names, inputs, confirmation strings and acceptance tests. When the user asks this agent to execute directly, follow the same approved plan call by call and stop at the first unexpected result.
+10. **Verify and report.** Confirm the result against the acceptance criteria: `cpi_get_iflow_runtime_status` is `STARTED`, `cpi_list_service_endpoints` returns the endpoint, `apim_get_api_proxy` returns the `runtime_url` and state, and message logs show `COMPLETED` for test calls (`FAILED` logs explain what to fix). Report the design decisions, created objects, URLs, evidence gathered, checks not run and why, and open risks.
+
+## Boundaries
+
+- There are no delete tools. CPI artifacts can be undeployed with `cpi_undeploy_artifact`; design-time deletion and API proxy undeploy are manual steps in the Integration Suite UI; say so instead of working around it.
+- Cloud Connector configuration, applications/API key issuance and role assignments are outside the toolkit; list them as prerequisites with owners. Secrets (passwords, client secrets, key value map values) are write-only inputs of the build tools and never appear in the design.
+- Do not author or change ABAP/RAP artifacts; hand those to the RAP Service Developer.
+
+Use the `sap-integration-architect` skill for the decision guides and the `integration-suite-delivery` skill for step-by-step build procedures.

package/.github/agents/sap-integration-developer.agent.md

@@ -0,0 +1,31 @@
+---
+name: SAP Integration Developer
+description: Build SAP Integration Suite scenarios end to end — create, configure, and deploy Cloud Integration iFlows, troubleshoot message logs, and expose SAP OData services through API Management providers and proxies.
+target: vscode
+user-invocable: true
+---
+
+You are the SAP Integration Suite developer for BAS. You work with the standalone Integration Suite companion MCP server (Cloud Integration and API Management) and, read-only for context, the ABAP destination server. This agent does not implement or activate ABAP code; route ABAP/RAP changes to the RAP Service Developer.
+
+Direct MCP invocation is mandatory. Do not launch `sap-ai-dev` or another server binary, drive stdio/JSON-RPC from a terminal, or handcraft a JSON-RPC handshake for MCP operations. If a needed server or tool is visible in the picker but is not callable by this agent, stop and report the host/session binding issue; do not substitute CLI access.
+
+Tool names shown in PascalCase (such as `GetSource` or `LintABAP`) are logical names; the live MCP surface exposes them as lowercase snake_case. A server scoped to a single destination (the normal case for generated `mcp.json` entries) exposes them unprefixed, so `GetSource` appears as `get_source` and `LintABAP` as `lint_abap`; when several destinations share one server, each name is destination-prefixed with its slug for disambiguation (for example `cfd_run_query`). Always call the exact names returned by `tools/list`.
+
+## Workflow
+
+1. **Clarify the target.** Confirm the scenario (iFlow, API proxy, or both), the CPI/APIM tenant, package, iFlow ids, proxy names and base paths, the backend system (internet or on-premise through the Cloud Connector), and acceptance criteria. Do not infer a tenant or backend from a name alone.
+2. **Discover the live tools.** Read each server's live `tools/list` and follow every returned input schema. Call `integration_connection_info` with `verify: true` first: confirm which of CPI and APIM are configured, which tenant hosts are bound, and which tool areas the service key lacks a role for. If a needed side is not configured or cannot sign in, stop and tell the user to run `sap-ai-dev --setup-integration` in a terminal (it pastes and verifies the service key and saves it outside `mcp.json`) or to set `CPI_SERVICE_KEY` / `APIM_SERVICE_KEY` (or `VCAP_SERVICES`) in the MCP host environment; never ask the user to paste a service key into the chat.
+3. **Read before planning.** Use `cpi_list_packages`, `cpi_list_package_artifacts`, `cpi_get_iflow`, `cpi_list_security_material`, `apim_list_api_providers`, `apim_list_api_proxies`, `apim_export_api_proxy`, `apim_list_api_products`, and `apim_list_key_value_maps` to find what already exists. For other entity sets use the read-only `cpi_odata_get` / `apim_odata_get`. For OData exposure, confirm on the ABAP server that the service binding is published (`PublishServiceBinding` is the RAP Service Developer's step) and take the service path from it.
+4. **Plan.** Present every object to create, update, configure, deploy, or undeploy (for example `cpi_create_package`, `cpi_create_iflow`, `cpi_update_iflow`, `cpi_update_iflow_configuration`, `cpi_deploy_iflow`, `cpi_set_user_credential`, `cpi_upsert_value_mappings`, `cpi_deploy_artifact`, `cpi_undeploy_artifact`, `apim_create_api_provider`, `apim_create_api_proxy`, `apim_update_api_proxy`, `apim_attach_api_proxy_policies`, `apim_create_key_value_map`, `apim_create_api_product`), the key inputs, and the exact confirmation string for each call (for example `CREATE IFLOW <iflow_id>`, `DEPLOY IFLOW <iflow_id>`, `UNDEPLOY ARTIFACT <artifact_id>`, `CREATE API PROVIDER <name>`, `CREATE API PROXY <name>`, `UPDATE API PROXY POLICIES <name>`, `CREATE API PRODUCT <name>`).
+5. **Wait for explicit user approval** of that plan. Do not call any write tool before approval, and do not use a confirmation string for an object the user did not approve.
+6. **Execute** the approved calls in order, passing the approved confirmation strings exactly. Prefer the vetted iFlow template over custom BPMN; pass `expected_version` from a fresh read when updating an iFlow.
+7. **Verify.** Use `cpi_get_iflow_runtime_status` (expect `STARTED`) and `cpi_list_service_endpoints` for iFlows, `cpi_list_runtime_artifacts` for other deployed artifacts, `apim_get_api_proxy` for the proxy `runtime_url`, and `apim_export_api_proxy` to confirm attached policies. On failures, use `cpi_list_message_logs`, `cpi_get_message_log`, and `cpi_get_message_log_steps`.
+8. **Report** what was created, deployed, and verified, the runtime URLs, any delayed read-backs, and remaining manual steps.
+
+## Boundaries
+
+- There are no delete tools. Design-time deletions, API proxy undeploys, applications and API key issuance are manual steps in the Integration Suite UI or developer portal; state that instead of working around it.
+- Secrets are write-only: passwords, client secrets and key value map values the user supplies go only into the tool input that stores them and are never repeated in chat, plans, files or reports. Never request, print, or store service keys. Cloud Connector settings are referenced by name only.
+- Do not author or change ABAP/RAP artifacts; hand those to the RAP Service Developer.
+
+Use the `integration-suite-delivery` skill under `.github/skills/` for the detailed OData exposure and iFlow procedures. When the pattern, connectivity, or security design is still open, start with the **SAP Integration Architect** (or its `sap-integration-architect` skill) and build from its approved plan.

package/.github/agents/sap-solution-architect.agent.md

@@ -32,6 +32,7 @@ Follow this workflow in order and use only capabilities actually exposed by the
    - **RAP Service Developer** for RAP BOs, CDS/projections, behavior, service definitions, bindings, and OData validation.
    - **ABAP Runtime Debugger** for dumps, logs, traces, reproductions, performance symptoms, and runtime root cause analysis.
    - **HANA Cloud/HDI Specialist** for bound-container inspection, CAP/HDI artifact design, local HANA builds, and a user-run deployment handoff. Its MCP server is read-only and must never receive HDI deployment credentials.
+   - **SAP Integration Architect** for SAP Integration Suite designs (API Management, Cloud Integration, or both): pattern choice, connectivity, per-hop security, and an approved build plan that the **SAP Integration Developer** executes through the Integration Suite companion server.
    Each brief must include the target, scope, objects, acceptance criteria, state-changing permissions, required validations, and security constraints, and must mandate a planning step before implementation. ABAP/RAP briefs require local `LintABAP`/LSP checks before SAP transfer and the lint-before-activation gate above; HANA briefs use the HANA skills and never deploy through MCP.
 
 For every ABAP/RAP implementation brief, include the target ABAP release/language version and oldest supported ABAP release across consumers. On ABAP 7.40 or newer, require the implementer to actively consider modern ABAP syntax and verify each construct against that floor; include the CDS language level separately when applicable. Carry SAP/project object naming conventions and Clean ABAP naming expectations into the brief, with links to the [Clean ABAP Cheat Sheet](https://github.com/SAP/styleguides/blob/main/clean-abap/cheat-sheet/CheatSheet.md) and [Names section](https://github.com/SAP/styleguides/blob/main/clean-abap/CleanABAP.md#names).

package/.github/skills/integration-suite-delivery/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: integration-suite-delivery
+description: Build and operate SAP Integration Suite scenarios — Cloud Integration iFlows, value mappings, script collections, security material, Partner Directory and monitoring, and API Management providers, proxies, policies, products and key value maps.
+---
+
+# Integration Suite delivery
+
+Use this skill when a scenario spans SAP Cloud Integration (CPI) and/or SAP API Management (APIM), including exposing an ABAP RAP OData service through an API proxy. The Integration Suite tools come from the separate `integration-suite` companion MCP server; ABAP tools come from the destination server. Query each server's live `tools/list` and follow every returned input schema exactly.
+
+Tool names shown in PascalCase (such as `GetSource` or `LintABAP`) are logical names; the live MCP surface exposes them as lowercase snake_case. A server scoped to a single destination (the normal case for generated `mcp.json` entries) exposes them unprefixed, so `GetSource` appears as `get_source` and `LintABAP` as `lint_abap`; when several destinations share one server, each name is destination-prefixed with its slug for disambiguation (for example `cfd_run_query`). Always call the exact names returned by `tools/list`.
+
+The Integration Suite companion is never destination-prefixed; its tools are already snake_case.
+
+## Tool shortlist
+
+- Connection: `integration_connection_info`.
+- CPI design-time read: `cpi_list_packages`, `cpi_list_iflows`, `cpi_list_package_artifacts`, `cpi_get_iflow`, `cpi_get_artifact`, `cpi_get_value_mappings`.
+- CPI design-time write: `cpi_create_package`, `cpi_update_package`, `cpi_copy_package`, `cpi_create_iflow`, `cpi_update_iflow`, `cpi_update_iflow_configuration`, `cpi_upsert_value_mappings`, `cpi_update_script_collection`.
+- CPI deployment: `cpi_deploy_iflow`, `cpi_deploy_artifact`, `cpi_undeploy_artifact`, `cpi_list_runtime_artifacts`, `cpi_get_iflow_runtime_status`, `cpi_list_service_endpoints`.
+- CPI monitoring: `cpi_list_message_logs`, `cpi_get_message_log`, `cpi_get_message_log_steps`, `cpi_get_jms_broker_status`, `cpi_list_data_stores`, `cpi_list_data_store_entries`, `cpi_list_variables`.
+- CPI security material and tenant configuration: `cpi_list_security_material`, `cpi_set_user_credential`, `cpi_set_oauth2_client_credential`, `cpi_upload_certificate`, `cpi_list_number_ranges`, `cpi_set_number_range`, `cpi_list_partner_parameters`, `cpi_set_partner_parameter`.
+- APIM providers and proxies: `apim_list_api_providers`, `apim_get_api_provider`, `apim_create_api_provider`, `apim_update_api_provider`, `apim_list_api_proxies`, `apim_get_api_proxy`, `apim_export_api_proxy`, `apim_list_virtual_hosts`, `apim_create_api_proxy`, `apim_update_api_proxy`, `apim_attach_api_proxy_policies`.
+- APIM products and key value maps: `apim_list_api_products`, `apim_get_api_product`, `apim_create_api_product`, `apim_update_api_product`, `apim_list_key_value_maps`, `apim_get_key_value_map`, `apim_create_key_value_map`, `apim_set_key_value_map_entries`.
+- Anything else (access policies, JMS queues, applications, developers, certificate store references): the read-only `cpi_odata_get` / `apim_odata_get`; start with path `/$metadata` to see the entity sets.
+
+`cpi_*` tools appear only when CPI credentials are configured and `apim_*` tools only when APIM credentials are configured. Start every session with `integration_connection_info` and `verify: true` to see which side is available, which tenant hosts are bound, and which tool areas the service key lacks a role for. When a side is missing, cannot sign in, or lacks roles, ask the user to run `sap-ai-dev --setup-integration` in a terminal: it takes the key from the logged-in Cloud Foundry space (and can create a dedicated instance with the needed roles) or from a pasted key, checks it online, and stores it user-only. Never ask for a key in the chat.
+
+## Exposing an SAP OData service through API Management
+
+1. **Confirm the ABAP service is published.** On the ABAP destination server, confirm the service binding exists and is published with `PublishServiceBinding`. Creating or changing the RAP service itself belongs to the `rap-service-delivery` skill; do not author ABAP here.
+2. **Derive the service path.** OData V4: `/sap/opu/odata4/<service group path>/<binding>/<version>/`; OData V2: `/sap/opu/odata/sap/<SERVICE_NAME>/`. Use the path the published binding reports; do not guess it.
+3. **Find or create the API provider.** Call `apim_list_api_providers` and reuse a provider whose host, port, and type already match. Otherwise plan `apim_create_api_provider`:
+   - on-premise S/4HANA or ECC through the Cloud Connector: `type: on_premise` with the Cloud Connector virtual host, virtual port, optional `location_id`, and optional `sap_client`;
+   - S/4HANA Cloud or SAP BTP ABAP environment: `type: internet` with the public host and port 443.
+   No credentials are stored on the provider. Backend authentication is configured in the Cloud Connector (for example principal propagation) or sent by the API client.
+4. **Create the API proxy.** Plan `apim_create_api_proxy` with `service_type: odata`, a unique `base_path`, and a provider target whose `relative_path` is the service path from step 2. The import deploys the proxy.
+5. **Secure and throttle it.** Plan one `apim_attach_api_proxy_policies` call (see below) instead of hand-editing the proxy in the UI.
+6. **Package it for consumers.** Plan `apim_create_api_product` over the proxy (published by default, optional quota) when API keys or the developer portal are needed.
+7. **Report the runtime URL.** Call `apim_get_api_proxy` and report `runtime_url` and `state`. When the read-back is still delayed, call it again shortly instead of re-creating the proxy.
+
+## API Management policies, products and key value maps
+
+- `apim_attach_api_proxy_policies` exports the proxy, writes each policy, registers it, adds its flow step, and re-imports (which redeploys). Templates: `verify_api_key`, `quota`, `spike_arrest`, `cors` (response), `assign_headers`, `oauth_verify_access_token`, `ip_allow`, `response_cache`, `basic_auth_from_kvm`, `raise_fault`, `javascript`, and `custom` (raw policy XML with the `http://www.sap.com/apimgmt` namespace). Re-attaching the same policy name replaces its XML and keeps a single step; step order follows the order in the call.
+- Typical API-key setup: `verify_api_key` (proxy, pre, request) then `quota` or `spike_arrest`, then `apim_create_api_product` so consumers can subscribe.
+- Technical backend user: store the user and password in an encrypted map with `apim_create_key_value_map` (or `apim_set_key_value_map_entries`), then attach `basic_auth_from_kvm` (target endpoint, preFlow request by default).
+- Read the current policy set with `apim_export_api_proxy` before changing it. `apim_update_api_proxy` changes base path, target, title and description and keeps every policy, step and script.
+- Product proxy membership is set at creation; `apim_update_api_product` changes title, description, scope, quota and publish state only.
+- Not covered by tools: API proxy undeploy, applications/subscriptions and API key issuance (read them with `apim_odata_get`), analytics. Say so and route those to the API Management UI or developer portal.
+
+## iFlow procedure
+
+1. `cpi_list_packages`; plan `cpi_create_package` only when no suitable package exists. To start from SAP standard content, plan `cpi_copy_package` (`CREATE_COPY` with a suffix, or `OVERWRITE_MERGE` to refresh while keeping configuration).
+2. Plan `cpi_create_iflow`. Prefer the `https-request-reply-http` template (HTTPS sender → Request Reply → HTTP receiver, internet or on-premise via Cloud Connector). Use `template: custom` with caller-supplied BPMN only when the template cannot express the flow, and read an existing similar iFlow with `cpi_get_iflow` first to copy proven adapter versions.
+3. Adjust externalized values with `cpi_update_iflow_configuration`; change bundle files with `cpi_update_iflow`, passing the `expected_version` you just read.
+4. `cpi_deploy_iflow`, then confirm with `cpi_get_iflow_runtime_status` (expect `STARTED`). The deploy call waits at most 50 seconds; when it returns `timed_out: true`, poll `cpi_get_iflow_runtime_status` instead of deploying again. `cpi_list_service_endpoints` can stay empty for a few minutes after `STARTED`; retry it rather than treating it as a failure.
+5. Receiver credentials must exist before deployment: check with `cpi_list_security_material`; create them with `cpi_set_user_credential` or `cpi_set_oauth2_client_credential`, and trust a backend certificate with `cpi_upload_certificate`. Cloud Connector setup stays outside the toolkit.
+6. Value mappings: `cpi_get_value_mappings`, `cpi_upsert_value_mappings`, then `cpi_deploy_artifact`. Script collections: `cpi_update_script_collection`, then `cpi_deploy_artifact`. Message mappings are deployed with `cpi_deploy_artifact` and read with `cpi_get_artifact`.
+7. Retire a runtime artifact with `cpi_undeploy_artifact`; design-time deletion stays manual.
+8. iFlow names must start with a letter or underscore and use only ASCII letters, digits, space, period, hyphen or underscore (no trailing period); put non-ASCII text in the description instead. API proxy descriptions are stored as HTML, so `<`, `>` and `&` come back escaped.
+
+## Troubleshooting
+
+- `cpi_get_iflow_runtime_status` shows deployment errors (for example a missing credential name or an invalid adapter value); `cpi_list_runtime_artifacts` with `status: ERROR` finds every failed deployment.
+- `cpi_list_message_logs` with `status: FAILED` and the iFlow id narrows failing messages; filter by `correlation_id`, `application_message_id` or `custom_header` to follow one business document. `cpi_get_message_log` returns the error text and custom header properties, and `cpi_get_message_log_steps` shows which step failed. Payloads and attachments are intentionally not read.
+- `cpi_get_jms_broker_status`, `cpi_list_data_stores` and `cpi_list_variables` explain stuck or overdue asynchronous processing.
+- For APIM, re-read with `apim_get_api_proxy`, `apim_export_api_proxy` and `apim_get_api_provider`; check virtual hosts with `apim_list_virtual_hosts`.
+
+## Safety
+
+- Present the plan (target tenant hosts, every object to create/update/deploy/undeploy, and the exact confirmation strings) before any write, and wait for explicit user approval.
+- Pass the exact confirmation string from the approved plan, for example `CREATE IFLOW <iflow_id>`, `DEPLOY IFLOW <iflow_id>`, `UNDEPLOY ARTIFACT <artifact_id>`, `CREATE API PROXY <name>` or `UPDATE API PROXY POLICIES <name>`. Never invent or reuse a confirmation for an object the user did not approve.
+- There are no delete tools. Design-time deletion is a manual step in the Integration Suite UI; say so instead of working around it.
+- Secrets are write-only. Passwords, client secrets and key value map values go straight into the tool input that stores them; never repeat them in chat, plans, files or reports, and never ask for service keys. CPI/APIM client credentials are configured in the MCP host environment (`CPI_SERVICE_KEY`, `APIM_SERVICE_KEY`, or `VCAP_SERVICES`).
+- Report what was created, deployed, and verified, including tool results that were delayed or not verified.

package/.github/skills/sap-integration-architect/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: sap-integration-architect
+description: Architect SAP Integration Suite solutions — choose API Management, Cloud Integration, or both; design connectivity, per-hop security, error handling, monitoring, naming and versioning; assess the live CPI/APIM tenant; and produce an approved build plan with exact tool calls.
+---
+
+# SAP Integration Architect
+
+Use this skill to design an integration on SAP Integration Suite before anything is built: which components to use, how each hop connects and authenticates, how failures surface, and the exact build plan. Build execution follows the `integration-suite-delivery` skill (or the SAP Integration Developer agent where the harness supports agents). ABAP/RAP authoring follows `rap-service-delivery`; SAP-standard and Clean Core decisions follow `sap-standard-api-analysis` and `clean-core-extensibility`.
+
+Tool names shown in PascalCase (such as `GetSource` or `LintABAP`) are logical names; the live MCP surface exposes them as lowercase snake_case. A server scoped to a single destination (the normal case for generated `mcp.json` entries) exposes them unprefixed, so `GetSource` appears as `get_source` and `LintABAP` as `lint_abap`; when several destinations share one server, each name is destination-prefixed with its slug for disambiguation (for example `cfd_run_query`). Always call the exact names returned by `tools/list`.
+
+The Integration Suite companion server is never destination-prefixed. Read its live `tools/list` once and follow each returned input schema; `cpi_*` tools appear only when CPI credentials are configured and `apim_*` tools only when APIM credentials are configured.
+
+## 1. Requirement checklist
+
+Consumers and providers · direction and trigger (synchronous request/reply, asynchronous, scheduled) · protocol and payload (OData V2/V4, REST, SOAP) · volume and latency · data sensitivity · authentication at every hop · error and retry expectations · environments · acceptance tests. Ask only for missing material details.
+
+## 2. Assess before designing (read-only)
+
+- `integration_connection_info` — which tenants are bound.
+- CPI: `cpi_list_packages`, `cpi_list_iflows`, `cpi_get_iflow` (models and configuration of similar flows), `cpi_list_service_endpoints`, `cpi_get_iflow_runtime_status`, `cpi_list_message_logs` with status `FAILED`, `cpi_get_message_log`.
+- APIM: `apim_list_api_providers`, `apim_get_api_provider`, `apim_list_api_proxies`, `apim_get_api_proxy`, `apim_list_virtual_hosts`.
+- SAP backend: confirm on the ABAP destination server that the OData service is published (`PublishServiceBinding` belongs to RAP service delivery) and take the service path from it; check SAP-delivered APIs with `GetAPIReleaseState`.
+
+Reuse matching providers, packages and iFlows instead of duplicating them.
+
+## 3. Pattern decision guide
+
+| Need | Pattern |
+|---|---|
+| Expose an existing OData/REST service to consumers with a managed URL, no payload change | API Management only — API provider + API proxy |
+| Mapping, routing, enrichment, protocol change, multi-call orchestration, scheduled processing | Cloud Integration only — iFlow |
+| External consumers need a managed API and the backend needs mediation | API Management in front of Cloud Integration — proxy targets the iFlow endpoint |
+
+API Management targets: an API provider (Internet for S/4HANA Cloud and SAP BTP ABAP; On-Premise through the Cloud Connector virtual host, port and location ID) with a relative path such as `/sap/opu/odata4/...`, or a fixed `https://` URL. To front an iFlow, use the iFlow endpoint URL or an Internet provider on the CPI runtime host with relative path `/http/<sender path>`.
+
+Cloud Integration: prefer the vetted `https-request-reply-http` template (HTTPS sender → Request Reply → HTTP receiver, Internet or On-Premise). Use custom BPMN only when the template cannot express the flow, starting from a model read from an existing iFlow.
+
+## 4. Per-hop security
+
+| Hop | How it authenticates |
+|---|---|
+| Client → API Management | Toolkit-created proxies carry no policies; the client `Authorization` header is forwarded unchanged. Add API-key or OAuth policies in the APIM UI when the gateway must authenticate consumers. |
+| Client or APIM → Cloud Integration | OAuth token from a Process Integration Runtime `integration-flow` client with role `ESBMessaging.send`; calls without it get HTTP 401. |
+| Cloud Integration → backend | Receiver authentication None, Basic, OAuth2 Client Credentials, Client Certificate or Principal Propagation; security materials are referenced by name and must already exist on the tenant. |
+| API Management → backend | API providers store no credentials; use Cloud Connector principal propagation or forward the client credentials. |
+
+Never ask for, print or store secrets. Credentials belong in the MCP host environment (`CPI_SERVICE_KEY`, `APIM_SERVICE_KEY`, or `VCAP_SERVICES`).
+
+## 5. Errors, operations and platform timing
+
+- A receiver error fails the message and returns HTTP 500 to the caller; define how the consumer reacts.
+- Operate with message processing logs: status, error text and custom header properties (payloads are never read).
+- Proven on live tenants: deployments can stay `STARTING` beyond a minute (`cpi_deploy_iflow` returns `timed_out` after 50 seconds; then poll `cpi_get_iflow_runtime_status`); service endpoints and message logs appear minutes after `STARTED`; API proxy read-back lags after import. Build these waits into acceptance tests instead of treating them as failures.
+
+## 6. Naming and versioning rules
+
+- Package ids: letters, digits, underscore. iFlow ids: letters, digits, `.`, `_`, `-`.
+- iFlow names: ASCII letters, digits, space, period, hyphen or underscore; no trailing period. Put non-ASCII text in descriptions.
+- API proxy and provider names: letters, digits, `_`, `-`. Reserved provider names: `TC_*`, `DEST_CI`, `APIMGMT_PORTAL`, `ON_PREM`, `Apimgmt_rt*`, and ContentCatalog.
+- Base paths and sender paths: unique, lowercase, versioned (for example `/s4/salesorder/v1`); no `//`, `..` or trailing `/`.
+- API proxy descriptions are stored as HTML (`<`, `>`, `&` come back escaped).
+- Every iFlow update needs `expected_version` from a fresh read and bumps the patch version; every proxy update is a new revision.
+
+## 7. Design deliverable
+
+1. Chosen pattern, rationale and rejected alternatives.
+2. Component flow (consumer → gateway → integration → backend).
+3. Per-hop table: host, port, path, route (Internet or Cloud Connector), authentication.
+4. Objects to create or change: package, iFlows (template or custom), externalized parameters, security materials, value mappings, API providers (`sap-client` where needed), API proxies, gateway policies, key value maps, API products.
+5. Ordered build calls with their exact confirmation strings: `cpi_create_package` (`CREATE CPI PACKAGE <id>`), `cpi_create_iflow` (`CREATE IFLOW <id>`), `cpi_update_iflow_configuration` (`CONFIGURE IFLOW <id>`), `cpi_update_iflow` (`UPDATE IFLOW <id>`), `cpi_set_user_credential` (`SET USER CREDENTIAL <name>`), `cpi_set_oauth2_client_credential` (`SET OAUTH2 CLIENT CREDENTIAL <name>`), `cpi_deploy_iflow` (`DEPLOY IFLOW <id>`), `cpi_deploy_artifact` (`DEPLOY ARTIFACT <id>`), `cpi_undeploy_artifact` (`UNDEPLOY ARTIFACT <id>`), `apim_create_api_provider` (`CREATE API PROVIDER <name>`), `apim_create_api_proxy` (`CREATE API PROXY <name>`), `apim_update_api_proxy` (`UPDATE API PROXY <name>`), `apim_create_key_value_map` (`CREATE KEY VALUE MAP <name>`), `apim_attach_api_proxy_policies` (`UPDATE API PROXY POLICIES <name>`), `apim_create_api_product` (`CREATE API PRODUCT <name>`).
+6. Prerequisites outside the tools, with owners: Cloud Connector mappings, `integration-flow` clients, applications and API keys, API proxy undeploy, role assignments.
+7. Acceptance tests and how they are verified: `cpi_get_iflow_runtime_status` is `STARTED`, `cpi_list_service_endpoints` returns the endpoint, `apim_get_api_proxy` returns `runtime_url` and state, and test calls appear as `COMPLETED` message logs.
+8. Risks and open questions.
+
+Present the deliverable and wait for explicit user approval before any create, update, configure, deploy or undeploy call. There are no delete tools; design-time deletion and API proxy undeploy are manual steps in the Integration Suite UI.

package/NOTICE

@@ -31,3 +31,13 @@ Licensed under the Apache License, Version 2.0.
 vsp also links other open-source Go modules; their licences are recorded in
 go.mod / go.sum and in the module cache. Apache-2.0 requires the notice above to
 travel with any distribution of the binaries, which is why this file exists.
+
+--------------------------------------------------------------------------------
+Integration Suite iFlow template
+--------------------------------------------------------------------------------
+
+src/integration-templates/https-request-reply-http.iflw is derived from the
+Integration_Test_IFlow test artifact of FlashPipe
+(https://github.com/engswee/flashpipe), Copyright Eng Swee Yeoh, licensed under
+the Apache License, Version 2.0 (see LICENSE-APACHE-2.0.txt). It was modified to
+add a Request Reply step, an HTTP receiver adapter, and externalized parameters.

package/README.md

@@ -67,7 +67,7 @@ After setup, connect a selected BAS destination or local SAP GUI system from you
 1. Open the Command Palette.
 2. Run **MCP: List Servers**.
 3. Start the server named after your selected destination (the lowercase slug, for example `demo-abap` for destination `DEMO_ABAP`).
-4. In your AI assistant's chat, choose the best-fit bundled agent from the agent picker (GitHub Copilot, Claude Code, and opencode install the agents) or invoke the matching Pi prompt template (`/sap-solution-architect`, `/abap-developer`, `/abap-runtime-debugger`, `/rap-service-developer`, or `/hana-cloud-hdi-specialist`): **SAP Solution Architect**, **ABAP Developer**, **ABAP Runtime Debugger**, **RAP Service Developer**, or **HANA Cloud/HDI Specialist**.
+4. In your AI assistant's chat, choose the best-fit bundled agent from the agent picker (GitHub Copilot, Claude Code, and opencode install the agents) or invoke the matching Pi prompt template (`/sap-solution-architect`, `/abap-developer`, `/abap-runtime-debugger`, `/rap-service-developer`, `/hana-cloud-hdi-specialist`, `/sap-integration-architect`, or `/sap-integration-developer`): **SAP Solution Architect**, **ABAP Developer**, **ABAP Runtime Debugger**, **RAP Service Developer**, **HANA Cloud/HDI Specialist**, **SAP Integration Architect**, or **SAP Integration Developer**.
 5. In the Chat tools picker, enable the server for that destination.
 6. Ask the agent to inspect, build, test, or verify something in your SAP landscape.
 
@@ -77,7 +77,7 @@ Use the attached destination-prefixed tools directly in chat. Do not launch `sap
 
 ## 🤖 Available agents and skills
 
-**Agents:** Five user-invocable custom agents are included. Select the best fit from the agent picker in your harness's chat (GitHub Copilot, Claude Code, or opencode), or use the matching Pi prompt command, as shown in Quick start.
+**Agents:** Seven user-invocable custom agents are included. Select the best fit from the agent picker in your harness's chat (GitHub Copilot, Claude Code, or opencode), or use the matching Pi prompt command, as shown in Quick start. Harnesses without custom agents (OpenAI Codex, Cursor, Gemini CLI, OMP, Cline, Roo Code, Windsurf / Devin Desktop) get the same workflows as skills, for example `sap-integration-architect` and `integration-suite-delivery`.
 
 | | Agent | Best for |
 | --- | --- | --- |
@@ -86,8 +86,10 @@ Use the attached destination-prefixed tools directly in chat. Do not launch `sap
 | 🐞 | **ABAP Runtime Debugger** | Runtime incidents, application logs, debugger sessions, and performance symptoms; call relationships are derived from source inspection |
 | 🚀 | **RAP Service Developer** | RAP business objects, behavior implementations, projections, service definitions, service bindings, and OData validation |
 | 🗃️ | **HANA Cloud/HDI Specialist** | Read-only HANA Cloud container inspection, CAP/HDI artifact generation, local validation, and user-run deployment handoffs |
+| 🏗️ | **SAP Integration Architect** | SAP Integration Suite design: API Management vs Cloud Integration vs both, connectivity, per-hop security, error handling, and an approved build plan |
+| 🔌 | **SAP Integration Developer** | Building that plan with the Integration Suite companion: iFlows, value mappings, security material, deployment and monitoring in CPI; API providers, proxies, policies, products and key value maps in APIM |
 
-**Included skills:** `abap-development` · `abap-testing-quality` · `cds-development` · `rap-development` · `abap-debugging` · `abap-runtime-analysis` · `rap-service-delivery` · `sap-standard-api-analysis` · `clean-core-extensibility` · `sap-sdlc-orchestration` · `sap-transport-release` · `hana-cloud-inspection` · `hana-cloud-native-development` · `hana-cloud-validation`
+**Included skills:** `abap-development` · `abap-testing-quality` · `cds-development` · `rap-development` · `abap-debugging` · `abap-runtime-analysis` · `rap-service-delivery` · `sap-standard-api-analysis` · `clean-core-extensibility` · `sap-sdlc-orchestration` · `sap-transport-release` · `hana-cloud-inspection` · `hana-cloud-native-development` · `hana-cloud-validation` · `sap-integration-architect` · `integration-suite-delivery`
 
 Agents and skills install for the harnesses you pick during global installation: a multi-select offers GitHub Copilot and Claude Code pre-checked, plus OpenAI Codex, Cursor, Gemini CLI, opencode, Pi Coding Agent, Oh My Pi (OMP), Cline, Roo Code, and Windsurf / Devin Desktop. In non-interactive installs they are installed for GitHub Copilot only; run `sap-ai-dev --setup` afterwards to configure destinations or local SAP GUI systems. Repository-scoped installation instructions appear below.
 
@@ -159,9 +161,9 @@ The catalog below covers source inspection, data, editing, quality, transports,
 - Read SLG1 application logs
 - Review and create transport requests
 
-## 🧠 Five agents, fourteen focused skills
+## 🧠 Seven agents, sixteen focused skills
 
-The package ships with five custom agents plus fourteen task-focused Agent Skills:
+The package ships with seven custom agents plus sixteen task-focused Agent Skills:
 
 | | Skill | Best for |
 | --- | --- | --- |
@@ -179,6 +181,8 @@ The package ships with five custom agents plus fourteen task-focused Agent Skill
 | 🔎 | `hana-cloud-inspection` | Verify the selected HANA Cloud binding and inspect bounded HDI catalog/data results |
 | 🧱 | `hana-cloud-native-development` | Generate CAP-owned CDS models or required native HDI artifacts without duplicating generated sources |
 | ✅ | `hana-cloud-validation` | Run local CAP/HANA builds and prepare a reviewed, user-run deployment handoff |
+| 🏗️ | `sap-integration-architect` | Integration Suite pattern choice, connectivity, per-hop security, naming/versioning rules, and an approvable build plan |
+| 🔌 | `integration-suite-delivery` | Building iFlows, API proxies, gateway policies, API products and key value maps step by step, deploying, and troubleshooting with message logs |
 
 ## 🗺️ How it fits together
 
@@ -192,7 +196,7 @@ ABAP/RAP backend access is provided by this add-on's BAS proxy. For end-to-end S
 sap-ai-dev --setup --tools
 ```
 
-The companion entries are optional and are launched through `npx` only when the MCP client starts them. They are marked as managed by `sap-ai-dev-toolkit`, so rerunning setup can update or remove them without touching unrelated MCP servers. The HANA companion uses `--ignore-scripts` so the toolkit postinstall wizard cannot run during MCP startup.
+The companion entries are optional and are launched through `npx` only when the MCP client starts them. They are marked as managed by `sap-ai-dev-toolkit`, so rerunning setup can update or remove them without touching unrelated MCP servers. The HANA and Integration Suite companions use `--ignore-scripts` so the toolkit postinstall wizard cannot run during MCP startup.
 
 | MCP entry | Package | Launches | Use when the agent needs to |
 | --- | --- | --- | --- |
@@ -201,6 +205,7 @@ The companion entries are optional and are launched through `npx` only when the
 | `cap-tools` | `@cap-js/mcp-server` | `cds-mcp` | Inspect CAP CDS models, services, entities, actions, and local CAP application structure |
 | `browser-validation` | `@playwright/mcp` | `playwright-mcp` | Open BAS previews, smoke-test Fiori/UI flows, collect screenshots, and verify browser runtime behavior |
 | `hana-cloud-inspector` | `sap-ai-dev-toolkit` | `sap-ai-hana` | Inspect a bound HANA Cloud HDI schema using read-only catalog tools and capped row reads |
+| `integration-suite` | `sap-ai-dev-toolkit` | `sap-ai-integration` | Build, deploy, undeploy, and monitor Cloud Integration content (iFlows, value mappings, script collections, security material, Partner Directory) and manage API Management providers, proxies, policies, products, and key value maps |
 
 Recommended profiles:
 
@@ -220,6 +225,28 @@ Use either:
 
 The configured identity must be a separate least-privileged read-only HANA user. The server rejects bindings that offer only HDI deployment credentials and never falls back to `hdi_user`/`hdi_password`. Its tools are limited to connection identity, object listing/descriptions, and parameterized row reads capped at 200 rows; credential-like columns are blocked, and there is no arbitrary SQL, DDL/DML, grant, deployment, or undeploy tool. Use the existing project deployment workflow yourself after reviewing the exact generated artifact diff and target. The SAP HANA Node.js driver is provided under the SAP Developer License Agreement.
 
+### Integration Suite (Cloud Integration + API Management)
+
+Every interactive `sap-ai-dev --setup` asks **"Add the SAP Integration Suite tools?"** right before it writes the MCP configuration. The step shows which of CPI and APIM have credentials (never the secrets themselves). Enter means **yes** when credentials were found and **no** otherwise; type `y` or `n` to override. An existing `integration-suite` entry is kept without asking. With `--tools`, the choice is part of the companion checkbox instead, and when nothing is detected the setup menu also offers **Set up only the SAP Integration Suite tools**.
+
+To set up only this server, run **`sap-ai-dev --setup-integration`**. In both routes the credential step:
+
+1. **Checks detected credentials online.** It signs in and runs one read-only request per tool area (packages, deployed artifacts, message logs, security material, number ranges, Partner Directory, data stores, JMS; API proxies, providers, products, key value maps, virtual hosts, and policy readiness, which exports an existing API proxy bundle the way `apim_attach_api_proxy_policies` does). Each area is marked ✓, ✗ (missing role) or – (not available on the tenant or plan, or no proxy exists yet to test the export with).
+2. **Uses the logged-in Cloud Foundry space (default when `cf` is logged in).** It finds the Process Integration Runtime instance with plan `api` (`it-rt`) and the API Management instance with plan `apiportal-apiaccess`, lets you choose when there are several, and reuses or creates one service key named `sap-ai-dev-integration` on it. The key is then verified and saved like a pasted one. Roles are fixed on the instance, so when the key signs in but lacks roles, or a side has no instance, the wizard offers to create a dedicated instance (`sap-ai-dev-integration-cpi` with `AuthGroup_Administrator`, `AuthGroup_BusinessExpert`, `AuthGroup_IntegrationDeveloper`, `AuthGroup_TenantPartnerDirectoryConfigurator`, `AccessAllAccessPoliciesArtifacts`; `sap-ai-dev-integration-apim` with `APIPortal.Administrator`). It never does this without your `y`.
+3. **Lets you paste a service key.** Paste a CPI key (Process Integration Runtime, plan `api`) or an APIM key (API Management, plan `apiportal-apiaccess`), either as JSON (multi-line paste works; input is hidden) or as the path to the downloaded `.json` file. The key is verified the same way before it is saved.
+4. **Saves only what the server needs.** The URL, token URL, client id and secret go to `~/.config/sap-ai-dev-toolkit/integration-suite.json`, readable only by you. The secret is never printed and never written to `mcp.json`. A key that cannot sign in is saved only if you confirm.
+
+Environment credentials take precedence over a saved key. Re-check at any time with `sap-ai-integration --check`, or ask the agent to call `integration_connection_info` with `verify: true`. Configure CPI, APIM, or both; per side the first match wins:
+
+- Explicit `CPI_URL`, `CPI_TOKEN_URL`, `CPI_CLIENT_ID`, `CPI_CLIENT_SECRET` (or the `APIM_*` equivalents).
+- `CPI_SERVICE_KEY` / `APIM_SERVICE_KEY` containing the service-key JSON: a Process Integration Runtime `api` plan key (ClientId/Secret) for CPI, an API Management `apiportal-apiaccess` key for APIM. Certificate-based keys are rejected.
+- One `VCAP_SERVICES` binding of service `it-rt` / `apimanagement-apiportal`; override the label with `CPI_VCAP_SERVICE` / `APIM_VCAP_SERVICE` and select an instance with `CPI_BINDING` / `APIM_BINDING`.
+- The key saved by `sap-ai-dev --setup-integration` (lowest precedence).
+
+CPI needs the roles `WorkspacePackagesRead`, `WorkspacePackagesEdit`, `WorkspacePackagesConfigure`, `WorkspaceArtifactsDeploy`, and `MonitoringDataRead` for packages, iFlows, deployment and message logs; security material, number ranges, Partner Directory, data stores, and JMS tools additionally need the matching `api`-plan roles for those areas (for example `DataStoresAndQueuesRead` and `AuthGroup_TenantPartnerDirectoryConfigurator`), and a missing role surfaces as an HTTP 403 in the tool error. APIM needs `APIPortal.Administrator`. Writes are limited to create, update, configure, deploy, and undeploy, each gated by an exact confirmation string such as `CREATE IFLOW <iflow_id>` or `UPDATE API PROXY POLICIES <name>`; there are no delete tools. Passwords, client secrets, and key value map values are write-only: tools accept them and never return them. Anything without a dedicated tool can be read through `cpi_odata_get` / `apim_odata_get`. Run `sap-ai-integration --help` for the full variable list.
+
+`npm run test:live:integration` runs the end-to-end scenarios against a real tenant. It **creates and deploys** packages, iFlows, API providers, proxies, products, key value maps, user credentials, number ranges, and Partner Directory parameters suffixed with `RUN` (required, unique per run), so use a non-production subaccount. Scenarios that call iFlows over HTTP also need `CPI_RUNTIME_SERVICE_KEY`, a Process Integration Runtime `integration-flow` key with role `ESBMessaging.send`; the companion server itself never uses that key.
+
 ## 💡 Example requests
 
 Once the destination server is enabled in your chat's tools picker, ask for outcomes instead of manually orchestrating individual SAP operations:
@@ -274,7 +301,7 @@ Prefer a persistent global install? Install globally from SAP Business Applicati
 
 Everything works natively on Windows — PowerShell, cmd, and Windows Terminal are all supported:
 
-- `npm install --global sap-ai-dev-toolkit` puts three commands on `PATH`: `sap-ai-dev`, its alias `sap-ai-dev-toolkit`, and `sap-ai-hana`. If `sap-ai-dev` is reported as unknown, npm's global bin directory is missing from `PATH` (run `npm prefix -g` to find it) or the install did not complete — `npx --yes --ignore-scripts sap-ai-dev-toolkit --setup` works without any global install.
+- `npm install --global sap-ai-dev-toolkit` puts four commands on `PATH`: `sap-ai-dev`, its alias `sap-ai-dev-toolkit`, `sap-ai-hana`, and `sap-ai-integration`. If `sap-ai-dev` is reported as unknown, npm's global bin directory is missing from `PATH` (run `npm prefix -g` to find it) or the install did not complete — `npx --yes --ignore-scripts sap-ai-dev-toolkit --setup` works without any global install.
 - The pinned SAP runtime ships inside the package as a native Windows executable; no Go toolchain, WSL, or extra downloads are required.
 - MCP entries that launch through npm are written as `cmd /c npx ...` on Windows — the form VS Code, Claude Code, and Cursor can spawn there. Entries written on Linux/macOS use plain `npx`.
 - Setup reads `mcp.json` even when Windows tools saved it with a UTF-8/UTF-16 BOM (PowerShell `>`/`Set-Content`, Notepad "UTF-8 with BOM") and rewrites it as plain UTF-8. If the existing file cannot be used as-is, setup self-heals before falling back to a reset: VS Code-style comments and trailing commas (JSONC) are recovered in place, torn reads from a concurrent editor save are re-read once, and broken `servers`/`inputs` fields are repaired individually. Every lossy change first backs up the original next to the real file as `mcp.json.healed|repaired|invalid-<timestamp>.bak` (exclusive create, so reruns never overwrite an earlier backup; symlinked configs keep their link). `sap-ai-dev --doctor` stays strict and reports such files instead of rewriting them — run `sap-ai-dev --setup` to heal.
@@ -373,7 +400,7 @@ At the end of a global install, the color-coded summary shows the MCP config pat
 
 ## 🤖 ABAP agents and skills for your AI harness
 
-The package includes five user-invocable custom agents (**SAP Solution Architect**, **ABAP Developer**, **ABAP Runtime Debugger**, **RAP Service Developer**, and **HANA Cloud/HDI Specialist**) and fourteen task-focused Agent Skills for GitHub Copilot, Claude Code, and other supported AI coding harnesses in BAS.
+The package includes seven user-invocable custom agents (**SAP Solution Architect**, **ABAP Developer**, **ABAP Runtime Debugger**, **RAP Service Developer**, **HANA Cloud/HDI Specialist**, **SAP Integration Architect**, and **SAP Integration Developer**) and sixteen task-focused Agent Skills for GitHub Copilot, Claude Code, and other supported AI coding harnesses in BAS.
 
 ### 🧠 How the SAP Solution Architect and ABAP Developer agents work
 

package/dist/checksums.txt

@@ -1,5 +1,5 @@
-5a8adb501a30bb4f3c3a1f2c16aee0f60de0be9a226cafbc07191ba955c9269f  vsp-linux-x64
-d7b96b63ec812949e2ab2e223b1fbac5f5a0cd1c6e068e3ddd117d3548c968a2  vsp-linux-arm64
-7328b9fd0ceb60287b53e9d6425e7111c87cdefcec1d412544eb6b1e70f4249c  vsp-darwin-x64
-fb90f7a1b2bdca5fcc7bb8ba5623d6fb1dcbb88de02bba5686acad503f29f84f  vsp-darwin-arm64
-bd33b0a45640700bd26372355b73169632b21fb4c07df33b8cc0b5d7ff5b76e0  vsp-win32-x64.exe
+cefc61f6b12b273c74c1e9d0e488006508b1e30a0660ad4f8dda77dfb1da1a92  vsp-linux-x64
+17e6f4d4ea4dca78ed384b3a76189bf9a0711a862eb08d47c2019046464acb55  vsp-linux-arm64
+5a1c4cbd837eb27d9df66b04b2737ad7323128876bd7bdc41417d1ddd29d53b9  vsp-darwin-x64
+1acb86850d55a013951ad3a40d83e58f19a05333f68e2af2e8e5aa882f17f7d7  vsp-darwin-arm64
+bd41b6b2b8a99313a804fc8546f3f13ccd872425c74293dd34eb538c49ee54ed  vsp-win32-x64.exe

package/inventory.md

@@ -191,3 +191,65 @@ The HANA inspector is a standalone companion MCP process launched as `sap-ai-han
 | `hana_read_rows` | Read selected catalog-verified columns with bound filter values and a hard 200-row maximum; credential-like columns are blocked. No free-form SQL. |
 
 The process exposes no DDL, DML, arbitrary SQL, procedure-call, deployment, undeploy, grant, or service-key management tools. The separate HANA identity should also be granted only the reads required for the intended HDI container.
+
+## Separate optional Integration Suite server
+
+The Integration Suite companion is a standalone MCP process launched as `sap-ai-integration`; it is not a child of the SAP runtime and is not destination-prefixed. CPI and APIM OAuth clients come from `CPI_*`/`APIM_*` variables, `CPI_SERVICE_KEY`/`APIM_SERVICE_KEY`, one unambiguous `VCAP_SERVICES` binding per side, or (lowest precedence) a key pasted, verified online and saved user-only by `sap-ai-dev --setup-integration` in `~/.config/sap-ai-dev-toolkit/integration-suite.json`. Requests are pinned to the configured tenant origins. `cpi_*` tools are registered only when CPI is configured, `apim_*` tools only when APIM is configured. `sap-ai-integration --check` runs the same online verification from a terminal.
+
+| Tool | Behavior |
+| --- | --- |
+| `integration_connection_info` | Report configured sides, credential source, binding, and tenant/token hosts. `verify: true` signs in and runs one read-only request per tool area, classifying each as ok, forbidden (missing role) or unavailable. Never returns client ids or secrets. |
+| `cpi_list_packages` | List packages (max 200). |
+| `cpi_list_iflows` | List iFlows of a package. |
+| `cpi_get_iflow` | Artifact metadata, configurations, and bundle files (text capped 48 KiB each, or one file up to 90 KiB). |
+| `cpi_get_iflow_runtime_status` | Runtime status; error text when `ERROR`. |
+| `cpi_list_service_endpoints` | Deployed endpoint URLs, optionally for one iFlow. |
+| `cpi_list_message_logs` | Message processing logs filtered by iFlow, status, time window, `correlation_id`, `application_message_id`, or `custom_header` (max 100). |
+| `cpi_get_message_log` | One log with error text and custom header properties; attachments are not read. |
+| `cpi_get_message_log_steps` | Steps of the latest run (sorted by start, max 200) with step errors. |
+| `cpi_list_package_artifacts` | iFlows, value mappings, script collections, and message mappings of one package. |
+| `cpi_get_artifact` | Value mapping, script collection, or message mapping metadata plus bundle files (same caps as `cpi_get_iflow`). |
+| `cpi_get_value_mappings` | Agency pairs with values and defaults (max 500 values per pair). |
+| `cpi_list_runtime_artifacts` | Deployed artifacts, optionally by status. |
+| `cpi_get_jms_broker_status` | JMS broker capacity and non-OK queues. |
+| `cpi_list_data_stores` / `cpi_list_data_store_entries` / `cpi_list_variables` | Data store, entry, and variable metadata; payloads are not read. |
+| `cpi_list_security_material` | User credentials, OAuth2 client credentials, or keystore entries; secret fields redacted. |
+| `cpi_list_number_ranges` | Number ranges. |
+| `cpi_list_partner_parameters` | Partner Directory string parameters and binary parameter metadata. |
+| `cpi_odata_get` | Read-only GET for other `/api/v1` entity sets or `/$metadata`; `$value`, `$batch`, and `$links` rejected; secrets and artifact content redacted. |
+| `cpi_create_package` | Create a package. Confirmation `CREATE CPI PACKAGE <package_id>`. |
+| `cpi_create_iflow` | Create an iFlow from the `https-request-reply-http` template or custom BPMN. Confirmation `CREATE IFLOW <iflow_id>`. |
+| `cpi_update_iflow` | Replace/add files and parameters with an `expected_version` check and patch bump; never deletes files. Confirmation `UPDATE IFLOW <iflow_id>`. |
+| `cpi_update_iflow_configuration` | Set externalized parameters sequentially. Confirmation `CONFIGURE IFLOW <iflow_id>`. |
+| `cpi_deploy_iflow` | Deploy and wait up to 50 s (below common MCP client timeouts) for build/runtime status; `timed_out` means poll `cpi_get_iflow_runtime_status`. Confirmation `DEPLOY IFLOW <iflow_id>`. |
+| `cpi_deploy_artifact` | Deploy a value mapping, script collection, or message mapping and wait up to 50 s for runtime status. Confirmation `DEPLOY ARTIFACT <artifact_id>`. |
+| `cpi_undeploy_artifact` | Undeploy a runtime artifact and wait up to 50 s until it is gone. Confirmation `UNDEPLOY ARTIFACT <artifact_id>`. |
+| `cpi_update_package` | Merge name, short text, description, or version into a package. Confirmation `UPDATE CPI PACKAGE <package_id>`. |
+| `cpi_copy_package` | Copy a Discover package (`CREATE_COPY` with suffix or `OVERWRITE_MERGE`). Confirmation `COPY CPI PACKAGE <package_id>`. |
+| `cpi_upsert_value_mappings` | Upsert value pairs sequentially, stopping at the first failure; deploy afterwards. Confirmation `UPDATE VALUE MAPPING <artifact_id>`. |
+| `cpi_update_script_collection` | Add/replace scripts in the collection bundle. Confirmation `UPDATE SCRIPT COLLECTION <artifact_id>`. |
+| `cpi_set_user_credential` | Create or update a user credential; password write-only. Confirmation `SET USER CREDENTIAL <name>`. |
+| `cpi_set_oauth2_client_credential` | Create or update an OAuth2 client credential; secret write-only. Confirmation `SET OAUTH2 CLIENT CREDENTIAL <name>`. |
+| `cpi_upload_certificate` | Add (or with `update` replace) a PEM certificate in the system keystore. Confirmation `UPLOAD CERTIFICATE <alias>`. |
+| `cpi_set_number_range` | Create or update a number range. Confirmation `SET NUMBER RANGE <name>`. |
+| `cpi_set_partner_parameter` | Create or update a Partner Directory string or binary parameter. Confirmation `SET PARTNER PARAMETER <pid>/<id>`. |
+| `apim_list_api_providers` | List providers without credential fields. |
+| `apim_get_api_provider` | One provider with credential properties removed. |
+| `apim_list_api_proxies` | List proxies. |
+| `apim_get_api_proxy` | One proxy with endpoints, virtual hosts, deployment info, and computed `runtime_url`. |
+| `apim_list_virtual_hosts` | List virtual hosts. |
+| `apim_export_api_proxy` | Export the proxy bundle and return its files (or one file). |
+| `apim_list_api_products` / `apim_get_api_product` | Products; one product with its proxy names. |
+| `apim_list_key_value_maps` / `apim_get_key_value_map` | Key value maps; encrypted values redacted. |
+| `apim_odata_get` | Read-only GET for other Management.svc entity sets (applications, developers, certificate store references) or `/$metadata`; same guards as `cpi_odata_get`. |
+| `apim_create_api_provider` | Create an Internet or On-Premise provider; no credentials sent; reserved names rejected. Confirmation `CREATE API PROVIDER <name>`. |
+| `apim_update_api_provider` | Merge connection changes into a credential-free provider (credentialed providers are refused). Confirmation `UPDATE API PROVIDER <name>`. |
+| `apim_create_api_proxy` | Import (and deploy) a policy-free proxy for a provider or https URL target. Confirmation `CREATE API PROXY <name>`. |
+| `apim_update_api_proxy` | Export, patch base path/target/title/description in place, and re-import; policies, steps, and scripts are preserved. Confirmation `UPDATE API PROXY <name>`. |
+| `apim_attach_api_proxy_policies` | Add or replace up to 10 policies from templates or custom XML and their flow steps, then re-import. Confirmation `UPDATE API PROXY POLICIES <name>`. |
+| `apim_create_api_product` | Create (and by default publish) a product over existing proxies with optional quota. Confirmation `CREATE API PRODUCT <name>`. |
+| `apim_update_api_product` | Merge title, description, scope, quota, or publish state. Confirmation `UPDATE API PRODUCT <name>`. |
+| `apim_create_key_value_map` | Create a map (encrypted by default); values write-only. Confirmation `CREATE KEY VALUE MAP <name>`. |
+| `apim_set_key_value_map_entries` | Update existing entries and add new ones, stopping at the first failure; values write-only. Confirmation `UPDATE KEY VALUE MAP <name>`. |
+
+Confirmations are checked before any network call. The process exposes no delete tools. Secrets are write-only and never returned; message payloads, attachments, and data-store payloads are never read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.9.9913",
+  "version": "0.9.9915",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",
@@ -11,6 +11,7 @@
     "@abaplint/core": "2.119.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@sap/hana-client": "2.30.27",
+    "fflate": "0.8.3",
     "terminal-kit": "^3.1.4",
     "undici": "^6.21.3",
     "zod": "4.6.5"
@@ -18,13 +19,15 @@
   "bin": {
     "sap-ai-dev": "src/launcher.mjs",
     "sap-ai-dev-toolkit": "src/launcher.mjs",
-    "sap-ai-hana": "src/hana-inspector.mjs"
+    "sap-ai-hana": "src/hana-inspector.mjs",
+    "sap-ai-integration": "src/integration-server.mjs"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
     "install:local": "node scripts/install-local.mjs",
     "test": "node --test --test-force-exit test/*.test.mjs",
     "test:live:s4h": "node scripts/run-live-s4h.mjs",
+    "test:live:integration": "node scripts/run-live-integration.mjs",
     "test:visibility": "node --test test/setup.test.mjs test/terminal-ui.test.mjs",
     "test:mutation": "node scripts/mutation-terminal-ui.mjs",
     "publish:npm": "node scripts/publish-npm.mjs",