Webp Batch MCP

🚀 WebP批量转换器

WebP批量转换器是一个支持跨平台的模型上下文协议（MCP）服务器，可将图像批量转换为WebP格式。它能与支持MCP的集成开发环境（IDE）（如Cursor）无缝协作，高效解决图像格式转换问题，为开发者提供便利。

✨ 主要特性

• 🖼️ 支持将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问题跟踪器。