Faxbot

🚀 Faxbot - 首個也是唯一的開源、可自託管傳真 API

Faxbot 是首個且唯一的開源、可自託管傳真 API，只需一次函數調用即可發送傳真。儘管乍看之下這個倉庫的內容可能讓人有些應接不暇，但這是因為 Faxbot 支持多種後端（雲服務和自託管）、多種用於 AI 集成的 MCP 傳輸選項，以及符合 HIPAA 標準的安全配置。不過，大多數用戶只需關注其中一條適合自己的路徑即可。

其核心功能僅需一個函數調用 send_fax(phone_number, pdf_file) 就能完成傳真發送。

為何選擇 Faxbot

• 端到端開源且可自託管：可完全在自己的基礎設施上運行，並根據需求進行修改。
• 一個 API，多種後端：通過環境設置，可在 Phaxio、Sinch 和自託管的 SIP/Asterisk 之間輕鬆切換。
• 自帶 SIP 中繼：可選擇任何 SIP 提供商，後續只需更改幾個環境變量即可遷移。
• 完全本地化選項：使用 SIP 時，傳輸路徑中不涉及第三方雲服務，相關文件可存儲在自己的存儲系統中（支持 S3/MinIO）。
• 內置 AI 助手工具：提供 MCP 服務器（Node 和 Python），支持 stdio/HTTP/SSE；桌面 stdio 支持 filePath（避免 base64 大小限制問題）。
• 支持傳真接收：具備雲 Webhook 簽名驗證功能，或通過 Asterisk ReceiveFAX 將 TIFF 轉換為 PDF，支持郵箱路由、短有效期令牌和文件保留。
• 測試/開發後端：可模擬發送/接收流程，無需使用付費服務提供商。
• 供應商中立的 SDK：Node 和 Python 客戶端相同，應用代碼具有可移植性。

如有疑問或遇到問題，請隨時聯繫我們。查看 CONTRIBUTING.md 瞭解獲取幫助的最佳方式。

🚀 快速開始選項

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 分鐘即可完成設置
• 無需電話技術知識
• 按傳真次數付費（雲服務）

→ Phaxio 設置指南

選項 2：Sinch Fax API v3（雲服務）

• 直接上傳模式（無需獲取 PUBLIC_API_URL）
• 適用於 “Phaxio by Sinch” 賬戶
• 需要項目 ID 和 API 密鑰/密鑰對

→ Sinch 設置指南

選項 3：自託管 SIP/Asterisk

• 完全自主控制
• 無需按傳真次數支付雲服務費用
• 需要具備 SIP 中繼和 T.38 相關知識

→ SIP 設置指南

💻 AI 助手集成

→ MCP 集成指南

• Node MCP 服務器位於 node_mcp/ 目錄（支持 stdio、HTTP、SSE+OAuth），Python MCP 服務器位於 python_mcp/ 目錄。
• Node 和 Python 均提供支持 OAuth2 保護的 SSE MCP 服務器。

⚠️ 重要文件類型說明

• Faxbot 僅接受 PDF 和 TXT 文件。如果有圖片（PNG/JPG），需先將其轉換為 PDF 再發送。
• 快速轉換方法：
  • macOS 預覽：文件 → 導出為… → PDF
  • macOS 命令行：sips -s format pdf "in.png" --out "out.pdf"
  • Linux：img2pdf in.png -o out.pdf 或 magick convert in.png out.pdf
  • Windows：打開圖片 → 打印 → “Microsoft 打印到 PDF”。

💡 Stdio 使用提示

對於桌面助手，建議使用 Node 或 Python 的 stdio MCP，並通過 filePath 參數調用 send_fax 發送本地 PDF/TXT 文件，這樣可避免使用 base64 編碼，從而避免令牌限制問題。

📦 客戶端 SDK

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

→ SDK 使用指南

📚 詳細文檔

核心指南

• 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 Webhook）
• Sinch 設置 — 雲服務直接上傳（v3 API）
• SIP/Asterisk 設置 — 自託管 T.38

安全與合規

• HIPAA 要求 — 安全、業務夥伴協議（BAAs）和合規性清單
• OAuth/OIDC 設置 — 配置 SSE 與 Auth0、Okta、Azure AD、Google、Keycloak 的集成

文件處理

• 圖片與文本 PDF — 正確傳真掃描件/照片的方法

高級功能

• Phaxio 端到端測試 — 本地測試的模擬回調流程

開發狀態

• v3 插件工作（功能門控）狀態：查看 docs/V3_PHASE_STATUS.md。

📄 注意事項

• 接收功能：仍在開發中。接收功能的框架已在配置標誌和 development 分支中實現（見 PHASE_RECEIVE.md），但尚未正式發佈，且目前僅在後端隔離環境中可用（Phaxio/Sinch 回調、SIP/Asterisk 內部）。外發傳真功能已可用於生產環境。
• 默認後端：默認後端為 phaxio，便於新用戶上手。電話用戶可顯式設置 FAX_BACKEND=sip，使用 Sinch v3 的用戶可設置 FAX_BACKEND=sinch。
• 身份驗證：使用 X-API-Key 進行身份驗證，可通過反向代理進行速率限制。

演示