sap-ai-dev-toolkit 0.9.9912 → 0.9.9914

package/src/integration-templates/https-request-reply-http.iflw

@@ -0,0 +1,391 @@
+<?xml version="1.0" encoding="UTF-8"?><bpmn2:definitions xmlns:bpmn2="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:ifl="http:///com.sap.ifl.model/Ifl.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="Definitions_1">
+    <bpmn2:collaboration id="Collaboration_1" name="Default Collaboration">
+        <bpmn2:extensionElements>
+            <ifl:property>
+                <key>namespaceMapping</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>httpSessionHandling</key>
+                <value>None</value>
+            </ifl:property>
+            <ifl:property>
+                <key>accessControlMaxAge</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>returnExceptionToSender</key>
+                <value>false</value>
+            </ifl:property>
+            <ifl:property>
+                <key>log</key>
+                <value>All events</value>
+            </ifl:property>
+            <ifl:property>
+                <key>corsEnabled</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>exposedHeaders</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>componentVersion</key>
+                <value>1.2</value>
+            </ifl:property>
+            <ifl:property>
+                <key>allowedHeaderList</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>ServerTrace</key>
+                <value>false</value>
+            </ifl:property>
+            <ifl:property>
+                <key>allowedOrigins</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>accessControlAllowCredentials</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>allowedHeaders</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>allowedMethods</key>
+                <value/>
+            </ifl:property>
+            <ifl:property>
+                <key>cmdVariantUri</key>
+                <value>ctype::IFlowVariant/cname::IFlowConfiguration/version::1.2.3</value>
+            </ifl:property>
+        </bpmn2:extensionElements>
+        <bpmn2:participant id="Participant_1" ifl:type="EndpointSender" name="Sender">
+            <bpmn2:extensionElements>
+                <ifl:property>
+                    <key>enableBasicAuthentication</key>
+                    <value>false</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>ifl:type</key>
+                    <value>EndpointSender</value>
+                </ifl:property>
+            </bpmn2:extensionElements>
+        </bpmn2:participant>
+        <bpmn2:participant id="Participant_2" ifl:type="EndpointRecevier" name="Receiver">
+            <bpmn2:extensionElements>
+                <ifl:property>
+                    <key>ifl:type</key>
+                    <value>EndpointRecevier</value>
+                </ifl:property>
+            </bpmn2:extensionElements>
+        </bpmn2:participant>
+        <bpmn2:participant id="Participant_Process_1" ifl:type="IntegrationProcess" name="Integration Process" processRef="Process_1">
+            <bpmn2:extensionElements/>
+        </bpmn2:participant>
+        <bpmn2:messageFlow id="MessageFlow_4" name="HTTPS" sourceRef="Participant_1" targetRef="StartEvent_2">
+            <bpmn2:extensionElements>
+                <ifl:property>
+                    <key>ComponentType</key>
+                    <value>HTTPS</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>Description</key>
+                    <value/>
+                </ifl:property>
+                <ifl:property>
+                    <key>maximumBodySize</key>
+                    <value>40</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>ComponentNS</key>
+                    <value>sap</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>componentVersion</key>
+                    <value>1.4</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>urlPath</key>
+                    <value>{{Sender_Path}}</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>Name</key>
+                    <value>HTTPS</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>TransportProtocolVersion</key>
+                    <value>1.4.3</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>ComponentSWCVName</key>
+                    <value>external</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>system</key>
+                    <value>Sender</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>xsrfProtection</key>
+                    <value>0</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>TransportProtocol</key>
+                    <value>HTTPS</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>cmdVariantUri</key>
+                    <value>ctype::AdapterVariant/cname::sap:HTTPS/tp::HTTPS/mp::None/direction::Sender/version::1.4.3</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>userRole</key>
+                    <value>ESBMessaging.send</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>senderAuthType</key>
+                    <value>RoleBased</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>MessageProtocol</key>
+                    <value>None</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>MessageProtocolVersion</key>
+                    <value>1.4.3</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>ComponentSWCVId</key>
+                    <value>1.4.3</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>direction</key>
+                    <value>Sender</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>clientCertificates</key>
+                    <value/>
+                </ifl:property>
+            </bpmn2:extensionElements>
+        </bpmn2:messageFlow>
+        <bpmn2:messageFlow id="MessageFlow_7" name="HTTP" sourceRef="ServiceTask_1" targetRef="Participant_2">
+            <bpmn2:extensionElements>
+                <ifl:property>
+                    <key>Description</key>
+                    <value/>
+                </ifl:property>
+                <ifl:property>
+                    <key>methodSourceExpression</key>
+                    <value/>
+                </ifl:property>
+                <ifl:property>
+                    <key>ComponentNS</key>
+                    <value>sap</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>privateKeyAlias</key>
+                    <value/>
+                </ifl:property>
+                <ifl:property>
+                    <key>httpMethod</key>
+                    <value>{{Receiver_Method}}</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>Name</key>
+                    <value>HTTP</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>TransportProtocolVersion</key>
+                    <value>1.7.2</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>ComponentSWCVName</key>
+                    <value>external</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>proxyPort</key>
+                    <value/>
+                </ifl:property>
+                <ifl:property>
+                    <key>httpAddressQuery</key>
+                    <value>{{Receiver_Query}}</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>httpRequestTimeout</key>
+                    <value>{{Receiver_Timeout}}</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>MessageProtocol</key>
+                    <value>None</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>ComponentSWCVId</key>
+                    <value>1.7.2</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>direction</key>
+                    <value>Receiver</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>ComponentType</key>
+                    <value>HTTP</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>httpShouldSendBody</key>
+                    <value>true</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>proxyType</key>
+                    <value>{{Receiver_Proxy_Type}}</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>componentVersion</key>
+                    <value>1.7</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>proxyHost</key>
+                    <value/>
+                </ifl:property>
+                <ifl:property>
+                    <key>system</key>
+                    <value>Receiver</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>authenticationMethod</key>
+                    <value>{{Receiver_Authentication}}</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>locationID</key>
+                    <value>{{Receiver_Location_ID}}</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>TransportProtocol</key>
+                    <value>HTTP</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>cmdVariantUri</key>
+                    <value>ctype::AdapterVariant/cname::sap:HTTP/tp::HTTP/mp::None/direction::Receiver/version::1.7.2</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>credentialName</key>
+                    <value>{{Receiver_Credential_Name}}</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>MessageProtocolVersion</key>
+                    <value>1.7.2</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>httpAddressWithoutQuery</key>
+                    <value>{{Receiver_Address}}</value>
+                </ifl:property>
+            </bpmn2:extensionElements>
+        </bpmn2:messageFlow>
+    </bpmn2:collaboration>
+    <bpmn2:process id="Process_1" name="Integration Process">
+        <bpmn2:extensionElements>
+            <ifl:property>
+                <key>transactionTimeout</key>
+                <value>30</value>
+            </ifl:property>
+            <ifl:property>
+                <key>componentVersion</key>
+                <value>1.2</value>
+            </ifl:property>
+            <ifl:property>
+                <key>cmdVariantUri</key>
+                <value>ctype::FlowElementVariant/cname::IntegrationProcess/version::1.2.1</value>
+            </ifl:property>
+            <ifl:property>
+                <key>transactionalHandling</key>
+                <value>Not Required</value>
+            </ifl:property>
+        </bpmn2:extensionElements>
+        <bpmn2:startEvent id="StartEvent_2" name="Start">
+            <bpmn2:extensionElements>
+                <ifl:property>
+                    <key>componentVersion</key>
+                    <value>1.0</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>cmdVariantUri</key>
+                    <value>ctype::FlowstepVariant/cname::MessageStartEvent/version::1.0</value>
+                </ifl:property>
+            </bpmn2:extensionElements>
+            <bpmn2:outgoing>SequenceFlow_3</bpmn2:outgoing>
+            <bpmn2:messageEventDefinition/>
+        </bpmn2:startEvent>
+        <bpmn2:endEvent id="EndEvent_2" name="End">
+            <bpmn2:extensionElements>
+                <ifl:property>
+                    <key>componentVersion</key>
+                    <value>1.1</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>cmdVariantUri</key>
+                    <value>ctype::FlowstepVariant/cname::MessageEndEvent/version::1.1.0</value>
+                </ifl:property>
+            </bpmn2:extensionElements>
+            <bpmn2:incoming>SequenceFlow_6</bpmn2:incoming>
+            <bpmn2:messageEventDefinition/>
+        </bpmn2:endEvent>
+        <bpmn2:serviceTask id="ServiceTask_1" name="Request Reply 1">
+            <bpmn2:extensionElements>
+                <ifl:property>
+                    <key>componentVersion</key>
+                    <value>1.0</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>activityType</key>
+                    <value>ExternalCall</value>
+                </ifl:property>
+                <ifl:property>
+                    <key>cmdVariantUri</key>
+                    <value>ctype::FlowstepVariant/cname::ExternalCall/version::1.0.4</value>
+                </ifl:property>
+            </bpmn2:extensionElements>
+            <bpmn2:incoming>SequenceFlow_3</bpmn2:incoming>
+            <bpmn2:outgoing>SequenceFlow_6</bpmn2:outgoing>
+        </bpmn2:serviceTask>
+        <bpmn2:sequenceFlow id="SequenceFlow_3" sourceRef="StartEvent_2" targetRef="ServiceTask_1"/>
+        <bpmn2:sequenceFlow id="SequenceFlow_6" sourceRef="ServiceTask_1" targetRef="EndEvent_2"/>
+    </bpmn2:process>
+    <bpmndi:BPMNDiagram id="BPMNDiagram_1" name="Default Collaboration Diagram">
+        <bpmndi:BPMNPlane bpmnElement="Collaboration_1" id="BPMNPlane_1">
+            <bpmndi:BPMNShape bpmnElement="EndEvent_2" id="BPMNShape_EndEvent_2">
+                <dc:Bounds height="32.0" width="32.0" x="703.0" y="142.0"/>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="StartEvent_2" id="BPMNShape_StartEvent_2">
+                <dc:Bounds height="32.0" width="32.0" x="292.0" y="142.0"/>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="ServiceTask_1" id="BPMNShape_ServiceTask_1">
+                <dc:Bounds height="60.0" width="100.0" x="412.0" y="132.0"/>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="Participant_2" id="BPMNShape_Participant_2">
+                <dc:Bounds height="140.0" width="100.0" x="900.0" y="100.0"/>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="Participant_1" id="BPMNShape_Participant_1">
+                <dc:Bounds height="140.0" width="100.0" x="40.0" y="100.0"/>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNShape bpmnElement="Participant_Process_1" id="BPMNShape_Participant_Process_1">
+                <dc:Bounds height="220.0" width="540.0" x="250.0" y="60.0"/>
+            </bpmndi:BPMNShape>
+            <bpmndi:BPMNEdge bpmnElement="SequenceFlow_6" id="BPMNEdge_SequenceFlow_6" sourceElement="BPMNShape_ServiceTask_1" targetElement="BPMNShape_EndEvent_2">
+                <di:waypoint x="462.0" xsi:type="dc:Point" y="160.0"/>
+                <di:waypoint x="719.0" xsi:type="dc:Point" y="160.0"/>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="SequenceFlow_3" id="BPMNEdge_SequenceFlow_3" sourceElement="BPMNShape_StartEvent_2" targetElement="BPMNShape_ServiceTask_1">
+                <di:waypoint x="308.0" xsi:type="dc:Point" y="160.0"/>
+                <di:waypoint x="462.0" xsi:type="dc:Point" y="160.0"/>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="MessageFlow_4" id="BPMNEdge_MessageFlow_4" sourceElement="BPMNShape_Participant_1" targetElement="BPMNShape_StartEvent_2">
+                <di:waypoint x="90.0" xsi:type="dc:Point" y="170.0"/>
+                <di:waypoint x="308.0" xsi:type="dc:Point" y="158.0"/>
+            </bpmndi:BPMNEdge>
+            <bpmndi:BPMNEdge bpmnElement="MessageFlow_7" id="BPMNEdge_MessageFlow_7" sourceElement="BPMNShape_ServiceTask_1" targetElement="BPMNShape_Participant_2">
+                <di:waypoint x="462.0" xsi:type="dc:Point" y="162.0"/>
+                <di:waypoint x="950.0" xsi:type="dc:Point" y="170.0"/>
+            </bpmndi:BPMNEdge>
+        </bpmndi:BPMNPlane>
+    </bpmndi:BPMNDiagram>
+</bpmn2:definitions>

package/src/integration-tools.mjs

@@ -0,0 +1,27 @@
+// MCP tools for SAP Integration Suite: Cloud Integration (CPI) and API Management (APIM).
+// Writes cover create, update, deploy and undeploy — there are no delete tools — and every write
+// checks an exact confirmation string before any network call. Secrets are write-only.
+import { z } from 'zod';
+import { apimToolNames, registerApimTools } from './apim-tools.mjs';
+import { cpiToolNames, registerCpiTools } from './cpi-tools.mjs';
+import { READ_ONLY_ANNOTATIONS, resultOf } from './integration-common.mjs';
+
+export { INTEGRATION_MAX_OUTPUT_BYTES } from './integration-common.mjs';
+
+export const INTEGRATION_TOOL_NAMES = Object.freeze(['integration_connection_info', ...cpiToolNames(), ...apimToolNames()]);
+
+/** Register Integration Suite tools; cpi_* and apim_* only appear when their client is configured. */
+export function registerIntegrationTools(server, { cpi, apim, summary, verify, pollIntervalMs = 2000, readBackDelayMs = 5000 } = {}) {
+  const register = (name, title, description, inputSchema, annotations, handler) => {
+    server.registerTool(name, { title, description, inputSchema, annotations }, async args => resultOf(() => handler(args)));
+  };
+
+  register('integration_connection_info', 'Integration Suite connection info',
+    'Return which Integration Suite services (CPI, APIM) are configured, their credential source and tenant hosts. With verify: true it also signs in and runs one read 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 via an API proxy bundle export) and reports areas whose role is missing. Never returns client ids or secrets.',
+    { verify: z.boolean().default(false) },
+    READ_ONLY_ANNOTATIONS,
+    async ({ verify: online }) => (online && verify ? { ...summary, verification: await verify() } : summary));
+
+  if (cpi) registerCpiTools(register, cpi, { pollIntervalMs });
+  if (apim) registerApimTools(register, apim, { readBackDelayMs });
+}

package/src/integration-verify.mjs

@@ -0,0 +1,118 @@
+// Online check of CPI/APIM credentials: sign in, then one read-only request per tool area so a
+// missing role shows up as a named area instead of a failing tool call later. Never writes.
+import { createServiceClient } from './integration-http.mjs';
+
+const CSRF_PATHS = Object.freeze({ CPI: '/api/v1/', APIM: '/apiportal/api/1.0/Management.svc/' });
+const APIM_BASE = '/apiportal/api/1.0/Management.svc';
+
+const PROBES = Object.freeze({
+  CPI: [
+    { area: 'Packages and iFlows', path: '/api/v1/IntegrationPackages', query: { $top: 1 }, core: true },
+    { area: 'Deployed artifacts', path: '/api/v1/IntegrationRuntimeArtifacts', query: { $top: 1 } },
+    { area: 'Message logs', path: '/api/v1/MessageProcessingLogs', query: { $top: 1 } },
+    { area: 'Security material', path: '/api/v1/UserCredentials' },
+    { area: 'Number ranges', path: '/api/v1/NumberRanges' },
+    { area: 'Partner Directory', path: '/api/v1/StringParameters', query: { $top: 1 } },
+    { area: 'Data stores', path: '/api/v1/DataStores' },
+    { area: 'JMS queues', path: "/api/v1/JmsBrokers('Broker1')" }
+  ],
+  APIM: [
+    { area: 'API proxies', path: `${APIM_BASE}/APIProxies`, query: { $top: 1, $select: 'name' }, core: true },
+    { area: 'API providers', path: `${APIM_BASE}/APIProviders`, query: { $top: 1, $select: 'name' } },
+    { area: 'API products', path: `${APIM_BASE}/APIProducts`, query: { $top: 1, $select: 'name' } },
+    { area: 'Key value maps', path: `${APIM_BASE}/KeyMapEntries`, query: { $top: 1, $select: 'name' } },
+    { area: 'Virtual hosts', path: `${APIM_BASE}/VirtualHosts` }
+  ]
+});
+
+// Statuses accepted as answers so they can be classified instead of thrown.
+const OBSERVED = [200, 204, 400, 401, 403, 404, 405, 500, 501, 502, 503, 504];
+
+function classify(status) {
+  if (status >= 200 && status < 300) return { result: 'ok', detail: 'readable' };
+  if (status === 401 || status === 403) return { result: 'forbidden', detail: `HTTP ${status}: the service key lacks the role for this area` };
+  if (status === 404 || status === 501) return { result: 'unavailable', detail: `HTTP ${status}: not available on this tenant or plan` };
+  return { result: 'error', detail: `HTTP ${status}` };
+}
+
+/** OAuth clients for the resolved CPI/APIM config (null for an unconfigured side). */
+export function createIntegrationClients(config, { env = process.env, fetchImpl } = {}) {
+  const clientFor = (label, side) => (side
+    ? createServiceClient({
+      label,
+      url: side.url,
+      tokenUrl: side.tokenUrl,
+      clientId: side.clientId,
+      clientSecret: side.clientSecret,
+      csrfPath: CSRF_PATHS[label],
+      env,
+      ...(fetchImpl ? { fetchImpl } : {})
+    })
+    : null);
+  return { cpi: clientFor('CPI', config?.cpi), apim: clientFor('APIM', config?.apim) };
+}
+
+// Policies are attached by exporting the proxy bundle (Transport.svc), editing it and re-importing it.
+// The export of an existing proxy proves the read half without writing; no proxy means nothing to test.
+async function policyCheck(client, coreText) {
+  const area = 'Policies (proxy bundle export)';
+  let name;
+  try {
+    const parsed = JSON.parse(coreText);
+    name = (parsed?.d?.results ?? parsed?.d ?? parsed?.value ?? [])[0]?.name;
+  } catch {
+    // Unparseable list: reported as unavailable below.
+  }
+  if (typeof name !== 'string' || !name) return { area, status: null, result: 'unavailable', detail: 'no API proxy exists yet to test the export with' };
+  try {
+    const { status, data } = await client.request('GET', '/apiportal/api/1.0/Transport.svc/APIProxies', {
+      query: { name }, expect: OBSERVED, withStatus: true, responseType: 'bytes', accept: 'application/zip, application/octet-stream'
+    });
+    const zip = data instanceof Uint8Array && data[0] === 0x50 && data[1] === 0x4b;
+    if (status >= 200 && status < 300 && !zip) return { area, status, result: 'error', detail: `HTTP ${status} but the export is not a zip bundle` };
+    return { area, status, ...classify(status) };
+  } catch (error) {
+    return { area, status: null, result: 'error', detail: String(error?.message || 'request failed').slice(0, 300) };
+  }
+}
+
+async function verifySide(label, client) {
+  if (!client) return { configured: false };
+  const probes = PROBES[label];
+  const run = async probe => {
+    try {
+      const { status, data } = await client.request('GET', probe.path, { query: probe.query, expect: OBSERVED, withStatus: true, responseType: 'text', accept: 'application/json' });
+      return { area: probe.area, status, ...classify(status), text: data };
+    } catch (error) {
+      return { area: probe.area, status: null, result: 'error', detail: String(error?.message || 'request failed').slice(0, 300) };
+    }
+  };
+  const { text: coreText, ...core } = await run(probes[0]);
+  // The core probe also fetches the token: a thrown request is a token or network failure, reported once.
+  if (core.status === null) {
+    return { configured: true, signed_in: false, ok: false, error: core.detail, checks: [] };
+  }
+  const others = probes.slice(1).map(run);
+  if (label === 'APIM' && core.result === 'ok') others.push(policyCheck(client, coreText));
+  const checks = [core, ...(await Promise.all(others)).map(({ text, ...check }) => check)];
+  return { configured: true, signed_in: true, ok: core.result === 'ok', checks };
+}
+
+/** Verify the configured sides online; `ok` means every configured side signed in and passed its core read. */
+export async function verifyIntegrationClients({ cpi, apim } = {}) {
+  const [cpiResult, apimResult] = await Promise.all([verifySide('CPI', cpi), verifySide('APIM', apim)]);
+  const sides = [cpiResult, apimResult].filter(side => side.configured);
+  return { ok: sides.length > 0 && sides.every(side => side.ok), cpi: cpiResult, apim: apimResult };
+}
+
+/** Human-readable lines for one verified side (no secrets: only host, area names and HTTP statuses). */
+export function verificationLines(label, host, side) {
+  if (!side?.configured) return [];
+  if (!side.signed_in) return [`✗ ${label} ${host}: sign-in failed — ${side.error}`];
+  const lines = [`${side.ok ? '✓' : '✗'} ${label} ${host}: signed in`];
+  for (const check of side.checks) {
+    const mark = check.result === 'ok' ? '✓' : (check.result === 'unavailable' ? '–' : '✗');
+    lines.push(`    ${mark} ${check.area}${check.result === 'ok' ? '' : ` — ${check.detail}`}`);
+  }
+  return lines;
+}

package/src/launcher.mjs

@@ -10,7 +10,7 @@ import { adtBaseUrl, adtPort, detectAdtUrl, discoverSapGuiSystems, hasExplicitPo
 import { binaryTarget, cacheDirectory, downloadBinary, findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
 import { configuredVersionHandoff, installMcpConfig, npxPackageLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
-import { runSetup } from './setup.mjs';
+import { runIntegrationSuiteSetup, runSetup } from './setup.mjs';
 import { runHarnessSetup } from './harness-setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { createTlsServerNameAdtProxy } from './tls-adt-proxy.mjs';
@@ -37,6 +37,7 @@ function usage() {
     'Options:',
     '  --setup                  Configure generated BAS MCP servers',
     '  --tools                  Also offer full-stack SAP companion MCP servers (use with --setup)',
+    '  --setup-integration      Only set up the Integration Suite MCP server: paste CPI/APIM service keys and verify them online',
     '  --npx                    Launch configured MCP servers through the pinned npm package (use with --setup)',
     '  --list-destinations      List discovered BAS destinations',
     '  --list-destinations --json  Print redacted JSON status',
@@ -369,6 +370,7 @@ async function configuredLocalSapGuiDestination(env) {
 }
 
 async function main() {
+  const setupIntegration = hasFlag('--setup-integration');
   const setup = hasFlag('--setup');
   const check = hasFlag('--check');
   const list = hasFlag('--list-destinations');
@@ -378,7 +380,7 @@ async function main() {
     process.stdout.write(usage());
     return;
   }
-  if (!setup && !check && !list && !doctor && !demo && await handOffToConfiguredVersion()) return;
+  if (!setup && !setupIntegration && !check && !list && !doctor && !demo && await handOffToConfiguredVersion()) return;
   if (doctor && demo) throw new Error('Use either --doctor or --demo, not both.');
   if (demo) {
     await runOfflineDemo();
@@ -407,6 +409,16 @@ async function main() {
     if (!report.ok) process.exitCode = 1;
     return;
   }
+  if (setupIntegration) {
+    const options = {};
+    if (hasFlag('--npx')) {
+      const launcher = npxPackageLauncher(pkg.version);
+      options.install = (selected, installOptions) => installMcpConfig(selected, { ...installOptions, ...launcher });
+    }
+    const result = await runIntegrationSuiteSetup(options);
+    if (!result?.skipped) await runHarnessSetup(result?.servers, { env: runtimeEnv, root });
+    return;
+  }
   if (setup) {
     const setupOptions = {
       includeSapDevelopmentToolsPrompt: hasFlag('--tools') || hasFlag('--companion-tools'),

package/src/mcp-config.mjs

@@ -12,7 +12,7 @@ const LEGACY_MCP_SERVER_PREFIXES = ['sapAiDev_', 'basVspMcp_'];
 const COMPANION_SERVER_KIND = 'sap-development-companion';
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 
-// The self-package companion (HANA inspector) must launch the exact version
+// The self-package companions (HANA inspector, Integration Suite) must launch the exact version
 // the user installed; an unpinned `npx sap-ai-dev-toolkit` would re-resolve
 // executable code from the registry at every MCP host start.
 let selfPackageVersion;
@@ -67,6 +67,15 @@ export const SAP_DEVELOPMENT_MCP_SERVERS = Object.freeze([
     bin: 'sap-ai-hana',
     ignoreScripts: true,
     priority: 'optional'
+  }),
+  Object.freeze({
+    id: 'integration-suite',
+    name: 'Integration Suite (CPI + API Management)',
+    description: 'Build, deploy and monitor Cloud Integration content and manage API Management providers, proxies, policies, products and key value maps, using service keys from the host environment or pasted and verified with sap-ai-dev --setup-integration.',
+    packageName: 'sap-ai-dev-toolkit',
+    bin: 'sap-ai-integration',
+    ignoreScripts: true,
+    priority: 'optional'
   })
 ]);
 
@@ -596,7 +605,11 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
   // instead of failing the whole setup (self-healing).
   const config = await readConfig(path, { recoverInvalid: true, warnings: installWarnings });
   const selfVersion = await runningPackageVersion();
-  const companionVersions = selfVersion ? { 'sap-ai-dev-toolkit': selfVersion, 'hana-cloud-inspector': selfVersion } : {};
+  // Values are full npx package specs; a bare version would become --package=<version>.
+  const selfSpec = selfVersion ? `sap-ai-dev-toolkit@${selfVersion}` : '';
+  const companionVersions = selfSpec
+    ? { 'sap-ai-dev-toolkit': selfSpec, 'hana-cloud-inspector': selfSpec, 'integration-suite': selfSpec }
+    : {};
   const generated = {
     ...buildMcpEntries(destinations, env),
     ...buildSapDevelopmentMcpEntries(options.sapDevelopmentServers || [], { packageVersions: companionVersions })
@@ -642,7 +655,9 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
     const exactManagedUpdate = managed && generatedNames.has(name)
       && destinationValue(entry.env) === generated[name]?.env?.SAP_AI_DEV_TOOLKIT_DESTINATION
       && destinationSource(entry.env) === generated[name]?.env?.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE;
-    if (additive && (managed || isCompanionServer(entry)) && !exactManagedUpdate) managedEntries.push([name, entry]);
+    // A companion that is being regenerated is replaced (version refresh), not retained as a conflict.
+    const regeneratedCompanion = isCompanionServer(entry) && generatedNames.has(name) && isCompanionServer(generated[name]);
+    if (additive && (managed || isCompanionServer(entry)) && !exactManagedUpdate && !regeneratedCompanion) managedEntries.push([name, entry]);
     else if (!managed && !isCompanionServer(entry) && !LEGACY_MCP_SERVER_PREFIXES.some(prefix => name.startsWith(prefix))) servers[name] = entry;
   }
   const retainedNames = new Set(managedEntries.map(([name]) => name));