Image Diff MCP

一个基于 MCP (Model Context Protocol) 协议的图片差异比较工具，支持通过 AI 助手进行图片对比分析。

功能特性

• 🔍 精确比较: 使用 pixelmatch 算法进行像素级图片比较
• 📊 差异统计: 提供详细的差异像素数量和百分比统计
• 🎨 可视化标记: 生成带有颜色标记的差异图片
  • 🟢 绿色：设计稿中存在但测试稿中缺少的区域
  • 🔴 红色：测试稿中额外的区域
• 📁 多种输入: 支持 base64 编码字符串和本地文件路径
• 💾 灵活输出: 可返回 base64 图片或保存到本地文件
• 🌐 双协议支持: 支持 stdio 和 HTTP Stream 两种传输协议
• 🔧 MCP 集成: 完全兼容 MCP 协议，可与支持 MCP 的 AI 助手无缝集成

安装

全局安装

npm install -g image-diff-mcp

本地开发

# 克隆项目
git clone <repository-url>
cd image-diff

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式
npm run dev

使用方法

1. 启动 MCP 服务器

HTTP Stream 模式（推荐）

# 使用默认配置启动
image-diff-mcp

# 自定义配置
image-diff-mcp --port 3000 --host 0.0.0.0 --endpoint /mcp

Stdio 模式

image-diff-mcp --stdio

2. 配置 AI 助手

将 MCP 服务器添加到您的 AI 助手配置中，例如在 Claude Desktop 的配置文件中：

{
  "mcpServers": {
    "image-diff": {
      "command": "image-diff-mcp",
      "args": ["--stdio"]
    }
  }
}

3. 使用图片比较功能

通过 AI 助手调用 imageDiff 工具：

请帮我比较这两张图片的差异：
- 设计稿：/path/to/design.png
- 测试稿：/path/to/test.png

API 参数

imageDiff 工具

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | designImage | string | ✅ | 设计稿图片，支持 base64 编码或本地文件路径 | | testImage | string | ✅ | 测试稿图片，支持 base64 编码或本地文件路径 | | outputPath | string | ❌ | 可选的输出路径，用于保存差异图片到本地 |

返回结果

interface ImageDiffResult {
  diffImage: string;        // base64 编码的差异图片
  pixelDiffCount: number;   // 不同像素的数量
  totalPixels: number;      // 总像素数
  diffPercentage: number;   // 差异百分比
  outputPath?: string;      // 保存路径（如果指定了 outputPath）
}

技术架构

核心技术栈

• MCP 协议: 基于 @modelcontextprotocol/sdk
• 图片处理: pngjs + pixelmatch
• Web 框架: Express.js (HTTP 模式)
• 构建工具: Rollup + TypeScript
• CLI 工具: Commander.js

项目结构

src/
├── index.ts                    # CLI 入口文件
├── mcp/                        # MCP 服务器相关
│   ├── createMcpServer.ts      # MCP 服务器创建器
│   ├── startStdioMcpServer.ts  # Stdio 传输服务器
│   ├── startHttpMcpServer.ts   # HTTP Stream 传输服务器
│   └── image_diff/             # 图片比较功能
│       ├── index.ts            # MCP 工具注册
│       └── imageDiff.ts        # 核心比较逻辑
└── type.d.ts                   # 类型定义

开发指南

可用脚本

npm run dev        # 开发模式（监听文件变化）
npm run build      # 构建生产版本
npm run test       # 运行测试
npm run test:watch # 监听模式运行测试
npm run release    # 发布新版本

测试

# 运行所有测试
npm test

# 生成覆盖率报告
npm run test:coverage

配置选项

HTTP 服务器选项

| 选项 | 默认值 | 描述 | |------|--------|------| | --port | 3000 | 服务器端口 | | --host | 0.0.0.0 | 服务器主机 | | --endpoint | /mcp | MCP 端点路径 | | --no-cors | false | 禁用 CORS |

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v0.0.1

• 初始版本发布
• 支持基本的图片差异比较功能
• 支持 MCP 协议的 stdio 和 HTTP Stream 传输