npm package: @mavlarn/video-clip-mcp
Description: 🎬 基于AI MCP协议的专业视频剪辑工具，支持精准剪辑、智能合并、灵活分割等功能
Author: Mavlarn
Latest version: 1.6.1

# 🎬 Video Clip MCP

[![npm version](https://badge.fury.io/js/@mavlarn%2Fvideo-clip-mcp.svg)](https://badge.fury.io/js/@mavlarn%2Fvideo-clip-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-blue.svg)](https://www.typescriptlang.org/)
[![FFmpeg](https://img.shields.io/badge/FFmpeg-Auto%20Install-green.svg)](https://ffmpeg.org/)

## 📖 项目简介

基于 AI MCP 协议的专业视频剪辑工具，提供高效的视频处理能力和智能化操作体验。无需手动安装 FFmpeg，开箱即用！

## ✨ 核心功能

- 🎯 **精准剪辑** - 支持毫秒级精度的视频片段裁剪
- 🧩 **片段拼接** - 将多个视频片段按顺序拼接成一个视频
- ✂️ **灵活分割** - 按时长、大小或段数智能分割视频
- 🔊 **音频提取** - 从视频中提取音频并输出为 WAV
- 🖼️ **首帧提取** - 提取视频第一帧并输出为图片文件
- 📊 **信息获取** - 详细的视频元数据分析和格式检测
- 🚀 **批量处理** - 高效的批量任务管理和并行处理
- 🎨 **多格式支持** - 支持主流视频格式和编码标准
- 📈 **任务监控** - 实时任务状态跟踪和进度管理
- 🛠️ **高度可配置** - 丰富的编码参数和质量预设

## 📦 安装使用

### 全局安装（推荐）

```bash
npm install -g @mavlarn/video-clip-mcp@latest
```

### 临时使用

```bash
npx @mavlarn/video-clip-mcp@latest
```

## 🔧 MCP 服务器配置

### Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "video-clip": {
      "command": "npx",
      "args": ["@mavlarn/video-clip-mcp@latest"]
    }
  }
}
```

### Cursor AI

在 `.cursorrules` 或项目配置中添加：

```json
{
  "mcp": {
    "servers": {
      "video-clip": {
        "command": "npx @mavlarn/video-clip-mcp@latest"
      }
    }
  }
}
```

### WindSurf

在 `windsurfconfig.json` 中配置：

```json
{
  "mcpServers": {
    "video-clip": {
      "command": "npx",
      "args": ["@mavlarn/video-clip-mcp@latest"],
      "env": {}
    }
  }
}
```

### CodeBuddy

在项目根目录创建 `.codebuddy/mcp.json`：

```json
{
  "servers": {
    "video-clip": {
      "command": "npx @mavlarn/video-clip-mcp@latest",
      "description": "🎬 视频剪辑处理工具"
    }
  }
}
```

### 其他 MCP 兼容工具

通用配置格式：

```json
{
  "mcpServers": {
    "video-clip": {
      "command": "npx",
      "args": ["@mavlarn/video-clip-mcp@latest"]
    }
  }
}
```

## 💡 使用示例

### 基础视频剪辑

```typescript
// 剪辑视频片段（10秒到30秒）
await clipVideo({
  inputPath: "input.mp4",
  outputPath: "output.mp4",
  timeSegment: {
    start: 10000,  // 10秒（毫秒）
    end: 30000     // 30秒（毫秒）
  },
  quality: "fast",
  videoCodec: "libx264"
});
```

### 片段拼接

```typescript
await concat_clips({
  clips: [
    { inputPath: "clip_001.mp4" },
    { inputPath: "clip_002.mp4" }
  ],
  outputPath: "concat.mp4",
  quality: "fast",
  videoCodec: "libx264"
});
```

### 视频分割

```typescript
// 按时长分割视频
await splitVideo({
  inputPath: "long_video.mp4",
  outputDir: "./segments",
  splitBy: "duration",
  duration: 60,  // 每60秒一段
  namePattern: "segment_{index}.{ext}"
});
```

```typescript
// 按自定义时间片段分割视频
await splitVideo({
  inputPath: "long_video.mp4",
  outputDir: "./segments",
  splitBy: "timestamps",
  segments: [
    { timestamp: "0.0s~5.5s" },
    { timestamp: "5.6s~10.4s" }
  ]
});
```

### 提取音频（WAV）

```typescript
await extract_audio_wav({
  inputPath: "input.mp4",
  outputPath: "output.wav"
});
```

### 提取第一帧

```typescript
await extract_video_first_frame({
  inputPath: "input.mp4",
  outputPath: "first_frame.png"
});
```

### 批量处理

```typescript
// 批量处理任务
const tasks = [
  {
    type: "clip",
    options: {
      inputPath: "video1.mp4",
      outputPath: "clip1.mp4",
      timeSegment: { start: 0, end: 30000 }
    }
  },
  {
    type: "clip", 
    options: {
      inputPath: "video2.mp4",
      outputPath: "clip2.mp4",
      timeSegment: { start: 10000, end: 40000 }
    }
  }
];

await batchProcess({ tasks });
```

## 🎥 支持格式

### 视频格式
- **输入格式**: MP4, AVI, MOV, MKV, WebM, FLV, 3GP, WMV
- **输出格式**: MP4, AVI, MOV, MKV, WebM

### 视频编码
- **H.264** (libx264) - 通用兼容性最佳
- **H.265** (libx265) - 高压缩比，文件更小
- **VP9** (libvpx-vp9) - 开源编码，适合网络传输
- **AV1** (libaom-av1) - 新一代编码，压缩效率极高

### 音频编码
- **AAC** - 高质量音频编码
- **MP3** (libmp3lame) - 通用兼容性
- **Opus** (libopus) - 低延迟高质量
- **Vorbis** (libvorbis) - 开源音频编码

## 🖥️ 系统要求

### Node.js 版本
- **最低要求**: Node.js 18.0.0+
- **推荐版本**: Node.js 20.0.0+

### 系统依赖
- **FFmpeg**: 自动安装（通过 @ffmpeg-installer/ffmpeg 包）
- **操作系统**: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+)

### 推荐硬件配置
- **CPU**: 4核心以上，支持硬件加速更佳
- **内存**: 8GB RAM 以上
- **存储**: SSD 硬盘，至少2GB可用空间
- **GPU**: 支持硬件编码的显卡（可选）

## 📚 API 文档

### 核心接口定义

```typescript
interface VideoClipOptions {
  inputPath: string;
  outputPath: string;
  timeSegment: {
    start: number;  // 开始时间（毫秒）
    end: number;    // 结束时间（毫秒）
  };
  quality?: 'ultrafast' | 'fast' | 'medium' | 'slow' | 'veryslow';
  videoCodec?: 'libx264' | 'libx265' | 'libvpx-vp9' | 'libaom-av1';
  audioCodec?: 'aac' | 'libmp3lame' | 'libopus' | 'libvorbis';
  preserveMetadata?: boolean;
}

interface SplitVideoOptions {
  inputPath: string;
  outputDir: string;
  splitBy: 'duration' | 'size' | 'segments' | 'timestamps';
  duration?: number;     // 按时长分割（秒）
  maxSize?: number;      // 按大小分割（MB）
  segmentCount?: number; // 分割段数
  segments?: { timestamp: string }[]; // 自定义时间片段，格式如 0.0s~5.5s
  namePattern?: string;  // 文件命名模式
}

interface VideoInfo {
  duration: number;      // 时长（秒）
  width: number;         // 宽度
  height: number;        // 高度
  fps: number;          // 帧率
  bitrate: number;      // 比特率
  format: string;       // 格式
  codec: string;        // 编码
  size: number;         // 文件大小（字节）
}

interface TaskStatus {
  id: string;
  type: 'clip' | 'merge' | 'split';
  status: 'pending' | 'processing' | 'completed' | 'failed';
  progress?: number;
  createdAt: string;
  completedAt?: string;
  error?: string;
  result?: any;
}
```

### 主要方法

```typescript
// 获取视频信息
getVideoInfo(filePath: string): Promise<VideoInfo>

// 提取音频（WAV）
extract_audio_wav(options: { inputPath: string; outputPath: string }): Promise<string>

// 提取第一帧
extract_video_first_frame(options: { inputPath: string; outputPath: string }): Promise<string>

// 拼接片段
concat_clips(options: { clips: { inputPath: string }[]; outputPath: string; quality?: string; videoCodec?: string; audioCodec?: string; preserveMetadata?: boolean }): Promise<string>

// 剪辑视频
clipVideo(options: VideoClipOptions): Promise<string>

// 分割视频
splitVideo(options: SplitVideoOptions): Promise<string[]>

// 批量处理
batchProcess(tasks: BatchTask[]): Promise<string[]>

// 获取任务状态
getTaskStatus(taskId: string): Promise<TaskStatus>

// 取消任务
cancelTask(taskId: string): Promise<boolean>

// 获取支持的格式
getSupportedFormats(): Promise<SupportedFormats>
```

## 🚨 疑难解答

### 常见问题及解决方案

#### 1. 🔄 Connection closed 错误

**问题描述**: 使用 `npx` 时出现连接关闭错误

**解决方案**（按推荐顺序）:

**a. 首选方案 - 使用 @latest 标签**
```bash
npx @mavlarn/video-clip-mcp@latest
```

**b. 备用方案 - 锁定特定版本**
```bash
npx @mavlarn/video-clip-mcp@1.2.0
```

**c. 终极方案 - 清理 npx 缓存**
```bash
# Windows
npx clear-npx-cache
# 或者手动删除缓存目录
rmdir /s "%APPDATA%\npm-cache\_npx"

# macOS/Linux
npx clear-npx-cache
# 或者手动删除缓存目录
rm -rf ~/.npm/_npx
```

#### 2. 🎬 FFmpeg 相关错误

**问题描述**: FFmpeg 执行失败或找不到

**解决方案**:
- 本工具已内置 FFmpeg，无需手动安装
- 如果仍有问题，请检查网络连接（首次使用需下载 FFmpeg）
- 确保有足够的磁盘空间（至少 100MB）

#### 3. 📁 文件路径问题

**问题描述**: 输入或输出文件路径错误

**解决方案**:
- 使用绝对路径而非相对路径
- 确保路径中不包含特殊字符
- Windows 用户注意使用正斜杠 `/` 或双反斜杠 `\\`

#### 4. 🔧 权限问题

**问题描述**: 没有文件读写权限

**解决方案**:
- 确保对输入文件有读取权限
- 确保对输出目录有写入权限
- Windows 用户可能需要以管理员身份运行

#### 5. 💾 内存不足

**问题描述**: 处理大文件时内存溢出

**解决方案**:
- 降低视频质量设置
- 分段处理大文件
- 增加系统虚拟内存

### 📞 获取帮助

如果以上解决方案无法解决您的问题，请：

1. 📋 收集错误信息和系统环境
2. 🐛 在 [GitHub Issues](https://github.com/mavlarn/video-clip-mcp/issues) 提交问题
3. 💬 联系开发者（见下方联系方式）

## 🤝 贡献指南

我们欢迎所有形式的贡献！请遵循以下步骤：

1. **Fork** 本仓库
2. **创建特性分支**: `git checkout -b feature/amazing-feature`
3. **提交更改**: `git commit -m 'Add amazing feature'`
4. **推送分支**: `git push origin feature/amazing-feature`
5. **提交 Pull Request**

### 开发环境设置

```bash
# 克隆仓库
git clone https://github.com/mavlarn/video-clip-mcp.git
cd video-clip-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 启动开发模式
npm run dev
```

## 📄 许可证

本项目采用 [MIT License](LICENSE) 开源协议。您可以自由使用、修改和分发本软件。

## 🙏 致谢

感谢以下开源项目和社区的支持：

- **[FFmpeg](https://ffmpeg.org/)** - 强大的多媒体处理框架
- **[fluent-ffmpeg](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg)** - Node.js FFmpeg 封装库
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - AI 工具集成协议
- **[TypeScript](https://www.typescriptlang.org/)** - 类型安全的 JavaScript 超集
- **开源社区** - 所有贡献者和用户的支持

## 🌟 支持项目

如果这个项目对您有帮助，请：

- ⭐ **给项目点个 Star**
- 🐛 **报告问题和建议** 
- 🔄 **分享给更多开发者**

让我们一起打造更好的视频处理工具！🚀

---