Explain Changes MCP

AI peer review for your code changes.

Just like humans review each other's PRs, your AI reviews its own changes — with inline annotations that appear directly in the diff.

---

Why AI Peer Review?

When humans write code, we do peer review. When AI writes code, we... scroll through chat hoping we understood what it did?

The asymmetry is broken. AI generates multi-file changes in seconds, but understanding those changes still requires you to:

• Read the chat explanation
• Open the diff
• Mentally map one to the other

This MCP gives AI the same workflow humans use: review the diff, annotate the changes, explain the reasoning.

---

How It Works

AI makes changes → AI reviews its own diff → Browser opens with annotated diff

The AI calls show_diff_explanation after completing a task. You get a visual diff with inline annotations — exactly where a human reviewer would leave comments.

Works on any git diff: commits, PRs, branches. Action buttons let you ask follow-up questions right from the review.

---

Features

• Visual diff — Side-by-side or unified view powered by diff2html
• Inline annotations — Review comments appear directly after relevant code lines
• Action buttons — Follow-up prompts ("Add tests", "Refactor this", "Security review")
• Click to open — File names link to VS Code or Cursor
• GitHub dark theme — Clean aesthetics

---

Installation

Prerequisites

• Node.js >= 18.0.0
• MCP Client (Cursor, Claude Code, VS Code, Windsurf, etc.)

Quick Start

1. Install the MCP Server

The MCP server runs via npx. Configure it in your MCP client (see Client-Specific Setup below).

---

Client-Specific Setup

Cursor

One-Click Install

Manual Install

Go to Cursor Settings → MCP → Add new global MCP server

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

Claude Code

Use the Claude Code CLI:

claude mcp add explain-changes-mcp npx -y explain-changes-mcp@latest

Or manually edit ~/.claude/config.json:

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

VS Code / VS Code Insiders

Or add to settings.json:

{
  "mcp.servers": {
    "explain-changes-mcp": {
      "command": "npx",
      "args": ["-y", "explain-changes-mcp@latest"]
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

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

Claude Desktop

Follow the MCP install guide, then add to claude_desktop_config.json:

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

---

Tool: show_diff_explanation

Renders a git diff with review annotations in the browser.

Parameters

Parameter	Type	Required	Description
title	string	Yes	Page title
diff	string	Yes	Raw git diff output (unified format)
summary	string	No	High-level overview of changes
annotations	array	No	Review comments for specific changes
globalActions	array	No	Action buttons in the header
editor	string	No	"vscode", "cursor", or "auto"

Annotation Object

Field	Type	Required	Description
file	string	Yes	File path
line	number	No	Line number to attach comment to
explanation	string	Yes	Review comment
actions	array	No	Array of { label, prompt } for action buttons

Action Object

Field	Type	Required	Description
label	string	Yes	Button label
prompt	string	Yes	Prompt to pre-fill in Cursor chat

---

MCP Prompt

explain-changes

Instructions for reviewing git diffs with visual output. The AI will get the diff, review the changes, and call the tool with appropriate annotations.

---

Example Usage

Ask your AI agent: "Explain the last commit"

The agent will:

1. Run git diff HEAD~1 HEAD
2. Review the changes
3. Call show_diff_explanation:

{
  "title": "Add JWT Authentication",
  "summary": "Added JWT auth middleware and applied to API routes.",
  "diff": "diff --git a/src/auth.ts b/src/auth.ts\n...",
  "annotations": [
    {
      "file": "src/auth.ts",
      "line": 5,
      "explanation": "Extracts Bearer token from Authorization header",
      "actions": [
        { "label": "Add tests", "prompt": "Write unit tests for this auth middleware" }
      ]
    }
  ],
  "globalActions": [
    { "label": "Security Review", "prompt": "Review this code for security vulnerabilities" }
  ],
  "editor": "cursor"
}

4. Browser opens with diff2html rendered diff + inline review comments

---

Development

npm run dev

Opens http://localhost:3456 with hot reload. Edit src/html-generator.ts to change styling, dev/server.mjs to change mock data.

---

Inspiration

Inspired by Cline's /explain-changes feature.

---

License

MIT