pdfport

pdfport

pdfport は、繰り返し必要になる 5 つの PDF 処理を行います。ファイルからテキストを抽出する、文書のメタデータを読み取る、ページ数・ページサイズ・ファイルサイズ・PDF バージョンを要約する、複数のファイルを 1 つに結合する、ファイルをページごとに 1 つの文書へ分割する、という処理です。ローカルファイルのみを対象とし、どこにもアップロードしません。

エンジンは、このプロジェクト向けに純粋な TypeScript で記述された、小規模ながら本格的な PDF 実装です。PDF ライブラリは同梱されておらず、実行時の依存関係は MCP SDK のみです。エンジンは文書の間接オブジェクトを走査し、Catalog から Pages ツリーをたどり、非圧縮および FlateDecode のコンテンツストリームをデコードして、標準的なテキスト表示演算子からテキストを復元します。結合時には、元のオブジェクトの番号を振り直して新しいオブジェクトグラフにまとめ、ページツリーを再構築します。分割時も同様にページごとに文書を出力します。どちらも新たに計算したクロスリファレンステーブルを書き込みます。

対応範囲 — エンジンで処理できることとできないこと

対応：フラットなページツリーを持つシンプルな PDF（Pages ノードに Page オブジェクトが直接列挙された Catalog。一般的なジェネレーターが生成する形式であり、pdfport 自身が結合・分割時に出力する形式）、非圧縮または FlateDecode のストリーム、コンテンツおよび Info 辞書内のリテラル文字列と 16 進文字列、ページごとの MediaBox サイズ（ページに独自の値がない場合は Pages ノードから継承）。

非対応：暗号化ファイル、オブジェクトストリームおよび圧縮クロスリファレンスストリーム（PDF 1.5 以降のコンパクトなファイル形式）、ネストされたページツリー、読み取りに ToUnicode マップが必要な埋め込みフォントのエンコーディング、結合または分割時のフォーム／注釈の忠実な保持。対応範囲外のファイルでは、見つからなかったものを示す簡潔なエラーが返されます。pdfport がテキストやメタデータを捏造して返すことはありません。

インストール

npx @reneturcios/pdfport get-pdf-info ./report.pdf

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/pdfport

コンテナはデフォルトで MCP サーバーとして起動します（下記を参照）。CLI として使用するには、CLI 引数を渡してください。

CLI

# Print the document's text
pdfport extract-text ./report.pdf

# Print the Info-dictionary metadata (plus page count) as JSON
pdfport get-metadata ./report.pdf

# Print page count, page sizes, file size and PDF version as JSON
pdfport get-pdf-info ./report.pdf

# Merge inputs, in order, into one output file
pdfport merge ./combined.pdf ./a.pdf ./b.pdf ./c.pdf

# Split into <name>-page-1.pdf, <name>-page-2.pdf, ... in a directory
pdfport split ./report.pdf ./report-pages

# Start the MCP server
pdfport mcp

pdfport --version

終了コード：成功時は 0、ファイルが見つからない場合または文書を処理できない場合（エラーに対象が示されます）は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

1 つの実行ファイルで両方のインターフェースを提供します。mcp サブコマンドは stdio MCP サーバーを起動します。

npx -y @reneturcios/pdfport mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "pdfport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pdfport", "mcp"]
    }
  }
}

ツール

ツール	入力	戻り値
extract_text	file_path（文字列、必須）	ファイル内のテキスト：各ページに表示されているテキストを改行で連結したものです。
get_metadata	file_path（文字列、必須）	Info 辞書のタイトル、作成者、件名、キーワード、作成アプリケーション、プロデューサー、日付（文書に含まれるフィールドのみ）と、ページ数です。
get_pdf_info	file_path（文字列、必須）	ページ数、各ページの MediaBox サイズ（ポイント単位）、ファイルサイズ（バイト単位）、ヘッダーに記載された PDF バージョンです。
merge_pdfs	input_files（文字列の配列、必須）、output_file（文字列、必須）	結合した文書を書き込み、出力パスと合計ページ数を報告します。最初の入力ファイルのメタデータが保持されます。
split_pdf	file_path（文字列、必須）、output_dir（文字列、必須）	ディレクトリ内にページごとに 1 つの単ページファイルを書き込み、作成したファイルのパスとページ数を報告します。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

テストスイートでは、プレーンおよび FlateDecode のコンテンツストリームを含む小さな PDF を生の文字列から作成し、デフォルトのエンジンをエンドツーエンドで実行します。抽出（TJ 配列やリテラル文字列のエスケープを含む）、メタデータ、情報取得、結合、分割が、すべて実際の実装に対して検証されます。その後、ファイルファサードを一時ディレクトリ内の実ファイルでテストします。

ライセンス

MIT — LICENSE を参照してください。