# Conversion Service MCP Server

An MCP server for the [PDF Tools Conversion Service](https://www.pdf-tools.com/docs/conversion-service/) Simple API v6.9.1, built from the official `openapi.yaml` spec.

## Tools

| Tool | Endpoint | Description |
|---|---|---|
| `convert_to_pdfa2` | `archive-pdfa2-default` | Convert to PDF/A-2 (recommended archival) |
| `convert_to_pdfa3` | `archive-pdfa3-default` | Convert to PDF/A-3 (e-invoices) |
| `convert_to_pdf` | `convert-to-pdf` | Convert any supported format to standard PDF |
| `merge_to_pdf` | `dossier-default` | Merge multiple documents into one PDF |
| `convert_to_pdfa2_print` | `archive-pdfa2-print-optimization` | PDF/A-2 optimized for printing |
| `convert_to_pdfa2_web` | `archive-pdfa2-web-optimization` | PDF/A-2 optimized for web |
| `convert_to_pdfa2_email` | `archive-pdfa2-email-optimization` | PDF/A-2 optimized for email |
| `repair_pdf` | `repair-pdf` | Convert to PDF, validate and repair |
| `convert_large_file` | `http.input/*` | Plain HTTP multipart for files >100 MB |
| `list_profiles` | -- | List all available profiles and endpoints |

## Dependencies

```bash
pip install mcp httpx
```

## Local Conversion Service Setup

The MCP server connects to a running instance of the PDF Tools Conversion Service. The easiest way to run it locally is via Docker.

### Prerequisites

- Docker Desktop installed and running
- The `eso-consrv` repo cloned locally

### Port conflicts (Windows only)

If you have the PDF Tools Windows services installed, they bind to the same ports as the Docker containers. Stop them first in an **elevated PowerShell**:

```powershell
net stop "Pdftools Licensing Gateway Service"
net stop "Pdftools Conversion Service Connections"
```

To prevent them from auto-starting on reboot (run once):

```powershell
Set-Service "LicensingGatewayService" -StartupType Manual
Set-Service "ConversionServiceConnectionService" -StartupType Manual
Set-Service "ConversionService" -StartupType Manual
```

### Start the containers

From the `eso-consrv` repo root:

```bash
docker compose --env-file docker-compose.env up -d
```

### Ports

| Service | Port | Purpose |
|---|---|---|
| license-gateway | 9999 | License management |
| conversion-service | 13033 | Advanced REST API |
| connector-service | 13034 | Simple REST API (used by MCP) |
| configurator-web | 13035 | Web UI for configuration |

### Health checks

```bash
curl http://localhost:9999/healthz/ready
curl http://localhost:13034/healthz
curl http://localhost:13033/api/v1/health
```

## MCP Configuration

Set the `CONVERSION_SERVICE_URL` environment variable to point to the Conversion Service Simple API. Default: `http://localhost:13034`.

### Claude Code

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "conversion-service": {
      "command": "python3",
      "args": ["<path-to-repo>/server.py"],
      "env": {
        "CONVERSION_SERVICE_URL": "http://localhost:13034"
      }
    }
  }
}
```

Or via CLI:

```bash
claude mcp add conversion-service -- python3 <path-to-repo>/server.py
```

### Claude Desktop

Add to `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/`, on Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "conversion-service": {
      "command": "python",
      "args": ["<path-to-repo>/server.py"],
      "env": {
        "CONVERSION_SERVICE_URL": "http://localhost:13034"
      }
    }
  }
}
```

## API Endpoints

Each profile supports two input modes:

- **JSON** (`/http.inputstructured/<profile>`) -- structured JSON with base64 content or URL references. Used by most tools.
- **Plain HTTP** (`/http.input/<profile>`) -- multipart/form-data for large files (>100 MB). Used by `convert_large_file`.

## Options

- `DOC.PASSWORD` -- unlock password-protected documents
- `META.AUTHOR` -- set author metadata on output PDF
- `OPTIMIZEPROFILE` -- `print`, `web`, or `max` (email) optimization