图片压缩 MCP 服务

智能图片压缩 MCP 服务，自动检测 Git 仓库中更改的图片文件并压缩。如果不是 Git 仓库，则扫描常见的静态资源目录并压缩所有图片。

✨ 功能特性

• 🤖 智能检测：自动判断 Git 仓库或非 Git 仓库
• 📦 Git 集成：自动压缩新增、修改、未跟踪的图片
• 🎯 自动扫描：非 Git 仓库时扫描常见静态资源目录
• 🔄 备份保护：压缩前自动备份，失败可恢复
• 📊 简洁报告：清晰的成功/失败统计
• 🎨 格式支持：支持 PNG、JPG、JPEG 格式
• ⚡ 高效快速：使用免费 Tinify API，压缩速度快
• 🚫 智能过滤：自动跳过已删除文件和过大文件

🎯 使用场景

场景 1：Git 仓库（推荐）

# 修改了一些图片
git status
# modified:   src/assets/images/logo.png
# modified:   src/assets/images/banner.png

# 在 Cursor 中使用 MCP
# "压缩图片"
# => 自动检测并压缩修改的图片

场景 2：新增图片

# 添加了新图片
cp new-image.png src/assets/images/

# 使用 MCP 压缩
# "压缩图片"
# => 自动检测并压缩新增的图片

场景 3：非 Git 仓库

# 非 Git 仓库的项目
# 使用 MCP 压缩
# "压缩图片"
# => 自动扫描 assets、images 等常见目录并压缩

📖 使用说明

MCP 工具

只有一个工具：compress_images

参数： 无

功能：

• 如果是 Git 仓库：压缩新增、修改、未跟踪的图片
• 如果不是 Git 仓库：扫描常见静态资源目录并压缩所有图片

返回格式：

成功示例：

✅ 压缩完成

成功: 2 张
| 文件名 | 原始大小 | 压缩后 | 节省 | 压缩比 |
|--------|----------|--------|------|--------|
| logo.png | 120 KB | 85 KB | 35 KB | 29.17% |
| banner.png | 500 KB | 350 KB | 150 KB | 30.00% |

总计节省: 185 KB (29.68%)

失败示例：

失败示例：

❌ 压缩失败

失败: 1 张
- background.jpg: 网络连接超时

混合示例（成功+失败）：

✅ 压缩完成

成功: 2 张
| 文件名 | 原始大小 | 压缩后 | 节省 | 压缩比 |
|--------|----------|--------|------|--------|
| logo.png | 120 KB | 85 KB | 35 KB | 29.17% |
| banner.png | 500 KB | 350 KB | 150 KB | 30.00% |

总计节省: 185 KB (29.68%)

❌ 压缩失败

失败: 1 张
- background.jpg: 网络连接超时

没有图片：

✅ 没有找到需要压缩的图片文件

检测模式: Git 仓库

⚙️ 配置

自动扫描的目录（非 Git 仓库）

当检测到非 Git 仓库时，会自动扫描以下目录：

assets/
images/
image/
img/
static/
public/
resources/
src/assets/
src/images/
src/image/
src/img/
public/assets/
public/images/
static/assets/
static/images/

注意： 如需添加更多目录，请编辑 mcp-server.js 中的 commonImageDirs 数组（有详细注释）。

自动排除的目录

以下目录会被自动跳过：

• node_modules
• dist
• build
• .git
• config
• coverage
• .next
• .nuxt
• target
• out

文件大小限制

• 默认最大支持 5MB 的图片
• 超过限制的图片会自动跳过

支持的图片格式

• PNG
• JPG
• JPEG

📁 项目结构

develop-mcp/
├── mcp-server.js       # MCP 服务器（主文件）
├── package.json        # 项目配置
├── README.md          # 本文件
├── INSTALL.md         # 安装和发布指南
└── .gitignore        # Git 忽略规则

🔧 技术细节

Git 检测原理

使用 git status --porcelain 命令获取更改的文件，解析状态码：

• M - Modified（已修改）
• A - Added（已添加）
• ? - Untracked（未跟踪）
• D - Deleted（已删除，跳过）

压缩流程

1. 检测当前目录是否为 Git 仓库
2. Git 仓库：获取更改的图片文件
3. 非 Git 仓库：扫描常见的静态资源目录
4. 过滤文件：排除过大文件、不支持的格式
5. 上传到 Tinify API 进行压缩
6. 下载压缩后的图片
7. 备份原文件（.bak）
8. 替换为压缩后的文件
9. 删除备份文件
10. 返回压缩结果

安全性

• 压缩前自动备份原文件
• 失败时保留原文件
• 仅处理支持的图片格式
• 跳过超过大小限制的文件
• 跳过已删除的文件

🚀 安装

详细的安装和发布指南请查看 INSTALL.md。

📝 团队使用

发布到 npm（推荐）

# 1. 登录 npm
npm login

# 2. 发布
npm publish

团队成员使用

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "image-compressor": {
      "command": "npx",
      "args": ["-y", "@caixm/image-compressor-mcp"]
    }
  }
}

然后重启 Cursor，即可使用！

详细步骤请查看 INSTALL.md。

❓ 常见问题

Q: MCP 工具不显示？

A:

1. 检查 .cursor/mcp.json 配置是否正确
2. 重启 Cursor IDE
3. 查看 Help > Open Logs

Q: 压缩失败？

A:

1. 检查网络连接
2. Tinify API 可能有频率限制，稍后再试
3. 查看错误提示信息

Q: 为什么某些图片没有被压缩？

A: 可能原因：

• 文件超过 5MB 大小限制
• 文件格式不支持（仅 PNG、JPG、JPEG）
• Git 仓库中文件已被删除
• 文件在排除的目录中

Q: 如何支持更多图片格式？

A: 编辑 mcp-server.js 中的 imgsInclude 数组：

const imgsInclude = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];

📄 许可证

MIT

🙏 致谢

使用 Tinify 免费服务进行图片压缩