# GIF 分割工具 MCP 服务器

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 GIF 动画分割工具，可以将动态 GIF 拆分为多张静态图片。

## 功能特点

- ✂️ **GIF 帧分割**：将 GIF 动画拆分为独立的静态图片
- 🎨 **多格式支持**：支持输出 PNG、WEBP、JPEG、TIFF、BMP 等格式
- 🎭 **透明度处理**：可选保留或去除透明通道
- 📁 **灵活配置**：自定义输出目录、文件名前缀等参数
- 🔒 **路径安全**：自动处理用户目录（`~`）和相对路径

## 环境要求

- Python 3.10 及以上
- [uv](https://github.com/astral-sh/uv) 或 pip（推荐使用 uv）

## 安装

### 使用 uv（推荐）

```bash
cd /Users/fjc/Desktop/项目/skills/图片/图片-分割GIF
uv sync
```

### 使用 pip

```bash
cd /Users/fjc/Desktop/项目/skills/图片/图片-分割GIF
pip install -e .
```

## 运行

### 启动 MCP 服务器

```bash
# stdio 模式（用于 Claude Desktop 等 MCP 客户端）
uv run mcp-gif-split

# 或直接使用 Python
uv run python -m mcp_gif_split.server

# SSE 模式（HTTP 服务器，端口 8080）
uv run mcp-gif-split sse
```

### 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

添加以下配置：

```json
{
  "mcpServers": {
    "gif-split": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/fjc/Desktop/项目/skills/图片/图片-分割GIF",
        "run",
        "mcp-gif-split"
      ]
    }
  }
}
```

## 可用工具

### `split_gif_frames`

将 GIF 动画拆分为多张静态图片。

#### 参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `file_path` | `string` | ✅ | - | GIF 文件路径 |
| `output_dir` | `string` | ❌ | `<文件名>_frames` | 输出目录路径 |
| `filename_prefix` | `string` | ❌ | `frame` | 输出文件名前缀 |
| `image_format` | `string` | ❌ | `PNG` | 输出格式（PNG/WEBP/JPEG/TIFF/BMP） |
| `keep_transparency` | `boolean` | ❌ | `true` | 是否保留透明通道 |

#### 返回值

```json
{
  "output_dir": "/path/to/output",
  "frame_count": 24,
  "image_format": "PNG",
  "files": [
    "/path/to/output/frame_000.png",
    "/path/to/output/frame_001.png",
    "..."
  ]
}
```

#### 使用示例

**基础用法**（使用默认设置）：

```
请将 ~/Downloads/animation.gif 分割为图片
```

**自定义输出目录和格式**：

```
将 /path/to/cat.gif 拆分为 WEBP 格式，
输出到 /path/to/output 目录，文件名前缀为 cat_frame
```

**去除透明通道**：

```
分割 ~/Desktop/logo.gif，不保留透明通道，输出为 JPEG 格式
```

## 支持的图片格式

| 格式 | 扩展名 | 透明度支持 | 说明 |
|------|--------|-----------|------|
| PNG | `.png` | ✅ | 推荐，无损压缩，支持透明 |
| WEBP | `.webp` | ✅ | 现代格式，压缩率高 |
| JPEG | `.jpg` | ❌ | 有损压缩，不支持透明 |
| TIFF | `.tiff` | ✅ | 专业格式，文件较大 |
| BMP | `.bmp` | ❌ | 无压缩，文件很大 |

## 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `MCP_DEBUG` | 启用调试日志（设置为 `1`） | `0` |

## 开发

### 安装开发依赖

```bash
uv sync --group dev
```

### 构建发布包

```bash
uv run python -m build
```

### 项目结构

```
图片-分割GIF/
├── mcp_gif_split/
│   ├── __init__.py          # 包初始化
│   └── server.py            # 核心服务器逻辑
├── pyproject.toml           # 项目配置
└── README.md                # 本文档
```

## 常见问题

### Q: 为什么分割后的图片文件很大？

A: 尝试使用 WEBP 或 JPEG 格式，并设置 `keep_transparency=false`（如果不需要透明度）。

### Q: 支持批量处理多个 GIF 吗？

A: 当前版本每次处理一个 GIF 文件，可以多次调用工具来处理多个文件。

### Q: 输出文件名的编号格式是什么？

A: 使用三位数编号格式，如 `frame_000.png`, `frame_001.png` 等，最多支持 1000 帧。

## 许可证

MIT License

## 作者

fengjinchao

## 更新日志

### v0.1.0 (2024-11-28)

- 🎉 初始版本发布
- ✅ 支持 GIF 帧分割
- ✅ 支持多种输出格式
- ✅ 支持透明度处理
