项目介绍
Unified Diff MCP Server
用于 Claude Desktop 的美观差异可视化。通过与 GitHub Gist 集成和本地文件输出，将代码差异转换为令人惊叹的视觉比较。
<img src="examples/screenshot.png" alt="统一差异可视化截图" width="800" style="max-width: 100%; height: auto;">✨ 特性
- 🎨 使用 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"
}'
手动安装
- 安装 Claude Desktop 和 Bun
- 克隆并构建：
git clone https://github.com/gorosun/unified-diff-mcp.git cd unified-diff-mcp bun install - 配置 Claude Desktop - 参见下方的 配置
🛠️ 工具概述
| 工具 | 目的 | 输出 | 最佳用途 |
|---|---|---|---|
visualize_diff_html_content | 浏览器显示及分享 | GitHub Gist + HTML 预览 URL | 快速分享，即时查看 |
visualize_diff_output_file | 本地文件存储 | PNG/HTML 文件 | 本地存储，演示 |
📖 使用示例
🎯 根据目的推荐提示
| 目的 | 推荐提示 | 使用工具 | 输出 |
|---|---|---|---|
| 快速预览 | 请可视化并预览以下差异：<br>以下のdiffを可視化してプレビューしてください | visualize_diff_html_content | GitHub Gist + HTML 预览 URL |
| 本地存储 | 请可视化并保存以下差异到文件：<br>以下のdiffを可視化してファイルに保存してください | visualize_diff_output_file | 本地 HTML/PNG 文件 |
| 与其他分享 | 请可视化以下差异并创建一个可分享链接：<br>以下のdiffを可視化して共有リンクを作成してください | visualize_diff_html_content | 带有可分享 URL 的 GitHub Gist |
| 图像导出 | 请可视化并保存以下差异为 PNG 图像：<br>以下のdiffを可視化してPNG画像で保存してください | visualize_diff_output_file | 本地 PNG 图像 |
| 代码审查 | 请以并排格式可视化以下差异：<br>以下のdiffをside-by-side形式で可視化してください | 任一工具 | 并排比较 |
| 文档 | 请可视化并保存以下差异为 HTML 文件：<br>以下のdiffを可視化してHTMLファイルで保存してください | visualize_diff_output_file | 本地 HTML 文件 |
| 🔒 安全分享 | 请以高安全性可视化此差异：<br>以下のdiffを高セキュリティで可視化してください | visualize_diff_html_content | 自动删除的秘密 Gist |
即时分享差异（GitHub Gist）
visualize_diff_html_content:
- 创建临时 GitHub Gist
- 30分钟后自动删除
- 即时浏览器可用 URL
- 适合代码审查
本地保存差异
visualize_diff_output_file:
- 将 PNG 或 HTML 保存到本地磁盘
- 可选自动在浏览器中打开
- 适合文档
🎛️ 配置
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
GITHUB_TOKEN | GitHub 个人访问令牌（用于 Gist 集成） | 对于 visualize_diff_html_content 是必需的 |
DEFAULT_AUTO_OPEN | 是否自动打开生成的文件 | false |
DEFAULT_OUTPUT_MODE | 默认输出格式（html 或 image） | html |
GitHub 令牌设置
- 转到 GitHub 设置 > 个人访问令牌
- 生成具有
gist范围的新令牌 - 添加到您的环境：
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 | (必填) | 统一差异文本 |
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 | 公开 vs 秘密 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 令牌或需要安全分享时，可以选择多个安全级别：
| 安全级别 | 配置 | 功能 | 使用案例 |
|---|---|---|---|
| 🟢 低 | 秘密 Gist + 60分钟自动删除 | 仅 URL 访问 | 代码示例，学习 |
| 🟡 中 | 秘密 Gist + 密码 + 30分钟自动删除 | 需要 URL + 访问码 | 团队审查 |
| 🔴 高 | 秘密 Gist + 密码 + 15分钟自动删除 | 需要 URL + 访问码 + 短暂时间 | 敏感代码 |
使用示例
请以高安全性可视化此差异：
--- a/config.js
+++ b/config.js
@@ -1,3 +1,4 @@
const config = {
- apiKey: 'old-key'
+ apiKey: 'new-secure-key',
+ timeout: 5000
};
响应示例：
🔒 **安全差异可视化**
🔴 **安全级别**：高安全性 - 秘密 Gist + 密码（15分钟自动删除）
📋 **预览链接**：https://htmlpreview.github.io/?...
🔑 **访问码**：`a7x9k2`
⏰ **自动删除**：15分钟
🔄 备用功能
当没有 GitHub 令牌时，系统会回退到本地文件：
- 作为临时文件保存 HTML
- 自动在浏览器中打开
- 基于安全性的文件管理
对于详细的设置和集成指南：
🤝 支持的客户端
- Claude Desktop（主要）
- Claude Code（CLI）
- VS Code + MCP 扩展
- Cline 和其他 MCP 客户端
📄 许可证
MIT 许可证 - 详情见 LICENSE 文件。
依赖项
| 库 | 许可证 | 目的 |
|---|---|---|
| diff2html | MIT | HTML 差异生成 |
| playwright-core | Apache 2.0 | 浏览器自动化 |
| @modelcontextprotocol/sdk | MIT | MCP 集成 |
由 ❤️ 为 Claude Desktop 社区制作