hac-mcp 1.0.0

package/tools/impex_import.js

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import { flexibleSearch, impexImport } from '../hac.js';
+import { optionalLooseBool, optionalLooseNumber } from './zodLoose.js';
+import { withSession, getEnvironment, mcpLogStart, mcpLog, text, error } from './context.js';
+import { fetchScalarFields } from './flexible_search.js';
+
+const TOOL = 'impex_import';
+
+function parseImpexHeaders(script) {
+  const result = [];
+  for (const line of script.split('\n')) {
+    const m = line.trim().match(/^(INSERT_UPDATE|INSERT|UPDATE|REMOVE)\s+(\w+)/);
+    if (!m) continue;
+    const typeCode = m[2];
+    const rest = line.trim().slice(m[0].length);
+    const semiIdx = rest.indexOf(';');
+    if (semiIdx === -1) continue;
+    const cols = rest.slice(semiIdx + 1).split(';')
+      .map(c => c.trim().match(/^(\w+)/)?.[1]).filter(Boolean);
+    result.push({ typeCode, cols });
+  }
+  return result;
+}
+
+async function validateImpexScript(env, script) {
+  const headers = parseImpexHeaders(script);
+  if (!headers.length) return [];
+  const uniqueTypes = [...new Set(headers.map(h => h.typeCode))];
+
+  const typeChains = {};
+  try {
+    const conds = uniqueTypes.map(t => `{code} = '${t}'`).join(' OR ');
+    const r = await withSession(env, s => flexibleSearch(s,
+      `SELECT {pk}, {code}, {inheritancepathstring} FROM {ComposedType} WHERE ${conds}`
+    ));
+    if (r.resultList) {
+      for (const [pk, code, inheritancePath] of r.resultList) {
+        typeChains[code] = inheritancePath ? inheritancePath.split(',').filter(Boolean) : [String(pk)];
+      }
+    }
+  } catch (_) { return []; }
+
+  const allPKs = [...new Set(Object.values(typeChains).flat())];
+  if (!allPKs.length) return [];
+
+  const mandatoryByTypePK = {};
+  const batchSize = 20;
+  for (let i = 0; i < allPKs.length; i += batchSize) {
+    const batch = allPKs.slice(i, i + batchSize);
+    try {
+      const encConds = batch.map(p => `{enclosingtype} = '${p}'`).join(' OR ');
+      const r = await withSession(env, s => flexibleSearch(s,
+        `SELECT {qualifier}, {enclosingtype} FROM {AttributeDescriptor} WHERE (${encConds}) AND {optional} = 0`,
+        { maxCount: 500 }
+      ));
+      if (r.resultList) {
+        for (const [qualifier, encPK] of r.resultList) {
+          const key = String(encPK);
+          if (!mandatoryByTypePK[key]) mandatoryByTypePK[key] = new Set();
+          mandatoryByTypePK[key].add(qualifier);
+        }
+      }
+    } catch (_) {}
+  }
+
+  const warnings = [];
+  for (const { typeCode, cols } of headers) {
+    const chain = typeChains[typeCode];
+    if (!chain) continue;
+    const allMandatory = [...new Set(chain.flatMap(pk => [...(mandatoryByTypePK[pk] || [])]))];
+    const missing = allMandatory.filter(f => !cols.includes(f));
+    if (missing.length) warnings.push(`**${typeCode}**: missing mandatory field(s): ${missing.join(', ')}`);
+  }
+  return warnings;
+}
+
+function formatImpexDetails(details) {
+  if (!details) return null;
+  return details.split('\n').map(line => {
+    const trimmed = line.trim();
+    if (!trimmed) return line;
+    const semiIdx = trimmed.indexOf(';');
+    if (semiIdx !== -1 && (trimmed.startsWith(',') || trimmed.length > 200)) {
+      const errorPart = trimmed.slice(0, semiIdx).replace(/^,+/, '').trim();
+      const dataCols = trimmed.slice(semiIdx + 1).split(';');
+      if (errorPart) {
+        return `ERROR: ${errorPart}\n  (row data: ${dataCols.length} column(s) omitted)`;
+      }
+    }
+    if (trimmed.length > 300) return trimmed.slice(0, 300) + `… [truncated]`;
+    return line;
+  }).join('\n');
+}
+
+export const tool = {
+  name: TOOL,
+  category: 'write',
+  description: 'Execute an ImpEx import script on a HAC environment. Call list_environments first to check import is allowed. IMPORTANT: Before calling this tool, you MUST show the user a summary of what data the script will insert, update, or remove and explicitly ask for their confirmation. Only proceed after the user approves and set confirmed_by_user to true.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    script: z.string().optional().describe('ImpEx script content'),
+    impexContent: z.string().optional().describe('ImpEx script content (alias for script)'),
+    validationEnum: z.enum(['IMPORT_STRICT', 'IMPORT_RELAXED']).optional(),
+    maxThreads: optionalLooseNumber(),
+    legacyMode: optionalLooseBool(),
+    enableCodeExecution: optionalLooseBool(),
+    distributedMode: optionalLooseBool(),
+    sldEnabled: optionalLooseBool(),
+    confirmed_by_user: z.boolean().describe('Must be true - user has explicitly reviewed and approved this script. The server will reject the call if false.'),
+  },
+  handler: async ({ environmentId, script: scriptArg, impexContent, validationEnum, maxThreads, legacyMode, enableCodeExecution, distributedMode, sldEnabled, confirmed_by_user }) => {
+    if (!confirmed_by_user) {
+      return error('User confirmation required. Show the user the ImpEx script and what it will insert, update, or remove, ask for explicit approval, then retry with confirmed_by_user: true.');
+    }
+    const script = scriptArg ?? impexContent;
+    if (typeof script !== 'string' || !script.length) {
+      mcpLog({ tool: TOOL, envName: environmentId, preview: 'Missing script', isError: true });
+      return error('Provide script or impexContent with the ImpEx script.');
+    }
+    const env = await getEnvironment(environmentId);
+    if (!env) {
+      mcpLog({ tool: TOOL, envName: environmentId, preview: 'Unknown environment', isError: true });
+      return error(`Environment "${environmentId}" not found.`);
+    }
+    if (!env.allowImpexImport) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'ImpEx disabled', isError: true });
+      return error(`ImpEx import is disabled for environment "${env.name}".`);
+    }
+
+    const scriptPreview = script.split('\n')[0].slice(0, 60);
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview: `${scriptPreview}…` });
+
+    let validationWarnings = [];
+    try {
+      validationWarnings = await validateImpexScript(env, script);
+    } catch (_) {}
+
+    if (validationWarnings.length) {
+      const warnOut = `**Pre-validation warnings** (import not executed):\n${validationWarnings.map(w => `- ${w}`).join('\n')}\n\nFix the script and retry.`;
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Pre-validation failed', detail: warnOut, isError: true, runId });
+      return error(warnOut);
+    }
+
+    let result;
+    try {
+      result = await withSession(env, s => impexImport(s, script, {
+        validationEnum, maxThreads, legacyMode, enableCodeExecution, distributedMode, sldEnabled,
+      }));
+    } catch (e) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Error: ${e.message}`, detail: e.stack || '', isError: true, runId });
+      return error(e.message);
+    }
+
+    const isErr = result.level === 'error';
+    const icon = isErr ? '❌' : '✅';
+    let out = `**${env.name}** - ${icon} ${result.result || 'Import complete'}\n`;
+    if (result.details) out += `\n\`\`\`\n${formatImpexDetails(result.details)}\n\`\`\``;
+
+    if (isErr && result.details) {
+      const unknownAttrTypes = [...new Set(
+        [...result.details.matchAll(/unknown attributes \[(\w+)\.\w+\]/g)].map(m => m[1])
+      )];
+      if (unknownAttrTypes.length) {
+        const hints = [];
+        for (const typeName of unknownAttrTypes) {
+          const fields = await fetchScalarFields(env, typeName);
+          if (fields) hints.push(`**${typeName}** valid scalar fields:\n  ${fields}`);
+        }
+        if (hints.length) out += `\n\n**Field hints** (use get_type_info for relation fields):\n${hints.join('\n\n')}`;
+      }
+    }
+
+    mcpLog({ tool: TOOL, envName: env.name,
+      preview: `${isErr ? '❌' : '✅'} ${result.result || 'Done'} - ${scriptPreview}…`,
+      detail: `Script:\n${script}\n\nResult: ${result.result}\n\n${result.details || ''}`,
+      isError: isErr, runId,
+    });
+    return text(out);
+  },
+};

package/tools/index.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { callCtx } from './context.js';
+import { tool as listEnvironments } from './list_environments.js';
+import { tool as flexibleSearch } from './flexible_search.js';
+import { tool as searchType } from './search_type.js';
+import { tool as getTypeInfo } from './get_type_info.js';
+import { tool as resolvePk } from './resolve_pk.js';
+import { tool as impexImport } from './impex_import.js';
+import { tool as groovyExecute } from './groovy_execute.js';
+import { tool as readProperty } from './read_property.js';
+import { tool as mediaRead } from './media_read.js';
+import { tool as mediaWrite } from './media_write.js';
+import { tool as runCronjob } from './run_cronjob.js';
+import { tool as listCronjobs } from './list_cronjobs.js';
+
+const tools = [
+  listEnvironments,
+  flexibleSearch,
+  searchType,
+  getTypeInfo,
+  resolvePk,
+  impexImport,
+  groovyExecute,
+  readProperty,
+  mediaRead,
+  mediaWrite,
+  runCronjob,
+  listCronjobs,
+];
+
+export { tools };
+
+export function registerAllTools(mcp, getClientLabel) {
+  for (const { name, description, handler, inputSchema } of tools) {
+    mcp.registerTool(name, { description, inputSchema: z.object(inputSchema ?? {}) }, (args, extra) => {
+      const client = getClientLabel?.(extra?.sessionId) ?? null;
+      return callCtx.run({ client }, () => handler(args, extra));
+    });
+  }
+}

package/tools/list_cronjobs.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { flexibleSearch } from '../hac.js';
+import { withSession, getEnvironment, mcpLogStart, mcpLog, text, error } from './context.js';
+
+const TOOL = 'list_cronjobs';
+
+export const tool = {
+  name: TOOL,
+  category: 'read',
+  description: 'List CronJobs on a SAP Commerce environment. Optionally filter by code (partial match). Returns pk, code, type, status, result, and last start/end times.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    code: z.string().optional().describe('Filter by code (case-insensitive partial match)'),
+  },
+  handler: async ({ environmentId, code }) => {
+    const env = await getEnvironment(environmentId);
+    if (!env) {
+      mcpLog({ tool: TOOL, envName: environmentId, preview: 'Unknown environment', isError: true });
+      return error(`Environment "${environmentId}" not found.`);
+    }
+    if (!env.allowFlexSearch) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'FlexSearch disabled', isError: true });
+      return error(`FlexibleSearch is disabled for environment "${env.name}".`);
+    }
+
+    const where = code ? ` WHERE {cj:code} LIKE '%${code.replace(/'/g, "''")}%'` : '';
+    const query = `SELECT {cj:pk}, {cj:code}, {t:code}, {s:code}, {r:code}, {cj:startTime}, {cj:endTime} FROM {CronJob AS cj LEFT JOIN EnumerationValue AS s ON {cj:status} = {s:pk} LEFT JOIN EnumerationValue AS r ON {cj:result} = {r:pk} LEFT JOIN ComposedType AS t ON {cj:itemtype} = {t:pk}}${where} ORDER BY {cj:code} ASC`;
+
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview: code ? `Listing CronJobs matching "${code}"` : 'Listing all CronJobs' });
+
+    let result;
+    try {
+      result = await withSession(env, s => flexibleSearch(s, query, { maxCount: 500 }));
+    } catch (e) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Error: ${e.message}`, detail: e.stack || '', isError: true, runId });
+      return error(e.message);
+    }
+
+    if (result.exception) {
+      const msg = result.exception.message || JSON.stringify(result.exception);
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Query error', detail: msg, isError: true, runId });
+      return error(`Query error: ${msg}`);
+    }
+
+    let { resultList, resultCount, executionTime } = result;
+    mcpLog({ tool: TOOL, envName: env.name, preview: `✅ ${resultCount} CronJob(s) in ${executionTime}ms`, runId });
+
+    if (code && resultList?.length) {
+      const q = code.toLowerCase();
+      const score = (row) => {
+        const c = (row[1] || '').toLowerCase();
+        if (c === q) return 0;
+        if (c.startsWith(q)) return 1;
+        return 2;
+      };
+      resultList = [...resultList].sort((a, b) => score(a) - score(b) || a[1].localeCompare(b[1]));
+    }
+
+    let out = `**${env.name}** - ${resultCount} CronJob(s) in ${executionTime}ms\n\n`;
+    if (resultList?.length) {
+      out += 'pk,code,type,status,result,startTime,endTime\n';
+      const csvCell = c => {
+        if (c === null) return '';
+        const s = String(c);
+        return (s.includes(',') || s.includes('"') || s.includes('\n')) ? `"${s.replace(/"/g, '""')}"` : s;
+      };
+      for (const row of resultList) out += row.map(csvCell).join(',') + '\n';
+    } else {
+      out += 'No CronJobs found.\n';
+    }
+
+    return text(out);
+  },
+};

package/tools/list_environments.js

@@ -0,0 +1,25 @@
+import { listEnvironments, mcpLogStart, mcpLog, text } from './context.js';
+
+const TOOL = 'list_environments';
+
+export const tool = {
+  name: TOOL,
+  category: 'utility',
+  description: 'List all configured HAC environments with their names, descriptions, and allowed operations.',
+  handler: async () => {
+    const runId = mcpLogStart({ tool: TOOL, envName: '', preview: 'Listing environments…' });
+    const envs = await listEnvironments();
+    if (!envs.length) {
+      mcpLog({ tool: TOOL, envName: '', preview: 'No environments configured', detail: 'No environments found.', runId });
+      return text('No environments configured. Add one via the management UI.');
+    }
+    const lines = envs.map(e =>
+      `- **${e.name}** (id: \`${e.id}\`)\n` +
+      `  ${e.description || 'No description'}\n` +
+      `  DB: ${e.dbType || 'unknown'}  FlexSearch: ${e.allowFlexSearch ? '✅' : '❌'}  ImpEx Import: ${e.allowImpexImport ? '✅' : '❌'}  Groovy: ${e.allowGroovyExecution ? '✅' : '❌'}  Read Property: ${e.allowReadProperty !== false ? '✅' : '❌'}`
+    );
+    const out = `## HAC Environments\n\n${lines.join('\n\n')}`;
+    mcpLog({ tool: TOOL, envName: '', preview: `${envs.length} environment(s)`, detail: out, runId });
+    return text(out);
+  },
+};

package/tools/media_read.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { groovyExecute } from '../hac.js';
+import { withSession, getEnvironment, mcpLogStart, mcpLog, text, error } from './context.js';
+
+const TOOL = 'media_read';
+
+const SCRIPT = (pk) => `
+import de.hybris.platform.core.PK
+import de.hybris.platform.servicelayer.media.MediaService
+
+def mediaService = spring.getBean('mediaService')
+def modelService = spring.getBean('modelService')
+
+def media = modelService.get(PK.fromLong(${pk}L))
+if (media.mime && media.mime != 'text/plain') {
+  throw new RuntimeException("media_read only supports text/plain media, but this media has mime: \${media.mime}")
+}
+def stream = mediaService.getStreamFromMedia(media)
+def bytes = stream.bytes
+stream.close()
+bytes.encodeBase64().toString()
+`.trim();
+
+function decodeTextBytes(bytes) {
+  // UTF-16LE with real BOM (FF FE)
+  if (bytes.length >= 2 && bytes[0] === 0xFF && bytes[1] === 0xFE) {
+    return bytes.slice(2).toString('utf16le');
+  }
+  // UTF-16LE with mangled BOM (FF FE encoded as UTF-8 replacement chars: EF BF BD EF BF BD)
+  if (bytes.length >= 8 &&
+      bytes[0] === 0xEF && bytes[1] === 0xBF && bytes[2] === 0xBD &&
+      bytes[3] === 0xEF && bytes[4] === 0xBF && bytes[5] === 0xBD &&
+      bytes[7] === 0x00) {
+    return bytes.slice(6).toString('utf16le');
+  }
+  // UTF-8 with BOM (EF BB BF)
+  if (bytes.length >= 3 && bytes[0] === 0xEF && bytes[1] === 0xBB && bytes[2] === 0xBF) {
+    return bytes.slice(3).toString('utf-8');
+  }
+  return bytes.toString('utf-8');
+}
+
+export const tool = {
+  name: TOOL,
+  category: 'read',
+  description: 'Read the text content of a SAP Commerce MediaModel by its PK. Only supports text/plain media.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    mediaPk: z.string().describe('PK of the MediaModel to read'),
+  },
+  handler: async ({ environmentId, mediaPk }) => {
+    const env = await getEnvironment(environmentId);
+    if (!env) {
+      mcpLog({ tool: TOOL, envName: environmentId, preview: 'Unknown environment', isError: true });
+      return error(`Environment "${environmentId}" not found.`);
+    }
+    if (!env.allowGroovyExecution) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Groovy disabled', isError: true });
+      return error(`Groovy execution is disabled for environment "${env.name}".`);
+    }
+
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview: `Reading media PK ${mediaPk}` });
+
+    let result;
+    try {
+      result = await withSession(env, s => groovyExecute(s, SCRIPT(mediaPk)));
+    } catch (e) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Error: ${e.message}`, detail: e.stack || '', isError: true, runId });
+      return error(e.message);
+    }
+
+    if (result.stacktraceText) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `❌ PK ${mediaPk}`, detail: result.stacktraceText, isError: true, runId });
+      let out = `**${env.name}** - ❌ Error reading media PK ${mediaPk}\n`;
+      out += `\n**Stacktrace:**\n\`\`\`\n${result.stacktraceText}\n\`\`\``;
+      return { content: [{ type: 'text', text: out }], isError: true };
+    }
+
+    const base64 = (result.executionResult || '').trim();
+    const content = decodeTextBytes(Buffer.from(base64, 'base64'));
+
+    mcpLog({ tool: TOOL, envName: env.name, preview: `✅ PK ${mediaPk} (${content.length} chars)`, runId });
+
+    return text(`**${env.name}** - ✅ Media PK ${mediaPk}\n\n**Content:**\n\`\`\`\n${content}\n\`\`\``);
+  },
+};

package/tools/media_write.js

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { groovyExecute } from '../hac.js';
+import { withSession, getEnvironment, mcpLogStart, mcpLog, text, error } from './context.js';
+
+const TOOL = 'media_write';
+
+const SCRIPT_OVERWRITE = (mediaPk, base64, realFileName) => `
+import de.hybris.platform.core.PK
+
+def mediaService = spring.getBean('mediaService')
+def modelService = spring.getBean('modelService')
+
+def media = modelService.get(PK.fromLong(${mediaPk}L))
+def bytes = "${base64}".decodeBase64()
+mediaService.setStreamForMedia(media, new java.io.ByteArrayInputStream(bytes), ${realFileName ? `"${realFileName}"` : 'media.realFileName ?: media.code'}, "text/plain")
+"OK - wrote \${bytes.length} bytes to media \${media.pk}"
+`.trim();
+
+const SCRIPT_CREATE = (targetPk, targetField, base64, realFileName, mediaCode, catalogVersionPk) => `
+import de.hybris.platform.core.PK
+
+def mediaService = spring.getBean('mediaService')
+def modelService = spring.getBean('modelService')
+def typeService = spring.getBean('typeService')
+
+def target = modelService.get(PK.fromLong(${targetPk}L))
+def typecode = target.itemtype
+def attrDesc = typeService.getAttributeDescriptor(typecode, "${targetField}")
+def mediaTypecode = attrDesc.attributeType.code
+
+def media = modelService.create(mediaTypecode)
+media.code = ${mediaCode ? `"${mediaCode}"` : `"media_" + System.currentTimeMillis()`}
+
+// assign catalog version only for catalog-aware media types (where catalogVersion is mandatory)
+def needsCatalogVersion = false
+try {
+  def cvAttr = typeService.getAttributeDescriptor(typeService.getComposedTypeForCode(mediaTypecode), 'catalogVersion')
+  needsCatalogVersion = !cvAttr.optional
+} catch (Exception e) { /* no catalogVersion attribute */ }
+if (needsCatalogVersion) {
+  ${catalogVersionPk
+    ? `media.catalogVersion = modelService.get(PK.fromLong(${catalogVersionPk}L))`
+    : `if (target.hasProperty('catalogVersion') && target.catalogVersion != null) {
+    media.catalogVersion = target.catalogVersion
+  } else {
+    throw new RuntimeException("Media type '\${mediaTypecode}' requires a catalog version but none could be inferred from the target item. Provide catalogVersionPk explicitly.")
+  }`
+  }
+}
+
+modelService.save(media)
+
+def bytes = "${base64}".decodeBase64()
+mediaService.setStreamForMedia(media, new java.io.ByteArrayInputStream(bytes), ${realFileName ? `"${realFileName}"` : `media.code + ".txt"`}, "text/plain")
+
+target."${targetField}" = media
+modelService.save(target)
+
+"OK - created media \${media.pk} (\${mediaTypecode}, code=\${media.code}), wrote \${bytes.length} bytes, assigned to \${typecode}.\${target.pk}.${targetField}"
+`.trim();
+
+export const tool = {
+  name: TOOL,
+  category: 'write',
+  description: 'Write text/plain content to a SAP Commerce MediaModel. If mediaPk is provided, overwrites the existing media stream. Otherwise creates a new media by inspecting the target item\'s field type, sets the stream, and assigns it back to the field. IMPORTANT: Before calling this tool, show the user what will be written and ask for confirmation. Set confirmed_by_user to true only after the user approves.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    content: z.string().describe('Text content to write (UTF-8)'),
+    confirmed_by_user: z.boolean().describe('Must be true - user has explicitly reviewed what will be written and approved. The server will reject the call if false.'),
+    mediaPk: z.string().optional().describe('PK of an existing MediaModel to overwrite. If provided, targetPk/targetField are ignored.'),
+    targetPk: z.string().optional().describe('PK of the item that owns the media field. Required when mediaPk is not provided.'),
+    targetField: z.string().optional().describe('Attribute name on the target item (e.g. "content"). Used to determine media type and assign after creation.'),
+    realFileName: z.string().optional().describe('Filename for the media (e.g. "import.txt")'),
+    mediaCode: z.string().optional().describe('Code for the new media item. Auto-generated if not provided.'),
+    catalogVersionPk: z.string().optional().describe('PK of the CatalogVersion to assign to the new media. Only needed for catalog-aware media types. If absent, inferred from the target item.'),
+  },
+  handler: async ({ environmentId, content: contentStr, mediaPk, targetPk, targetField, realFileName, mediaCode, catalogVersionPk, confirmed_by_user }) => {
+    if (!confirmed_by_user) {
+      return error('User confirmation required. Show the user what content will be written and to which media, ask for explicit approval, then retry with confirmed_by_user: true.');
+    }
+    const env = await getEnvironment(environmentId);
+    if (!env) {
+      mcpLog({ tool: TOOL, envName: environmentId, preview: 'Unknown environment', isError: true });
+      return error(`Environment "${environmentId}" not found.`);
+    }
+    if (!env.allowGroovyExecution) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Groovy disabled', isError: true });
+      return error(`Groovy execution is disabled for environment "${env.name}".`);
+    }
+    if (env.allowGroovyCommitMode === false) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Groovy commit mode disabled', isError: true });
+      return error(`Groovy commit mode is disabled for environment "${env.name}".`);
+    }
+    if (!mediaPk && (!targetPk || !targetField)) {
+      return error('Either mediaPk or both targetPk and targetField must be provided.');
+    }
+
+    const base64 = Buffer.from(contentStr, 'utf-8').toString('base64');
+    const preview = mediaPk ? `Overwriting media PK ${mediaPk}` : `Creating media for ${targetField} on PK ${targetPk}`;
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview });
+
+    const script = mediaPk
+      ? SCRIPT_OVERWRITE(mediaPk, base64, realFileName)
+      : SCRIPT_CREATE(targetPk, targetField, base64, realFileName, mediaCode, catalogVersionPk);
+
+    let result;
+    try {
+      result = await withSession(env, s => groovyExecute(s, script, { commit: true }));
+    } catch (e) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Error: ${e.message}`, detail: e.stack || '', isError: true, runId });
+      return error(e.message);
+    }
+
+    const isErr = !!result.stacktraceText;
+    mcpLog({ tool: TOOL, envName: env.name, preview: `${isErr ? '❌' : '✅'} ${preview}`, detail: result.stacktraceText || result.executionResult || '', isError: isErr, runId });
+
+    let out = `**${env.name}** - ${isErr ? '❌ Error' : '✅ Success'}\n`;
+    if (result.executionResult) out += `\n**Result:**\n\`\`\`\n${result.executionResult}\n\`\`\``;
+    if (result.stacktraceText) out += `\n**Stacktrace:**\n\`\`\`\n${result.stacktraceText}\n\`\`\``;
+    return isErr ? { content: [{ type: 'text', text: out }], isError: true } : text(out);
+  },
+};

package/tools/read_property.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { readProperties } from '../hac.js';
+import { withSession, getEnvironment, mcpLogStart, mcpLog, text, error } from './context.js';
+
+const TOOL = 'read_property';
+
+export const tool = {
+  name: TOOL,
+  category: 'read',
+  description: 'Search HAC configuration properties by key or value. Returns matching key-value pairs from the platform configuration page.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    search: z.string().describe('Search term - matches against property keys and values (case-insensitive substring)'),
+  },
+  handler: async ({ environmentId, search }) => {
+    const env = await getEnvironment(environmentId);
+    if (!env) {
+      mcpLog({ tool: TOOL, envName: environmentId, preview: 'Unknown environment', isError: true });
+      return error(`Environment "${environmentId}" not found.`);
+    }
+    if (env.allowReadProperty === false) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Read property disabled', isError: true });
+      return error(`Read property is disabled for environment "${env.name}".`);
+    }
+
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview: `Searching "${search}"…` });
+
+    let properties;
+    try {
+      properties = await withSession(env, s => readProperties(s));
+    } catch (e) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Error: ${e.message}`, isError: true, runId });
+      return error(e.message);
+    }
+
+    const term = search.toLowerCase();
+    const matches = Object.entries(properties).filter(
+      ([k, v]) => k.toLowerCase().includes(term) || v.toLowerCase().includes(term)
+    );
+
+    if (!matches.length) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `No properties matching "${search}"`, runId });
+      return text(`No properties found matching "${search}".`);
+    }
+
+    const lines = matches.map(([k, v]) => `${k} = ${v}`).join('\n');
+    const out = `**${env.name}** - ${matches.length} property match(es) for "${search}":\n\n\`\`\`\n${lines}\n\`\`\``;
+    mcpLog({ tool: TOOL, envName: env.name, preview: `${matches.length} match(es) for "${search}"`, detail: out, runId });
+    return text(out);
+  },
+};

package/tools/resolve_pk.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { flexibleSearch, pkAnalyze } from '../hac.js';
+import { withSession, getEnvironment, isTruthy, mcpLogStart, mcpLog, text, error } from './context.js';
+
+const TOOL = 'resolve_pk';
+
+export const tool = {
+  name: TOOL,
+  category: 'read',
+  description: 'Resolve a SAP Commerce PK to its type code and unique field values. Use this when a FlexibleSearch result contains an opaque PK and you need to know what item it refers to.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    pk: z.string().describe('The PK value to resolve'),
+  },
+  handler: async ({ environmentId, pk }) => {
+    const env = await getEnvironment(environmentId);
+    if (!env) {
+      mcpLog({ tool: TOOL, envName: environmentId, preview: 'Unknown environment', isError: true });
+      return error(`Environment "${environmentId}" not found.`);
+    }
+    if (!env.allowFlexSearch) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'FlexSearch disabled', isError: true });
+      return error(`FlexibleSearch is disabled for environment "${env.name}".`);
+    }
+
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview: `Resolving PK ${pk}…` });
+
+    let analysis;
+    try {
+      analysis = await withSession(env, s => pkAnalyze(s, pk));
+    } catch (e) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Error: ${e.message}`, isError: true, runId });
+      return error(`PK analysis failed: ${e.message}`);
+    }
+
+    if (analysis.possibleException) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Invalid PK ${pk}`, detail: analysis.possibleException, isError: true, runId });
+      return error(`Invalid PK ${pk}: ${analysis.possibleException}`);
+    }
+
+    const typeCode = analysis.pkComposedTypeCode;
+    let out = `PK ${pk} → **${typeCode}** (typeCode: ${analysis.pkTypeCode})\nCreated: ${analysis.pkCreationDate}\n`;
+
+    if (typeCode && typeCode !== 'Item') {
+      let uniqueFields = [];
+      try {
+        const typePKResult = await withSession(env, s => flexibleSearch(s,
+          `SELECT {pk} FROM {ComposedType} WHERE {code} = '${typeCode}'`
+        ));
+        const typePK = typePKResult.resultList?.[0]?.[0];
+        if (typePK) {
+          const attrResult = await withSession(env, s => flexibleSearch(s,
+            `SELECT {qualifier}, {unique} FROM {AttributeDescriptor} WHERE {enclosingtype} = '${typePK}'`,
+            { maxCount: 200 }
+          ));
+          uniqueFields = (attrResult.resultList || [])
+            .filter(([, isUnique]) => isTruthy(isUnique))
+            .map(([q]) => q);
+        }
+      } catch (_) {}
+
+      const fieldsToFetch = uniqueFields.length ? uniqueFields : ['pk'];
+      try {
+        const selectFields = fieldsToFetch.map(f => `{${f}}`).join(', ');
+        const itemResult = await withSession(env, s => flexibleSearch(s,
+          `SELECT ${selectFields} FROM {${typeCode}} WHERE {pk} = '${pk}'`
+        ));
+        if (itemResult.resultList?.[0]) {
+          out += '\nUnique fields:\n';
+          for (const [i, f] of fieldsToFetch.entries()) {
+            out += `  ${f}: ${itemResult.resultList[0][i] ?? 'null'}\n`;
+          }
+        } else {
+          out += '\n(Item not found - may have been deleted)\n';
+        }
+      } catch (e) {
+        out += `\n(Could not fetch item details: ${e.message})\n`;
+      }
+    }
+
+    mcpLog({ tool: TOOL, envName: env.name, preview: `PK ${pk} → ${typeCode}`, detail: out, runId });
+    return text(out);
+  },
+};