mcp-server-mcdev

mcp-server-mcdev

通过 AI 使用 Accenture SFMC DevTools（mcdev）：执行原生元数据工作流、了解命令语法、排查故障，并离线搜索随附的项目 Wiki。服务通过 MCP stdio 在本地运行；原生凭据保留在 mcdev 的存储中。

搭配 mcp-server-sfmc 使用，可进行 AMPscript / SSJS 语言验证和查询。

要求

需要 Node.js ^22.22.2 || >=24.15.0。此服务使用 npm mcdev 10.1.1 版本线；无需单独全局安装 mcdev。

MCP Registry

已注册为 io.github.JoernBerkefeld/mcp-server-mcdev（快速入门）。Registry 仅托管元数据；服务通过 stdio 在本地运行。

发布后验证：

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

CI 使用 GitHub OIDC 发布 npm 制品和 Registry 元数据（Actions 文档）——请参阅 .github/workflows/npm-publish.yml。npm 发布成功后，CI 会等待五分钟，让 npm Registry 完成传播，然后再发布 MCP Registry 元数据。

工具

此服务提供以下 20 个工具。对于受支持的非交互式命令，run_mcdev_command 是原生执行入口；只有在操作员完成协调后，reconcile_mcdev_operation 才会解除不确定操作锁存状态。其余 18 个工具用于检查、诊断和提供指导。预览不等同于试运行，也不构成执行许可。目录条目会区分可执行的非交互式情形与不受支持或依赖提示词的情形。

工具	用途
run_mcdev_command	使用精确的 argv 词元和明确的目标／选项，执行明确请求且受支持的原生 mcdev 命令；支持长时间运行的操作、取消和有界诊断。适用原生本地／远程影响；操作完成不代表已独立验证远程状态。
reconcile_mcdev_operation	在操作人员确认相关进程已停止且部分影响已协调后，解除不确定的原生操作锁存状态。不执行或验证协调操作，不重试命令，也不授权其他操作。
mcdev_search_docs	按关键词搜索捆绑的 sfmc-devtools wiki Markdown，可选设置结果数量上限。
mcdev_get_doc_section	使用搜索结果 Source ID 和 UTF-16 偏移量，分页查看尚未审阅的捆绑 wiki 章节；检索到的说法不代表认可。
mcdev_explain_config_key	解释配置主题（markets、marketList、createDeltaPkg 等），并提供摘要和 wiki 提示。
mcdev_component_checklist	返回组件问题和典型的依赖元数据类型（journey、automation 等）。
mcdev_list_metadata_types	在静默 JSON 模式下列出 Mcdev.explainTypes() 中的类型，可选择按名称或 API 名称筛选。
mcdev_list_commands	列出经审阅的命令声明和别名，仅供参考；它们不是可执行命令或 argv 允许列表。
mcdev_get_command	按精确且区分大小写的命令名称或别名查找命令，仅供参考，不用于执行或审批。
read_mcdev_project_config	从规范的绝对项目根目录返回完整的未脱敏原始 .mcdevrc.json 文本，包括凭据和自定义字段；绝不读取 .mcdev-auth.json。
diagnose_mcdev_project_config	提供部分静态配置诊断，并建议优先使用可视化 MCDev Pipeline Builder；不写入、不进行原生验证，也不评估执行就绪状态。
preview_mcdev_project_config	将当前配置与完整的拟议 JSON 文档进行比较，而非补丁；在整个结果的字节数预算内返回完整未脱敏的变更和部分静态诊断，不应用变更。
inspect_mcdev_git_policy	检查本地 Git 状态／引用元数据和远程跟踪祖先关系；分支约定、远程最新状态和 BU 同步情况仍未经验证。与身份验证保护检查分开。
inspect_mcdev_git_range	使用本地 Git 元数据比较两个明确的引用；可选择标注一条由调用方声明的晋升／回退晋升边。不推断策略或分支角色，也不验证远程最新状态／BU 同步情况。
inspect_mcdev_project	返回完整未脱敏配置，并独立检查 Git 忽略／索引元数据以确认身份验证信息是否受保护；不读取身份验证内容或历史记录，不修复、不暂存，也不取消跟踪。
inventory_mcdev_project_artifacts	通过有界且仅限元数据的遍历，盘点已配置的检索／部署路径；不读取产物内容，也不确认依赖关系。
resolve_mcdev_project_artifact	将一个明确的根目录／凭据／BU／类型／键标识解析为本地查询、脚本或有界的资源电子邮件路径及其可编辑配套文件；不确认依赖关系，也不保证远程状态为最新。
read_mcdev_artifact_source	为符合条件的查询、脚本或有界资源电子邮件标识，移交完整的原始 UTF-8 可编辑源文件及其原始字节 SHA-256；必要时，明确指定的电子邮件 sourceRole 用于选择 HTML／预标题／纯文本。不执行渲染、验证或运行；由宿主协调配套验证器，纯文本／SQL 验证尚未确定。
preview_mcdev_project_command	针对明确的配置映射、经审阅的类型、字面键和受支持选项，提供仅供参考的检索／部署预览；路径和执行就绪状态仍未知。不启动子进程或执行试运行。
diagnose_mcdev_retrieve_logs	针对一个精确的查询／脚本检索和明确的 UTC 时间窗口，读取有界的历史常规日志；仅返回有限的观察结果以及基于文件名和时间的来源信息，绝不返回原始日志或远程完整性信息。不重新运行。
配置检查采用有界读取、路径检查和经清理的失败响应；这些不是脱敏。调用方必须防止文件系统并发变更：这些检查并非原子文件系统沙箱。内容读取会排除 .mcdev-auth.json。

原生命令执行

调用 mcdev_list_commands / mcdev_get_command，以了解原生命令签名和执行可用性。然后调用 run_mcdev_command，并提供绝对路径 workspaceRoot、规范的 command，以及包含命令之后精确 argv 令牌的 args。Shell 元字符会作为字面参数处理；不会启动 shell。已安装的 npm mcdev 负责选择器、类型/子类型支持、验证、格式化、模板化和部署。

例如，要检索查询：

{
  "workspaceRoot": "F:\\Projects\\marketing",
  "command": "retrieve",
  "args": ["development/Main", "query", "welcome-query"]
}

其他原生工作流使用相同的参数封装：

• 资源/邮件检索：命令 retrieve，参数 ["development/Main", "asset-email", "welcome-email"]。
• 从检索到的源代码部署自动化：命令 deploy，参数 ["development/Main", "automation", "nightly-import", "--fromRetrieve"]。
• 基于市场的构建：命令 build，参数 ["--buFrom", "development/Main", "--buTo", "production/Main", "--marketFrom", "development", "--marketTo", "production", "--metadata", "query:welcome-query", "--no-purge"]。检查生成的输出，然后明确请求单独的 deploy 命令。
• 模板和定义工作流：使用 buildTemplate、buildDefinition 或 buildDefinitionBulk，并提供原生的位置参数以及市场/列表参数。原生配置会控制所有 templateBuilds 目标位置；其范围不限于查询 SQL 或单个部署目录。
• 跨 BU 克隆：使用 clone，并明确提供 --buFrom、--buTo、--metadata 以及布尔选项 --purge 或 --no-purge。适用原生的克隆市场和构建行为。
• 其他原生命令：badKeys 和 document 会写入原生本地报告。explainTypes --json 会返回有界的结构化类型目录；resolveId BU asset ID --json 会返回经审核的资源解析字段，并可进行身份验证/读取远程元数据。这些仅输出命令必须使用 JSON 模式和受支持的日志选项；调试/详细模式及不受支持的结果形式会在启动前被拒绝。
• getFilesToCommit 仍可供发现，但执行已被阻止：已安装的 CLI 会丢弃其结果。请改用 mcdev 的本地编程 API。声明清单不代表可执行覆盖范围。

启动前请提供缺失的选项。不会添加终端模拟、自动 --yes、自定义同意令牌或重复覆盖确认。常规 MCP 宿主审批适用于实际操作。没有明确选项的依赖提示词的组合会保持阻止状态，而不会由系统猜测。对于 deploy 的共享 Data Extension 修复，请提供 --fixShared=ChildA,ChildB（或单独的明确值），或者使用 --fixShared=* 修复所有已配置的子项。服务会在启动前针对每个选定凭据验证所有名称，排除父 BU，并拒绝空选项或冲突选项。已安装的 mcdev 10.1.1 CLI 会直接处理明确的选择；无需桥接、未发布的依赖项或运行时补丁。使用 --no-fixShared 可禁用修复。单独使用 --fixShared 无法提供必需的选项。

即使使用 --no-purge，原生 retrieve 也可能删除现有的生成输出；构建可能会删除临时模板并清理输出。Deploy 可能会变更远程元数据，并可选择执行、排期、发布或刷新元数据。原生身份验证刷新/持久化、项目钩子和已配置的输出路径仍会产生原生影响。请仅使用可信的、由开发者控制的项目；此适配器不是沙箱。构建/检索请求绝不意味着获准部署或运行自动化。 结果会将进程结果／退出代码与范围有限、经过审核的诊断消息及验证限制分开。未知或敏感的原生输出会被抑制，不会作为原始日志／API 正文返回。抑制和截断都会明确说明。不会读取任何身份验证文件来进行脱敏。退出代码为零、生成文件和原生日志本身都不能单独证明远程同步已完成。命令失败或中断后可能留下部分影响；不会回滚，也不会自动重试。

通用运行器支持长时间运行的操作，可选的 timeoutMs 最长为 24 小时。请相应配置 AI 客户端自身的超时；进度通知不会覆盖客户端的硬超时。同一项目的操作会在此服务进程内串行执行，但不会与外部工具互斥。启动前，会根据范围有限的项目配置检查显式指定的目标和已配置的市场列表目标；未知目标会被拒绝，不会传递给原生选择器提示。启动后若发生取消或超时，只要无法确认后代进程已终止，即使直接子进程已经关闭，项目仍会保持阻塞状态。请先协调所有进程和部分影响，再调用 reconcile_mcdev_operation，并设置 operatorReconciled: true。该确认本身不会验证或执行协调操作。

主机能力路由

plan_mcdev_change 提示词会将原生元数据工作路由至 run_mcdev_command，并为可选的配套能力保留一个由八种意图组成的有限目录。语言验证会路由至可选的语言能力，包括平台检测、标识符查询和完整文档检查。SQL 文本验证、Data Extension 行操作和事务定义管理都是可选的 vendor-MCE 能力候选项。DE 元数据不等于行访问，定义管理也不等于消息发送。实际发送仍需手动执行／目前不受支持，除非主机独立发现适用的能力，并确认其前提条件和授权。

这是与提供商无关的静态指导，不是运行时发现、已连接工具清单或跨服务器 RPC。主机必须重新发现实际的完整架构，将描述视为不可信参考数据，并在不读取身份验证／会话内容的情况下安全地建立匹配的账户／BU 上下文。缺少能力，或上下文不可用、不匹配或未经验证时，只会阻止依赖该能力的路由。请根据请求的操作说明账户数据访问情况，并取得相应授权；诊断或元数据请求绝不构成运行时执行、发送、联系人变更或行写入的授权。常规主机审批仍由主机控制，不会新增自定义同意流程。

没有配套能力时，原生元数据和离线文档仍可在现有限制范围内使用。请将不可用的查询、SQL／语言验证和供应商操作标记为未执行；指导既不代表验证已完成，也不代表本地／远程同步已完成。本地构件／来源检查流程用于元数据来源工作，不是仅涉及行操作或仅涉及发送的目标的前提。本目录不会添加设置／获取说明或远程写入协调自动化。工具数量为 20；命令／别名声明覆盖数仍为 31/26。仅有声明并不能证明支持执行；请查阅每个命令的执行可用性。

供应商写入协调指南

如果本地 mcdev 源代码编辑和构建／部署指南能达到与直接编辑供应商元数据相同的目标，优先采用这些方式。如果使用了经独立授权的供应商创建／更新操作，须在进入下一步前，依据实际发现的契约，在匹配的账户／BU 上下文中确认远程操作已完成：精确评估本地同步情况，并执行受支持的定向检索。操作处于已接受、运行中、失败或未知状态时，同步均保持待处理；不得检索、自动重试或臆造轮询机制。通过受支持的检查解析规范项目、凭据、BU、类型、字面外部键以及确切的 JSON／配套文件目标；身份、目标位置或文件是否存在不确定时，应保持待处理，不得猜测文件不存在。

评估并说明干净、已修改和仅有配套文件的文件状态，以及编辑／不确定性和原生操作的覆盖／可能删除／授权持久化影响。在既有授权范围内行事：仅凭文件存在，不要求重复确认原生影响或覆盖。常规主机审批仍由主机控制；实际拒绝时，文件保持不变，同步保持待处理。仅针对尚未解决的选项或超出既有授权范围的操作请求确认。对于明确请求的受支持定向检索，使用通用原生执行器。不得在未获请求范围授权的情况下，将精确选择扩大为整个类型／BU 的回退操作。行、运行时、发送和联系人都没有臆造的元数据对应项。检索失败、不完整、未改变或未经验证，以及终止状态未知时，同步均保持待处理；本地文件落盘不能证明远程内容完整，也不允许悄然部署过时内容。这是主机指导，不是同步自动化、新工具、锁、轮询或跨服务器调用。

显式 Git 晋级评估

inspect_mcdev_git_range 仍只需要 workspaceRoot、sourceRef 和 targetRef。省略 declaredEdge，以保留原有仅比较的 JSON 响应。也可传入 declaredEdge: "promotion" 或 "back-promotion"，以追加包含 direction: "source-to-target"、basis: "exact-source-commit-ancestry" 和 policySource: "caller-declared" 的 promotionAssessment。两种类型都使用精确提供的源和目标；反向晋级绝不会调换两者或推断分支角色。

当端点相同或目标端领先时，评估的 status 为 contained；当源端领先或已验证的非浅克隆历史存在分歧时，为 not-contained；当端点或祖先关系未经验证时，为 unknown，其中包括无法得出结论的浅克隆负面结果。此评估仅判断精确源提交是否位于目标的本地祖先历史中：不会评估通过 cherry-pick 得到或其他等效的元数据。not-contained 不代表缺少元数据更改，也不代表遗漏了必须执行的反向晋级。不会因此确认全项目策略／发现结果、远程最新状态、部署就绪情况或远程 BU 同步状态。检查期间应防止并发修改项目／Git；这不是原子快照。

连接 AI 客户端

按照与其他 stdio MCP 服务相同的模式注册 mcp-server-mcdev（在 args 中填写包名）。

VS Code（1.99+）— .vscode/mcp.json

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

Cursor — ~/.cursor/mcp.json 或项目 .cursor/mcp.json

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

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）——使用与 Cursor 相同结构的 mcpServers 对象。

Windsurf

~/.codeium/windsurf/mcp_config.json——使用与 Cursor 相同结构的 mcpServers。

全局安装（启动更快）

npm install -g mcp-server-mcdev

然后使用 "command": "mcp-server-mcdev", "args": []（或此包 bin 字段中的二进制名称）。

历史检索日志诊断

diagnose_mcdev_retrieve_logs 是一项专用只读功能，是对禁止使用通用日志内容读取器的例外。它接受且只接受七个必填字段：workspaceRoot、credential、businessUnit、metadataType（query 或 script）、key、startedAfter 和 startedBefore。请使用准确配置的别名和单个字面量键。两个时间都必须是带毫秒的有效 UTC ISO 时间戳（例如 2026-10-22T11:00:00.000Z），按包含边界的顺序排列，且相隔不得超过 24 小时。不接受调用方提供的路径、标志或预算覆盖值。

历史关联支持 mcdev 10.1.0 和 10.1.1，规范化的组合命令拼写为 retrieve credential/BU query key 或 retrieve credential/BU script key。每个 credential、BU 和 key 都必须符合 [A-Za-z0-9_][A-Za-z0-9_.-]{0,127}。不支持选项、命令别名、引号、空白字符／列表／通配符选择器及多 BU 调用；这种刻意收窄的语法可避免猜测最初如何输入未转义的组合参数。版本／命令、retrieve、限定的 BU 以及准确的类型／键记录必须与时间戳文件名一致。不能仅凭修改时间选择日志。

只会私下读取项目 logs 目录下直接存放的常规时间戳命名 .log 文件；排除 -errors.log 配套文件。发现范围限制为 256 个目录项和 16 个候选文件，每个文件 1 MiB，总计 4 MiB。超出预算、遇到链接、硬链接、非普通文件或检测到文件变动时，操作都会安全失败。调用期间请确保项目和日志保持静止：这些检查不会强制执行外部排他，也不会提供原子文件系统沙箱。

结果包含 status（matched、no-match、ambiguous、unsupported、blocked 或 unavailable）、remoteCompletenessVerified: false 和 logs。失败时不包含日志；匹配时最多包含最新的相关常规日志基本文件名、调用 UTC 时间戳、有限的发现代码／计数，以及被抑制记录的数量。发现项仅包括 retrieve-start-observed、type-key-observed、download-zero-observed 和 download-nonzero-observed；观察到开始或下载并不能证明远程操作成功或完整。未知记录、解析器片段和 API 正文会被抑制，不会在脱敏后返回。不会暴露原始日志、绝对路径、原生错误、选择器或机密，也绝不会检查身份验证／会话内容。

使用 --noLogFile 进行的原生命令调用不会为此读取器提供历史日志。缺少日志或只有未知证据属于实际限制，不应因此重复检索。如果发现不足，请通过安全的本地工作流手动调查，不要分享原始日志。此工具不会执行子进程、网络请求或原生操作，也不会发起询问、重试或重新运行 API 日志，并且无法授权这些操作。

SFMC DevTools VS Code 扩展

SFMC DevTools 扩展介绍了供 AI 辅助 mcdev 工作流使用的可选 MCP 设置（请参阅该仓库的 README）。

刷新打包的 wiki

常规的 npm run bundle-wiki、构建、钩子和预发布流程会复用已提交的 bundled/wiki，而不会读取同级检出目录。如需从同级的 ../sfmc-devtools.wiki 检出目录主动刷新：

npm run bundle-wiki -- --refresh

若要使用干净且经过审核的源目录，请设置 SFMC_DEVTOOLS_WIKI 并明确请求刷新：

export SFMC_DEVTOOLS_WIKI=/absolute/path/to/reviewed-wiki
npm run bundle-wiki -- --refresh

在 PowerShell 中，使用 $env:SFMC_DEVTOOLS_WIKI = 'F:\path\to\reviewed-wiki'。即使设置了此变量，常规构建、钩子和预发布流程也不会读取该源。刷新源缺失或为空时会报错，不会静默回退到其他检出目录。若刷新与本地注释冲突，必须通过导出的 bundleWiki API，使用准确的旧版／拟议版 SHA-256 进行协调；没有强制刷新 CLI 标志。

已发布的 wiki 基线是干净的远程提交 6a87898ba811ba9f5ad3553e72cce97f128a8601（这是提交，不是 wiki 标签），刷新时对应 mcdev 10.1.1。bundled/wiki-provenance.json 记录了已发布页面的哈希值、准确的刷新协调信息，以及六个带有本地注释的页面各自最终字节的哈希值。源仍标记为 not-reviewed：导入干净的已发布快照并不代表认可所有上游声明。

Getting Started、Updating mcdev、Admin Commands 和 Git-based deployments and CI/CD 保留了明确标记为待定／尚未发布的扩展程序打包 CLI 与可选 Git 指南。Templating Commands 和 Advanced Configuration 保留了本地行为／安全性修正。这些注释不能证明待定的 VS Code 扩展已经发布。共享的 Data Extension 选择文档从已发布的 wiki 导入；根据 mcdev 10.1.1 发布说明，初始推送修复以及布尔值 --purge／--no-purge 修复均标记为已发布。已发布的 wiki 仍将 purge 修复标记为待定，因此打包内容在本地修正了这个过时的标记。未来刷新时，请保留或明确协调所有其余注释。

许可证

MIT © Jörn Berkefeld