mcp-server-sfmc

mcp-server-sfmc

提供 Salesforce Marketing Cloud 语言智能的 MCP 服务——AMPscript、SSJS、GTL 和 Marketing Cloud Next (MCN) Handlebars——作为 Model Context Protocol 工具、资源和提示词，用于 AI 辅助开发和代码审查。提供两个可搜索的文档索引：MCE 帮助文档（Salesforce Help 中有关 Marketing Cloud Engagement 管理和设置的内容）和 MCN 开发者文档（Marketing Cloud Next REST API 和开发者参考）。全面支持 Marketing Cloud Next (MCN) 平台：自动检测项目面向 MCE 还是 MCN，将补全和验证限制为 MCN 支持的函数，将 SSJS 标记为 MCN 不支持，在悬停提示和诊断中呈现 MCN 的行为差异，验证 MCN Handlebars 模板，并提供 迁移工具包来分析代码并将其改写为适用于 MCN 的代码——包括 AMPscript ↔ Handlebars 和 SSJS → Handlebars 转换。

基于 sfmc-language-lsp 构建，该引擎也为 SFMC Language Service VS Code 扩展提供支持。

共享诊断迁移

sfmc-language-lsp 4.0.0 将共享验证器代码改为规范的 sfmc/... ID，并在命名空间信封中保留快速修复变体和原始负载。请参阅 LSP 迁移和规则文档。文档 URL 由 LSP 版本管理，而非此 MCP 软件包。

使用者回归覆盖会检查规范的 SSJS 诊断、不同的 polyfill／替换负载以及重叠抑制。这不会新增 MCP 工具，也不保证每个工具响应都会公开原始 LSP 诊断。

版本 2.10.0 采用了 npm 中的 ampscript-data: ^4.2.0 和 sfmc-language-lsp: ^4.2.0。此次 Winter ’27 (API 68) 目录更新使当前 AMPscript 和共享语言服务元数据可供 MCP 客户端使用。MCP 验证和审查输出会继续格式化位置、严重性和消息，而不会公开原始 LSP 代码或信封。

VS Code MCP 服务库（@mcp）

此软件包已作为 io.github.JoernBerkefeld/mcp-server-sfmc 注册到官方 MCP 注册表，因此在扩展视图中使用 @mcp 筛选器时，它可以显示在 Visual Studio Code 中（请参阅发布快速入门）。如果服务库未显示，请启用 chat.mcp.gallery.enabled。

注册表仅存储元数据；该服务仍通过 stdio 在本地运行（例如 npx -y mcp-server-sfmc@latest）。这与 @contribute:mcp 不同，后者会列出提供 MCP 定义的 VS Code 扩展——如需使用该方式，请使用 SFMC Language Service。

发布元数据后（请参阅发布 MCP 服务或发布工作流），可通过以下命令确认条目：

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

无需手动配置 MCP 的 VS Code

如果你使用 SFMC Language Service 扩展（1.101+），它会注册此 MCP 服务，以便在 VS Code 中发现——通常不需要为此修改 .vscode/mcp.json 或运行 npm install；服务启动时，VS Code 仍会通过 npx 启动已发布的软件包。

对于其他编辑器，或如果你更倾向于显式配置，请使用下方的 npx 或安装选项。

不使用 VS Code 扩展时如何使用此软件包

你无需安装 VS Code 扩展。选择一种方式来运行服务：

方式	适用场景
npx（无需安装）	以下示例中的默认方式。按需运行 npm 上最新发布的版本；首次运行时可能会下载软件包。需要 Node.js 和 npm（npm 提供 npx）。
npm install -g mcp-server-sfmc	与 npx 使用相同的 CLI，但软件包会保留在磁盘上，因此启动更快；你可以在 MCP 配置中设置 "command": "mcp-server-sfmc"，并将 args 留空。
在项目中运行 npm install mcp-server-sfmc	在该文件夹的 node_modules 中保留一个固定版本——将 MCP 配置指向 npx mcp-server-sfmc 并将 cwd 设为该项目，或直接运行 ./node_modules/.bin/mcp-server-sfmc。
sfmc-review-diff（捆绑的 CLI）	用于CI：启动此 MCP 服务，对统一差异（stdin 或文件）调用 review_change，默认在遇到 ERROR 时以非零状态码退出。在任务中安装该软件包，然后例如运行 git diff base...HEAD | npx sfmc-review-diff。

这些方式都无法取代 VS Code 扩展的编辑功能（语法、LSP、代码片段）；它们只会向支持 Model Context Protocol 的工具提供 MCP 服务。

CI 模板和 sfmc-review-diff

可直接复制的工作流（GitHub Actions、GitLab CI、Jenkins、Azure Pipelines、Bitbucket Pipelines）位于 ci-templates/ 下。它们会对已更改的文件运行 eslint-plugin-sfmc，并对 PR/MR 的统一差异运行 sfmc-review-diff。每个文件的作用以及两项检查的区别，请参阅 ci-templates/README.md。

它能为你的 AI 助手提供什么

功能	详情
验证	语法错误、未知函数、参数数量不匹配、不支持的 SSJS 语法；target: 'next' 会标记与 MCN 不兼容的函数和所有 SSJS；validate_handlebars 会检查 MCN Handlebars 助手名称、参数数量、代码块是否平衡以及不支持的结构
查询	完整的函数签名、参数、返回类型、MCN 兼容性标记（API 版本）、行为说明和示例
PR 审查	可感知差异的审查工具，会指出确切变更行中的问题
修复建议	具体且可编译的替换代码；target: 'next' 会包含 MCN 平台问题
代码补全	AMPscript 补全（当 target: 'next' 时会筛选为 MCN 支持的内容）；SSJS 目录（针对 MCN 会转向 AMPscript）
平台检测	detect_sfmc_platform 会检查项目根目录中的 .mcdevrc.json（MCE）或 sfdx-project.json（MCN）
MCN 兼容性分析	check_mcn_compatibility 会分析文件以评估其是否已为 MCN 做好准备——按函数分类（支持／需审查／不支持）、SSJS 代码块迁移难度以及执行摘要
MCN 迁移	rewrite_for_mcn（工具 + 提示词）会以确定性方式重写 AMPscript，并将可转换的 SSJS 转为 AMPscript 以用于 MCN，然后对其余需要手动重写的部分应用 AI 推理
代码转换	convertSsjsToAmpscript 和 convertAmpscriptToSsjs（工具 + 提示词混合模式）——基于规则进行转换，并通过 AI 增强对已标记部分的处理
MCN Handlebars	lookup_handlebars_helper、list_handlebars_helpers、get_handlebars_completions 和 write_handlebars（编写）由 handlebars-data 目录提供支持
Handlebars 转换	convertAmpscriptToHandlebars、convertHandlebarsToAmpscript 和 convertSsjsToHandlebars（工具 + 提示词混合模式）——由 ampscript-data 中的 handlebarsEquivalent／handlebarsExact 数据驱动
提示词	用于编写 AMPscript／SSJS／Handlebars（包含 MCN 限制）、审查代码、在语言之间转换以及为 MCN 重写的引导式提示词
资源	完整的函数目录、关键字列表、不支持的 ES6+ 语法列表、MCN Handlebars 助手和绑定目录
帮助搜索	search_help（统一搜索，根据项目根目录自动检测 MCE 或 MCN）；search_mce_help（MCE 帮助，7 个产品范围）；search_mcn_help（MCN 开发者 API 参考）

混合 HTML 验证边界

从版本 2.10.1 开始，validate_sfmc_html 会验证嵌入的 AMPscript/GTL，并且只对实际的服务器端 JavaScript 代码块（runat="server"，不包括 AMPscript 脚本代码块）应用 SSJS 检查。浏览器脚本和非 JavaScript 脚本数据不会发送给 SSJS 验证器。服务器端诊断会保留在原始 HTML 中的位置，浏览器声明、Core 加载或 polyfill 不会屏蔽服务器端警告。仅仅因为 target 为 'next'，不含服务器端 JavaScript 的 HTML 不会收到 SSJS 不兼容错误。

此工具不会验证浏览器 JavaScript，也不会提供 DOM/类型诊断。独立的 validate_ssjs 工具会继续按照现有的目标平台行为验证原始 SSJS。

此边界使用 sfmc-language-lsp 4.3.1 或更高版本中发布的 validateMixedDocumentSsjs API。版本 2.10.1 将依赖版本下限提高到 ^4.3.1；发布验证使用仅从注册表安装的干净环境。

连接 AI 客户端

VS Code（1.99+）+ GitHub Copilot — 手动配置 mcp.json

如果你没有使用 SFMC Language Service 扩展内置的 MCP 注册功能，请在项目中添加 .vscode/mcp.json 文件（或从此仓库复制）：

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

在 VS Code 中打开该文件——顶部会出现 Start 按钮。点击它即可启动服务。在 Agent 模式下打开 GitHub Copilot Chat，SFMC 工具便会自动显示。

Cursor

将以下内容添加到 Cursor 设置中（~/.cursor/mcp.json 或项目级 .cursor/mcp.json）：

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

重启 Cursor。工具可在 Agent 模式下使用。

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

重启 Claude Desktop。

Windsurf

将以下内容添加到 Windsurf MCP 设置中（~/.codeium/windsurf/mcp_config.json）：

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

本地安装（比 npx 启动更快）

npm install -g mcp-server-sfmc

然后将 "command": "npx", "args": ["-y", "mcp-server-sfmc@latest"] 替换为：

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

工具

工具	描述
validate_ampscript	验证 AMPscript 代码——未知函数、参数数量、分隔符匹配情况、注释语法。target: 'next' 会标记与 MCN 不兼容的函数。
validate_ssjs	验证 SSJS——ES6+ 用法、缺少 Platform.Load、错误的 API 调用。target: 'next' 会将所有 SSJS 标记为不受支持。
validate_sfmc_html	验证包含嵌入式 AMPscript、SSJS 和 GTL 代码块的 HTML。target: 'next' 会启用 MCN 验证。
lookup_ampscript_function	完整签名、参数、返回类型、MCN 兼容性徽标（API 版本）、MCN 行为说明和示例
lookup_ssjs_function	任意 SSJS Platform 函数或方法的完整签名和说明
list_ampscript_functions	列出所有 AMPscript 函数；可选通过 platform: 'next' 筛选，仅返回 MCN 支持的函数
review_change	审查统一差异——仅验证新增行，并映射回差异中的行号
suggest_fix	为代码片段中的每条诊断生成修复建议。target: 'next' 会包含 MCN 修复建议。
get_ampscript_completions	列出给定光标位置的有效补全项；当 target: 'next' 时，不受 MCN 支持的函数会标记为 [MCE only]
get_ssjs_completions	列出 SSJS Platform API 补全项，可选按前缀筛选；当 target: 'next' 时，转而提供 AMPscript 补全项
format_sfmc_code	应用基本格式规范（关键字大小写、引号规范化）
detect_sfmc_platform	检测项目的目标平台——检查 .mcdevrc.json（→ "engagement"）或 sfdx-project.json（→ "next"）
check_mcn_compatibility	分析一个或多个 AMPscript/HTML 文件是否满足 MCN 就绪要求。返回每个函数的分类、SSJS 代码块迁移难度，以及包含整体迁移工作量的执行摘要。在运行 rewrite_for_mcn 前先运行此工具。
rewrite_for_mcn	确定性 MCN 重写引擎：修正 .NET → Java 格式字符串、移除 StringToDate 包装器、将可转换的 SSJS 转换为 AMPscript、标记不受支持的函数，并将其余内容注释为 MANUAL_REWRITE_REQUIRED。交互使用时优先选择 rewrite_for_mcn 提示词——它会先调用此工具，再对已标记的部分应用 AI 推理。仅在流水线中需要结构化 JSON 输出时直接使用此工具。
convertSsjsToAmpscript	基于规则的 SSJS → AMPscript 转换引擎：将 Platform.Function.* 转为 AMPscript 等效项，并转换变量/请求访问和控制流。将 JavaScript 原生结构标记为 MANUAL_REWRITE_REQUIRED。交互使用时优先选择 convertSsjsToAmpscript 提示词。
convertAmpscriptToSsjs	基于规则的 AMPscript → SSJS 转换引擎：转换变量、控制流和函数调用。将仅限 AMPscript 的结构标记为 MANUAL_REWRITE_REQUIRED。交互使用时优先选择 convertAmpscriptToSsjs 提示词。
validate_handlebars	验证 MCN Handlebars 模板代码——辅助函数名称、参数数量、代码块匹配情况，以及不受支持的结构（局部模板、装饰器，以及 MCN 锁定引擎中不存在的内置辅助函数）。
lookup_handlebars_helper	单个 MCN Handlebars 辅助函数的签名、参数、说明、来源和 MCN API 版本（不区分大小写）。
list_handlebars_helpers	列出所有 MCN Handlebars 辅助函数，可选按 category 和/或 origin（handlebars-builtin、mcn-helper、mcn-platform）筛选。
get_handlebars_completions	列出 MCN Handlebars 辅助函数补全项，可选按前缀筛选。
convertAmpscriptToHandlebars	基于规则的 AMPscript → MCN Handlebars 转换。存在等效项时将函数映射为辅助函数；将不受支持的函数和运行时限制标记为 MANUAL_REWRITE_REQUIRED。交互使用时优先选择 convertAmpscriptToHandlebars 提示词。
convertHandlebarsToAmpscript	基于规则的 MCN Handlebars → AMPscript 转换。将辅助函数和绑定映射回 AMPscript；将代码块辅助函数标记为 MANUAL_REWRITE_REQUIRED。交互使用时优先选择 convertHandlebarsToAmpscript 提示词。
convertSsjsToHandlebars	传递式 SSJS → AMPscript → MCN Handlebars 转换。保守地将命令式 SSJS 标记为需手动重写。交互使用时优先选择 convertSsjsToHandlebars 提示词。
write_handlebars	根据辅助函数目录验证 MCN Handlebars-in-HTML 草稿。编写时优先选择 writeHandlebars 提示词。
search_help	统一帮助搜索——根据 projectRoot 自动检测平台，并路由到相应的文档索引。MCN 项目会同时搜索开发者 API 参考和 MCN 管理文档。传入 target 可覆盖检测结果。
search_mce_help	搜索内置的 Marketing Cloud Engagement 设置/运维帮助；使用 product_focus 指定 Engagement 或 Next
search_mcn_help	搜索内置的 Marketing Cloud Next 开发者 API 文档（对象、流、细分、REST/SOAP API、MCN 中 AMPscript 的行为）

资源

URI	描述
sfmc://ampscript/functions	完整的 AMPscript 函数目录及其签名
sfmc://ssjs/functions	完整的 SSJS 函数目录
sfmc://ampscript/keywords	所有 AMPscript 关键字
sfmc://ssjs/unsupported-syntax	SFMC SSJS 不支持的 ES6+ 特性
sfmc://handlebars/helpers	完整的 MCN Handlebars 辅助函数目录，包含签名、来源和 MCN API 版本
sfmc://handlebars/bindings	MCN Handlebars 数据绑定（模板中可用的上下文变量）
sfmc://mce/product-context	Marketing Cloud Engagement 与 Marketing Cloud Next 的区别（何时使用哪个）
sfmc://mce/help-index	随附的 MCE 帮助文件列表及各产品范围的章节数量
sfmc://mcn/help-index	随附的 MCN 开发者 API 文档文件列表及分块数量

提示词

在 VS Code 中通过 /mcp.sfmc.writeAmpscript 等方式访问，或通过提示词 API 访问：

提示词	描述
writeAmpscript	为描述的任务生成 AMPscript 代码。target: 'next' 会强制遵循 MCN 限制（仅使用 MCN 支持的函数、使用 Java SimpleDateFormat 格式模式、不使用 SSJS）。
writeSsjs	为描述的任务生成 SSJS 代码。target: 'next' 会改为生成 AMPscript（MCN 不支持 SSJS）。
reviewSfmcCode	检查 AMPscript 或 SSJS 代码中的错误及违反最佳实践的情况。target: 'next' 会添加 MCN 兼容性检查清单。
rewrite_for_mcn	MCN 迁移的主要接口。 内部会对所有可确定性重写的部分调用 rewrite_for_mcn 工具，然后运用 AI 推理处理每个 MANUAL_REWRITE_REQUIRED 部分，生成一个完整迁移后的代码块，并附带文字变更日志。一步即可完成基于规则的处理和 AI 处理。
convertSsjsToAmpscript	SSJS → AMPscript 转换的主要接口。 内部会调用 convertSsjsToAmpscript 工具进行基于规则的转换，然后运用 AI 推理处理规则无法处理的部分。
convertAmpscriptToSsjs	AMPscript → SSJS 转换的主要接口。 内部会调用 convertAmpscriptToSsjs 工具进行基于规则的转换，然后运用 AI 推理处理标记出的仅适用于 AMPscript 的结构。
writeHandlebars	为描述的任务生成 MCN Handlebars-in-HTML 代码，并限制为使用锁定的 MCN 辅助函数目录。会使用 handlebars-data 验证草稿，并报告不受支持的结构。
convertAmpscriptToHandlebars	AMPscript → MCN Handlebars 转换的主要接口。 内部会调用 convertAmpscriptToHandlebars 工具进行基于规则的转换，然后运用 AI 推理处理没有 Handlebars 等效项的函数（运行时缺口和不受支持的函数）。
convertHandlebarsToAmpscript	MCN Handlebars → AMPscript 转换的主要接口。 内部会调用 convertHandlebarsToAmpscript 工具进行基于规则的转换，然后运用 AI 推理处理规则无法处理的区块辅助函数和结构。
convertSsjsToHandlebars	SSJS → MCN Handlebars 转换的主要接口。 此转换为传递式转换（SSJS → AMPscript → Handlebars）；会调用 convertSsjsToHandlebars 工具，然后运用 AI 推理处理被标记为需要手动重写的命令式 SSJS 代码。
answerMceHowTo	用于管理员／设置问题的引导式提示词——搜索内置帮助内容，并明确区分 Engagement 与 Next。

将代码迁移到 Marketing Cloud Next

Marketing Cloud Next（MCN）支持 155 个 AMPscript 函数中的 41 个，且不支持 SSJS。其中 3 个受支持的函数在行为上有所不同（见下文）。迁移工具包会引导你完成从分析到全面重写的整个过程。

推荐工作流

1. detect_sfmc_platform  →  confirm the project targets MCN
2. check_mcn_compatibility  →  understand scope: which files need work, how hard
3. rewrite_for_mcn prompt  →  calls the rewrite_for_mcn tool internally, then applies AI
                               reasoning to any MANUAL_REWRITE_REQUIRED sections
4. validate_ampscript with target:'next'  →  verify the rewritten code is clean

check_mcn_compatibility 会告诉你什么

传入一个或多个 { filename, content } 对，即可获得：

• 每个函数的分类，涵盖所有 AMPscript 调用位置：
  • ✅ 支持——可直接使用
  • ⚠️ 需要审核——MCN 支持，但行为有所不同
  • ❌ 不支持——没有对应的 MCN 功能
• SSJS 代码块分析——分类为“需要转换”（有对应的 AMPscript 功能）或“无法迁移”（使用了 try/catch、forEach、正则表达式等 JavaScript 原生结构）
• 每个文件的迁移难度——可直接迁移 / 需要少量修改 / 需要大幅重写 / 无法迁移
• 所有文件的执行摘要

rewrite_for_mcn 的作用

使用 rewrite_for_mcn 提示词——这是主要接口，可在一个步骤中提供完整结果。它会先在内部为所有可确定的重写调用 rewrite_for_mcn 工具，然后对工具无法机械处理的每个部分应用 AI 推理。你无需分别调用，即可同时获得基于规则的转换准确性和 AI 的智能处理能力。

确定性重写（由工具在内部处理）：

• 从 FormatDate() 调用中移除 StringToDate() 包装（FormatDate(StringToDate(@x), fmt) → FormatDate(@x, fmt)）
• 将 .NET → Java SimpleDateFormat 格式字符串转换（例如，tt → a）
• 标注搜索参数数量为奇数的 Lookup() 调用
• 为仅 MCE 支持的 AMPscript 函数添加 %%-- NOT SUPPORTED IN MCN %% 标记
• 将可转换的 SSJS 代码块转换为 AMPscript（Platform.Function.* → 对应的 AMPscript 功能，Platform.Variable.GetValue/SetValue → @variable 引用）
• 将 JavaScript 原生 SSJS 结构（try/catch、数组方法、正则表达式、复杂逻辑）标记为 MANUAL_REWRITE_REQUIRED

AI 推理层（由提示词添加）： 对于每个 MANUAL_REWRITE_REQUIRED 部分，提示词会指示 AI 利用其 AMPscript 和 SSJS 知识尝试完整转换，然后生成一个最终重写代码块，并附上涵盖所有更改的文字变更日志。

流水线和编程方式调用： 需要结构化 JSON 输出（{ rewrittenCode, changes[], nonMigratableItems[], difficulty, summary }）且不需要 AI 层时，可直接调用 rewrite_for_mcn 工具——例如，在 CI 步骤中将结果传递给另一个工具。

同样的混合模式也适用于 convertSsjsToAmpscript 和 convertAmpscriptToSsjs：交互使用时始终使用提示词；在流水线中需要结构化输出时使用工具。

需要留意的 MCN 行为差异

函数	差异
FormatDate	MCN 使用 Java SimpleDateFormat 模式，而非 .NET 模式。例如：.NET "M/d/yyyy h:mm:ss tt" → Java "M/d/yyyy h:mm:ss a"
Lookup	搜索参数必须按列/值成对提供——在 MCN 中，参数数量为奇数会导致错误。所有筛选键都必须完整指定复合主键。
StringToDate	在 MCN 中返回区域设置格式的字符串（G 标准格式，例如 "5/15/2026 1:23:45 PM"），而非 dateTime 对象。在 MCN 中无法可靠地将其传递给 FormatDate()——请直接将原始日期字符串传给 FormatDate()。

CloudPages 函数——不可迁移

依赖 CloudPages 上下文的函数（CloudPagesURL、RequestParameter、QueryParameter、Redirect、MicrositeURL）在 Marketing Cloud Next 中没有对应功能。check_mcn_compatibility 和 rewrite_for_mcn 会立即将这些函数标记为不可迁移。

MCN Handlebars

Marketing Cloud Next 除 AMPscript 外，还内置了一个受限的 Handlebars 模板层（Handlebars.Net）。服务端提供完整的辅助函数目录和转换工具，所有内容都由 handlebars-data 以及 ampscript-data 中的 handlebarsEquivalent / handlebarsExact 字段驱动——无需手动维护任何内容。

编写与查询

1. list_handlebars_helpers       →  browse the catalog (filter by category / origin)
2. lookup_handlebars_helper      →  signature, parameters, origin, MCN API version
3. get_handlebars_completions    →  prefix-filtered completions
4. writeHandlebars prompt        →  generate Handlebars-in-HTML, validated against the catalog
5. validate_handlebars           →  helper names, arity, block balance, unsupported constructs

validate_handlebars 会拒绝 MCN 引擎未实现的结构——局部模板（{{> name}}）、装饰器（{{#* ...}}），以及受限运行时中不存在的内置辅助函数。

转换类别

AMPscript → Handlebars 转换会为 ampscript-data 中的每个函数分类：

类别	条件（在 ampscript-data 中）	输出
精确	设置了 handlebarsEquivalent 且 handlebarsExact !== false	映射到规范的 MCN Handlebars 辅助函数
近似	设置了 handlebarsEquivalent 且 handlebarsExact === false	{{!-- MANUAL_REWRITE_REQUIRED: … (names the closest helper) --}}
无对应项	没有 Handlebars 对应项	{{!-- MANUAL_REWRITE_REQUIRED: … no Handlebars equivalent --}}

“近似”备注会指出最接近的辅助函数，方便使用者区分仅调用形式不同的函数（例如 ContentBlockByKey → getContentBlock）和完全没有 MCN 对应项的函数。convertSsjsToHandlebars 会执行传递式转换（SSJS → AMPscript → Handlebars），并会保守地将命令式 SSJS 标记为需要手动重写。

编写有效的提示词

自动使用工具

遵循 MCP instructions 字段的客户端（Cursor、Claude Desktop、GitHub Copilot Agent 模式）会在你提出 MCE 管理或设置问题时自动调用 search_help 或 search_mce_help——无需特殊措辞。如果你的客户端不处理服务指令，或你想显式控制，下面的模板会有所帮助。

快速参考：使用哪个工具或提示词

情况	操作
MCE 管理问题（经典版 Engagement）	自然提问；服务会调用 search_help（或直接调用 search_mce_help）。也可以使用 answerMceHowTo 提示词，并设置 assumeProduct: engagement。
Marketing Cloud Next 开发者 API 问题	服务会自动调用 search_help 或 search_mcn_help。也可以显式使用 search_mcn_help。
MCN 运营／迁移／设置问题	使用 search_mce_help，并设置 product_focus: 'next'；也可以自然提问，由服务进行路由。
不确定属于哪个产品	使用 answerMceHowTo，并设置 assumeProduct: unsure；也可以使用不带 target 的 search_help。
编写或验证 AMPscript	使用 writeAmpscript 提示词，或直接提问（服务会自动验证）。MCN 请添加 target: 'next'。
编写或验证 SSJS	使用 writeSsjs 提示词，或直接提问。注意：MCN 不支持 SSJS。
检查代码是否适用于 MCN	使用 check_mcn_compatibility 并提供文件内容。
将代码迁移到 Marketing Cloud Next	使用 rewrite_for_mcn 提示词——它会在内部调用工具进行确定性重写，然后运用 AI 推理处理剩余的手动部分。仅在管道中需要结构化 JSON 输出时，才直接使用该工具。
转换 SSJS ↔ AMPscript	使用 convertSsjsToAmpscript 或 convertAmpscriptToSsjs 提示词——同样采用混合模式：工具先运行，AI 再处理规则无法处理的部分。
编写或验证 MCN Handlebars	使用 writeHandlebars 提示词编写，或使用 validate_handlebars 检查现有模板代码。使用 lookup_handlebars_helper / list_handlebars_helpers 查询辅助函数。
转换 AMPscript ↔ Handlebars（或 SSJS → Handlebars）	使用 convertAmpscriptToHandlebars、convertHandlebarsToAmpscript 或 convertSsjsToHandlebars 提示词——同样采用混合模式：工具先运行，AI 再处理规则无法处理的部分。
审查代码差异	使用 reviewSfmcCode 提示词，或提及“审查以下差异”。

可直接复制粘贴的提示词模板

Classic Engagement 管理员（最常见）

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 — 开发者 API

Search the Marketing Cloud Next developer docs and tell me:
<your question here>

Confirm the steps apply to Marketing Cloud Next, not classic Engagement.

MCN 迁移分析

Check these files for Marketing Cloud Next compatibility and give me an executive summary:
<paste file contents>

为 MCN 重写代码

使用 rewrite_for_mcn 提示词——它会先运行确定性重写工具，然后对需要处理的部分应用 AI 推理。一步即可获得完整结果。

Rewrite the following AMPscript/HTML for Marketing Cloud Next:
<paste code>

Apply all deterministic fixes, convert convertible SSJS to AMPscript, and explain every change.

未知产品 / 迁移问题

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.

明确使用 answerMceHowTo 提示词

在支持 MCP 提示词的客户端中（例如使用 /mcp.sfmc.answerMceHowTo 命令的 VS Code）：

/mcp.sfmc.answerMceHowTo
  question: "How do I create a child business unit and assign it a sender profile?"
  assumeProduct: engagement

将 MCE 管理与代码结合使用

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.

对 AI 的预期

• AI 会在每个回答中注明产品范围（Engagement 或 Next）。
• 如果捆绑的摘录未能完全涵盖问题，AI 会说明这一点，并建议在 Salesforce Help 在线版本中核实。
• 函数签名（AMPscript / SSJS）始终取自语言目录，而非训练数据。

刷新捆绑的帮助索引

Marketing Cloud Engagement 帮助

已发布的 npm 包包含 bundled/mce-help/chunks.json，由 npm run bundle-mce-help 生成。默认情况下，打包工具使用 MCE_HELP_DOCS 中指定的路径（参见 scripts/bundle-mce-help.mjs）；如果不使用维护者的默认路径，请将其设为镜像 MCE Help Markdown 树的根目录。

cd mcp-server-sfmc
npm run bundle-mce-help
npm run build
npm test

示例：MCE_HELP_DOCS=/absolute/path/to/mce-help-mirror npm run bundle-mce-help

Marketing Cloud Next 开发者文档

已发布的 npm 包包含 bundled/mcn-help/chunks.json，由 npm run bundle-mcn-help 生成。如果不使用维护者的默认路径，请将 MCN_HELP_DOCS 设为镜像 MCN 开发者文档树的根目录（参见 scripts/bundle-mcn-help.mjs）。

cd mcp-server-sfmc
npm run bundle-mcn-help
npm run build
npm test

要用一条命令重建两个索引：npm run bundle-all

拉取请求中的 AI 代码审查

Cursor Bugbot

Cursor Bugbot 会自动审查拉取请求（GitHub）和合并请求（GitLab），发布带有修复建议的行内评论，并发布 Cursor Bugbot 检查。它不会自行运行 sfmc-review-diff——你可以通过两种方式让它了解 SFMC：

1. 仓库规则（BUGBOT.md）——适用于所有方案。 将 ci-templates/BUGBOT.md 复制到仓库根目录下的 .cursor/BUGBOT.md。该文件会告知 Bugbot 如何审查 AMPscript、SSJS 和 SFMC HTML，包括未知函数、参数数量、分隔符配对、仅限 ES3 的 SSJS，以及可选的 Marketing Cloud Next 迁移规则。Bugbot 会读取根目录中的文件，以及变更文件附近任何嵌套的 .cursor/BUGBOT.md 文件，因此你可以为子文件夹设置更严格的规则。

2. MCP 工具（mcp-server-sfmc）——仅限 Team / Enterprise 方案。 Bugbot 可以在审查过程中调用 MCP 工具，让审查结果与编辑器使用同一语言目录：

1. 在 Bugbot 控制面板中，为仓库启用 Bugbot。
2. 打开 Bugbot 的 MCP 配置，并添加此服务：

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

3. 在控制面板中将工具添加到 Bugbot。相关的审查工具包括 review_change、validate_ampscript、validate_ssjs、validate_sfmc_html 和 suggest_fix。上述 BUGBOT.md 规则会指示 Bugbot 何时调用这些工具。

分支保护：要求通过 Cursor Bugbot 检查，以确保合并前运行审查。 检查结果默认采用 neutral 结论；如果希望审查发现导致检查失败，请在控制面板中启用 fail-on-unresolved-issues（如有此选项）。

先在本地运行。 在 Cursor 3.7+ 中，推送前可在分支上运行 /review-bugbot；如果 PR/MR 的差异相同，Bugbot 会复用该审查，避免重复运行。

GitHub Copilot（云 Agent）

此仓库中的 .github/agents/sfmc-reviewer.agent.md 自定义 Agent 配置了一个 GitHub Copilot 云 Agent，使用 mcp-server-sfmc 进行 SFMC 感知型 PR 审查。

要在你自己的仓库中启用它：

1. 将 .github/agents/sfmc-reviewer.agent.md 复制到你的仓库。
2. 在 GitHub 仓库设置 → Copilot → Cloud agent → MCP configuration 中添加：

{
  "mcpServers": {
    "sfmc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-sfmc@latest"],
      "tools": ["*"]
    }
  }
}

3. 在评论中提及 sfmc-reviewer Agent，或通过 GitHub Copilot Chat 中的 @sfmc-reviewer Agent，将其分配给拉取请求。

GitHub Copilot（专用 PR 审查）

将此仓库中的 .github/copilot-instructions.md 复制到你的项目。GitHub Copilot 的专用 PR 审查功能会读取此文件，并在总结 PR 时应用 SFMC 语言规则。

GitLab Duo

1. 将 ci-templates/gitlab-duo-review-instructions.md 的内容复制到你仓库中的 .gitlab/duo-instructions.md。
2. GitLab Duo Code Review 会在每个合并请求中应用这些说明。

GitLab Duo 的专用 MR 审查不直接支持 MCP。请使用下方的 CI lint 任务执行自动化静态分析，并使用 Duo 说明生成 AI 辅助审查评论。

CI lint（确定性检查）

如需确定性、可阻止合并的 CI 验证，请使用 ci-templates/ 中提供的模板。 每个模板都会在每个 PR/MR 上运行两项检查：对更改文件运行 eslint-plugin-sfmc，并对统一差异运行 sfmc-review-diff（此软件包）。因此，无论是否同时启用了 Bugbot、Copilot 或 Duo 等 AI 审查器，只要发现问题，任务就会失败。

平台	文件
GitHub Actions	ci-templates/github-action.yml
GitLab CI	ci-templates/gitlab-ci.yml
Jenkins	ci-templates/Jenkinsfile
Azure DevOps	ci-templates/azure-pipelines.yml
Bitbucket Pipelines	ci-templates/bitbucket-pipelines.yml

ESLint 任务会将 lint 结果作为 PR/MR 评论发布；默认情况下，sfmc-review-diff 任务在遇到 ERROR 诊断时会以非零状态退出（使用 --fail-on warning|info 可提高严格程度）。 请参阅 ci-templates/README.md，了解两项检查的区别。

ESLint + @eslint/mcp

对于不支持 MCP、但支持工具调用的 AI 助手，可以将 eslint-plugin-sfmc 与官方 @eslint/mcp 服务结合使用。将其与 mcp-server-sfmc 一起添加：

{
  "servers": {
    "sfmc": {
      "command": "npx",
      "args": ["-y", "mcp-server-sfmc@latest"]
    },
    "eslint": {
      "command": "npx",
      "args": ["-y", "@eslint/mcp@latest"]
    }
  }
}

在项目根目录中创建 eslint.config.mjs：

import sfmc from 'eslint-plugin-sfmc';
export default [...sfmc.configs.recommended];

@eslint/mcp 服务会提供一个 eslint_lint 工具，供 AI 调用，以便在任意文件上运行完整的 ESLint 规则集（包括 eslint-plugin-sfmc 中的所有 AMPscript 和 SSJS 规则）。

架构

mcp-server-sfmc
    ├── sfmc-language-lsp   (language intelligence core)
    │       ├── ampscript-data   (AMPscript function catalog)
    │       ├── ssjs-data        (SSJS function catalog)
    │       └── handlebars-data  (MCN Handlebars helper catalog)
    ├── ampscript-data     (direct — conversion maps, mcnSince, handlebarsEquivalent)
    ├── ssjs-data          (direct — Platform.Function ↔ AMPscript mapping)
    └── handlebars-data    (direct — AMPscript ↔ Handlebars conversion)

vscode-sfmc-language (VS Code extension)
    └── sfmc-language-lsp   (same core, bundled via esbuild)

VS Code 扩展和 MCP 服务通过 sfmc-language-lsp 共享完全相同的验证、补全、悬停和查询逻辑。这意味着 AI 助手看到的错误和建议与编辑器中显示的相同。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT — 请参阅 LICENSE。