JinDaGe - webp-batch-mcp MCP Details

article

README

🚀 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中添加此服务器的步骤

克隆并构建项目：

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

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

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

重启Cursor。
convert_to_webp 工具将在您的AI对话中可用。

🔧 技术细节

转换策略

主引擎：Google的 cwebp 工具（包含在libwebp-tools中）
- 性能最快。
- 压缩效果最佳。
- 支持全部功能。
备用引擎：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文件。

🤝 贡献指南

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

🆘 支持

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

webp-batch-mcp