sap-ai-dev-toolkit 0.9.9921 → 0.9.9923

package/src/cloud-alm-client.mjs

@@ -0,0 +1,44 @@
+// SAP Cloud ALM API REST client, shared by the MCP server, the tools and the
+// setup verification: XSUAA client credentials with token retry, on-demand CSRF
+// and SAP error details.
+import { list } from './integration-common.mjs';
+import { createServiceClient } from './integration-http.mjs';
+
+export const CLOUD_ALM_PATHS = Object.freeze({
+  analytics: '/calm-analytics/v1/analytics',
+  logs: '/calm-logs/v1/logs',
+  landscape: '/calm-landscape/v1/landscapeObjects',
+  features: '/calm-features/v1',
+  eventSituations: '/calm-event-situations/v1/event-situations'
+});
+
+export function createCloudAlmRestClient(config, { env = process.env, fetchImpl } = {}) {
+  return createServiceClient({
+    label: 'CLOUD_ALM',
+    url: config.url,
+    tokenUrl: config.tokenUrl,
+    clientId: config.clientId,
+    clientSecret: config.clientSecret,
+    csrfPath: `${CLOUD_ALM_PATHS.analytics}/providers`,
+    env,
+    ...(fetchImpl ? { fetchImpl } : {})
+  });
+}
+
+/** Read-only reachability check of the Landscape and Analytics APIs; never throws. */
+export async function verifyCloudAlmAccess(rest) {
+  const report = {};
+  try {
+    const objects = list(await rest.request('GET', CLOUD_ALM_PATHS.landscape, { query: { limit: 1 } }));
+    report.landscape_api = `ok (${objects.length} object(s) on first page)`;
+  } catch (error) {
+    report.landscape_api = `failed: ${error?.message || 'Landscape API request failed'}`;
+  }
+  try {
+    const providers = list(await rest.request('GET', `${CLOUD_ALM_PATHS.analytics}/providers`));
+    report.analytics_api = `ok (${providers.length} authorized providers)`;
+  } catch (error) {
+    report.analytics_api = `failed: ${error?.message || 'Analytics API request failed'}`;
+  }
+  return report;
+}

package/src/cloud-alm-config.mjs

@@ -0,0 +1,92 @@
+// SAP Cloud ALM API service-key / OAuth client configuration.
+// Pure: no I/O, no network. SAP documents only client credentials for the
+// Cloud ALM API, so there is no interactive mode or refresh token.
+import { finalizeClientCredentials } from './integration-config.mjs';
+
+const BASE_KEYS = ['CLOUD_ALM_URL', 'CLOUD_ALM_TOKEN_URL', 'CLOUD_ALM_CLIENT_ID', 'CLOUD_ALM_CLIENT_SECRET'];
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * Parse a "SAP Cloud ALM API" service key (JSON text or object, optionally wrapped
+ * as `cf service-key --json` output) into `{ url, tokenUrl, clientId, clientSecret }`.
+ */
+export function parseCloudAlmServiceKey(value) {
+  let parsed = value;
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      fail('CLOUD_ALM_SERVICE_KEY is not valid JSON');
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') fail('CLOUD_ALM_SERVICE_KEY is not valid JSON');
+  const key = parsed.credentials ?? parsed.service_key?.credentials ?? parsed;
+  let api = text(key?.endpoints?.Api) || text(key?.endpoints?.api);
+  if (!api) {
+    fail('CLOUD_ALM_SERVICE_KEY has no endpoints.Api; use a service key of the "SAP Cloud ALM API" instance (plan standard) from your Cloud ALM subaccount');
+  }
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(api)) api = `https://${api}`;
+  const uaa = key.uaa ?? {};
+  if (!text(uaa.clientsecret) && (uaa.certificate || uaa.key)) {
+    fail('CLOUD_ALM_SERVICE_KEY is a certificate (x509) binding; create a binding with client secret credentials (credential type binding-secret)');
+  }
+  const missing = ['url', 'clientid', 'clientsecret'].filter(field => !text(uaa[field])).map(field => `uaa.${field}`);
+  if (missing.length) fail(`CLOUD_ALM_SERVICE_KEY is missing ${missing.join(', ')}`);
+  return { url: api, tokenUrl: text(uaa.url), clientId: text(uaa.clientid), clientSecret: text(uaa.clientsecret) };
+}
+
+/** Validate raw credentials `{ url, tokenUrl, clientId, clientSecret }` into a frozen config. */
+export function parseCloudAlmCredentials(raw, source) {
+  const clientId = text(raw?.clientId);
+  const clientSecret = text(raw?.clientSecret);
+  if (!clientId || !clientSecret) fail('CLOUD_ALM_CLIENT_ID and CLOUD_ALM_CLIENT_SECRET are required');
+  const base = finalizeClientCredentials('CLOUD_ALM', source, {
+    url: text(raw?.url),
+    tokenUrl: text(raw?.tokenUrl),
+    clientId,
+    clientSecret
+  });
+  return Object.freeze({
+    source,
+    url: base.url,
+    tokenUrl: base.tokenUrl,
+    clientId: base.clientId,
+    clientSecret: base.clientSecret
+  });
+}
+
+/**
+ * Resolve credentials: explicit CLOUD_ALM_* variables, then CLOUD_ALM_SERVICE_KEY,
+ * then the record stored by `sap-ai-dev --setup-cloud-alm`.
+ */
+export function resolveCloudAlmConfig(env = process.env, { stored } = {}) {
+  if (BASE_KEYS.some(key => env[key] !== undefined && env[key] !== '')) {
+    const missing = BASE_KEYS.filter(key => !text(env[key]));
+    if (missing.length) fail(`Explicit CLOUD_ALM configuration is incomplete: ${missing.join(', ')}`);
+    return parseCloudAlmCredentials({
+      url: env.CLOUD_ALM_URL,
+      tokenUrl: env.CLOUD_ALM_TOKEN_URL,
+      clientId: env.CLOUD_ALM_CLIENT_ID,
+      clientSecret: env.CLOUD_ALM_CLIENT_SECRET
+    }, 'environment');
+  }
+  if (text(env.CLOUD_ALM_SERVICE_KEY)) {
+    return parseCloudAlmCredentials(parseCloudAlmServiceKey(env.CLOUD_ALM_SERVICE_KEY), 'service-key');
+  }
+  if (stored) {
+    return parseCloudAlmCredentials({
+      url: stored.url,
+      tokenUrl: stored.tokenurl,
+      clientId: stored.clientid,
+      clientSecret: stored.clientsecret
+    }, 'stored-key');
+  }
+  return fail('Configure SAP Cloud ALM (CLOUD_ALM_SERVICE_KEY, or CLOUD_ALM_URL/CLOUD_ALM_TOKEN_URL/CLOUD_ALM_CLIENT_ID/CLOUD_ALM_CLIENT_SECRET) in the MCP host environment, or run sap-ai-dev --setup-cloud-alm.');
+}

package/src/cloud-alm-credentials.mjs

@@ -0,0 +1,29 @@
+// User-only store for SAP Cloud ALM API client credentials (never mcp.json):
+// ~/.config/sap-ai-dev-toolkit/cloud-alm.json, mode 0600, atomic writes.
+import { readFileSync } from 'node:fs';
+import { userConfigFilePath, writeUserOnlyJson } from './integration-credentials.mjs';
+
+export function cloudAlmCredentialsPath(env = process.env) {
+  return userConfigFilePath(env, 'cloud-alm.json');
+}
+
+/** Stored record ({ url, tokenurl, clientid, clientsecret }); undefined when absent. */
+export function readStoredCloudAlmCredentials(env = process.env) {
+  const path = cloudAlmCredentialsPath(env);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    throw new Error(`Stored SAP Cloud ALM credentials at ${path} could not be read`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Stored SAP Cloud ALM credentials at ${path} are not valid JSON; rerun sap-ai-dev --setup-cloud-alm`);
+  }
+}
+
+export async function storeCloudAlmCredentials(record, env = process.env) {
+  return writeUserOnlyJson(cloudAlmCredentialsPath(env), record);
+}

package/src/cloud-alm-data.mjs

@@ -0,0 +1,129 @@
+// Pure SAP Cloud ALM data helpers: API timestamps, lookback windows, OTLP log
+// record flattening and analytics table reading/aggregation. No I/O.
+
+/** Cloud ALM `YYYYMMDDHHmmss` UTC timestamp. */
+export function calmTimestamp(ms) {
+  return new Date(ms).toISOString().slice(0, 19).replace(/[-:T]/g, '');
+}
+
+/** Window ending at `end` (ISO, default now) and spanning `spanMs`. */
+export function lookbackWindow({ end, spanMs, now = Date.now }) {
+  const endMs = end === undefined ? now() : Date.parse(end);
+  const startMs = endMs - spanMs;
+  return {
+    startMs,
+    endMs,
+    from: calmTimestamp(startMs),
+    to: calmTimestamp(endMs),
+    from_iso: new Date(startMs).toISOString(),
+    to_iso: new Date(endMs).toISOString()
+  };
+}
+
+function cap(value, max) {
+  return typeof value === 'string' && value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+function nanosToIso(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  try {
+    const date = new Date(Number(BigInt(value) / 1000000n));
+    return Number.isFinite(date.getTime()) ? date.toISOString() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function anyValue(value, max) {
+  if (!value || typeof value !== 'object') return value;
+  if ('stringValue' in value) return cap(value.stringValue, max);
+  if ('boolValue' in value) return value.boolValue;
+  if ('intValue' in value) {
+    const number = Number(value.intValue);
+    return Number.isSafeInteger(number) ? number : String(value.intValue);
+  }
+  if ('doubleValue' in value) return Number(value.doubleValue);
+  if ('arrayValue' in value) return (value.arrayValue?.values ?? []).map(entry => anyValue(entry, max));
+  if ('kvlistValue' in value) return keyValues(value.kvlistValue?.values, max);
+  if ('bytesValue' in value) return '[bytes]';
+  return undefined;
+}
+
+function keyValues(entries, max) {
+  const result = {};
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (typeof entry?.key === 'string') result[entry.key] = anyValue(entry.value, max);
+  }
+  return result;
+}
+
+/** Flatten an OTLP JSON logs payload into one plain record per log record. */
+export function flattenLogRecords(payload, { bodyMax = 2048, valueMax = 512 } = {}) {
+  const records = [];
+  for (const resourceLog of payload?.resourceLogs ?? []) {
+    const resource = keyValues(resourceLog?.resource?.attributes, valueMax);
+    const service = {
+      name: resource['service.name'],
+      type: resource['service.namespace'],
+      display_name: resource['sap.service.display_name'],
+      instance_id: resource['service.instance.id']
+    };
+    for (const scopeLog of resourceLog?.scopeLogs ?? []) {
+      for (const record of scopeLog?.logRecords ?? []) {
+        records.push({
+          time: nanosToIso(record.timeUnixNano),
+          observed_time: nanosToIso(record.observedTimeUnixNano),
+          severity: record.severityText || record.severityNumber,
+          body: anyValue(record.body, bodyMax),
+          service,
+          attributes: keyValues(record.attributes, valueMax)
+        });
+      }
+    }
+  }
+  return records;
+}
+
+/** Read one analytics table entry into row objects keyed by column text. */
+export function readAnalyticsTable(entry) {
+  const columns = entry?.columns ?? entry?.COLUMNS ?? [];
+  const data = entry?.rows ?? entry?.ROWS ?? [];
+  const rows = data.map(values => Object.fromEntries(columns.map((column, index) => {
+    const value = values?.[index];
+    return [column.text, column.type === 'time' && value !== null && value !== undefined
+      ? new Date(Number(value)).toISOString()
+      : value];
+  })));
+  const total = Number.isFinite(Number(entry?.totalCount)) && entry?.totalCount !== null && entry?.totalCount !== undefined
+    ? Number(entry.totalCount)
+    : null;
+  const count = entry?.count;
+  const truncated = total !== null && count !== null && count !== undefined && Number.isFinite(Number(count)) && total > Number(count);
+  return { columns, rows, total, truncated };
+}
+
+/** Group rows by dimension columns (time dropped) and combine measures by sum or max; sorted by the first measure. */
+export function aggregateAnalyticsRows(table, mode) {
+  const columns = table.columns.filter(column => column.type !== 'time');
+  const measures = columns.filter(column => column.type === 'number').map(column => column.text);
+  const dimensions = columns.filter(column => column.type !== 'number').map(column => column.text);
+  const groups = new Map();
+  for (const row of table.rows) {
+    const id = JSON.stringify(dimensions.map(name => row[name]));
+    let group = groups.get(id);
+    if (!group) {
+      group = Object.fromEntries(dimensions.map(name => [name, row[name]]));
+      for (const name of measures) group[name] = null;
+      groups.set(id, group);
+    }
+    for (const name of measures) {
+      const value = Number(row[name]);
+      if (row[name] === null || row[name] === undefined || !Number.isFinite(value)) continue;
+      group[name] = group[name] === null ? value : mode === 'max' ? Math.max(group[name], value) : group[name] + value;
+    }
+  }
+  const first = measures[0];
+  const result = [...groups.values()];
+  if (first !== undefined) result.sort((a, b) => (b[first] ?? -Infinity) - (a[first] ?? -Infinity));
+  return result;
+}

package/src/cloud-alm-server.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// sap-ai-cloud-alm: stdio MCP server for SAP Cloud ALM operations (landscape,
+// Integration & Exception Monitoring, analytics, features/transports, event
+// situations) with service-key client credentials.
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createCloudAlmRestClient, verifyCloudAlmAccess } from './cloud-alm-client.mjs';
+import { resolveCloudAlmConfig } from './cloud-alm-config.mjs';
+import { cloudAlmCredentialsPath, readStoredCloudAlmCredentials } from './cloud-alm-credentials.mjs';
+import { registerCloudAlmTools } from './cloud-alm-tools.mjs';
+
+const packageMetadata = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+/** Create an injectable server runtime for tests and the stdio executable. */
+export function createCloudAlmServer({ env = process.env, fetchImpl } = {}) {
+  const config = resolveCloudAlmConfig(env, { stored: readStoredCloudAlmCredentials(env) });
+  const rest = createCloudAlmRestClient(config, { env, ...(fetchImpl ? { fetchImpl } : {}) });
+
+  const summary = Object.freeze({
+    api_host: new URL(config.url).host,
+    token_host: new URL(config.tokenUrl).host,
+    auth: 'client_credentials',
+    source: config.source
+  });
+
+  const verify = () => verifyCloudAlmAccess(rest);
+
+  const server = new McpServer({
+    name: 'sap-ai-cloud-alm',
+    version: packageMetadata.version
+  }, { capabilities: { tools: {} } });
+  registerCloudAlmTools(server, { rest, summary, verify });
+
+  let closing;
+  const close = () => {
+    if (!closing) closing = server.close().catch(() => {});
+    return closing;
+  };
+
+  return { server, close, verify, connectionSummary: summary };
+}
+
+export async function runCloudAlmServer({ 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-cloud-alm',
+      '',
+      'Starts a stdio MCP server for SAP Cloud ALM operations: landscape objects and tiers, health,',
+      'exception and alert hotspots, Integration & Exception Monitoring records, monitoring events,',
+      'incident triage with CPI message log and SLG1 handoffs, analytics queries, feature and',
+      'transport status. Closing an event situation requires an exact confirmation string.',
+      '',
+      'Credentials come from a service key of a "SAP Cloud ALM API" instance (plan standard) in the',
+      'MCP host environment, or from the user-only store filled by sap-ai-dev --setup-cloud-alm:',
+      '  CLOUD_ALM_SERVICE_KEY                     service key JSON (endpoints.Api and uaa client secret)',
+      '  CLOUD_ALM_URL                             API base URL including /api; takes precedence over the key',
+      '  CLOUD_ALM_TOKEN_URL                       XSUAA URL or token URL (uaa.url)',
+      '  CLOUD_ALM_CLIENT_ID                       OAuth client id (all four variables required together)',
+      '  CLOUD_ALM_CLIENT_SECRET                   OAuth client secret',
+      `  ${cloudAlmCredentialsPath(env)}`,
+      '                                            service key stored by sap-ai-dev --setup-cloud-alm (never mcp.json)',
+      '',
+      'HTTP_PROXY, HTTPS_PROXY and NO_PROXY are honored.',
+      '',
+      '  --check   verify Landscape and Analytics API access; exit 1 when a check fails',
+      ''
+    ].join('\n'));
+    return;
+  }
+  let runtime;
+  try {
+    runtime = createCloudAlmServer({ env });
+  } catch (error) {
+    stderr.write(`[sap-ai-cloud-alm] ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (process.argv.slice(2).includes('--check')) {
+    const report = await runtime.verify();
+    stdout.write(`${Object.entries(report).map(([name, result]) => `${name}: ${result}`).join('\n')}\n`);
+    await runtime.close();
+    if (Object.values(report).some(result => String(result).startsWith('failed'))) 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-cloud-alm] MCP stdio transport failed.\n');
+
+  try {
+    await runtime.server.connect(transport);
+  } catch {
+    stderr.write('[sap-ai-cloud-alm] MCP server startup failed.\n');
+    await shutdown();
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await runCloudAlmServer();
+}