mcp-server-sfmc 0.1.7 → 0.1.9

package/README.md

@@ -1,6 +1,6 @@
 # mcp-server-sfmc
 
-MCP server providing Salesforce Marketing Cloud language intelligence — AMPscript, SSJS, and GTL — as Model Context Protocol tools, resources, and prompts for AI-assisted development and code review.
+MCP server providing Salesforce Marketing Cloud language intelligence — AMPscript, SSJS, and GTL — as Model Context Protocol tools, resources, and prompts for AI-assisted development and code review. It also ships a **searchable index** of mirrored Salesforce Help for **Marketing Cloud Engagement** administration and setup (business units, Journey Builder, Automation Studio, tenants, and similar topics), with explicit scoping vs **Marketing Cloud Next** (a separate product).
 
 Built 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).
 
@@ -43,6 +43,7 @@ None of these replace the VS Code extension for **editing** (syntax, LSP, snippe
 | **Completions** | AMPscript function/keyword completions, SSJS Platform API catalog |
 | **Prompts** | Guided prompts for writing AMPscript, SSJS, reviewing code, and converting between the two |
 | **Resources** | Full function catalogs, keyword list, unsupported ES6+ syntax list |
+| **MCE help search** | Bundled excerpts from local Help mirrors (`docs/help.salesforce/mce`) with Engagement vs Next labeling |
 
 ## Quick start
 
@@ -140,6 +141,7 @@ Then replace `"command": "npx", "args": ["-y", "mcp-server-sfmc@latest"]` with:
 | `get_ampscript_completions` | List valid completions at a given cursor position in AMPscript |
 | `get_ssjs_completions` | List SSJS Platform API completions, optionally filtered by prefix |
 | `format_sfmc_code` | Apply basic formatting conventions (keyword casing, quote normalisation) |
+| `search_mce_help` | Search bundled Marketing Cloud setup/ops help; use `product_focus` to target **Engagement** vs **Next** |
 
 ## Resources
 
@@ -149,6 +151,8 @@ Then replace `"command": "npx", "args": ["-y", "mcp-server-sfmc@latest"]` with:
 | `sfmc://ssjs/functions` | Full SSJS function catalog |
 | `sfmc://ampscript/keywords` | All AMPscript keywords |
 | `sfmc://ssjs/unsupported-syntax` | ES6+ features not supported in SFMC SSJS |
+| `sfmc://mce/product-context` | How **Marketing Cloud Engagement** differs from **Marketing Cloud Next** (when to use which) |
+| `sfmc://mce/help-index` | List of bundled help files and section counts per product scope |
 
 ## Prompts
 
@@ -160,6 +164,90 @@ Access via `/mcp.sfmc.writeAmpscript` etc. in VS Code, or via the prompts API:
 | `writeSsjs` | Generate SSJS code for a described task |
 | `reviewSfmcCode` | Review AMPscript or SSJS code for bugs and best-practice violations |
 | `convertAmpscriptToSsjs` | Convert AMPscript code to equivalent SSJS |
+| `answerMceHowTo` | Guided prompt for admin/setup questions — searches bundled help and keeps Engagement vs Next explicit |
+
+## Writing effective prompts
+
+### Automatic tool use
+
+Clients that honour the MCP `instructions` field (Cursor, Claude Desktop, GitHub Copilot Agent mode) will call `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.
+
+### Quick reference: which tool or prompt to use
+
+| Situation | What to do |
+|---|---|
+| MCE admin question (classic Engagement) | Ask naturally; the server will call `search_mce_help` for you. Or use the `answerMceHowTo` prompt with `assumeProduct: engagement`. |
+| Marketing Cloud Next question | Use `answerMceHowTo` with `assumeProduct: next`, or add "for Marketing Cloud Next" to your question. |
+| Not sure which product | Use `answerMceHowTo` with `assumeProduct: unsure`, or add "check both Engagement and Next" to your question. |
+| Write or validate AMPscript | Use the `writeAmpscript` prompt, or ask directly (the server auto-validates). |
+| Write or validate SSJS | Use the `writeSsjs` prompt, or ask directly. |
+| Review a code diff | Use the `reviewSfmcCode` prompt or mention "review the following diff". |
+
+### Copy-paste prompt templates
+
+#### Classic Engagement admin (most common)
+
+```
+Search the Marketing Cloud Engagement help (product_focus: engagement) and tell me:
+<your question here>
+
+Cite which product version your steps apply to and note if the bundled docs are incomplete.
+```
+
+#### Marketing Cloud Next
+
+```
+Search the Marketing Cloud Next help (product_focus: next) and tell me:
+<your question here>
+
+Confirm the steps apply to Marketing Cloud Next, not classic Engagement.
+```
+
+#### Unknown product / migration question
+
+```
+Search both Marketing Cloud Engagement and Next help (product_focus: any) and tell me:
+<your question here>
+
+Separate the steps for classic Engagement vs Marketing Cloud Next clearly.
+```
+
+#### Explicit use of the answerMceHowTo prompt
+
+In clients that support MCP prompts (e.g. VS Code with the `/mcp.sfmc.answerMceHowTo` command):
+
+```
+/mcp.sfmc.answerMceHowTo
+  question: "How do I create a child business unit and assign it a sender profile?"
+  assumeProduct: engagement
+```
+
+#### Combining MCE admin with code
+
+```
+1. Use search_mce_help (product_focus: engagement) to find the correct Journey Builder entry event
+   configuration steps, then
+2. Write the AMPscript snippet that reads the data extension row inside the journey email.
+```
+
+### What to expect from the AI
+
+- The AI cites the product scope (Engagement or Next) in every answer.
+- If the bundled excerpts do not cover the question fully, the AI says so and suggests verifying in the live Salesforce Help.
+- Function signatures (AMPscript / SSJS) are always sourced from the language catalog, not from training data.
+
+## Refresh bundled Marketing Cloud Engagement help
+
+The published npm package includes `bundled/mce-help/chunks.json`, built from a checkout that contains the mirrored Help tree at `docs/help.salesforce/mce` (for example in this monorepo). To regenerate after updating those docs:
+
+```bash
+cd mcp-server-sfmc
+npm run bundle-mce-help
+npm run build
+npm test
+```
+
+Override the source path: `MCE_HELP_DOCS=/absolute/path/to/mce npm run bundle-mce-help`
 
 ## AI code review in pull requests