explain-changes-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Structure

Monorepo with two packages:

• packages/mcp - MCP server that provides the show_diff_explanation tool
• packages/extension - VS Code/Cursor extension that displays diff explanations in a webview panel

Commands

# Root commands
npm run build            # Build all packages
npm run build:mcp        # Build MCP server only
npm run build:extension  # Build extension only

# Extension (from packages/extension)
npm run dev              # Dev server at http://localhost:3457 for webview debugging
npm run watch            # Watch mode for extension development
npm run package          # Create .vsix file

# MCP (from packages/mcp)
npm run build            # Compile TypeScript to dist/
npm run start            # Run MCP server via stdio

Architecture

MCP Server                    VS Code Extension
     │                              │
     │ writes JSON to               │ watches
     │ ~/.explain-changes/          │ ~/.explain-changes/
     │ pending.json                 │ pending.json
     │                              │
     └──────────────────────────────┘
                                    │
                                    ▼
                              Webview Panel
                              (renders diff + annotations)

MCP Package (packages/mcp)

• src/index.ts - MCP server entry point. Registers tool and prompt, writes JSON to ~/.explain-changes/pending.json

Extension Package (packages/extension)

• src/extension.ts - Extension entry point. Watches pending.json, auto-configures MCP in Cursor/Windsurf
• src/webviewProvider.ts - Creates webview panel, renders diff with diff2html, handles button clicks
• src/types.ts - Shared TypeScript types
• dev/server.mjs - Dev server for debugging webview in browser with mock data and HMR

Tool Schema

The show_diff_explanation tool accepts:

• title (required): Page title
• diff (required): Raw git diff output (unified format)
• summary: High-level overview
• annotations: Array of { file, line?, explanation, actions? }
• workspacePath: Absolute path to project (for workspace filtering)
• editor: "cursor" | "vscode"