Unified Diff MCP Server

Beautiful HTML and PNG diff visualization using diff2html, designed for filesystem edit_file dry-run output with high-performance Bun runtime.

GitHub

Unified Diff MCP Server

smithery badge

Beautiful diff visualization for Claude Desktop. Transform code diffs into stunning visual comparisons with GitHub Gist integration and local file output.

Unified Diff Visualization Screenshot

✨ Features

  • 🎨 Beautiful HTML diff visualization using diff2html
  • 🌐 GitHub Gist integration for instant sharing
  • 📁 Local file output (PNG/HTML)
  • 🔄 Auto-delete functionality for temporary diffs
  • 🖥️ Cross-platform support (Windows, macOS, Linux)
  • ⚡ High-performance with Bun runtime
  • 🛡️ Enhanced Security with multi-level protection for shared diffs
  • 🔒 Multi-level security (Low/Medium/High) for different use cases

🚀 Quick Start

Installing via Smithery

bunx @smithery/cli install @gorosun/unified-diff-mcp --client claude --config '{
  "defaultAutoOpen": true,
  "defaultOutputMode": "html",
  "githubUsername": "your_actual_github_username",
  "githubToken": "ghp_your_actual_token_here"
}'

Manual Installation

  1. Install Claude Desktop and Bun
  2. Clone and build: 
    git clone https://github.com/gorosun/unified-diff-mcp.git
cd unified-diff-mcp
bun install
  3. Configure Claude Desktop - see Configuration below

🛠️ Tools Overview

ToolPurposeOutputBest For
visualize_diff_html_contentBrowser display & sharingGitHub Gist + HTML preview URLQuick sharing, instant viewing
visualize_diff_output_fileLocal file storagePNG/HTML filesLocal storage, presentations

📖 Usage Examples

🎯 Optimal Prompts by Purpose

PurposeRecommended PromptTool UsedOutput
Quick PreviewPlease visualize and preview the following diff:
以下のdiffを可視化してプレビューしてください		visualize_diff_html_contentGitHub Gist + HTML preview URL
Local StoragePlease visualize and save the following diff to a file:
以下のdiffを可視化してファイルに保存してください		visualize_diff_output_fileLocal HTML/PNG file
Share with OthersPlease visualize the following diff and create a shareable link:
以下のdiffを可視化して共有リンクを作成してください		visualize_diff_html_contentGitHub Gist with shareable URL
Image ExportPlease visualize and save the following diff as a PNG image:
以下のdiffを可視化してPNG画像で保存してください		visualize_diff_output_fileLocal PNG image
Code ReviewPlease visualize the following diff in side-by-side format:
以下のdiffをside-by-side形式で可視化してください		Either toolSide-by-side comparison
DocumentationPlease visualize and save the following diff as an HTML file:
以下のdiffを可視化してHTMLファイルで保存してください		visualize_diff_output_fileLocal HTML file
🔒 Secure SharingPlease visualize this diff with high security:
以下のdiffを高セキュリティで可視化してください		visualize_diff_html_contentSecret Gist with auto-delete

Share diff instantly (GitHub Gist)

visualize_diff_html_content:
- Creates temporary GitHub Gist
- Auto-deletes after 30 minutes
- Instant browser-ready URLs
- Perfect for code reviews

Save diff locally

visualize_diff_output_file:
- Saves PNG or HTML to local disk
- Auto-opens in browser (optional)
- Perfect for documentation

🎛️ Configuration

Environment Variables

VariableDescriptionDefault
GITHUB_TOKENGitHub Personal Access Token (for Gist integration)Required for visualize_diff_html_content
DEFAULT_AUTO_OPENAuto-open generated filesfalse
DEFAULT_OUTPUT_MODEDefault output format (html or image)html

GitHub Token Setup

  1. Go to GitHub Settings > Personal Access Tokens
  2. Generate new token with gist scope
  3. Add to your environment: 
    export GITHUB_TOKEN="your_token_here"

Claude Desktop Configuration

macOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

code %APPDATA%\Claude\claude_desktop_config.json

Configuration template:

{
  "mcpServers": {
    "unified-diff-mcp": {
      "command": "bun",
      "args": ["run", "/path/to/unified-diff-mcp/src/index.ts"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "DEFAULT_AUTO_OPEN": "true",
        "DEFAULT_OUTPUT_MODE": "html"
      }
    }
  }
}

📋 Parameters Reference

Common Parameters

ParameterTypeDefaultDescription
diffstring(required)Unified diff text
formatstringside-by-sideDisplay format (line-by-line or side-by-side)
showFileListbooleantrueShow file list summary
highlightbooleantrueEnable syntax highlighting
oldPathstringfile.txtOriginal file path
newPathstringfile.txtModified file path
autoOpenbooleanfalseAuto-open in browser

GitHub Gist Specific

ParameterTypeDefaultDescription
expiryMinutesnumber30Auto-delete time (1-1440 minutes)
publicbooleanfalsePublic vs secret gist

Local File Specific

ParameterTypeDefaultDescription
outputTypestringhtmlOutput format (html or image)

🌍 Platform Support

PlatformAuto-OpenCommands
Windows✅start (primary), explorer (fallback)
macOS✅open (primary), AppleScript (fallback)
Linux✅xdg-open

🔧 Development

Development mode (with hot reload):

{
  "command": "bun",
  "args": ["--watch", "/path/to/unified-diff-mcp/src/index.ts"]
}

Production mode:

{
  "command": "bun",
  "args": ["run", "/path/to/unified-diff-mcp/src/index.ts"]
}

📚 Advanced Usage

🔒 Enhanced Security Levels

When GitHub Token isn't available or for secure sharing, you can choose from multiple security levels:

Security LevelConfigurationFeaturesUse Cases
🟢 LowSecret Gist + 60min auto-deleteURL-only accessCode examples, learning
🟡 MediumSecret Gist + Password + 30min auto-deleteURL + Access code requiredTeam reviews
🔴 HighSecret Gist + Password + 15min auto-deleteURL + Access code + Short durationSensitive code

Usage Example

Please visualize this diff with high security:
--- a/config.js
+++ b/config.js
@@ -1,3 +1,4 @@
 const config = {
-  apiKey: 'old-key'
+  apiKey: 'new-secure-key',
+  timeout: 5000
 };

Response Example:

🔒 **Secure Diff Visualization**

🔴 **Security Level**: High Security - Secret Gist + Password (15min auto-delete)
📋 **Preview Link**: https://htmlpreview.github.io/?...
🔑 **Access Code**: `a7x9k2`
⏰ **Auto-delete**: 15 minutes

🔄 Fallback Functionality

When GitHub Token is unavailable, the system falls back to local files:

  • HTML saved as temporary file
  • Automatic browser opening
  • Security-based file management

For detailed setup and integration guides:

🤝 Supported Clients

  • Claude Desktop (Primary)
  • Claude Code (CLI)
  • VS Code + MCP Extension
  • Cline and other MCP clients

📄 License

MIT License - see LICENSE file for details.

Dependencies

LibraryLicensePurpose
diff2htmlMITHTML diff generation
playwright-coreApache 2.0Browser automation
@modelcontextprotocol/sdkMITMCP integration

Made with ❤️ for the Claude Desktop community

相关服务器