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問題跟蹤器。