Format Converter MCP

汎用フォーマット変換 MCP Server

音声・動画・画像・Office・データ・電子書籍・PDF・字幕など、あらゆるフォーマット変換をカバーする Model Context Protocol (MCP) サーバーです。TimeVerse Studio、Claude Desktop、Cursor、VS Code など、任意の MCP クライアントから呼び出せます。

English

✨ 特徴

Related MCP server: ChangeThisFile MCP Server

📦 対応フォーマット

* は制限付きフォーマット（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 個）

補助ツール（4 個）

すべての変換ツールは 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                                         │
└──────────────────────────────────────────────────────┘

スマートパスプランニングの例：

⚙️ 技術スタック

• メイン言語：TypeScript (Node.js ≥ 18)

• プロトコル：@modelcontextprotocol/sdk

• 変換エンジン：FFmpeg / ImageMagick / LibreOffice / Pandoc / Python (venv 分離) / PyMuPDF

システム依存関係

LaTeX（オプション、Markdown→PDF 高品質）と Calibre（オプション、MOBI/AZW3）は省略可能で、システムが自動的にフォールバックします。

Python 依存関係

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 依存関係をインストールします：

# 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 でワンクリック実行でき、ローカルビルドは不要です：

{
  "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 で直接実行します：

{
  "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 を自動検出させます）。

🔧 環境変数

💬 使用例

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

ツール呼び出しの例：

{
  "name": "convert_media",
  "arguments": {
    "input_path": "C:/media/input.mov",
    "output_format": "mp4",
    "options": {
      "video_codec": "libx264",
      "video_resolution": "1920x1080",
      "crf": 23
    }
  }
}

返り値：

{
  "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