acg-frontend-mcp 0.1.4

Add your description here

ACG Frontend MCP

基于 Model Context Protocol (MCP) 的图片压缩服务，使用 Python 和 uv 构建。提供多种图片压缩算法和格式转换功能，支持批量处理。

功能特性

• 多种压缩模式：支持无损压缩、有损压缩、极度压缩等多种模式
• 格式转换：支持转换为 WebP 和 AVIF 格式
• 批量处理：可批量处理目录中的所有图片
• 透明度保留：PNG 透明度在所有压缩模式下都会保留
• 动画支持：GIF 动画可转换为 WebP 动画
• 灵活配置：支持质量、尺寸、压缩方法等多种参数配置

支持的图片格式

输入格式：PNG, JPG, JPEG, BMP, TIFF, GIF 输出格式：WebP, AVIF

系统要求

• Python: >= 3.12
• uv: 最新版本（推荐使用 uv 管理 Python 环境和依赖）

快速开始

1. 安装 uv

如果还没有安装 uv，请根据您的操作系统选择以下方式之一：

macOS

方法一：使用官方安装脚本（推荐）

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后，需要将 uv 添加到 PATH（如果提示）：

# 添加到 ~/.zshrc 或 ~/.bash_profile
export PATH="$HOME/.cargo/bin:$PATH"

方法二：使用 Homebrew

brew install uv

Linux

方法一：使用官方安装脚本（推荐）

curl -LsSf https://astral.sh/uv/install.sh | sh

如果系统没有 curl，可以使用 wget：

wget -qO- https://astral.sh/uv/install.sh | sh

安装完成后，需要将 uv 添加到 PATH（如果提示）：

# 添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"

方法二：使用 pipx 或 pip

# 使用 pipx（推荐）
pipx install uv

# 或使用 pip
pip install uv

Windows

方法一：使用 PowerShell 脚本（推荐）

打开 PowerShell（建议以管理员身份运行），执行：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

如果遇到执行策略错误，需要先运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

方法二：使用 pipx 或 pip

# 使用 pipx（推荐）
pipx install uv

# 或使用 pip
pip install uv

验证安装

安装完成后，可以通过以下命令验证：

uv --version

如果显示版本号，说明安装成功。

2. MCP 客户端配置

在 Claude Desktop 或其他 MCP 客户端中配置：

{
  "mcpServers": {
    "acg-frontend-mcp": {
      "command": "uvx",
      "args": ["acg-frontend-mcp"]
    }
  }
}

uvx 会自动下载并运行最新版本的包，无需手动安装或配置路径。

MCP 工具使用

本项目提供了一个 MCP 工具 compress_images，可以通过 MCP 协议调用。

工具：compress_images

批量压缩图片，支持多种压缩类型和格式转换。

参数说明：

参数	类型	必需	默认值	说明
input_dir	string	是	-	包含图片文件的输入目录路径
output_dir	string	是	-	压缩后图片的输出目录路径
compression_type	string	是	-	压缩类型（见下表）
max_size_kb	integer	否	50	目标最大文件大小(KB)
quality	integer	否	80	WebP/AVIF 质量 (0-100)
keep_original_size	boolean	否	false	是否保持原始尺寸
optimize	boolean	否	true	是否启用优化
method	integer	否	6	压缩方法 (0-6，6为最强压缩)

压缩类型：

类型	说明	适用场景
image_lossless	通用图片无损压缩	图标、UI、插画、需要保持透明度的图片
image_extreme	通用图片极度压缩（有损）	追求最小体积，允许一定质量损失
image_force_lossless	通用图片强制无损压缩	忽略大小限制的无损压缩
image_ultra	通用图片超强压缩	智能选择有损/无损（quality>=95 时无损）
webp	转换为 WebP 格式	标准 WebP 格式转换
avif	转换为 AVIF 格式	追求更高压缩比（编码较慢）

使用示例

在支持 MCP 的客户端中，可以这样使用：

请帮我压缩 /Users/xxx/images 目录下的所有图片，
使用无损压缩，输出到 /Users/xxx/compressed 目录

客户端会自动调用 compress_images 工具：

{
  "input_dir": "/Users/xxx/images",
  "output_dir": "/Users/xxx/compressed",
  "compression_type": "image_lossless",
  "max_size_kb": 50
}

压缩类型详解

1. image_lossless - 通用图片无损压缩

• 输出格式：WebP
• 透明/动画：保留透明度；GIF 动画转为 WebP 动画
• 压缩细节：
  • 使用 WebP 无损模式（lossless=True, optimize=True, method=6）
  • 不缩放尺寸，保持原分辨率
  • max_size_kb 仅用于结果提示，不会降低画质或缩小分辨率

2. image_extreme - 通用图片极度压缩

• 输出格式：WebP
• 透明/动画：保留透明度；GIF 动画转为 WebP 动画
• 压缩细节：
  • 按质量序列自适应尝试：[80,70,60,50,40,30,20,10,5,3,1]
  • 允许缩放时，大边>1200 会按比例缩放至最长边 1200
  • 追求最小体积，直到文件≤max_size_kb 或降至最低质量

3. image_force_lossless - 强制无损压缩

• 输出格式：WebP
• 透明/动画：保留透明度；GIF 动画转为 WebP 动画
• 压缩细节：
  • 始终使用 WebP 无损模式
  • 不缩放尺寸，不校验 max_size_kb
  • 动画 GIF 使用无损转 WebP 动画

4. image_ultra - 智能超强压缩

• 输出格式：WebP
• 透明/动画：保留透明度；GIF 动画转为 WebP 动画
• 压缩细节：
  • quality>=95 时走无损路径
  • quality<95 时走有损路径（与 image_extreme 相同策略）
  • 无损路径不缩放，有损路径可缩放

5. webp - WebP 格式转换

• 输出格式：WebP
• 透明/动画：保留透明度；GIF 动画转为 WebP 动画
• 压缩细节：
  • quality>=95 时采用 WebP 无损
  • 不缩放尺寸，不按体积目标迭代质量
  • 标准 WebP 格式转换

6. avif - AVIF 格式转换

• 输出格式：AVIF
• 透明/动画：保留透明度；动画不支持（GIF 仅取第一帧）
• 压缩细节：
  • 内部固定 quality=100, speed=0
  • 更高压缩效率，但编码速度较慢
  • 不缩放尺寸

选择建议

• 图标/插画/线稿/透明图：image_lossless 或 image_force_lossless
• 摄影/复杂纹理：image_extreme 或 image_ultra
• 追求极小体积：image_extreme，设置合适的 max_size_kb
• 追求更高压缩比：avif（注意编码速度和兼容性）
• 动图（GIF）：转换为 WebP 动画，体积更小、质量更好

注意事项

1. 输入格式：支持 PNG, JPG, JPEG, BMP, TIFF, GIF
2. 输出格式：根据压缩类型输出 WebP 或 AVIF 格式
3. 透明度：PNG 透明度在所有压缩模式下都会保留
4. 目录结构：压缩后会保持原有的目录结构
5. 临时文件：处理过程中使用临时目录，自动清理
6. AVIF 质量：当前 AVIF 转换固定为高质量，quality 参数对 AVIF 不生效
7. 动画支持：GIF 动画可转为 WebP 动画，AVIF 暂不支持动画

许可证

MIT License