mcp-server-sfmc 1.4.0 → 1.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +134 -83
- package/ci-templates/BUGBOT.md +68 -0
- package/ci-templates/README.md +13 -12
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -24,12 +24,12 @@ For **other editors**, or if you prefer explicit configuration, use the `npx` or
|
|
|
24
24
|
|
|
25
25
|
You **do not** have to install the VS Code extension. Pick one way to run the server:
|
|
26
26
|
|
|
27
|
-
| Approach
|
|
28
|
-
|
|
29
|
-
| **`npx` (no install)**
|
|
30
|
-
| **`npm install -g mcp-server-sfmc`**
|
|
31
|
-
| **`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.
|
|
32
|
-
| **`sfmc-review-diff` (bundled CLI)**
|
|
27
|
+
| Approach | When to use it |
|
|
28
|
+
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| **`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`). |
|
|
30
|
+
| **`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. |
|
|
31
|
+
| **`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. |
|
|
32
|
+
| **`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`. |
|
|
33
33
|
|
|
34
34
|
None 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.
|
|
35
35
|
|
|
@@ -39,20 +39,20 @@ Ready-to-copy workflows (GitHub Actions, GitLab CI, Jenkins, Azure Pipelines, Bi
|
|
|
39
39
|
|
|
40
40
|
## What it gives your AI assistant
|
|
41
41
|
|
|
42
|
-
| Feature
|
|
43
|
-
|
|
44
|
-
| **Validation**
|
|
45
|
-
| **Lookup**
|
|
46
|
-
| **PR review**
|
|
47
|
-
| **Fix suggestions**
|
|
48
|
-
| **Completions**
|
|
49
|
-
| **Platform detection**
|
|
42
|
+
| Feature | Details |
|
|
43
|
+
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| **Validation** | Syntax errors, unknown functions, arity mismatches, unsupported SSJS syntax; `target: 'next'` flags MCN-incompatible functions and all SSJS |
|
|
45
|
+
| **Lookup** | Full function signatures, parameters, return types, MCN compatibility badge (API version), behavioral notes, and examples |
|
|
46
|
+
| **PR review** | Diff-aware review tool that surfaces issues in the exact lines that changed |
|
|
47
|
+
| **Fix suggestions** | Concrete, compilable replacement code; `target: 'next'` includes MCN platform issues |
|
|
48
|
+
| **Completions** | AMPscript completions (filtered to MCN-supported when `target: 'next'`); SSJS catalog (redirects to AMPscript for MCN) |
|
|
49
|
+
| **Platform detection** | `detect_sfmc_platform` checks `.mcdevrc.json` (MCE) or `sfdx-project.json` (MCN) in the project root |
|
|
50
50
|
| **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 |
|
|
51
|
-
| **MCN migration**
|
|
52
|
-
| **Code conversion**
|
|
53
|
-
| **Prompts**
|
|
54
|
-
| **Resources**
|
|
55
|
-
| **Help search**
|
|
51
|
+
| **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 |
|
|
52
|
+
| **Code conversion** | `convertSsjsToAmpscript` and `convertAmpscriptToSsjs` (tool + prompt hybrid) — rule-based conversion with AI-enhanced handling of flagged sections |
|
|
53
|
+
| **Prompts** | Guided prompts for writing AMPscript/SSJS (with MCN constraints), reviewing code, converting between the two, and rewriting for MCN |
|
|
54
|
+
| **Resources** | Full function catalogs, keyword list, unsupported ES6+ syntax list |
|
|
55
|
+
| **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) |
|
|
56
56
|
|
|
57
57
|
## Connecting AI clients
|
|
58
58
|
|
|
@@ -138,53 +138,53 @@ Then replace `"command": "npx", "args": ["-y", "mcp-server-sfmc@latest"]` with:
|
|
|
138
138
|
|
|
139
139
|
## Tools
|
|
140
140
|
|
|
141
|
-
| Tool
|
|
142
|
-
|
|
143
|
-
| `validate_ampscript`
|
|
144
|
-
| `validate_ssjs`
|
|
145
|
-
| `validate_sfmc_html`
|
|
146
|
-
| `lookup_ampscript_function` | Full signature, parameters, return type, MCN compatibility badge (API version), behavioral notes for MCN, and examples
|
|
147
|
-
| `lookup_ssjs_function`
|
|
148
|
-
| `list_ampscript_functions`
|
|
149
|
-
| `review_change`
|
|
150
|
-
| `suggest_fix`
|
|
151
|
-
| `get_ampscript_completions` | List valid completions at a given cursor position; MCN-unsupported functions marked `[MCE only]` when `target: 'next'`
|
|
152
|
-
| `get_ssjs_completions`
|
|
153
|
-
| `format_sfmc_code`
|
|
154
|
-
| `detect_sfmc_platform`
|
|
155
|
-
| `check_mcn_compatibility`
|
|
156
|
-
| `rewrite_for_mcn`
|
|
157
|
-
| `convertSsjsToAmpscript`
|
|
158
|
-
| `convertAmpscriptToSsjs`
|
|
159
|
-
| `search_help`
|
|
160
|
-
| `search_mce_help`
|
|
161
|
-
| `search_mcn_help`
|
|
141
|
+
| Tool | Description |
|
|
142
|
+
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
143
|
+
| `validate_ampscript` | Validate AMPscript code — unknown functions, arity, delimiter balance, comment syntax. `target: 'next'` flags MCN-incompatible functions. |
|
|
144
|
+
| `validate_ssjs` | Validate SSJS — ES6+ usage, missing Platform.Load, wrong API calls. `target: 'next'` flags all SSJS as unsupported. |
|
|
145
|
+
| `validate_sfmc_html` | Validate HTML with embedded AMPscript, SSJS, and GTL blocks. `target: 'next'` enables MCN validation. |
|
|
146
|
+
| `lookup_ampscript_function` | Full signature, parameters, return type, MCN compatibility badge (API version), behavioral notes for MCN, and examples |
|
|
147
|
+
| `lookup_ssjs_function` | Full signature and description for any SSJS Platform function or method |
|
|
148
|
+
| `list_ampscript_functions` | List all AMPscript functions, optionally filtered by `platform: 'next'` to return only MCN-supported functions |
|
|
149
|
+
| `review_change` | Review a unified diff — validates only added lines, maps back to diff line numbers |
|
|
150
|
+
| `suggest_fix` | Generate fix suggestions for each diagnostic in a code snippet. `target: 'next'` includes MCN fixes. |
|
|
151
|
+
| `get_ampscript_completions` | List valid completions at a given cursor position; MCN-unsupported functions marked `[MCE only]` when `target: 'next'` |
|
|
152
|
+
| `get_ssjs_completions` | List SSJS Platform API completions, optionally filtered by prefix; redirects to AMPscript completions when `target: 'next'` |
|
|
153
|
+
| `format_sfmc_code` | Apply basic formatting conventions (keyword casing, quote normalisation) |
|
|
154
|
+
| `detect_sfmc_platform` | Detect the target platform for a project — checks `.mcdevrc.json` (→ `"engagement"`) or `sfdx-project.json` (→ `"next"`) |
|
|
155
|
+
| `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`. |
|
|
156
|
+
| `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. |
|
|
157
|
+
| `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. |
|
|
158
|
+
| `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. |
|
|
159
|
+
| `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. |
|
|
160
|
+
| `search_mce_help` | Search bundled Marketing Cloud Engagement setup/ops help; use `product_focus` to target Engagement vs Next |
|
|
161
|
+
| `search_mcn_help` | Search bundled Marketing Cloud Next developer API documentation (objects, flows, segments, REST/SOAP APIs, AMPscript behavior in MCN) |
|
|
162
162
|
|
|
163
163
|
## Resources
|
|
164
164
|
|
|
165
|
-
| URI
|
|
166
|
-
|
|
167
|
-
| `sfmc://ampscript/functions`
|
|
168
|
-
| `sfmc://ssjs/functions`
|
|
169
|
-
| `sfmc://ampscript/keywords`
|
|
170
|
-
| `sfmc://ssjs/unsupported-syntax` | ES6+ features not supported in SFMC SSJS
|
|
171
|
-
| `sfmc://mce/product-context`
|
|
172
|
-
| `sfmc://mce/help-index`
|
|
173
|
-
| `sfmc://mcn/help-index`
|
|
165
|
+
| URI | Description |
|
|
166
|
+
| -------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
167
|
+
| `sfmc://ampscript/functions` | Full AMPscript function catalog with signatures |
|
|
168
|
+
| `sfmc://ssjs/functions` | Full SSJS function catalog |
|
|
169
|
+
| `sfmc://ampscript/keywords` | All AMPscript keywords |
|
|
170
|
+
| `sfmc://ssjs/unsupported-syntax` | ES6+ features not supported in SFMC SSJS |
|
|
171
|
+
| `sfmc://mce/product-context` | How **Marketing Cloud Engagement** differs from **Marketing Cloud Next** (when to use which) |
|
|
172
|
+
| `sfmc://mce/help-index` | List of bundled MCE help files and section counts per product scope |
|
|
173
|
+
| `sfmc://mcn/help-index` | List of bundled MCN developer API doc files and chunk counts |
|
|
174
174
|
|
|
175
175
|
## Prompts
|
|
176
176
|
|
|
177
177
|
Access via `/mcp.sfmc.writeAmpscript` etc. in VS Code, or via the prompts API:
|
|
178
178
|
|
|
179
|
-
| Prompt
|
|
180
|
-
|
|
181
|
-
| `writeAmpscript`
|
|
182
|
-
| `writeSsjs`
|
|
183
|
-
| `reviewSfmcCode`
|
|
184
|
-
| `rewrite_for_mcn`
|
|
185
|
-
| `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.
|
|
186
|
-
| `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.
|
|
187
|
-
| `answerMceHowTo`
|
|
179
|
+
| Prompt | Description |
|
|
180
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
181
|
+
| `writeAmpscript` | Generate AMPscript code for a described task. `target: 'next'` enforces MCN constraints (MCN-supported functions only, Java `SimpleDateFormat` patterns, no SSJS). |
|
|
182
|
+
| `writeSsjs` | Generate SSJS code for a described task. `target: 'next'` redirects to AMPscript instead (SSJS is not available in MCN). |
|
|
183
|
+
| `reviewSfmcCode` | Review AMPscript or SSJS code for bugs and best-practice violations. `target: 'next'` adds MCN compatibility checklist. |
|
|
184
|
+
| `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. |
|
|
185
|
+
| `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. |
|
|
186
|
+
| `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. |
|
|
187
|
+
| `answerMceHowTo` | Guided prompt for admin/setup questions — searches bundled help and keeps Engagement vs Next explicit |
|
|
188
188
|
|
|
189
189
|
## Migrating code to Marketing Cloud Next
|
|
190
190
|
|
|
@@ -233,10 +233,10 @@ The same hybrid pattern applies to `convertSsjsToAmpscript` and `convertAmpscrip
|
|
|
233
233
|
|
|
234
234
|
### MCN behavioral differences to watch for
|
|
235
235
|
|
|
236
|
-
| Function
|
|
237
|
-
|
|
238
|
-
| `FormatDate`
|
|
239
|
-
| `Lookup`
|
|
236
|
+
| Function | Difference |
|
|
237
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
238
|
+
| `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"` |
|
|
239
|
+
| `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. |
|
|
240
240
|
| `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. |
|
|
241
241
|
|
|
242
242
|
### CloudPages functions — not migratable
|
|
@@ -251,18 +251,18 @@ Clients that honour the MCP `instructions` field (Cursor, Claude Desktop, GitHub
|
|
|
251
251
|
|
|
252
252
|
### Quick reference: which tool or prompt to use
|
|
253
253
|
|
|
254
|
-
| Situation
|
|
255
|
-
|
|
256
|
-
| MCE admin question (classic Engagement)
|
|
257
|
-
| Marketing Cloud Next developer API question
|
|
258
|
-
| MCN operational / migration / setup question | Use `search_mce_help` with `product_focus: 'next'`, or ask naturally and the server routes it.
|
|
259
|
-
| Not sure which product
|
|
260
|
-
| Write or validate AMPscript
|
|
261
|
-
| Write or validate SSJS
|
|
262
|
-
| Check if code is MCN-ready
|
|
263
|
-
| Migrate code to Marketing Cloud Next
|
|
264
|
-
| Convert SSJS ↔ AMPscript
|
|
265
|
-
| Review a code diff
|
|
254
|
+
| Situation | What to do |
|
|
255
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
256
|
+
| 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`. |
|
|
257
|
+
| Marketing Cloud Next developer API question | The server calls `search_help` or `search_mcn_help` automatically. Or use `search_mcn_help` explicitly. |
|
|
258
|
+
| MCN operational / migration / setup question | Use `search_mce_help` with `product_focus: 'next'`, or ask naturally and the server routes it. |
|
|
259
|
+
| Not sure which product | Use `answerMceHowTo` with `assumeProduct: unsure`, or `search_help` without a `target`. |
|
|
260
|
+
| Write or validate AMPscript | Use the `writeAmpscript` prompt, or ask directly (the server auto-validates). Add `target: 'next'` for MCN. |
|
|
261
|
+
| Write or validate SSJS | Use the `writeSsjs` prompt, or ask directly. Note: SSJS is not supported in MCN. |
|
|
262
|
+
| Check if code is MCN-ready | Use `check_mcn_compatibility` with your file contents. |
|
|
263
|
+
| 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. |
|
|
264
|
+
| Convert SSJS ↔ AMPscript | Use the `convertSsjsToAmpscript` or `convertAmpscriptToSsjs` **prompt** — same hybrid pattern: tool runs first, AI handles what the rules couldn't. |
|
|
265
|
+
| Review a code diff | Use the `reviewSfmcCode` prompt or mention "review the following diff". |
|
|
266
266
|
|
|
267
267
|
### Copy-paste prompt templates
|
|
268
268
|
|
|
@@ -365,11 +365,56 @@ To rebuild both indexes in one command: `npm run bundle-all`
|
|
|
365
365
|
|
|
366
366
|
## AI code review in pull requests
|
|
367
367
|
|
|
368
|
+
### Cursor Bugbot
|
|
369
|
+
|
|
370
|
+
[Cursor Bugbot](https://cursor.com/bugbot) reviews pull requests (GitHub) and merge
|
|
371
|
+
requests (GitLab) automatically, leaves inline comments with fix suggestions, and publishes
|
|
372
|
+
a `Cursor Bugbot` check. It does not run `sfmc-review-diff` itself — you make it
|
|
373
|
+
SFMC-aware in two ways:
|
|
374
|
+
|
|
375
|
+
**1. Repository rules (`BUGBOT.md`) — all plans.** Copy
|
|
376
|
+
[`ci-templates/BUGBOT.md`](ci-templates/BUGBOT.md) to **`.cursor/BUGBOT.md`** in your repo
|
|
377
|
+
root. It tells Bugbot how to review AMPscript, SSJS, and SFMC HTML — unknown functions,
|
|
378
|
+
arity, delimiter balance, ES3-only SSJS, and optional Marketing Cloud Next migration
|
|
379
|
+
rules. Bugbot reads the root file plus any nested `.cursor/BUGBOT.md` files near changed
|
|
380
|
+
files, so you can scope stricter rules to subfolders.
|
|
381
|
+
|
|
382
|
+
**2. MCP tools (`mcp-server-sfmc`) — Team / Enterprise plans only.** Bugbot can call MCP
|
|
383
|
+
tools during a review so its findings come from the same language catalog as the editor:
|
|
384
|
+
|
|
385
|
+
1. In the [Bugbot dashboard](https://cursor.com/dashboard?tab=bugbot), enable Bugbot on
|
|
386
|
+
the repository.
|
|
387
|
+
2. Open the **MCP** configuration for Bugbot and add this server:
|
|
388
|
+
|
|
389
|
+
```json
|
|
390
|
+
{
|
|
391
|
+
"mcpServers": {
|
|
392
|
+
"sfmc": {
|
|
393
|
+
"command": "npx",
|
|
394
|
+
"args": ["-y", "mcp-server-sfmc@latest"]
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
3. Add the tools to Bugbot in the dashboard. The relevant review tools are
|
|
401
|
+
`review_change`, `validate_ampscript`, `validate_ssjs`, `validate_sfmc_html`, and
|
|
402
|
+
`suggest_fix`. The `BUGBOT.md` rules above instruct Bugbot when to call them.
|
|
403
|
+
|
|
404
|
+
> Branch protection: require the **`Cursor Bugbot`** check to make sure a review runs
|
|
405
|
+
> before merge. Findings default to a `neutral` conclusion; enable
|
|
406
|
+
> fail-on-unresolved-issues in the dashboard (where available) if you want findings to
|
|
407
|
+
> produce a failing check.
|
|
408
|
+
|
|
409
|
+
**Run it locally first.** In Cursor 3.7+, run `/review-bugbot` on your branch before you
|
|
410
|
+
push; Bugbot reuses that review on the PR/MR with the same diff, avoiding a duplicate run.
|
|
411
|
+
|
|
368
412
|
### GitHub Copilot (cloud agent)
|
|
369
413
|
|
|
370
414
|
The `.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.
|
|
371
415
|
|
|
372
416
|
To enable it in your own repository:
|
|
417
|
+
|
|
373
418
|
1. Copy `.github/agents/sfmc-reviewer.agent.md` to your repo.
|
|
374
419
|
2. In your GitHub repo settings → **Copilot → Cloud agent → MCP configuration**, add:
|
|
375
420
|
|
|
@@ -401,17 +446,23 @@ Copy `.github/copilot-instructions.md` from this repo to your project. GitHub Co
|
|
|
401
446
|
|
|
402
447
|
### CI linting (deterministic checks)
|
|
403
448
|
|
|
404
|
-
For deterministic, blocking CI validation, use the
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
|
410
|
-
|
|
|
411
|
-
|
|
|
449
|
+
For deterministic, blocking CI validation, use the templates provided in `ci-templates/`.
|
|
450
|
+
Each one runs **two checks** on every PR/MR: `eslint-plugin-sfmc` on changed files, and
|
|
451
|
+
`sfmc-review-diff` (this package) on the unified diff — so a finding fails the job
|
|
452
|
+
regardless of which AI reviewer (Bugbot, Copilot, Duo) is also enabled.
|
|
453
|
+
|
|
454
|
+
| Platform | File |
|
|
455
|
+
| ------------------- | ------------------------------------------------------------------------------ |
|
|
456
|
+
| GitHub Actions | [`ci-templates/github-action.yml`](ci-templates/github-action.yml) |
|
|
457
|
+
| GitLab CI | [`ci-templates/gitlab-ci.yml`](ci-templates/gitlab-ci.yml) |
|
|
458
|
+
| Jenkins | [`ci-templates/Jenkinsfile`](ci-templates/Jenkinsfile) |
|
|
459
|
+
| Azure DevOps | [`ci-templates/azure-pipelines.yml`](ci-templates/azure-pipelines.yml) |
|
|
412
460
|
| Bitbucket Pipelines | [`ci-templates/bitbucket-pipelines.yml`](ci-templates/bitbucket-pipelines.yml) |
|
|
413
461
|
|
|
414
|
-
|
|
462
|
+
The ESLint job posts lint results as PR/MR comments; the `sfmc-review-diff` job exits
|
|
463
|
+
non-zero on `ERROR` diagnostics by default (`--fail-on warning|info` to be stricter).
|
|
464
|
+
See [`ci-templates/README.md`](ci-templates/README.md) for the difference between the two
|
|
465
|
+
checks.
|
|
415
466
|
|
|
416
467
|
### ESLint + @eslint/mcp
|
|
417
468
|
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# SFMC Bugbot Rules
|
|
2
|
+
|
|
3
|
+
Copy this file into your repository as `.cursor/BUGBOT.md` (project root). Cursor Bugbot
|
|
4
|
+
always reads the root `.cursor/BUGBOT.md` and any nested `.cursor/BUGBOT.md` files found
|
|
5
|
+
while traversing upward from changed files. These rules tell Bugbot how to review
|
|
6
|
+
Salesforce Marketing Cloud code in your pull/merge requests.
|
|
7
|
+
|
|
8
|
+
> Bugbot rules are guidance, not a parser. For deterministic, blocking validation, also
|
|
9
|
+
> run `eslint-plugin-sfmc` and `sfmc-review-diff` in CI (see the templates in this folder).
|
|
10
|
+
> If your team has the MCP integration enabled (Team/Enterprise plan), Bugbot can call the
|
|
11
|
+
> `mcp-server-sfmc` tools named below directly during a review.
|
|
12
|
+
|
|
13
|
+
## Scope
|
|
14
|
+
|
|
15
|
+
These rules apply to files that contain SFMC server-side code:
|
|
16
|
+
|
|
17
|
+
- AMPscript: `*.amp`, `*.ampscript`, and `*.html` with `%%[ ... ]%%` / `%%=...=%%` blocks
|
|
18
|
+
- SSJS: `*.ssjs` and `<script runat="server">` blocks in `*.html`
|
|
19
|
+
- GTL (Guide Template Language) blocks in `*.html`
|
|
20
|
+
|
|
21
|
+
## Required behaviour
|
|
22
|
+
|
|
23
|
+
- When a diff touches any in-scope file, review the **added/changed lines** for SFMC
|
|
24
|
+
correctness before leaving comments.
|
|
25
|
+
- If the `mcp-server-sfmc` MCP tools are available, call `review_change` on the diff, or
|
|
26
|
+
`validate_ampscript` / `validate_ssjs` / `validate_sfmc_html` on the changed file, and
|
|
27
|
+
base your findings on the returned diagnostics.
|
|
28
|
+
- Treat each `ERROR` diagnostic as a **blocking** bug; treat `WARNING` / `INFO` as
|
|
29
|
+
**non-blocking** suggestions.
|
|
30
|
+
- When you flag an issue, suggest the corrected line inline so the author can apply it.
|
|
31
|
+
|
|
32
|
+
## AMPscript standards
|
|
33
|
+
|
|
34
|
+
- Flag calls to unknown AMPscript functions as blocking bugs (typos, wrong casing of a
|
|
35
|
+
real function are common causes).
|
|
36
|
+
- Flag wrong argument counts (arity) for known functions as blocking bugs.
|
|
37
|
+
- Flag unbalanced AMPscript delimiters — every `%%[` must have a matching `]%%`, and
|
|
38
|
+
inline `%%= ... =%%` must be closed — as blocking bugs.
|
|
39
|
+
- Flag malformed AMPscript comments (`/* ... */` must be balanced) as blocking bugs.
|
|
40
|
+
- Suggest consistent keyword casing and quote style for new code.
|
|
41
|
+
|
|
42
|
+
## SSJS standards
|
|
43
|
+
|
|
44
|
+
- SFMC SSJS runs on an ES3-era engine. Flag ES5+/ES6+ syntax as blocking bugs, including:
|
|
45
|
+
`let` / `const`, arrow functions, template literals, `for...of`, `Array.prototype`
|
|
46
|
+
iterators (`forEach`, `map`, `filter`, `reduce`), `JSON.parse` / `JSON.stringify`, and
|
|
47
|
+
`String.prototype.trim`. Use the Platform equivalents instead
|
|
48
|
+
(`Platform.Function.ParseJSON`, `Platform.Function.Stringify`, `Platform.Function.Trim`).
|
|
49
|
+
- Flag SSJS that calls Platform/Core API without a preceding
|
|
50
|
+
`Platform.Load("Core", "1.1.1")` (or equivalent) as a warning.
|
|
51
|
+
- Flag direct use of undefined SSJS objects or misspelled `Platform.Function.*` names as
|
|
52
|
+
blocking bugs.
|
|
53
|
+
|
|
54
|
+
## Marketing Cloud Next (MCN) migration — optional
|
|
55
|
+
|
|
56
|
+
Enable this section only for repositories that target Marketing Cloud Next (presence of a
|
|
57
|
+
`sfdx-project.json` at the repo root, or absence of `.mcdevrc.json`):
|
|
58
|
+
|
|
59
|
+
- Treat SSJS as **unsupported** in MCN — flag any new SSJS block as a blocking bug and
|
|
60
|
+
suggest an AMPscript rewrite.
|
|
61
|
+
- Flag AMPscript functions that have no MCN equivalent (MCN supports a subset of AMPscript
|
|
62
|
+
functions) as blocking bugs. When the MCP tools are available, call the validation tools
|
|
63
|
+
with `target: "next"` to identify them.
|
|
64
|
+
- Flag `.NET`-style `FormatDate` patterns; MCN uses Java `SimpleDateFormat` patterns.
|
|
65
|
+
- Flag `Lookup()` calls with an odd number of search arguments — MCN requires
|
|
66
|
+
column/value pairs.
|
|
67
|
+
- Flag CloudPages-only functions (`CloudPagesURL`, `RequestParameter`, `QueryParameter`,
|
|
68
|
+
`Redirect`, `MicrositeURL`) as not migratable.
|
package/ci-templates/README.md
CHANGED
|
@@ -4,9 +4,9 @@ Copy these files into your own repository and adjust branch names, Node version,
|
|
|
4
4
|
|
|
5
5
|
## Two complementary checks
|
|
6
6
|
|
|
7
|
-
| Mechanism
|
|
8
|
-
|
|
9
|
-
| **ESLint** (`eslint-plugin-sfmc`)
|
|
7
|
+
| Mechanism | What it does |
|
|
8
|
+
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
9
|
+
| **ESLint** (`eslint-plugin-sfmc`) | Lints **changed files** matching `*.amp`, `*.ssjs`, `*.html` (and embedded rules for HTML). File-level rules (unknown functions, arity, ES6 in SSJS, etc.). |
|
|
10
10
|
| **`sfmc-review-diff`** (this package, CLI) | Pipes a **unified `git diff`** into the MCP tool `review_change`, which validates **only added lines** using the same language catalog as the MCP server. Fails the job on `ERROR` diagnostics by default (`--fail-on` can include warnings or infos). |
|
|
11
11
|
|
|
12
12
|
You can keep **both** jobs in CI, or drop one if you only want file-based linting or only diff-based review.
|
|
@@ -15,19 +15,20 @@ You can keep **both** jobs in CI, or drop one if you only want file-based lintin
|
|
|
15
15
|
|
|
16
16
|
## Files in this folder
|
|
17
17
|
|
|
18
|
-
| File
|
|
19
|
-
|
|
20
|
-
| [github-action.yml](./github-action.yml)
|
|
21
|
-
| [gitlab-ci.yml](./gitlab-ci.yml)
|
|
22
|
-
| [Jenkinsfile](./Jenkinsfile)
|
|
23
|
-
| [azure-pipelines.yml](./azure-pipelines.yml)
|
|
24
|
-
| [bitbucket-pipelines.yml](./bitbucket-pipelines.yml) | Bitbucket Pipelines | yes
|
|
25
|
-
| [eslint.config.mjs](./eslint.config.mjs)
|
|
18
|
+
| File | Platform | ESLint | `sfmc-review-diff` |
|
|
19
|
+
| ---------------------------------------------------- | ------------------- | ------------------ | ------------------ |
|
|
20
|
+
| [github-action.yml](./github-action.yml) | GitHub Actions | yes | yes |
|
|
21
|
+
| [gitlab-ci.yml](./gitlab-ci.yml) | GitLab CI | yes | yes |
|
|
22
|
+
| [Jenkinsfile](./Jenkinsfile) | Jenkins | yes | yes |
|
|
23
|
+
| [azure-pipelines.yml](./azure-pipelines.yml) | Azure Pipelines | yes | yes |
|
|
24
|
+
| [bitbucket-pipelines.yml](./bitbucket-pipelines.yml) | Bitbucket Pipelines | yes | yes |
|
|
25
|
+
| [eslint.config.mjs](./eslint.config.mjs) | (reference) | shared flat config | — |
|
|
26
26
|
|
|
27
27
|
## AI review instructions (not CI)
|
|
28
28
|
|
|
29
|
-
These files guide **GitLab Duo** / **GitHub Copilot** style review text; they do **not** run `sfmc-review-diff`:
|
|
29
|
+
These files guide **Cursor Bugbot** / **GitLab Duo** / **GitHub Copilot** style review text; they do **not** run `sfmc-review-diff`:
|
|
30
30
|
|
|
31
|
+
- [BUGBOT.md](./BUGBOT.md) — copy to `.cursor/BUGBOT.md` in your repo root to make [Cursor Bugbot](https://cursor.com/bugbot) review AMPscript / SSJS / SFMC HTML. On Team/Enterprise plans, Bugbot can also call the `mcp-server-sfmc` MCP tools (`review_change`, `validate_*`, `suggest_fix`).
|
|
31
32
|
- [gitlab-duo-review-instructions.md](./gitlab-duo-review-instructions.md) — place content in `.gitlab/duo/mr-review-instructions.yaml` per GitLab docs (YAML format), not as a raw paste of this file.
|
|
32
33
|
- [github-copilot-review-instructions.md](./github-copilot-review-instructions.md) — Copilot / agent instructions; MCP blocks belong in client config, not in Actions YAML.
|
|
33
34
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mcp-server-sfmc",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.1",
|
|
4
4
|
"mcpName": "io.github.JoernBerkefeld/mcp-server-sfmc",
|
|
5
5
|
"description": "SFMC AMPscript/SSJS/GTL tools + searchable MCE and MCN developer docs, with full MCN platform support.",
|
|
6
6
|
"author": "Jörn Berkefeld",
|
|
@@ -55,13 +55,14 @@
|
|
|
55
55
|
"clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
|
|
56
56
|
"lint": "eslint .",
|
|
57
57
|
"lint:fix": "eslint --fix .",
|
|
58
|
+
"version": "node -e \"const fs=require('fs'),p=require('./package.json'),s=JSON.parse(fs.readFileSync('server.json','utf8'));s.version=p.version;s.packages[0].version=p.version;fs.writeFileSync('server.json',JSON.stringify(s,null,4)+'\\n','utf8');\" && git add server.json",
|
|
58
59
|
"prepare": "husky || true",
|
|
59
60
|
"format": "prettier --write .",
|
|
60
61
|
"format:check": "prettier --check ."
|
|
61
62
|
},
|
|
62
63
|
"dependencies": {
|
|
63
64
|
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
64
|
-
"sfmc-language-lsp": "^1.
|
|
65
|
+
"sfmc-language-lsp": "^1.5.0",
|
|
65
66
|
"ssjs-data": "^0.5.0"
|
|
66
67
|
},
|
|
67
68
|
"engines": {
|