# Salesforce Deployment Guard MCP

[![CI](https://github.com/qpulce-dev/salesforce-deployment-guard-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/qpulce-dev/salesforce-deployment-guard-mcp/actions/workflows/ci.yml)

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.

```bash
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:

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

Claude Desktop-compatible configuration:

```json
{
  "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:

```text
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

```text
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

```bash
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:

```bash
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