docs: update HIPAA requirements and MCP integration guide to include OAuth2 support for SSE transport; enhance README with new MCP server options

Author: DMontgomery40

HIPAA_REQUIREMENTS.md

@@ -94,12 +94,16 @@ Implement the following as minimum controls:
 ## MCP (AI Assistant) Considerations
 - MCP transmits base64 file content for the `send_fax` tool. Treat the MCP server with the same controls as the API (auth, network restrictions, audit logging).
 - Do not send PHI to LLMs or external services unless you have a signed BAA and an approved use case.
-- Keep MCP HTTP behind authentication and rate limiting.
+- All MCP servers must require authentication:
+  - REST API: `X-API-Key` for /fax endpoints.
+  - MCP HTTP/SSE: `Authorization: Bearer <JWT>` verified against your OIDC JWKS.
+- Serve MCP over TLS. Never log PHI (file content, rendered pages). Log only job IDs and metadata.
 
 ## Operational Checklist (Minimum)
 - [ ] Signed BAA with Phaxio (if using cloud backend).
 - [ ] TLS everywhere (HTTPS for public endpoints; VPN/private link for SIP media).
 - [ ] API auth enabled (`API_KEY` set). Reverse proxy with IP allowlist + rate limiting.
+- [ ] MCP auth enforced (OAuth2 Bearer required for HTTP/SSE MCP).
 - [ ] Callback signature verification enabled (`PHAXIO_VERIFY_SIGNATURE=true`).
 - [ ] Tokenized PDF access enabled with short TTL (`PDF_TOKEN_TTL_MINUTES`).
 - [ ] Logs do not contain PHI; tokens redacted; job IDs only.

README.md

@@ -24,6 +24,7 @@ Simple fax-sending API with AI integration. Choose your backend:
 [→ 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.
 
 ## Client SDKs
 - Python: `pip install faxbot`

api/mcp_sse_server.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+// MCP SSE transport for Faxbot with OAuth2 (JWT) Bearer authentication.
+// Requires valid JWTs issued by an OIDC provider and verified via JWKS.
+
+require('dotenv').config();
+const express = require('express');
+const helmet = require('helmet');
+const cors = require('cors');
+const morgan = require('morgan');
+const { jwtVerify, createRemoteJWKSet } = require('jose');
+
+const { SSEServerTransport } = require('@modelcontextprotocol/sdk/server/sse.js');
+const { FaxMcpServer } = require('./mcp_server.js');
+
+const app = express();
+app.use(helmet());
+app.use(express.json({ limit: '10mb' }));
+app.use(cors({ origin: '*', exposedHeaders: ['Mcp-Session-Id'] }));
+app.use(morgan('dev'));
+
+// Health route
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok', transport: 'sse', server: 'faxbot-mcp', version: '2.0.0' });
+});
+
+// OAuth2 / JWT verification
+const issuer = (process.env.OAUTH_ISSUER || '').replace(/\/$/, '');
+const audience = process.env.OAUTH_AUDIENCE || '';
+const jwksUrl = process.env.OAUTH_JWKS_URL || (issuer ? `${issuer}/.well-known/jwks.json` : '');
+
+if (!issuer || !audience || !jwksUrl) {
+  console.warn('[mcp-sse] OAuth2 env not fully configured. Set OAUTH_ISSUER, OAUTH_AUDIENCE, and optionally OAUTH_JWKS_URL.');
+}
+
+let JWKS; // initialized lazily on first request
+
+async function authenticate(req, res, next) {
+  try {
+    const auth = req.headers['authorization'] || '';
+    const [scheme, token] = auth.split(' ');
+    if (scheme !== 'Bearer' || !token) {
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+    if (!JWKS) {
+      JWKS = createRemoteJWKSet(new URL(jwksUrl));
+    }
+    const { payload } = await jwtVerify(token, JWKS, {
+      issuer,
+      audience,
+    });
+    req.user = payload;
+    return next();
+  } catch (err) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+}
+
+// In-memory session store: sessionId -> { transport, server }
+const sessions = Object.create(null);
+
+async function initServerWithTransport(transport) {
+  const fax = new FaxMcpServer();
+  const server = fax.server;
+  transport.onclose = () => {
+    if (transport.sessionId && sessions[transport.sessionId]) {
+      delete sessions[transport.sessionId];
+    }
+    try { server.close(); } catch (_) {}
+  };
+  await server.connect(transport);
+  return server;
+}
+
+// GET /sse - establish SSE session
+app.get('/sse', authenticate, async (req, res) => {
+  try {
+    const existingId = req.query.sessionId || req.headers['mcp-session-id'];
+    if (existingId && sessions[existingId]) {
+      return sessions[existingId].transport.handleRequest(req, res);
+    }
+    const transport = new SSEServerTransport({});
+    const server = await initServerWithTransport(transport);
+    if (!transport.sessionId) {
+      return res.status(500).json({ error: 'Failed to initialize session' });
+    }
+    sessions[transport.sessionId] = { transport, server };
+    return transport.handleRequest(req, res);
+  } catch (err) {
+    console.error('SSE /sse error:', err);
+    if (!res.headersSent) {
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  }
+});
+
+// POST /messages - deliver client messages into a session
+app.post('/messages', authenticate, async (req, res) => {
+  try {
+    const sessionId = req.query.sessionId || req.headers['mcp-session-id'] || req.body.sessionId;
+    if (!sessionId || !sessions[sessionId]) {
+      return res.status(400).json({ error: 'Invalid or missing sessionId' });
+    }
+    const session = sessions[sessionId];
+    return session.transport.handlePostMessage(req, res);
+  } catch (err) {
+    console.error('SSE POST /messages error:', err);
+    if (!res.headersSent) {
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  }
+});
+
+// DELETE /messages - close a session
+app.delete('/messages', authenticate, async (req, res) => {
+  try {
+    const sessionId = req.query.sessionId || req.headers['mcp-session-id'];
+    if (!sessionId || !sessions[sessionId]) {
+      return res.status(400).json({ error: 'Invalid or missing sessionId' });
+    }
+    const session = sessions[sessionId];
+    await session.transport.handleClose();
+    delete sessions[sessionId];
+    res.status(204).end();
+  } catch (err) {
+    console.error('SSE DELETE /messages error:', err);
+    if (!res.headersSent) {
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  }
+});
+
+const port = parseInt(process.env.PORT || '3002', 10);
+app.listen(port, () => {
+  console.log(`Faxbot MCP SSE (OAuth2) on http://localhost:${port}`);
+});
+

api/package.json

@@ -5,12 +5,14 @@
   "main": "mcp_server.js",
   "bin": {
     "faxbot-mcp": "./mcp_server.js",
-    "faxbot-mcp-http": "./mcp_http_server.js"
+    "faxbot-mcp-http": "./mcp_http_server.js",
+    "faxbot-mcp-sse": "./mcp_sse_server.js"
   },
   "scripts": {
     "start": "node mcp_server.js",
     "start:mcp": "node mcp_server.js",
     "start:http": "node mcp_http_server.js",
+    "start:sse": "node mcp_sse_server.js",
     "dev:mcp": "nodemon mcp_server.js",
     "dev:http": "nodemon mcp_http_server.js",
     "install-global": "npm install -g .",
@@ -39,7 +41,8 @@
     "cors": "^2.8.5",
     "helmet": "^7.1.0",
     "joi": "^17.12.0",
-    "dotenv": "^16.4.0"
+    "dotenv": "^16.4.0",
+    "jose": "^5.2.0"
   },
   "devDependencies": {
     "nodemon": "^3.0.0"

docs/MCP_INTEGRATION.md

@@ -3,7 +3,7 @@
 ## What is MCP?
 - Model Context Protocol (2024/2025) lets AI assistants use external tools safely.
 - Here, Faxbot exposes two tools: `send_fax` and `get_fax_status`.
-- Transports supported: stdio (desktop) and HTTP (server).
+- Transports supported: stdio (desktop), HTTP (server), and SSE with OAuth2 (server).
 
 ## Architecture
 Assistant → MCP Server → Faxbot API → Backend (Phaxio or SIP/Asterisk)
@@ -62,7 +62,7 @@ FAX_API_URL=http://localhost:8080 API_KEY=$API_KEY MCP_HTTP_PORT=3001 faxbot-mcp
 ```
 
 ## Stdio Transport (Claude Desktop, Cursor)
-- Start stdio MCP:
+- Node (stdio) start:
 ```
 cd api && npm run start:mcp
 ```
@@ -72,8 +72,18 @@ cd api && node setup-mcp.js
 ```
 - Claude Desktop/Cursor will reference the generated configs to launch `mcp_server.js`.
 
+- Python (stdio) start:
+```
+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
+python stdio_server.py
+```
+
 ## HTTP Transport (Cloud/Local)
-- Start HTTP MCP:
+- Node (HTTP) start:
 ```
 cd api && npm run start:http
 ```
@@ -85,6 +95,16 @@ cd api && npm run start:http
 
 Note: Streamable HTTP is intended for MCP-aware clients (Claude Desktop, Cursor/Cline, etc.). Manual curl testing requires constructing JSON-RPC requests and handling SSE, which is beyond the scope of this guide.
 
+- Python (HTTP) start:
+```
+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
+uvicorn http_server:app --host 0.0.0.0 --port 3004
+```
+
 Docker option (profile `mcp`):
 ```
 make mcp-up     # builds and starts the faxbot-mcp service
@@ -96,5 +116,62 @@ make mcp-down   # stop MCP service
 - If the API uses `X-API-Key`, set `API_KEY` for MCP so it forwards the header.
 - For HTTP transport, place behind auth and rate limits.
 
+## SSE Transport with OAuth2 (Node)
+- Requirements:
+  - Node 18+
+  - Dependencies: `npm install jose`
+- Configure OAuth2 (resource server):
+  - `OAUTH_ISSUER` (e.g., `https://your-tenant.auth0.com`)
+  - `OAUTH_AUDIENCE` (e.g., `faxbot-mcp`)
+  - `OAUTH_JWKS_URL` (optional override; defaults to `${OAUTH_ISSUER}/.well-known/jwks.json`)
+  - `FAX_API_URL` (Faxbot REST API base URL)
+  - `API_KEY` (Faxbot API key if enabled)
+- Start the server:
+```
+cd api
+npm install  # ensure deps
+OAUTH_ISSUER=https://example.auth0.com \
+OAUTH_AUDIENCE=faxbot-mcp \
+OAUTH_JWKS_URL=https://example.auth0.com/.well-known/jwks.json \
+FAX_API_URL=http://localhost:8080 \
+API_KEY=your_api_key \
+PORT=3002 \
+npm run start:sse
+```
+- Endpoints:
+  - `GET /health` → `{ status: 'ok', transport: 'sse', server: 'faxbot-mcp', version: '2.0.0' }`
+  - `GET /sse` → starts an SSE session (requires `Authorization: Bearer <JWT>`) and returns events
+  - `POST /messages` → send client messages (requires Bearer token and `sessionId`)
+  - `DELETE /messages` → close a session
+- Notes:
+  - JWTs are verified against the JWKS (signature + `iss`/`aud`/`exp`/`nbf`).
+  - Sessions are kept in-memory (stateless JWT + stateful transport).
+
+## SSE Transport with OAuth2 (Python)
+- Requirements:
+  - Python 3.9+
+  - Dependencies: see `python_mcp/requirements.txt`
+- Configure OAuth2 / Env:
+  - `OAUTH_ISSUER`, `OAUTH_AUDIENCE`, `OAUTH_JWKS_URL`
+  - `FAX_API_URL`, `API_KEY`
+  - `PORT` (default 3003)
+- Run:
+```
+cd python_mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+export OAUTH_ISSUER=https://example.auth0.com
+export OAUTH_AUDIENCE=faxbot-mcp
+export OAUTH_JWKS_URL=https://example.auth0.com/.well-known/jwks.json
+export FAX_API_URL=http://localhost:8080
+export API_KEY=my_api_key
+uvicorn server:app --host 0.0.0.0 --port 3003
+```
+- Endpoints:
+  - `GET /health` → `{ status: 'ok', transport: 'sse', server: 'faxbot-mcp', version: '2.0.0' }`
+  - SSE endpoints are mounted at `/` by the MCP SSE app and protected by Bearer auth middleware.
+- Notes:
+  - The Python MCP server bridges SSE + OAuth2 until official Python MCP SDKs add built-in HTTP/OAuth support.
+
 ## Voice Examples
 - You can say: “Send this PDF to +1555… using fax tools.” The assistant will call `send_fax` with base64 content, then `get_fax_status`.

docs/SDKS.md

@@ -1,6 +1,6 @@
 # Client SDKs
 
-Thin, official clients for the Faxbot API. They call the unified Faxbot REST API (no direct Phaxio/Asterisk calls).
+Thin, official clients for the Faxbot API. They call the unified Faxbot REST API (no direct Phaxio/Asterisk calls). Current version alignment: Python 1.0.2, Node 1.0.2.
 
 - Python: `faxbot`
 - Node.js: `faxbot`