ConvertAgent

AI エージェント向けに構築されたファイル変換。 CLI、REST API、MCP サーバーが、すべて同じエンジンを共有します。

クイックスタート · API リファレンス · MCP サーバー · 形式 · アーキテクチャ · ロードマップ

---

ConvertAgent は、AI エージェント向けに設計された、セルフホスト可能なオープンソースのファイル変換ツールキットです。ファイルがインフラストラクチャの外に出ることはありません。クラウドへのアップロードも、API キーも、変換ごとの料金も、使用制限もありません。インストールして実行するだけで、変換できます。ローカルエージェント向けの CLI、リモートアクセス向けの REST API、そしてエージェントエコシステム向けのMCPを利用できます。

セルフホスト可能。オープンソース。変換ごとの費用はゼロ。 エージェントはファイルをローカルで変換します。クラウドも、制限も、ベンダーロックインもありません。

---

✨ 機能

• 🖥️ CLI ファースト — convertagent convert file.pdf --to docx — エージェント向けのネイティブインターフェース
• 🌐 REST API — リモートエージェントや Web サービス向けの POST /v1/convert
• 🔌 MCP サーバー — MCP 互換の AI クライアント（Claude、ChatGPT、Cursor など）から検出可能
• ⚡ 1 つのディスパッチャー — 3 つのインターフェースすべてが同じ変換エンジンを共有
• 📦 20 種類の変換ペア — ドキュメント、画像、音声／動画、テキストに対応
• 🔧 オープンソースのエンジン — 内部では FFmpeg、LibreOffice、ImageMagick、Pandoc を使用
• 🚀 セルフホスト可能 — ファイルがインフラストラクチャの外に出ることはありません

---

📋 対応する変換

カテゴリー	変換
ドキュメント	pdf→docx · docx→pdf · html→pdf · md→pdf · md→html · md→docx · xlsx→csv · csv→xlsx · pptx→pdf
画像	jpg→png · png→jpg · png→webp · webp→png · svg→png · image-resize · image-compress
音声／動画	mp4→mp3 · wav→mp3 · mp4→gif · any-video→mp4

---

🚀 クイックスタート

前提条件

# Install conversion engines (Ubuntu/Debian)
sudo apt-get update && sudo apt-get install -y ffmpeg libreoffice imagemagick pandoc

インストールと実行

git clone https://github.com/vid-factory/convertagent.git
cd convertagent
npm install
npm run build

CLI の使用方法

# Convert a PDF to Word
convertagent convert report.pdf --to docx

# Convert with custom output path
convertagent convert photo.png --to webp --output ./compressed.webp

# Extract audio from video
convertagent convert video.mp4 --to mp3

# List all supported formats
convertagent formats

# Check engine health
convertagent health

API サーバーの起動

# Start on default port 3001
node dist/api/server.js

# Or with custom port
PORT=8080 node dist/api/server.js

---

📡 API リファレンス

POST /v1/convert

ファイルをある形式から別の形式に変換します。

リクエスト：

{
  "action": "pdf-to-docx",
  "source": "/path/to/file.pdf",
  "options": {}
}

URL ソースを使用する場合：

{
  "action": "html-to-pdf",
  "source_url": "https://example.com/page.html",
  "options": {}
}

base64 ソースを使用する場合：

{
  "action": "jpg-to-png",
  "source_base64": "data:image/jpeg;base64,/9j/4AAQ...",
  "options": {}
}

レスポンス：

{
  "success": true,
  "job_id": "a1b2c3d4",
  "artifact": {
    "path": "/output/a1b2c3d4.docx",
    "url": "/v1/artifacts/a1b2c3d4",
    "format": "docx",
    "size": 45231,
    "duration_ms": 1200
  }
}

GET /v1/formats

対応している変換ペアをすべて一覧表示します。

GET /health

エンジンの利用可能状況を確認します。

{
  "ok": true,
  "service": "convertagent",
  "engines": {
    "ffmpeg": true,
    "libreoffice": true,
    "imagemagick": true,
    "pandoc": true
  }
}

---

🔌 MCP サーバー

ConvertAgent は、MCP 互換の AI クライアントとの統合用に MCP サーバーを公開します。

利用可能なツール

ツール	説明
convert_file	ファイルをある形式から別の形式に変換します
list_formats	対応している変換形式のペアをすべて一覧表示します

MCP 経由で接続

{
  "mcpServers": {
    "convertagent": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

例：Claude Desktop

Claude Desktop の MCP 設定に追加します。

{
  "mcpServers": {
    "convertagent": {
      "command": "node",
      "args": ["/path/to/convertagent/dist/mcp/server.js"]
    }
  }
}

---

🏗️ アーキテクチャ

┌─────────────────────────────────────────────────────┐
│                    ConvertAgent                       │
│                                                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐              │
│  │   CLI   │  │   API   │  │   MCP   │  ← Interfaces│
│  └────┬────┘  └────┬────┘  └────┬────┘              │
│       │            │            │                     │
│       └────────────┼────────────┘                     │
│                    │                                  │
│           ┌────────▼────────┐                         │
│           │   Dispatcher    │  ← Shared routing core  │
│           └────────┬────────┘                         │
│                    │                                  │
│    ┌───────┬───────┼───────┬────────┐                │
│    │       │       │       │        │                │
│  ┌─▼──┐ ┌─▼──┐ ┌──▼──┐ ┌─▼────┐   │                │
│  │ FF │ │ LO │ │ IM  │ │ Pan  │   │  ← Engines     │
│  │mpeg│ │    │ │     │ │ doc  │   │                 │
│  └────┘ └────┘ └─────┘ └──────┘   │                │
│                                     │                │
│  FF = FFmpeg    LO = LibreOffice    │                │
│  IM = ImageMagick  Pan = Pandoc     │                │
└─────────────────────────────────────────────────────┘

---

🐳 Docker（近日公開）

docker run -p 3001:3001 vid-factory/convertagent

---

🛠️ 開発

# Clone
git clone https://github.com/vid-factory/convertagent.git
cd convertagent

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run the full 20-pair conversion test matrix
node scripts/run-tea-20.mjs

プロジェクト構成

convertagent/
├── src/
│   ├── cli/              # CLI commands (convert, formats, health)
│   ├── api/              # REST API server (Fastify)
│   ├── mcp/              # MCP server (Streamable HTTP)
│   ├── core/             # Shared dispatcher + format registry
│   ├── engines/          # Engine adapters
│   │   ├── ffmpeg.ts     # Audio/video conversions
│   │   ├── libreoffice.ts# Document conversions
│   │   ├── imagemagick.ts# Image conversions
│   │   ├── pandoc.ts     # Text/markup conversions
│   │   └── shell.ts      # Shared shell runner with timeouts
│   └── tests/            # Unit + integration tests
├── scripts/              # TEA matrix runner, utilities
├── test-assets/          # Real input files for testing
├── test-artifacts/       # TEA results + parity evidence
├── deploy/               # systemd service file
├── package.json
├── tsconfig.json
└── README.md

---

📊 テスト結果

ConvertAgent には、モックを使わない、実ファイルによる包括的なテストマトリックスが用意されています。

ペア	ステータス	エンジン
pdf→docx	✅ 合格	LibreOffice
docx→pdf	✅ 合格	LibreOffice
html→pdf	✅ 合格	Pandoc
md→pdf	✅ 合格	Pandoc
md→html	✅ 合格	Pandoc
md→docx	✅ 合格	Pandoc
xlsx→csv	✅ 合格	LibreOffice
csv→xlsx	✅ 合格	LibreOffice
pptx→pdf	✅ 合格	LibreOffice
jpg→png	✅ 合格	ImageMagick
png→jpg	✅ 合格	ImageMagick
png→webp	✅ 合格	ImageMagick
webp→png	✅ 合格	ImageMagick
svg→png	✅ 合格	ImageMagick
image-resize	✅ 合格	ImageMagick
image-compress	✅ 合格	ImageMagick
mp4→mp3	✅ 合格	FFmpeg
wav→mp3	✅ 合格	FFmpeg
mp4→gif	✅ 合格	FFmpeg
any-video→mp4	✅ 合格	FFmpeg

20/20 件合格 — CLI、API、MCP インターフェース全体で、バイナリ同等性チェックにより検証済みです。

---

🗺️ ロードマップ

• 20 種類の変換ペアに対応する CLI インターフェース
• REST API（/v1/convert、/v1/formats、/health）
• ツールの検出と実行に対応する MCP サーバー
• 実ファイルによる TEA テストマトリックス（20/20）
• インターフェース間の同等性検証（CLI = API = MCP）
• 永続稼働のための systemd デプロイ
• URL ソースの取り込み（変換用にリモートファイルを取得）
• ワンコマンドでデプロイできる Docker イメージ
• OpenClaw スキルパッケージ（ClawHub に公開）
• Claw Mart マーケットプレイスへの掲載
• パイプラインエンドポイント（複数の変換を連結）
• npm グローバルインストール（npm install -g convertagent）
• 使用状況の追跡とレート制限
• 追加のフォーマットペア（50 種類以上）

---

🤝 貢献

貢献を歓迎します！以下のガイドラインに従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feat/new-format-pair）
3. 新しい変換のテストを作成します（モックではなく実ファイルを使用してください）
4. TEA マトリックス全体を実行します（node scripts/run-tea-20.mjs）
5. Conventional Commits の形式でコミットします（feat:、fix:、docs:、test:）
6. プルリクエストを作成します

新しい変換ペアの追加

1. src/core/formats.ts にフォーマットペアを追加します
2. src/engines/ で適切なエンジンアダプターを実装または拡張します
3. test-assets/input/ に実際のテスト入力ファイルを追加します
4. scripts/run-tea-20.mjs の TEA マトリックスにペアを追加します
5. テストを実行し、出力を検証します

---

📄 ライセンス

MIT License — 詳細は LICENSE をご覧ください。

---

🙏 謝辞

• FFmpeg — オーディオ／動画処理
• LibreOffice — ドキュメント変換
• ImageMagick — 画像処理
• Pandoc — 汎用ドキュメントコンバーター
• Model Context Protocol — AI ツール連携の標準

---

AI 時代のエージェントインフラストラクチャを提供する vid-factory が開発しました。