fast-paddleocr-mcp 0.3.9__py3-none-any.whl

fast_paddleocr_mcp-0.3.9.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: fast-paddleocr-mcp
+Version: 0.3.9
+Summary: Fast PaddleOCR MCP server - Extract text from images using PaddleOCR with optimized performance
+Project-URL: Homepage, https://github.com/yourusername/PaddleOCR-MCP
+Project-URL: Documentation, https://github.com/yourusername/PaddleOCR-MCP#readme
+Project-URL: Repository, https://github.com/yourusername/PaddleOCR-MCP
+Project-URL: Issues, https://github.com/yourusername/PaddleOCR-MCP/issues
+Author: PaddleOCR-MCP Contributors
+License: MIT
+License-File: LICENSE
+Keywords: image-processing,mcp,model-context-protocol,ocr,paddleocr,text-recognition
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: paddleocr>=2.7.0
+Requires-Dist: paddlepaddle>=2.5.0
+Requires-Dist: pillow>=10.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PaddleOCR-MCP
+
+PaddleOCR MCP (Model Context Protocol) server and CLI tool that extracts text from images and outputs results in markdown format. Optimized for fast inference with GPU auto-detection.
+
+## MCP Server Configuration
+
+The MCP (Model Context Protocol) server allows integration with MCP clients like Cursor, Claude Desktop, etc.
+
+**Use `uvx` directly (no installation required, automatically downloads from PyPI):**
+
+```json
+{
+  "mcpServers": {
+    "fast-paddleocr-mcp": {
+      "command": "uvx",
+      "args": ["fast-paddleocr-mcp"]
+    }
+  }
+}
+```
+
+#### MCP Tool: `ocr_image`
+
+The server provides a single tool called `ocr_image` that:
+- **Input**: `image_path` (string) - Path to the input image file
+- **Output**: Returns the path to the generated markdown file containing OCR results
+- **Automatic optimizations**: All performance optimizations are applied automatically with intelligent fallback
+- **Default language**: Uses 'ch' (Chinese and English) by default for maximum compatibility
+
+Example: When called with `image_path: "photo.png"`, it returns `"photo.png.md"` containing the recognized text.
+
+**Note**: The server automatically applies all optimizations (HPI, GPU acceleration, image preprocessing, etc.) and falls back to simpler configurations if needed. No configuration required from the caller.
+
+See [MCP_README.md](MCP_README.md) for detailed MCP server documentation.
+
+## Usage
+
+### Basic Usage
+
+The tool is optimized for speed by default with the following settings:
+- **Fast mode enabled** (disables preprocessing for maximum speed)
+- **PP-OCRv4** (faster mobile models)
+- **640px image size limit** (faster processing)
+- **Auto GPU detection** (uses GPU if available, falls back to CPU)
+
+```bash
+# Output will be saved as <image_name>.png.md
+# Uses: fast mode + PP-OCRv4 + 640px + auto GPU detection
+uvx --from . paddleocr-md image.png
+
+# Specify custom output path
+uvx --from . paddleocr-md image.png -o result.md
+
+# Force CPU mode
+uvx --from . paddleocr-md image.png --cpu
+
+# Disable fast mode for better accuracy on rotated text
+uvx --from . paddleocr-md image.png --no-fast
+
+# Use PP-OCRv5 for better accuracy (slower)
+uvx --from . paddleocr-md image.png --ocr-version PP-OCRv5
+```
+
+### Default Optimization Settings
+
+The MCP server is optimized for **low latency** by default with these settings:
+
+- ✅ **Fast mode enabled**: Disables textline orientation classification (skips one model)
+- ✅ **PP-OCRv4**: Uses faster mobile models (PP-OCRv4_mobile_det, PP-OCRv4_mobile_rec)
+- ✅ **High-Performance Inference (HPI)**: Automatically selects optimal inference backend
+  - Can reduce latency by **40-73%** (e.g., 73.1% reduction on PP-OCRv5_mobile_rec)
+  - Supports Paddle Inference, OpenVINO, ONNX Runtime, TensorRT
+- ✅ **Multi-threaded CPU**: Uses all available CPU cores for parallel processing
+- ✅ **MKL-DNN enabled**: Intel CPU optimization for faster inference
+- ✅ **Single image batch**: `rec_batch_num=1` for lowest latency per image
+- ✅ **Auto GPU detection**: Automatically uses GPU if available, falls back to CPU
+  - **GPU device selection**: Uses first available GPU (gpu_id=0)
+  - **TensorRT support**: Automatically enabled via HPI if TensorRT is installed
+  - **GPU memory**: Uses default allocation (can be customized if needed)
+- ✅ **Automatic image preprocessing**: Optimizes images before OCR for better performance
+  - **Automatic downsampling**: Resizes large images to maximum 1920px (maintains aspect ratio)
+    - Reduces processing time for large images significantly
+    - Uses high-quality LANCZOS resampling to preserve text quality
+  - **Image sharpening**: Enhances text edges for improved OCR accuracy
+    - Uses unsharp mask filter (radius=1, percent=150, threshold=3)
+    - Additional sharpening enhancement (factor=1.2)
+    - Makes text characters more distinct and easier to recognize
+  - **Format conversion**: Automatically converts RGBA, LA, P modes to RGB with white background
+  - **Temporary file management**: Automatically cleans up preprocessed images after OCR
+- ✅ **Logging disabled**: Reduces overhead by disabling verbose logging
+
+**GPU Performance:**
+- When GPU is available, HPI automatically selects TensorRT backend for maximum performance
+- TensorRT can provide 2-3x speedup compared to standard GPU inference
+- First run with HPI may take longer to build the inference engine, but subsequent runs will be much faster
+
+**Requirements**: 
+- PaddleOCR >= 2.7.0 with all latest features supported (HPI, MKL-DNN, etc.)
+- No backward compatibility - requires latest PaddleOCR version
+- For maximum GPU performance: NVIDIA GPU with CUDA support and TensorRT (optional)
+- Sufficient GPU memory (typically 1-2GB for mobile models)
+
+#### Customization Options
+
+1. **`--no-fast`**: Disable fast mode for better accuracy
+   - Enables textline orientation classification
+   - Better accuracy on rotated text, but slower
+
+2. **`--cpu`**: Force CPU mode
+   - Overrides auto GPU detection
+   - Explicitly use CPU
+
+3. **`--gpu`**: Force GPU mode
+   - Will fail if GPU not available
+   - Use when you want to ensure GPU usage
+
+4. **`--ocr-version PP-OCRv5`**: Use better accuracy version
+   - PP-OCRv5 has better accuracy but slower than PP-OCRv4 (default)
+   - Uses server models
+
+5. **`--max-size <pixels>`**: Adjust image processing size
+   - Default: 640px
+   - Larger values (e.g., 960, 1280) = better accuracy, slower
+   - Smaller values (e.g., 480) = faster, may reduce accuracy
+
+6. **`--hpi`**: High-Performance Inference
+   - Automatically selects best inference backend (Paddle Inference, OpenVINO, ONNX Runtime, TensorRT)
+   - Requires HPI dependencies: `paddleocr install_hpi_deps cpu/gpu`
+   - Best performance but requires additional setup
+
+### Examples
+
+```bash
+# Basic usage (uses all optimizations by default: fast + PP-OCRv4 + 640px + auto GPU)
+uvx --from . paddleocr-md photo.jpg
+
+# Process with custom output
+uvx --from . paddleocr-md document.png -o extracted_text.md
+
+# Better accuracy (slower) - disable fast mode and use PP-OCRv5
+uvx --from . paddleocr-md image.png --no-fast --ocr-version PP-OCRv5 --max-size 960
+
+# Force CPU mode
+uvx --from . paddleocr-md image.png --cpu
+
+# Use High-Performance Inference (requires HPI dependencies)
+uvx --from . paddleocr-md image.png --hpi
+```
+
+## Output Format
+
+The tool generates a markdown file containing:
+- Source image path
+- List of detected text (one per line)
+
+Example output (`test_image.png.md`):
+```markdown
+# OCR Result
+
+**Source Image:** `test_image.png`
+
+---
+
+- HelloPaddleOcR
+- 10000C
+```
+
+## Testing
+
+Run tests using pytest:
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run all tests
+pytest
+
+# Run tests with coverage
+pytest --cov=paddleocr_cli --cov-report=html
+
+# Run specific test file
+pytest tests/test_mcp_server.py
+
+# Run specific test class or function
+pytest tests/test_mcp_server.py::TestGetOCR
+pytest tests/test_mcp_server.py::TestGetOCR::test_get_ocr_default_language
+```
+
+The test suite includes:
+- OCR instance initialization and caching
+- Tool listing and definition
+- OCR tool calls with various parameters
+- Language parameter handling
+- File validation and error handling
+- Markdown output generation
+- Edge cases and error scenarios
+
+## License
+
+MIT

fast_paddleocr_mcp-0.3.9.dist-info/RECORD

@@ -0,0 +1,8 @@
+paddleocr_cli/__init__.py,sha256=9d0cQnw9I6dU0JgGO_zoLUAWnjE2wI6S7zhGn5YHn-c,79
+paddleocr_cli/__main__.py,sha256=U6N_qETotH9_4MKQRO-H6pDI8nuzSeE7DQ7fvTqIyW8,128
+paddleocr_cli/mcp_server.py,sha256=DLDQ7okwuVudUnnf09Tfrt_DkGpJF5PPETMpGF3rwuo,10394
+fast_paddleocr_mcp-0.3.9.dist-info/METADATA,sha256=u3b_Xq8BVw3DDryPLmwCFZgl8VaBqWESJB2gMLvGXQc,8816
+fast_paddleocr_mcp-0.3.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fast_paddleocr_mcp-0.3.9.dist-info/entry_points.txt,sha256=hFFJt1b5a_MXARyZ6Qg8yVtR5VcgZnaRZ2s2aKa52hs,69
+fast_paddleocr_mcp-0.3.9.dist-info/licenses/LICENSE,sha256=UMu98eNUpnO26Nv7JguuhZtFeh5HEE-X00IrJ5uH04A,1104
+fast_paddleocr_mcp-0.3.9.dist-info/RECORD,,

fast_paddleocr_mcp-0.3.9.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fast_paddleocr_mcp-0.3.9.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fast-paddleocr-mcp = paddleocr_cli.mcp_server:main

fast_paddleocr_mcp-0.3.9.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PaddleOCR-MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paddleocr_cli/__init__.py

@@ -0,0 +1,3 @@
+"""PaddleOCR-MCP: PaddleOCR MCP server and CLI tool."""
+
+__version__ = "0.3.9"

paddleocr_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Enable running as python -m paddleocr_cli.mcp_server"""
+
+from .mcp_server import main
+
+if __name__ == "__main__":
+    main()

paddleocr_cli/mcp_server.py

@@ -0,0 +1,275 @@
+"""MCP server for PaddleOCR - accepts image path and outputs image path + .md"""
+
+import asyncio
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Optional, Tuple
+
+try:
+    from mcp.server import NotificationOptions, Server
+    from mcp.server.models import InitializationOptions
+    import mcp.server.stdio
+    import mcp.types as types
+except ImportError:
+    print("Error: mcp package is not installed. Please install it with: pip install mcp", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    from paddleocr import PaddleOCR
+except ImportError:
+    print("Error: paddleocr is not installed. Please install it with: pip install paddleocr", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    from PIL import Image, ImageEnhance, ImageFilter
+except ImportError:
+    print("Error: pillow is not installed. Please install it with: pip install pillow", file=sys.stderr)
+    sys.exit(1)
+
+# Initialize MCP server
+server = Server("fast-paddleocr-mcp")
+
+# Cache PaddleOCR instance (lazy initialization with automatic fallback)
+ocr_cache: dict[str, PaddleOCR] = {}
+
+# Image preprocessing parameters
+MAX_IMAGE_SIZE = 1920  # Maximum dimension (width or height) for automatic downsampling
+SHARPEN_FACTOR = 1.2  # Sharpening factor (1.0 = no sharpening, higher = more sharpening)
+
+
+def preprocess_image(image_path: str) -> str:
+    """Preprocess image with automatic downsampling and sharpening for better OCR performance
+    
+    Args:
+        image_path: Path to the input image file
+        
+    Returns:
+        Path to the preprocessed image (temporary file)
+    """
+    from PIL import Image, ImageEnhance, ImageFilter
+    
+    # Open the original image
+    img = Image.open(image_path)
+    
+    # Convert to RGB if necessary (handle RGBA, L, P, etc.)
+    if img.mode != 'RGB':
+        if img.mode == 'RGBA':
+            # Create a white background for transparent images
+            background = Image.new('RGB', img.size, (255, 255, 255))
+            background.paste(img, mask=img.split()[3])  # Use alpha channel as mask
+            img = background
+        elif img.mode == 'LA':
+            # Convert LA (grayscale with alpha) to RGB
+            background = Image.new('RGB', img.size, (255, 255, 255))
+            rgb_img = img.convert('RGB')
+            # Use alpha channel from original image
+            alpha = img.split()[1] if len(img.split()) > 1 else None
+            if alpha:
+                background.paste(rgb_img, mask=alpha)
+            else:
+                background.paste(rgb_img)
+            img = background
+        elif img.mode == 'P':
+            # Convert palette mode to RGB (handle transparency)
+            # First check if the palette image has transparency
+            if 'transparency' in img.info:
+                img = img.convert('RGBA')
+            else:
+                img = img.convert('RGB')
+            
+            if img.mode == 'RGBA':
+                background = Image.new('RGB', img.size, (255, 255, 255))
+                background.paste(img, mask=img.split()[3])  # Use alpha channel as mask
+                img = background
+            # else: already RGB, no conversion needed
+        else:
+            # Convert other modes (L, etc.) to RGB
+            img = img.convert('RGB')
+    
+    # Automatic downsampling: resize if image is too large
+    # Large images slow down OCR significantly, so we resize while maintaining aspect ratio
+    width, height = img.size
+    if width > MAX_IMAGE_SIZE or height > MAX_IMAGE_SIZE:
+        # Calculate new dimensions maintaining aspect ratio
+        if width > height:
+            new_width = MAX_IMAGE_SIZE
+            new_height = int(height * (MAX_IMAGE_SIZE / width))
+        else:
+            new_height = MAX_IMAGE_SIZE
+            new_width = int(width * (MAX_IMAGE_SIZE / height))
+        
+        # Resize using high-quality resampling (LANCZOS) to preserve text quality
+        img = img.resize((new_width, new_height), Image.Resampling.LANCZOS)
+    
+    # Apply sharpening filter to enhance text edges and improve OCR accuracy
+    # Unsharp mask filter enhances edges without oversharpening
+    img = img.filter(ImageFilter.UnsharpMask(radius=1, percent=150, threshold=3))
+    
+    # Additional sharpening with ImageEnhance for fine control
+    # This helps make text characters more distinct and easier to recognize
+    enhancer = ImageEnhance.Sharpness(img)
+    img = enhancer.enhance(SHARPEN_FACTOR)
+    
+    # Save preprocessed image to temporary file
+    # Use JPEG format with high quality to preserve text clarity
+    temp_file = tempfile.NamedTemporaryFile(delete=False, suffix='.jpg', prefix='preprocessed_')
+    temp_path = temp_file.name
+    temp_file.close()
+    
+    # Save as JPEG with high quality to preserve text clarity
+    img.save(temp_path, 'JPEG', quality=95, optimize=True)
+    
+    return temp_path
+
+
+def get_ocr() -> PaddleOCR:
+    """Initialize PaddleOCR with optimized settings for speed and low latency
+    
+    Uses default language 'ch' (Chinese and English) with all performance optimizations enabled.
+    No backward compatibility - assumes latest PaddleOCR version with all features supported.
+    
+    Returns:
+        PaddleOCR instance with optimal configuration
+    """
+    global ocr_cache
+    
+    # Use default language 'ch' (Chinese and English) - most versatile
+    lang_key = 'ch'
+    
+    if lang_key not in ocr_cache:
+        # Build optimization parameters compatible with PaddleOCR 2.7+
+        # Note: PaddleOCR 2.7+ uses different parameter names
+        ocr_params = {
+            'lang': lang_key,  # Default language 'ch' (Chinese and English) - most versatile
+            'use_textline_orientation': False,  # Fast mode: disable textline orientation classification
+            'text_recognition_batch_size': 1,  # Process one image at a time for lowest latency
+        }
+        
+        # Initialize PaddleOCR with compatible parameters
+        # PaddleOCR 2.7+ automatically detects GPU/CPU and uses optimal settings
+        ocr_cache[lang_key] = PaddleOCR(**ocr_params)
+    
+    return ocr_cache[lang_key]
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+    """List available tools"""
+    return [
+        types.Tool(
+            name="ocr_image",
+            description="Extract text from an image using PaddleOCR with automatic optimizations. Returns the path to the generated markdown file (image_path + .md). All optimizations are applied automatically.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "image_path": {
+                        "type": "string",
+                        "description": "Path to the input image file"
+                    }
+                },
+                "required": ["image_path"]
+            }
+        )
+    ]
+
+
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: Optional[dict[str, Any]]) -> list[types.TextContent]:
+    """Handle tool calls"""
+    if name != "ocr_image":
+        raise ValueError(f"Unknown tool: {name}")
+    
+    if not arguments or "image_path" not in arguments:
+        raise ValueError("Missing required argument: image_path")
+    
+    image_path = arguments["image_path"]
+    if not isinstance(image_path, str):
+        raise ValueError("image_path must be a string")
+    
+    try:
+        # Validate input file exists
+        image_path_obj = Path(image_path)
+        if not image_path_obj.exists():
+            raise FileNotFoundError(f"Image file not found: {image_path}")
+        
+        if not image_path_obj.is_file():
+            raise ValueError(f"Path is not a file: {image_path}")
+        
+        # Preprocess image: automatic downsampling and sharpening
+        # This improves OCR performance and accuracy
+        preprocessed_path = preprocess_image(str(image_path_obj))
+        
+        try:
+            # Initialize OCR with automatic optimizations and fallback
+            ocr_instance = get_ocr()
+            
+            # Perform OCR on preprocessed image
+            # PaddleOCR 2.7+ doesn't support cls parameter
+            result = ocr_instance.ocr(preprocessed_path)
+        finally:
+            # Clean up temporary preprocessed image file
+            try:
+                if os.path.exists(preprocessed_path):
+                    os.unlink(preprocessed_path)
+            except Exception:
+                pass  # Ignore cleanup errors
+        
+        # Generate output markdown file path (image.png -> image.png.md)
+        output_path = Path(str(image_path_obj) + '.md')
+        
+        # Extract text from OCR result
+        detected_texts = []
+        if result and result[0]:
+            for line in result[0]:
+                if line and len(line) >= 2:
+                    text = line[1][0]  # Extract text from OCR result format: [[box_coords], (text, confidence)]
+                    if text:
+                        detected_texts.append(text)
+        
+        # Write markdown file
+        with open(output_path, 'w', encoding='utf-8') as f:
+            f.write("# OCR Result\n\n")
+            f.write(f"**Source Image:** `{image_path}`\n\n")
+            f.write("---\n\n")
+            
+            if detected_texts:
+                for text in detected_texts:
+                    f.write(f"- {text}\n")
+            else:
+                f.write("- No text detected\n")
+        
+        # Return the output file path
+        return [types.TextContent(type="text", text=str(output_path))]
+    
+    except Exception as e:
+        error_msg = f"Error processing image {image_path}: {str(e)}"
+        print(error_msg, file=sys.stderr)
+        raise RuntimeError(error_msg) from e
+
+
+async def main_async():
+    """Async main entry point for the MCP server"""
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="fast-paddleocr-mcp",
+                server_version="0.3.9",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+def main():
+    """Main entry point for the MCP server (synchronous wrapper)"""
+    asyncio.run(main_async())
+
+
+if __name__ == "__main__":
+    main()