hac-mcp 1.0.0

package/tools/context.js

@@ -0,0 +1,107 @@
+// Shared runtime context injected into every tool registration.
+// server.js creates one instance and passes it to each tool's register().
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { login, SessionExpiredError } from '../hac.js';
+import { getEnvironment, listEnvironments } from '../storage.js';
+import { getIndex, invalidateIndex, fuzzySearch } from '../type-index.js';
+import { flexibleSearch } from '../hac.js';
+
+// ─── HAC session manager ──────────────────────────────────────────────────────
+const sessions  = new Map(); // envId → session
+const loginLock = new Map(); // envId → Promise<session>
+
+async function getSession(env) {
+  if (sessions.has(env.id)) return sessions.get(env.id);
+  if (loginLock.has(env.id)) return loginLock.get(env.id);
+  const promise = login(env.url, env.username, env.password, env.name)
+    .then(session => { sessions.set(env.id, session); return session; })
+    .finally(() => loginLock.delete(env.id));
+  loginLock.set(env.id, promise);
+  return promise;
+}
+
+function invalidateSession(envId) {
+  sessions.delete(envId);
+  invalidateIndex(envId);
+}
+
+async function withSession(env, fn) {
+  const session = await getSession(env);
+  try {
+    return await fn(session);
+  } catch (e) {
+    if (e instanceof SessionExpiredError) {
+      console.error(`[MCP] Session expired for "${env.name}", re-logging in…`);
+      invalidateSession(env.id);
+      const fresh = await getSession(env);
+      return fn(fresh);
+    }
+    throw e;
+  }
+}
+
+// ─── MCP activity log ─────────────────────────────────────────────────────────
+const logClients = new Set();
+const mcpLogBuffer = [];
+const callCtx = new AsyncLocalStorage();
+
+function broadcastLog(entry) {
+  const ctx = callCtx.getStore();
+  const enriched = ctx ? { ...entry, client: ctx.client } : entry;
+  mcpLogBuffer.push(enriched);
+  if (mcpLogBuffer.length > 50) mcpLogBuffer.shift();
+  const data = `data: ${JSON.stringify(enriched)}\n\n`;
+  for (const res of logClients) res.write(data);
+}
+
+function mcpLogSystem({ client, preview, detail = '' }) {
+  broadcastLog({ id: null, tool: null, client, preview, detail, status: 'system', ts: Date.now() });
+}
+
+function mcpLogStart({ tool, envName, preview }) {
+  const id = Date.now().toString(36) + Math.random().toString(36).slice(2);
+  broadcastLog({ id, tool, envName, preview, status: 'running', ts: Date.now() });
+  return id;
+}
+
+function mcpLog({ tool, envName, preview, detail = '', isError = false, runId = null }) {
+  broadcastLog({ id: runId, tool, envName, preview, detail, isError, status: 'done', ts: Date.now() });
+  console.error(`[MCP] ${tool}${envName ? ' / ' + envName : ''} - ${preview}`);
+}
+
+function attachLogClient(res) { logClients.add(res); }
+function detachLogClient(res) { logClients.delete(res); }
+function getMcpLogBuffer() { return mcpLogBuffer; }
+
+// ─── Type index ───────────────────────────────────────────────────────────────
+async function getTypeIndex(env) {
+  return getIndex(env.id, (query, opts) => withSession(env, s => flexibleSearch(s, query, opts)));
+}
+
+// ─── Shared utilities ─────────────────────────────────────────────────────────
+// FlexibleSearch returns booleans as true/false, 1/0, or 'true'/'false' strings
+const isTruthy = v => v === true || v === 'true' || v === 1 || v === '1';
+
+// ─── Response helpers ─────────────────────────────────────────────────────────
+function text(t) { return { content: [{ type: 'text', text: t }] }; }
+function error(msg) { return { content: [{ type: 'text', text: `**Error:** ${msg}` }], isError: true }; }
+
+export {
+  callCtx,
+  isTruthy,
+  getSession,
+  withSession,
+  getEnvironment,
+  listEnvironments,
+  fuzzySearch,
+  getTypeIndex,
+  mcpLogStart,
+  mcpLog,
+  attachLogClient,
+  detachLogClient,
+  getMcpLogBuffer,
+  mcpLogSystem,
+  text,
+  error,
+};

package/tools/flexible_search.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+import { flexibleSearch } from '../hac.js';
+import { withSession, getEnvironment, getTypeIndex, fuzzySearch, isTruthy, mcpLogStart, mcpLog, text, error } from './context.js';
+import { optionalLooseNumber } from './zodLoose.js';
+
+const TOOL = 'flexible_search';
+
+function parseFlexSearchError(msg) {
+  if (!msg?.includes('cannot search unknown field')) return null;
+  const unknownField = msg.match(/TableField\(name='([^']+)'/)?.[1];
+  const typeCode = msg.match(/within type (\w+)/)?.[1];
+  const parseSection = str => str ? [...str.matchAll(/^\s{6}(\w+)\s*=/gm)].map(m => m[1]) : [];
+  const core = parseSection(msg.match(/core fields\s*=\s*\n([\s\S]*?)(?=\n\s{3}\w+ fields)/)?.[1]);
+  const unlocalized = parseSection(msg.match(/unlocalized fields\s*=\s*\n([\s\S]*?)(?=\n\s{3}\w+ fields)/)?.[1]);
+  const localized = parseSection(msg.match(/localized fields\s*=\s*\n([\s\S]*?)(?=\n\))/)?.[1]);
+  const allFields = [...core, ...unlocalized, ...localized];
+  if (!typeCode || !allFields.length) return null;
+  return { unknownField, typeCode, allFields };
+}
+
+function parseUnknownTypeError(msg) {
+  if (!msg) return null;
+  const m = msg.match(/unknown type[:\s]+'?(\w+)'?/i) || msg.match(/[Tt]he type '(\w+)' is unknown/);
+  return m?.[1] ?? null;
+}
+
+export async function fetchScalarFields(env, typeCode) {
+  try {
+    const typeResult = await withSession(env, s => flexibleSearch(s,
+      `SELECT {pk} FROM {ComposedType} WHERE {code} = '${typeCode}'`
+    ));
+    const typePK = typeResult.resultList?.[0]?.[0];
+    if (!typePK) return null;
+
+    const attrResult = await withSession(env, s => flexibleSearch(s,
+      `SELECT {qualifier}, {databasecolumn}, {attributetype}, {unique} FROM {AttributeDescriptor} WHERE {enclosingtype} = '${typePK}' ORDER BY {qualifier} ASC`,
+      { maxCount: 300 }
+    ));
+    if (!attrResult.resultList?.length) return null;
+
+    const scalar = attrResult.resultList.filter(([, dbCol]) => dbCol);
+    const attrTypePKs = [...new Set(scalar.map(([,, attrTypePK]) => attrTypePK).filter(Boolean))];
+    const refTypes = {};
+    if (attrTypePKs.length) {
+      const conds = attrTypePKs.map(p => `{pk} = '${p}'`).join(' OR ');
+      const r = await withSession(env, s => flexibleSearch(s,
+        `SELECT {pk}, {code} FROM {ComposedType} WHERE ${conds}`
+      ));
+      if (r.resultList) for (const [tpk, tcode] of r.resultList) refTypes[String(tpk)] = tcode;
+    }
+
+    return scalar.map(([q,, attrTypePK, isUnique]) => {
+      const refType = attrTypePK ? refTypes[String(attrTypePK)] : null;
+      let s = q;
+      if (isTruthy(isUnique)) s += ' [unique]';
+      if (refType) s += ` → ${refType}`;
+      return s;
+    }).join(', ');
+  } catch (_) { return null; }
+}
+
+export const tool = {
+  name: TOOL,
+  category: 'read',
+  description: 'Execute a FlexibleSearch query on a HAC environment. Call list_environments first to get valid IDs. IMPORTANT: The database is MSSQL - do NOT use LIMIT, TOP, or OFFSET in queries; use the maxCount parameter to limit rows instead.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    query: z.string().describe('FlexibleSearch query, e.g. SELECT {pk}, {uid} FROM {User}'),
+    maxCount: optionalLooseNumber().describe('Max rows to return (default 200)'),
+    locale: z.string().optional().describe('Locale (default en)'),
+    dataSource: z.string().optional().describe('Data source (default master)'),
+  },
+  handler: async ({ environmentId, query, maxCount, locale, dataSource }) => {
+    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 preview = `${query.slice(0, 60)}${query.length > 60 ? '…' : ''}`;
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview });
+
+    const rowLimitMatch = query.match(/\b(LIMIT|TOP|ROWNUM|FETCH\s+FIRST|ROWS\s+ONLY)\b/i);
+    if (rowLimitMatch) {
+      const msg = `Do not use row-limiting clauses (LIMIT, TOP, ROWNUM, FETCH FIRST, ROWS ONLY) in FlexibleSearch queries - use the maxCount parameter to limit rows instead.`;
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Query error', detail: msg, isError: true, runId });
+      return error(`Query error: ${msg}`);
+    }
+
+    let result;
+    try {
+      result = await withSession(env, s => flexibleSearch(s, query, { maxCount, locale, dataSource }));
+    } 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 ex = result.exception;
+      const msg = ex.message || ex.localizedMessage || JSON.stringify(ex);
+      const causeMsg = ex.cause?.message;
+      const rawDetail = causeMsg && causeMsg !== msg ? `${msg}\nCaused by: ${causeMsg}` : msg;
+
+      const parsed = parseFlexSearchError(causeMsg) || parseFlexSearchError(msg);
+      if (parsed) {
+        const { unknownField, typeCode: parsedTypeCode } = parsed;
+        let detail = `Unknown field "{${unknownField}}" on type ${parsedTypeCode}.`;
+        const scalarFields = await fetchScalarFields(env, parsedTypeCode);
+        if (scalarFields) {
+          detail += `\n\nValid scalar fields for ${parsedTypeCode}:\n  ${scalarFields}\n\nFor relation/collection fields use get_type_info.`;
+        } else {
+          detail += `\n\nTip: use get_type_info with typeCode "${parsedTypeCode}" to see valid fields.`;
+        }
+        mcpLog({ tool: TOOL, envName: env.name, preview: 'Query error', detail, isError: true, runId });
+        return error(`Query error: ${detail}`);
+      }
+
+      const unknownType = parseUnknownTypeError(causeMsg) || parseUnknownTypeError(msg);
+      if (unknownType) {
+        let detail = `Unknown type "${unknownType}".`;
+        try {
+          const types = await getTypeIndex(env);
+          const suggestions = fuzzySearch(unknownType, types, { topN: 5 });
+          if (suggestions.length) detail += ` Did you mean: ${suggestions.join(', ')}?`;
+        } catch (_) {}
+        mcpLog({ tool: TOOL, envName: env.name, preview: 'Query error', detail, isError: true, runId });
+        return error(`Query error: ${detail}`);
+      }
+
+
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Query error', detail: rawDetail, isError: true, runId });
+      return error(`Query error: ${rawDetail}`);
+    }
+
+    const { headers, resultList, resultCount, executionTime } = result;
+    let out = `**${env.name}** - ${resultCount} row(s) in ${executionTime}ms\n\n`;
+
+    if (resultList?.length) {
+      const csvCell = c => {
+        if (c === null) return '';
+        const s = String(c);
+        return (s.includes(',') || s.includes('"') || s.includes('\n')) ? `"${s.replace(/"/g, '""')}"` : s;
+      };
+      out += (headers || []).map(csvCell).join(',') + '\n';
+      for (const row of resultList) out += row.map(csvCell).join(',') + '\n';
+    } else {
+      out += 'No results.\n';
+    }
+
+    mcpLog({ tool: TOOL, envName: env.name,
+      preview: `${resultCount} row(s) in ${executionTime}ms - ${preview}`,
+      detail: `Query: ${query}\n\nResult:\n${out}`,
+      runId,
+    });
+    return text(out);
+  },
+};

package/tools/get_type_info.js

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import { flexibleSearch } from '../hac.js';
+import { optionalLooseBool } from './zodLoose.js';
+import { withSession, getEnvironment, isTruthy, mcpLogStart, mcpLog, text, error } from './context.js';
+
+const TOOL = 'get_type_info';
+
+export const tool = {
+  name: TOOL,
+  category: 'read',
+  description: 'Get metadata and queryable fields for a SAP Commerce type. Use this when a FlexibleSearch query fails with unknown field errors to discover the correct field qualifiers. The database is MSSQL - do NOT use LIMIT, TOP, or OFFSET in FlexibleSearch queries; use the maxCount parameter instead.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    typeCode: z.string().optional().describe('Type code to look up, e.g. SolrFacetSearchConfig, Order, Product'),
+    type: z.string().optional().describe('Alias for typeCode if the client sends this key instead'),
+    includeInherited: optionalLooseBool().describe('Also include attributes inherited from supertypes (default false)'),
+  },
+  handler: async ({ environmentId, typeCode, type: typeArg, includeInherited }) => {
+    const env = await getEnvironment(environmentId);
+    if (!env) {
+      mcpLog({ tool: TOOL, envName: environmentId, preview: 'Unknown environment', isError: true });
+      return error(`Environment "${environmentId}" not found.`);
+    }
+
+    const resolvedType = typeCode ?? typeArg;
+    if (!resolvedType) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Missing typeCode', isError: true });
+      return error('Provide typeCode (or type) with the Commerce type code.');
+    }
+
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview: `Type info: ${resolvedType}` });
+
+    let typeResult;
+    try {
+      typeResult = await withSession(env, s => flexibleSearch(s,
+        `SELECT {pk}, {code}, {supertype}, {jaloclass}, {inheritancepathstring}, {extensionname}, {catalogitemtype}, {singleton} FROM {ComposedType} WHERE {code} = '${resolvedType}'`
+      ));
+    } catch (e) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Error: ${e.message}`, isError: true, runId });
+      return error(e.message);
+    }
+
+    if (typeResult.exception) {
+      const ex = typeResult.exception;
+      const msg = ex.message || ex.localizedMessage || JSON.stringify(ex);
+      mcpLog({ tool: TOOL, envName: env.name, preview: 'Query error', detail: msg, isError: true, runId });
+      return error(msg);
+    }
+
+    if (!typeResult.resultList?.length) {
+      mcpLog({ tool: TOOL, envName: env.name, preview: `Type not found: ${resolvedType}`, isError: true, runId });
+      return error(`Type "${resolvedType}" not found. Check the type code (case-sensitive).`);
+    }
+
+    const [pk, code, supertypePK, , inheritancePath] = typeResult.resultList[0];
+
+    const typePKs = includeInherited
+      ? inheritancePath.split(',').filter(Boolean)
+      : [String(pk)];
+
+    let ancestorNames = {};
+    if (includeInherited && typePKs.length > 1) {
+      try {
+        const ancestorPKConditions = typePKs.map(p => `{pk} = '${p}'`).join(' OR ');
+        const ancestorResult = await withSession(env, s => flexibleSearch(s,
+          `SELECT {pk}, {code} FROM {ComposedType} WHERE ${ancestorPKConditions}`
+        ));
+        if (ancestorResult.resultList) {
+          for (const [apk, acode] of ancestorResult.resultList) ancestorNames[String(apk)] = acode;
+        }
+      } catch (_) {}
+    }
+    ancestorNames[String(pk)] = code;
+
+    const allAttrs = [];
+    for (const typePK of typePKs) {
+      try {
+        const attrResult = await withSession(env, s => flexibleSearch(s,
+          `SELECT {qualifier}, {databasecolumn}, {enclosingtype}, {attributetype}, {unique} FROM {AttributeDescriptor} WHERE {enclosingtype} = '${typePK}' ORDER BY {qualifier} ASC`,
+          { maxCount: 300 }
+        ));
+        if (attrResult.resultList) {
+          for (const row of attrResult.resultList) allAttrs.push(row);
+        }
+      } catch (_) {}
+    }
+
+    let supertypeName = null;
+    if (supertypePK) {
+      try {
+        const stResult = await withSession(env, s => flexibleSearch(s,
+          `SELECT {code} FROM {ComposedType} WHERE {pk} = '${supertypePK}'`
+        ));
+        supertypeName = stResult.resultList?.[0]?.[0] || null;
+      } catch (_) {}
+    }
+
+    const scalar = allAttrs.filter(([, dbCol]) => dbCol);
+    const relations = allAttrs.filter(([, dbCol]) => !dbCol);
+
+    const collTypePKs = [...new Set(relations.map(([,,,attrTypePK]) => attrTypePK).filter(Boolean))];
+    const elementTypeMap = {};
+    const composedTypeNames = {};
+    const collCodeMap = {};
+    if (collTypePKs.length) {
+      try {
+        const pkConditions = collTypePKs.map(p => `{pk} = '${p}'`).join(' OR ');
+        const collResult = await withSession(env, s => flexibleSearch(s,
+          `SELECT {pk}, {elementtype}, {code} FROM {CollectionType} WHERE ${pkConditions}`
+        ));
+        if (collResult.resultList) {
+          for (const [cpk, eltPK, collCode] of collResult.resultList) {
+            elementTypeMap[String(cpk)] = eltPK;
+            collCodeMap[String(cpk)] = collCode;
+          }
+        }
+        const eltPKs = [...new Set(Object.values(elementTypeMap).filter(Boolean))];
+        if (eltPKs.length) {
+          const eltConditions = eltPKs.map(p => `{pk} = '${p}'`).join(' OR ');
+          const eltResult = await withSession(env, s => flexibleSearch(s,
+            `SELECT {pk}, {code} FROM {ComposedType} WHERE ${eltConditions}`
+          ));
+          if (eltResult.resultList) {
+            for (const [epk, ecode] of eltResult.resultList) composedTypeNames[String(epk)] = ecode;
+          }
+        }
+      } catch (_) {}
+    }
+
+    const relationInfo = {};
+    for (const [qualifier,, , attrTypePK] of relations) {
+      const attrTypePKStr = String(attrTypePK);
+      const eltPK = elementTypeMap[attrTypePKStr];
+      const collCode = collCodeMap?.[attrTypePKStr];
+      const targetType = eltPK ? (composedTypeNames[String(eltPK)] || null) : null;
+      const suffix = `${qualifier}Coll`;
+      const linkTable = collCode?.endsWith(suffix) ? collCode.slice(0, -suffix.length) : null;
+      relationInfo[qualifier] = { targetType, linkTable };
+    }
+
+    const scalarAttrTypePKs = [...new Set(scalar.map(([,,,attrTypePK]) => attrTypePK).filter(Boolean))];
+    const scalarRefTypes = {};
+    if (scalarAttrTypePKs.length) {
+      try {
+        const conds = scalarAttrTypePKs.map(p => `{pk} = '${p}'`).join(' OR ');
+        const r = await withSession(env, s => flexibleSearch(s,
+          `SELECT {pk}, {code} FROM {ComposedType} WHERE ${conds}`
+        ));
+        if (r.resultList) for (const [tpk, tcode] of r.resultList) scalarRefTypes[String(tpk)] = tcode;
+      } catch (_) {}
+    }
+
+    let out = `Type: ${code}`;
+    if (supertypeName) out += ` (extends ${supertypeName})`;
+    out += '\n\n';
+
+    out += `Scalar fields - use directly in SELECT / WHERE / ORDER BY:\n`;
+    for (const [q, , encPK, attrTypePK, isUnique] of scalar) {
+      const inherited = includeInherited && ancestorNames[String(encPK)] && ancestorNames[String(encPK)] !== code
+        ? ` (from ${ancestorNames[String(encPK)]})` : '';
+      const refType = attrTypePK ? scalarRefTypes[String(attrTypePK)] : null;
+      let line = `  ${q}`;
+      if (isTruthy(isUnique)) line += ' [unique]';
+      if (refType) line += ` → ${refType}`;
+      if (inherited) line += inherited;
+      out += line + '\n';
+    }
+
+    out += '\nRelation/collection fields - require JOIN to query:\n';
+    for (const [q,,encPK] of relations) {
+      const { targetType, linkTable } = relationInfo[q] || {};
+      const inherited = includeInherited && ancestorNames[String(encPK)] && ancestorNames[String(encPK)] !== code ? ` (from ${ancestorNames[String(encPK)]})` : '';
+      if (targetType && linkTable) {
+        const alias = code.charAt(0).toLowerCase();
+        const tAlias = targetType.charAt(0).toLowerCase() + '2';
+        out += `  ${q}${inherited}: Collection<${targetType}>\n`;
+        out += `    JOIN: {${code} AS ${alias} JOIN ${linkTable} AS lnk ON {lnk:source}={${alias}:pk} JOIN ${targetType} AS ${tAlias} ON {lnk:target}={${tAlias}:pk}}\n`;
+      } else if (targetType) {
+        out += `  ${q}${inherited}: Collection<${targetType}>\n`;
+      } else {
+        out += `  ${q}${inherited}\n`;
+      }
+    }
+
+    mcpLog({ tool: TOOL, envName: env.name, preview: `Type info: ${code} (${allAttrs.length} attrs)`, detail: out, runId });
+    return text(out);
+  },
+};

package/tools/groovy_execute.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { groovyExecute } from '../hac.js';
+import { optionalLooseBool } from './zodLoose.js';
+import { withSession, getEnvironment, mcpLogStart, mcpLog, text, error } from './context.js';
+
+const TOOL = 'groovy_execute';
+
+export const tool = {
+  name: TOOL,
+  category: 'write',
+  description: 'Execute a Groovy script on a HAC environment. Call list_environments first to check groovy execution is allowed. IMPORTANT: Before calling this tool, you MUST show the user the script and a clear explanation of what it does and explicitly ask for their confirmation. Only proceed after the user approves and set confirmed_by_user to true. Note: even with commit disabled, scripts can send emails, trigger SMS, or call external APIs.',
+  inputSchema: {
+    environmentId: z.string().describe('Environment ID from list_environments'),
+    script: z.string().describe('Groovy script content'),
+    commit: optionalLooseBool().describe('Whether to commit the transaction (default: false)'),
+    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, commit, confirmed_by_user }) => {
+    if (!confirmed_by_user) {
+      return error('User confirmation required. Show the user the script and what it does, 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 (commit && 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}".`);
+    }
+
+    const scriptPreview = script.split('\n')[0].slice(0, 60);
+    const runId = mcpLogStart({ tool: TOOL, envName: env.name, preview: `${scriptPreview}…` });
+
+    let result;
+    try {
+      result = await withSession(env, s => groovyExecute(s, script, { commit }));
+    } 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;
+    let out = `**${env.name}** - ${isErr ? '❌ Error' : '✅ Success'}\n`;
+    if (result.executionResult != null) out += `\n**Result:**\n\`\`\`\n${result.executionResult}\n\`\`\``;
+    if (result.outputText) out += `\n**Output:**\n\`\`\`\n${result.outputText}\n\`\`\``;
+    if (result.stacktraceText) out += `\n**Stacktrace:**\n\`\`\`\n${result.stacktraceText}\n\`\`\``;
+
+    mcpLog({ tool: TOOL, envName: env.name,
+      preview: `${isErr ? '❌' : '✅'} ${scriptPreview}…`,
+      detail: `Script:\n${script}\n\nResult: ${result.executionResult}\n\n${result.stacktraceText || ''}`,
+      isError: isErr, runId,
+    });
+    return text(out);
+  },
+};