Unified Diff MCP Server

Unified Diff MCP 服务

为 Claude Desktop 打造的精美差异可视化工具。借助 GitHub Gist 集成和本地文件输出，将代码差异转换为令人惊艳的可视化对比。

✨ 功能

• 🎨 使用 diff2html 实现精美的 HTML 差异可视化
• 🌐 集成 GitHub Gist，即时分享
• 📁 本地文件输出（PNG/HTML）
• 🔄 自动删除功能，用于临时差异
• 🖥️ 跨平台支持（Windows、macOS、Linux）
• ⚡ 使用 Bun 运行时，性能出色
• 🛡️ 增强的安全性，为共享的差异提供多级保护
• 🔒 多级安全性（低/中/高），适用于不同场景

🚀 快速开始

通过 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"
}'

手动安装

1. 安装 Claude Desktop 和 Bun
2. 克隆并构建：

   git clone https://github.com/gorosun/unified-diff-mcp.git
   cd unified-diff-mcp
   bun install
   

3. 配置 Claude Desktop——参见下方的配置

🛠️ 工具概览

工具	用途	输出	适用场景
visualize_diff_html_content	浏览器显示与分享	GitHub Gist + HTML 预览 URL	快速分享、即时查看
visualize_diff_output_file	本地文件存储	PNG/HTML 文件	本地存储、演示

📖 使用示例

🎯 按用途选择最佳提示词

用途	推荐提示词	使用的工具	输出
快速预览	Please visualize and preview the following diff: 以下のdiffを可視化してプレビューしてください	visualize_diff_html_content	GitHub Gist + HTML 预览 URL
本地存储	Please visualize and save the following diff to a file: 以下のdiffを可視化してファイルに保存してください	visualize_diff_output_file	本地 HTML/PNG 文件
与他人分享	Please visualize the following diff and create a shareable link: 以下のdiffを可視化して共有リンクを作成してください	visualize_diff_html_content	带可分享 URL 的 GitHub Gist
导出图像	Please visualize and save the following diff as a PNG image: 以下のdiffを可視化してPNG画像で保存してください	visualize_diff_output_file	本地 PNG 图像
代码审查	Please visualize the following diff in side-by-side format: 以下のdiffをside-by-side形式で可視化してください	任一工具	并排对比
文档	Please visualize and save the following diff as an HTML file: 以下のdiffを可視化してHTMLファイルで保存してください	visualize_diff_output_file	本地 HTML 文件
🔒 安全分享	Please visualize this diff with high security: 以下のdiffを高セキュリティで可視化してください	visualize_diff_html_content	带自动删除功能的 Secret Gist

即时分享差异（GitHub Gist）

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

将差异保存到本地

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

🎛️ 配置

环境变量

变量	描述	默认值
GITHUB_TOKEN	GitHub 个人访问令牌（用于 Gist 集成）	visualize_diff_html_content 必需
DEFAULT_AUTO_OPEN	自动打开生成的文件	false
DEFAULT_OUTPUT_MODE	默认输出格式（html 或 image）	html

设置 GitHub 令牌

1. 前往 GitHub Settings > Personal Access Tokens
2. 生成具有 gist 权限范围的新令牌
3. 添加到环境中：

   export GITHUB_TOKEN="your_token_here"
   

Claude Desktop 配置

macOS：

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

Windows：

code %APPDATA%\Claude\claude_desktop_config.json

配置模板：

{
  "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"
      }
    }
  }
}

📋 参数参考

通用参数

参数	类型	默认值	描述
diff	string	(required)	统一差异文本
format	string	side-by-side	显示格式（line-by-line 或 side-by-side）
showFileList	boolean	true	显示文件列表摘要
highlight	boolean	true	启用语法高亮
oldPath	string	file.txt	原始文件路径
newPath	string	file.txt	修改后的文件路径
autoOpen	boolean	false	在浏览器中自动打开

GitHub Gist 专用参数

参数	类型	默认值	描述
expiryMinutes	number	30	自动删除时间（1-1440 分钟）
public	boolean	false	公开或私密 gist

本地文件专用参数

参数	类型	默认值	描述
outputType	string	html	输出格式（html 或 image）

🌍 平台支持

平台	自动打开	命令
Windows	✅	start（主要方式），explorer（备用方式）
macOS	✅	open（主要方式），AppleScript（备用方式）
Linux	✅	xdg-open

🔧 开发

开发模式（支持热重载）：

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

生产模式：

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

📚 高级用法

🔒 增强安全级别

如果没有 GitHub Token，或需要安全共享，可以选择多个安全级别：

安全级别	配置	功能	使用场景
🟢 低	私密 Gist + 60 分钟后自动删除	仅通过 URL 访问	代码示例、学习
🟡 中	私密 Gist + 密码 + 30 分钟后自动删除	需要 URL + 访问码	团队审查
🔴 高	私密 Gist + 密码 + 15 分钟后自动删除	URL + 访问码 + 短时有效	敏感代码

用法示例

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
 };

响应示例：

🔒 **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

🔄 回退功能

GitHub Token 不可用时，系统会回退到本地文件：

• 将 HTML 保存为临时文件
• 自动打开浏览器
• 根据安全级别管理文件

详细的设置和集成指南：

• 🇺🇸 英语：CLAUDE_CODE_INTEGRATION.md
• 🇯🇵 日语：CLAUDE_CODE_INTEGRATION_JP.md

🤝 支持的客户端

• Claude Desktop（主要）
• Claude Code（CLI）
• VS Code + MCP Extension
• Cline 及其他 MCP 客户端

📄 许可证

MIT License - 详情请参阅 LICENSE 文件。

依赖项

库	许可证	用途
diff2html	MIT	生成 HTML 差异
playwright-core	Apache 2.0	浏览器自动化
@modelcontextprotocol/sdk	MIT	MCP 集成

---

为 Claude Desktop 社区倾心打造 ❤️