# FFmpeg MCP Tool

一个基于FFmpeg的MCP（Model Context Protocol）工具，用于处理图片和视频的转码、压缩等操作。

## 功能特性

### 图片处理
- 图片压缩（单个文件或批量处理）
- 图片格式转换（JPG、PNG、BMP、GIF、TIFF、WebP等）
- 图片尺寸调整
- 获取图片信息

### 视频处理
- 视频压缩（支持H.264编码）
- 视频格式转换（MP4、AVI、MKV、MOV等）
- 视频尺寸调整
- 获取视频信息

### 批量处理
- 支持批量压缩指定文件夹中的所有图片
- 支持批量压缩指定文件夹中的所有视频
- 自动识别常见的图片和视频格式

## 系统要求

1. Python 3.8+
2. FFmpeg（必须安装并可在命令行中使用）

## 安装步骤

### 1. 安装FFmpeg

#### Windows
- 下载FFmpeg：https://ffmpeg.org/download.html#build-windows
- 解压到某个目录（如 `C:\ffmpeg`）
- 将 `C:\ffmpeg\bin` 添加到系统PATH环境变量
- 打开命令提示符，运行 `ffmpeg -version` 验证安装

#### macOS
```bash
brew install ffmpeg
```

#### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install ffmpeg
```

### 2. 安装Python依赖

```bash
pip install -r requirements.txt
```

## 使用方法

### 1. 启动MCP服务器

```bash
python start_server.py
```

### 2. 配置MCP客户端

将 `config.json` 中的配置添加到你的MCP客户端配置中：

```json
{
  "mcpServers": {
    "ffmpeg": {
      "command": "python",
      "args": ["path/to/ffmpeg_mcp.py"],
      "env": null
    }
  }
}
```

### 3. 可用工具

#### 图片处理工具

##### `compress_image`
压缩单个图片文件
```json
{
  "input_path": "D:/input/image.jpg",
  "output_path": "D:/output/compressed.jpg", 
  "quality": 85
}
```

##### `batch_compress_images`
批量压缩指定文件夹中的所有图片
```json
{
  "input_dir": "D:/1",
  "output_dir": "D:/output",
  "quality": 85
}
```

##### `convert_image_format`
转换图片格式
```json
{
  "input_path": "D:/input/image.png",
  "output_path": "D:/output/image.jpg"
}
```

##### `resize_image`  
调整图片尺寸
```json
{
  "input_path": "D:/input/image.jpg",
  "output_path": "D:/output/resized.jpg",
  "width": 800,
  "height": 600
}
```

#### 视频处理工具

##### `compress_video`
压缩单个视频文件
```json
{
  "input_path": "D:/input/video.mp4",
  "output_path": "D:/output/compressed.mp4",
  "crf": 23,
  "preset": "medium"
}
```

##### `batch_compress_videos`
批量压缩指定文件夹中的所有视频
```json
{
  "input_dir": "D:/videos", 
  "output_dir": "D:/output",
  "crf": 23,
  "preset": "medium"
}
```

##### `convert_video_format`
转换视频格式
```json
{
  "input_path": "D:/input/video.avi",
  "output_path": "D:/output/video.mp4"
}
```

##### `resize_video`
调整视频尺寸
```json
{
  "input_path": "D:/input/video.mp4",
  "output_path": "D:/output/resized.mp4",
  "width": 1280,
  "height": 720
}
```

#### 信息工具

##### `get_media_info`
获取媒体文件详细信息
```json
{
  "file_path": "D:/media/file.mp4"
}
```

##### `check_ffmpeg_status`
检查FFmpeg是否安装并可用
```json
{}
```

## 参数说明

### 图片压缩质量 (quality)
- 范围：1-100
- 数值越高，质量越好，文件越大
- 推荐值：80-90

### 视频压缩质量 (crf)  
- 范围：18-28
- 数值越小，质量越高，文件越大
- 推荐值：
  - 高质量：18-20
  - 平衡：21-24  
  - 小文件：25-28

### 视频压缩速度预设 (preset)
- `ultrafast`：最快速度，文件最大
- `superfast, veryfast, faster, fast`：速度递减，质量递增
- `medium`：平衡选择（默认）
- `slow, slower, veryslow`：速度最慢，质量最好

## 支持的文件格式

### 图片格式
- 输入：JPG, JPEG, PNG, BMP, GIF, TIFF, WebP
- 输出：根据输出文件扩展名自动判断

### 视频格式
- 输入：MP4, AVI, MKV, MOV, WMV, FLV, WebM, M4V
- 输出：根据输出文件扩展名自动判断

## 使用示例

### 批量压缩图片
假设你有一个文件夹 `D:/1` 包含很多JPG图片，想要压缩后保存到 `D:/output`：

```python
# 使用MCP客户端调用
tool_call = {
    "name": "batch_compress_images",
    "arguments": {
        "input_dir": "D:/1",
        "output_dir": "D:/output", 
        "quality": 80
    }
}
```

### 视频格式转换
将AVI格式转换为MP4：

```python
tool_call = {
    "name": "convert_video_format",
    "arguments": {
        "input_path": "D:/video.avi",
        "output_path": "D:/output/video.mp4"
    }
}
```

## 实际应用案例

### 网站图片批量优化

**场景**：网站有大量高分辨率图片需要优化以提高加载速度

**操作**：

```
用户：我需要优化网站的所有图片，它们在 D:/website/images 目录，
      请压缩到 D:/website/optimized，质量保持在 80-85 之间
```

AI助手自动执行：

1. 调用 `batch_compress_images` 工具
2. 处理目录中的所有图片
3. 生成压缩报告，显示节省的存储空间

**结果**：假设处理了 500 张图片，平均压缩率 60%，节省了约 2GB 存储空间。

### 视频素材格式转换

**场景**：将不同格式的视频素材统一转换为 MP4 格式

**操作**：

```
用户：把 D:/videos/raw 目录下的所有视频转换为 MP4 格式，
      保存到 D:/videos/mp4，使用中等压缩质量
```

AI助手处理流程：

1. 识别目录中的所有视频文件（AVI、MKV、MOV等）
2. 逐个转换为 MP4 格式
3. 应用 H.264 编码和 AAC 音频编码
4. 报告转换结果

### 社交媒体图片批量调整

**场景**：为不同社交平台准备合适尺寸的图片

**操作**：

```
用户：将 D:/photos/original 中的照片调整为 1080x1080 正方形，
      适合 Instagram 发布，保存到 D:/photos/instagram
```

AI助手会：

1. 调用 `resize_image` 工具
2. 批量处理所有图片
3. 调整为指定尺寸
4. 保持合适的压缩质量

## 错误处理

工具会自动处理常见错误：
- 输入文件不存在
- 输出目录不存在（会自动创建）
- FFmpeg命令执行失败
- 不支持的文件格式

## 注意事项

1. 确保有足够的磁盘空间用于输出文件
2. 大文件处理可能需要较长时间
3. 批量处理时会跳过无法处理的文件并在结果中报告
4. 输出路径中的目录会被自动创建

## 故障排除

### FFmpeg未找到
```
错误：FFmpeg 未安装或不可用
```
解决方案：
1. 确认FFmpeg已正确安装
2. 确认FFmpeg已添加到系统PATH
3. 在命令行运行 `ffmpeg -version` 验证

### 文件权限错误
确保Python有读取输入文件和写入输出目录的权限。

### 内存不足
对于大文件或大量文件，可能需要：
1. 增加系统内存
2. 分批处理文件
3. 调整FFmpeg参数

## 开发和扩展

项目结构：
```
ffmpeg-mcp/
├── ffmpeg_mcp.py      # 主要的MCP服务器代码
├── requirements.txt   # Python依赖
├── config.json       # MCP配置文件
├── start_server.py   # 服务器启动脚本
├── test_example.py   # 使用示例
└── README.md        # 说明文档
```

如需添加新功能，可以：
1. 在 `FFmpegProcessor` 类中添加新的处理方法
2. 在 `handle_list_tools()` 中注册新工具
3. 在 `handle_call_tool()` 中处理新工具的调用

## 许可证

MIT License - 可自由使用和修改。