sap-ai-dev-toolkit 0.9.9913 → 0.9.9915

package/src/setup.mjs

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { platform } from 'node:os';
@@ -7,6 +8,10 @@ import { discoverDestinations, remediation } from './bas-discovery.mjs';
 import { adtBaseUrl, adtPort, defaultAdtUrl, discoverSapGuiSystems, hasExplicitPort, hasPathPrefix, messageServerAppServers } from './local-sap-gui.mjs';
 import { discoverCloudFoundryDestinations, getCloudFoundryTarget, deleteManagedCloudFoundryServiceKeys, findOrphanedCloudFoundryServiceKeys } from './cf-destination.mjs';
 import { SAP_DEVELOPMENT_MCP_SERVERS, collectCloudFoundryKeyReferencesFromAllEntries, collectManagedCloudFoundryKeyReferences, installMcpConfig, readMcpConfig, resolveMcpConfigPath } from './mcp-config.mjs';
+import { parseIntegrationServiceKey, resolveIntegrationConfig, resolveIntegrationSideFromEnvironment } from './integration-config.mjs';
+import { readStoredIntegrationKeys, storeIntegrationKey } from './integration-credentials.mjs';
+import { INTEGRATION_CF_SERVICES, createIntegrationInstance, findIntegrationInstances, integrationServiceKey } from './cf-integration.mjs';
+import { createIntegrationClients, verificationLines, verifyIntegrationClients } from './integration-verify.mjs';
 import { discoverCertificateDnsNames } from './tls-adt-proxy.mjs';
 import { findRemoteControllableSsoBrowsers } from './sso-browsers.mjs';
 
@@ -268,14 +273,286 @@ function warnSsoIpHost(destination, label, output) {
   print(output, formatStatus(`${label} uses an IP address; SSO needs the DNS host name for Kerberos and the browser certificate check. Enter the host name if the sign-in fails.`, 'warning', output, 'SSO'));
 }
 
-async function confirmPrompt(message, { input = stdin, output = stdout } = {}) {
+async function confirmPrompt(message, { input = stdin, output = stdout, defaultYes = true } = {}) {
   const answer = await textPrompt({
     message,
-    placeholder: 'y',
+    placeholder: defaultYes ? 'y' : 'n',
     required: false,
     validate: value => /^(?:|y|yes|n|no)$/i.test(String(value || '').trim()) || 'Enter y or n.'
   }, { input, output });
-  return !/^n(?:o)?$/i.test(String(answer || '').trim());
+  const trimmed = String(answer || '').trim();
+  if (!trimmed) return defaultYes;
+  return !/^n(?:o)?$/i.test(trimmed);
+}
+
+// Credential status for the Integration Suite companion, without exposing any value: which sides
+// (CPI, APIM) resolve from this environment or the stored-key file, and from which source.
+export function integrationSuiteCredentialStatus(env = process.env) {
+  try {
+    const config = resolveIntegrationConfig(env, { stored: readStoredIntegrationKeys(env) });
+    const side = value => (value ? `configured from ${value.source}${value.bindingName ? ` (${value.bindingName})` : ''}, host ${new URL(value.url).host}` : 'not configured');
+    return { found: true, config, lines: [`CPI: ${side(config.cpi)}`, `APIM: ${side(config.apim)}`] };
+  } catch (error) {
+    const message = String(error?.message || '');
+    if (/^Configure CPI/.test(message)) return { found: false, config: null, lines: ['No CPI or APIM credentials were found in this environment.'] };
+    return { found: false, config: null, lines: [`Credentials found but not usable: ${message}`] };
+  }
+}
+
+function defaultVerifyIntegration(config, { env }) {
+  return verifyIntegrationClients(createIntegrationClients(config, { env }));
+}
+
+/** Read a pasted service key: JSON text (line breaks from a multi-line paste are dropped) or a path to a .json file. */
+function pastedServiceKey(side, value, env) {
+  const trimmed = String(value || '').trim();
+  let text = trimmed;
+  if (!trimmed.startsWith('{')) {
+    const path = trimmed.replace(/^~(?=$|[\\/])/, env.HOME || env.USERPROFILE || '~');
+    try {
+      text = readFileSync(path, 'utf8');
+    } catch {
+      throw new Error('Paste the service key JSON (starting with {) or the path to a readable .json file.');
+    }
+  }
+  return parseIntegrationServiceKey(side, text);
+}
+
+async function printIntegrationVerification(config, { env, output, verifyIntegration }) {
+  const stop = startProgress('Signing in to Integration Suite and checking each tool area', { output, env, label: 'Integration Suite' });
+  let report;
+  try {
+    report = await verifyIntegration(config, { env });
+  } finally {
+    stop();
+  }
+  const host = side => (config[side] ? new URL(config[side].url).host : '');
+  for (const line of [...verificationLines('CPI', host('cpi'), report.cpi), ...verificationLines('APIM', host('apim'), report.apim)]) print(output, `  ${line}`);
+  const missing = [report.cpi, report.apim].flatMap(side => side?.checks || []).filter(check => check.result === 'forbidden').length;
+  if (report.ok) {
+    print(output, formatStatus(`Integration Suite credentials verified${missing ? `; ${missing} area${missing === 1 ? ' needs' : 's need'} an extra role on the service key` : ''}.`, missing ? 'warning' : 'success', output, 'Integration Suite'));
+  } else {
+    const signedIn = [report.cpi, report.apim].some(side => side?.signed_in);
+    print(output, formatStatus(signedIn
+      ? 'The key signs in but lacks the roles for the core area; use an instance with the needed roles (the Cloud Foundry option can create one) or replace the key.'
+      : 'Integration Suite sign-in failed; fix or replace the service key before using the tools.', 'warning', output, 'Integration Suite'));
+  }
+  return report;
+}
+
+const defaultIntegrationCloudFoundry = Object.freeze({
+  getTarget: getCloudFoundryTarget,
+  findInstances: findIntegrationInstances,
+  serviceKey: integrationServiceKey,
+  createInstance: createIntegrationInstance
+});
+
+const SIDE_LABELS = Object.freeze({ CPI: 'Cloud Integration (CPI)', APIM: 'API Management' });
+
+function cfFailure(error) {
+  const detail = String(error?.stderr || error?.message || '').replace(/\s+/g, ' ').trim();
+  return detail ? detail.slice(0, 300) : 'Cloud Foundry CLI command failed';
+}
+
+// Verify one side's key online, then save it user-only. A key that cannot sign in is saved only when confirmed.
+async function acceptIntegrationKey(side, config, { env, input, output, verifyIntegration }) {
+  const choice = side.toLowerCase();
+  const report = await printIntegrationVerification({ [choice]: config }, { env, output, verifyIntegration });
+  if (!report[choice].signed_in && !await confirmPrompt('Save this key anyway? (y/n, Enter=no)', { input, output, defaultYes: false })) return { saved: false, report };
+  const path = await storeIntegrationKey(side, config, env);
+  print(output, formatStatus(`Saved the ${side} key to ${path} (readable only by you; not written to mcp.json).`, 'success', output, 'Integration Suite'));
+  let fromEnvironment = null;
+  try {
+    fromEnvironment = resolveIntegrationSideFromEnvironment(env, side);
+  } catch {
+    // A broken environment value is reported by the status lines.
+  }
+  if (fromEnvironment) print(output, formatStatus(`${side} credentials from ${fromEnvironment.source} in this environment take precedence over the saved key.`, 'warning', output, 'Integration Suite'));
+  return { saved: true, report };
+}
+
+function lacksRoles(side) {
+  return Boolean(side?.signed_in) && (!side.ok || side.checks.some(check => check.result === 'forbidden'));
+}
+
+async function cloudFoundryStep(message, operation, { env, output }) {
+  const stop = startProgress(message, { output, env, label: 'Cloud Foundry' });
+  try {
+    return await operation();
+  } finally {
+    stop();
+  }
+}
+
+// Key from an instance: reuse or create the toolkit's service key, then verify and save it.
+async function useCloudFoundryInstance(side, instanceName, context) {
+  const { env, output, cloudFoundry } = context;
+  const key = await cloudFoundryStep(`Reading service key ${instanceName}/sap-ai-dev-integration`, () => cloudFoundry.serviceKey(instanceName, { env }), context);
+  print(output, formatStatus(`${key.created ? 'Created' : 'Reusing'} service key ${key.keyName} on ${instanceName}.`, 'info', output, 'Cloud Foundry'));
+  return acceptIntegrationKey(side, parseIntegrationServiceKey(side, key.credentials), context);
+}
+
+async function createDedicatedInstance(side, context) {
+  const { env, output, cloudFoundry } = context;
+  const service = INTEGRATION_CF_SERVICES[side];
+  try {
+    await cloudFoundryStep(`Creating ${service.offering}/${service.plan} instance ${service.dedicatedInstance}`, () => cloudFoundry.createInstance(side, { env }), context);
+  } catch (error) {
+    print(output, formatStatus(`Could not create ${service.dedicatedInstance}: ${cfFailure(error)}`, 'warning', output, 'Cloud Foundry'));
+    return null;
+  }
+  print(output, formatStatus(`Created service instance ${service.dedicatedInstance}.`, 'success', output, 'Cloud Foundry'));
+  return useCloudFoundryInstance(side, service.dedicatedInstance, context);
+}
+
+// Use the logged-in CF space: per side pick the matching instance (or offer to create a dedicated one with the
+// roles the tools need), reuse or create the toolkit's service key, verify it online and save it.
+async function useCloudFoundrySpace(target, context) {
+  const { env, input, output, cloudFoundry } = context;
+  let instances;
+  try {
+    instances = await cloudFoundryStep('Looking for Integration Suite service instances in the CF space', () => cloudFoundry.findInstances({ env, spaceGuid: target.spaceGuid }), context);
+  } catch (error) {
+    print(output, formatStatus(`Could not list service instances: ${cfFailure(error)}`, 'warning', output, 'Cloud Foundry'));
+    return;
+  }
+  for (const side of ['CPI', 'APIM']) {
+    const service = INTEGRATION_CF_SERVICES[side];
+    const candidates = instances[side] || [];
+    print(output, '');
+    if (!candidates.length) {
+      print(output, formatStatus(`No ${service.label} instance with plan ${service.plan} (${service.offering}) in this space.`, 'info', output, SIDE_LABELS[side]));
+      if (await confirmPrompt(`Create instance ${service.dedicatedInstance} (${service.offering}, plan ${service.plan}) with the roles the tools need? (y/n, Enter=no)`, { input, output, defaultYes: false })) {
+        await createDedicatedInstance(side, context);
+      }
+      continue;
+    }
+    const dedicated = candidates.find(candidate => candidate.name === service.dedicatedInstance);
+    const instanceName = candidates.length === 1 ? candidates[0].name : await selectPrompt({
+      message: colorText(`☁️ ${SIDE_LABELS[side]}: choose the ${service.offering}/${service.plan} instance to use`, 'cyan', output),
+      defaultValue: (dedicated || candidates[0]).name,
+      choices: [...candidates.map(candidate => ({ name: candidate.name, value: candidate.name })), { name: 'Skip', value: '', shortcut: 's' }]
+    }, { input, output });
+    if (!instanceName) continue;
+    let result;
+    try {
+      result = await useCloudFoundryInstance(side, instanceName, context);
+    } catch (error) {
+      print(output, formatStatus(`Could not use ${instanceName}: ${cfFailure(error)}`, 'warning', output, SIDE_LABELS[side]));
+      continue;
+    }
+    const sideReport = result.report[side.toLowerCase()];
+    if (instanceName !== service.dedicatedInstance && !dedicated && lacksRoles(sideReport)) {
+      print(output, `  The roles of ${instanceName} are fixed on the instance; a new key cannot add them.`);
+      print(output, `  A dedicated instance gets: ${service.parameters.roles ? service.parameters.roles.join(', ') : service.parameters.role}.`);
+      if (await confirmPrompt(`Create instance ${service.dedicatedInstance} with these roles and use it instead? (y/n, Enter=no)`, { input, output, defaultYes: false })) {
+        await createDedicatedInstance(side, context);
+      }
+    }
+  }
+}
+
+// Verify the detected credentials online and let the user take CPI/APIM keys from the logged-in CF space or
+// paste them. A key is checked online first and saved to the user-only store (never to mcp.json); it is used
+// when the environment has no key.
+async function configureIntegrationCredentials({ env, input, output, verifyIntegration, cloudFoundry = defaultIntegrationCloudFoundry }) {
+  let status = integrationSuiteCredentialStatus(env);
+  if (status.found) await printIntegrationVerification(status.config, { env, output, verifyIntegration });
+  let target = { available: false };
+  try {
+    target = await cloudFoundryStep('Checking the Cloud Foundry login', () => cloudFoundry.getTarget({ env }), { env, output });
+  } catch {
+    // No CF CLI or no login: the CF option is simply not offered.
+  }
+  const context = { env, input, output, verifyIntegration, cloudFoundry };
+  for (;;) {
+    print(output, '');
+    const space = target.available ? [target.orgName, target.spaceName].filter(Boolean).join(' / ') || target.spaceGuid : '';
+    const choice = await selectPrompt({
+      message: colorText('🔑 Integration Suite credentials', 'cyan', output),
+      defaultValue: status.found ? 'done' : (target.available ? 'cf' : 'cpi'),
+      choices: [
+        { name: status.found ? 'Continue' : 'Continue without credentials (the server will not start until a key is configured)', value: 'done', shortcut: 'c' },
+        ...(target.available ? [{ name: `Use the logged-in Cloud Foundry space (${space}): find the instances, create or reuse service keys, verify`, value: 'cf', shortcut: 'f' }] : []),
+        { name: 'Paste a Cloud Integration (CPI) service key — Process Integration Runtime, plan api', value: 'cpi', shortcut: 'p' },
+        { name: 'Paste an API Management service key — API Management, plan apiportal-apiaccess', value: 'apim', shortcut: 'a' },
+        ...(status.found ? [{ name: 'Check the configured credentials online again', value: 'verify', shortcut: 'v' }] : [])
+      ]
+    }, { input, output });
+    if (choice === 'done') return status;
+    if (choice === 'verify') {
+      await printIntegrationVerification(status.config, { env, output, verifyIntegration });
+      continue;
+    }
+    if (choice === 'cf') {
+      await useCloudFoundrySpace(target, context);
+    } else {
+      const side = choice.toUpperCase();
+      const pasted = await textPrompt({
+        message: `Paste the ${side} service key JSON or the path to its .json file`,
+        secret: true,
+        validate: value => {
+          try {
+            pastedServiceKey(side, value, env);
+            return true;
+          } catch (error) {
+            return error.message;
+          }
+        }
+      }, { input, output });
+      await acceptIntegrationKey(side, pastedServiceKey(side, pasted, env), context);
+    }
+    status = integrationSuiteCredentialStatus(env);
+    for (const line of status.lines) print(output, `  ${line}`);
+  }
+}
+
+async function promptIntegrationSuite({ env, alreadyConfigured, input, output, verifyIntegration = defaultVerifyIntegration, integrationCloudFoundry, ask = true }) {
+  print(output, '');
+  print(output, formatStatus('SAP Integration Suite tools (Cloud Integration + API Management).', 'step', output, 'Integration Suite'));
+  print(output, '  Adds the sap-ai-integration MCP server: iFlows, value mappings, security material and monitoring in CPI; API providers, proxies, policies, products and key value maps in APIM.');
+  print(output, '  Every write needs an exact confirmation string; there are no delete tools and secrets are write-only. Agents: SAP Integration Architect, SAP Integration Developer.');
+  if (alreadyConfigured) print(output, '  Already configured in this MCP config; keeping it and refreshing its version.');
+  const status = integrationSuiteCredentialStatus(env);
+  for (const line of status.lines) print(output, `  ${line}`);
+  if (!status.found) {
+    print(output, '  The server needs CPI_SERVICE_KEY and/or APIM_SERVICE_KEY (or CPI_*/APIM_* variables, VCAP_SERVICES) in the MCP host environment,');
+    print(output, '  or a service key pasted in the next step (verified online, then saved for your user only). Credentials are never written to mcp.json.');
+  }
+  if (ask && !alreadyConfigured) {
+    print(output, '');
+    const defaultYes = status.found;
+    if (!await confirmPrompt(`Add the SAP Integration Suite tools? (y/n, Enter=${defaultYes ? 'yes' : 'no'})`, { input, output, defaultYes })) return false;
+  }
+  await configureIntegrationCredentials({ env, input, output, verifyIntegration, ...(integrationCloudFoundry ? { cloudFoundry: integrationCloudFoundry } : {}) });
+  return true;
+}
+
+/** `sap-ai-dev --setup-integration`: only the Integration Suite step (paste, verify, add the server), keeping every other MCP entry. */
+export async function runIntegrationSuiteSetup({
+  env = process.env,
+  input = stdin,
+  output = stdout,
+  install = installMcpConfig,
+  verifyIntegration = defaultVerifyIntegration,
+  integrationCloudFoundry
+} = {}) {
+  if (!input.isTTY || !output.isTTY) {
+    print(output, formatStatus('Interactive setup needs a terminal. Rerun sap-ai-dev --setup-integration from a terminal.', 'warning', output, 'SAP AI Dev Toolkit'));
+    return { skipped: true, reason: 'non-tty' };
+  }
+  let alreadyConfigured = false;
+  try {
+    alreadyConfigured = Boolean((await readMcpConfig(await resolveMcpConfigPath(env)))?.servers?.['integration-suite']);
+  } catch {
+    // A missing or unreadable config is created or healed by install.
+  }
+  await promptIntegrationSuite({ env, alreadyConfigured, input, output, verifyIntegration, integrationCloudFoundry, ask: false });
+  const result = await install([], { env, sapDevelopmentServers: ['integration-suite'], additive: true });
+  print(output, '');
+  print(output, formatStatus(`Configured the Integration Suite MCP server${result?.path ? ` in ${result.path}` : ''}.`, 'success', output, 'Integration Suite'));
+  for (const message of Array.isArray(result?.warnings) ? result.warnings : []) print(output, formatStatus(message, 'warning', output, 'Warning'));
+  return { selected: [], ...(result || {}) };
 }
 
 function buildLocalClientDestination(destination, client, authMode, { multipleClients = false, duplicateSystemName = false, browserPath } = {}) {
@@ -613,7 +890,9 @@ export async function runSetup({
   install = installMcpConfig,
   includeSapDevelopmentToolsPrompt = false,
   detectAdtUrl,
-  discoverSsoBrowsers = findRemoteControllableSsoBrowsers
+  discoverSsoBrowsers = findRemoteControllableSsoBrowsers,
+  verifyIntegration = defaultVerifyIntegration,
+  integrationCloudFoundry
 } = {}) {
   const isBas = Boolean(env.H2O_URL);
   if (!isBas && (!input.isTTY || !output.isTTY)) {
@@ -661,11 +940,13 @@ export async function runSetup({
   let configPath;
   let managedKeys = [];
   let previousAdtUrls = new Map();
+  let integrationSuiteConfigured = false;
   try {
     configPath = await resolveMcpConfigPath(env);
     const existingConfig = await readMcpConfig(configPath);
     managedKeys = collectManagedCloudFoundryKeyReferences(existingConfig);
     previousAdtUrls = previousLocalAdtUrls(existingConfig);
+    integrationSuiteConfigured = Boolean(existingConfig?.servers?.['integration-suite']);
   } catch {
     warnings.push('Existing MCP config could not be read before setup; existing CF service keys will not be reused.');
   }
@@ -750,6 +1031,7 @@ export async function runSetup({
   };
   let selected;
   let additiveSetup = false;
+  let integrationOnly = false;
   if (!selectable.length) {
     // Nothing was detected — no BAS/CF destinations, or no SAP GUI entries.
     // Offer the manual MCP entry wizard before giving up.
@@ -761,23 +1043,34 @@ export async function runSetup({
       defaultValue: 'manual',
       choices: [
         { name: '✍️  Start manual entry wizard (system name, ADT URL, client, login)', value: 'manual', shortcut: 'm' },
+        { name: '🔌 Set up only the SAP Integration Suite tools (paste and verify CPI / API Management service keys)', value: 'integration', shortcut: 'i' },
         { name: 'Exit setup without changes', value: 'exit', shortcut: 'e' }
       ]
     }, { input, output });
-    if (choice !== 'manual') return await exitWithoutDestinations();
-    selected = await runManualEntryWizard({ env, input, output, detectAdtUrl, selectSsoBrowser });
-    additiveSetup = true;
-    if (!selected.length) return await exitWithoutDestinations();
+    if (choice === 'integration') {
+      selected = [];
+      additiveSetup = true;
+      integrationOnly = true;
+    } else {
+      if (choice !== 'manual') return await exitWithoutDestinations();
+      selected = await runManualEntryWizard({ env, input, output, detectAdtUrl, selectSsoBrowser });
+      additiveSetup = true;
+      if (!selected.length) return await exitWithoutDestinations();
+    }
   } else {
     selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env, detectAdtUrl, previousAdtUrls, selectSsoBrowser });
     additiveSetup = selected.length > 0;
   }
 
   let sapDevelopmentServers = [];
-  if (includeSapDevelopmentToolsPrompt) {
+  if (integrationOnly) {
+    await promptIntegrationSuite({ env, alreadyConfigured: integrationSuiteConfigured, input, output, verifyIntegration, integrationCloudFoundry, ask: false });
+    sapDevelopmentServers = ['integration-suite'];
+  } else if (includeSapDevelopmentToolsPrompt) {
     print(output, '');
-    print(output, formatStatus('Optionally add companion MCP servers for full-stack SAP development and HANA inspection.', 'step', output, 'Tools'));
+    print(output, formatStatus('Optionally add companion MCP servers for full-stack SAP development, HANA inspection, and Integration Suite (CPI/API Management).', 'step', output, 'Tools'));
     print(output, '  HANA Cloud inspector is read-only and uses HANA_RO_* or VCAP_SERVICES already present in the MCP host environment; credentials are not written to mcp.json.');
+    print(output, '  Integration Suite uses CPI/APIM service keys from the MCP host environment or keys you paste next (verified online, saved for your user only); credentials are not written to mcp.json.');
     print(output, '  Leave empty to only configure ABAP/ADT destination servers.');
     print(output, '');
     sapDevelopmentServers = await checkboxPrompt({
@@ -785,11 +1078,17 @@ export async function runSetup({
       choices: SAP_DEVELOPMENT_MCP_SERVERS.map(server => ({
         value: server.id,
         name: `${server.name} — ${server.description}`,
-        checked: false
+        checked: server.id === 'integration-suite' && integrationSuiteConfigured
       })),
       required: false,
       shortcuts: { all: 'a' }
     }, { input, output });
+    if (sapDevelopmentServers.includes('integration-suite')) {
+      await promptIntegrationSuite({ env, alreadyConfigured: integrationSuiteConfigured, input, output, verifyIntegration, integrationCloudFoundry, ask: false });
+    }
+  } else if (await promptIntegrationSuite({ env, alreadyConfigured: integrationSuiteConfigured, input, output, verifyIntegration, integrationCloudFoundry })) {
+    // Without --tools, Integration Suite still gets its own yes/no step instead of being hidden.
+    sapDevelopmentServers = ['integration-suite'];
   }
 
   try {

package/tools.md

@@ -110,3 +110,79 @@ The optional `hana-cloud-inspector` companion starts `sap-ai-hana` as a separate
 - `hana_read_rows` — perform parameterized reads of selected columns, capped at 200 rows; credential-like columns are blocked and arbitrary SQL is not accepted.
 
 Connection secrets are read from the MCP host environment via explicit `HANA_RO_*` variables or a selected `VCAP_SERVICES` binding and are not written to `mcp.json`. TLS certificate verification is mandatory. No HANA write, DDL/DML, deploy/undeploy, grants, or service-key tools are exposed; deployment remains a user-run project workflow.
+
+## Separate optional Integration Suite server
+
+The optional `integration-suite` companion starts `sap-ai-integration` as a separate stdio MCP server for SAP Cloud Integration (CPI) and API Management (APIM). It does not use the BAS proxy or a destination prefix. Tools for a side appear only when that side is configured:
+
+- `integration_connection_info` — show which of CPI/APIM are configured, the credential source, and tenant hosts; with `verify: true` it signs in and reports per tool area whether the service key has the needed role. Never returns client ids or secrets.
+
+Cloud Integration — design time:
+
+- `cpi_list_packages` — list Cloud Integration packages.
+- `cpi_list_iflows` — list the iFlows of one package.
+- `cpi_list_package_artifacts` — list a package's iFlows, value mappings, script collections, and message mappings.
+- `cpi_get_iflow` — read iFlow metadata, externalized configuration, and bundle files (or one file by path).
+- `cpi_get_artifact` — read a value mapping, script collection, or message mapping with its bundle files.
+- `cpi_get_value_mappings` — read value-mapping agency pairs with their value and default pairs.
+- `cpi_create_package` — create a package.
+- `cpi_update_package` — change package name, short text, description, or version.
+- `cpi_copy_package` — copy a Discover package into Design (new copy with suffix, or overwrite-merge keeping configuration).
+- `cpi_create_iflow` — create an iFlow from the vetted HTTPS → Request Reply → HTTP template or caller-supplied BPMN.
+- `cpi_update_iflow` — replace/add bundle files and parameters with an expected-version check and patch-version bump.
+- `cpi_update_iflow_configuration` — set externalized configuration parameters.
+- `cpi_upsert_value_mappings` — add or change value-mapping pairs.
+- `cpi_update_script_collection` — add or replace scripts in a script collection.
+
+Cloud Integration — deployment and monitoring:
+
+- `cpi_deploy_iflow` — deploy the active iFlow version and wait for build and runtime status.
+- `cpi_deploy_artifact` — deploy a value mapping, script collection, or message mapping and wait for runtime status.
+- `cpi_undeploy_artifact` — undeploy any runtime artifact and wait until it is gone.
+- `cpi_list_runtime_artifacts` — list deployed artifacts, optionally by status.
+- `cpi_get_iflow_runtime_status` — read deployed runtime status, including error text when the iFlow failed to start.
+- `cpi_list_service_endpoints` — list deployed endpoint URLs, optionally for one iFlow.
+- `cpi_list_message_logs` — list message processing logs by iFlow, status, time window, correlation id, application message id, or custom header.
+- `cpi_get_message_log` — read one message log with error text and custom header properties; payload attachments are never read.
+- `cpi_get_message_log_steps` — read the processing steps of a message's latest run with step errors.
+- `cpi_get_jms_broker_status` — read JMS broker capacity and queues that are not healthy.
+- `cpi_list_data_stores` — list data stores with message and overdue counts.
+- `cpi_list_data_store_entries` — list entry metadata of one data store; payloads are never read.
+- `cpi_list_variables` — list global and iFlow variables (metadata only).
+
+Cloud Integration — security material and tenant configuration:
+
+- `cpi_list_security_material` — list user credentials, OAuth2 client credentials, or keystore entries with secret fields redacted.
+- `cpi_set_user_credential` — create or update a user credential; the password is write-only.
+- `cpi_set_oauth2_client_credential` — create or update an OAuth2 client credential; the client secret is write-only.
+- `cpi_upload_certificate` — add or replace a public certificate in the tenant keystore.
+- `cpi_list_number_ranges` — list number ranges.
+- `cpi_set_number_range` — create or update a number range.
+- `cpi_list_partner_parameters` — list Partner Directory string parameters and binary parameter metadata.
+- `cpi_set_partner_parameter` — create or update a Partner Directory string or binary parameter.
+- `cpi_odata_get` — guarded read-only GET for other CPI entity sets (for example access policies or JMS queues) and the service metadata.
+
+API Management:
+
+- `apim_list_api_providers` — list API providers without credential fields.
+- `apim_get_api_provider` — read one API provider with credential properties removed.
+- `apim_create_api_provider` — create an Internet or On-Premise (Cloud Connector) API provider without credentials.
+- `apim_update_api_provider` — change host, port, type, location, path prefix, or sap-client of a credential-free provider.
+- `apim_list_api_proxies` — list API proxies.
+- `apim_get_api_proxy` — read one API proxy with endpoints, virtual hosts, and the computed runtime URL.
+- `apim_export_api_proxy` — export an API proxy bundle and return its files (policies, endpoints, scripts).
+- `apim_list_virtual_hosts` — list virtual hosts.
+- `apim_create_api_proxy` — import (and thereby deploy) a policy-free API proxy for a provider or https URL target.
+- `apim_update_api_proxy` — change base path, target, title, or description; existing policies and steps are kept.
+- `apim_attach_api_proxy_policies` — add or replace policies (API key, quota, spike arrest, CORS, headers, OAuth, IP allow list, response cache, Basic auth from a key value map, raise fault, JavaScript, custom XML) and their flow steps, then redeploy.
+- `apim_list_api_products` — list API products.
+- `apim_get_api_product` — read one API product with its proxies.
+- `apim_create_api_product` — create (and by default publish) an API product over existing proxies with an optional quota.
+- `apim_update_api_product` — change product title, description, scope, quota, or publish state.
+- `apim_list_key_value_maps` — list key value maps.
+- `apim_get_key_value_map` — read one key value map; encrypted values are redacted.
+- `apim_create_key_value_map` — create a key value map; values are write-only.
+- `apim_set_key_value_map_entries` — add or change key value map entries; values are write-only.
+- `apim_odata_get` — guarded read-only GET for other Management.svc entity sets (for example applications, developers, certificate store references) and the service metadata.
+
+Credentials come from CPI/APIM OAuth client service keys in the MCP host environment (`CPI_SERVICE_KEY`/`APIM_SERVICE_KEY`, explicit `CPI_*`/`APIM_*` variables, or `VCAP_SERVICES`) and are never written to `mcp.json`. Every write requires an exact confirmation string (for example `CREATE IFLOW <iflow_id>` or `UNDEPLOY ARTIFACT <artifact_id>`) and is checked before any network call. Scope is create, update, deploy, and undeploy: there are no delete tools, and deletions stay manual in the Integration Suite UI. Secrets (passwords, client secrets, key value map values) are write-only: tools accept them as input and never return them. Message payloads, attachments, and data-store payloads are never read.