sap-ai-dev-toolkit 0.9.9913 → 0.9.9915

package/src/integration-config.mjs

@@ -0,0 +1,167 @@
+// Resolves CPI (Cloud Integration) and APIM (API Management) OAuth client
+// credentials from the MCP host environment. Pure: no I/O, no network.
+// Every error message starts with a stable prefix (Explicit CPI/APIM, CPI_,
+// APIM_, No CPI/APIM, Multiple CPI/APIM, Configure CPI) so the tool layer
+// can surface it verbatim; no message ever echoes a secret value.
+
+const SIDES = Object.freeze({
+  CPI: Object.freeze({ prefix: 'CPI', defaultVcapService: 'it-rt' }),
+  APIM: Object.freeze({ prefix: 'APIM', defaultVcapService: 'apimanagement-apiportal' })
+});
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function validateEndpoint(value, prefix, label) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    fail(`${prefix}_${label} is not a valid URL`);
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    fail(`${prefix}_${label} must not contain credentials, a query, or a fragment`);
+  }
+  const loopback = LOOPBACK_HOSTS.has(parsed.hostname);
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) {
+    fail(`${prefix}_${label} must use https`);
+  }
+  return parsed;
+}
+
+function finalize(prefix, source, bindingName, raw) {
+  const url = validateEndpoint(raw.url, prefix, 'URL').href.replace(/\/+$/, '');
+  const token = validateEndpoint(raw.tokenUrl, prefix, 'TOKEN_URL');
+  if (!/\/oauth\/token$/.test(token.pathname)) {
+    token.pathname = `${token.pathname.replace(/\/+$/, '')}/oauth/token`;
+  }
+  return Object.freeze({
+    source,
+    bindingName: bindingName || null,
+    url,
+    tokenUrl: token.href,
+    clientId: raw.clientId,
+    clientSecret: raw.clientSecret
+  });
+}
+
+function explicitConfig(env, prefix) {
+  const keys = [`${prefix}_URL`, `${prefix}_TOKEN_URL`, `${prefix}_CLIENT_ID`, `${prefix}_CLIENT_SECRET`];
+  if (!keys.some(key => env[key] !== undefined && env[key] !== '')) return null;
+  const missing = keys.filter(key => !text(env[key]));
+  if (missing.length) fail(`Explicit ${prefix} configuration is incomplete: ${missing.join(', ')}`);
+  return finalize(prefix, 'environment', null, {
+    url: text(env[`${prefix}_URL`]),
+    tokenUrl: text(env[`${prefix}_TOKEN_URL`]),
+    clientId: text(env[`${prefix}_CLIENT_ID`]),
+    clientSecret: text(env[`${prefix}_CLIENT_SECRET`])
+  });
+}
+
+/** Parse a CPI/APIM service key (nested `oauth` or flat APIM shape) into raw OAuth fields. */
+function parseServiceKey(value, origin) {
+  let key = value;
+  if (typeof value === 'string') {
+    try {
+      key = JSON.parse(value);
+    } catch {
+      fail(`${origin} is not valid JSON`);
+    }
+  }
+  if (!key || typeof key !== 'object' || Array.isArray(key)) fail(`${origin} must be a JSON object`);
+  const oauth = key.oauth && typeof key.oauth === 'object' && !Array.isArray(key.oauth) ? key.oauth : key;
+  const raw = {
+    url: text(oauth.url),
+    tokenUrl: text(oauth.tokenurl) || text(oauth.tokenUrl),
+    clientId: text(oauth.clientid) || text(oauth.clientId),
+    clientSecret: text(oauth.clientsecret) || text(oauth.clientSecret)
+  };
+  if (!raw.clientSecret && (oauth.certificate || oauth.key || oauth.privateKey || key.certificate || key.key || key.privateKey)) {
+    fail(`${origin} is a certificate-based key; create a ClientId/Secret service key`);
+  }
+  const missing = Object.entries({ url: raw.url, tokenurl: raw.tokenUrl, clientid: raw.clientId, clientsecret: raw.clientSecret })
+    .filter(([, entry]) => !entry)
+    .map(([name]) => name);
+  if (missing.length) fail(`${origin} is missing ${missing.join(', ')}`);
+  return raw;
+}
+
+function serviceKeyConfig(env, prefix) {
+  const value = env[`${prefix}_SERVICE_KEY`];
+  if (value === undefined || value === '') return null;
+  return finalize(prefix, 'service-key', null, parseServiceKey(value, `${prefix}_SERVICE_KEY`));
+}
+
+function vcapConfig(env, prefix, defaultVcapService) {
+  const raw = env.VCAP_SERVICES;
+  const bindingName = text(env[`${prefix}_BINDING`]);
+  if (!raw) {
+    if (bindingName) fail(`No ${prefix} VCAP_SERVICES binding matches ${prefix}_BINDING`);
+    return null;
+  }
+  let services;
+  try {
+    services = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch {
+    fail(`${prefix}_VCAP_SERVICE lookup failed: VCAP_SERVICES is not valid JSON`);
+  }
+  const label = text(env[`${prefix}_VCAP_SERVICE`]) || defaultVcapService;
+  const instances = services && typeof services === 'object' && Array.isArray(services[label]) ? services[label] : [];
+  let candidates = instances.filter(instance => instance && typeof instance === 'object' && !Array.isArray(instance));
+  if (bindingName) {
+    candidates = candidates.filter(instance => (instance.name || instance.binding_name) === bindingName);
+    if (!candidates.length) fail(`No ${prefix} VCAP_SERVICES binding matches ${prefix}_BINDING`);
+  }
+  if (!candidates.length) return null;
+  if (candidates.length > 1) fail(`Multiple ${prefix} VCAP_SERVICES bindings; set ${prefix}_BINDING`);
+  const [instance] = candidates;
+  const name = instance.name || instance.binding_name;
+  const origin = `${prefix}_VCAP_SERVICE binding credentials`;
+  return finalize(prefix, 'vcap-services', typeof name === 'string' ? name : null, parseServiceKey(instance.credentials, origin));
+}
+
+function storedConfig(stored, prefix) {
+  const key = stored?.[prefix.toLowerCase()];
+  if (key === undefined || key === null) return null;
+  return finalize(prefix, 'stored-key', null, parseServiceKey(key, `Stored ${prefix} service key`));
+}
+
+// Precedence: explicit variables, *_SERVICE_KEY, VCAP_SERVICES, then the key stored by `sap-ai-dev --setup-integration`.
+function resolveSide(env, { prefix, defaultVcapService }, stored) {
+  return explicitConfig(env, prefix)
+    ?? serviceKeyConfig(env, prefix)
+    ?? vcapConfig(env, prefix, defaultVcapService)
+    ?? storedConfig(stored, prefix);
+}
+
+/** Resolve one side from the environment only (no stored key); null when that side is not configured there. */
+export function resolveIntegrationSideFromEnvironment(env, side) {
+  return resolveSide(env, SIDES[side]);
+}
+
+/** Validate a pasted CPI/APIM service key (JSON text or object); returns the resolved side config. */
+export function parseIntegrationServiceKey(side, value) {
+  return finalize(side, 'stored-key', null, parseServiceKey(value, `${side} service key`));
+}
+
+/**
+ * Resolve CPI and APIM client credentials; at least one side must be configured.
+ * `stored` holds service keys saved by the setup wizard ({ cpi, apim }) and has the lowest precedence.
+ */
+export function resolveIntegrationConfig(env = process.env, { stored } = {}) {
+  const cpi = resolveSide(env, SIDES.CPI, stored);
+  const apim = resolveSide(env, SIDES.APIM, stored);
+  if (!cpi && !apim) {
+    fail('Configure CPI (CPI_SERVICE_KEY or CPI_URL/CPI_TOKEN_URL/CPI_CLIENT_ID/CPI_CLIENT_SECRET) and/or APIM (APIM_SERVICE_KEY or APIM_*) credentials in the MCP host environment, or run sap-ai-dev --setup-integration to paste and verify service keys.');
+  }
+  return Object.freeze({ cpi, apim });
+}
+
+export const INTEGRATION_CONFIG_ERROR = /^(?:Explicit CPI|Explicit APIM|CPI_|APIM_|No CPI|No APIM|Multiple CPI|Multiple APIM|Configure CPI|Stored (?:CPI|APIM)|Stored Integration Suite)/;

package/src/integration-credentials.mjs

@@ -0,0 +1,65 @@
+// User-only store for CPI/APIM service keys pasted into `sap-ai-dev --setup-integration`.
+// The file lives outside mcp.json (~/.config/sap-ai-dev-toolkit/integration-suite.json, mode 0600)
+// and keeps only the four OAuth fields the companion needs; environment credentials take precedence.
+import { readFileSync } from 'node:fs';
+import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const SIDES = ['cpi', 'apim'];
+
+export function integrationCredentialsPath(env = process.env) {
+  const configHome = typeof env.XDG_CONFIG_HOME === 'string' && env.XDG_CONFIG_HOME.trim()
+    ? env.XDG_CONFIG_HOME.trim()
+    : join(env.HOME || env.USERPROFILE || homedir(), '.config');
+  return join(configHome, 'sap-ai-dev-toolkit', 'integration-suite.json');
+}
+
+/** Stored service keys ({ cpi?, apim? }); {} when nothing was stored. */
+export function readStoredIntegrationKeys(env = process.env) {
+  const path = integrationCredentialsPath(env);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {};
+    throw new Error(`Stored Integration Suite credentials at ${path} could not be read`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`Stored Integration Suite credentials at ${path} are not valid JSON; rerun sap-ai-dev --setup-integration`);
+  }
+  return Object.fromEntries(SIDES.filter(side => parsed?.[side]).map(side => [side, parsed[side]]));
+}
+
+/** Save one side's verified OAuth client (resolved config) next to the other side's stored key. */
+export async function storeIntegrationKey(side, config, env = process.env) {
+  const key = side.toLowerCase();
+  if (!SIDES.includes(key)) throw new Error(`Unknown Integration Suite side ${side}`);
+  const path = integrationCredentialsPath(env);
+  let existing = {};
+  try {
+    existing = readStoredIntegrationKeys(env);
+  } catch {
+    // An unreadable or corrupt store is replaced by the verified key.
+  }
+  const next = {
+    ...existing,
+    [key]: { oauth: { url: config.url, tokenurl: config.tokenUrl, clientid: config.clientId, clientsecret: config.clientSecret } }
+  };
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await chmod(dirname(path), 0o700).catch(() => {});
+  const temporary = join(dirname(path), `.integration-suite.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+  await chmod(path, 0o600).catch(() => {});
+  return path;
+}

package/src/integration-http.mjs

@@ -0,0 +1,282 @@
+// OAuth client-credentials HTTP client for one CPI or APIM tenant.
+// Requests are pinned to the configured tenant origin, bodies are size
+// capped, and token/error responses are never echoed raw.
+import { EnvHttpProxyAgent, fetch as undiciFetch } from 'undici';
+import { diagnosticText } from './redact.mjs';
+
+const TOKEN_TIMEOUT_MS = 15_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_BYTES = 20 * 1024 * 1024;
+const MAX_TEXT = 2 * 1024 * 1024;
+const DEFAULT_TOKEN_TTL_MS = 10 * 60 * 1000;
+const SERVER_RETRIES = 2;
+const RETRYABLE_STATUS = new Set([500, 502, 503, 504]);
+// Only idempotent methods are retried; POST (create/deploy/import) is never re-sent.
+const RETRYABLE_METHODS = new Set(['GET', 'PUT']);
+
+export class IntegrationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'IntegrationError';
+  }
+}
+
+/** Quote an OData string key literal; callers still percent-encode the whole segment. */
+export function odataKey(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+/** Convert OData v2 `/Date(ms)/` values to ISO strings; other values pass through. */
+export function odataDate(value) {
+  if (typeof value !== 'string') return value;
+  const match = /^\/Date\((-?\d+)(?:[+-]\d{4})?\)\/$/.exec(value);
+  return match ? new Date(Number(match[1])).toISOString() : value;
+}
+
+async function readCapped(response, limit, label) {
+  const declared = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > limit) {
+    await response.body?.cancel().catch(() => {});
+    throw new IntegrationError(`${label} response exceeded the safe size limit`);
+  }
+  if (!response.body) return new Uint8Array(0);
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of response.body) {
+    total += chunk.byteLength;
+    if (total > limit) {
+      await response.body.cancel().catch(() => {});
+      throw new IntegrationError(`${label} response exceeded the safe size limit`);
+    }
+    chunks.push(chunk);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+function sapMessage(bodyText) {
+  try {
+    const parsed = JSON.parse(bodyText);
+    const message = parsed?.error?.message;
+    if (typeof message?.value === 'string') return message.value;
+    if (typeof message === 'string') return message;
+  } catch {
+    // Not JSON: try an OData XML error, then the raw text prefix.
+  }
+  const xmlMessage = /<(?:\w+:)?message\b[^>]*>([\s\S]*?)<\/(?:\w+:)?message>/i.exec(bodyText);
+  if (xmlMessage) return xmlMessage[1].replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+  return bodyText.slice(0, 400);
+}
+
+function setCookiePairs(headers) {
+  const values = typeof headers.getSetCookie === 'function'
+    ? headers.getSetCookie()
+    : [headers.get('set-cookie')].filter(Boolean);
+  return values.map(value => value.split(';')[0].trim()).filter(Boolean);
+}
+
+// undici flags EnvHttpProxyAgent as experimental with a process warning that lands in the middle of the
+// setup wizard output; only that warning is dropped, and only while the agent is constructed.
+function envProxyAgent(options) {
+  const emitWarning = process.emitWarning;
+  process.emitWarning = (warning, ...rest) => {
+    const code = typeof rest[0] === 'object' ? rest[0]?.code : rest[1];
+    if (code === 'UNDICI-EHPA') return;
+    emitWarning.call(process, warning, ...rest);
+  };
+  try {
+    return new EnvHttpProxyAgent(options);
+  } finally {
+    process.emitWarning = emitWarning;
+  }
+}
+
+/** Create a tenant-scoped client using OAuth client credentials. */
+export function createServiceClient({
+  label,
+  url,
+  tokenUrl,
+  clientId,
+  clientSecret,
+  csrfPath = '/',
+  env = process.env,
+  fetchImpl = undiciFetch,
+  now = Date.now,
+  retryDelayMs = 500
+}) {
+  const origin = new URL(url).origin;
+  const httpProxy = env.HTTP_PROXY || env.http_proxy;
+  const httpsProxy = env.HTTPS_PROXY || env.https_proxy;
+  const dispatcher = httpProxy || httpsProxy
+    ? envProxyAgent({ httpProxy, httpsProxy, noProxy: env.NO_PROXY || env.no_proxy })
+    : undefined;
+  const transportOptions = dispatcher ? { dispatcher } : {};
+  let cachedToken = null;
+
+  async function token() {
+    if (cachedToken && cachedToken.expiresAt > now()) return cachedToken.value;
+    const basic = Buffer.from(`${clientId}:${clientSecret}`, 'utf8').toString('base64');
+    let response;
+    try {
+      response = await fetchImpl(tokenUrl, {
+        method: 'POST',
+        headers: {
+          authorization: `Basic ${basic}`,
+          'content-type': 'application/x-www-form-urlencoded',
+          accept: 'application/json'
+        },
+        body: 'grant_type=client_credentials',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+        ...transportOptions
+      });
+    } catch {
+      throw new IntegrationError(`${label} token request failed (network error)`);
+    }
+    if (response.status < 200 || response.status > 299) {
+      await response.body?.cancel().catch(() => {});
+      throw new IntegrationError(`${label} token request failed (HTTP ${response.status})`);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(new TextDecoder().decode(await readCapped(response, 64 * 1024, `${label} token`)));
+    } catch (error) {
+      if (error instanceof IntegrationError) throw error;
+      throw new IntegrationError(`${label} token response is not valid JSON`);
+    }
+    if (typeof payload?.access_token !== 'string' || !payload.access_token) {
+      throw new IntegrationError(`${label} token response has no access_token`);
+    }
+    const ttlMs = Number.isFinite(Number(payload.expires_in))
+      ? Math.max(0, (Number(payload.expires_in) - 60) * 1000)
+      : DEFAULT_TOKEN_TTL_MS;
+    cachedToken = { value: payload.access_token, expiresAt: now() + ttlMs };
+    return cachedToken.value;
+  }
+
+  async function send(target, init) {
+    try {
+      return await fetchImpl(target, {
+        ...init,
+        redirect: 'manual',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        ...transportOptions
+      });
+    } catch {
+      throw new IntegrationError(`${label} ${init.method} ${new URL(target).pathname} failed (network error or timeout)`);
+    }
+  }
+
+  async function fetchCsrf(bearer) {
+    const response = await send(new URL(`${url}${csrfPath}`).href, {
+      method: 'GET',
+      headers: { authorization: `Bearer ${bearer}`, 'x-csrf-token': 'Fetch', accept: 'application/json' }
+    });
+    await response.body?.cancel().catch(() => {});
+    const csrfToken = response.headers.get('x-csrf-token');
+    if (!csrfToken || csrfToken.toLowerCase() === 'required') {
+      throw new IntegrationError(`${label} CSRF token fetch failed (HTTP ${response.status})`);
+    }
+    return { csrfToken, cookies: setCookiePairs(response.headers) };
+  }
+
+  async function request(method, path, {
+    query,
+    json,
+    body,
+    contentType,
+    accept = 'application/json',
+    expect = [200],
+    responseType = 'json',
+    withStatus = false,
+    unwrap = true
+  } = {}) {
+    const target = new URL(`${url}${path}`);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value !== undefined && value !== null) target.searchParams.set(key, String(value));
+    }
+    // URLSearchParams emits '+' for spaces; OData servers expect %20. Literal '+' is already %2B.
+    target.search = target.search.replaceAll('+', '%20');
+    if (target.origin !== origin) throw new IntegrationError(`${label} request escaped the configured tenant`);
+
+    const baseHeaders = { accept };
+    let payload;
+    if (json !== undefined) {
+      baseHeaders['content-type'] = 'application/json';
+      payload = JSON.stringify(json);
+    } else if (typeof body === 'string') {
+      // Bytes, not a string: undici would otherwise add content-type: text/plain.
+      payload = Buffer.from(body, 'utf8');
+      if (contentType) baseHeaders['content-type'] = contentType;
+    }
+
+    // One retry each for an expired token (401) and a CSRF challenge. Idempotent GET/PUT are also retried
+    // on transient 5xx: CPI intermittently fails bundle downloads and configuration PUTs with HTTP 500.
+    let csrf = null;
+    let response;
+    let authRetried = false;
+    let csrfRetried = false;
+    let serverRetries = 0;
+    for (;;) {
+      const headers = { ...baseHeaders, authorization: `Bearer ${await token()}` };
+      if (csrf) {
+        headers['x-csrf-token'] = csrf.csrfToken;
+        if (csrf.cookies.length) headers.cookie = csrf.cookies.join('; ');
+      }
+      response = await send(target.href, { method, headers, body: payload });
+      if (response.status === 401 && !authRetried) {
+        authRetried = true;
+        await response.body?.cancel().catch(() => {});
+        cachedToken = null;
+        continue;
+      }
+      if (response.status === 403 && !csrfRetried && (response.headers.get('x-csrf-token') || '').toLowerCase() === 'required') {
+        csrfRetried = true;
+        await response.body?.cancel().catch(() => {});
+        csrf = await fetchCsrf(await token());
+        continue;
+      }
+      if (RETRYABLE_METHODS.has(method) && RETRYABLE_STATUS.has(response.status) && !expect.includes(response.status) && serverRetries < SERVER_RETRIES) {
+        serverRetries += 1;
+        await response.body?.cancel().catch(() => {});
+        await new Promise(resolve => setTimeout(resolve, retryDelayMs * serverRetries));
+        continue;
+      }
+      break;
+    }
+
+    if (!expect.includes(response.status)) {
+      let detail = '';
+      try {
+        detail = diagnosticText(sapMessage(new TextDecoder().decode(await readCapped(response, MAX_TEXT, label))), 400);
+      } catch {
+        detail = 'response body unavailable';
+      }
+      throw new IntegrationError(`${label} ${method} ${target.pathname} failed (HTTP ${response.status}): ${detail}`);
+    }
+    const status = response.status;
+    const wrap = data => (withStatus ? { status, data } : data);
+    if (status === 204 || status >= 300) {
+      await response.body?.cancel().catch(() => {});
+      return wrap(null);
+    }
+    if (responseType === 'bytes') return wrap(await readCapped(response, MAX_BYTES, label));
+    const responseText = new TextDecoder().decode(await readCapped(response, MAX_TEXT, label));
+    if (responseType === 'text') return wrap(responseText);
+    if (!responseText.trim()) return wrap(null);
+    let parsed;
+    try {
+      parsed = JSON.parse(responseText);
+    } catch {
+      throw new IntegrationError(`${label} ${method} ${target.pathname} returned a non-JSON response`);
+    }
+    return wrap(unwrap ? parsed?.d?.results ?? parsed?.d ?? parsed : parsed);
+  }
+
+  return Object.freeze({ label, request });
+}

package/src/integration-server.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { resolveIntegrationConfig } from './integration-config.mjs';
+import { integrationCredentialsPath, readStoredIntegrationKeys } from './integration-credentials.mjs';
+import { registerIntegrationTools } from './integration-tools.mjs';
+import { createIntegrationClients, verificationLines, verifyIntegrationClients } from './integration-verify.mjs';
+
+const packageMetadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+function sideSummary(config) {
+  if (!config) return Object.freeze({ configured: false });
+  return Object.freeze({
+    configured: true,
+    source: config.source,
+    binding: config.bindingName,
+    host: new URL(config.url).host,
+    token_host: new URL(config.tokenUrl).host
+  });
+}
+
+/** Create an injectable server runtime for tests and the stdio executable. */
+export function createIntegrationServer({ env = process.env, fetchImpl, pollIntervalMs, readBackDelayMs } = {}) {
+  const config = resolveIntegrationConfig(env, { stored: readStoredIntegrationKeys(env) });
+  const summary = Object.freeze({ cpi: sideSummary(config.cpi), apim: sideSummary(config.apim) });
+  const clients = createIntegrationClients(config, { env, fetchImpl });
+  const verify = () => verifyIntegrationClients(clients);
+
+  const server = new McpServer({
+    name: 'sap-ai-integration-suite',
+    version: packageMetadata.version
+  }, { capabilities: { tools: {} } });
+  registerIntegrationTools(server, {
+    cpi: clients.cpi,
+    apim: clients.apim,
+    summary,
+    verify,
+    ...(pollIntervalMs !== undefined ? { pollIntervalMs } : {}),
+    ...(readBackDelayMs !== undefined ? { readBackDelayMs } : {})
+  });
+
+  let closing;
+  const close = () => {
+    if (!closing) closing = server.close().catch(() => {});
+    return closing;
+  };
+
+  return { server, close, verify, connectionSummary: summary };
+}
+
+export async function runIntegrationServer({ env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (process.argv.slice(2).some(argument => argument === '--help' || argument === '-h')) {
+    stdout.write([
+      'Usage: sap-ai-integration',
+      '',
+      'Starts a stdio MCP server for SAP Integration Suite: Cloud Integration (CPI) packages, iFlows, value mappings,',
+      'script collections, security material, Partner Directory and monitoring, and API Management (APIM) providers,',
+      'proxies, policies, products and key value maps. Writes are create/update/deploy/undeploy only and need an',
+      'exact confirmation string; there are no delete tools. Secrets are write-only and never returned.',
+      '',
+      'Credentials are read from the MCP host environment (never from mcp.json). Per side, first match wins:',
+      '  CPI_URL, CPI_TOKEN_URL, CPI_CLIENT_ID, CPI_CLIENT_SECRET      explicit CPI OAuth client (all four)',
+      '  CPI_SERVICE_KEY                                              CPI "api" plan service key JSON',
+      '  VCAP_SERVICES + CPI_VCAP_SERVICE (default it-rt), CPI_BINDING',
+      '  APIM_URL, APIM_TOKEN_URL, APIM_CLIENT_ID, APIM_CLIENT_SECRET  explicit APIM OAuth client (all four)',
+      '  APIM_SERVICE_KEY                                             APIM "apiportal-apiaccess" service key JSON',
+      '  VCAP_SERVICES + APIM_VCAP_SERVICE (default apimanagement-apiportal), APIM_BINDING',
+      `  ${integrationCredentialsPath(env)}`,
+      '                                                               keys pasted and verified by sap-ai-dev --setup-integration',
+      'HTTP_PROXY, HTTPS_PROXY and NO_PROXY are honored. At least one of CPI or APIM must be configured.',
+      '',
+      '  --check   sign in and run one read per tool area, report missing roles, and exit (1 on failure)',
+      ''
+    ].join('\n'));
+    return;
+  }
+  let runtime;
+  try {
+    runtime = createIntegrationServer({ env });
+  } catch (error) {
+    stderr.write(`[sap-ai-integration] ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (process.argv.slice(2).includes('--check')) {
+    const report = await runtime.verify();
+    const lines = [
+      ...verificationLines('CPI', runtime.connectionSummary.cpi.host, report.cpi),
+      ...verificationLines('APIM', runtime.connectionSummary.apim.host, report.apim)
+    ];
+    stdout.write(`${lines.join('\n')}\n`);
+    await runtime.close();
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+
+  const transport = new StdioServerTransport(stdin, stdout, { maxBufferSize: 1024 * 1024 });
+  let closing;
+  const shutdown = () => {
+    if (!closing) closing = runtime.close().catch(() => {});
+    return closing;
+  };
+  const onStdinEnd = () => { void shutdown(); };
+  const onSignal = signal => {
+    void shutdown().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+  };
+  stdin.once('end', onStdinEnd);
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  transport.onerror = () => stderr.write('[sap-ai-integration] MCP stdio transport failed.\n');
+
+  try {
+    await runtime.server.connect(transport);
+  } catch {
+    stderr.write('[sap-ai-integration] MCP server startup failed.\n');
+    await shutdown();
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  await runIntegrationServer();
+}