npm package: @pickstar-2002/video-metadata-mcp
Description: MCP server for video metadata management
Author: pickstar-2002
Latest version: 1.0.2

# 📹 Video Metadata MCP

[![npm version](https://badge.fury.io/js/@pickstar-2002%2Fvideo-metadata-mcp.svg)](https://badge.fury.io/js/@pickstar-2002%2Fvideo-metadata-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/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)

> 🚀 基于 Model Context Protocol (MCP) 的专业视频元数据管理服务器，提供完整的视频文件元数据读取、编辑和管理功能。

## ✨ 功能特性

- 📖 **元数据读取** - 读取视频文件的完整元数据信息（格式、分辨率、时长、编解码器等）
- ✏️ **元数据编辑** - 修改标题、作者、描述、版权等元数据信息
- 🏷️ **标签管理** - 添加、删除、搜索视频标签
- 📦 **批量处理** - 批量管理多个视频文件的元数据
- 🔍 **智能搜索** - 根据多种条件搜索视频文件
- ⚡ **缓存优化** - 智能缓存机制提升性能

## 📋 系统要求

- Node.js 18+ 
- FFmpeg (自动包含在依赖中)

## 🚀 安装

### 推荐方式（使用 @latest 标签）

```bash
npx @pickstar-2002/video-metadata-mcp@latest
```

### 全局安装

```bash
npm install -g @pickstar-2002/video-metadata-mcp@latest
```

## 🔧 使用方法

### 在 IDE 中配置 MCP 服务

#### Cursor / Claude Desktop

在您的 MCP 客户端配置文件中添加：

```json
{
  "mcpServers": {
    "video-metadata": {
      "command": "npx",
      "args": ["@pickstar-2002/video-metadata-mcp@latest"]
    }
  }
}
```

#### VS Code (使用 MCP 扩展)

```json
{
  "mcp.servers": {
    "video-metadata": {
      "command": "npx @pickstar-2002/video-metadata-mcp@latest"
    }
  }
}
```

### 直接运行

```bash
# 使用 @latest 标签（推荐）
npx @pickstar-2002/video-metadata-mcp@latest

# 或者全局安装后运行
video-metadata-mcp
```

## 🛠️ 可用工具

### 1. 📖 read_video_metadata
读取视频文件的完整元数据信息。

**参数：**
- `filePath` (string): 视频文件的完整路径

**返回：** 包含视频完整元数据的JSON对象

### 2. ✏️ update_video_metadata
更新视频文件的元数据信息。

**参数：**
- `filePath` (string): 视频文件的完整路径
- `updates` (object): 要更新的元数据字段

### 3. 🏷️ add_video_tags / remove_video_tags
管理视频标签。

**参数：**
- `filePath` (string): 视频文件的完整路径
- `tags` (string[]): 标签列表

### 4. 🔍 search_videos
在目录中搜索视频文件。

**参数：**
- `directory` (string): 要搜索的目录路径
- `options` (object): 搜索选项

### 5. 📦 批量操作工具
- `batch_update_metadata` - 批量更新元数据
- `batch_add_tags` - 批量添加标签
- `batch_remove_tags` - 批量删除标签

## 📁 支持的视频格式

- 🎬 MP4 (.mp4)
- 🎞️ AVI (.avi)
- 📹 MOV (.mov)
- 🎥 MKV (.mkv)
- 📺 WMV (.wmv)
- 🌐 FLV (.flv)
- 🕸️ WebM (.webm)
- 📱 M4V (.m4v)

## 📝 使用示例

### 读取视频元数据

```javascript
// 通过 MCP 客户端调用
{
  "tool": "read_video_metadata",
  "arguments": {
    "filePath": "/path/to/your/video.mp4"
  }
}
```

### 更新视频元数据

```javascript
{
  "tool": "update_video_metadata",
  "arguments": {
    "filePath": "/path/to/your/video.mp4",
    "updates": {
      "title": "我的视频标题",
      "artist": "pickstar-2002",
      "description": "这是一个示例视频",
      "tags": ["教程", "演示", "MCP"]
    }
  }
}
```

## 🔧 开发

```bash
# 克隆仓库
git clone https://github.com/pickstar-2002/video-metadata-mcp.git
cd video-metadata-mcp

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build
```

## ❗ 疑难解答

### 常见问题及解决方案

#### 🚨 问题：遇到 `Connection closed` 错误

这通常是由于 `npx` 缓存问题导致的。请按以下顺序尝试解决：

**解决方案 1（首选）：确认使用 @latest 标签**
```bash
npx @pickstar-2002/video-metadata-mcp@latest
```

**解决方案 2（备用）：锁定到特定稳定版本**
```bash
# 查看可用版本
npm view @pickstar-2002/video-metadata-mcp versions --json

# 使用特定版本（例如 1.0.0）
npx @pickstar-2002/video-metadata-mcp@1.0.0
```

**解决方案 3（终极方案）：清理 npx 缓存**
```bash
# 清理 npx 缓存
npx clear-npx-cache

# 或者手动删除缓存目录
# Windows: %USERPROFILE%\.npm\_npx
# macOS/Linux: ~/.npm/_npx

# 然后重新运行
npx @pickstar-2002/video-metadata-mcp@latest
```

#### 🚨 问题：FFmpeg 相关错误

确保系统已安装 FFmpeg：

```bash
# Windows (使用 Chocolatey)
choco install ffmpeg

# macOS (使用 Homebrew)
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg
```

#### 🚨 问题：权限错误

在 Linux/macOS 上可能需要适当的文件权限：

```bash
# 给予执行权限
chmod +x node_modules/.bin/video-metadata-mcp

# 或使用 sudo（不推荐）
sudo npx @pickstar-2002/video-metadata-mcp@latest
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

如有问题或建议，欢迎联系：

**微信: pickstar_loveXX**

---

⭐ 如果这个项目对您有帮助，请给个 Star！