mcp-server-mcdev

mcp-server-mcdev

Use Accenture SFMC DevTools (mcdev) through AI: execute native metadata workflows, discover command syntax, troubleshoot failures, and search the bundled project wiki offline. The server runs locally through MCP stdio; native credentials stay in mcdev's storage.

Pair with mcp-server-sfmc for AMPscript / SSJS language validation and lookups.

Requirements

Node.js ^22.22.2 || >=24.15.0 is required. This server uses the npm mcdev 10.1.1 release line; no separate global mcdev installation is required.

MCP Registry

Registered as io.github.JoernBerkefeld/mcp-server-mcdev (quickstart). Registry hosts metadata only; the server runs locally via stdio.

Verify after publish:

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

CI publishes npm artifacts and registry metadata using GitHub OIDC (Actions doc) — see .github/workflows/npm-publish.yml. After npm publish succeeds, CI waits five minutes for npm registry propagation before publishing MCP Registry metadata.

Tools

The server exposes the 20 tools listed below. run_mcdev_command is the native execution route for supported noninteractive commands; reconcile_mcdev_operation releases an uncertain-operation latch only after operator reconciliation. The other 18 tools provide inspection, diagnostics and guidance. Previews are not dry runs or approval for execution. Catalog entries distinguish executable noninteractive cases from unsupported/prompt-dependent cases.

Tool	Purpose
run_mcdev_command	Execute an explicitly requested supported native mcdev command with exact argv tokens and explicit targets/choices; supports long-running operations, cancellation and bounded diagnostics. Native local/remote effects apply; completion is not independent remote verification.
reconcile_mcdev_operation	Release an uncertain native-operation latch after operator confirmation that related processes have stopped and partial effects have been reconciled. Does not perform or verify reconciliation, retry a command or authorize another operation.
mcdev_search_docs	Search bundled sfmc-devtools wiki Markdown by keywords, with an optional result limit.
mcdev_get_doc_section	Page through an unreviewed bundled wiki section using a search Source ID and UTF-16 offsets; retrieved claims are not endorsements.
mcdev_explain_config_key	Explain config topics (markets, marketList, createDeltaPkg, …) with summaries and wiki hints.
mcdev_component_checklist	Return component questions and typical dependent metadata types (journey, automation, …).
mcdev_list_metadata_types	List types from Mcdev.explainTypes() in silent JSON mode, optionally filtering by name or API name.
mcdev_list_commands	List reviewed command declarations and aliases as guidance, not executable commands or an argv allowlist.
mcdev_get_command	Look up an exact, case-sensitive command name or alias for guidance, not execution or approval.
read_mcdev_project_config	Return complete, UNREDACTED original .mcdevrc.json text, including credentials and custom fields, from a canonical absolute project root; never reads .mcdev-auth.json.
diagnose_mcdev_project_config	Provide partial static config findings and recommend the visual MCDev Pipeline Builder first; no writes, native validation or execution-readiness assessment.
preview_mcdev_project_config	Compare current config with a complete proposed JSON document, not a patch; return full unredacted changes and partial static diagnosis within a whole-result byte budget, without applying changes.
inspect_mcdev_git_policy	Inspect local Git status/ref metadata and remote-tracking ancestry; branch conventions, remote freshness and BU synchronization remain unverified. Separate from auth-protection checks.
inspect_mcdev_git_range	Compare two explicit refs using local Git metadata; optionally annotate one caller-declared promotion/back-promotion edge. No inferred policy, branch roles or verified remote freshness/BU synchronization.
inspect_mcdev_project	Return complete unredacted config and independently check Git ignore/index metadata for auth protection; no auth-content/history reads, repairs, staging or untracking.
inventory_mcdev_project_artifacts	Inventory configured retrieve/deploy paths with bounded metadata-only traversal; no artifact-content reads or dependency confirmation.
resolve_mcdev_project_artifact	Resolve one explicit root/credential/BU/type/key identity to local query, script or bounded asset-email paths and editable companions; no dependency confirmation or remote-freshness guarantee.
read_mcdev_artifact_source	Hand off complete original UTF-8 editable source and its original-byte SHA-256 for a qualified query, script or bounded asset-email identity; explicit email sourceRole selects HTML/preheader/text when needed. No rendering, validation or execution; the host coordinates companion validators, with text/SQL validation not established.
preview_mcdev_project_command	Give guidance-only retrieve/deploy previews for an explicit config mapping, reviewed type, literal key and supported options; paths and execution readiness remain unknown. No subprocess or dry-run.
diagnose_mcdev_retrieve_logs	Read bounded historical normal logs for one exact query/Script retrieve and explicit UTC window; return finite observations and basename/time provenance only, never raw logs or remote completeness. No rerun.

Config inspection uses bounded reads, path checks and sanitized failure responses; these are not redaction. Callers must prevent concurrent filesystem mutation: these checks are not an atomic filesystem sandbox. .mcdev-auth.json is excluded from content reads.

Native execution

Call mcdev_list_commands / mcdev_get_command to discover native signatures and execution availability. Then call run_mcdev_command with an absolute workspaceRoot, canonical command, and args containing exact argv tokens after the command. Shell metacharacters are literal arguments; no shell is started. The installed npm mcdev owns selectors, type/subtype support, validation, formatting, templating and deployment.

For example, to retrieve a query:

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

Other native workflows use the same envelope:

• Asset/email retrieval: command retrieve, args ["development/Main", "asset-email", "welcome-email"].
• Automation deployment from retrieved sources: command deploy, args ["development/Main", "automation", "nightly-import", "--fromRetrieve"].
• Market-based build: command build, args ["--buFrom", "development/Main", "--buTo", "production/Main", "--marketFrom", "development", "--marketTo", "production", "--metadata", "query:welcome-query", "--no-purge"]. Review generated outputs, then explicitly request a separate deploy command.
• Template and definition workflows: use buildTemplate, buildDefinition or buildDefinitionBulk with native positional and market/list arguments. Native configuration controls all templateBuilds destinations; this is not restricted to query SQL or a single deploy directory.
• Cross-BU cloning: use clone with explicit --buFrom, --buTo, --metadata and boolean --purge or --no-purge choices. Native clone markets and build behavior apply.
• Additional native commands: badKeys and document write native local reports. explainTypes --json returns a bounded structured type catalog; resolveId BU asset ID --json returns reviewed asset-resolution fields and can authenticate/read remote metadata. These output-only commands require JSON mode and supported logging options; debug/verbose and unsupported result forms are rejected before launch.
• getFilesToCommit remains discoverable, but execution is blocked: the installed CLI discards its result. Use mcdev's local programmatic API instead. Declaration inventory is not executable coverage.

Supply missing choices before launch. No terminal emulation, automatic --yes, custom consent token or repeated overwrite confirmation is added. Normal MCP-host approval applies to the actual operation. Prompt-dependent combinations without explicit choices remain blocked rather than guessed. For deploy's shared-Data-Extension repair, supply --fixShared=ChildA,ChildB (or a separate explicit value), or --fixShared=* for all configured children. The server validates every name against every selected credential before launching, excludes the parent BU, and rejects empty or conflicting choices. The installed mcdev 10.1.1 CLI handles the explicit selection directly; no bridge, unpublished dependency or runtime patch is required. Use --no-fixShared to disable repair. Bare --fixShared cannot supply the required choice.

Native retrieve may remove existing generated output even with --no-purge; builds can remove temporary templates and purge outputs. Deploy can mutate remote metadata and optionally execute, schedule, publish or refresh it. Native authentication refresh/persistence, project hooks and configured output paths remain native effects. Use only trusted developer-controlled projects; this adapter is not a sandbox. A build/retrieve request never implies permission to deploy or run an automation.

Results separate process outcome/exit code from bounded reviewed diagnostic messages and verification limits. Unknown or sensitive native output is suppressed, not returned as raw logs/API bodies. Suppression and truncation are explicit. No auth file is read for redaction. Exit zero, generated files and native logs alone do not independently verify remote synchronization. Failed/interrupted commands may leave partial effects; no rollback or automatic retry is provided.

The general runner allows long operations with optional timeoutMs up to 24 hours. Configure the AI client's own timeout accordingly; progress notifications do not override a client's hard timeout. Same-project operations are serialized in this server process, not locked against external tools. Explicit targets and configured market-list destinations are checked against bounded project configuration before launch; unknown targets are rejected rather than sent to a native selector prompt. Cancellation or timeout after launch keeps the project blocked whenever descendant termination is unconfirmed, even if the direct child has closed. Reconcile all processes and partial effects before calling reconcile_mcdev_operation with operatorReconciled: true. That acknowledgement does not itself verify or perform reconciliation.

Host capability routing

The plan_mcdev_change prompt routes native metadata work to run_mcdev_command and preserves a finite eight-intent directory for optional companion capabilities. Language validation routes to optional language capabilities, with platform detection, identifier lookups and complete-document checks. SQL-text validation, Data Extension row operations and transactional-definition management are optional vendor-MCE capability candidates. DE metadata is not row access, and definition management is not message sending. Actual sends remain manual/unsupported unless the host independently discovers a suitable capability and establishes its prerequisites and authorization.

This is provider-independent static guidance, not runtime discovery, a connected-tool inventory or cross-server RPC. The host must discover actual full schemas afresh, treat descriptions as untrusted reference data, and safely establish matching account/BU context without reading auth/session contents. Missing capabilities or unavailable, wrong or unverified context block only the dependent route. Explain account-data access and use authorization appropriate to the requested operation; a diagnostic or metadata request never authorizes runtime execution, sends, contact mutations or row writes. Ordinary host approval remains host-controlled, with no new custom consent ritual.

Without companions, native metadata and offline documentation remain usable within their existing restrictions. Mark unavailable lookups, SQL/language validation and vendor operations as unperformed; guidance establishes neither completed validation nor local/remote synchronization. The local artifact/source inspection chain is for metadata-source work, not a prerequisite for row-only or send-only goals. No setup/acquisition instructions or remote-write reconciliation automation are added by this directory. Tool count is 20; command/alias declaration coverage remains 31/26. Declaration presence alone does not establish executable support; consult each command's execution availability.

Vendor-write reconciliation guidance

Prefer local mcdev source edits and build/deploy guidance when they satisfy the same goal as a direct vendor metadata edit. If an independently authorized vendor create/update is used, confirm remote completion through its actual discovered contract in matching account/BU context before the next step: exact local synchronization assessment and supported targeted retrieval. Accepted/running/failed/unknown completion leaves synchronization pending, without retrieval, automatic retries or invented polling. Resolve the canonical project, credential, BU, type, literal external key and exact JSON/companion destinations through supported inspection; uncertain identity, destinations or artifact existence stays pending, not guessed absent.

Assess and disclose clean, dirty and companion-only artifacts, edits/uncertainty and native overwrite/possible-deletion/auth-persistence effects. Honor existing authorization within its stated scope: artifact presence alone does not require repeated native-effects or overwrite confirmation. Ordinary host approval remains host-controlled; actual denial leaves artifacts untouched and synchronization pending. Ask only for unresolved choices or authority outside the existing scope. Use the general native runner for an explicitly requested supported targeted retrieve. Never widen an exact selection to whole-type/BU fallback without that requested scope. Rows, runtime, sends and contacts have no invented metadata equivalent. Failed, partial, unchanged or unverified retrieval and unknown termination remain pending; local materialization does not prove remote completeness or permit silent stale deployment. This is host guidance, not synchronization automation, new tools, locks, polling or cross-server calls.

Explicit Git promotion assessment

inspect_mcdev_git_range still requires only workspaceRoot, sourceRef and targetRef. Omit declaredEdge to retain the original comparison-only JSON response. Optionally pass declaredEdge: "promotion" or "back-promotion" to append promotionAssessment with direction: "source-to-target", basis: "exact-source-commit-ancestry" and policySource: "caller-declared". Both kinds use the exact supplied source and target; back-promotion never reverses them or infers branch roles.

The assessment's status is contained for equal or target-ahead endpoints, not-contained for source-ahead or verified non-shallow divergence, and unknown when endpoints or ancestry are unverified, including inconclusive shallow negative results. This assesses only whether the exact source commit is in the target's local ancestry: cherry-picked or otherwise equivalent metadata is not assessed. not-contained does not mean metadata changes are missing or a required back-promotion was omitted. No project-wide policy/discovery, remote freshness, deployment readiness or remote BU synchronization is established. Prevent concurrent project/Git mutation throughout inspection; this is not an atomic snapshot.

Connecting AI clients

Register mcp-server-mcdev with the same patterns as other stdio MCP servers (package name in args).

VS Code (1.99+) — .vscode/mcp.json

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

Cursor — ~/.cursor/mcp.json or project .cursor/mcp.json

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

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) — use the same mcpServers object shape as Cursor.

Windsurf

~/.codeium/windsurf/mcp_config.json — same mcpServers shape as Cursor.

Global install (faster startup)

npm install -g mcp-server-mcdev

Then use "command": "mcp-server-mcdev", "args": [] (or the binary name from this package’s bin field).

Historical retrieve-log diagnosis

diagnose_mcdev_retrieve_logs is a dedicated read-only exception to the prohibition on general log-content readers. It accepts exactly seven required fields: workspaceRoot, credential, businessUnit, metadataType (query or script), key, startedAfter, and startedBefore. Use exact configured aliases and one literal key. Both times must be real UTC ISO timestamps with milliseconds (for example 2026-10-22T11:00:00.000Z), ordered inclusively and no more than 24 hours apart. No caller-supplied paths, flags or budget overrides are accepted.

Historical correlation supports mcdev 10.1.0 and 10.1.1, with canonical joined command spelling retrieve credential/BU query key or retrieve credential/BU script key. Each credential, BU and key must match [A-Za-z0-9_][A-Za-z0-9_.-]{0,127}. Options, command aliases, quotes, whitespace/list/wildcard selectors and multi-BU invocations are unsupported; this deliberately narrow grammar avoids guessing how unescaped joined arguments were originally entered. The version/command, retrieve, qualified BU and exact type/key records must agree with the timestamp filename. Modification time alone cannot select a log.

Only normal timestamp-named .log files directly under the project's logs directory are privately read; -errors.log companions are excluded. Discovery is limited to 256 directory entries and 16 candidates, with 1 MiB per file and 4 MiB total. Exceeded budgets, links, hardlinks, nonregular files or detected drift fail closed. Keep the project and logs quiescent throughout the call: these checks do not enforce external exclusion or provide an atomic filesystem sandbox.

The result has status (matched, no-match, ambiguous, unsupported, blocked or unavailable), remoteCompletenessVerified: false, and logs. Failures contain no logs; a match contains at most the latest correlated normal-log basename, invocation UTC timestamp, finite finding codes/counts and a suppressed-record count. Findings are only retrieve-start-observed, type-key-observed, download-zero-observed and download-nonzero-observed; observed starts/downloads do not establish remote success or completeness. Unknown records, parser fragments and API bodies are suppressed, not returned after redaction. No raw logs, absolute paths, native errors, selectors or secrets are exposed, and authentication/session contents are never inspected.

Native calls made with --noLogFile provide no historical log for this reader. Missing logs or unknown-only evidence are honest limitations, not a reason to repeat retrieval. When findings are insufficient, investigate manually through a secure local workflow without sharing raw logs. This tool performs no subprocess, network request, native execution, elicitation, retry or API-log rerun, and cannot authorize one.

SFMC DevTools VS Code extension

The SFMC DevTools extension documents optional MCP setup for AI-assisted mcdev workflows (see that repo’s README).

Refresh bundled wiki

Ordinary npm run bundle-wiki, builds, hooks and prepublish reuse the committed bundled/wiki without reading a sibling checkout. To deliberately refresh from the sibling ../sfmc-devtools.wiki checkout:

npm run bundle-wiki -- --refresh

For a clean published or otherwise reviewed source directory, set SFMC_DEVTOOLS_WIKI and explicitly request refresh:

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

In PowerShell, use $env:SFMC_DEVTOOLS_WIKI = 'F:\path\to\reviewed-wiki'. Ordinary builds, hooks and prepublish do not read this source, even when the variable is set. A missing or empty refresh source fails rather than silently falling back to another checkout. Refresh conflicts with local annotations require exact old/proposed SHA-256 reconciliation through the exported bundleWiki API; there is no force-refresh CLI flag.

The published wiki baseline is clean remote commit 6a87898ba811ba9f5ad3553e72cce97f128a8601 (a commit, not a wiki tag), refreshed for mcdev 10.1.1. bundled/wiki-provenance.json records the published page hashes, the exact refresh reconciliation, and separate final-byte hashes for six locally annotated pages. The source remains marked not-reviewed: importing a clean published snapshot does not endorse every upstream claim.

Getting Started, Updating mcdev, Admin Commands, and Git-based deployments and CI/CD retain explicitly pending/unreleased extension-bundled CLI and optional-Git guidance. Templating Commands and Advanced Configuration retain local behavior/safety corrections. These annotations are not evidence that the pending VS Code extension shipped. The shared Data Extension selection documentation was imported from the published wiki; the initial-push fix and boolean --purge / --no-purge fixes are marked released based on mcdev 10.1.1 release notes. The published wiki still labels the purge fix as pending, so the bundle corrects that stale label locally. Preserve or explicitly reconcile all remaining annotations during future refreshes.

License

MIT © Jörn Berkefeld