eFax to JSON MCP Server

A Model Context Protocol (MCP) server that converts eFax documents from OpenText Fax Server Software into structured JSON format. Supports PDF, TIFF, and CCD XML document formats with advanced OCR and metadata extraction capabilities.

Features

Supported Formats

• PDF Documents - Text extraction and OCR for scanned PDFs

• TIFF Images - Multi-page TIFF support with OCR processing

• CCD XML - Clinical Document Architecture parsing

Processing Capabilities

• Intelligent OCR - Tesseract-based text recognition with confidence scoring

• Metadata Extraction - Preserve document properties and fax information

• Batch Processing - Convert multiple documents simultaneously

• Format Validation - Comprehensive document structure validation

• Error Recovery - Robust error handling with detailed reporting

Installation

Prerequisites

• Node.js 18+

• System-level Tesseract OCR installation:

  • Ubuntu/Debian: sudo apt-get install tesseract-ocr

  • macOS: brew install tesseract

  • Windows: Download from UB Mannheim releases

Setup Steps

1. Create project directory

   mkdir efax-mcp-server cd efax-mcp-server

2. Initialize and install dependencies

   npm init -y npm install @modelcontextprotocol/sdk pdf-parse sharp tesseract.js xml2js npm install -D @types/node @types/pdf-parse @types/xml2js typescript ts-node

3. Create directory structure

   mkdir -p src/{types,processors,utils} mkdir -p tests/test-files mkdir -p docs

4. Add source files (paste the provided code into respective files)

5. Build the project

   npm run build

Usage

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

Available Tools

1. Convert Single Document

Parameters:

• filePath (required) - Path to eFax document

• outputPath (optional) - Custom output JSON path

• extractMetadata (default: true) - Extract document metadata

• performOCR (default: true) - Enable OCR processing

• ocrLanguage (default: "eng") - OCR language code

• includeRawData (default: false) - Include raw document data

2. Batch Convert Documents

Parameters:

• inputDirectory (required) - Source document directory

• outputDirectory (required) - JSON output directory

• filePattern (default: "*") - File matching pattern

• continueOnError (default: true) - Continue on individual failures

3. Validate JSON Output

4. Get File Information

5. List Supported Formats

JSON Output Structure

Architecture

Modular Design

• Processors: Format-specific conversion logic

• Utilities: Shared validation and file handling

• Types: Comprehensive TypeScript definitions

Processing Pipeline

1. File Validation - Format and size checks

2. Format Detection - Automatic type identification

3. Content Extraction - Text and metadata processing

4. OCR Processing - Image-to-text conversion when needed

5. Structure Validation - Output quality assurance

6. JSON Serialization - Standardized output format

Development

Build Commands

Testing

Place sample documents in tests/test-files/ and run:

Adding New Formats

1. Create processor in src/processors/

2. Add type definitions in src/types/

3. Register in main server

4. Update documentation

Performance Considerations

• OCR Processing: CPU-intensive, consider batch size limits

• Memory Usage: Large TIFF files may require significant RAM

• Processing Time: Varies by document complexity and OCR requirements

• Concurrent Processing: Single-threaded OCR worker per instance

Error Handling

The server provides comprehensive error handling:

• File Validation Errors - Invalid paths, unsupported formats

• Processing Errors - OCR failures, corrupted documents

• System Errors - Memory issues, disk space problems

• Validation Errors - Output structure problems

Troubleshooting

Common Issues

OCR Not Working

• Verify Tesseract installation: tesseract --version

• Check language pack availability

• Ensure sufficient system memory

Large File Processing

• Monitor memory usage during conversion

• Consider breaking large batches into smaller chunks

• Verify available disk space for output

Permission Errors

• Check read permissions on input files

• Verify write permissions on output directory

• Ensure MCP server has appropriate file system access

License

MIT License - see LICENSE file for details.

Support

For issues and feature requests, please use the project's issue tracker.