sap-ai-dev-toolkit 0.9.9922 → 0.9.9923

package/src/process-automation-common.mjs

@@ -0,0 +1,69 @@
+// Shared schemas and helpers for the SAP Build Process Automation tool modules.
+import { writeFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { z } from 'zod';
+import { IntegrationError, odataKey } from './integration-http.mjs';
+
+export const WORKFLOW = '/public/workflow/rest/v1';
+export const INBOX = '/public/workflow/odata/v1/tcm';
+export const RULES = '/public/rule/runtime/rest/v2/rule-services';
+export const UNIFIED = '/public/unified/v1';
+export const IRPA_RUNTIME = '/public/irpa/runtime/v1';
+export const IRPA_MONITORING = '/public/irpa/monitoring/v1';
+export const VISIBILITY = '/public/visibility/runtime';
+export const EVENTS = '/internal/be/v1/events';
+export const CONTEXT_MAX_BYTES = 48 * 1024;
+
+// Workflow ids are UUID v1; a plain shape check avoids strict variant rejection.
+export const guid = z.string().regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, 'expected a BPA id (UUID)');
+export const identifier = (label = 'identifier') => z.string().regex(/^[A-Za-z0-9_.:-]{1,255}$/, `expected a ${label}`);
+export const payload = z.record(z.string(), z.unknown());
+export const environmentId = z.string().regex(/^[A-Za-z0-9_.-]{1,128}$/, 'expected an environment id').optional()
+  .describe('Environment id (Control Tower > Environments); defaults to PROCESS_AUTOMATION_ENVIRONMENT_ID when configured.');
+export const timestamp = z.string().max(40).regex(/^\d{4}-\d\d-\d\d(?:T\d\d:\d\d(?::\d\d(?:\.\d{1,3})?)?(?:Z|[+-]\d\d:\d\d)?)?$/, 'expected an ISO 8601 date or timestamp');
+export const top = (max, fallback) => z.number().int().min(1).max(max).default(fallback);
+export const skip = z.number().int().min(0).default(0);
+export const outputFile = z.string().min(1).max(1024).refine(isAbsolute, 'must be an absolute path')
+  .describe('Absolute path of a new local file (must not exist); written with mode 0600.');
+
+export const rows = value => (Array.isArray(value) ? value : []);
+export const enc = encodeURIComponent;
+/** OData string literal ('x', quotes doubled) for keys and function-import parameters. */
+export const odataString = odataKey;
+
+export function capContext(value, field = 'context') {
+  const bytes = Buffer.byteLength(JSON.stringify(value ?? null));
+  if (bytes <= CONTEXT_MAX_BYTES) return { [field]: value };
+  return {
+    [`${field}_truncated`]: true,
+    [`${field}_bytes`]: bytes,
+    [`${field}_keys`]: value && typeof value === 'object' ? Object.keys(value) : []
+  };
+}
+
+/** Header carrying the environment API key; `required` APIs fail before any tenant call without one. */
+export function apiKeyHeaders(access, name, { required = false } = {}) {
+  if (access?.apiKey) return { [name]: access.apiKey };
+  if (required) {
+    throw new IntegrationError('This SAP Build Process Automation API needs an environment API key (Control Tower > Environments > API Keys); set PROCESS_AUTOMATION_API_KEY or rerun sap-ai-dev --setup-process-automation.');
+  }
+  return {};
+}
+
+export function environmentQuery(access, given) {
+  const value = given ?? access?.environmentId ?? undefined;
+  return value ? { environmentId: value } : {};
+}
+
+/** Write downloaded bytes to a new user-only file; never overwrites. */
+export async function writeExportFile(path, data) {
+  const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data ?? new Uint8Array(0));
+  try {
+    await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+  } catch (error) {
+    if (error?.code === 'EEXIST') throw new IntegrationError(`output file ${path} already exists; choose a new path`);
+    if (error?.code === 'ENOENT') throw new IntegrationError(`output directory for ${path} does not exist`);
+    throw new IntegrationError(`output file ${path} could not be written (${error?.code || 'error'})`);
+  }
+  return { output_file: path, bytes: bytes.byteLength };
+}

package/src/process-automation-config.mjs

@@ -0,0 +1,142 @@
+// SAP Build Process Automation service-key / OAuth client configuration.
+// Pure: no I/O, no network. Two auth modes: 'technical' (service-key client
+// credentials) and 'interactive' (authorization code + refresh token with the
+// same service-key client, so actions are attributed to the signed-in user).
+import { finalizeClientCredentials } from './integration-config.mjs';
+
+const BASE_KEYS = ['PROCESS_AUTOMATION_URL', 'PROCESS_AUTOMATION_TOKEN_URL', 'PROCESS_AUTOMATION_CLIENT_ID', 'PROCESS_AUTOMATION_CLIENT_SECRET'];
+
+export const PROCESS_AUTOMATION_OAUTH = Object.freeze({
+  product: 'SAP Build Process Automation',
+  setupCommand: 'sap-ai-dev --setup-process-automation',
+  sacCustomAuth: false
+});
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * Parse a process-automation-service key (JSON text or object, optionally wrapped
+ * as `cf service-key --json` output) into `{ url, tokenUrl, clientId, clientSecret }`.
+ */
+export function parseProcessAutomationServiceKey(value) {
+  let parsed = value;
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      fail('PROCESS_AUTOMATION_SERVICE_KEY is not valid JSON');
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') fail('PROCESS_AUTOMATION_SERVICE_KEY is not valid JSON');
+  const key = parsed.credentials ?? parsed.service_key?.credentials ?? parsed;
+  let api = text(key?.endpoints?.api);
+  if (!api) {
+    fail('PROCESS_AUTOMATION_SERVICE_KEY has no endpoints.api; use a service key of the SAP Build Process Automation instance (process-automation-service)');
+  }
+  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('PROCESS_AUTOMATION_SERVICE_KEY is a certificate-based key; create a service key with client secret credentials');
+  }
+  const missing = ['url', 'clientid', 'clientsecret'].filter(field => !text(uaa[field])).map(field => `uaa.${field}`);
+  if (missing.length) fail(`PROCESS_AUTOMATION_SERVICE_KEY is missing ${missing.join(', ')}`);
+  return { url: api, tokenUrl: text(uaa.url), clientId: text(uaa.clientid), clientSecret: text(uaa.clientsecret) };
+}
+
+const ENVIRONMENT_ID = /^[A-Za-z0-9_.-]{1,128}$/;
+
+/** Optional environment-scoped API key (Control Tower > Environments > API Keys) and default environment. */
+function parseOptionalAccess(raw) {
+  const apiKey = text(raw?.apiKey);
+  if (apiKey && (apiKey.length > 512 || /[^\x21-\x7e]/.test(apiKey))) fail('PROCESS_AUTOMATION_API_KEY must be a single printable token');
+  const environmentId = text(raw?.environmentId);
+  if (environmentId && !ENVIRONMENT_ID.test(environmentId)) fail('PROCESS_AUTOMATION_ENVIRONMENT_ID must be 1-128 letters, digits, dots, dashes or underscores');
+  return { apiKey: apiKey || null, environmentId: environmentId || null };
+}
+
+/**
+ * Validate raw credentials into a frozen config.
+ * `raw = { auth, url, tokenUrl, clientId, clientSecret, refreshToken?, apiKey?, environmentId? }`.
+ */
+export function parseProcessAutomationCredentials(raw, source) {
+  const auth = text(raw?.auth) || 'technical';
+  if (auth !== 'technical' && auth !== 'interactive') fail('PROCESS_AUTOMATION_AUTH must be technical or interactive');
+  const clientId = text(raw?.clientId);
+  const clientSecret = text(raw?.clientSecret);
+  if (!clientId || !clientSecret) fail('PROCESS_AUTOMATION_CLIENT_ID and PROCESS_AUTOMATION_CLIENT_SECRET are required');
+  const base = finalizeClientCredentials('PROCESS_AUTOMATION', source, {
+    url: text(raw?.url),
+    tokenUrl: text(raw?.tokenUrl),
+    clientId,
+    clientSecret
+  });
+  let authorizationUrl = null;
+  let refreshToken = null;
+  if (auth === 'interactive') {
+    authorizationUrl = `${new URL(base.tokenUrl).origin}/oauth/authorize`;
+    refreshToken = text(raw?.refreshToken);
+    if (!refreshToken) fail('PROCESS_AUTOMATION_REFRESH_TOKEN is required for interactive sign-in; run sap-ai-dev --setup-process-automation');
+  }
+  return Object.freeze({
+    source,
+    auth,
+    url: base.url,
+    tokenUrl: base.tokenUrl,
+    clientId: base.clientId,
+    clientSecret: base.clientSecret,
+    authorizationUrl,
+    refreshToken,
+    ...parseOptionalAccess(raw)
+  });
+}
+
+/**
+ * Resolve credentials: explicit PROCESS_AUTOMATION_* variables, then
+ * PROCESS_AUTOMATION_SERVICE_KEY, then the record stored by
+ * `sap-ai-dev --setup-process-automation`. PROCESS_AUTOMATION_API_KEY and
+ * PROCESS_AUTOMATION_ENVIRONMENT_ID always win over stored values.
+ */
+export function resolveProcessAutomationConfig(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 PROCESS_AUTOMATION configuration is incomplete: ${missing.join(', ')}`);
+    return parseProcessAutomationCredentials({
+      auth: env.PROCESS_AUTOMATION_AUTH,
+      url: env.PROCESS_AUTOMATION_URL,
+      tokenUrl: env.PROCESS_AUTOMATION_TOKEN_URL,
+      clientId: env.PROCESS_AUTOMATION_CLIENT_ID,
+      clientSecret: env.PROCESS_AUTOMATION_CLIENT_SECRET,
+      refreshToken: env.PROCESS_AUTOMATION_REFRESH_TOKEN,
+      apiKey: env.PROCESS_AUTOMATION_API_KEY,
+      environmentId: env.PROCESS_AUTOMATION_ENVIRONMENT_ID
+    }, 'environment');
+  }
+  if (text(env.PROCESS_AUTOMATION_SERVICE_KEY)) {
+    return parseProcessAutomationCredentials({
+      auth: env.PROCESS_AUTOMATION_AUTH,
+      ...parseProcessAutomationServiceKey(env.PROCESS_AUTOMATION_SERVICE_KEY),
+      refreshToken: env.PROCESS_AUTOMATION_REFRESH_TOKEN,
+      apiKey: env.PROCESS_AUTOMATION_API_KEY,
+      environmentId: env.PROCESS_AUTOMATION_ENVIRONMENT_ID
+    }, 'service-key');
+  }
+  if (stored) {
+    return parseProcessAutomationCredentials({
+      auth: stored.auth,
+      url: stored.url,
+      tokenUrl: stored.tokenurl,
+      clientId: stored.clientid,
+      clientSecret: stored.clientsecret,
+      refreshToken: stored.refreshtoken,
+      apiKey: text(env.PROCESS_AUTOMATION_API_KEY) || stored.apikey,
+      environmentId: text(env.PROCESS_AUTOMATION_ENVIRONMENT_ID) || stored.environmentid
+    }, 'stored-key');
+  }
+  return fail('Configure SAP Build Process Automation (PROCESS_AUTOMATION_SERVICE_KEY, or PROCESS_AUTOMATION_URL/PROCESS_AUTOMATION_TOKEN_URL/PROCESS_AUTOMATION_CLIENT_ID/PROCESS_AUTOMATION_CLIENT_SECRET) in the MCP host environment, or run sap-ai-dev --setup-process-automation.');
+}

package/src/process-automation-credentials.mjs

@@ -0,0 +1,37 @@
+// User-only store for SAP Build Process Automation OAuth client credentials (never
+// mcp.json): ~/.config/sap-ai-dev-toolkit/process-automation.json, mode 0600, atomic writes.
+import { readFileSync } from 'node:fs';
+import { userConfigFilePath, writeUserOnlyJson } from './integration-credentials.mjs';
+
+export function processAutomationCredentialsPath(env = process.env) {
+  return userConfigFilePath(env, 'process-automation.json');
+}
+
+/** Stored record ({ auth, url, tokenurl, clientid, clientsecret, refreshtoken?, apikey?, environmentid? }); undefined when absent. */
+export function readStoredProcessAutomationCredentials(env = process.env) {
+  const path = processAutomationCredentialsPath(env);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    throw new Error(`Stored SAP Build Process Automation credentials at ${path} could not be read`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Stored SAP Build Process Automation credentials at ${path} are not valid JSON; rerun sap-ai-dev --setup-process-automation`);
+  }
+}
+
+export async function storeProcessAutomationCredentials(record, env = process.env) {
+  return writeUserOnlyJson(processAutomationCredentialsPath(env), record);
+}
+
+/** Persist a rotated refresh token without touching the rest of the record. */
+export async function updateStoredProcessAutomationRefreshToken(refreshToken, env = process.env) {
+  const path = processAutomationCredentialsPath(env);
+  const stored = readStoredProcessAutomationCredentials(env);
+  if (!stored) throw new Error(`Stored SAP Build Process Automation credentials at ${path} could not be read`);
+  return writeUserOnlyJson(path, { ...stored, refreshtoken: refreshToken });
+}

package/src/process-automation-inbox-tools.mjs

@@ -0,0 +1,246 @@
+// SAP Build Process Automation Inbox API (OData v2 Task Consumption Model) tools: the signed-in
+// user's task inbox, task details, task definitions, claim/release/forward and substitution rules.
+// The API is user-centric: with technical (client-credentials) auth it shows the technical
+// client's own inbox, which is normally empty.
+import { z } from 'zod';
+import { CREATE_ANNOTATIONS, OVERWRITE_ANNOTATIONS, READ_ONLY_ANNOTATIONS, confirmation, requireConfirmation } from './integration-common.mjs';
+import { INBOX, enc, odataString, rows, skip, timestamp, top } from './process-automation-common.mjs';
+
+export const INBOX_TOOL_NAMES = Object.freeze([
+  'bpa_inbox_list_tasks',
+  'bpa_inbox_get_task',
+  'bpa_inbox_list_task_definitions',
+  'bpa_inbox_task_action',
+  'bpa_inbox_list_substitution_rules',
+  'bpa_inbox_create_substitution_rule',
+  'bpa_inbox_change_substitution_rule'
+]);
+
+const USER_SCOPE = 'Needs the ProcessAutomationParticipant role; returns the signed-in user\'s inbox (with technical auth the technical client\'s, normally empty).';
+
+// Status values the TCM $filter accepts (other values fail with HTTP 400).
+const FILTER_STATUS = z.enum(['READY', 'RESERVED', 'IN_PROGRESS', 'EXECUTED']);
+const PRIORITY = z.enum(['LOW', 'MEDIUM', 'HIGH', 'VERY_HIGH']);
+const ORDER_BY = z.enum([
+  'TaskDefinitionName asc', 'TaskDefinitionName desc', 'TaskTitle asc', 'TaskTitle desc', 'Status asc', 'Status desc',
+  'Priority asc', 'Priority desc', 'PriorityNumber asc', 'PriorityNumber desc', 'CreatedOn asc', 'CreatedOn desc',
+  'CreatedByName asc', 'CreatedByName desc', 'CompletionDeadLine asc', 'CompletionDeadLine desc'
+]);
+const TASK_INCLUDES = Object.freeze({
+  task_definition: '/TaskDefinitionData',
+  workflow_logs: '/WorkflowLogs',
+  description: '/Description',
+  custom_attributes: '/CustomAttributeData'
+});
+
+const origin = z.string().min(1).max(100).describe('SAP__Origin of the task; \'NA\' for SAP Build Process Automation.');
+const instanceId = z.string().min(1).max(255).describe('Task InstanceID.');
+const text = max => z.string().min(1).max(max);
+
+/** UTC milliseconds of an ISO timestamp; a timestamp without zone is read as UTC (TCM expects UTC). */
+function utcMillis(value) {
+  const zoned = /T/.test(value) && !/(?:Z|[+-]\d\d:\d\d)$/.test(value) ? `${value}Z` : value;
+  return Date.parse(zoned);
+}
+
+/** OData v2 datetime literal, e.g. datetime'2026-11-05T00:00:00'. */
+const datetimeLiteral = value => `datetime'${new Date(utcMillis(value)).toISOString().slice(0, 19)}'`;
+
+/** Drop OData v2 `__metadata` and deferred navigation stubs so results stay compact. */
+function clean(value) {
+  if (Array.isArray(value)) return value.map(clean);
+  if (!value || typeof value !== 'object') return value;
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key === '__metadata') continue;
+    if (item && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).length === 1 && item.__deferred) continue;
+    result[key] = clean(item);
+  }
+  return result;
+}
+
+const anyOf = (field, values) => {
+  const terms = values.map(value => `${field} eq ${odataString(value)}`);
+  return terms.length > 1 ? `(${terms.join(' or ')})` : terms[0];
+};
+
+/** One $filter from typed inputs; attributes are and-combined, multiple values of one attribute or-combined. */
+function taskFilter({ status, task_definition_id, priority, created_from, created_up_to, due_from, due_up_to, custom_attributes }) {
+  const parts = [];
+  if (status?.length) parts.push(anyOf('Status', status));
+  if (task_definition_id?.length) parts.push(anyOf('TaskDefinitionID', task_definition_id));
+  if (priority?.length) parts.push(anyOf('Priority', priority));
+  if (created_from) parts.push(`CreatedOn ge ${datetimeLiteral(created_from)}`);
+  if (created_up_to) parts.push(`CreatedOn le ${datetimeLiteral(created_up_to)}`);
+  if (due_from) parts.push(`CompletionDeadLine ge ${datetimeLiteral(due_from)}`);
+  if (due_up_to) parts.push(`CompletionDeadLine le ${datetimeLiteral(due_up_to)}`);
+  for (const { name, value } of custom_attributes ?? []) {
+    parts.push(`(CustomAttributeData/Name eq ${odataString(name)} and CustomAttributeData/Value eq ${odataString(value)})`);
+  }
+  return parts.length ? parts.join(' and ') : undefined;
+}
+
+const taskKey = (sapOrigin, id) => `/TaskCollection(SAP__Origin=${enc(odataString(sapOrigin))},InstanceID=${enc(odataString(id))})`;
+
+export function registerInboxTools(register, { rest }) {
+  const get = (path, query = {}) => rest.request('GET', `${INBOX}${path}`, { query: { ...query, $format: 'json' } });
+  const count = async (path, query = {}) => {
+    const body = await rest.request('GET', `${INBOX}${path}/$count`, { query, accept: 'text/plain', responseType: 'text' });
+    const value = Number(String(body ?? '').trim());
+    return { count: Number.isFinite(value) ? value : null };
+  };
+  // Function imports take OData literals as query parameters and answer 202 with the changed entity.
+  const functionImport = async (name, query) => clean(await rest.request('POST', `${INBOX}/${name}`, {
+    query: { ...query, $format: 'json' },
+    expect: [200, 202, 204]
+  }));
+
+  register('bpa_inbox_list_tasks', 'List inbox tasks',
+    `List or count tasks in the Inbox (Task Consumption Model) with typed filters. ${USER_SCOPE}`,
+    z.object({
+      status: z.array(FILTER_STATUS).min(1).max(4).optional().describe('Defaults to the API default (READY or RESERVED).'),
+      task_definition_id: z.array(text(255)).min(1).max(20).optional().describe('TaskDefinitionID values ({task name}@{workflow definition id}, lowercase).'),
+      priority: z.array(PRIORITY).min(1).max(4).optional(),
+      created_from: timestamp.optional().describe('CreatedOn ge (UTC).'),
+      created_up_to: timestamp.optional().describe('CreatedOn le (UTC).'),
+      due_from: timestamp.optional().describe('CompletionDeadLine ge (UTC).'),
+      due_up_to: timestamp.optional().describe('CompletionDeadLine le (UTC).'),
+      custom_attributes: z.array(z.object({ name: text(255), value: z.string().max(255) })).min(1).max(10).optional()
+        .describe('Custom attribute name/value pairs, all must match; also filter task_definition_id for performance.'),
+      orderby: z.array(ORDER_BY).min(1).max(2).default(['CreatedOn desc'])
+        .describe('Up to two sort keys; TaskDefinitionName must come first when used.'),
+      expand: z.array(z.enum(['Description', 'CustomAttributeData'])).max(2).optional(),
+      top: top(200, 50),
+      skip,
+      count_only: z.boolean().default(false).describe('Return only the number of matching tasks (TaskCollection/$count).')
+    }).refine(args => !args.orderby.slice(1).some(key => key.startsWith('TaskDefinitionName')), {
+      message: 'TaskDefinitionName must be the first orderby key', path: ['orderby']
+    }).refine(args => !(args.count_only && args.custom_attributes), {
+      message: 'custom_attributes filters are not supported with count_only', path: ['custom_attributes']
+    }),
+    READ_ONLY_ANNOTATIONS,
+    async args => {
+      const filter = taskFilter(args);
+      if (args.count_only) return count('/TaskCollection', filter ? { $filter: filter } : {});
+      const tasks = await get('/TaskCollection', {
+        ...(filter ? { $filter: filter } : {}),
+        $orderby: args.orderby.join(','),
+        ...(args.expand?.length ? { $expand: args.expand.join(',') } : {}),
+        $top: args.top,
+        $skip: args.skip
+      });
+      return { tasks: clean(rows(tasks)) };
+    });
+
+  register('bpa_inbox_get_task', 'Get inbox task',
+    `Get one inbox task with optional task definition, workflow log, description and custom attributes. ${USER_SCOPE}`,
+    {
+      origin,
+      instance_id: instanceId,
+      include: z.array(z.enum(Object.keys(TASK_INCLUDES))).max(4).default([])
+    },
+    READ_ONLY_ANNOTATIONS,
+    async ({ origin: sapOrigin, instance_id, include }) => {
+      const key = taskKey(sapOrigin, instance_id);
+      const result = { task: clean(await get(key)) };
+      for (const name of new Set(include)) result[name] = clean(await get(`${key}${TASK_INCLUDES[name]}`));
+      return result;
+    });
+
+  register('bpa_inbox_list_task_definitions', 'List inbox task definitions',
+    `List (or count) the task definitions of the user's inbox tasks, or with origin and task_definition_id the custom attribute definitions of one. ${USER_SCOPE}`,
+    z.object({
+      origin: origin.optional(),
+      task_definition_id: text(255).optional(),
+      count_only: z.boolean().default(false).describe('Return only the number of task definitions (TaskDefinitionCollection/$count).')
+    }).refine(args => Boolean(args.origin) === Boolean(args.task_definition_id), {
+      message: 'provide both origin and task_definition_id, or neither', path: ['task_definition_id']
+    }).refine(args => !(args.count_only && args.task_definition_id), {
+      message: 'count_only lists all task definitions; omit origin and task_definition_id', path: ['count_only']
+    }),
+    READ_ONLY_ANNOTATIONS,
+    async ({ origin: sapOrigin, task_definition_id, count_only }) => {
+      if (count_only) return count('/TaskDefinitionCollection');
+      if (task_definition_id) {
+        const path = `/TaskDefinitionCollection(SAP__Origin=${enc(odataString(sapOrigin))},TaskDefinitionID=${enc(odataString(task_definition_id))})/CustomAttributeDefinitionData`;
+        return { custom_attribute_definitions: clean(rows(await get(path))) };
+      }
+      return { task_definitions: clean(rows(await get('/TaskDefinitionCollection'))) };
+    });
+
+  register('bpa_inbox_task_action', 'Claim, release or forward inbox task',
+    `Claim (to RESERVED), release (to READY) or forward (to another user, who becomes processor and recipient; the user id is not validated) an inbox task. ${USER_SCOPE}`,
+    z.object({
+      origin,
+      instance_id: instanceId,
+      action: z.enum(['claim', 'release', 'forward']),
+      forward_to: text(255).optional().describe('User id to forward to; required for forward only.'),
+      confirmation
+    }).refine(args => (args.action === 'forward') === Boolean(args.forward_to), {
+      message: 'forward_to is required for forward and not allowed otherwise', path: ['forward_to']
+    }),
+    OVERWRITE_ANNOTATIONS,
+    async ({ origin: sapOrigin, instance_id, action, forward_to, confirmation: given }) => {
+      requireConfirmation(given, `${action.toUpperCase()} BPA INBOX TASK ${instance_id}`);
+      const name = { claim: 'Claim', release: 'Release', forward: 'Forward' }[action];
+      const task = await functionImport(name, {
+        SAP__Origin: odataString(sapOrigin),
+        InstanceID: odataString(instance_id),
+        ...(action === 'forward' ? { ForwardTo: odataString(forward_to) } : {})
+      });
+      return { action, instance_id, task };
+    });
+
+  register('bpa_inbox_list_substitution_rules', 'List substitution rules',
+    `List the user's own substitution rules (my_rules) or the rules where the user is the substitute (substituting_for). ${USER_SCOPE}`,
+    { scope: z.enum(['my_rules', 'substituting_for']).default('my_rules') },
+    READ_ONLY_ANNOTATIONS,
+    async ({ scope }) => ({
+      rules: clean(rows(await get(scope === 'my_rules' ? '/SubstitutionRuleCollection' : '/SubstitutesRuleCollection')))
+    }));
+
+  register('bpa_inbox_create_substitution_rule', 'Create substitution rule',
+    `Create a substitution rule for the signed-in user: RECEIVE_TASKS (planned, enabled, needs end_date) or TAKE_OVER (unplanned, disabled until the substitute enables it). ${USER_SCOPE}`,
+    z.object({
+      user: text(255).describe('User id of the substitute.'),
+      begin_date: timestamp.describe('UTC begin; yesterday, today or later.'),
+      end_date: timestamp.optional().describe('UTC end; required for RECEIVE_TASKS, ignored for TAKE_OVER.'),
+      mode: z.enum(['RECEIVE_TASKS', 'TAKE_OVER']),
+      enabled: z.boolean().optional().describe('Must be true for RECEIVE_TASKS and false for TAKE_OVER; derived from mode when omitted.'),
+      origin: origin.default('NA'),
+      confirmation
+    }).refine(args => args.mode !== 'RECEIVE_TASKS' || Boolean(args.end_date), {
+      message: 'end_date is required for RECEIVE_TASKS', path: ['end_date']
+    }).refine(args => args.enabled === undefined || args.enabled === (args.mode === 'RECEIVE_TASKS'), {
+      message: 'enabled must be true for RECEIVE_TASKS and false for TAKE_OVER', path: ['enabled']
+    }),
+    CREATE_ANNOTATIONS,
+    async ({ user, begin_date, end_date, mode, origin: sapOrigin, confirmation: given }) => {
+      requireConfirmation(given, `CREATE BPA SUBSTITUTION FOR ${user}`);
+      const rule = await rest.request('POST', `${INBOX}/SubstitutionRuleCollection`, {
+        query: { $format: 'json' },
+        json: {
+          SAP__Origin: sapOrigin,
+          User: user,
+          BeginDate: `/Date(${utcMillis(begin_date)})/`,
+          ...(mode === 'RECEIVE_TASKS' ? { EndDate: `/Date(${utcMillis(end_date)})/` } : {}),
+          Mode: mode,
+          IsEnabled: mode === 'RECEIVE_TASKS'
+        },
+        expect: [200, 201]
+      });
+      return { rule: clean(rule) };
+    });
+
+  register('bpa_inbox_change_substitution_rule', 'Enable, disable or delete substitution rule',
+    `Enable or disable a passive (TAKE_OVER) substitution rule where the user is the substitute, or delete one of the user's substitution rules. ${USER_SCOPE}`,
+    { rule_id: text(255).describe('SubstitutionRuleID.'), action: z.enum(['enable', 'disable', 'delete']), confirmation },
+    OVERWRITE_ANNOTATIONS,
+    async ({ rule_id, action, confirmation: given }) => {
+      requireConfirmation(given, `${action.toUpperCase()} BPA SUBSTITUTION ${rule_id}`);
+      const rule = action === 'delete'
+        ? await functionImport('DeleteSubstitutionRule', { SubstitutionRuleID: odataString(rule_id) })
+        : await functionImport('EnableSubstitutionRule', { SubstitutionRuleID: odataString(rule_id), Enabled: action === 'enable' ? 'true' : 'false' });
+      return { action, rule_id, rule: rule ?? null };
+    });
+}

package/src/process-automation-server.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// sap-ai-process-automation: stdio MCP server for SAP Build Process Automation.
+// Technical (service-key client credentials) or interactive (authorization code +
+// refresh token with the service-key client) OAuth; Workflow, decision runtime and
+// business event APIs.
+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 { createProcessAutomationRestClient } from './process-automation-client.mjs';
+import { resolveProcessAutomationConfig } from './process-automation-config.mjs';
+import {
+  processAutomationCredentialsPath,
+  readStoredProcessAutomationCredentials,
+  updateStoredProcessAutomationRefreshToken
+} from './process-automation-credentials.mjs';
+import { registerProcessAutomationTools } from './process-automation-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 createProcessAutomationServer({ env = process.env, fetchImpl } = {}) {
+  const config = resolveProcessAutomationConfig(env, { stored: readStoredProcessAutomationCredentials(env) });
+  const rest = createProcessAutomationRestClient(config, {
+    env,
+    ...(fetchImpl ? { fetchImpl } : {}),
+    persistRefreshToken: token => (config.source === 'stored-key' ? updateStoredProcessAutomationRefreshToken(token, env) : undefined)
+  });
+
+  const summary = Object.freeze({
+    api_host: new URL(config.url).host,
+    uaa_host: new URL(config.tokenUrl).host,
+    auth: config.auth,
+    source: config.source,
+    task_attribution: config.auth === 'technical' ? 'technical client' : 'signed-in user',
+    api_key_configured: Boolean(config.apiKey),
+    environment_id: config.environmentId
+  });
+
+  const verify = async () => {
+    try {
+      const definitions = await rest.request('GET', '/public/workflow/rest/v1/workflow-definitions', { query: { $top: 1 } });
+      return { workflow_api: `ok (${Array.isArray(definitions) ? definitions.length : 0} definitions on first page)` };
+    } catch (error) {
+      return { workflow_api: `failed: ${error?.message || 'Workflow API request failed'}` };
+    }
+  };
+
+  const server = new McpServer({
+    name: 'sap-ai-process-automation',
+    version: packageMetadata.version
+  }, { capabilities: { tools: {} } });
+  registerProcessAutomationTools(server, { rest, summary, verify, access: { apiKey: config.apiKey, environmentId: config.environmentId } });
+
+  let closing;
+  const close = () => {
+    if (!closing) closing = server.close().catch(() => {});
+    return closing;
+  };
+
+  return { server, close, verify, connectionSummary: summary };
+}
+
+export async function runProcessAutomationServer({ 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-process-automation',
+      '',
+      'Starts a stdio MCP server covering the SAP Build Process Automation APIs: Workflow (definitions,',
+      'instances, contexts, logs, errors, user tasks, export, purge, jobs, messages), Inbox (TCM),',
+      'Decisions, Unified API triggers, Automation Execution/Monitoring, Visibility Scenarios and',
+      'Workspace, and business events. Writes require exact confirmation strings.',
+      '',
+      'Credentials come from a service key of a process-automation-service instance in the MCP host',
+      'environment, or from the user-only store filled by sap-ai-dev --setup-process-automation:',
+      '  PROCESS_AUTOMATION_SERVICE_KEY            service key JSON (endpoints.api and uaa client secret)',
+      '  PROCESS_AUTOMATION_URL                    API URL (endpoints.api); takes precedence over the key',
+      '  PROCESS_AUTOMATION_TOKEN_URL              XSUAA URL or token URL (uaa.url)',
+      '  PROCESS_AUTOMATION_CLIENT_ID              OAuth client id (all four variables required together)',
+      '  PROCESS_AUTOMATION_CLIENT_SECRET          OAuth client secret',
+      '  PROCESS_AUTOMATION_AUTH                   technical (default) | interactive',
+      '  PROCESS_AUTOMATION_REFRESH_TOKEN          refresh token (required for interactive)',
+      '  PROCESS_AUTOMATION_API_KEY                environment API key (Control Tower > Environments > API Keys);',
+      '                                            required for automation triggers/jobs/exports, optional elsewhere',
+      '  PROCESS_AUTOMATION_ENVIRONMENT_ID         default environment id for API triggers and process starts',
+      `  ${processAutomationCredentialsPath(env)}`,
+      '                                            sign-in stored by sap-ai-dev --setup-process-automation (never mcp.json)',
+      '',
+      'HTTP_PROXY, HTTPS_PROXY and NO_PROXY are honored.',
+      '',
+      '  --check   verify Workflow API access; exit 1 when the check fails',
+      ''
+    ].join('\n'));
+    return;
+  }
+  let runtime;
+  try {
+    runtime = createProcessAutomationServer({ env });
+  } catch (error) {
+    stderr.write(`[sap-ai-process-automation] ${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-process-automation] MCP stdio transport failed.\n');
+
+  try {
+    await runtime.server.connect(transport);
+  } catch {
+    stderr.write('[sap-ai-process-automation] MCP server startup failed.\n');
+    await shutdown();
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await runProcessAutomationServer();
+}