An advanced MCP (Model Context Protocol) server for high-quality PDF to Markdown conversion with comprehensive monitoring, security, and testing capabilities.

This implementation provides a comprehensive MCP server with advanced features including:

• Enhanced Document Processing: Improved heading detection, caption recognition, and layout analysis
• LLM-Powered Refinement: AI-driven layout consistency checking and correction
• Advanced Table Processing: Direct text extraction with OCR fallback for optimal table handling
• Surya OCR Integration: Compatible with surya-ocr 0.14.1 for superior OCR performance
• Real-time monitoring and metrics collection
• Advanced security framework
• Comprehensive testing suite
• High-performance PDF processing
• Batch and chunked processing capabilities

• EnhancedHeadingDetectorProcessor: Advanced heading detection using font analysis and layout patterns
• EnhancedCaptionDetectorProcessor: Smart caption recognition with proximity-based matching
• LLMLayoutRefinementProcessor: AI-powered layout consistency checking and correction
• LayoutConsistencyChecker: Validates and fixes layout inconsistencies

• Surya Library Compatibility: Fixed compatibility issues with surya-ocr for optimal performance
• Custom Table Processing: Implemented custom table_output function for better table text extraction
• Enhanced Configuration System: Comprehensive configuration options for fine-tuning processing
• Robust Error Handling: Graceful fallbacks and error recovery mechanisms

# Install dependencies
pip install .

# Or using poetry
poetry install

For the enhanced PDF processing capabilities, ensure you have the compatible surya version:

# Remove incompatible surya version if installed
pip uninstall surya-ocr -y

# Install compatible surya version (development mode)
# Replace with path to your compatible surya repository
cd /path/to/compatible/surya
pip install -e .

# Verify installation
python -c "from marker.converters.enhanced_pdf import EnhancedPdfConverter; print('Enhanced features ready!')"

• Python: 3.8+
• Memory: 8GB+ RAM recommended (4GB minimum)
• GPU: Optional but recommended for faster processing
• Storage: Sufficient space for model downloads (~2-4GB)

# Start the MCP server
python -m marker_mcp_server

# Show help and available options
python -m src.marker_mcp_server.server --help

# Show version information
python -m src.marker_mcp_server.server --version

# Enable debug logging
python -m src.marker_mcp_server.server --debug

The new EnhancedPdfConverter provides superior document processing with AI-powered enhancements:

from marker.converters.enhanced_pdf import EnhancedPdfConverter, EnhancedPdfConfig

# Create enhanced configuration
config = EnhancedPdfConfig()
config.use_enhanced_heading_detection = True
config.use_enhanced_caption_detection = True
config.use_llm_layout_refinement = True

# Create converter (when models are available)
converter = EnhancedPdfConverter(config)

from marker.processors.enhanced_heading_detector import EnhancedHeadingDetectorProcessor

processor = EnhancedHeadingDetectorProcessor({
    'min_font_size_ratio': 1.1,        # Minimum font size ratio for headings
    'max_heading_length': 200,         # Maximum heading length
    'font_weight_threshold': 600.0     # Font weight threshold
})

from marker.processors.enhanced_caption_detector import EnhancedCaptionDetectorProcessor

processor = EnhancedCaptionDetectorProcessor({
    'max_caption_distance': 0.15,      # Maximum distance from figure/table
    'max_caption_length': 500,         # Maximum caption length
    'min_caption_length': 10           # Minimum caption length
})

from marker.processors.llm.llm_layout_refinement import LLMLayoutRefinementProcessor

processor = LLMLayoutRefinementProcessor({
    'confidence_threshold': 0.7,       # Confidence threshold
    'max_text_length': 300             # Maximum text length for processing
})

# Complete enhanced configuration
config = EnhancedPdfConfig()

# Feature toggles
config.use_enhanced_heading_detection = True
config.use_enhanced_caption_detection = True
config.use_llm_layout_refinement = True
config.use_layout_consistency_checking = True

# Heading detection settings
config.heading_min_font_ratio = 1.1
config.heading_max_length = 200
config.heading_font_weight_threshold = 600.0

# Caption detection settings
config.caption_max_distance = 0.15
config.caption_max_length = 500
config.caption_min_length = 10

# LLM refinement settings
config.llm_refinement_confidence = 0.7
config.llm_refinement_max_length = 300

NEW FEATURE: Process large PDFs efficiently by splitting them into page chunks.

• Memory Efficient: Processes documents in configurable page chunks (default: 5 pages)
• Fault Tolerant: Individual chunk failures don't stop entire process
• Progress Tracking: Detailed progress information for each chunk
• Automatic Stitching: Combines chunk outputs into single cohesive document

# Example usage
arguments = {
    "file_path": "/path/to/large_document.pdf",
    "pages_per_chunk": 5,
    "combine_output": True,
    "use_llm": True,
    "output_format": "markdown"
}

Convert multiple PDFs in a folder with full CLI argument support.

arguments = {
    "folder_path": "/path/to/pdfs",
    "output_dir": "/path/to/outputs",
    "workers": 8,
    "debug": True,
    "use_llm": True,
    "page_range": "0-10",
    "skip_existing": True
}

Convert individual PDF files with advanced options.

arguments = {
    "pdf_path": "/path/to/document.pdf",
    "output_path": "/path/to/output.md",
    "debug": True,
    "use_llm": True,
    "page_range": "0-5"
}

Process large collections of PDFs using memory-efficient chunking.

arguments = {
    "in_folder": "/path/to/large/collection",
    "chunk_size": 50,
    "use_llm": True
}

Start FastAPI server for REST API access.

arguments = {
    "host": "0.0.0.0",
    "port": 8080
}

Enable high-quality processing with Large Language Models:

• groq: Groq's fast inference API
• openai: OpenAI GPT models (including compatible APIs)
• anthropic: Anthropic Claude models
• gemini: Google Gemini models
• nvidia: NVIDIA's Llama-3.1-Nemotron-Nano-VL-8B-V1 model

# Basic LLM usage
{
    "use_llm": True,
    "llm_service": "groq"  # Automatically normalized to full path
}

# NVIDIA model usage
{
    "use_llm": True,
    "llm_service": "nvidia"  # Uses NVIDIA's vision-language model
}

# Advanced LLM configuration
{
    "use_llm": True,
    "llm_service": "marker.services.groq.GroqService",
    "config_json": "examples/llm_enhanced_config.json"
}

Process specific page ranges efficiently:

{
    "page_range": "0-5",      # Pages 0 through 5
    "page_range": "0,3,5-10", # Pages 0, 3, and 5 through 10
    "page_range": "10-"       # Page 10 to end
}

Choose from multiple output formats:

{
    "output_format": "markdown",  # Default, clean markdown
    "output_format": "json",      # Structured JSON with metadata
    "output_format": "html"       # Styled HTML output
}

Enable comprehensive debugging:

{
    "debug": True  # Saves debug images, processing data, and detailed logs
}

Use JSON configuration files for complex setups:

{
  "use_llm": false,
  "output_format": "markdown",
  "debug": false,
  "extract_images": true,
  "pdftext_workers": 2
}

{
  "use_llm": true,
  "llm_service": "marker.services.groq.GroqService",
  "output_format": "markdown",
  "debug": false,
  "extract_images": true,
  "format_lines": true
}

{
  "workers": 8,
  "max_tasks_per_worker": 20,
  "disable_multiprocessing": false,
  "pdftext_workers": 4,
  "chunk_size": 100
}

• Memory Usage: Real-time tracking with configurable alerts (85% threshold)
• CPU Utilization: Multi-core usage monitoring
• GPU Usage: Apple Silicon MPS device monitoring
• Processing Times: Per-operation timing with alert thresholds (300s)

• Job Lifecycle: Start, progress, completion, and error states
• Resource Consumption: Memory, CPU, and GPU usage per operation
• Throughput: Pages per second and batch processing metrics
• Error Rates: Failure tracking and categorization

• Path Traversal Prevention: Blocks ../ and absolute path attacks
• Directory Restriction: Enforces allowed input/output directories
• Extension Validation: Restricts to approved file types (.pdf)
• Filename Sanitization: Prevents malicious filename patterns

• Parameter Sanitization: Type checking and range validation
• Configuration Validation: Schema-based security settings
• Access Logging: Detailed security event tracking

The system uses a compatible version of surya-ocr (0.14.1) that provides:

• Layout Detection: Advanced document layout analysis
• Text Recognition: High-quality OCR capabilities
• Table Recognition: Specialized table structure detection
• Error Detection: OCR quality assessment

# Core surya imports (fixed compatibility)
from surya.layout import LayoutPredictor, LayoutBox, LayoutResult
from surya.detection import DetectionPredictor, TextDetectionResult
from surya.recognition import RecognitionPredictor, OCRResult, TextChar
from surya.table_rec import TableRecPredictor
from surya.ocr_error import OCRErrorPredictor
from surya.common.surya.schema import TaskNames

def table_output(filepath, table_inputs, page_range=None, workers=None):
    """Custom table text extraction using pdftext.extraction.dictionary_output"""
    # Implementation provides:
    # - Direct text extraction from PDF tables
    # - OCR fallback for scanned tables
    # - Structured output compatible with marker pipeline

1. Document Loading: PDF parsing and page extraction
2. Layout Detection: Surya-based layout analysis
3. Text Detection: Line and text region identification
4. Enhanced Processing: Custom processors for headings and captions
5. LLM Refinement: AI-powered layout correction
6. Table Processing: Direct text extraction with OCR fallback
7. Output Generation: Structured Markdown generation

# Error: Cannot import surya components
# Solution: Ensure compatible surya version is installed
pip uninstall surya-ocr -y
cd /path/to/compatible/surya
pip install -e .

# Error: Cannot load models
# Solution: Ensure sufficient memory and proper model paths
export TORCH_DEVICE_MODEL="cpu"  # or "cuda" for GPU

# Error: table_output function issues
# Solution: Verify pdftext installation
pip install --upgrade pdftext

# Error: Enhanced processors not working
# Solution: Verify all dependencies are installed
python -c "from marker.converters.enhanced_pdf import EnhancedPdfConverter; print('OK')"

• Base Processing: ~2-4GB RAM
• With ML Models: ~4-8GB RAM
• Enhanced Processing: ~6-10GB RAM (with all enhancements)
• GPU Processing: ~2-6GB VRAM

• Direct Text Extraction: ~10-50 pages/minute
• OCR Processing: ~1-5 pages/minute (GPU accelerated)
• Enhanced Processing: ~5-15 pages/minute (with all enhancements)

• Heading Detection: ~15-25% improvement in accuracy
• Caption Recognition: ~20-30% improvement in association
• Table Processing: ~10-20% improvement in text extraction

• Fixtures: Configuration, temporary workspace, mock collectors
• Test Data Generation: Synthetic performance data and test scenarios
• Environment Setup: Isolated test environments with cleanup
• Enhanced Component Testing: Specific tests for new processors and converters

• Unit Tests: Component-level testing with mocking
• Integration Tests: End-to-end workflow validation
• Security Tests: Attack scenario prevention
• Performance Tests: Load testing and benchmarking capabilities
• Enhanced Feature Tests: Validation of new processing capabilities

# Convert PDF with monitoring
result = await mcp_client.call_tool("convert_single_pdf", {
    "file_path": "/safe/path/document.pdf",
    "output_format": "markdown"
})

# Check system health
health = await mcp_client.call_tool("get_system_health", {})

# Get performance metrics
metrics = await mcp_client.call_tool("get_metrics_summary", {})

{
    "resource_limits": {
        "max_file_size_mb": 500,
        "max_memory_usage_mb": 4096,
        "max_processing_time_seconds": 600,
        "max_concurrent_jobs": 3
    },
    "monitoring": {
        "enable_metrics": true,
        "metrics_interval_seconds": 30,
        "alert_memory_threshold_percent": 85.0
    },
    "security": {
        "validate_file_paths": true,
        "allowed_input_dirs": ["/safe/input"],
        "allowed_output_dirs": ["/safe/output"]
    }
}

• Improved Heading Hierarchy: Better detection of section structures
• Caption Association: Accurate linking of figures/tables with captions
• Mathematical Content: Enhanced handling of equations and formulas

• Table Processing: Superior extraction of complex tables
• Layout Consistency: AI-powered layout correction and validation
• Multi-Column Layouts: Better handling of complex document structures

• Report Processing: Enhanced extraction of structured business reports
• Financial Documents: Improved table and numerical data extraction
• Presentation Materials: Better handling of slide-based content

• Single PDF: ~2-5 pages/second (device dependent)
• Enhanced Processing: ~1-3 pages/second (with all enhancements)
• Batch Processing: 3 concurrent jobs by default
• Memory Efficient: Streaming processing for large files

• Memory: Configurable limits with real-time monitoring
• CPU: Multi-core utilization with Apple Silicon optimization
• GPU: MPS acceleration on compatible devices
• Storage: Efficient caching and cleanup

• Fast processing for basic document conversion
• Suitable for simple layouts and text-heavy documents
• Lower resource requirements

• Superior quality for complex documents
• AI-powered layout analysis and correction
• Higher resource requirements but significantly better output quality

# Run all tests
python -m pytest tests/ -v

# Run specific test categories
python -m pytest tests/ -m "unit"
python -m pytest tests/ -m "security"
python -m pytest tests/ -m "performance"

# Run with coverage
python -m pytest tests/ --cov=src/marker_mcp_server

# Start development server
python -m src.marker_mcp_server.server --debug

# With custom configuration
python -m src.marker_mcp_server.server --config-path /path/to/config.json

For more detailed documentation on:

• Configuration options
• Advanced usage
• API endpoints
• Development guidelines

Please refer to the project's documentation in the docs/ directory.

1. Fork the repository and create your branch from main.
2. Write tests for your changes (see tests/ directory).
3. Document new features or changes in the README or relevant doc files.
4. Open a Pull Request with a clear description of your changes.

This project is licensed under the terms of the Marker Contributor Agreement.

Special thanks to all contributors who have helped make this project possible.

For support, please open an issue in the GitHub repository or contact the maintainers directly.

# Install dependencies
pip install .

# Or using poetry
poetry install

# Start the MCP server
python -m marker_mcp_server

# Show help and available options
python -m src.marker_mcp_server.server --help

# Show version information
python -m src.marker_mcp_server.server --version

# Enable debug logging
python -m src.marker_mcp_server.server --debug

NEW FEATURE: Process large PDFs efficiently by splitting them into page chunks.

• Memory Efficient: Processes documents in configurable page chunks (default: 5 pages)
• Fault Tolerant: Individual chunk failures don't stop entire process
• Progress Tracking: Detailed progress information for each chunk
• Automatic Stitching: Combines chunk outputs into single cohesive document

# Example usage
arguments = {
    "file_path": "/path/to/large_document.pdf",
    "pages_per_chunk": 5,
    "combine_output": True,
    "use_llm": True,
    "output_format": "markdown"
}

Convert multiple PDFs in a folder with full CLI argument support.

arguments = {
    "folder_path": "/path/to/pdfs",
    "output_dir": "/path/to/outputs",
    "workers": 8,
    "debug": True,
    "use_llm": True,
    "page_range": "0-10",
    "skip_existing": True
}

Convert individual PDF files with advanced options.

arguments = {
    "pdf_path": "/path/to/document.pdf",
    "output_path": "/path/to/output.md",
    "debug": True,
    "use_llm": True,
    "page_range": "0-5"
}

Process large collections of PDFs using memory-efficient chunking.

arguments = {
    "in_folder": "/path/to/large/collection",
    "chunk_size": 50,
    "use_llm": True
}

Start FastAPI server for REST API access.

arguments = {
    "host": "0.0.0.0",
    "port": 8080
}

Enable high-quality processing with Large Language Models:

• groq: Groq's fast inference API
• openai: OpenAI GPT models (including compatible APIs)
• anthropic: Anthropic Claude models
• gemini: Google Gemini models
• nvidia: NVIDIA's Llama-3.1-Nemotron-Nano-VL-8B-V1 model

# Basic LLM usage
{
    "use_llm": True,
    "llm_service": "groq"  # Automatically normalized to full path
}

# NVIDIA model usage
{
    "use_llm": True,
    "llm_service": "nvidia"  # Uses NVIDIA's vision-language model
}

# Advanced LLM configuration
{
    "use_llm": True,
    "llm_service": "marker.services.groq.GroqService",
    "config_json": "examples/llm_enhanced_config.json"
}

Process specific page ranges efficiently:

{
    "page_range": "0-5",      # Pages 0 through 5
    "page_range": "0,3,5-10", # Pages 0, 3, and 5 through 10
    "page_range": "10-"       # Page 10 to end
}

Choose from multiple output formats:

{
    "output_format": "markdown",  # Default, clean markdown
    "output_format": "json",      # Structured JSON with metadata
    "output_format": "html"       # Styled HTML output
}

Enable comprehensive debugging:

{
    "debug": True  # Saves debug images, processing data, and detailed logs
}

Use JSON configuration files for complex setups:

{
  "use_llm": false,
  "output_format": "markdown",
  "debug": false,
  "extract_images": true,
  "pdftext_workers": 2
}

{
  "use_llm": true,
  "llm_service": "marker.services.groq.GroqService",
  "output_format": "markdown",
  "debug": false,
  "extract_images": true,
  "format_lines": true
}

{
  "workers": 8,
  "max_tasks_per_worker": 20,
  "disable_multiprocessing": false,
  "pdftext_workers": 4,
  "chunk_size": 100
}

• When the server is started with start_server, FastAPI automatically exposes OpenAPI/Swagger documentation at /docs (Swagger UI) and /redoc (ReDoc UI).
• You can interactively test the API and see all endpoints and schemas there.

• To add a new processor, use the plugin registry in marker/processors/registry.py:

from marker.processors import register_processor

@register_processor('my_custom_processor')
class MyCustomProcessor:
    ...

• To add a new converter, use the plugin registry in marker/converters/registry.py:

from marker.converters import register_converter

@register_converter('my_custom_converter')
class MyCustomConverter:
    ...

• See marker/processors/__init__.py and marker/converters/__init__.py for more details.

• Batch and chunked processing are supported for large-scale PDF conversion.
• For very large jobs or distributed processing, consider integrating an async task queue (e.g., Celery, RQ). This is not included by default, but the architecture supports async handlers.
• Monitor resource usage (CPU, memory) for large jobs. Logging includes memory usage if psutil is installed.
• You can adjust worker counts and chunk sizes in the configuration for optimal performance.

See CONTRIBUTING.md for guidelines on contributing, adding new processors/converters, and running tests.