Salesforce Deployment Guard MCP

A local-only Model Context Protocol server that turns Salesforce-style deployment evidence into structured findings and remediation steps.

This is a clean-room portfolio project. It uses deterministic rules and synthetic examples—no Salesforce org, credentials, LLM, telemetry, or network access.

Tools

Tool	Purpose
`analyze_deployment_log`	Classifies missing metadata, invalid references, Apex test failures, permission failures, malformed XML, and unknown evidence.
`validate_metadata_manifest`	Detects missing dependencies, duplicates, invalid names, self-dependencies, and cycles.
`assess_permission_risk`	Flags broad system permissions, object Modify All, duplicate changes, and write-without-read combinations.
`build_remediation_plan`	Turns findings into a deterministic, priority-ordered checklist.

Every tool is read-only and returns both human-readable text and structured JSON.

Quick start

Requirements: Node.js 20.19 or newer.

git clone https://github.com/qpulce-dev/salesforce-deployment-guard-mcp.git
cd salesforce-deployment-guard-mcp
npm ci
npm run verify
npm run build

Connect an MCP client

Codex CLI:

codex mcp add salesforce-deployment-guard -- node "/absolute/path/to/salesforce-deployment-guard-mcp/dist/server.js"

Claude Desktop-compatible configuration:

{
  "mcpServers": {
    "salesforce-deployment-guard": {
      "command": "node",
      "args": [
        "/absolute/path/to/salesforce-deployment-guard-mcp/dist/server.js"
      ]
    }
  }
}

Restart the client after changing its MCP configuration.

Live MCP transcript

Captured from a real MCP client connected to the built server over stdio:

connected: salesforce-deployment-guard-mcp
tools: analyze_deployment_log, validate_metadata_manifest, assess_permission_risk, build_remediation_plan
call: analyze_deployment_log
arguments: {"log":"Error: no CustomField named Demo__c.Region__c found"}
{
  "status": "issues_found",
  "findings": [
    {
      "code": "SF_MISSING_METADATA",
      "category": "missing_dependency",
      "severity": "error",
      "evidence": "Error: no CustomField named Demo__c.Region__c found",
      "likelyCause": "A referenced metadata component is absent from the deployment set or target org.",
      "nextChecks": [
        "Confirm the referenced component exists in source control.",
        "Add the dependency to the deployment manifest before its consumer."
      ]
    }
  ]
}

The fixtures/ directory contains additional synthetic inputs.

Architecture

MCP client
  -> Zod input schema
  -> small tool handler
  -> deterministic domain function
  -> structured JSON + concise text

src/server.ts registers tools and owns stdio startup.
src/domain/ contains pure diagnostic and planning logic.
src/tools/result.ts formats stable MCP responses.
tests/ covers domain behavior, privacy rules, and a real stdio MCP handshake.
fixtures/ contains synthetic examples only.

Verification

npm run verify

That command runs formatting, ESLint, strict TypeScript checks, 39 tests, a production build, and the privacy scan. The MCP smoke test launches the built server, negotiates a client connection, lists all four tools, and calls one tool.

CI runs the same verification on Node.js 20.19 and 22.

Privacy and security

No runtime network calls.
No data persistence or telemetry.
No environment variables or credentials required.
Inputs are bounded before analysis.
Errors do not return stack traces or local paths.
Included examples use names such as Demo__c and Demo_Access.
The privacy scanner reports only file and rule identifiers, never matched secret text.

For an extra local organization-name check:

PRIVATE_ORG_NAMES="Private Org One,Private Org Two" npm run privacy:scan

Do not paste real production logs into public issues, commits, or fixtures.

Limits

This server provides deterministic review guidance. It does not connect to Salesforce, validate against a live org, replace a security review, or guarantee deployment success. Unknown evidence stays classified as unknown.