timeverse-omni-converter-mcp
by elimyliu
README.md
# Format Converter MCP
> 通用格式转换 MCP Server
一个覆盖音频、视频、图片、Office、数据、电子书、PDF、字幕等全格式转换的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器，可被 TimeVerse Studio、Claude Desktop、Cursor、VS Code 等任意 MCP 客户端调用。
[English](./README.en.md)
***
## ✨ 特性
| 特性 | 说明 |
| --------- | --------------------------------------------------------------- |
| 🎯 格式覆盖广 | 9 大格式域、71 种去重格式，另含字幕、PDF 操作等特殊能力 |
| 🧩 14 个工具 | 10 个核心转换工具 + 4 个辅助工具，按格式域精准分类，LLM 易于选择 |
| 🧠 智能路由 | 自动选择最优转换路径（直转 / 多步链式），依赖不可用时自动降级 |
| 🔧 6 大引擎 | FFmpeg / ImageMagick / LibreOffice / Pandoc / Python / PDF 统一封装 |
| ⚡ 零配置 | 启动时自检测系统依赖，缺失时提示或降级 |
| 🛡️ 生产可用 | 分级错误处理、资源上限防护、临时文件 TTL 清理 |
***
## 📦 支持的格式
| 格式域 | 工具 | 引擎 | 格式数 | 示例 |
| ------ | ---------------------- | ----------------------------------- | ----- | ----------------------------------------------------------------------------- |
| 音频 | `convert_media` | FFmpeg | 12 | MP3, WAV, FLAC, AAC, OGG, M4A, WMA, AIFF, OPUS, AC3, AMR, MKA |
| 视频 | `convert_media` | FFmpeg | 14 | MP4, AVI, MKV, MOV, WebM, FLV, WMV, M4V, MPEG, 3GP, TS, GIF, VOB, RMVB |
| 图片 | `convert_image` | ImageMagick / Pillow | 16 | JPEG, PNG, GIF, BMP, TIFF, WebP, SVG, HEIC, ICO, PSD, RAW, AVIF, EXR |
| 文档 | `convert_document` | LibreOffice / Pandoc / pdf2docx | 10 | DOCX, DOC, PDF, RTF, ODT, TXT, PAGES\*, WPS\*, HTML, MD |
| 演示 | `convert_presentation` | LibreOffice | 6 | PPTX, PPT, ODP, PDF, KEY\*, HTML |
| 表格 | `convert_spreadsheet` | openpyxl / pandas / LibreOffice | 8 | XLSX, XLS, ODS, CSV, TSV, NUMBERS\*, FODS, HTML |
| 标记 | `convert_markup` | Pandoc | 12 | Markdown, HTML, RST, AsciiDoc, LaTeX, Org, MediaWiki, EPUB, Typst, TXT, IPYNB |
| 数据 | `convert_data` | Python (PyYAML/tomlkit/pandas/lxml) | 8 | JSON, YAML, XML, TOML, CSV, TSV, Parquet, Protobuf |
| 电子书 | `convert_ebook` | Pandoc / Calibre | 5 | EPUB, MOBI, AZW3, FB2, PDF |
| 字幕 | `convert_subtitle` | pysubs2 | 3 | SRT, ASS/SSA, VTT |
| PDF 操作 | `convert_pdf` | PyMuPDF / pypdf | 9 种操作 | merge, split, compress, extract, watermark, rotate, to\_images |
> `*` 标记为受限格式（PAGES / WPS / NUMBERS / KEY），需 macOS 原生应用或 iCloud 导出。
> 合计去重后约 **71 种格式**，覆盖行业 95%+ 的常见转换需求。
***
## ⚠️ 已知限制
- **受限格式**：`PAGES` / `WPS` / `NUMBERS` / `KEY` 需 macOS 原生应用或 iCloud 导出，其它平台通常无法直接转换。
- **HEIC/HEIF 解码**：依赖 ImageMagick 的 libheif 支持；缺失时无法解码 Apple 高效图片。
- **引擎缺省降级**：若未安装 LaTeX，Markdown→PDF 会降级为 weasyprint；若未安装 Calibre，MOBI/AZW3 电子书不可用；若未安装 ImageMagick，图片转换回退到 Python Pillow（能力更有限）。
- **Protocol Buffers**：转换为 PB 需要额外的 `.proto` 定义文件。
- **Parquet / Protobuf**：对应的 Python 依赖（`pyarrow`、`protobuf`）为可选，需手动安装。
***
## 🧰 工具列表
### 核心转换工具（10 个）
| 工具 | 说明 |
| ---------------------- | -------------------------------------------- |
| `convert_media` | 音频/视频互转，提取音频、截取片段、嵌入字幕 |
| `convert_image` | 图片互转，缩放、优化、矢量↔栅格、DPI 控制 |
| `convert_document` | Word/PDF/RTF/TXT/HTML/MD 高保真转换，OCR、表格提取 |
| `convert_presentation` | PPT/ODP/PDF/HTML/PNG（幻灯片图片）转换 |
| `convert_spreadsheet` | Excel/CSV/TSV/JSON/HTML 转换，保留公式与多工作表 |
| `convert_markup` | Markdown/HTML/LaTeX/EPUB 等标记文本转换，目录/高亮/公式 |
| `convert_data` | JSON/YAML/XML/TOML/CSV/Parquet/Protobuf 数据转换 |
| `convert_ebook` | EPUB/MOBI/AZW3/FB2/PDF 电子书转换，封面/元数据 |
| `convert_pdf` | PDF 合并/拆分/压缩/提取/水印/旋转/转图片 |
| `convert_subtitle` | SRT/ASS/VTT 字幕互转，时间偏移、编码转换 |
### 辅助工具（4 个）
| 工具 | 说明 |
| ----------------------- | ------------------------- |
| `get_supported_formats` | 查询支持的格式、转换路径与可用引擎 |
| `get_file_info` | 探测文件元信息（格式、编码、分辨率、时长、页数等） |
| `batch_convert` | 批量转换，支持 Glob 匹配与并行执行 |
| `check_dependencies` | 检查所有引擎与系统依赖的可用性与版本 |
所有转换工具统一遵循 `input_path` + `output_format` + `options` 参数范式。
***
## 🏗️ 架构
```
┌─────────────────────────────────────────────────────┐
│ MCP Client (LLM) │
│ Claude / Cursor / VS Code / ... │
└──────────────────────┬──────────────────────────────┘
│ JSON-RPC (stdio)
┌──────────────────────┴──────────────────────────────┐
│ MCP Protocol Layer │
│ tool list · tool call · notifications │
├──────────────────────────────────────────────────────┤
│ Tool Router Layer │
│ 请求解析 → 格式识别 → 路由分发 → 结果封装 │
├───────────┬───────────┬──────────┬───────────────────┤
│ Format │ Conversion│ File │ Dependency │
│ Registry │ Planner │ Manager │ Checker │
├───────────┴───────────┴──────────┴───────────────────┤
│ Conversion Engine Layer │
│ FFmpeg · ImageMagick · LibreOffice · Pandoc │
│ Python · PDF │
└──────────────────────────────────────────────────────┘
```
智能路径规划示例：
| 源 → 目标 | 路径 |
| ----------- | ---------------------------------------- |
| PDF → XLSX | PDF → CSV (pdfplumber) → XLSX (openpyxl) |
| PDF → DOCX | PDF → DOCX (pdf2docx) |
| XLSX → JSON | XLSX → DataFrame (pandas) → JSON |
| PPTX → MD | PPTX → HTML (LibreOffice) → MD (Pandoc) |
| DOCX → EPUB | DOCX → HTML (Pandoc) → EPUB (Pandoc) |
***
## ⚙️ 技术栈
- **主语言**：TypeScript (Node.js ≥ 18)
- **协议**：`@modelcontextprotocol/sdk`
- **转换引擎**：FFmpeg / ImageMagick / LibreOffice / Pandoc / Python (venv 隔离) / PyMuPDF
### 系统依赖
| 依赖 | 版本 | 用途 | 安装 |
| ----------- | ------ | ------------- | ------------------------------------------------------------------------------------- |
| Node.js | ≥ 18 | 运行 MCP Server | [nodejs.org](https://nodejs.org) |
| FFmpeg | ≥ 6.0 | 音视频/字幕转换 | `winget install ffmpeg` / `brew install ffmpeg` / `apt install ffmpeg` |
| ImageMagick | ≥ 7.0 | 图片转换 | `winget install ImageMagick` / `brew install imagemagick` / `apt install imagemagick` |
| LibreOffice | ≥ 7.5 | Office 文档保真转换 | [libreoffice.org](https://www.libreoffice.org) |
| Pandoc | ≥ 3.0 | 标记/文档/电子书转换 | `winget install pandoc` / `brew install pandoc` / `apt install pandoc` |
| Python | ≥ 3.10 | 数据/PDF/表格/字幕 | [python.org](https://python.org) |
> LaTeX（可选，Markdown→PDF 高质量）与 Calibre（可选，MOBI/AZW3）可缺省，系统会自动降级。
### Python 依赖
```bash
pip install -r python/requirements.txt
```
核心依赖：`openpyxl`、`pandas`、`PyYAML`、`tomlkit`、`xmltodict`、`PyMuPDF`、`pypdf`、`pdf2docx`、`pysubs2`、`Pillow`（`pyarrow`、`protobuf` 为可选）。
***
## 🚀 安装
先安装系统依赖（FFmpeg / ImageMagick / LibreOffice / Pandoc）：
- **Windows**：`npm run prepare-deps`（一键下载便携版）
- **macOS**：`brew install ffmpeg imagemagick pandoc && brew install --cask libreoffice`
- **Linux**：`apt install ffmpeg imagemagick libreoffice pandoc`
然后构建并安装 Python 依赖：
```bash
# 1. 安装 Node 依赖
npm install
# 2. 构建（生成 dist/）
npm run build
# 3. 安装 Python 依赖（建议使用虚拟环境）
python3 -m venv .venv # macOS/Linux；Windows 使用 python
source .venv/bin/activate # macOS/Linux；Windows 使用 .venv\Scripts\activate
pip install -r python/requirements.txt
```
***
## 🔌 MCP 配置
在 MCP 客户端的 `mcpServers` 配置中添加以下服务器即可。
### TimeVerse Studio（推荐 · npm 托管）
TimeVerse Studio 使用标准 `mcpServers` JSON 接入。发布到 npm 后，直接通过 `npx` 一键运行，无需本地构建：
```json
{
"mcpServers": {
"timeverse-omni-converter-mcp": {
"command": "npx",
"args": ["-y", "timeverse-omni-converter-mcp"],
"env": {
"FC_PYTHON_PATH": "python",
"FC_TEMP_DIR": "C:/temp/format-converter",
"FC_MAX_FILE_SIZE": "524288000",
"FC_TIMEOUT": "300000"
}
}
}
}
```
### Claude Desktop / Cursor（本地构建）
本地构建后，通过 `node` 直接运行：
```json
{
"mcpServers": {
"timeverse-omni-converter-mcp": {
"command": "node",
"args": ["C:/path/to/timeverse-omni-converter-mcp/dist/index.js"],
"env": {
"FC_PYTHON_PATH": "python",
"FC_TEMP_DIR": "C:/temp/format-converter",
"FC_MAX_FILE_SIZE": "524288000",
"FC_TIMEOUT": "300000"
}
}
}
}
```
> macOS：将 `args` 改为 `/Users/<you>/timeverse-omni-converter-mcp/dist/index.js`，并将 `FC_PYTHON_PATH` 改为 `python3`（或删除该项，让其自动检测 `.venv`/`python3`）。
***
## 🔧 环境变量
| 变量 | 默认值 | 说明 |
| -------------------------- | ------------------- | -------------------- |
| `FC_PYTHON_PATH` | `python` | Python 解释器路径 |
| `FC_FFMPEG_PATH` | `ffmpeg` | FFmpeg 可执行文件路径 |
| `FC_FFPROBE_PATH` | `ffprobe` | ffprobe 可执行文件路径 |
| `FC_IMAGEMAGICK_PATH` | `magick` | ImageMagick 可执行文件路径 |
| `FC_LIBREOFFICE_PATH` | `soffice` | LibreOffice 可执行文件路径 |
| `FC_PANDOC_PATH` | `pandoc` | Pandoc 可执行文件路径 |
| `FC_CALIBRE_PATH` | `ebook-convert` | Calibre 电子书转换器路径 |
| `FC_TEMP_DIR` | 系统临时目录 | 临时文件目录 |
| `FC_MAX_FILE_SIZE` | `524288000` (500MB) | 最大输入文件大小 |
| `FC_MAX_EXTRACTED_SIZE` | `1073741824` (1GB) | 解压后总大小上限（防 zip bomb） |
| `FC_MAX_COMPRESSION_RATIO` | `100` | 最大压缩比 |
| `FC_MAX_PIXELS` | `100000000` | 图片解压像素上限（防解压炸弹） |
| `FC_TIMEOUT` | `300000` (5min) | 单次转换超时 |
| `FC_PARALLEL` | `1` | 默认并行数 |
| `FC_LOG_LEVEL` | `info` | 日志级别 |
***
## 💬 使用示例
向 MCP 客户端中的 LLM 发出自然语言指令，例如：
- 「把 `a.mov` 转成 `a.mp4`，分辨率 1920x1080」→ `convert_media`
- 「把 `photo.heic` 转成 `photo.png`」→ `convert_image`
- 「把 `report.docx` 转成 `report.pdf`」→ `convert_document`
- 「把 `data.json` 转成 `data.csv`」→ `convert_data`
- 「把 `slides.pptx` 每一页导出成 PNG」→ `convert_presentation`
- 「把 `book.epub` 转成 `book.mobi`」→ `convert_ebook`
- 「合并 `a.pdf` 和 `b.pdf`」→ `convert_pdf`（`operation: "merge"`）
- 「把 `subs.ass` 转成 `subs.srt`」→ `convert_subtitle`
工具调用示例：
```json
{
"name": "convert_media",
"arguments": {
"input_path": "C:/media/input.mov",
"output_format": "mp4",
"options": {
"video_codec": "libx264",
"video_resolution": "1920x1080",
"crf": 23
}
}
}
```
返回结果：
```json
{
"success": true,
"outputPath": "C:/media/input.mp4",
"outputSize": 10485760,
"duration": 3215,
"warnings": []
}
```
***
## ❓ 常见问题
**Q: 转换提示依赖缺失或失败怎么办？**
A: 调用 `check_dependencies` 工具查看各引擎（FFmpeg / ImageMagick / LibreOffice / Pandoc / Python）的可用状态与版本，安装缺失的依赖后重试。
**Q: Python 相关转换（数据 / PDF / 表格 / 字幕）报错？**
A: 确认已通过 `pip install -r python/requirements.txt` 安装依赖，并通过 `FC_PYTHON_PATH` 指向正确的 Python 解释器（或已激活虚拟环境）。
**Q: 目标文件已存在会发生什么？**
A: 默认自动重命名为 `文件名_1.扩展名`；批量转换时可通过 `on_conflict` 参数控制 `overwrite` / `skip` / `rename`。
**Q: 为什么某些格式（如 PAGES / NUMBERS）无法转换？**
A: 这些是 Apple 专有格式，需 macOS 原生应用或 iCloud 导出，属于受限格式，详见「已知限制」。
**Q: 大文件转换超时怎么办？**
A: 调大 `FC_TIMEOUT`（默认 300000ms），并注意 `FC_MAX_FILE_SIZE`（默认 500MB）上限。
***
## 🛡️ 安全
Server 处理不可信文件内容，内置多项资源与安全防护：
- 输入文件大小、解压后体积、压缩比、图片像素上限（防 zip bomb / 解压炸弹）
- 单次转换超时与并发上限
- 解析器禁用 XXE（外部实体注入）、PDF 嵌入脚本、外部资源加载
- 外部进程统一使用参数数组调用（`execFile`），避免命令注入
***
## 📄 License
MIT
TDQS
A3.6/5.0
Scored across 14 tools
Disambiguation5/5
每个转换工具针对特定媒体类型（媒体、图像、文档、演示、电子表格、标记、数据、电子书、PDF、字幕），用途明确不重叠。辅助工具如获取支持格式、文件信息、批量转换和依赖检查与转换工具区分明显。
Naming Consistency5/5
所有工具名称均采用一致的动词_名词模式（如convert_media、get_file_info、batch_convert），全部使用小写蛇形命名法，风格统一，易于预测和选择。
Tool Count5/5
14个工具覆盖了广泛的转换领域，每个工具都针对特定的格式类别或辅助功能，数量适中，没有冗余或明显不足，与服务器目的匹配。
Completeness5/5
工具集覆盖了媒体、图像、文档、演示、电子表格、标记、数据、电子书、PDF和字幕等多种格式转换，并包含格式查询、文件信息、批量转换和依赖检查等辅助功能，看似完整无重大缺失。
Maintenance
ActivityMaintained
ResponsivenessNo issues