PDFCompress

PDFCompressは、人間とAIエージェントのための、構造を保持するオープンソースのPDF圧縮ツールです。独立に検証されたWPSスタイルの画像プリセットを使用しますが、WPS DLLを呼び出したり配布したりすることはなく、WPSアカウントにも依存しません。

その中核となるルールはシンプルです：

テキストとベクターはテキストとベクターのまま保持し、過大なサイズの描画画像のみをダウンサンプリングし、公開前に結果を検証します。

特徴

• 実際のPDF変換行列から画像解像度を計算します（Form XObject内にネストされた画像も含む）。

• WPS互換のhigh、standard、medium、low設定を適用します。

• 入札、入札、アーカイブ添付用のarchive-safeプロファイルを追加します。

• ソースファイルを保持し、別の出力パスにアトミックに書き込みます。

• デフォルトでブックマーク、添付ファイル、注釈、フォント、可視のPDF構造を保持します。

• 署名の無効化が明示的に承認されない限り、署名付きPDFを拒否します。

• 各候補の後にページ数、ページボックス、抽出可能なテキストを検証します。

• 前のJPEG結果を繰り返し再圧縮することなく、ターゲットサイズをサポートします。

• Python API、CLI、共有Agent Skill、Codexプラグイン、Claude Codeプラグイン、MCPサーバーを提供します。

Related MCP server: MokuPDF

インストール

Python 3.11以降が必要です。

git clone https://github.com/ncepuee/PDFCompress.git
cd PDFCompress
python -m pip install -e ".[mcp]"

uvを使用する場合：

uv tool install --editable ".[mcp]"

クローンせずにタグ付きGitHubリリースをインストール：

uv tool install "pdfcompress-agent[mcp] @ git+https://github.com/ncepuee/PDFCompress.git@v0.1.0"

クイックスタート

圧縮前に分析：

pdfcompress analyze "input.pdf" --json

WPS互換の高品質プロファイルで圧縮：

pdfcompress compress "input.pdf" "output.pdf" --preset high --json

4MB未満である必要がある正式な添付ファイルの場合：

pdfcompress compress "input.pdf" "output.pdf" `
  --preset archive-safe `
  --target-size-mb 4 `
  --json

既存のペアを検証：

pdfcompress verify "input.pdf" "output.pdf" --json

プリセット

4つのWPS互換値は、インストールされた圧縮プラグインのgenerateCompressArgsブランチから復元され、付属の分析ノートに独立に文書化されています。正確なWPSリサンプリングカーネル、クロマサブサンプリングポリシー、完全なオプティマイザービットマスクはコピーも主張もされていません。

ターゲットサイズの動作

--target-size-mbが指定されると、PDFCompressは要求されたプリセットから始めて、段階的に強力なプロファイルを試します。各試行は元のPDFを再度開きます：

archive-safe → high → standard → medium → low

制限未満の最初の検証済み候補が選択されます。どのプロファイルも制限に達しない場合、最小の検証済み候補が警告とともに返されます。PDFCompressは、ターゲットを強制するためにページを静かにラスタライズしたり、フォントを削除したり、添付ファイルを削除したりしません。

エージェント統合

Claude Code

まずPythonパッケージをインストールし、セッション用にプラグインをロードします：

cd PDFCompress
claude --plugin-dir .

スキルを/pdfcompress:pdf-compressとして呼び出すか、ClaudeにPDFの圧縮を依頼します。Claude Codeはプラグインの.mcp.jsonもロードし、pdfcompress-mcpをstdioで起動します。

Codex

リポジトリには、検証済みの.codex-plugin/plugin.json、共有skills/ディレクトリ、.mcp.jsonが含まれています。ローカルのCodexマーケットプレイスからインストールするか、スキルを個人/プロジェクトのスキルディレクトリにコピーできます。pdfcompress-mcpがPATH上にあるように、コアパッケージをインストールする必要があります。

一般的なMCPクライアント

このstdio設定を使用します：

{
  "mcpServers": {
    "pdfcompress": {
      "type": "stdio",
      "command": "pdfcompress-mcp",
      "args": []
    }
  }
}

MCPツール：

• analyze_pdf(path, password?)

• compress_pdf(input_path, output_path, preset?, target_size_mb?, overwrite?, allow_signature_loss?)

• verify_pdf(input_path, output_path)

オープンソースの研究と採用したアイデア

ライセンス境界についてはTHIRD_PARTY_NOTICES.mdを参照してください。

安全性と制限事項

• PDFを書き換えるとデジタル署名が無効になります。デフォルトでは停止します。

• 暗号化されたPDFにはパスワードが必要です。出力時には暗号化が保持されます。

• バージョン0.1では、視覚的な破損のリスクを避けるため、画像マスク、透明度、カスタムデコード配列、特殊な色空間、8ビット以外の画像をスキップします。

• テキストの等価性チェックは抽出可能なテキストを使用します。OCRなしのスキャンページは、依然として視覚的なQAが必要です。

• 法的に重要な文書や非常に複雑な文書にツールを使用する前に、ピクセルレベルのレンダリング比較を推奨します。

• 候補がソースより小さくない場合、PDFCompressはソースのバイト単位のコピーを出力し、安全なサイズ削減が見つからなかったことを報告します。

検証済みの例

開発中に使用された12ページの画像中心のPDFについて：

100 DPIレンダリング比較では、すべてのページ寸法が一致しました。archive-safeの結果は、0〜255チャンネルスケールで平均ページごとのRGB RMS差が0.388、最大が3.002でした。これは1つの検証ケースであり、普遍的な品質保証ではありません。

開発

python -m pip install -e ".[mcp,dev]"
pytest
ruff check .

テストは、検索可能なテキストと高解像度画像を含む独自のPDFを生成します。リポジトリには個人文書は含まれていません。

ライセンス

PDFCompressはMITライセンスの下でリリースされています。サードパーティの依存関係はそれぞれのライセンスを保持します。

バージョンごとの変更とダウンロード可能なPythonパッケージについては、変更履歴とGitHubリリースを参照してください。