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.

License

MIT © 2026 Queanu Pulce