# image diff mcp

**Repository Path**: jeoy/image-diff-mcp

## Basic Information

- **Project Name**: image diff mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-25
- **Last Updated**: 2025-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Image Diff MCP

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

## 功能特性

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

## 安装

### 全局安装

```bash
npm install -g image-diff-mcp
```

### 本地开发

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

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式
npm run dev
```

## 使用方法

### 1. 启动 MCP 服务器

#### HTTP Stream 模式（推荐）

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

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

#### Stdio 模式

```bash
image-diff-mcp --stdio
```

### 2. 配置 AI 助手

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

```json
{
  "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 | ❌ | 可选的输出路径，用于保存差异图片到本地 |

### 返回结果

```typescript
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                   # 类型定义
```

## 开发指南

### 可用脚本

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

### 测试

```bash
# 运行所有测试
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 传输