docs: update README and MCP integration guide to recommend new Node MCP servers with OCR support; enhance troubleshooting documentation for OCR and transport options

Author: DMontgomery40

README.md

@@ -23,8 +23,11 @@ Simple fax-sending API with AI integration. Choose your backend:
 ## AI Assistant Integration
 [→ MCP Integration Guide](docs/MCP_INTEGRATION.md)
 
-- Quick start: use the scripts in `api/scripts` (`start-mcp.sh`, `start-mcp-http.sh`) or `make mcp-stdio` / `make mcp-http`.
-- New: OAuth2‑protected SSE MCP servers for Node and Python — see the SSE sections in the MCP guide.
+- Recommended (OCR, avoids base64): use the new Node MCP servers in `node_mcp/` and the `faxbot_pdf` prompt to extract PDF text locally and send as TXT fax.
+  - `cd node_mcp && npm install && ./scripts/start-stdio.sh`
+  - Env: `FAX_API_URL`, `API_KEY`, optional `MAX_TEXT_SIZE`
+- Legacy servers remain under `api/` (`start-mcp.sh`, `start-mcp-http.sh`) and Python `python_mcp/`.
+- OAuth2‑protected SSE MCP servers are available in both Node and Python — see the SSE sections in the MCP guide.
 
 ## Client SDKs
 - Python: `pip install faxbot`

docs/MCP_INTEGRATION.md

@@ -15,6 +15,14 @@ Faxbot provides **2 MCP servers × 3 transports = 6 integration options**:
 | **HTTP** | mcp_http_server.js | 3001 | API key | Web apps, cloud AI |
 | **SSE+OAuth** | mcp_sse_server.js | 3002 | JWT/Bearer | Enterprise, HIPAA |
 
+New (recommended) Node MCP servers with OCR prompt live under `node_mcp/`:
+
+| Transport | File (node_mcp) | Port | Auth | Notes |
+|-----------|------------------|------|------|-------|
+| **stdio** | src/servers/stdio.js | N/A | API key | Includes `faxbot_pdf` prompt (OCR) |
+| **HTTP** | src/servers/http.js | 3001 | API key | Streamable HTTP + prompts |
+| **SSE+OAuth** | src/servers/sse.js | 3002 | JWT/Bearer | Prompts + OAuth2 |
+
 **Quick Selection Guide:**
 - **stdio**: Desktop AI assistants (Claude Desktop, Cursor) - simplest setup
 - **HTTP**: Web applications, cloud-based AI services - scalable
@@ -49,7 +57,7 @@ Assistant → MCP Server → Faxbot API → Backend (Phaxio or SIP/Asterisk)
    - Pass huge base64 string as tool parameter
    - Base64 encoding increases file size by ~33%
 
-### Realistic User Workflow:
+### Realistic User Workflow (Legacy Base64 Path):
 ```
 ❌ NOT POSSIBLE: "Hey Claude, fax document.pdf to +1234567890"
 
@@ -69,7 +77,60 @@ Assistant → MCP Server → Faxbot API → Backend (Phaxio or SIP/Asterisk)
 ### Why This Design Was Chosen:
 MCP protocol's JSON-based messaging requires binary data as base64. Alternative approaches (file paths, resource URLs) are emerging in the MCP community but not yet standardized for tool parameters.
 
-## Setup
+## OCR Workaround (Recommended): Faxbot Prompt/Tool (Node + Python)
+
+The new Node MCP servers in `node_mcp/` add a prompt-driven workflow that avoids sending base64 data through the conversation. Python MCP servers now include a matching tool for parity.
+
+- Node prompt: `faxbot_pdf`
+- Python tool: `faxbot_pdf(pdf_path, to, header_text?)`
+- Behavior: Extracts text from the local PDF and sends it as a TXT fax to drastically reduce tokens. If text is not embedded, optional OCR fallback can be enabled.
+
+Example prompt execution (conceptual GetPrompt request):
+```
+name: "faxbot_pdf"
+arguments: { "pdf_path": "/abs/path/report.pdf", "to": "+15551234567", "header_text": "Acme Clinic" }
+```
+
+Start Node MCP servers with OCR support:
+```
+# stdio (desktop assistants)
+cd node_mcp && npm install
+FAX_API_URL=http://localhost:8080 API_KEY=$API_KEY ./scripts/start-stdio.sh
+
+# HTTP (port 3001)
+FAX_API_URL=http://localhost:8080 API_KEY=$API_KEY MCP_HTTP_PORT=3001 ./scripts/start-http.sh
+
+# SSE + OAuth (port 3002)
+OAUTH_ISSUER=... OAUTH_AUDIENCE=... FAX_API_URL=http://localhost:8080 API_KEY=$API_KEY \
+  MCP_SSE_PORT=3002 ./scripts/start-sse.sh
+```
+
+Notes:
+- Set `MAX_TEXT_SIZE` (default 100000 bytes) to control extracted text size. Exceeding text is truncated with a warning.
+- This path does not embed base64 in the AI conversation, improving reliability for large PDFs.
+
+Python MCP (stdio/HTTP/SSE) with OCR tool:
+```
+cd python_mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+export FAX_API_URL=http://localhost:8080
+export API_KEY=your_api_key
+export FAXBOT_OCR_ENABLE=true        # optional; enables OCR fallback when embedded text is missing
+export FAXBOT_OCR_DPI=200            # optional; rasterization DPI for OCR
+python stdio_server.py               # stdio
+# or: uvicorn http_server:app --host 0.0.0.0 --port 3004
+# or: uvicorn server:app --host 0.0.0.0 --port 3003 (SSE+OAuth)
+```
+
+OCR dependencies (Python optional):
+- Requires `pdfminer.six` (installed via requirements)
+- OCR fallback requires: `pypdfium2`, `Pillow`, `pytesseract`, and the Tesseract binary on your system
+  - macOS: `brew install tesseract`
+  - Ubuntu/Debian: `sudo apt-get install tesseract-ocr`
+  - Set `TESSERACT_CMD` if tesseract is not on PATH
+
+## Setup (Legacy /api servers)
 1) API running at `FAX_API_URL` (default `http://localhost:8080`).
 2) Install Node deps in `api/`:
 ```
@@ -81,7 +142,7 @@ export FAX_API_URL=http://localhost:8080
 export API_KEY=your_secure_api_key
 ```
 
-## Quick Start (Scripts)
+## Quick Start (Scripts) — Legacy /api servers
 - macOS/Linux (stdio):
 ```
 FAX_API_URL=http://localhost:8080 API_KEY=$API_KEY \
@@ -111,7 +172,7 @@ FAX_API_URL=http://localhost:8080 API_KEY=$API_KEY faxbot-mcp
 FAX_API_URL=http://localhost:8080 API_KEY=$API_KEY MCP_HTTP_PORT=3001 faxbot-mcp-http
 ```
 
-## Stdio Transport (Claude Desktop, Cursor)
+## Stdio Transport (Claude Desktop, Cursor) — Legacy /api server
 - Node (stdio) start:
 ```
 cd api && npm run start:mcp
@@ -132,7 +193,7 @@ export API_KEY=your_api_key
 python stdio_server.py
 ```
 
-## HTTP Transport (Cloud/Local)
+## HTTP Transport (Cloud/Local) — Legacy /api server
 - Node (HTTP) start:
 ```
 cd api && npm run start:http

docs/TROUBLESHOOTING.md

@@ -36,9 +36,9 @@ If you're unsure which MCP transport to use:
 
 | Transport | File | Port | Auth | Use Case |
 |-----------|------|------|------|----------|
-| **stdio** | mcp_server.js | N/A | API key | Claude Desktop, Cursor |
-| **HTTP** | mcp_http_server.js | 3001 | API key | Web apps, cloud AI |
-| **SSE+OAuth** | mcp_sse_server.js | 3002 | JWT/Bearer | Enterprise, HIPAA |
+| **stdio** | api/mcp_server.js or node_mcp/src/servers/stdio.js | N/A | API key | Desktop AI |
+| **HTTP** | api/mcp_http_server.js or node_mcp/src/servers/http.js | 3001 | API key | Web apps, cloud AI |
+| **SSE+OAuth** | api/mcp_sse_server.js or node_mcp/src/servers/sse.js | 3002 | JWT/Bearer | Enterprise, HIPAA |
 
 ### Common MCP Problems
 
@@ -50,10 +50,23 @@ If you're unsure which MCP transport to use:
   - 100KB PDF = usable
   - 500KB PDF = borderline  
   - 1MB+ PDF = probably fails
-- **Workaround**: Use smaller PDFs or convert large documents to text first
+- **Recommended Workaround (OCR)**: Use the Faxbot OCR workflow to extract text locally and send as TXT fax.
+  - Node prompt: `faxbot_pdf` (in `node_mcp/`)
+  - Python tool: `faxbot_pdf(pdf_path, to, header_text?)` (in `python_mcp/`)
+  - Start (Node): `cd node_mcp && npm install && ./scripts/start-stdio.sh`
+  - Start (Python): `cd python_mcp && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && python stdio_server.py`
+  - Env: set `FAX_API_URL` and `API_KEY`; optional `MAX_TEXT_SIZE`, `FAXBOT_OCR_ENABLE=true`, `FAXBOT_OCR_DPI=200`
 
 #### Connection & Authentication
-- **MCP server not found**: Ensure you're in the `api/` directory when starting MCP servers
+- **MCP server not found**: Ensure you’re starting from the correct path:
+  - Legacy servers: `api/scripts/start-mcp*.sh`
+  - New servers (recommended): `node_mcp/scripts/start-*.sh`
+  - Python servers: `python_mcp/` (`stdio_server.py`, `http_server.py`, `server.py`)
+
+### OCR Issues (Python)
+- `pytesseract` errors: Install Tesseract OCR (macOS: `brew install tesseract`, Ubuntu: `sudo apt-get install tesseract-ocr`). Ensure `tesseract` is on PATH or set `TESSERACT_CMD`.
+- `pypdfium2` missing: Run `pip install -r python_mcp/requirements.txt` within a virtualenv.
+- OCR not triggered: Ensure `FAXBOT_OCR_ENABLE=true`. The code only falls back to OCR when extracted text is empty or very short.
 - **Authentication failures**: 
   - stdio: Check `API_KEY` environment variable matches Faxbot API setting
   - HTTP: Verify `X-API-Key` header is being passed correctly

node_mcp/src/servers/http.js

@@ -80,8 +80,16 @@ app.delete('/mcp', async (req, res) => {
   await session.transport.handleRequest(req, res);
 });
 
-const port = parseInt(process.env.MCP_HTTP_PORT || '3001', 10);
-app.listen(port, () => {
-  console.log(`Faxbot MCP HTTP (streamable) on http://localhost:${port}`);
-});
+export async function start() {
+  const port = parseInt(process.env.MCP_HTTP_PORT || '3001', 10);
+  app.listen(port, () => {
+    console.log(`Faxbot MCP HTTP (streamable) on http://localhost:${port}`);
+  });
+}
 
+if (import.meta.url === `file://${process.argv[1]}`) {
+  start().catch((err) => {
+    console.error('Failed to start HTTP server:', err);
+    process.exit(1);
+  });
+}

node_mcp/src/servers/sse.js

@@ -99,8 +99,16 @@ app.delete('/messages', authenticate, async (req, res) => {
   }
 });
 
-const port = parseInt(process.env.MCP_SSE_PORT || '3002', 10);
-app.listen(port, () => {
-  console.log(`Faxbot MCP SSE (OAuth2) on http://localhost:${port}`);
-});
+export async function start() {
+  const port = parseInt(process.env.MCP_SSE_PORT || '3002', 10);
+  app.listen(port, () => {
+    console.log(`Faxbot MCP SSE (OAuth2) on http://localhost:${port}`);
+  });
+}
 
+if (import.meta.url === `file://${process.argv[1]}`) {
+  start().catch((err) => {
+    console.error('Failed to start SSE server:', err);
+    process.exit(1);
+  });
+}

node_mcp/src/shared/pdf-extractor.js

@@ -22,7 +22,8 @@ export async function extractTextFromBuffer(buffer) {
     throw new Error('Invalid or empty buffer provided');
   }
   try {
-    const { default: pdf } = await import('pdf-parse');
+    const mod = await import('pdf-parse/lib/pdf-parse.js');
+    const pdf = mod.default || mod;
     const data = await pdf(buffer);
     const cleaned = normalizeWhitespace(data.text || '');
     if (!cleaned) {

python_mcp/requirements.txt

@@ -3,3 +3,7 @@ starlette>=0.36.3
 uvicorn>=0.30.6
 python-jose>=3.3.0
 httpx>=0.27.2
+pdfminer.six>=20231228
+pypdfium2>=4.30.0
+Pillow>=10.3.0
+pytesseract>=0.3.10

python_mcp/server.py

@@ -21,6 +21,7 @@
     uvicorn server:app --host 0.0.0.0 --port 3003
 """
 import base64
+import pathlib
 import os
 import time
 from typing import Dict, Any, Optional
@@ -206,6 +207,44 @@ async def get_fax_status(jobId: str) -> str:  # noqa: N803
     return "\n".join(lines)
 
 
+def _normalize_and_truncate(text: str) -> str:
+    max_bytes = int(os.getenv("MAX_TEXT_SIZE", "100000"))
+    b = text.encode("utf-8")
+    if len(b) > max_bytes:
+        return b[:max_bytes].decode("utf-8", errors="ignore")
+    return text
+
+
+@mcp.tool()
+async def faxbot_pdf(pdf_path: str, to: str, header_text: str = "") -> str:
+    """Extract text from a PDF (with optional OCR fallback) and send as TXT fax.
+
+    Mirrors the Node `faxbot_pdf` prompt functionality for Python MCP.
+    """
+    from .text_extract import extract_text_from_pdf
+
+    if not pdf_path:
+        raise ValueError("pdf_path is required")
+    abs_path = str(pathlib.Path(pdf_path).expanduser().resolve())
+    if not os.path.exists(abs_path):
+        raise ValueError(f"File not found: {abs_path}")
+    if not abs_path.lower().endswith(".pdf"):
+        raise ValueError("Only PDF input is supported")
+
+    text, used_ocr = extract_text_from_pdf(abs_path)
+    if header_text and header_text.strip():
+        text = f"{header_text.strip()}\n\n{text}"
+    text = _normalize_and_truncate(text)
+
+    file_b64 = base64.b64encode(text.encode("utf-8")).decode("ascii")
+    job = await api_send_fax(to, "extracted.txt", file_b64, "txt")
+    method = "OCR" if used_ocr else "text extraction"
+    return (
+        f"Faxbot workflow initiated via {method}.\n\nPDF: {abs_path}\nJob ID: {job['id']}\nRecipient: {to}\n"
+        f"Status: {job['status']}\n(Truncation may apply; adjust MAX_TEXT_SIZE if needed.)"
+    )
+
+
 # Build underlying SSE ASGI app from FastMCP
 inner_app = mcp.sse_app()
 
@@ -236,4 +275,3 @@ async def health(_request: Request):
     ],
 )
 app.add_middleware(AuthMiddleware)
-

python_mcp/stdio_server.py

@@ -14,6 +14,8 @@
 """
 import asyncio
 import os
+import base64
+import pathlib
 from typing import Optional, Dict, Any
 
 import httpx
@@ -98,6 +100,50 @@ async def get_fax_status(jobId: str) -> str:  # noqa: N803
     return "\n".join(parts)
 
 
+def _normalize_and_truncate(text: str) -> str:
+    max_bytes = int(os.getenv("MAX_TEXT_SIZE", "100000"))
+    b = text.encode("utf-8")
+    if len(b) > max_bytes:
+        return b[:max_bytes].decode("utf-8", errors="ignore")
+    return text
+
+
+@mcp.tool()
+async def faxbot_pdf(pdf_path: str, to: str, header_text: str = "") -> str:
+    """Extract text from a PDF (with optional OCR fallback) and send as TXT fax.
+
+    Args:
+        pdf_path: Absolute or relative path to a local PDF file
+        to: Destination fax number
+        header_text: Optional header text prepended to the content
+    Returns:
+        Confirmation string including job ID.
+    """
+    from .text_extract import extract_text_from_pdf
+
+    if not pdf_path:
+        raise ValueError("pdf_path is required")
+    abs_path = str(pathlib.Path(pdf_path).expanduser().resolve())
+    if not os.path.exists(abs_path):
+        raise ValueError(f"File not found: {abs_path}")
+    if not abs_path.lower().endswith(".pdf"):
+        raise ValueError("Only PDF input is supported")
+
+    text, used_ocr = extract_text_from_pdf(abs_path)
+    if header_text and header_text.strip():
+        text = f"{header_text.strip()}\n\n{text}"
+    text = _normalize_and_truncate(text)
+
+    # Encode as base64 TXT and send via existing API function
+    file_b64 = base64.b64encode(text.encode("utf-8")).decode("ascii")
+    job = await _api_send(to, "extracted.txt", file_b64, "txt")
+    method = "OCR" if used_ocr else "text extraction"
+    return (
+        f"Faxbot workflow initiated via {method}.\n\nPDF: {abs_path}\nJob ID: {job['id']}\nRecipient: {to}\n"
+        f"Status: {job['status']}\n(Truncation may apply; adjust MAX_TEXT_SIZE if needed.)"
+    )
+
+
 def main() -> None:
     # FastMCP provides stdio runner; prefer run() or run_stdio() depending on version
     runner = None
@@ -116,4 +162,3 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
-