code-explainer-mcp

Code Explainer MCP

Give your AI agent a way to show its work.

An MCP tool that lets AI visualize the code changes it made — rendering git diffs as interactive HTML pages with inline annotations.

What is this?

When an AI agent makes code changes, it usually just tells you what it did in text. This MCP gives the agent a better way to communicate: a visual diff with annotations.

AI makes changes to your code
       ↓
AI calls show_diff_explanation
       ↓
Browser opens with diff + AI's annotations inline

The AI can highlight the important lines and explain what each change does — right next to the code.

Features

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

Installation

git clone <repo>
cd code-explainer-mcp
npm install
npm run build

Configuration

Claude Code

claude mcp add code-explainer node /path/to/code-explainer-mcp/dist/index.js

Or add to ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "code-explainer": {
      "command": "node",
      "args": ["/path/to/code-explainer-mcp/dist/index.js"]
    }
  }
}

Cursor

Add to Cursor MCP settings:

{
  "mcpServers": {
    "code-explainer": {
      "command": "node",
      "args": ["/path/to/code-explainer-mcp/dist/index.js"]
    }
  }
}

Tool: show_diff_explanation

Renders a git diff with 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
annotations	array	No	Explanations 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 annotation to
explanation	string	Yes	Your explanation
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 explaining git diffs with visual output. The AI will get the diff, analyze the changes, and call the tool with appropriate annotations.

Example Usage

Ask your AI agent: "Explain the last commit"

The agent will:

• Run git diff HEAD~1 HEAD
• Analyze the changes
• 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"
}

• Browser opens with diff2html rendered diff + inline annotations

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.

License

MIT