MCP Setup

The @diffpulse/mcp package exposes DiffPulse as a Model Context Protocol (MCP) server. Your editor's AI can call DiffPulse tools during code review — without DiffPulse calling OpenAI, Anthropic, or any other hosted AI provider.

How it works

DiffPulse runs deterministic checks and returns structured JSON. Your editor's model reads that output and decides what to tell you. DiffPulse never sends your code or diffs to external AI services.

Install

No global install required — use npx in your MCP config:

npx -y @diffpulse/mcp

Or add as a dev dependency if you prefer a pinned local install:

npm install -D @diffpulse/mcp

Cursor configuration

Add a server entry to .cursor/mcp.json in your project (or global Cursor MCP settings):

{
  "mcpServers": {
    "diffpulse": {
      "command": "npx",
      "args": ["-y", "@diffpulse/mcp"]
    }
  }
}

Set cwd to your repository root if the MCP server should evaluate a specific project:

{
  "mcpServers": {
    "diffpulse": {
      "command": "npx",
      "args": ["-y", "@diffpulse/mcp"],
      "cwd": "/path/to/your/repo"
    }
  }
}

Restart Cursor or reload MCP servers after saving the config. Run diffpulse init first if your repo does not yet have a policy file.

Tools

`diffpulse_check`

Run deterministic PR risk evaluation for the current repository. Returns the full EvaluationReport JSON — verdict, risk score, merge readiness, checks, and findings.

Input	Description
`repoRoot`	Git repository root (defaults to server working directory)
`base`	Base git ref (defaults to policy or remote default branch)
`policy`	Path to policy YAML (default: `.diffpulse/policy.yaml`)
`failOn`	Exit semantics threshold: `pass`, `warn`, or `block`

`diffpulse_policy_summary`

Load and summarize your DiffPulse policy — enabled checks, thresholds, pattern counts, and validation status. Useful before tuning policy or explaining why a check fired.

Input	Description
`repoRoot`	Git repository root (optional)
`policy`	Path to policy YAML (optional)

`diffpulse_explain_report`

Produce a deterministic natural-language explanation of an evaluation report. Includes verdict summary, triggered checks, dimension notes, and remediation hints — all template-based, with no external AI calls.

Input	Description
`report`	Inline `EvaluationReport` JSON object
`reportPath`	Path to a `diffpulse-report.json` file
`format`	`summary`, `markdown`, or `findings_detail`

Provide either report or reportPath, not both.

Example workflow

Run npx @diffpulse/cli init to scaffold policy and CI.
Add the MCP config above to Cursor.
Ask your assistant: "Run diffpulse_check on this branch."
Follow up with diffpulse_explain_report for remediation guidance.

CLI equivalent

The MCP tools wrap the same engine as the CLI:

# diffpulse_check ≈
npx @diffpulse/cli check --format json

# diffpulse_policy_summary ≈
npx @diffpulse/cli config validate

# diffpulse_explain_report ≈
# (deterministic explain layer — MCP-only structured narrative)

Troubleshooting

Policy not found — run npx @diffpulse/cli init in the repository root.
Not a git repository — ensure cwd points to a git repo with commits.
Verify the binary — npx @diffpulse/mcp --help