<p align="center">
  <img src="assets/banner.svg" alt="ConvertAgent — File conversion built for AI agents" width="800"/>
</p>

<p align="center">
  <strong>File conversion built for AI agents.</strong> CLI, REST API, and MCP server — all sharing one engine.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-0.1.0-blue?style=flat-square" alt="Version"/>
  <img src="https://img.shields.io/badge/tests-20%2F20_passing-brightgreen?style=flat-square" alt="Tests"/>
  <img src="https://img.shields.io/badge/MCP-compatible-8b5cf6?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMiAydjIwTTIgMTJoMjAiLz48L3N2Zz4=" alt="MCP Compatible"/>
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License"/>
  <img src="https://img.shields.io/badge/node-%3E%3D22-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node"/>
  <img src="https://img.shields.io/badge/engines-FFmpeg%20·%20LibreOffice%20·%20ImageMagick%20·%20Pandoc-orange?style=flat-square" alt="Engines"/>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> ·
  <a href="#-api-reference">API Reference</a> ·
  <a href="#-mcp-server">MCP Server</a> ·
  <a href="#-supported-conversions">Formats</a> ·
  <a href="#%EF%B8%8F-architecture">Architecture</a> ·
  <a href="#-roadmap">Roadmap</a>
</p>

---

ConvertAgent is a self-hosted, open-source file conversion toolkit designed for AI agents. Your files never leave your infrastructure — no cloud uploads, no API keys, no per-conversion fees, no usage limits. Just install, run, and convert. CLI for local agents, REST API for remote access, and [MCP](https://modelcontextprotocol.io/) for the agent ecosystem.

> **Self-hosted. Open source. Zero cost per conversion.** Your agent converts files locally — no cloud, no limits, no vendor lock-in.

---

## ✨ Features

- **🖥️ CLI-first** — `convertagent convert file.pdf --to docx` — the native interface for agents
- **🌐 REST API** — `POST /v1/convert` for remote agents and web services
- **🔌 MCP Server** — Discoverable by any MCP-compatible AI client (Claude, ChatGPT, Cursor, etc.)
- **⚡ One dispatcher** — All three interfaces share the same conversion engine
- **📦 20 conversion pairs** across documents, images, audio/video, and text
- **🔧 Open-source engines** — FFmpeg, LibreOffice, ImageMagick, Pandoc under the hood
- **🚀 Self-hosted** — Your files never leave your infrastructure

---

## 📋 Supported Conversions

| Category | Conversions |
|----------|------------|
| **Documents** | `pdf→docx` · `docx→pdf` · `html→pdf` · `md→pdf` · `md→html` · `md→docx` · `xlsx→csv` · `csv→xlsx` · `pptx→pdf` |
| **Images** | `jpg→png` · `png→jpg` · `png→webp` · `webp→png` · `svg→png` · `image-resize` · `image-compress` |
| **Audio/Video** | `mp4→mp3` · `wav→mp3` · `mp4→gif` · `any-video→mp4` |

---

## 🚀 Quick Start

### Prerequisites

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

### Install & Run

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

### CLI Usage

```bash
# 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
```

### Start the API Server

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

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

---

## 📡 API Reference

### `POST /v1/convert`

Convert a file from one format to another.

**Request:**

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

**With URL source:**

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

**With base64 source:**

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

**Response:**

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

### `GET /v1/formats`

List all supported conversion pairs.

### `GET /health`

Check engine availability.

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

---

## 🔌 MCP Server

ConvertAgent exposes an MCP server for integration with any MCP-compatible AI client.

### Available Tools

| Tool | Description |
|------|------------|
| `convert_file` | Convert a file from one format to another |
| `list_formats` | List all supported conversion format pairs |

### Connect via MCP

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

### Example: Claude Desktop

Add to your Claude Desktop MCP config:

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

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────┐
│                    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 (Coming Soon)

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

---

## 🛠️ Development

```bash
# 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
```

### Project Structure

```
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
```

---

## 📊 Test Results

ConvertAgent ships with a full real-file test matrix — no mocks.

| Pair | Status | Engine |
|------|--------|--------|
| pdf→docx | ✅ Pass | LibreOffice |
| docx→pdf | ✅ Pass | LibreOffice |
| html→pdf | ✅ Pass | Pandoc |
| md→pdf | ✅ Pass | Pandoc |
| md→html | ✅ Pass | Pandoc |
| md→docx | ✅ Pass | Pandoc |
| xlsx→csv | ✅ Pass | LibreOffice |
| csv→xlsx | ✅ Pass | LibreOffice |
| pptx→pdf | ✅ Pass | LibreOffice |
| jpg→png | ✅ Pass | ImageMagick |
| png→jpg | ✅ Pass | ImageMagick |
| png→webp | ✅ Pass | ImageMagick |
| webp→png | ✅ Pass | ImageMagick |
| svg→png | ✅ Pass | ImageMagick |
| image-resize | ✅ Pass | ImageMagick |
| image-compress | ✅ Pass | ImageMagick |
| mp4→mp3 | ✅ Pass | FFmpeg |
| wav→mp3 | ✅ Pass | FFmpeg |
| mp4→gif | ✅ Pass | FFmpeg |
| any-video→mp4 | ✅ Pass | FFmpeg |

**20/20 passing** — verified across CLI, API, and MCP interfaces with binary parity checks.

---

## 🗺️ Roadmap

- [x] CLI interface with 20 conversion pairs
- [x] REST API (`/v1/convert`, `/v1/formats`, `/health`)
- [x] MCP server with tool discovery + execution
- [x] Real-file TEA test matrix (20/20)
- [x] Cross-interface parity verification (CLI = API = MCP)
- [x] systemd deployment for persistence
- [ ] URL source intake (fetch remote files for conversion)
- [ ] Docker image for one-command deployment
- [ ] OpenClaw skill package (publish to ClawHub)
- [ ] Claw Mart marketplace listing
- [ ] Pipeline endpoint (chain multiple conversions)
- [ ] npm global install (`npm install -g convertagent`)
- [ ] Usage tracking + rate limiting
- [ ] Additional format pairs (50+)

---

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/new-format-pair`)
3. Write tests for new conversions (use real files, not mocks)
4. Run the full TEA matrix (`node scripts/run-tea-20.mjs`)
5. Commit with conventional commits (`feat:`, `fix:`, `docs:`, `test:`)
6. Open a Pull Request

### Adding a New Conversion Pair

1. Add the format pair to `src/core/formats.ts`
2. Implement or extend the appropriate engine adapter in `src/engines/`
3. Add a real test input file to `test-assets/input/`
4. Add the pair to the TEA matrix in `scripts/run-tea-20.mjs`
5. Run tests and verify output

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- **[FFmpeg](https://ffmpeg.org/)** — Audio/video processing
- **[LibreOffice](https://www.libreoffice.org/)** — Document conversions
- **[ImageMagick](https://imagemagick.org/)** — Image processing
- **[Pandoc](https://pandoc.org/)** — Universal document converter
- **[Model Context Protocol](https://modelcontextprotocol.io/)** — The standard for AI tool integration

---

<p align="center">
  Built by <a href="https://github.com/vid-factory">vid-factory</a> — Agent infrastructure for the AI era.
</p>