Webp Batch MCP

🚀 WebP批量转换器

这是一个模型上下文协议（MCP）服务器，用于将图像批量转换为WebP格式，支持跨平台使用。它能与支持MCP的集成开发环境（IDE）（如Cursor）无缝协作。

🚀 快速开始

WebP批量转换器可帮助你将多种格式的图像批量转换为WebP格式。你可以通过以下几种方式进行安装和使用。

✨ 主要特性

• 🖼️ 支持将PNG、JPG和JPEG文件批量转换为WebP格式。
• 🌍 具备跨平台支持能力，可在macOS、Linux和Windows系统上运行。
• ⚡ 采用多线程处理，实现快速转换。
• 🎛️ 提供灵活的选项，包括质量控制、无损模式和元数据保留。
• 📊 能提供详细报告，包含文件大小和节省的统计信息。
• 🔧 支持双引擎，优先使用Google的cwebp，若不可用则回退到Sharp。
• 🎯 可与MCP集成，适用于人工智能驱动的开发环境。

📦 安装指南

全局安装

npm install -g webp-batch-mcp

本地开发

git clone https://github.com/mhe8mah/webp-batch-mcp.git
cd webp-batch-mcp
npm install
npm run build

Docker安装

docker build -t webp-batch .
docker run -v /path/to/images:/data webp-batch

💻 使用示例

基础用法

命令行界面

node dist/cli.js [options]

选项说明

• --src <dir> - 要扫描的源目录（默认：当前目录）
• --quality <0-100> - WebP质量设置（默认：75）
• --lossless - 使用无损编码（推荐用于PNG）
• --overwrite - 用WebP版本替换原始文件
• --threads <n> - 并发转换的数量（默认：CPU核心数）
• --preserve-meta - 保留EXIF和ICC元数据
• --flat <dir> - 将所有WebP文件输出到指定目录

示例

# 转换当前目录中的所有图像
node dist/cli.js

# 对特定目录进行高质量转换
node dist/cli.js --src ./photos --quality 95 --preserve-meta

# 无损转换并覆盖原始文件
node dist/cli.js --src ./images --lossless --overwrite

# 批量处理并输出到指定目录
node dist/cli.js --src ./input --flat ./output --threads 8

高级用法

MCP服务器

MCP服务器提供了一个工具：convert_to_webp

工具参数

{
  "src": "string",          // 源目录（默认："."）
  "quality": "number",      // 质量范围0 - 100（默认：75）
  "lossless": "boolean",    // 无损模式（默认：false）
  "overwrite": "boolean",   // 替换原始文件（默认：false）
  "threads": "number",      // 并发线程数（默认：CPU核心数）
  "preserveMeta": "boolean", // 保留元数据（默认：false）
  "flat": "string"          // 输出目录（可选）
}

⚙️ 如何在Cursor中添加此服务器

1. 克隆并构建项目：

git clone https://github.com/mhe8mah/webp-batch-mcp.git
cd webp-batch-mcp
npm install
npm run build

2. 打开Cursor设置。
3. 导航到 功能 → MCP。
4. 添加新的服务器配置：

{
  "mcpServers": {
    "webp-batch": {
      "command": "node",
      "args": ["/path/to/webp-batch-mcp/dist/server.js"]
    }
  }
}

5. 重启Cursor。
6. convert_to_webp 工具将在你的AI对话中可用。

🔧 技术细节

转换策略

1. 主引擎：Google的 cwebp 工具（包含在libwebp-tools中）

   • 性能最快
   • 压缩效果最佳
   • 支持全部功能

2. 备用引擎：Sharp（Node.js）

   • 纯JavaScript实现
   • 无需外部依赖
   • 具备跨平台兼容性

输出行为

• 默认情况：在原始文件旁边创建 .webp 文件。
• 覆盖模式：用WebP版本替换原始文件。
• 扁平模式：将所有WebP文件输出到指定目录。
• 元数据保留：根据请求保留EXIF和ICC配置文件。

性能

• 默认情况下利用所有CPU核心。
• 使用p-limit并发处理图像。
• 提供实时进度反馈。
• 报告详细的转换统计信息。

🛠️ 开发

构建项目

npm run build

测试项目

npm test

开发模式

npm run dev

📊 测试结果

通过真实网页图像验证：

• JPEG（35KB → 17KB）：节省51%的空间。
• PNG（7.9KB → 2.8KB）：节省65%的空间。
• 总体：平均压缩率为53%。

📋 依赖项

运行时依赖

• @modelcontextprotocol/sdk - MCP服务器框架
• sharp - 图像转换备用工具
• chalk - 彩色终端输出
• commander - 命令行参数解析
• glob - 文件模式匹配
• p-limit - 并发控制

开发依赖

• typescript - 类型安全
• tsup - 快速TypeScript打包工具
• jest - 测试框架

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

🤝 贡献指南

1. 分叉仓库。
2. 创建功能分支。
3. 为新功能添加测试。
4. 确保所有测试通过。
5. 提交拉取请求。

🆘 支持

如有问题或功能请求，请使用 GitHub问题跟踪器。