Faxbot

🚀 Faxbot - 最初で唯一のオープンソース、セルフホスティング可能なFAX API

Faxbotは、最初で唯一のオープンソースでセルフホスティング可能なFAX APIです。1つの関数呼び出しでFAXを送信できます。

このリポジトリは一見すると圧倒的に見えるかもしれませんが、それはFaxbotが複数のバックエンド（クラウドとセルフホスティング）、AI統合のためのいくつかのMCPトランスポートオプション、およびHIPAA準拠のセキュリティ構成をサポートしているからです。ほとんどのユーザーはこの複雑さの中から1つのパスだけを必要とするでしょう。

コア関数: send_fax(phone_number, pdf_file) → 完了。

🚀 クイックスタート

Docker Compose (API + オプションのMCP)

• .env をコピーして編集します（または .env.example から始めます）。
• APIを起動します:

docker compose up -d --build api

• オプションのMCP (HTTP, ポート3001):

docker compose --profile mcp up -d --build faxbot-mcp
# または: make mcp-up

• オプションのMCP SSE (OAuth2/JWT, ポート3002):

export OAUTH_ISSUER=https://YOUR_ISSUER
export OAUTH_AUDIENCE=faxbot-mcp
export OAUTH_JWKS_URL=https://YOUR_ISSUER/.well-known/jwks.json
docker compose --profile mcp up -d --build faxbot-mcp-sse
# または: make mcp-sse-up

• ヘルスチェック: curl http://localhost:8080/health
• レディネスチェック: curl -i http://localhost:8080/health/ready (準備ができている場合は200、できていない場合は503)
• MCP HTTPのヘルスチェック: curl http://localhost:3001/health
• MCP SSEのヘルスチェック: curl http://localhost:3002/health

オプション1: Phaxio (ほとんどのユーザーにおすすめ)

• セットアップに5分
• 電話技術の知識不要
• FAXごとに支払い (クラウド)

→ Phaxioセットアップガイド

オプション2: Sinch Fax API v3 (クラウド)

• 直接アップロードモデル (PUBLIC_API_URLのフェッチ不要)
• “Phaxio by Sinch” アカウントで動作
• プロジェクトID + APIキー/シークレットが必要

→ Sinchセットアップガイド

オプション3: セルフホスティングのSIP/Asterisk

• 完全なコントロール
• FAXごとのクラウド料金なし
• SIPトランクとT.38の知識が必要

→ SIPセットアップガイド

✨ 主な機能

• オープンソースでエンドツーエンドのセルフホスティング可能: 完全に自社のインフラで実行でき、必要に応じて変更できます。
• 1つのAPI、複数のバックエンド: 環境設定を介してPhaxio ↔ Sinch ↔ セルフホスティングのSIP/Asteriskを切り替えられます。
• 独自のSIPトランクを持ち込める: 任意のSIPプロバイダーを選択でき、いくつかの環境変数を変更することで後で移行できます。
• 完全にローカルなオプション: SIPを使用する場合、パスにサードパーティのクラウドは含まれません。成果物は自社のストレージ（S3/MinIO対応）に残ります。
• 組み込みのAIアシスタントツール: stdio/HTTP/SSE用のMCPサーバー (Node & Python)。デスクトップのstdioは filePath をサポートしています (base64のサイズ制限の問題がありません)。
• 着信受信設計: 署名検証付きのクラウドウェブフックまたはAsterisk ReceiveFAX → TIFF→PDF、メールボックスルーティング、短いTTLのトークン、保持機能。
• テスト/開発用バックエンド: 有料のプロバイダーにアクセスせずに送受信フローをシミュレートできます。
• ベンダー中立のSDK: 同一のNode/Pythonクライアントがあり、アプリコードを移植可能です。

📦 インストール

クライアントSDK

• Python: pip install faxbot
• Node.js: npm install faxbot

→ SDK使用ガイド

💻 使用例

基本的な使用法

# コア関数の呼び出し
send_fax(phone_number, pdf_file)

📚 ドキュメント

コアガイド

• MCP統合 — Claude/Cursor stdio, HTTP, SSE (Node + Python)
• APIリファレンス — エンドポイントとサンプル
• クライアントSDK — PythonとNode SDKの使用方法
• MCPインスペクター: docker compose --profile mcp up -d mcp-inspector を使用し、http://localhost:6274 を開いてツール/リソース/プロンプトを探索します。

バックエンド

• Phaxioセットアップ — クラウド (トークン化されたPDF URL + HMACウェブフック)
• Sinchセットアップ — クラウド直接アップロード (v3 API)
• SIP/Asteriskセットアップ — セルフホスティングのT.38

セキュリティとコンプライアンス

• HIPAA要件 — セキュリティ、BAA、およびコンプライアンスチェックリスト
• OAuth/OIDCセットアップ — Auth0、Okta、Azure AD、Google、KeycloakでSSEを設定します。

ファイル処理

• 画像とテキストPDF — スキャン/写真をFAXする正しい方法

高度な使い方

• Phaxioエンドツーエンドテスト — ローカルテスト用のシミュレートされたコールバックフロー

開発状況

• v3プラグインの作業 (機能ゲート付き) の状況: docs/V3_PHASE_STATUS.md を参照してください。

🔧 技術詳細

AIアシスタント統合

→ MCP統合ガイド

• Node MCPサーバーは node_mcp/ にあります (stdio, HTTP, SSE+OAuth)。Python MCPサーバーは python_mcp/ にあります。
• OAuth2で保護されたSSE MCPサーバーはNodeとPythonの両方で利用可能です。

重要なファイルタイプの注意事項

• FaxbotはPDFとTXTのみを受け付けます。画像 (PNG/JPG) がある場合は、送信前にPDFに変換してください。
• 簡単な変換方法:
  • macOS Preview: ファイル → PDFとしてエクスポート…
  • macOS CLI: sips -s format pdf "in.png" --out "out.pdf"
  • Linux: img2pdf in.png -o out.pdf または magick convert in.png out.pdf
  • Windows: 画像を開く → 印刷 → “Microsoft Print to PDF”

Stdioの使い方のヒント

• デスクトップアシスタントの場合、NodeまたはPythonのstdio MCPを使用し、send_fax をローカルのPDF/TXTの filePath で呼び出すことをおすすめします。これにより、base64を回避し、トークン制限を避けることができます。

📄 ライセンス

ドキュメントにライセンス情報は記載されていません。

その他の注意事項

• 着信機能: 開発中です。着信の足場は設定フラグの背後と development ブランチに存在します (PHASE_RECEIVE.mdを参照)。まだ一般公開されておらず、バックエンドは分離されています (Phaxio/Sinchのコールバック、SIP/Asteriskの内部)。発信は本番環境で使用できます。
• デフォルトのバックエンド: オンボーディングを容易にするため、デフォルトのバックエンドは phaxio です。電話ユーザーは FAX_BACKEND=sip を明示的に設定し、Sinch v3ユーザーは FAX_BACKEND=sinch を設定してください。
• 認証: X-API-Key を使用して認証し、レート制限のためにリバースプロキシの背後に配置してください。

デモ

質問や問題がある場合は、遠慮なくお問い合わせください。ヘルプを得る最良の方法は CONTRIBUTING.md を参照してください。