pdfporter

pdfporter

ファイルを入力するとPDFを出力し、PDFを加工することもできます。pdfporterはconv2pdf変換サービスの クライアントです。お使いのコンピューター上のファイルパスを受け取り、変換のために送信して、 変換結果を元のファイルと同じ場所に書き込みます。Office文書、スプレッドシート、プレゼンテーション、 画像、電子書籍、PostScriptファイル、HTMLファイルをPDFに変換します。PDFはWord文書やページごとの 画像に変換できます。また、PDFの結合、分割、ページ抽出、回転、ページ番号の追加、透かしの追加、 圧縮、パスワード保護、ロック解除にも対応しています。

設定

• CONV2PDF_API_KEY（呼び出しに必須）— conv2pdfのダッシュボードにあるDeveloperタブで作成します。すべての リクエストでAuthorization: Bearer <key>として送信されます。キーがなくてもサーバーは起動し、ツールの一覧を 表示しますが、ツールの呼び出しはキーの設定方法を説明するメッセージとともに失敗します。
• CONV2PDF_API_URL（任意）— APIのベースURLです。デフォルトは https://api.conv2pdf.com/v1です。
• CONV2PDF_TIMEOUT_MS（任意）— リクエストごとのタイムアウト時間をミリ秒で指定します。デフォルトは 120000です。変換に正当に約1分かかる場合があるためです。

ツール

• convert_to_pdf — 拡張子に応じてファイルをPDFに変換します。Word、Excel、PowerPoint、OpenDocument、 Apple Pages、RTF、TXT、CSVファイルはoffice-to-pdfで変換します。PNG、JPG、WebP、GIF、TIFF画像は image-to-pdfで変換します。HEIC/HEIF写真はheic-to-pdf、EPUBはepub-to-pdf、PS/EPSはps-to-pdf、 HTMLはhtml-to-pdfで変換します。不明な拡張子の場合は、リクエストを送信せずにローカルで失敗します。
• convert_url_to_pdf — 公開ウェブページをURLからPDFに変換します。書き込み元となる入力ファイルがないため、 必ずoutput_pathを指定します。
• convert_heic_to_jpg — iPhoneのHEICまたはHEIF写真をJPGに変換します。
• convert_pdf_to_word — テキストを含むPDFを編集可能なDOCX文書に変換します。保護されたPDFを開くには passwordを指定します。
• convert_pdf_to_images — ページごとにPNG（デフォルト）またはJPGを作成し、ZIPファイルで返します。
• merge_pdfs — 2～20個のPDFを、pathsで指定した順序で1つに結合します。
• extract_pdf_pages — ranges（例：1-5,7,10-12）で指定したページを、新しいPDFに記載順で コピーします。
• split_pdf — ページごとにPDFを作成し、ZIPファイルにまとめます。
• rotate_pdf — rotationで指定した角度（90、180、270度）だけ、すべてのページを回転します。
• add_page_numbers — ページ番号を「3 / 12」（format: "full"、デフォルト）または「3」 （format: "simple"）の形式で、positionに指定した位置（デフォルトは下中央、または下左、下右）に 追加します。
• add_watermark — 最大50文字のtextをすべてのページにスタンプします。
• compress_pdf — quality（low、medium（デフォルト）、high）に応じて画像の解像度を72、150、300 DPIに 保ちながら、ファイルサイズを縮小します。
• protect_pdf — 新しいpassword（6～64文字）を設定します。prevent_printとprevent_copyを指定すると、 印刷またはコピーを禁止できます。
• unlock_pdf — 知っているパスワードをpasswordとして渡して削除するか、印刷およびコピーの制限を解除します。
• get_quota — APIキーのプラン、使用状況、制限をそのまま返します。

ほとんどのPDF読み取りツールでは、保護されたPDFを開くためのpasswordを任意で指定できます。結果にパスワードは設定されません。

変換の動作

1. 入力ファイルをローカルで読み込み、multipart/form-data として <base>/convert/<api-tool> に POST します。file フィールドにファイルを指定し、ツールのフィールドは文字列フィールドとして送信します。
2. HTTP 429 または 503 が返された場合、サーバーが指定する待機時間（Retry-After ヘッダーの値、またはヘッダーがない場合は本文の retry_after 秒）だけ待機して再試行します。再試行は最大 2 回で、待機時間が 30 秒以下の場合に限ります。
3. 変換レスポンスには job_id と相対パスの download_url が含まれます。結果は API のオリジンからダウンロードしてディスクに書き込み、ベストエフォートでサービスからジョブを削除します。

結果が上書きされることはありません。デフォルトでは、出力は入力ファイルと同じ場所に保存されます。変換では拡張子が置き換わり（report.docx は report.pdf になります）、PDF 操作ではサフィックスが追加されます（compress_pdf の場合は report-compressed.pdf、convert_pdf_to_images の場合は report-images.zip などになります）。結合では、最初の入力ファイルと同じ場所に merged.pdf が作成されます。出力先の名前がすでに使われている場合は、空きが見つかるまで拡張子の前に (2)、 (3)、…を追加します。output_path を明示的に指定した場合、その場所に既存のファイルがあると、何も送信する前に処理を拒否します。

変換が成功すると、{"job_id": ..., "output_path": ..., "size_bytes": ...} という JSON の概要が返されます。サービスから quota オブジェクトが送られた場合は、それも含まれます。get_quota はサービスのレスポンス本文をそのまま返します。

エラー：2xx 以外のレスポンスでは、本文に error コードが含まれる場合は conv2pdf error: <error>、含まれない場合は conv2pdf error: HTTP <status> で失敗します。API に到達できない場合は conv2pdf unreachable で失敗します。

CLI

各ツールは、JSON 引数文字列を 1 つ受け取るサブコマンドです。

npx @reneturcios/pdfporter convert_to_pdf '{"path":"report.docx"}'
npx @reneturcios/pdfporter convert_url_to_pdf '{"url":"https://example.com/article","output_path":"article.pdf"}'
npx @reneturcios/pdfporter convert_heic_to_jpg '{"path":"IMG_0001.heic"}'
npx @reneturcios/pdfporter convert_pdf_to_word '{"path":"report.pdf"}'
npx @reneturcios/pdfporter convert_pdf_to_images '{"path":"report.pdf","format":"jpg"}'
npx @reneturcios/pdfporter merge_pdfs '{"paths":["a.pdf","b.pdf"]}'
npx @reneturcios/pdfporter extract_pdf_pages '{"path":"report.pdf","ranges":"1-5,7,10-12"}'
npx @reneturcios/pdfporter split_pdf '{"path":"report.pdf"}'
npx @reneturcios/pdfporter rotate_pdf '{"path":"scan.pdf","rotation":90}'
npx @reneturcios/pdfporter add_page_numbers '{"path":"report.pdf","position":"bottom-right"}'
npx @reneturcios/pdfporter add_watermark '{"path":"contract.pdf","text":"CONFIDENTIAL"}'
npx @reneturcios/pdfporter compress_pdf '{"path":"big.pdf","quality":"low"}'
npx @reneturcios/pdfporter protect_pdf '{"path":"confidential.pdf","password":"secret123","prevent_print":true}'
npx @reneturcios/pdfporter unlock_pdf '{"path":"protected.pdf","password":"secret123"}'
npx @reneturcios/pdfporter get_quota '{}'
npx @reneturcios/pdfporter --version

終了コード：成功時は 0、実行時エラー時は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/pdfporter mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "pdfporter": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pdfporter", "mcp"],
      "env": {
        "CONV2PDF_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/pdfporter
docker run --rm ghcr.io/cloudcorprecords/pdfporter get_quota '{}'

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios