PaddleOCR-MCP: Instructions file for Codex

Project Instructions

⚠️ Important: You must read cursor-agents-md skills every time before write or update this AGENTS.md.

Project Overview

This is a Fast PaddleOCR MCP (Model Context Protocol) server that extracts text from images using PaddleOCR and outputs results in markdown format. The server provides an ocr_image tool that accepts an image path and returns the path to the generated markdown file (image_path + .md).

Code Style

• Use Python 3.8+ (supports up to 3.12)
• Follow PEP 8 style guidelines
• Use type hints with typing module (e.g., Optional[dict[str, Any]])
• Maximum line length: 100 characters (preferred) or 120 characters (if needed)
• Use async/await for MCP server handlers
• Use f-strings for string formatting
• Use Path from pathlib for file operations, not os.path
• Import order: standard library → third-party → local imports
• Use snake_case for function and variable names
• Use UPPER_CASE for constants

Example Code Style

from pathlib import Path
from typing import Any, Optional

async def handle_call_tool(name: str, arguments: Optional[dict[str, Any]]) -> list[types.TextContent]:
    """Handle tool calls with proper type hints"""
    if not arguments or "image_path" not in arguments:
        raise ValueError("Missing required argument: image_path")
    
    image_path = arguments["image_path"]
    image_path_obj = Path(image_path)
    
    if not image_path_obj.exists():
        raise FileNotFoundError(f"Image file not found: {image_path}")

Architecture

MCP Server Structure

• Single tool: ocr_image - Main functionality
• Lazy initialization: OCR instances are cached by language
• Error handling: Wrap exceptions in RuntimeError with descriptive messages
• Async handlers: All MCP handlers must be async functions
• Stdio transport: Server communicates via standard input/output

Key Components

1. OCR Instance Management:
   • Cache PaddleOCR instances by language in global ocr_cache dict
   • Use lowercase language keys for consistency
   • Lazy initialization on first use