# ACG Frontend MCP

基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的图片压缩服务，使用 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

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

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

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

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

**方法二：使用 Homebrew**

```bash
brew install uv
```

#### Linux

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

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

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

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

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

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

**方法二：使用 pipx 或 pip**

```bash
# 使用 pipx（推荐）
pipx install uv

# 或使用 pip
pip install uv
```

#### Windows

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

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

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

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

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

**方法二：使用 pipx 或 pip**

```powershell
# 使用 pipx（推荐）
pipx install uv

# 或使用 pip
pip install uv
```

#### 验证安装

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

```bash
uv --version
```

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

### 2. MCP 客户端配置

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

```json
{
  "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 的客户端中，可以这样使用：

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

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

```json
{
  "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
