{ "markdown": "# mcp-server-sfmc\n\nMCP server providing Salesforce Marketing Cloud language intelligence — AMPscript, SSJS, GTL, and **Marketing Cloud Next (MCN) Handlebars** — as Model Context Protocol tools, resources, and prompts for AI-assisted development and code review. Ships two searchable doc indexes: **MCE help** (Salesforce Help for Marketing Cloud Engagement administration and setup) and **MCN developer docs** (Marketing Cloud Next REST API and developer reference). Includes full **Marketing Cloud Next (MCN) platform awareness**: auto-detects whether a project targets MCE or MCN, restricts completions and validation to MCN-supported functions, flags SSJS as unsupported in MCN, surfaces MCN behavioral differences in hover and diagnostics, validates MCN Handlebars templates, and provides a **migration toolkit** to analyze and rewrite code for MCN — including AMPscript ↔ Handlebars and SSJS → Handlebars conversion.\n\nBuilt on [sfmc-language-lsp](https://github.com/JoernBerkefeld/sfmc-language-lsp), the same engine that powers the [SFMC Language Service VS Code extension](https://marketplace.visualstudio.com/items?itemName=joernberkefeld.sfmc-language).\n\n## VS Code MCP Server Gallery (`@mcp`)\n\nThis package is registered with the [official MCP Registry](https://registry.modelcontextprotocol.io) as **`io.github.JoernBerkefeld/mcp-server-sfmc`** so it can appear in Visual Studio Code when you use the **`@mcp`** filter in the Extensions view (see the [publish quickstart](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx)). Enable **`chat.mcp.gallery.enabled`** if the gallery does not show.\n\nThe registry only stores **metadata**; the server still runs **locally** via stdio (for example `npx -y mcp-server-sfmc@latest`). This is separate from **`@contribute:mcp`**, which lists VS Code extensions that contribute MCP definitions — use the [SFMC Language Service](https://marketplace.visualstudio.com/items?itemName=joernberkefeld.sfmc-language) for that path.\n\nAfter publishing metadata (see [Publish an MCP Server](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx) or the release workflow), you can confirm the entry with:\n\n`curl \"https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.JoernBerkefeld/mcp-server-sfmc\"`\n\n## VS Code without manual MCP config\n\nIf you use the **SFMC Language Service** extension (**1.101+**), it registers this MCP server for discovery in VS Code — you normally do **not** need to edit `.vscode/mcp.json` or run `npm install` for that path; VS Code still launches the published package via `npx` when the server starts.\n\nFor **other editors**, or if you prefer explicit configuration, use the `npx` or install options below.\n\n## Using this package without the VS Code extension\n\nYou **do not** have to install the VS Code extension. Pick one way to run the server:\n\n| Approach | When to use it |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`npx` (no install)** | Default in the examples below. Runs the latest published version from npm on demand; first run may download the package. **Requires Node.js and npm** (which provides `npx`). |\n| **`npm install -g mcp-server-sfmc`** | Same CLI as `npx`, but the package stays on disk so **startup is faster** and you can set `\"command\": \"mcp-server-sfmc\"` with empty `args` in your MCP config. |\n| **`npm install mcp-server-sfmc` in a project** | Keeps a **pinned version** in that folder's `node_modules` — point your MCP config at `npx mcp-server-sfmc` with `cwd` set to the project, or run `./node_modules/.bin/mcp-server-sfmc` directly. |\n| **`sfmc-review-diff` (bundled CLI)** | For **CI**: spawns this MCP server, calls `review_change` on a unified diff (stdin or file), exits non-zero on `ERROR` by default. Install the package in the job, then e.g. `git diff base...HEAD \\| npx sfmc-review-diff`. |\n\nNone of these replace the VS Code extension for **editing** (syntax, LSP, snippets); they only expose the **MCP server** to tools that speak the Model Context Protocol.\n\n## CI templates and `sfmc-review-diff`\n\nReady-to-copy workflows (GitHub Actions, GitLab CI, Jenkins, Azure Pipelines, Bitbucket Pipelines) live under **[`ci-templates/`](./ci-templates/)**. They run **`eslint-plugin-sfmc`** on changed files and **`sfmc-review-diff`** on the PR/MR unified diff. See **[`ci-templates/README.md`](./ci-templates/README.md)** for what each file does and how the two checks differ.\n\n## What it gives your AI assistant\n\n| Feature | Details |\n| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Validation** | Syntax errors, unknown functions, arity mismatches, unsupported SSJS syntax; `target: 'next'` flags MCN-incompatible functions and all SSJS; `validate_handlebars` checks MCN Handlebars helper names, arity, block balance, and unsupported constructs |\n| **Lookup** | Full function signatures, parameters, return types, MCN compatibility badge (API version), behavioral notes, and examples |\n| **PR review** | Diff-aware review tool that surfaces issues in the exact lines that changed |\n| **Fix suggestions** | Concrete, compilable replacement code; `target: 'next'` includes MCN platform issues |\n| **Completions** | AMPscript completions (filtered to MCN-supported when `target: 'next'`); SSJS catalog (redirects to AMPscript for MCN) |\n| **Platform detection** | `detect_sfmc_platform` checks `.mcdevrc.json` (MCE) or `sfdx-project.json` (MCN) in the project root |\n| **MCN compatibility analysis** | `check_mcn_compatibility` analyzes files for MCN readiness — per-function classification (supported / needs review / not supported), SSJS block migration difficulty, and an executive summary |\n| **MCN migration** | `rewrite_for_mcn` (tool + prompt) deterministically rewrites AMPscript and converts convertible SSJS to AMPscript for MCN, then applies AI reasoning to remaining manual-rewrite sections |\n| **Code conversion** | `convertSsjsToAmpscript` and `convertAmpscriptToSsjs` (tool + prompt hybrid) — rule-based conversion with AI-enhanced handling of flagged sections |\n| **MCN Handlebars** | `lookup_handlebars_helper`, `list_handlebars_helpers`, `get_handlebars_completions`, and `write_handlebars` (authoring) backed by the `handlebars-data` catalog |\n| **Handlebars conversion** | `convertAmpscriptToHandlebars`, `convertHandlebarsToAmpscript`, and `convertSsjsToHandlebars` (tool + prompt hybrid) — data-driven from `ampscript-data` `handlebarsEquivalent` / `handlebarsExact` |\n| **Prompts** | Guided prompts for writing AMPscript/SSJS/Handlebars (with MCN constraints), reviewing code, converting between languages, and rewriting for MCN |\n| **Resources** | Full function catalogs, keyword list, unsupported ES6+ syntax list, MCN Handlebars helper and binding catalogs |\n| **Help search** | `search_help` (unified, auto-detects MCE vs MCN from project root); `search_mce_help` (MCE help, 7 product scopes); `search_mcn_help` (MCN developer API reference) |\n\n## Connecting AI clients\n\n### VS Code (1.99+) + GitHub Copilot — manual `mcp.json`\n\nIf you are **not** using the SFMC Language Service extension's built-in MCP registration, add a `.vscode/mcp.json` file to your project (or copy it from this repo):\n\n```json\n{\n \"servers\": {\n \"sfmc\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-sfmc@latest\"]\n }\n }\n}\n```\n\nOpen the file in VS Code — a **Start** button appears at the top. Click it to launch the server. Open GitHub Copilot Chat in **Agent mode** and the SFMC tools appear automatically.\n\n### Cursor\n\nAdd to your Cursor settings (`~/.cursor/mcp.json` or project-level `.cursor/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"sfmc\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-sfmc@latest\"]\n }\n }\n}\n```\n\nRestart Cursor. The tools are available in Agent mode.\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"sfmc\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-sfmc@latest\"]\n }\n }\n}\n```\n\nRestart Claude Desktop.\n\n### Windsurf\n\nAdd to your Windsurf MCP settings (`~/.codeium/windsurf/mcp_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"sfmc\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-sfmc@latest\"]\n }\n }\n}\n```\n\n### Local install (faster startup than npx)\n\n```bash\nnpm install -g mcp-server-sfmc\n```\n\nThen replace `\"command\": \"npx\", \"args\": [\"-y\", \"mcp-server-sfmc@latest\"]` with:\n\n```json\n\"command\": \"mcp-server-sfmc\",\n\"args\": []\n```\n\n## Tools\n\n| Tool | Description |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `validate_ampscript` | Validate AMPscript code — unknown functions, arity, delimiter balance, comment syntax. `target: 'next'` flags MCN-incompatible functions. |\n| `validate_ssjs` | Validate SSJS — ES6+ usage, missing Platform.Load, wrong API calls. `target: 'next'` flags all SSJS as unsupported. |\n| `validate_sfmc_html` | Validate HTML with embedded AMPscript, SSJS, and GTL blocks. `target: 'next'` enables MCN validation. |\n| `lookup_ampscript_function` | Full signature, parameters, return type, MCN compatibility badge (API version), behavioral notes for MCN, and examples |\n| `lookup_ssjs_function` | Full signature and description for any SSJS Platform function or method |\n| `list_ampscript_functions` | List all AMPscript functions, optionally filtered by `platform: 'next'` to return only MCN-supported functions |\n| `review_change` | Review a unified diff — validates only added lines, maps back to diff line numbers |\n| `suggest_fix` | Generate fix suggestions for each diagnostic in a code snippet. `target: 'next'` includes MCN fixes. |\n| `get_ampscript_completions` | List valid completions at a given cursor position; MCN-unsupported functions marked `[MCE only]` when `target: 'next'` |\n| `get_ssjs_completions` | List SSJS Platform API completions, optionally filtered by prefix; redirects to AMPscript completions when `target: 'next'` |\n| `format_sfmc_code` | Apply basic formatting conventions (keyword casing, quote normalisation) |\n| `detect_sfmc_platform` | Detect the target platform for a project — checks `.mcdevrc.json` (→ `\"engagement\"`) or `sfdx-project.json` (→ `\"next\"`) |\n| `check_mcn_compatibility` | Analyze one or more AMPscript/HTML files for MCN readiness. Returns per-function classification, SSJS block migration difficulty, and an executive summary with overall migration effort. Run this before `rewrite_for_mcn`. |\n| `rewrite_for_mcn` | Deterministic MCN rewrite engine: fixes `.NET → Java` format strings, removes `StringToDate` wrappers, converts convertible SSJS to AMPscript, marks unsupported functions, annotates the rest as `MANUAL_REWRITE_REQUIRED`. **Prefer the `rewrite_for_mcn` prompt** for interactive use — it calls this tool first, then applies AI reasoning to the flagged sections. Use the tool directly only for structured JSON output in pipelines. |\n| `convertSsjsToAmpscript` | Rule-based SSJS → AMPscript conversion engine: `Platform.Function.*` → AMPscript equivalents, variable/request access, control flow. Flags JS-native constructs as `MANUAL_REWRITE_REQUIRED`. **Prefer the `convertSsjsToAmpscript` prompt** for interactive use. |\n| `convertAmpscriptToSsjs` | Rule-based AMPscript → SSJS conversion engine: variables, control flow, function calls. Flags AMPscript-only constructs as `MANUAL_REWRITE_REQUIRED`. **Prefer the `convertAmpscriptToSsjs` prompt** for interactive use. |\n| `validate_handlebars` | Validate MCN Handlebars template code — helper names, arity, block balance, and unsupported constructs (partials, decorators, built-in helpers absent from the locked-down MCN engine). |\n| `lookup_handlebars_helper` | Signature, parameters, description, origin, and MCN API version for a single MCN Handlebars helper (case-insensitive). |\n| `list_handlebars_helpers` | List all MCN Handlebars helpers, optionally filtered by `category` and/or `origin` (`handlebars-builtin`, `mcn-helper`, `mcn-platform`). |\n| `get_handlebars_completions` | List MCN Handlebars helper completions, optionally filtered by prefix. |\n| `convertAmpscriptToHandlebars` | Rule-based AMPscript → MCN Handlebars conversion. Maps functions to helpers where an equivalent exists; flags unsupported functions and runtime gaps as `MANUAL_REWRITE_REQUIRED`. **Prefer the `convertAmpscriptToHandlebars` prompt** for interactive use. |\n| `convertHandlebarsToAmpscript` | Rule-based MCN Handlebars → AMPscript conversion. Maps helpers and bindings back to AMPscript; flags block helpers as `MANUAL_REWRITE_REQUIRED`. **Prefer the `convertHandlebarsToAmpscript` prompt** for interactive use. |\n| `convertSsjsToHandlebars` | Transitive SSJS → AMPscript → MCN Handlebars conversion. Conservatively flags imperative SSJS for manual rewrite. **Prefer the `convertSsjsToHandlebars` prompt** for interactive use. |\n| `write_handlebars` | Validate an MCN Handlebars-in-HTML draft against the helper catalog. **Prefer the `writeHandlebars` prompt** for authoring. |\n| `search_help` | **Unified help search** — auto-detects the platform from `projectRoot` and routes to the right doc index. MCN projects search both the developer API reference and MCN admin docs. Pass `target` to override detection. |\n| `search_mce_help` | Search bundled Marketing Cloud Engagement setup/ops help; use `product_focus` to target Engagement vs Next |\n| `search_mcn_help` | Search bundled Marketing Cloud Next developer API documentation (objects, flows, segments, REST/SOAP APIs, AMPscript behavior in MCN) |\n\n## Resources\n\n| URI | Description |\n| -------------------------------- | -------------------------------------------------------------------------------------------- |\n| `sfmc://ampscript/functions` | Full AMPscript function catalog with signatures |\n| `sfmc://ssjs/functions` | Full SSJS function catalog |\n| `sfmc://ampscript/keywords` | All AMPscript keywords |\n| `sfmc://ssjs/unsupported-syntax` | ES6+ features not supported in SFMC SSJS |\n| `sfmc://handlebars/helpers` | Full MCN Handlebars helper catalog with signatures, origin, and MCN API version |\n| `sfmc://handlebars/bindings` | MCN Handlebars data bindings (context variables available in templates) |\n| `sfmc://mce/product-context` | How **Marketing Cloud Engagement** differs from **Marketing Cloud Next** (when to use which) |\n| `sfmc://mce/help-index` | List of bundled MCE help files and section counts per product scope |\n| `sfmc://mcn/help-index` | List of bundled MCN developer API doc files and chunk counts |\n\n## Prompts\n\nAccess via `/mcp.sfmc.writeAmpscript` etc. in VS Code, or via the prompts API:\n\n| Prompt | Description |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `writeAmpscript` | Generate AMPscript code for a described task. `target: 'next'` enforces MCN constraints (MCN-supported functions only, Java `SimpleDateFormat` patterns, no SSJS). |\n| `writeSsjs` | Generate SSJS code for a described task. `target: 'next'` redirects to AMPscript instead (SSJS is not available in MCN). |\n| `reviewSfmcCode` | Review AMPscript or SSJS code for bugs and best-practice violations. `target: 'next'` adds MCN compatibility checklist. |\n| `rewrite_for_mcn` | **Primary interface for MCN migration.** Internally calls the `rewrite_for_mcn` tool for all deterministic rewrites, then applies AI reasoning to every `MANUAL_REWRITE_REQUIRED` section — producing a single fully migrated code block with a prose changelog. You always get both the rule-based pass and the AI pass in one step. |\n| `convertSsjsToAmpscript` | **Primary interface for SSJS → AMPscript conversion.** Internally calls the `convertSsjsToAmpscript` tool for rule-based conversion, then AI-reasons over any sections the rules could not handle. |\n| `convertAmpscriptToSsjs` | **Primary interface for AMPscript → SSJS conversion.** Internally calls the `convertAmpscriptToSsjs` tool for rule-based conversion, then applies AI reasoning to flagged AMPscript-only constructs. |\n| `writeHandlebars` | Generate MCN Handlebars-in-HTML for a described task, constrained to the locked-down MCN helper catalog. Validates the draft against `handlebars-data` and reports unsupported constructs. |\n| `convertAmpscriptToHandlebars` | **Primary interface for AMPscript → MCN Handlebars conversion.** Internally calls the `convertAmpscriptToHandlebars` tool for rule-based conversion, then AI-reasons over functions with no Handlebars equivalent (runtime gaps and unsupported functions). |\n| `convertHandlebarsToAmpscript` | **Primary interface for MCN Handlebars → AMPscript conversion.** Internally calls the `convertHandlebarsToAmpscript` tool for rule-based conversion, then AI-reasons over block helpers and constructs the rules could not handle. |\n| `convertSsjsToHandlebars` | **Primary interface for SSJS → MCN Handlebars conversion.** Transitive (SSJS → AMPscript → Handlebars); calls the `convertSsjsToHandlebars` tool, then applies AI reasoning to imperative SSJS flagged for manual rewrite. |\n| `answerMceHowTo` | Guided prompt for admin/setup questions — searches bundled help and keeps Engagement vs Next explicit |\n\n## Migrating code to Marketing Cloud Next\n\nMarketing Cloud Next (MCN) supports **41 of the 155 AMPscript functions** and **does not support SSJS**. Three supported functions have behavioral differences (see below). The migration toolkit guides you from analysis through to a fully rewritten result.\n\n### Recommended workflow\n\n```\n1. detect_sfmc_platform → confirm the project targets MCN\n2. check_mcn_compatibility → understand scope: which files need work, how hard\n3. rewrite_for_mcn prompt → calls the rewrite_for_mcn tool internally, then applies AI\n reasoning to any MANUAL_REWRITE_REQUIRED sections\n4. validate_ampscript with target:'next' → verify the rewritten code is clean\n```\n\n### What `check_mcn_compatibility` tells you\n\nPass one or more `{ filename, content }` pairs and get back:\n\n- **Per-function classification** for every AMPscript call site:\n - ✅ Supported — works as-is\n - ⚠️ Needs review — supported but has behavioral differences in MCN\n - ❌ Not supported — no MCN equivalent\n- **SSJS block analysis** — classified as \"needs conversion\" (has AMPscript equivalents) or \"not migratable\" (uses JS-native constructs such as `try/catch`, `forEach`, regex)\n- **Migration difficulty per file** — Ready / Minor changes needed / Significant rewrite / Not migratable\n- **Executive summary** across all files\n\n### What `rewrite_for_mcn` does\n\n**Use the `rewrite_for_mcn` prompt** — it is the primary interface and gives you the full result in one step. It first calls the `rewrite_for_mcn` tool internally for all deterministic rewrites, then applies AI reasoning to every section the tool could not handle mechanically. You get both the accuracy of rule-based conversion and the intelligence of an AI pass, without having to invoke them separately.\n\n**Deterministic rewrites (handled by the tool internally):**\n\n- Removes `StringToDate()` wrappers from `FormatDate()` calls (`FormatDate(StringToDate(@x), fmt)` → `FormatDate(@x, fmt)`)\n- Converts `.NET → Java SimpleDateFormat` format strings (e.g. `tt` → `a`)\n- Annotates `Lookup()` calls with an odd number of search arguments\n- Marks MCE-only AMPscript functions with `%%-- NOT SUPPORTED IN MCN %%`\n- Converts convertible SSJS blocks to AMPscript (`Platform.Function.*` → AMPscript equivalents, `Platform.Variable.GetValue/SetValue` → `@variable` references)\n- Flags JS-native SSJS constructs (`try/catch`, array methods, regex, complex logic) as `MANUAL_REWRITE_REQUIRED`\n\n**AI reasoning layer (added by the prompt):** for each `MANUAL_REWRITE_REQUIRED` section, the prompt instructs the AI to attempt a full conversion using its knowledge of AMPscript and SSJS, then produces a single final rewritten code block with a prose changelog covering every change.\n\n> **Pipelines and programmatic use:** call the `rewrite_for_mcn` **tool** directly when you need the structured JSON output (`{ rewrittenCode, changes[], nonMigratableItems[], difficulty, summary }`) without the AI layer — for example in a CI step that feeds results to another tool.\n\nThe same hybrid pattern applies to `convertSsjsToAmpscript` and `convertAmpscriptToSsjs`: always use the **prompt** for interactive use; use the **tool** when you need structured output in a pipeline.\n\n### MCN behavioral differences to watch for\n\n| Function | Difference |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `FormatDate` | Uses **Java `SimpleDateFormat`** patterns in MCN instead of .NET. Example: `.NET \"M/d/yyyy h:mm:ss tt\"` → Java `\"M/d/yyyy h:mm:ss a\"` |\n| `Lookup` | Search arguments must come in column/value pairs — an **odd argument count causes an error** in MCN. All filter keys must fully specify the composite primary key. |\n| `StringToDate` | Returns a **locale-formatted string** in MCN (G standard format, e.g. `\"5/15/2026 1:23:45 PM\"`) instead of a dateTime object. Cannot be reliably passed to `FormatDate()` in MCN — use `FormatDate()` directly with the original date string instead. |\n\n### CloudPages functions — not migratable\n\nFunctions that depend on CloudPages context (`CloudPagesURL`, `RequestParameter`, `QueryParameter`, `Redirect`, `MicrositeURL`) have no equivalent in Marketing Cloud Next. `check_mcn_compatibility` and `rewrite_for_mcn` flag these as **Not migratable** immediately.\n\n## MCN Handlebars\n\nMarketing Cloud Next embeds a **locked-down Handlebars** templating layer (Handlebars.Net) alongside AMPscript. The server exposes the full helper catalog and conversion tooling, all data-driven from [`handlebars-data`](https://www.npmjs.com/package/handlebars-data) and the `handlebarsEquivalent` / `handlebarsExact` fields in [`ampscript-data`](https://www.npmjs.com/package/ampscript-data) — nothing is hand-maintained.\n\n### Authoring & lookup\n\n```\n1. list_handlebars_helpers → browse the catalog (filter by category / origin)\n2. lookup_handlebars_helper → signature, parameters, origin, MCN API version\n3. get_handlebars_completions → prefix-filtered completions\n4. writeHandlebars prompt → generate Handlebars-in-HTML, validated against the catalog\n5. validate_handlebars → helper names, arity, block balance, unsupported constructs\n```\n\n`validate_handlebars` rejects constructs the MCN engine does not implement — partials (`{{> name}}`), decorators (`{{#* ...}}`), and built-in helpers absent from the locked-down runtime.\n\n### Conversion categories\n\nAMPscript → Handlebars conversion classifies every function from `ampscript-data`:\n\n| Category | Condition (in `ampscript-data`) | Output |\n| -------- | ----------------------------------------------------- | ----------------------------------------------------------------- |\n| **Exact** | `handlebarsEquivalent` set AND `handlebarsExact !== false` | Mapped to the canonical MCN Handlebars helper |\n| **Approximate** | `handlebarsEquivalent` set AND `handlebarsExact === false` | `{{!-- MANUAL_REWRITE_REQUIRED: … (names the closest helper) --}}` |\n| **None** | No Handlebars counterpart | `{{!-- MANUAL_REWRITE_REQUIRED: … no Handlebars equivalent --}}` |\n\nThe Approximate note names the closest helper so consumers can tell a function whose call shape merely differs (e.g. `ContentBlockByKey` → `getContentBlock`) apart from one with no MCN counterpart at all. `convertSsjsToHandlebars` is transitive (SSJS → AMPscript → Handlebars) and conservatively flags imperative SSJS for manual rewrite.\n\n## Writing effective prompts\n\n### Automatic tool use\n\nClients that honour the MCP `instructions` field (Cursor, Claude Desktop, GitHub Copilot Agent mode) will call `search_help` or `search_mce_help` automatically whenever you ask an MCE administration or setup question — no special phrasing needed. If your client does not process server instructions, or if you want explicit control, the templates below help.\n\n### Quick reference: which tool or prompt to use\n\n| Situation | What to do |\n| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| MCE admin question (classic Engagement) | Ask naturally; the server calls `search_help` (or `search_mce_help` directly). Or use the `answerMceHowTo` prompt with `assumeProduct: engagement`. |\n| Marketing Cloud Next developer API question | The server calls `search_help` or `search_mcn_help` automatically. Or use `search_mcn_help` explicitly. |\n| MCN operational / migration / setup question | Use `search_mce_help` with `product_focus: 'next'`, or ask naturally and the server routes it. |\n| Not sure which product | Use `answerMceHowTo` with `assumeProduct: unsure`, or `search_help` without a `target`. |\n| Write or validate AMPscript | Use the `writeAmpscript` prompt, or ask directly (the server auto-validates). Add `target: 'next'` for MCN. |\n| Write or validate SSJS | Use the `writeSsjs` prompt, or ask directly. Note: SSJS is not supported in MCN. |\n| Check if code is MCN-ready | Use `check_mcn_compatibility` with your file contents. |\n| Migrate code to Marketing Cloud Next | Use the `rewrite_for_mcn` **prompt** — it calls the tool internally for deterministic rewrites, then applies AI reasoning to any remaining manual sections. Use the tool directly only when you need structured JSON output in a pipeline. |\n| Convert SSJS ↔ AMPscript | Use the `convertSsjsToAmpscript` or `convertAmpscriptToSsjs` **prompt** — same hybrid pattern: tool runs first, AI handles what the rules couldn't. |\n| Write or validate MCN Handlebars | Use the `writeHandlebars` prompt to author, or `validate_handlebars` to check existing template code. Look helpers up with `lookup_handlebars_helper` / `list_handlebars_helpers`. |\n| Convert AMPscript ↔ Handlebars (or SSJS → Handlebars) | Use the `convertAmpscriptToHandlebars`, `convertHandlebarsToAmpscript`, or `convertSsjsToHandlebars` **prompt** — same hybrid pattern: tool runs first, AI handles what the rules couldn't. |\n| Review a code diff | Use the `reviewSfmcCode` prompt or mention \"review the following diff\". |\n\n### Copy-paste prompt templates\n\n#### Classic Engagement admin (most common)\n\n```\nSearch the Marketing Cloud Engagement help (product_focus: engagement) and tell me:\n\n\nCite which product version your steps apply to and note if the bundled docs are incomplete.\n```\n\n#### Marketing Cloud Next — developer API\n\n```\nSearch the Marketing Cloud Next developer docs and tell me:\n\n\nConfirm the steps apply to Marketing Cloud Next, not classic Engagement.\n```\n\n#### MCN migration analysis\n\n```\nCheck these files for Marketing Cloud Next compatibility and give me an executive summary:\n\n```\n\n#### Rewrite code for MCN\n\nUse the `rewrite_for_mcn` **prompt** — it first runs the deterministic rewrite tool, then applies AI reasoning to any sections that need it. You get the full result in one step.\n\n```\nRewrite the following AMPscript/HTML for Marketing Cloud Next:\n\n\nApply all deterministic fixes, convert convertible SSJS to AMPscript, and explain every change.\n```\n\n#### Unknown product / migration question\n\n```\nSearch both Marketing Cloud Engagement and Next help (product_focus: any) and tell me:\n\n\nSeparate the steps for classic Engagement vs Marketing Cloud Next clearly.\n```\n\n#### Explicit use of the answerMceHowTo prompt\n\nIn clients that support MCP prompts (e.g. VS Code with the `/mcp.sfmc.answerMceHowTo` command):\n\n```\n/mcp.sfmc.answerMceHowTo\n question: \"How do I create a child business unit and assign it a sender profile?\"\n assumeProduct: engagement\n```\n\n#### Combining MCE admin with code\n\n```\n1. Use search_mce_help (product_focus: engagement) to find the correct Journey Builder entry event\n configuration steps, then\n2. Write the AMPscript snippet that reads the data extension row inside the journey email.\n```\n\n### What to expect from the AI\n\n- The AI cites the product scope (Engagement or Next) in every answer.\n- If the bundled excerpts do not cover the question fully, the AI says so and suggests verifying in the live Salesforce Help.\n- Function signatures (AMPscript / SSJS) are always sourced from the language catalog, not from training data.\n\n## Refresh bundled help indexes\n\n### Marketing Cloud Engagement help\n\nThe published npm package includes `bundled/mce-help/chunks.json`, produced by `npm run bundle-mce-help`. By default the bundler uses the path in **`MCE_HELP_DOCS`** (see `scripts/bundle-mce-help.mjs`); set it to the root of your mirrored MCE Help Markdown tree when not using the maintainer default.\n\n```bash\ncd mcp-server-sfmc\nnpm run bundle-mce-help\nnpm run build\nnpm test\n```\n\nExample: `MCE_HELP_DOCS=/absolute/path/to/mce-help-mirror npm run bundle-mce-help`\n\n### Marketing Cloud Next developer docs\n\nThe published npm package includes `bundled/mcn-help/chunks.json`, produced by `npm run bundle-mcn-help`. Set **`MCN_HELP_DOCS`** to the root of your mirrored MCN developer docs tree when not using the maintainer default (see `scripts/bundle-mcn-help.mjs`).\n\n```bash\ncd mcp-server-sfmc\nnpm run bundle-mcn-help\nnpm run build\nnpm test\n```\n\nTo rebuild both indexes in one command: `npm run bundle-all`\n\n## AI code review in pull requests\n\n### Cursor Bugbot\n\n[Cursor Bugbot](https://cursor.com/bugbot) reviews pull requests (GitHub) and merge\nrequests (GitLab) automatically, leaves inline comments with fix suggestions, and publishes\na `Cursor Bugbot` check. It does not run `sfmc-review-diff` itself — you make it\nSFMC-aware in two ways:\n\n**1. Repository rules (`BUGBOT.md`) — all plans.** Copy\n[`ci-templates/BUGBOT.md`](ci-templates/BUGBOT.md) to **`.cursor/BUGBOT.md`** in your repo\nroot. It tells Bugbot how to review AMPscript, SSJS, and SFMC HTML — unknown functions,\narity, delimiter balance, ES3-only SSJS, and optional Marketing Cloud Next migration\nrules. Bugbot reads the root file plus any nested `.cursor/BUGBOT.md` files near changed\nfiles, so you can scope stricter rules to subfolders.\n\n**2. MCP tools (`mcp-server-sfmc`) — Team / Enterprise plans only.** Bugbot can call MCP\ntools during a review so its findings come from the same language catalog as the editor:\n\n1. In the [Bugbot dashboard](https://cursor.com/dashboard?tab=bugbot), enable Bugbot on\n the repository.\n2. Open the **MCP** configuration for Bugbot and add this server:\n\n```json\n{\n \"mcpServers\": {\n \"sfmc\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-sfmc@latest\"]\n }\n }\n}\n```\n\n3. Add the tools to Bugbot in the dashboard. The relevant review tools are\n `review_change`, `validate_ampscript`, `validate_ssjs`, `validate_sfmc_html`, and\n `suggest_fix`. The `BUGBOT.md` rules above instruct Bugbot when to call them.\n\n> Branch protection: require the **`Cursor Bugbot`** check to make sure a review runs\n> before merge. Findings default to a `neutral` conclusion; enable\n> fail-on-unresolved-issues in the dashboard (where available) if you want findings to\n> produce a failing check.\n\n**Run it locally first.** In Cursor 3.7+, run `/review-bugbot` on your branch before you\npush; Bugbot reuses that review on the PR/MR with the same diff, avoiding a duplicate run.\n\n### GitHub Copilot (cloud agent)\n\nThe `.github/agents/sfmc-reviewer.agent.md` custom agent in this repository configures a GitHub Copilot cloud agent that uses `mcp-server-sfmc` for SFMC-aware PR reviews.\n\nTo enable it in your own repository:\n\n1. Copy `.github/agents/sfmc-reviewer.agent.md` to your repo.\n2. In your GitHub repo settings → **Copilot → Cloud agent → MCP configuration**, add:\n\n```json\n{\n \"mcpServers\": {\n \"sfmc\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-sfmc@latest\"],\n \"tools\": [\"*\"]\n }\n }\n}\n```\n\n3. Assign the `sfmc-reviewer` agent to a pull request by mentioning it in a comment or via the **@sfmc-reviewer** agent in GitHub Copilot Chat.\n\n### GitHub Copilot (dedicated PR review)\n\nCopy `.github/copilot-instructions.md` from this repo to your project. GitHub Copilot's dedicated PR review feature reads this file and applies the SFMC language rules when summarising your PRs.\n\n### GitLab Duo\n\n1. Copy the content of `ci-templates/gitlab-duo-review-instructions.md` to `.gitlab/duo-instructions.md` in your repository.\n2. GitLab Duo Code Review will apply these instructions on every merge request.\n\n> GitLab Duo's dedicated MR review does not support MCP directly. Use the CI lint job below for automated static analysis, and the Duo instructions for AI-assisted review comments.\n\n### CI linting (deterministic checks)\n\nFor deterministic, blocking CI validation, use the templates provided in `ci-templates/`.\nEach one runs **two checks** on every PR/MR: `eslint-plugin-sfmc` on changed files, and\n`sfmc-review-diff` (this package) on the unified diff — so a finding fails the job\nregardless of which AI reviewer (Bugbot, Copilot, Duo) is also enabled.\n\n| Platform | File |\n| ------------------- | ------------------------------------------------------------------------------ |\n| GitHub Actions | [`ci-templates/github-action.yml`](ci-templates/github-action.yml) |\n| GitLab CI | [`ci-templates/gitlab-ci.yml`](ci-templates/gitlab-ci.yml) |\n| Jenkins | [`ci-templates/Jenkinsfile`](ci-templates/Jenkinsfile) |\n| Azure DevOps | [`ci-templates/azure-pipelines.yml`](ci-templates/azure-pipelines.yml) |\n| Bitbucket Pipelines | [`ci-templates/bitbucket-pipelines.yml`](ci-templates/bitbucket-pipelines.yml) |\n\nThe ESLint job posts lint results as PR/MR comments; the `sfmc-review-diff` job exits\nnon-zero on `ERROR` diagnostics by default (`--fail-on warning|info` to be stricter).\nSee [`ci-templates/README.md`](ci-templates/README.md) for the difference between the two\nchecks.\n\n### ESLint + @eslint/mcp\n\nFor AI assistants that don't support MCP but do support tool-calling, you can combine `eslint-plugin-sfmc` with the official `@eslint/mcp` server. Add it alongside `mcp-server-sfmc`:\n\n```json\n{\n \"servers\": {\n \"sfmc\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-server-sfmc@latest\"]\n },\n \"eslint\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@eslint/mcp@latest\"]\n }\n }\n}\n```\n\nCreate an `eslint.config.mjs` in your project root:\n\n```js\nimport sfmc from 'eslint-plugin-sfmc';\nexport default [...sfmc.configs.recommended];\n```\n\nThe `@eslint/mcp` server exposes an `eslint_lint` tool that your AI can call to run the full ESLint rule set (including all AMPscript and SSJS rules from `eslint-plugin-sfmc`) on any file.\n\n## Architecture\n\n```\nmcp-server-sfmc\n ├── sfmc-language-lsp (language intelligence core)\n │ ├── ampscript-data (AMPscript function catalog)\n │ ├── ssjs-data (SSJS function catalog)\n │ └── handlebars-data (MCN Handlebars helper catalog)\n ├── ampscript-data (direct — conversion maps, mcnSince, handlebarsEquivalent)\n ├── ssjs-data (direct — Platform.Function ↔ AMPscript mapping)\n └── handlebars-data (direct — AMPscript ↔ Handlebars conversion)\n\nvscode-sfmc-language (VS Code extension)\n └── sfmc-language-lsp (same core, bundled via esbuild)\n```\n\nBoth the VS Code extension and the MCP server share exactly the same validation, completion, hover, and lookup logic through `sfmc-language-lsp`. This means the AI assistant sees the same errors and suggestions that the editor shows.\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/JoernBerkefeld/mcp-server-sfmc/blob/main/CONTRIBUTING.md).\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n", "bytes": 51453, "sha": "77ed9c533a8bf18724a0be114c8c42f9c26919cd10f666480acb8416696c80a8", "repo_slug": "joernberkefeld/mcp-server-sfmc", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_joernberkefeld_mcp_server_sfmc_f02a10dd/readme" }