mcp-server-sfmc 1.9.2 → 2.1.0

package/dist/index.js

@@ -16,12 +16,26 @@ import { z } from 'zod';
 import { sfmcLanguageService, validateAmpscript, validateSsjs, validateGtlBlocks, isMcnSupported, getMcnApiVersion, getMcnNotes, extractAmpscriptFunctionCalls, } from 'sfmc-language-lsp';
 import { getChunks, getMceHelpStats, searchMceHelp, } from './mce-help-search.js';
 import { getMcnChunks, getMcnHelpStats, searchMcnHelp } from './mcn-help-search.js';
-import { CLOUDPAGES_ONLY_FUNCTIONS, NON_MIGRATABLE_SSJS_PATTERNS, ssjsToAmpscript, ampscriptToSsjs, rewriteAmpForMcn, isSsjsBlockConvertible, } from './conversion-rules.js';
+import { CLOUDPAGES_ONLY_FUNCTIONS, NON_MIGRATABLE_SSJS_PATTERNS, ssjsToAmpscript, ampscriptToSsjs, rewriteAmpForMcn, isSsjsBlockConvertible, ampscriptToHandlebars, handlebarsToAmpscript, ssjsToHandlebars, AMP_MCN_HANDLEBARS_GAP, HBS_GAP_NOTE, } from './conversion-rules.js';
 import { ECMASCRIPT_BUILTINS, KNOWN_UNSUPPORTED, polyfillByPrototypeName, polyfillByStaticName, } from 'ssjs-data';
 function projectPackageRoot() {
     return path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 }
-const pkg = JSON.parse(fs.readFileSync(path.join(projectPackageRoot(), 'package.json'), 'utf8'));
+const packageJsonPath = path.join(projectPackageRoot(), 'package.json');
+const package_ = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+/**
+ * Normalize a completion item's `label` (which may be a string or a
+ * `{ label: string }` object) to its plain-string form.
+ * @param item - A completion item with a string or object label.
+ * @param item.label
+ * @returns {string} The label text.
+ */
+function labelText(item) {
+    if (typeof item.label === 'string') {
+        return item.label;
+    }
+    return item.label.label;
+}
 // ---------------------------------------------------------------------------
 // Server instance
 // ---------------------------------------------------------------------------
@@ -84,7 +98,7 @@ const SERVER_INSTRUCTIONS = 'This server provides authoritative SFMC language in
     'and route the query to the right doc index (or both for MCN). Only fall back to the individual ' +
     'search tools when you need to scope by `product_focus` (MCE only) or when you are **certain** ' +
     'which doc index to target.';
-const server = new McpServer({ name: 'mcp-server-sfmc', version: pkg.version }, { instructions: SERVER_INSTRUCTIONS });
+const server = new McpServer({ name: 'mcp-server-sfmc', version: package_.version }, { instructions: SERVER_INSTRUCTIONS });
 function detectLanguage(code, hint) {
     if (hint === 'ssjs')
         return 'ssjs';
@@ -106,6 +120,17 @@ function detectLanguage(code, hint) {
         return 'ssjs';
     return 'ampscript';
 }
+/**
+ * Extracts the human-readable text from a diagnostic message, which may be a
+ * plain string or a `{ value }` wrapper depending on the language-service type.
+ * @param message
+ */
+function diagnosticMessage(message) {
+    if (typeof message === 'string') {
+        return message;
+    }
+    return message.value;
+}
 function formatDiagnostics(diagnostics) {
     if (diagnostics.length === 0)
         return 'No issues found.';
@@ -113,11 +138,33 @@ function formatDiagnostics(diagnostics) {
         .map((d) => {
         const sev = d.severity === 1 ? 'ERROR' : d.severity === 2 ? 'WARNING' : 'INFO';
         const loc = `line ${d.range.start.line + 1}, col ${d.range.start.character + 1}`;
-        const message = typeof d.message === 'string' ? d.message : d.message.value;
+        const message = diagnosticMessage(d.message);
         return `[${sev}] ${loc}: ${message}`;
     })
         .join('\n');
 }
+function formatHandlebarsHelper(helper) {
+    const parameters = helper.params
+        .map((p) => {
+        const request = p.optional ? '(optional)' : '(required)';
+        const variadic = p.variadic ? ' (variadic)' : '';
+        return `  - ${p.name}: ${p.type}${variadic} ${request}${p.description ? ' — ' + p.description : ''}`;
+    })
+        .join('\n');
+    const subexpr = helper.subexpressionOnly
+        ? '\n\n> Subexpression-only — may only be used inside `( … )`.'
+        : '';
+    return (`## {{${helper.name}}}\n\n` +
+        `**Category:** ${helper.category}\n\n` +
+        `**Origin:** ${helper.origin}\n\n` +
+        `**Type:** ${helper.helperType}\n\n` +
+        `**Returns:** ${helper.returnType}\n\n` +
+        `**Description:** ${helper.description}\n\n` +
+        `**Parameters:**\n${parameters || '  (none)'}` +
+        subexpr +
+        `\n\n✅ **Marketing Cloud Next:** Supported since API v${helper.mcnSince}.0` +
+        (helper.docUrl ? `\n\n[Documentation](${helper.docUrl})` : ''));
+}
 // ---------------------------------------------------------------------------
 // Tool: validate_ampscript
 // ---------------------------------------------------------------------------
@@ -215,28 +262,28 @@ server.tool('lookup_ampscript_function', 'Look up the signature, parameters, des
     'Case-insensitive. Returns null if the function is not found.', {
     name: z.string().describe('The AMPscript function name, e.g. "Lookup", "DateAdd", "IIf".'),
 }, ({ name }) => {
-    const fn = sfmcLanguageService.lookupAmpscriptFunction(name);
-    if (!fn) {
+    const function_ = sfmcLanguageService.lookupAmpscriptFunction(name);
+    if (!function_) {
         return { content: [{ type: 'text', text: `AMPscript function "${name}" not found.` }] };
     }
-    const params = fn.params
+    const parameters = function_.params
         .map((p) => {
-        const req = p.optional ? '(optional)' : '(required)';
-        return `  - ${p.name}: ${p.type ?? 'any'} ${req}${p.description ? ' — ' + p.description : ''}`;
+        const request = p.optional ? '(optional)' : '(required)';
+        return `  - ${p.name}: ${p.type ?? 'any'} ${request}${p.description ? ' — ' + p.description : ''}`;
     })
         .join('\n');
-    const examples = fn.example ? '\n\nExample:\n' + fn.example : '';
+    const examples = function_.example ? '\n\nExample:\n' + function_.example : '';
     // MCN compatibility badge
-    const fnMcnSince = fn.mcnSince ?? null;
-    const fnMcnNotes = fn.mcnNotes ?? null;
-    const mcnLine = fnMcnSince === null
+    const functionMcnSince = function_.mcnSince ?? null;
+    const functionMcnNotes = function_.mcnNotes ?? null;
+    const mcnLine = functionMcnSince === null
         ? '\n\n❌ **Marketing Cloud Next:** Not supported'
-        : `\n\n✅ **Marketing Cloud Next:** Supported since API v${fnMcnSince}.0` +
-            (fnMcnNotes ? `\n> **MCN Note:** ${fnMcnNotes}` : '');
-    const text = `## ${fn.name}\n\n` +
-        `**Category:** ${fn.category ?? 'Unknown'}\n\n` +
-        `**Description:** ${fn.description ?? ''}\n\n` +
-        `**Parameters:**\n${params || '  (none)'}` +
+        : `\n\n✅ **Marketing Cloud Next:** Supported since API v${functionMcnSince}.0` +
+            (functionMcnNotes ? `\n> **MCN Note:** ${functionMcnNotes}` : '');
+    const text = `## ${function_.name}\n\n` +
+        `**Category:** ${function_.category ?? 'Unknown'}\n\n` +
+        `**Description:** ${function_.description ?? ''}\n\n` +
+        `**Parameters:**\n${parameters || '  (none)'}` +
         examples +
         mcnLine;
     return { content: [{ type: 'text', text }] };
@@ -289,6 +336,90 @@ server.tool('list_ampscript_functions', 'List all AMPscript functions, optionall
     };
 });
 // ---------------------------------------------------------------------------
+// Tool: validate_handlebars
+// ---------------------------------------------------------------------------
+server.tool('validate_handlebars', 'Validate Marketing Cloud Next (MCN) Handlebars template code. ' +
+    'Checks helper names, arity, block balance, and flags unsupported constructs ' +
+    '(partials, decorators, and built-in helpers absent from the locked-down MCN engine). ' +
+    'MCN Handlebars lives inside the combined sfmc language and is always validated for the ' +
+    "'next' target.", {
+    code: z
+        .string()
+        .describe('The MCN Handlebars template code to validate. May include HTML context.'),
+    maxProblems: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe('Maximum number of problems to return (default 100).'),
+}, ({ code, maxProblems }) => {
+    const settings = {
+        maxNumberOfProblems: maxProblems ?? 100,
+        targetPlatform: 'next',
+    };
+    const diagnostics = validateAmpscript(code, settings).filter((d) => d.source === 'handlebars');
+    return {
+        content: [{ type: 'text', text: formatDiagnostics(diagnostics) }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool: lookup_handlebars_helper
+// ---------------------------------------------------------------------------
+server.tool('lookup_handlebars_helper', 'Look up the signature, parameters, description, and origin for a Marketing Cloud Next ' +
+    'Handlebars helper by name. Case-insensitive. Returns null if the helper is not found.', {
+    name: z
+        .string()
+        .describe('The Handlebars helper name, e.g. "uppercase", "if", "formatDate".'),
+}, ({ name }) => {
+    const helper = sfmcLanguageService.lookupHandlebarsHelper(name);
+    if (!helper) {
+        return {
+            content: [{ type: 'text', text: `Handlebars helper "${name}" not found.` }],
+        };
+    }
+    return { content: [{ type: 'text', text: formatHandlebarsHelper(helper) }] };
+});
+// ---------------------------------------------------------------------------
+// Tool: list_handlebars_helpers
+// ---------------------------------------------------------------------------
+server.tool('list_handlebars_helpers', 'List all Marketing Cloud Next Handlebars helpers, optionally filtered by category ' +
+    'and/or origin (handlebars-builtin, mcn-helper, mcn-platform).', {
+    category: z
+        .string()
+        .optional()
+        .describe('Filter by helper category (case-insensitive substring match), e.g. "string", "date", "comparison".'),
+    origin: z
+        .enum(['handlebars-builtin', 'mcn-helper', 'mcn-platform'])
+        .optional()
+        .describe('Filter by helper origin.'),
+}, ({ category, origin }) => {
+    let helpers = sfmcLanguageService.listHandlebarsHelpers();
+    if (origin) {
+        helpers = helpers.filter((h) => h.origin === origin);
+    }
+    if (category) {
+        const catLower = category.toLowerCase();
+        helpers = helpers.filter((h) => h.category.toLowerCase().includes(catLower));
+    }
+    if (helpers.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No Handlebars helpers match the filter.' }],
+        };
+    }
+    const rows = helpers
+        .map((h) => `- **${h.name}** *(${h.category}, ${h.origin}, ${h.helperType})*: ${h.description}`)
+        .join('\n');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `## MCN Handlebars Helpers\n\n${rows}`,
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
 // ECMAScript-builtin support lookup, sourced exclusively from ssjs-data.
 // Used as a fall-through inside lookup_ssjs_function so a single tool answers
 // "can I use X in SSJS?" for both SFMC APIs and plain-JavaScript built-ins.
@@ -422,35 +553,37 @@ server.tool('lookup_ssjs_function', 'Authoritative lookup (sourced ONLY from the
 }, ({ name, owner }) => {
     // Strip namespace prefix for lookup
     const bare = name.replace(/^(Platform\.(Function|Variable|Response|Request|ClientBrowser|Recipient|DateTime)\.|WSProxy\.|HTTP\.|Script\.Util\.|Function\.|Variable\.|Response\.|Request\.)/i, '');
-    const fn = sfmcLanguageService.lookupSsjsFunction(bare);
-    if (!fn) {
+    const function_ = sfmcLanguageService.lookupSsjsFunction(bare);
+    if (!function_) {
         // Fall through to the ECMAScript built-in / polyfill / unsupported catalogs.
         const builtinResult = lookupSsjsBuiltin(name, owner);
         return { content: [{ type: 'text', text: builtinResult.text }] };
     }
-    const params = (fn.params ?? [])
+    const parameters = (function_.params ?? [])
         .map((p) => {
         const isOptional = p.optional || p.required === false;
-        const req = isOptional ? '(optional)' : '(required)';
-        return `  - ${p.name}: ${p.type ?? 'any'} ${req}${p.description ? ' — ' + p.description : ''}`;
+        const request = isOptional ? '(optional)' : '(required)';
+        return `  - ${p.name}: ${p.type ?? 'any'} ${request}${p.description ? ' — ' + p.description : ''}`;
     })
         .join('\n');
     const badges = [];
-    if (fn.deprecated) {
+    if (function_.deprecated) {
         badges.push('⚠️ **Deprecated** — avoid in new code.');
     }
-    if (fn.requiresCoreLoad) {
+    if (function_.requiresCoreLoad) {
         badges.push('⚠️ **Requires** `Platform.Load("core", "1.1.5")` before calling this method.');
     }
-    const header = fn.isStatic ? `## ${fn.name} *(static)*` : `## ${fn.name}`;
+    const header = function_.isStatic
+        ? `## ${function_.name} *(static)*`
+        : `## ${function_.name}`;
     const badgeBlock = badges.length > 0 ? badges.join('\n') + '\n\n' : '';
-    const aliasLine = fn.aliasOf ? `**Alias of:** \`${fn.aliasOf}\`\n\n` : '';
+    const aliasLine = function_.aliasOf ? `**Alias of:** \`${function_.aliasOf}\`\n\n` : '';
     const text = `${header}\n\n` +
         badgeBlock +
         aliasLine +
-        `**Description:** ${fn.description ?? ''}\n\n` +
-        `**Parameters:**\n${params || '  (none)'}\n\n` +
-        `**Returns:** ${fn.returnType ?? 'void'}`;
+        `**Description:** ${function_.description ?? ''}\n\n` +
+        `**Parameters:**\n${parameters || '  (none)'}\n\n` +
+        `**Returns:** ${function_.returnType ?? 'void'}`;
     return { content: [{ type: 'text', text }] };
 });
 // ---------------------------------------------------------------------------
@@ -474,13 +607,13 @@ server.tool('review_change', 'Review a code diff for SFMC (AMPscript, SSJS, or H
 }, ({ diff, language = 'auto', maxProblems = 50 }) => {
     // Extract added lines from the unified diff
     const addedLines = [];
-    let lineNum = 0;
+    let lineNumber = 0;
     const lineMap = []; // maps index in addedLines to original diff line number
     for (const line of diff.split('\n')) {
-        lineNum++;
+        lineNumber++;
         if (line.startsWith('+') && !line.startsWith('+++')) {
             addedLines.push(line.slice(1));
-            lineMap.push(lineNum);
+            lineMap.push(lineNumber);
         }
     }
     if (addedLines.length === 0) {
@@ -493,8 +626,8 @@ server.tool('review_change', 'Review a code diff for SFMC (AMPscript, SSJS, or H
             ? detectLanguage(addedCode, 'html')
             : language;
     const settings = { maxNumberOfProblems: maxProblems };
-    const doc = { text: addedCode, languageId: detectedLang, uri: 'diff' };
-    const diagnostics = sfmcLanguageService.validate(doc, settings);
+    const document = { text: addedCode, languageId: detectedLang, uri: 'diff' };
+    const diagnostics = sfmcLanguageService.validate(document, settings);
     if (diagnostics.length === 0) {
         return {
             content: [
@@ -509,7 +642,7 @@ server.tool('review_change', 'Review a code diff for SFMC (AMPscript, SSJS, or H
     for (const d of diagnostics) {
         const sev = d.severity === 1 ? '🔴 ERROR' : d.severity === 2 ? '🟡 WARNING' : '🔵 INFO';
         const origLine = lineMap[d.range.start.line] ?? d.range.start.line + 1;
-        const message = typeof d.message === 'string' ? d.message : d.message.value;
+        const message = diagnosticMessage(d.message);
         output.push(`${sev} (diff line ${origLine}): ${message}`);
     }
     return { content: [{ type: 'text', text: output.join('\n') }] };
@@ -538,15 +671,15 @@ server.tool('suggest_fix', 'Generate a corrected version of SFMC code based on v
         ? detectLanguage(code)
         : detectLanguage(code, language);
     const settings = { maxNumberOfProblems: 50, targetPlatform: target };
-    const doc = { text: code, languageId: detectedLang, uri: 'fix-target' };
-    const diagnostics = sfmcLanguageService.validate(doc, settings);
+    const document = { text: code, languageId: detectedLang, uri: 'fix-target' };
+    const diagnostics = sfmcLanguageService.validate(document, settings);
     const lines = code.split('\n');
     const suggestions = [];
     for (const d of diagnostics) {
         const lineText = lines[d.range.start.line] ?? '';
         // Diagnostic.message widened to `string | MarkupContent` in newer LSP types; the
         // SFMC language service only emits plain strings, so unwrap MarkupContent to its value.
-        const message = typeof d.message === 'string' ? d.message : d.message.value;
+        const message = diagnosticMessage(d.message);
         suggestions.push(`Line ${d.range.start.line + 1}: ${message}\n` +
             `  Code: ${lineText.trim()}\n` +
             `  Fix: ${getFixSuggestion(message, lineText, detectedLang)}`);
@@ -568,6 +701,24 @@ server.tool('suggest_fix', 'Generate a corrected version of SFMC code based on v
  */
 function getFixSuggestion(message, line, lang) {
     const m = message.toLowerCase();
+    // MCN Handlebars diagnostics (surfaced when target === 'next' on {{…}} regions).
+    if (m.includes('partials ({{>'))
+        return 'Inline the partial content directly — the locked-down MCN engine cannot register partials.';
+    if (m.includes('partial blocks'))
+        return 'Inline the block content directly — the MCN engine cannot register partial blocks.';
+    if (m.includes('decorators ({{*') || m.includes('decorator blocks'))
+        return 'Remove the decorator — the MCN engine cannot register decorators.';
+    if (m.includes('{{log}}'))
+        return 'Remove the {{log}} debugging helper — it is not available in MCN Handlebars.';
+    if (m.includes('unknown handlebars helper')) {
+        const helperMatch = message.match(/'([^']+)'/);
+        const hint = helperMatch
+            ? ` Check spelling or use a catalog helper instead of "${helperMatch[1]}".`
+            : '';
+        return `Use a helper from the MCN Handlebars catalog (list_handlebars_helpers); custom helpers cannot be registered.${hint}`;
+    }
+    if (m.includes('handlebars for marketing cloud next') || m.includes('mcn engine'))
+        return 'Replace with a supported MCN Handlebars construct — see list_handlebars_helpers.';
     if (m.includes("'let'") || m.includes("'const'"))
         return 'Replace `let`/`const` with `var`.';
     if (m.includes('arrow function'))
@@ -583,9 +734,9 @@ function getFixSuggestion(message, line, lang) {
     if (m.includes('html comment'))
         return 'Remove the `<!-- -->` wrapper; use `/* comment */` inside AMPscript.';
     if (m.includes('unknown function')) {
-        const fnMatch = message.match(/"([^"]+)"/);
-        if (fnMatch)
-            return `Check spelling — did you mean a known AMPscript function? ("${fnMatch[1]}")`;
+        const functionMatch = message.match(/"([^"]+)"/);
+        if (functionMatch)
+            return `Check spelling — did you mean a known AMPscript function? ("${functionMatch[1]}")`;
     }
     if (m.includes('expects'))
         return 'Check the number and types of arguments against the function signature.';
@@ -606,13 +757,11 @@ server.tool('get_ampscript_completions', 'Return a list of AMPscript function na
         .optional()
         .describe("Target platform. Use 'next' to return only completions supported in Marketing Cloud Next."),
 }, ({ code, line, character, target }) => {
-    const doc = { text: code, languageId: 'ampscript', uri: 'completions' };
-    let items = sfmcLanguageService.getCompletions(doc, { line, character });
+    const document = { text: code, languageId: 'ampscript', uri: 'completions' };
+    let items = sfmcLanguageService.getCompletions(document, { line, character });
     if (target === 'next') {
         items = items.filter((item) => {
-            const label = typeof item.label === 'string'
-                ? item.label
-                : item.label.label;
+            const label = labelText(item);
             // Keep keywords and variables (non-function entries); filter out MCN-unsupported functions
             return !label.includes('(') || isMcnSupported(label.replace(/\(.*/, '').trim());
         });
@@ -620,9 +769,7 @@ server.tool('get_ampscript_completions', 'Return a list of AMPscript function na
     const formatted = items
         .slice(0, 50)
         .map((item) => {
-        const label = typeof item.label === 'string'
-            ? item.label
-            : item.label.label;
+        const label = labelText(item);
         return `- ${label}${item.detail ? ` — ${item.detail}` : ''}`;
     })
         .join('\n');
@@ -665,19 +812,12 @@ server.tool('get_ssjs_completions', 'Return a list of SSJS Platform functions, W
     }
     const items = sfmcLanguageService.getSsjsCompletionCatalog();
     const filtered = filter
-        ? items.filter((item) => {
-            const label = typeof item.label === 'string'
-                ? item.label
-                : item.label.label;
-            return label.toLowerCase().startsWith(filter.toLowerCase());
-        })
+        ? items.filter((item) => labelText(item).toLowerCase().startsWith(filter.toLowerCase()))
         : items;
     const formatted = filtered
         .slice(0, 80)
         .map((item) => {
-        const label = typeof item.label === 'string'
-            ? item.label
-            : item.label.label;
+        const label = labelText(item);
         return `- ${label}${item.detail ? ` — ${item.detail}` : ''}`;
     })
         .join('\n');
@@ -693,12 +833,74 @@ server.tool('get_ssjs_completions', 'Return a list of SSJS Platform functions, W
     };
 });
 // ---------------------------------------------------------------------------
+// Tool: get_handlebars_completions
+// ---------------------------------------------------------------------------
+server.tool('get_handlebars_completions', 'Return Marketing Cloud Next (MCN) Handlebars helper completions with snippet insert text. ' +
+    'MCN Handlebars is only available on the next platform, so this catalog is always the ' +
+    '\'next\' set. Optionally filter by a name prefix (e.g. "form", "date").', {
+    filter: z
+        .string()
+        .optional()
+        .describe('Optional helper-name prefix filter (case-insensitive), e.g. "form", "to".'),
+}, ({ filter }) => {
+    const items = sfmcLanguageService.getHandlebarsCompletionCatalog();
+    const filtered = filter
+        ? items.filter((item) => labelText(item).toLowerCase().startsWith(filter.toLowerCase()))
+        : items;
+    const formatted = filtered
+        .slice(0, 80)
+        .map((item) => {
+        const label = labelText(item);
+        return `- ${label}${item.detail ? ` — ${item.detail}` : ''}`;
+    })
+        .join('\n');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: filtered.length === 0
+                    ? `No MCN Handlebars helpers matching "${filter}".`
+                    : `${filtered.length} MCN Handlebars helper completions${filter ? ` matching "${filter}"` : ''} (showing up to 80):\n\n${formatted}`,
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
 // Tool: format_sfmc_code (basic, no prettier integration needed)
 // ---------------------------------------------------------------------------
-server.tool('format_sfmc_code', 'Apply basic formatting conventions to AMPscript or SSJS code. ' +
-    'Normalises keyword casing, whitespace around operators, and indentation hints.', {
+/**
+ * Conservatively normalize whitespace inside Marketing Cloud Next (MCN)
+ * Handlebars `{{…}}` mustaches: collapse runs of internal whitespace to a
+ * single space and trim the edges (e.g. `{{ foo   bar }}` → `{{foo bar}}`),
+ * matching what Prettier's Glimmer parser does for mustache interiors.
+ *
+ * Hard guardrails (never altered):
+ * - `{!$…}` merge-field bindings — they are not Handlebars syntax.
+ * - `{{!-- … --}}` / `{{! … }}` comments — preserved byte-for-byte.
+ *
+ * This is the deferred-Prettier stub for item 8 of the MCN Handlebars handoff:
+ * full routing through prettier-plugin-sfmc's Glimmer path lands once that
+ * plugin ships Handlebars support (see HANDOFF-prettier-handlebars.md).
+ * @param {string} code - The Handlebars-in-HTML code to normalize.
+ * @returns {string} The code with mustache interiors normalized.
+ */
+function normalizeHandlebarsWhitespace(code) {
+    return code.replaceAll(/\{\{([\s\S]*?)\}\}/g, (full, inner) => {
+        // Preserve comments verbatim.
+        if (inner.startsWith('!')) {
+            return full;
+        }
+        const normalized = inner.replaceAll(/\s+/g, ' ').trim();
+        return `{{${normalized}}}`;
+    });
+}
+server.tool('format_sfmc_code', 'Apply basic formatting conventions to AMPscript, SSJS, or Marketing Cloud Next (MCN) ' +
+    'Handlebars code. Normalises keyword casing and whitespace. For Handlebars, collapses ' +
+    'whitespace inside {{…}} mustaches while leaving {!$…} bindings and {{!-- … --}} comments ' +
+    'untouched. (Handlebars formatting is a conservative whitespace normalizer; full Prettier ' +
+    'Glimmer routing is deferred until prettier-plugin-sfmc ships Handlebars support.)', {
     code: z.string().describe('The SFMC code to format.'),
-    language: z.enum(['ampscript', 'ssjs']).describe('The language of the code.'),
+    language: z.enum(['ampscript', 'ssjs', 'handlebars']).describe('The language of the code.'),
 }, ({ code, language }) => {
     let formatted = code;
     if (language === 'ampscript') {
@@ -709,6 +911,9 @@ server.tool('format_sfmc_code', 'Apply basic formatting conventions to AMPscript
             .replaceAll(/\bOR\b/gi, 'OR')
             .replaceAll(/\bNOT\b/gi, 'NOT');
     }
+    else if (language === 'handlebars') {
+        formatted = normalizeHandlebarsWhitespace(formatted);
+    }
     else {
         // SSJS: normalise Platform.Load to use double quotes
         formatted = formatted.replaceAll(/Platform\.Load\s*\(\s*'([^']*)'\s*,\s*'([^']*)'\s*\)/g, 'Platform.Load("$1", "$2")');
@@ -759,9 +964,9 @@ server.tool('search_mce_help', MCE_HELP_TOOL_DESC, {
             : `No matches for this query with product_focus="${focus}". Try broader keywords or product_focus="any".`;
         return { content: [{ type: 'text', text: hint }] };
     }
-    const lines = hits.map((h, i) => {
+    const lines = hits.map((h, index) => {
         const excerpt = h.chunk.body.replaceAll(/\s+/g, ' ').slice(0, 520);
-        return (`### ${i + 1}. ${h.chunk.relativePath} — ${h.chunk.heading}\n` +
+        return (`### ${index + 1}. ${h.chunk.relativePath} — ${h.chunk.heading}\n` +
             `**Product:** ${h.chunk.productLabel}\n` +
             `**Score:** ${h.score}\n\n` +
             `${excerpt}${h.chunk.body.length > 520 ? '…' : ''}\n`);
@@ -775,11 +980,11 @@ server.tool('search_mce_help', MCE_HELP_TOOL_DESC, {
 // ---------------------------------------------------------------------------
 server.resource('ampscript-function-catalog', 'sfmc://ampscript/functions', async () => {
     const functions = sfmcLanguageService.getAllAmpscriptFunctions();
-    const lines = functions.map((fn) => {
-        const paramList = fn.params
+    const lines = functions.map((function_) => {
+        const parameterList = function_.params
             .map((p) => p.optional ? `[${p.name}: ${p.type ?? 'any'}]` : `${p.name}: ${p.type ?? 'any'}`)
             .join(', ');
-        return `${fn.name}(${paramList}) — ${fn.description ?? ''}`;
+        return `${function_.name}(${parameterList}) — ${function_.description ?? ''}`;
     });
     return {
         contents: [
@@ -797,13 +1002,13 @@ server.resource('ampscript-function-catalog', 'sfmc://ampscript/functions', asyn
 // ---------------------------------------------------------------------------
 server.resource('ssjs-function-catalog', 'sfmc://ssjs/functions', async () => {
     const functions = sfmcLanguageService.getAllSsjsFunctions();
-    const lines = functions.map((fn) => {
-        const paramList = (fn.params ?? [])
+    const lines = functions.map((function_) => {
+        const parameterList = (function_.params ?? [])
             .map((p) => p.optional || p.required === false
             ? `[${p.name}: ${p.type ?? 'any'}]`
             : `${p.name}: ${p.type ?? 'any'}`)
             .join(', ');
-        return `${fn.name}(${paramList}) — ${fn.description ?? ''}`;
+        return `${function_.name}(${parameterList}) — ${function_.description ?? ''}`;
     });
     return {
         contents: [
@@ -817,6 +1022,48 @@ server.resource('ssjs-function-catalog', 'sfmc://ssjs/functions', async () => {
     };
 });
 // ---------------------------------------------------------------------------
+// Resource: handlebars-helper-catalog
+// ---------------------------------------------------------------------------
+server.resource('handlebars-helper-catalog', 'sfmc://handlebars/helpers', async () => {
+    const helpers = sfmcLanguageService.listHandlebarsHelpers();
+    const lines = helpers.map((h) => {
+        const parameterList = h.params
+            .map((p) => {
+            const inner = `${p.name}: ${p.type}`;
+            return p.optional ? `[${inner}]` : inner;
+        })
+            .join(', ');
+        return `{{${h.name} ${parameterList}}} — (${h.category}, ${h.origin}, v${h.mcnSince}.0+) ${h.description}`;
+    });
+    return {
+        contents: [
+            {
+                uri: 'sfmc://handlebars/helpers',
+                mimeType: 'text/plain',
+                text: `# MCN Handlebars Helper Catalog (${helpers.length} helpers)\n\n` +
+                    lines.join('\n'),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Resource: handlebars-binding-catalog
+// ---------------------------------------------------------------------------
+server.resource('handlebars-binding-catalog', 'sfmc://handlebars/bindings', async () => {
+    const bindings = sfmcLanguageService.listHandlebarsBindings();
+    const lines = bindings.map((b) => `${b.token} — (${b.namespace}, v${b.mcnSince}.0+) ${b.description}`);
+    return {
+        contents: [
+            {
+                uri: 'sfmc://handlebars/bindings',
+                mimeType: 'text/plain',
+                text: `# MCN Handlebars Built-in Binding Catalog (${bindings.length} bindings)\n\n` +
+                    lines.join('\n'),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
 // Resource: ampscript-keywords
 // ---------------------------------------------------------------------------
 server.resource('ampscript-keywords', 'sfmc://ampscript/keywords', async () => {
@@ -902,7 +1149,7 @@ server.resource('mce-product-context', 'sfmc://mce/product-context', async () =>
 // ---------------------------------------------------------------------------
 server.resource('mce-help-index', 'sfmc://mce/help-index', async () => {
     const chunks = getChunks();
-    const files = [...new Set(chunks.map((c) => c.relativePath))].sort();
+    const files = [...new Set(chunks.map((c) => c.relativePath))].sort((a, b) => a.localeCompare(b));
     const stats = getMceHelpStats();
     const scopeRows = Object.entries(stats.breakdown)
         .sort(([, a], [, b]) => b - a)
@@ -921,7 +1168,7 @@ server.resource('mce-help-index', 'sfmc://mce/help-index', async () => {
 // ---------------------------------------------------------------------------
 server.resource('mcn-help-index', 'sfmc://mcn/help-index', async () => {
     const chunks = getMcnChunks();
-    const files = [...new Set(chunks.map((c) => c.relativePath))].sort();
+    const files = [...new Set(chunks.map((c) => c.relativePath))].sort((a, b) => a.localeCompare(b));
     const stats = getMcnHelpStats();
     const text = `# Bundled Marketing Cloud Next developer API docs (${stats.chunkCount} sections from ${stats.fileCount} files)\n\n` +
         `## Files\n\n` +
@@ -1032,16 +1279,16 @@ server.tool('search_help', 'Unified help search that automatically detects the t
     const sections = [];
     if (platform === 'next') {
         // MCN: search both the developer API reference and the MCN operational/admin help
-        const devHits = searchMcnHelp(query, Math.ceil(limit / 2));
+        const developmentHits = searchMcnHelp(query, Math.ceil(limit / 2));
         const opsHits = searchMceHelp(query, Math.floor(limit / 2), 'next');
-        if (devHits.length > 0) {
-            const parts = devHits.map(({ chunk }) => `### ${chunk.heading}\n*Source: ${chunk.relativePath}*\n\n${chunk.body}`);
+        if (developmentHits.length > 0) {
+            const parts = developmentHits.map(({ chunk }) => `### ${chunk.heading}\n*Source: ${chunk.relativePath}*\n\n${chunk.body}`);
             sections.push(`## MCN Developer API Docs\n\n${parts.join('\n\n---\n\n')}`);
         }
         if (opsHits.length > 0) {
-            const parts = opsHits.map((h, i) => {
+            const parts = opsHits.map((h, index) => {
                 const excerpt = h.chunk.body.replaceAll(/\s+/g, ' ').slice(0, 520);
-                return (`### ${i + 1}. ${h.chunk.relativePath} — ${h.chunk.heading}\n` +
+                return (`### ${index + 1}. ${h.chunk.relativePath} — ${h.chunk.heading}\n` +
                     `**Score:** ${h.score}\n\n` +
                     `${excerpt}${h.chunk.body.length > 520 ? '…' : ''}`);
             });
@@ -1071,9 +1318,9 @@ server.tool('search_help', 'Unified help search that automatically detects the t
                 : `No results found for "${query}". Try broader keywords.`;
             return { content: [{ type: 'text', text: hint }] };
         }
-        const parts = hits.map((h, i) => {
+        const parts = hits.map((h, index) => {
             const excerpt = h.chunk.body.replaceAll(/\s+/g, ' ').slice(0, 520);
-            return (`### ${i + 1}. ${h.chunk.relativePath} — ${h.chunk.heading}\n` +
+            return (`### ${index + 1}. ${h.chunk.relativePath} — ${h.chunk.heading}\n` +
                 `**Product:** ${h.chunk.productLabel}\n` +
                 `**Score:** ${h.score}\n\n` +
                 `${excerpt}${h.chunk.body.length > 520 ? '…' : ''}`);
@@ -1244,6 +1491,23 @@ server.prompt('reviewSfmcCode', 'Review SFMC code for correctness, best practice
     const platformNote = target === 'next'
         ? '\n- **Marketing Cloud Next compatibility**: Flag any AMPscript functions not supported in MCN (API v67.0+), and any SSJS blocks (SSJS is not supported in MCN).'
         : '';
+    const fenceLang = detectedLang === 'ssjs' ? 'javascript' : detectedLang;
+    const checklistItems = detectedLang === 'ampscript'
+        ? [
+            '- Delimiter balance (%%[ ]%%, %%= =%%)',
+            '- IF/ENDIF, FOR/NEXT block balance',
+            '- Correct function names and argument counts',
+            '- Correct comment syntax (/* */ only)',
+            '- Proper variable declaration with @',
+        ]
+        : [
+            '- No ES6+ syntax (var, not let/const; no arrow functions)',
+            '- Platform.Load before Core library objects',
+            '- Correct Platform.Function calls',
+            '- WSProxy error handling',
+            '- No sensitive data in logs or responses',
+        ];
+    const checklist = checklistItems.join('\n') + platformNote;
     return {
         messages: [
             {
@@ -1260,26 +1524,12 @@ server.prompt('reviewSfmcCode', 'Review SFMC code for correctness, best practice
                         focus ? `Focus especially on: ${focus}` : '',
                         '',
                         '## Code to Review',
-                        '```' + (detectedLang === 'ssjs' ? 'javascript' : detectedLang),
+                        '```' + fenceLang,
                         code,
                         '```',
                         '',
                         '## Review checklist',
-                        detectedLang === 'ampscript'
-                            ? [
-                                '- Delimiter balance (%%[ ]%%, %%= =%%)',
-                                '- IF/ENDIF, FOR/NEXT block balance',
-                                '- Correct function names and argument counts',
-                                '- Correct comment syntax (/* */ only)',
-                                '- Proper variable declaration with @',
-                            ].join('\n') + platformNote
-                            : [
-                                '- No ES6+ syntax (var, not let/const; no arrow functions)',
-                                '- Platform.Load before Core library objects',
-                                '- Correct Platform.Function calls',
-                                '- WSProxy error handling',
-                                '- No sensitive data in logs or responses',
-                            ].join('\n') + platformNote,
+                        checklist,
                     ]
                         .filter(Boolean)
                         .join('\n'),
@@ -1395,16 +1645,56 @@ server.prompt('answerMceHowTo', 'Answer a Marketing Cloud **administration or se
 // ---------------------------------------------------------------------------
 // Tool: check_mcn_compatibility
 // ---------------------------------------------------------------------------
+const mcnFileObjectSchema = z.object({
+    filename: z.string().describe('File name (e.g. "email-template.html").'),
+    content: z.string().describe('Full file content to analyze.'),
+});
+const mcnFileArraySchema = z.array(mcnFileObjectSchema).describe('List of files to analyze.');
+/**
+ * Returns the reason for the first non-migratable SSJS pattern that matches the
+ * given block code, or an empty string when none match.
+ * @param blockCode
+ */
+function firstNonMigratableSsjsReason(blockCode) {
+    for (const { pattern, reason } of NON_MIGRATABLE_SSJS_PATTERNS) {
+        pattern.lastIndex = 0;
+        if (pattern.test(blockCode)) {
+            return reason;
+        }
+    }
+    return '';
+}
+/**
+ * Scans content for recognized Handlebars helper usages, deduplicated by
+ * helper name and approximate line. Matching is data-driven via the LSP lookup.
+ * @param content
+ */
+function collectHandlebarsHelperUsages(content) {
+    const helperCallPattern = /\{\{[#/]?\s*([a-zA-Z][\w-]*)/g;
+    const seenHelper = new Set();
+    const usages = [];
+    let helperMatch;
+    while ((helperMatch = helperCallPattern.exec(content)) !== null) {
+        const token = helperMatch[1];
+        const helper = sfmcLanguageService.lookupHandlebarsHelper(token);
+        if (!helper) {
+            continue;
+        }
+        const line = content.slice(0, helperMatch.index).split('\n').length;
+        const dedupeKey = `${helper.name}@${line}`;
+        if (seenHelper.has(dedupeKey)) {
+            continue;
+        }
+        seenHelper.add(dedupeKey);
+        usages.push({ name: helper.name, line, mcnSince: helper.mcnSince });
+    }
+    return usages;
+}
 server.tool('check_mcn_compatibility', 'Analyze one or more AMPscript/HTML files for Marketing Cloud Next (MCN) readiness. ' +
     'Returns an executive summary and a per-file, per-function report with migration difficulty. ' +
     'SSJS blocks that only use Platform.Function.* calls are classified as "Needs conversion" (not "Not migratable"). ' +
     'Use this tool before using rewrite_for_mcn.', {
-    files: z
-        .array(z.object({
-        filename: z.string().describe('File name (e.g. "email-template.html").'),
-        content: z.string().describe('Full file content to analyze.'),
-    }))
-        .describe('List of files to analyze.'),
+    files: mcnFileArraySchema,
 }, ({ files }) => {
     const results = [];
     for (const { filename, content } of files) {
@@ -1417,7 +1707,15 @@ server.tool('check_mcn_compatibility', 'Analyze one or more AMPscript/HTML files
             const notes = getMcnNotes(site.name);
             let status;
             let reason;
-            if (mcnSince !== null && notes === null) {
+            const isHbsGap = AMP_MCN_HANDLEBARS_GAP.has(site.name.toLowerCase());
+            if (isHbsGap) {
+                // Category C: documented as MCN-supported but no working Handlebars
+                // helper exists yet — fails at runtime. Always needs-review, even when
+                // mcnSince is set, because the data flags a runtime gap.
+                status = 'needs-review';
+                reason = `${site.name}() is ${HBS_GAP_NOTE}`;
+            }
+            else if (mcnSince !== null && notes === null) {
                 status = 'supported';
                 reason = '—';
             }
@@ -1444,14 +1742,7 @@ server.tool('check_mcn_compatibility', 'Analyze one or more AMPscript/HTML files
             const blockCode = blockMatch[1];
             const lineApprox = content.slice(0, blockMatch.index).split('\n').length;
             // Check for non-migratable patterns
-            let notMigratableReason = '';
-            for (const { pattern, reason } of NON_MIGRATABLE_SSJS_PATTERNS) {
-                pattern.lastIndex = 0;
-                if (pattern.test(blockCode)) {
-                    notMigratableReason = reason;
-                    break;
-                }
-            }
+            const notMigratableReason = firstNonMigratableSsjsReason(blockCode);
             if (notMigratableReason) {
                 ssjsBlocks.push({
                     index: blockIndex,
@@ -1469,28 +1760,61 @@ server.tool('check_mcn_compatibility', 'Analyze one or more AMPscript/HTML files
                 });
             }
         }
+        // 2b. Analyze MCN Handlebars regions (only meaningful for the 'next' target).
+        // Diagnostics flag unsupported constructs (partials, decorators, built-in
+        // helpers absent from the locked-down engine), unknown helpers, and arity.
+        const handlebarsProblems = [];
+        const handlebarsHelpers = [];
+        if (content.includes('{{')) {
+            const hbsDiagnostics = validateAmpscript(content, {
+                maxNumberOfProblems: 200,
+                targetPlatform: 'next',
+            }).filter((d) => d.source === 'handlebars');
+            for (const d of hbsDiagnostics) {
+                const severity = d.severity === 1 ? 'error' : d.severity === 2 ? 'warning' : 'info';
+                const message = diagnosticMessage(d.message);
+                handlebarsProblems.push({
+                    line: d.range.start.line + 1,
+                    severity,
+                    message,
+                });
+            }
+            // Report recognized helper usages with their MCN availability version.
+            // Helper names are matched against handlebars-data via the LSP lookup so
+            // this stays data-driven (no hand-maintained helper list).
+            handlebarsHelpers.push(...collectHandlebarsHelperUsages(content));
+        }
         // 3. Assess per-file difficulty
-        const hasCloudPagesFn = ampFunctions.some((f) => CLOUDPAGES_ONLY_FUNCTIONS.has(f.name.toLowerCase()) &&
+        const hasCloudPagesFunction = ampFunctions.some((f) => CLOUDPAGES_ONLY_FUNCTIONS.has(f.name.toLowerCase()) &&
             f.status === 'not-supported');
         const hasNotMigratableSsjs = ssjsBlocks.some((b) => b.status === 'not-migratable');
         const hasUnsupportedAmp = ampFunctions.some((f) => f.status === 'not-supported' &&
             !CLOUDPAGES_ONLY_FUNCTIONS.has(f.name.toLowerCase()));
         const hasConvertibleSsjs = ssjsBlocks.some((b) => b.status === 'needs-conversion');
         const hasNeedsReview = ampFunctions.some((f) => f.status === 'needs-review');
+        const hasHandlebarsError = handlebarsProblems.some((p) => p.severity === 'error');
+        const hasHandlebarsWarning = handlebarsProblems.some((p) => p.severity === 'warning');
         let difficulty;
-        if (hasCloudPagesFn || hasNotMigratableSsjs) {
+        if (hasCloudPagesFunction || hasNotMigratableSsjs) {
             difficulty = 'not-migratable';
         }
-        else if (hasUnsupportedAmp || hasConvertibleSsjs) {
+        else if (hasUnsupportedAmp || hasConvertibleSsjs || hasHandlebarsError) {
             difficulty = 'significant';
         }
-        else if (hasNeedsReview) {
+        else if (hasNeedsReview || hasHandlebarsWarning) {
             difficulty = 'minor';
         }
         else {
             difficulty = 'ready';
         }
-        results.push({ filename, difficulty, ampFunctions, ssjsBlocks });
+        results.push({
+            filename,
+            difficulty,
+            ampFunctions,
+            ssjsBlocks,
+            handlebarsProblems,
+            handlebarsHelpers,
+        });
     }
     // 4. Build Markdown report
     const difficultyLabel = {
@@ -1541,22 +1865,37 @@ server.tool('check_mcn_compatibility', 'Analyze one or more AMPscript/HTML files
         }
         if (result.ampFunctions.length > 0) {
             fileLines.push('| Function | Line | Status | Reason |', '|---|---|---|---|');
-            for (const fn of result.ampFunctions) {
-                const icon = fn.status === 'supported'
+            for (const function_ of result.ampFunctions) {
+                const icon = function_.status === 'supported'
                     ? '✅'
-                    : fn.status === 'needs-review'
+                    : function_.status === 'needs-review'
                         ? '⚠️'
                         : '❌';
-                const statusLabel = fn.status === 'supported'
+                const statusLabel = function_.status === 'supported'
                     ? 'Supported'
-                    : fn.status === 'needs-review'
+                    : function_.status === 'needs-review'
                         ? 'Needs review'
                         : 'Not supported';
-                fileLines.push(`| ${fn.name} | ${fn.line} | ${icon} ${statusLabel} | ${fn.reason} |`);
+                fileLines.push(`| ${function_.name} | ${function_.line} | ${icon} ${statusLabel} | ${function_.reason} |`);
             }
         }
-        else if (result.ssjsBlocks.length === 0) {
-            fileLines.push('*No AMPscript functions or SSJS blocks found.*');
+        else if (result.ssjsBlocks.length === 0 &&
+            result.handlebarsProblems.length === 0 &&
+            result.handlebarsHelpers.length === 0) {
+            fileLines.push('*No AMPscript functions, SSJS blocks, or Handlebars found.*');
+        }
+        if (result.handlebarsHelpers.length > 0) {
+            fileLines.push('', '**MCN Handlebars Helpers:**', '');
+            for (const h of result.handlebarsHelpers) {
+                fileLines.push(`✅ \`{{${h.name}}}\` (line ${h.line}): Supported since API v${h.mcnSince}.0`);
+            }
+        }
+        if (result.handlebarsProblems.length > 0) {
+            fileLines.push('', '**MCN Handlebars Problems:**', '');
+            for (const p of result.handlebarsProblems) {
+                const icon = p.severity === 'error' ? '❌' : p.severity === 'warning' ? '⚠️' : 'ℹ️';
+                fileLines.push(`${icon} Line ${p.line}: ${p.message}`);
+            }
         }
         fileLines.push('', '---');
     }
@@ -1641,7 +1980,8 @@ server.tool('rewrite_for_mcn', 'Deterministically rewrite AMPscript (and optiona
     });
     // Reassess difficulty
     const hasMigratable = allNonMigratable.length > 0;
-    const difficulty = hasMigratable && allNonMigratable.some((i) => i.reason.includes('not-migratable'))
+    const difficulty = hasMigratable &&
+        allNonMigratable.some((index) => index.reason.includes('not-migratable'))
         ? 'not-migratable'
         : ampResult.difficulty;
     const result = {
@@ -1801,6 +2141,263 @@ server.tool('convertAmpscriptToSsjs', 'Deterministically convert AMPscript code
     };
 });
 // ---------------------------------------------------------------------------
+// Tool: convertAmpscriptToHandlebars
+// ---------------------------------------------------------------------------
+server.tool('convertAmpscriptToHandlebars', 'Deterministically convert AMPscript to Marketing Cloud Next (MCN) Handlebars using the ' +
+    'three-category model built from ampscript-data: (A) functions with a Handlebars helper ' +
+    'equivalent become {{helper …}}; (B) functions with no MCN counterpart become a ' +
+    'MANUAL_REWRITE_REQUIRED comment; (C) mcnHandlebarsGap functions (e.g. ContentBlockByKey) ' +
+    'become a DISTINCT MANUAL_REWRITE_REQUIRED comment noting they are documented as ' +
+    'MCN-supported but currently fail at runtime. Procedural AMPscript blocks (SET/VAR/IF/FOR) ' +
+    'have no Handlebars equivalent and are flagged. ' +
+    'Use the convertAmpscriptToHandlebars PROMPT for AI-enhanced handling of flagged sections.', {
+    code: z.string().describe('The AMPscript code to convert to MCN Handlebars.'),
+}, ({ code }) => {
+    const result = ampscriptToHandlebars(code);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    convertedCode: result.convertedCode,
+                    changes: result.changes,
+                    flaggedSections: result.flaggedSections,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Prompt: convertAmpscriptToHandlebars
+// ---------------------------------------------------------------------------
+server.prompt('convertAmpscriptToHandlebars', 'Convert AMPscript to Marketing Cloud Next (MCN) Handlebars. ' +
+    'Calls the convertAmpscriptToHandlebars tool first for a deterministic, data-driven ' +
+    'conversion, then applies AI reasoning to handle MANUAL_REWRITE_REQUIRED sections.', {
+    code: z.string().describe('The AMPscript code to convert to MCN Handlebars.'),
+}, ({ code }) => ({
+    messages: [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: [
+                    'You are an expert Salesforce Marketing Cloud developer converting AMPscript to Marketing Cloud Next (MCN) Handlebars.',
+                    '',
+                    '## Instructions',
+                    '1. Call the `convertAmpscriptToHandlebars` **tool** with the code below to get a deterministic conversion.',
+                    '2. Review the `flaggedSections` — these are constructs the tool could not convert automatically.',
+                    '3. For each flagged section, apply your expertise, but obey these hard rules:',
+                    '   - NEVER invent a Handlebars helper. Only use helpers that exist in the MCN catalog (call `list_handlebars_helpers` / `lookup_handlebars_helper`).',
+                    '   - Category B (no MCN counterpart): leave a clear `{{!-- MANUAL_REWRITE_REQUIRED … --}}` note explaining the manual step.',
+                    '   - Category C (documented-supported but runtime gap, e.g. ContentBlockByKey): keep the DISTINCT runtime-gap note — do not replace it with a fabricated helper.',
+                    '   - AMPscript procedural blocks (SET/VAR/IF/FOR) have no Handlebars equivalent — Handlebars cannot assign variables or run imperative logic. Restructure the data upstream instead.',
+                    '4. Validate your final output by calling `validate_handlebars`.',
+                    '5. Produce a single final Handlebars-in-HTML code block plus a short bulleted change log.',
+                    '',
+                    '## AMPscript code to convert',
+                    '```',
+                    code,
+                    '```',
+                ].join('\n'),
+            },
+        },
+    ],
+}));
+// ---------------------------------------------------------------------------
+// Tool: convertHandlebarsToAmpscript
+// ---------------------------------------------------------------------------
+server.tool('convertHandlebarsToAmpscript', 'Deterministically convert Marketing Cloud Next (MCN) Handlebars to AMPscript (best-effort, ' +
+    'lossy). Inline helper calls that map back to an AMPscript function become %%=Fn(…)=%%; ' +
+    'bare variables {{name}} become %%=v(@name)=%%. Block helpers ({{#each}}/{{#if}}), partials, ' +
+    'dotted binding paths, and helpers with no AMPscript equivalent are flagged ' +
+    'MANUAL_REWRITE_REQUIRED. Use the convertHandlebarsToAmpscript PROMPT for AI-enhanced handling.', {
+    code: z.string().describe('The MCN Handlebars code to convert to AMPscript.'),
+}, ({ code }) => {
+    const result = handlebarsToAmpscript(code);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    convertedCode: result.convertedCode,
+                    changes: result.changes,
+                    flaggedSections: result.flaggedSections,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Prompt: convertHandlebarsToAmpscript
+// ---------------------------------------------------------------------------
+server.prompt('convertHandlebarsToAmpscript', 'Convert Marketing Cloud Next (MCN) Handlebars to AMPscript (best-effort, lossy). ' +
+    'Calls the convertHandlebarsToAmpscript tool first for a deterministic conversion, then ' +
+    'applies AI reasoning to handle MANUAL_REWRITE_REQUIRED sections.', {
+    code: z.string().describe('The MCN Handlebars code to convert to AMPscript.'),
+}, ({ code }) => ({
+    messages: [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: [
+                    'You are an expert Salesforce Marketing Cloud developer converting MCN Handlebars to AMPscript.',
+                    '',
+                    '## Instructions',
+                    '1. Call the `convertHandlebarsToAmpscript` **tool** with the code below to get a deterministic conversion.',
+                    '2. Review the `flaggedSections` — block helpers, partials, and binding paths often need context-specific AMPscript.',
+                    '3. For each flagged section, apply your expertise:',
+                    '   - `{{#each items}}…{{/each}}` → AMPscript `FOR @i = 1 TO RowCount(@items) DO … NEXT @i`',
+                    '   - `{{#if cond}}…{{else}}…{{/if}}` → `IF cond THEN … ELSE … ENDIF`',
+                    '   - `{!$…}` bindings and `mcn-platform` helpers may have no AMPscript equivalent — keep the MANUAL_REWRITE_REQUIRED note.',
+                    '4. Produce a single final AMPscript code block plus a short bulleted change log.',
+                    '',
+                    '## Handlebars code to convert',
+                    '```',
+                    code,
+                    '```',
+                ].join('\n'),
+            },
+        },
+    ],
+}));
+// ---------------------------------------------------------------------------
+// Tool: convertSsjsToHandlebars
+// ---------------------------------------------------------------------------
+server.tool('convertSsjsToHandlebars', 'Deterministically convert SSJS to Marketing Cloud Next (MCN) Handlebars transitively ' +
+    '(SSJS → AMPscript → Handlebars). Because Handlebars is declarative, most imperative SSJS ' +
+    'has no Handlebars counterpart and is conservatively flagged MANUAL_REWRITE_REQUIRED; ' +
+    'inline Platform.Function.* calls that map through AMPscript to a Handlebars helper are ' +
+    'converted. Use the convertSsjsToHandlebars PROMPT for AI-enhanced handling of flagged sections.', {
+    code: z
+        .string()
+        .describe('The SSJS code to convert (may include <script runat="server"> tags).'),
+}, ({ code }) => {
+    const result = ssjsToHandlebars(code);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    convertedCode: result.convertedCode,
+                    changes: result.changes,
+                    flaggedSections: result.flaggedSections,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Prompt: convertSsjsToHandlebars
+// ---------------------------------------------------------------------------
+server.prompt('convertSsjsToHandlebars', 'Convert SSJS to Marketing Cloud Next (MCN) Handlebars. Calls the convertSsjsToHandlebars ' +
+    'tool first (SSJS → AMPscript → Handlebars), then applies AI reasoning to handle the many ' +
+    'MANUAL_REWRITE_REQUIRED sections that imperative SSJS produces.', {
+    code: z.string().describe('The SSJS code to convert to MCN Handlebars.'),
+}, ({ code }) => ({
+    messages: [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: [
+                    'You are an expert Salesforce Marketing Cloud developer converting SSJS to Marketing Cloud Next (MCN) Handlebars.',
+                    '',
+                    '## Key reality',
+                    'MCN runs a locked-down Handlebars engine. SSJS does NOT exist in MCN, and Handlebars is declarative — it cannot run imperative logic. Conversion is only possible transitively (SSJS → MCN-valid AMPscript subset → Handlebars), and most non-trivial SSJS will need a redesign (move logic to the data layer / a query).',
+                    '',
+                    '## Instructions',
+                    '1. Call the `convertSsjsToHandlebars` **tool** with the code below to get a deterministic conversion.',
+                    '2. Review the `flaggedSections` from BOTH stages ([SSJS→AMPscript] and [AMPscript→Handlebars]).',
+                    '3. For each flagged section, apply your expertise — but NEVER invent a Handlebars helper (use only the MCN catalog via `list_handlebars_helpers`).',
+                    '4. Where imperative logic cannot be expressed, recommend moving it upstream (e.g. a `{{#query}}` / data binding) and keep a clear MANUAL_REWRITE_REQUIRED note.',
+                    '5. Validate your final output by calling `validate_handlebars`.',
+                    '6. Produce a single final Handlebars-in-HTML code block plus a short bulleted change log.',
+                    '',
+                    '## SSJS code to convert',
+                    '```javascript',
+                    code,
+                    '```',
+                ].join('\n'),
+            },
+        },
+    ],
+}));
+// ---------------------------------------------------------------------------
+// Tool: write_handlebars
+// ---------------------------------------------------------------------------
+server.tool('write_handlebars', 'Validate a Marketing Cloud Next (MCN) Handlebars-in-HTML draft so it can be finalized as ' +
+    'authored content. Runs the MCN Handlebars validator (locked-down engine) on the draft and ' +
+    'returns whether it is clean, plus any diagnostics (unknown/too-new helpers, unsupported ' +
+    'constructs, arity). Use the write_handlebars PROMPT to AUTHOR from intent — that prompt ' +
+    'instructs the model to use only catalog helpers and then call this tool to verify.', {
+    draft: z.string().describe('The Handlebars-in-HTML draft to validate before finalizing.'),
+    intent: z
+        .string()
+        .optional()
+        .describe('Optional human description of what the content should do (echoed for context).'),
+}, ({ draft, intent }) => {
+    const diagnostics = validateAmpscript(draft, {
+        maxNumberOfProblems: 100,
+        targetPlatform: 'next',
+    }).filter((d) => d.source === 'handlebars');
+    const isClean = diagnostics.length === 0;
+    const header = isClean
+        ? '✅ Draft is valid MCN Handlebars.'
+        : `❌ Draft has ${diagnostics.length} MCN Handlebars issue(s) — fix before finalizing:`;
+    const intentLine = intent ? `Intent: ${intent}\n\n` : '';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${intentLine}${header}\n\n${formatDiagnostics(diagnostics)}`,
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Prompt: writeHandlebars
+// ---------------------------------------------------------------------------
+server.prompt('writeHandlebars', 'Author Marketing Cloud Next (MCN) Handlebars-in-HTML from a natural-language intent, using ' +
+    'only helpers that exist in the MCN catalog, then validate the result with write_handlebars.', {
+    intent: z
+        .string()
+        .describe('What the content should do, e.g. "greet the subscriber by first name and show their loyalty tier".'),
+    context: z
+        .string()
+        .optional()
+        .describe('Optional data/personalization context (available fields, bindings, sample data).'),
+}, ({ intent, context }) => ({
+    messages: [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: [
+                    'You are an expert Salesforce Marketing Cloud developer authoring Marketing Cloud Next (MCN) Handlebars-in-HTML.',
+                    '',
+                    '## Hard rules',
+                    '- MCN runs a LOCKED-DOWN Handlebars engine. NEVER invent a helper. Only use helpers in the MCN catalog — call `list_handlebars_helpers` (and `lookup_handlebars_helper` for signatures) before writing.',
+                    '- Respect each helper`s `mcnSince` availability.',
+                    '- Partials ({{> …}}), decorators ({{* …}}), and built-in helpers absent from MCN (e.g. {{log}}) are NOT allowed.',
+                    '- `{!$…}` bindings are merge fields, not helpers — use `list_handlebars_helpers` output / bindings catalog for valid ones.',
+                    '',
+                    '## Instructions',
+                    '1. Inspect the available catalog with `list_handlebars_helpers`.',
+                    '2. Author the Handlebars-in-HTML to satisfy the intent below.',
+                    '3. Call the `write_handlebars` **tool** with your draft to validate it.',
+                    '4. If validation reports issues, fix them and re-validate until clean.',
+                    '5. Return the final, validated Handlebars-in-HTML code block.',
+                    '',
+                    `## Intent`,
+                    intent,
+                    ...(context ? ['', '## Context', context] : []),
+                ].join('\n'),
+            },
+        },
+    ],
+}));
+// ---------------------------------------------------------------------------
 // Tool: get_server_version
 // ---------------------------------------------------------------------------
 server.tool('get_server_version', 'Return the running mcp-server-sfmc version and the size of the bundled Salesforce ' +
@@ -1815,7 +2412,7 @@ server.tool('get_server_version', 'Return the running mcp-server-sfmc version an
                 type: 'text',
                 text: JSON.stringify({
                     name: 'mcp-server-sfmc',
-                    version: pkg.version,
+                    version: package_.version,
                     mceHelp: { chunkCount: mce.chunkCount, fileCount: mceFileCount },
                     mcnHelp: { chunkCount: mcn.chunkCount, fileCount: mcn.fileCount },
                 }, null, 2),
@@ -1828,15 +2425,18 @@ server.tool('get_server_version', 'Return the running mcp-server-sfmc version an
 // ---------------------------------------------------------------------------
 async function main() {
     if (process.argv.includes('--version') || process.argv.includes('-v')) {
-        process.stdout.write(pkg.version + '\n');
+        process.stdout.write(package_.version + '\n');
         return;
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     process.stderr.write('mcp-server-sfmc running on stdio\n');
 }
-main().catch((ex) => {
+try {
+    await main();
+}
+catch (ex) {
     process.stderr.write(`Fatal: ${String(ex)}\n`);
     process.exit(1);
-});
+}
 //# sourceMappingURL=index.js.map