mcp-server-sfmc

# 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. 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, and provides a **migration toolkit** to analyze and rewrite code for MCN.

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).

## VS Code MCP Server Gallery (`@mcp`)

This 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.

The 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.

After 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:

`curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.JoernBerkefeld/mcp-server-sfmc"`

## VS Code without manual MCP config

If 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.

For **other editors**, or if you prefer explicit configuration, use the `npx` or install options below.

## Using this package without the VS Code extension

You **do not** have to install the VS Code extension. Pick one way to run the server:

| Approach | When to use it |
|---|---|
| **`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`). |
| **`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. |
| **`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. |
| **`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`. |

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.

## CI templates and `sfmc-review-diff`

Ready-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.

## What it gives your AI assistant

| Feature | Details |
|---|---|
| **Validation** | Syntax errors, unknown functions, arity mismatches, unsupported SSJS syntax; `target: 'next'` flags MCN-incompatible functions and all SSJS |
| **Lookup** | Full function signatures, parameters, return types, MCN compatibility badge (API version), behavioral notes, and examples |
| **PR review** | Diff-aware review tool that surfaces issues in the exact lines that changed |
| **Fix suggestions** | Concrete, compilable replacement code; `target: 'next'` includes MCN platform issues |
| **Completions** | AMPscript completions (filtered to MCN-supported when `target: 'next'`); SSJS catalog (redirects to AMPscript for MCN) |
| **Platform detection** | `detect_sfmc_platform` checks `.mcdevrc.json` (MCE) or `sfdx-project.json` (MCN) in the project root |
| **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 |
| **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 |
| **Code conversion** | `convertSsjsToAmpscript` and `convertAmpscriptToSsjs` (tool + prompt hybrid) — rule-based conversion with AI-enhanced handling of flagged sections |
| **Prompts** | Guided prompts for writing AMPscript/SSJS (with MCN constraints), reviewing code, converting between the two, and rewriting for MCN |
| **Resources** | Full function catalogs, keyword list, unsupported ES6+ syntax list |
| **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) |

## Connecting AI clients

### VS Code (1.99+) + GitHub Copilot — manual `mcp.json`

If 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):

```json
{
  "servers": {
    "sfmc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-sfmc@latest"]
    }
  }
}
```

Open 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.

### Cursor

Add to your Cursor settings (`~/.cursor/mcp.json` or project-level `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "sfmc": {
      "command": "npx",
      "args": ["-y", "mcp-server-sfmc@latest"]
    }
  }
}
```

Restart Cursor. The tools are available in Agent mode.

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "sfmc": {
      "command": "npx",
      "args": ["-y", "mcp-server-sfmc@latest"]
    }
  }
}
```

Restart Claude Desktop.

### Windsurf

Add to your Windsurf MCP settings (`~/.codeium/windsurf/mcp_config.json`):

```json
{
  "mcpServers": {
    "sfmc": {
      "command": "npx",
      "args": ["-y", "mcp-server-sfmc@latest"]
    }
  }
}
```

### Local install (faster startup than npx)

```bash
npm install -g mcp-server-sfmc
```

Then replace `"command": "npx", "args": ["-y", "mcp-server-sfmc@latest"]` with:

```json
"command": "mcp-server-sfmc",
"args": []
```

## Tools

| Tool | Description |
|---|---|
| `validate_ampscript` | Validate AMPscript code — unknown functions, arity, delimiter balance, comment syntax. `target: 'next'` flags MCN-incompatible functions. |
| `validate_ssjs` | Validate SSJS — ES6+ usage, missing Platform.Load, wrong API calls. `target: 'next'` flags all SSJS as unsupported. |
| `validate_sfmc_html` | Validate HTML with embedded AMPscript, SSJS, and GTL blocks. `target: 'next'` enables MCN validation. |
| `lookup_ampscript_function` | Full signature, parameters, return type, MCN compatibility badge (API version), behavioral notes for MCN, and examples |
| `lookup_ssjs_function` | Full signature and description for any SSJS Platform function or method |
| `list_ampscript_functions` | List all AMPscript functions, optionally filtered by `platform: 'next'` to return only MCN-supported functions |
| `review_change` | Review a unified diff — validates only added lines, maps back to diff line numbers |
| `suggest_fix` | Generate fix suggestions for each diagnostic in a code snippet. `target: 'next'` includes MCN fixes. |
| `get_ampscript_completions` | List valid completions at a given cursor position; MCN-unsupported functions marked `[MCE only]` when `target: 'next'` |
| `get_ssjs_completions` | List SSJS Platform API completions, optionally filtered by prefix; redirects to AMPscript completions when `target: 'next'` |
| `format_sfmc_code` | Apply basic formatting conventions (keyword casing, quote normalisation) |
| `detect_sfmc_platform` | Detect the target platform for a project — checks `.mcdevrc.json` (→ `"engagement"`) or `sfdx-project.json` (→ `"next"`) |
| `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`. |
| `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 `