AeternaLabsHQ/pullmd

PullMD – 自己ホスト型 URL から Markdown への変換サービス

何ができるか

• ウェブページ（および他のメディア形式）を取得し、トークン効率の高いクリーンな Markdown ドキュメントを返す自己ホスト型ウェブサービス。
• オンラインコンテンツの要約された構造化表現が必要な人間と AI エージェントの両方を対象に設計されています。

主な機能

機能	詳細
ウェブページ抽出	カスケード処理：Cloudflare のネイティブ Markdown → Mozilla Readability → Trafilatura → （フォールバック）Playwright によるヘッドレス Chromium。Reddit および Hacker News のスレッド（コメントツリーを含む）も完全に対応。
ドキュメント変換（v3）	PDF、Word/PowerPoint/Excel、EPUB などはアップロードまたは URL で提供可能。オプションの OCR タイア（?pdf=ocr）により高品質なテーブルを生成。
メディア処理	画像 → キャプション生成；音声 → 音声認識；YouTube URL → タイトル、説明、タイムスタンプ付きトランスクリプト。すべて、任意の OpenAI 互換のビジョン/音声認識エンドポイントで動作。
出力形式	Markdown 本文には # タイトル + コンテンツのみ。すべてのメタデータ（元URL、取得日時、著者、サブレッド、いいね数、OCR/モデル使用状況など）は YAML フロントマターに格納。PULLMD_FRONTMATTER_FIELDS で不要なフィールドを除外可能。
共有可能な ID	各変換には 8 ハッシュ文字の ID が割り当てられます。GET /s/:id でキャッシュされた Markdown を取得し、1 時間以上古い場合は自動的に更新されます。
API サーフェス	• GET /api?url=… – ウェブページのワンショット変換。 • POST /api/file – ドキュメント、画像、音声のアップロードによる変換。 • POST /mcp – 状態なしストリーミングに対応する MCP（Claude互換）エンドポイント。
認証	3 モード：disabled（公開）、single-admin（1 人の管理者）、multi-user（セルフサービス登録）。管理者は提供された CLI でユーザーを管理可能。
セキュリティ	内部アドレス、ループバック、リンクローカル、クラウドメタデータアドレスをブロックする SSRF 対策を内蔵。PULLMD_ALLOWED_HOSTS でホストをホワイトリスト化可能。
拡張性	PULLMD_SITE_RECIPES でサイト固有の「レシピ」（JSON-LD からフロントマターへの変換、カスタムセレクタなど）を追加可能。
モニタリング	サイドカーのヘルスエンドポイント（GET /api/status）で、レンダラー（Playwright、MarkItDown など）が停止している場合 503 を返す。

実行方法

1. Docker Compose（推奨） – Docker Hub からマルチアーキテクチャイメージを取得し、1 つのコマンドで起動：

   mkdir pullmd && cd pullmd
   curl -O https://raw.githubusercontent.com/AeternaLabsHQ/pullmd/main/docker-compose.yml
   docker compose up -d   # サービスは http://localhost:3000 で稼働
   

   .env ファイルは不要。合理的なデフォルト値が組み込まれている。設定を上書きするには、compose ファイルと同じディレクトリに .env を作成する。
2. オプションのサイドカー – スタックには3つの補助コンテナが含まれます：
   • pullmd-trafilatura – Trafilatura 抽出サービス。
   • pullmd-playwright – JavaScript が豊富なページ用のヘッドレス Chromium/Firefox/WebKit レンダラー（イメージキャッシュに約 3.7 GB 追加）。静的抽出のみの場合は省略可能。
   • pullmd-markitdown – ドキュメントから Markdown への変換（PDF/Office/EPUB に必須）。変換機能を無効にするには省略。
3. ローカル開発 – リポジトリをクローンし、npm install を実行後、npm start を実行。

設定のハイライト（.env ファイルで設定）

• PUBLIC_URL – ヘルプページおよびダウンロード可能な Claude スキルで使用される公開オリジン。
• PULLMD_AUTH_MODE – disabled / single-admin / multi-user。
• PULLMD_ADMIN_EMAIL / PULLMD_ADMIN_PASSWORD – 管理者資格情報を初期化。
• PULLMD_VISION_API_KEY, PULLMD_STT_API_KEY – 任意の OpenAI 互換のビジョン/音声認識エンドポイントで画像キャプションまたは音声トランスクリプトを有効化。
• PULLMD_PDF_OCR_API_KEY – PDF 用のプレミアム OCR タイアを有効化（?pdf=ocr）。
• PULLMD_FRONTMATTER_FIELDS – LLM パイプラインのトークン使用量を抑えるために保持するフロントマターのキーをホワイトリスト化。
• DISABLE_PUBLIC_HISTORY – プライバシー重視のデプロイでグローバルな変換履歴を非表示に。
• PULLMD_ALLOWED_HOSTS – デフォルトの SSRF ブロックを無視して内部ホストを取得する必要がある場合にホワイトリスト化。

AI/LLM ワークフローにおける意義

• トークン効率：すべてのメタデータをフロントマターに移動し、本文を最小限にすることで、LLM に送信する際に URL やタイムスタンプの繰り返しによるコンテキストの浪費を回避。
• エージェント対応：MCP エンドポイントにより、Claude 風のエージェントがストリーミング対応 HTTP 呼び出しで変換をリクエスト可能。
• 自己ホスト制御：基本的なウェブ抽出には第三者の API キーが不要で、データのプライバシーとコストの予測可能性を確保。
• 拡張可能なメディア処理：画像や音声をリアルタイムでキャプションやトランスクリプトに変換可能。マルチモーダルエージェントに有用。

一般的な使用例

# ウェブページを1回限り Markdown に変換
curl "http://localhost:3000/api?url=https://example.com"

# PDF をアップロードして変換（markitdown サイドカーが必要）
curl -F file=@report.pdf http://localhost:3000/api/file

# ID で共有可能な Markdown を取得
curl http://localhost:3000/s/1a2b3c4d

ライセンス – AGPL-3.0（LICENSE を参照）。

---

上記のすべての詳細はリポジトリの README から直接取得；追加機能は推測されていません。