mistral-ocr-mcp 0.1.3__py3-none-any.whl

mistral_ocr_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""Mistral OCR MCP Server.
+
+A Model Context Protocol (MCP) server that provides tools for extracting
+text and images from PDF and image files using the Mistral OCR API.
+"""
+
+__version__ = "0.1.0"

mistral_ocr_mcp/__main__.py

@@ -0,0 +1,27 @@
+"""MCP server implementation for Mistral OCR."""
+
+import sys
+from .config import ConfigurationError, load_config
+from .server import run
+
+
+def main() -> int:
+    """Main entry point for the MCP server."""
+    try:
+        # Load and validate configuration before starting server
+        load_config()
+        run()
+        return 0
+    except ConfigurationError as e:
+        print(f"Configuration error: {e}", file=sys.stderr)
+        return 1
+    except NotImplementedError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mistral_ocr_mcp/config.py

@@ -0,0 +1,88 @@
+"""Configuration module for Mistral OCR MCP server.
+
+This module loads and validates environment variables required for the server.
+"""
+
+import os
+from pathlib import Path
+from typing import NamedTuple
+
+
+class Config(NamedTuple):
+    """Configuration for the Mistral OCR MCP server.
+
+    Attributes:
+        api_key: Mistral API key (never logged)
+        allowed_dir_original: Original allowed directory string from environment
+        allowed_dir_resolved: Resolved canonical path to allowed directory
+    """
+
+    api_key: str
+    allowed_dir_original: str
+    allowed_dir_resolved: Path
+
+
+class ConfigurationError(Exception):
+    """Exception raised for configuration errors."""
+
+    pass
+
+
+def load_config() -> Config:
+    """Load and validate configuration from environment variables.
+
+    Reads:
+        - MISTRAL_API_KEY: Required API key for Mistral OCR service
+        - MISTRAL_OCR_ALLOWED_DIR: Required absolute path to allowed directory
+
+    Returns:
+        Config object with validated settings
+
+    Raises:
+        ConfigurationError: If any required environment variable is missing
+                            or if the allowed directory is invalid
+    """
+    # Load API key
+    api_key = os.getenv("MISTRAL_API_KEY")
+    if not api_key:
+        raise ConfigurationError(
+            "Missing required environment variable: MISTRAL_API_KEY"
+        )
+
+    # Load allowed directory
+    allowed_dir_str = os.getenv("MISTRAL_OCR_ALLOWED_DIR")
+    if not allowed_dir_str:
+        raise ConfigurationError(
+            "Missing required environment variable: MISTRAL_OCR_ALLOWED_DIR"
+        )
+
+    # Verify it's an absolute path BEFORE canonicalization (SRS FR-5.3)
+    if not Path(allowed_dir_str).is_absolute():
+        raise ConfigurationError(
+            f"MISTRAL_OCR_ALLOWED_DIR must be an absolute path: {allowed_dir_str}"
+        )
+
+    # Validate and canonicalize allowed directory
+    try:
+        allowed_dir = Path(allowed_dir_str).resolve(strict=True)
+    except FileNotFoundError:
+        raise ConfigurationError(
+            f"MISTRAL_OCR_ALLOWED_DIR does not exist: {allowed_dir_str}"
+        )
+    except RuntimeError as e:
+        # Can happen if path contains infinite symlink loops
+        raise ConfigurationError(
+            f"Invalid MISTRAL_OCR_ALLOWED_DIR: {allowed_dir_str} - {e}"
+        )
+
+    # Verify it's a directory
+    if not allowed_dir.is_dir():
+        raise ConfigurationError(
+            f"MISTRAL_OCR_ALLOWED_DIR is not a directory: {allowed_dir_str}"
+        )
+
+    return Config(
+        api_key=api_key,
+        allowed_dir_original=allowed_dir_str,
+        allowed_dir_resolved=allowed_dir,
+    )

mistral_ocr_mcp/extraction.py

@@ -0,0 +1,159 @@
+"""Extraction orchestration for Mistral OCR MCP server.
+
+This module provides the main extraction functions that orchestrate OCR calls,
+image saving, and markdown rewriting.
+"""
+
+import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .config import load_config
+from .images import save_images
+from .markdown_rewrite import rewrite_markdown
+from .mistral_client import process_local_file
+from .path_sandbox import PathValidationError, validate_file_path, validate_output_dir
+
+
+def extract_markdown(file_path: str) -> str:
+    """Extract markdown text from a file without images.
+
+    Args:
+        file_path: Absolute path to the input file (PDF or image)
+
+    Returns:
+        Concatenated markdown content from all pages
+
+    Raises:
+        PathValidationError: If file_path is invalid
+        MistralOCRAPIError: If the OCR API call fails
+        MistralOCRFileError: If filesystem operations fail
+    """
+    # Validate file path
+    validated_path = validate_file_path(file_path)
+
+    # Call OCR without images
+    response = process_local_file(validated_path, include_image_base64=False)
+
+    # Join page markdowns with double newline
+    page_markdowns = [page.markdown for page in response.pages]
+    return "\n\n".join(page_markdowns)
+
+
+def extract_markdown_with_images(file_path: str, output_dir: str) -> Dict[str, Any]:
+    """Extract markdown with embedded images and save them as separate files.
+
+    This function:
+    1. Validates both file_path and output_dir
+    2. Enforces sandbox constraints using config
+    3. Creates a unique output subdirectory
+    4. Calls OCR with include_image_base64=True
+    5. Saves images to the output subdirectory
+    6. Rewrites markdown to replace base64 URIs with relative paths
+    7. Saves the rewritten markdown as content.md
+    8. Returns metadata about the extracted content
+
+    Args:
+        file_path: Absolute path to the input file (PDF or image)
+        output_dir: Absolute path to the output directory (must be within allowed dir)
+
+    Returns:
+        Dictionary with keys:
+            - output_directory: Absolute path to the output subdirectory
+            - markdown_file: Absolute path to the content.md file
+            - images: List of saved image filenames (not full paths)
+
+    Raises:
+        PathValidationError: If file_path or output_dir is invalid
+        MistralOCRAPIError: If the OCR API call fails
+        MistralOCRFileError: If filesystem operations fail
+    """
+    # Load config to get allowed directory
+    config = load_config()
+
+    # Validate file path
+    validated_file_path = validate_file_path(file_path)
+
+    # Validate output directory with sandbox enforcement
+    validated_output_dir = validate_output_dir(
+        output_dir,
+        config.allowed_dir_resolved,
+        config.allowed_dir_original,
+    )
+
+    # Create output subdirectory with collision handling
+    output_subdir = _create_output_subdirectory(
+        validated_output_dir, validated_file_path
+    )
+
+    # Call OCR with images
+    response = process_local_file(validated_file_path, include_image_base64=True)
+
+    # Extract images from response
+    images: List[dict] = []
+    for page in response.pages:
+        if hasattr(page, "images") and page.images:
+            images.extend(
+                [
+                    img.model_dump() if hasattr(img, "model_dump") else img
+                    for img in page.images
+                ]
+            )
+
+    # Save images
+    saved_filenames = save_images(output_subdir, images)
+
+    # Join page markdowns
+    page_markdowns = [page.markdown for page in response.pages]
+    markdown_content = "\n\n".join(page_markdowns)
+
+    # Rewrite markdown to replace base64 URIs with relative paths
+    rewritten_markdown = rewrite_markdown(markdown_content, images, saved_filenames)
+
+    # Save markdown as content.md
+    markdown_file_path = output_subdir / "content.md"
+    markdown_file_path.write_text(rewritten_markdown, encoding="utf-8")
+
+    return {
+        "output_directory": str(output_subdir),
+        "markdown_file": str(markdown_file_path),
+        "images": saved_filenames,
+    }
+
+
+def _create_output_subdirectory(output_dir: Path, file_path: Path) -> Path:
+    """Create a unique output subdirectory for a file's extracted content.
+
+    The subdirectory name is based on the file stem (without extension).
+    If a directory with that name already exists, appends a timestamp
+    in the format _YYYYMMDD_HHMMSS.
+
+    Args:
+        output_dir: The validated output directory
+        file_path: The validated input file path
+
+    Returns:
+        Path to the created output subdirectory
+    """
+    base_name = file_path.stem
+    subdir_path = output_dir / base_name
+
+    # If base directory doesn't exist, just use it
+    if not subdir_path.exists():
+        subdir_path.mkdir(parents=True, exist_ok=True)
+        return subdir_path
+
+    # Directory exists, append timestamp until we find a unique name
+    while True:
+        timestamp = datetime.datetime.now().strftime("_%Y%m%d_%H%M%S")
+        timestamped_path = output_dir / f"{base_name}{timestamp}"
+
+        if not timestamped_path.exists():
+            timestamped_path.mkdir(parents=True, exist_ok=True)
+            return timestamped_path
+
+        # Extremely unlikely but possible: timestamp collision
+        # Sleep a tiny bit and try again
+        import time
+
+        time.sleep(0.001)

mistral_ocr_mcp/images.py

@@ -0,0 +1,175 @@
+"""Image handling for Mistral OCR MCP server.
+
+This module handles parsing and saving base64-encoded images from OCR responses.
+"""
+
+import base64
+import binascii
+import re
+from pathlib import Path
+from typing import List, Tuple
+
+
+class ImageError(Exception):
+    """Exception raised for image processing errors."""
+
+    pass
+
+
+def parse_data_uri(data_uri: str) -> Tuple[str, str]:
+    """Parse a data URI to extract MIME type and raw base64 data.
+
+    Args:
+        data_uri: Data URI string like `data:image/jpeg;base64,<...>`
+
+    Returns:
+        Tuple of (mime_type, raw_base64_string)
+
+    Raises:
+        ImageError: If the data URI is invalid or missing required parts
+    """
+    if not data_uri:
+        raise ImageError("data_uri cannot be empty")
+
+    # Match data URI pattern: data:<mime>;base64,<data>
+    match = re.match(r"^data:([^;]*);base64,(.*)$", data_uri)
+    if not match:
+        raise ImageError(
+            f"Invalid data URI format, expected 'data:<mime>;base64,<data>': {data_uri[:50]}..."
+        )
+
+    mime_type = match.group(1)
+    raw_b64 = match.group(2)
+
+    if not mime_type:
+        raise ImageError(f"Missing MIME type in data URI: {data_uri[:50]}...")
+
+    if not raw_b64:
+        raise ImageError(f"Missing base64 data in data URI: {data_uri[:50]}...")
+
+    return mime_type, raw_b64
+
+
+def get_extension_from_mime(mime_type: str) -> str:
+    """Determine file extension from MIME type.
+
+    Args:
+        mime_type: MIME type string like 'image/jpeg'
+
+    Returns:
+        File extension including the dot (e.g., '.jpeg')
+
+    Returns:
+        str: File extension with leading dot
+    """
+    # Mapping of common image MIME types to extensions
+    mime_to_ext = {
+        "image/jpeg": ".jpeg",
+        "image/jpg": ".jpg",
+        "image/png": ".png",
+        "image/webp": ".webp",
+        "image/gif": ".gif",
+    }
+
+    # Normalize MIME type to lowercase
+    mime_lower = mime_type.lower()
+
+    # Default to .png if unknown
+    return mime_to_ext.get(mime_lower, ".png")
+
+
+def save_base64_image(output_dir: Path, image_id: str, data_uri: str) -> str:
+    """Decode a base64 data URI and save it as an image file.
+
+    Args:
+        output_dir: Directory to save the image in
+        image_id: Identifier for the image (used as filename; may already include an extension)
+        data_uri: Base64 data URI string
+
+    Returns:
+        Filename of the saved image (without directory path)
+
+    Raises:
+        ImageError: If parsing, decoding, or saving fails
+    """
+    try:
+        mime_type, raw_b64 = parse_data_uri(data_uri)
+        ext = get_extension_from_mime(mime_type)
+
+        # Sanitize image_id to prevent path traversal attacks
+        # First, remove any path separators and null bytes
+        sanitized_id = image_id.replace("\0", "_")
+        # Remove any directory separators and parent directory references
+        sanitized_id = sanitized_id.replace("/", "_").replace("\\", "_")
+        sanitized_id = sanitized_id.replace("..", "__")
+
+        # Only allow alphanumeric characters, underscores, hyphens, and dots
+        sanitized_id = re.sub(r"[^\w\-.]", "_", sanitized_id)
+
+        # Ensure it doesn't start with a dot (hidden file) or dash (flag)
+        if sanitized_id.startswith(".") or sanitized_id.startswith("-"):
+            sanitized_id = "_" + sanitized_id.lstrip(".-")
+
+        # Remove any remaining path traversal patterns
+        sanitized_id = re.sub(r"\.\.+", "__", sanitized_id)
+
+        # Limit length to prevent filesystem issues
+        max_id_length = 200  # Leave room for extension
+        if len(sanitized_id) > max_id_length:
+            sanitized_id = sanitized_id[:max_id_length]
+
+        # Don't append extension if image_id already ends with it (case-insensitive)
+        # This prevents duplicate extensions like image.jpeg.jpeg
+        if sanitized_id.lower().endswith(ext.lower()):
+            filename = sanitized_id
+        else:
+            filename = f"{sanitized_id}{ext}"
+
+        output_path = output_dir / filename
+
+        # Decode base64
+        image_data = base64.b64decode(raw_b64)
+
+        # Ensure output directory exists
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Write file
+        output_path.write_bytes(image_data)
+
+        return filename
+
+    except (binascii.Error, ValueError) as e:
+        raise ImageError(
+            f"Failed to decode base64 image data for image_id={image_id}: {e}"
+        ) from e
+
+
+def save_images(output_dir: Path, images: List[dict]) -> List[str]:
+    """Save multiple base64-encoded images from OCR response.
+
+    Args:
+        output_dir: Directory to save images in
+        images: List of image dictionaries with 'id' and 'image_base64' keys
+
+    Returns:
+        List of saved filenames in the same order as input images
+
+    Raises:
+        ImageError: If any image fails to parse, decode, or save
+    """
+    saved_filenames = []
+
+    for img in images:
+        image_id = img.get("id")
+        image_base64 = img.get("image_base64")
+
+        if image_id is None:
+            raise ImageError("Image missing 'id' field")
+
+        if image_base64 is None:
+            raise ImageError(f"Image '{image_id}' missing 'image_base64' field")
+
+        filename = save_base64_image(output_dir, image_id, image_base64)
+        saved_filenames.append(filename)
+
+    return saved_filenames

mistral_ocr_mcp/markdown_rewrite.py

@@ -0,0 +1,118 @@
+"""Markdown rewrite module for Mistral OCR MCP server.
+
+This module rewrites markdown content to replace embedded base64 image URIs
+with relative file paths.
+"""
+
+import re
+from typing import List, Optional
+
+
+def rewrite_markdown(
+    markdown: str, images: List[dict], output_filenames: Optional[List[str]] = None
+) -> str:
+    """Rewrite markdown to replace embedded base64 image URIs with relative paths.
+
+    The function uses a deterministic strategy:
+    1. First, try exact-match replacement using the image_base64 strings
+       returned by the API, paired with output_filenames.
+    2. If no output_filenames provided or exact matches fail, fall back to
+       sequential regex replacement in document order.
+
+    Args:
+        markdown: The original markdown content with embedded base64 images
+        images: List of image dictionaries from OCR response with 'image_base64' keys
+        output_filenames: Optional list of filenames to use for exact-match replacement.
+                         Must match length of images. If None, uses sequential strategy.
+
+    Returns:
+        Rewritten markdown with base64 URIs replaced by relative paths like './img_id.ext'
+
+    Raises:
+        ValueError: If output_filenames is provided but doesn't match images length
+    """
+    if output_filenames is not None:
+        if len(output_filenames) != len(images):
+            raise ValueError(
+                f"output_filenames length ({len(output_filenames)}) "
+                f"must match images length ({len(images)})"
+            )
+        # Strategy 1: Exact-match replacement
+        return _rewrite_exact_match(markdown, images, output_filenames)
+    else:
+        # Strategy 2: Sequential regex replacement
+        return _rewrite_sequential(markdown, images)
+
+
+def _rewrite_exact_match(
+    markdown: str, images: List[dict], output_filenames: List[str]
+) -> str:
+    """Rewrite using exact-match replacement of data URIs.
+
+    Args:
+        markdown: Original markdown content
+        images: List of image dicts with 'image_base64' keys
+        output_filenames: List of filenames to use for replacement
+
+    Returns:
+        Rewritten markdown
+    """
+    result = markdown
+    for img, filename in zip(images, output_filenames):
+        data_uri = img.get("image_base64")
+        if data_uri:
+            # Replace exact data URI string with relative path
+            result = result.replace(data_uri, f"./{filename}")
+    return result
+
+
+def _rewrite_sequential(markdown: str, images: List[dict]) -> str:
+    """Rewrite using sequential regex replacement.
+
+    Finds all data:image/...;base64,... patterns and replaces them
+    sequentially with ./<id>.ext using extensions determined from the data URI.
+
+    Args:
+        markdown: Original markdown content
+        images: List of image dicts with 'id' and 'image_base64' keys
+
+    Returns:
+        Rewritten markdown
+    """
+    # Import here to avoid circular dependency
+    from .images import get_extension_from_mime, parse_data_uri
+
+    result = markdown
+
+    # Pattern to match data URIs in markdown
+    # This matches: data:image/...;base64,... (case-insensitive for mime type)
+    data_uri_pattern = re.compile(r'data:image/[^;]+;base64,[^"\'\)]+', re.IGNORECASE)
+
+    # Find all data URIs in the markdown
+    matches = list(data_uri_pattern.finditer(result))
+
+    # Replace sequentially in order of appearance
+    for i, match in enumerate(matches):
+        # Get the image data for this position
+        if i < len(images):
+            img = images[i]
+            image_id = img.get("id", f"image_{i}")
+            data_uri = img.get("image_base64", match.group(0))
+
+            try:
+                # Parse the data URI to get the extension
+                mime_type, _ = parse_data_uri(data_uri)
+                ext = get_extension_from_mime(mime_type)
+            except Exception:
+                # If parsing fails, default to .png
+                ext = ".png"
+
+            # Replace this occurrence with relative path
+            result = (
+                result[: match.start()] + f"./{image_id}{ext}" + result[match.end() :]
+            )
+        else:
+            # More data URIs in markdown than images - skip extras
+            break
+
+    return result

mistral_ocr_mcp/mistral_client.py

@@ -0,0 +1,129 @@
+"""Mistral OCR client adapter.
+
+This module wraps the official `mistralai` SDK behind a small adapter function.
+It centralizes:
+- client initialization from environment-based config
+- the upload -> signed URL -> OCR process flow
+- consistent error normalization (FR-6)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, Optional
+
+try:
+    from mistralai import Mistral, models
+except ModuleNotFoundError:  # pragma: no cover
+    # Allow offline unit tests to inject a fake client without requiring the SDK.
+    Mistral = None  # type: ignore[assignment]
+    models = SimpleNamespace(  # type: ignore[assignment]
+        OCRResponse=Any,
+        MistralError=Exception,
+    )
+
+from .config import load_config
+
+
+def _mistral_error_types() -> tuple[type[BaseException], ...]:
+    """Return the Mistral SDK exception types we normalize (FR-6.2)."""
+
+    error_types: list[type[BaseException]] = [models.MistralError]
+    sdk_error = getattr(models, "SDKError", None)
+    if sdk_error is not None:
+        error_types.append(sdk_error)
+    return tuple(error_types)
+
+
+def _format_mistral_error(e: BaseException) -> str:
+    status_code = getattr(e, "status_code", None)
+    message = getattr(e, "message", str(e))
+
+    if status_code is None:
+        return f"Mistral OCR request failed: {message}"
+
+    return f"Mistral OCR request failed (status={status_code}): {message}"
+
+
+class MistralOCRClientError(RuntimeError):
+    """Base exception for Mistral OCR client adapter errors."""
+
+
+class MistralOCRAPIError(MistralOCRClientError):
+    """Raised when the Mistral API returns an error."""
+
+
+class MistralOCRFileError(MistralOCRClientError):
+    """Raised when local filesystem operations fail."""
+
+
+def process_local_file(
+    path: Path,
+    *,
+    include_image_base64: bool = False,
+    client: Optional[Mistral] = None,
+) -> models.OCRResponse:
+    """Run OCR against a local file path.
+
+    Flow:
+      1) Upload file via `client.files.upload(..., purpose="ocr")`
+      2) Fetch signed URL via `client.files.get_signed_url(...)`
+      3) Call `client.ocr.process(...)` with a `document_url` for PDFs and an
+         `image_url` for other supported image formats.
+
+    Args:
+        path: Local filesystem path to a PDF or image.
+        include_image_base64: Whether to include base64 images in OCR response.
+        client: Optional injected Mistral client (useful for unit tests).
+
+    Returns:
+        The SDK's OCRResponse.
+
+    Raises:
+        MistralOCRAPIError: For SDK/API errors (includes status code + message).
+        MistralOCRFileError: For local filesystem errors (includes path + operation).
+    """
+
+    def _process(mistral: Mistral) -> models.OCRResponse:
+        try:
+            with path.open("rb") as fh:
+                uploaded = mistral.files.upload(
+                    file={"file_name": path.name, "content": fh},
+                    purpose="ocr",
+                )
+        except OSError as e:
+            raise MistralOCRFileError(
+                f"Filesystem error during open/read for upload: path={path!s}"
+            ) from e
+        except _mistral_error_types() as e:
+            raise MistralOCRAPIError(_format_mistral_error(e)) from e
+
+        try:
+            signed_url = mistral.files.get_signed_url(file_id=uploaded.id)
+
+            is_pdf = path.suffix.lower() == ".pdf"
+            if is_pdf:
+                document = {"type": "document_url", "document_url": signed_url.url}
+            else:
+                document = {"type": "image_url", "image_url": signed_url.url}
+
+            return mistral.ocr.process(
+                model="mistral-ocr-latest",
+                document=document,
+                include_image_base64=bool(include_image_base64),
+            )
+        except _mistral_error_types() as e:
+            raise MistralOCRAPIError(_format_mistral_error(e)) from e
+
+    if client is not None:
+        return _process(client)
+
+    if Mistral is None:
+        raise MistralOCRClientError(
+            "mistralai SDK is required when no client is injected"
+        )
+
+    config = load_config()
+    with Mistral(api_key=config.api_key) as mistral:
+        return _process(mistral)

mistral_ocr_mcp/path_sandbox.py

@@ -0,0 +1,143 @@
+"""Path sandbox validation for Mistral OCR MCP server.
+
+This module provides validation for file paths and output directories,
+ensuring they are within the allowed directory sandbox.
+"""
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Set
+
+# Supported file extensions for OCR processing
+SUPPORTED_EXTENSIONS: Set[str] = {
+    ".pdf",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".gif",
+}
+
+
+class PathValidationError(Exception):
+    """Exception raised for path validation errors."""
+
+    pass
+
+
+def validate_file_path(file_path: str) -> Path:
+    """Validate and canonicalize an input file path.
+
+    Args:
+        file_path: Absolute path to the input file
+
+    Returns:
+        Resolved canonical Path to the file
+
+    Raises:
+        PathValidationError: If path is not absolute, doesn't exist,
+                            has unsupported extension, or other filesystem error
+    """
+    path = Path(file_path)
+
+    # Check if absolute
+    if not path.is_absolute():
+        raise PathValidationError(
+            f"validate file_path: must be an absolute path: {file_path}"
+        )
+
+    # Canonicalize and check existence
+    try:
+        resolved_path = path.resolve(strict=True)
+    except FileNotFoundError:
+        raise PathValidationError(
+            f"validate file_path: resolve failed, path does not exist: {file_path}"
+        )
+    except RuntimeError as e:
+        # Can happen with infinite symlink loops
+        raise PathValidationError(
+            f"validate file_path: resolve failed: {file_path} - {e}"
+        )
+
+    # Check extension
+    if resolved_path.suffix.lower() not in SUPPORTED_EXTENSIONS:
+        raise PathValidationError(
+            f"validate file_path: unsupported file type '{resolved_path.suffix}'. "
+            f"Supported types: .pdf, .png, .jpg, .jpeg, .webp, .gif. Path: {file_path}"
+        )
+
+    return resolved_path
+
+
+def validate_output_dir(
+    output_dir: str,
+    allowed_dir_resolved: Path,
+    allowed_dir_original: str,
+) -> Path:
+    """Validate and canonicalize an output directory path.
+
+    Args:
+        output_dir: Absolute path to the output directory
+        allowed_dir_resolved: Canonical path to the allowed directory
+        allowed_dir_original: Original string from environment (for error messages)
+
+    Returns:
+        Resolved canonical Path to the output directory
+
+    Raises:
+        PathValidationError: If path is not absolute, doesn't exist,
+                            is not a directory, not writable, or outside allowed dir
+    """
+    path = Path(output_dir)
+
+    # Check if absolute
+    if not path.is_absolute():
+        raise PathValidationError(
+            f"validate output_dir: must be an absolute path: {output_dir}"
+        )
+
+    # Canonicalize and check existence
+    try:
+        resolved_path = path.resolve(strict=True)
+    except FileNotFoundError:
+        raise PathValidationError(
+            f"validate output_dir: resolve failed, path does not exist: {output_dir}"
+        )
+    except RuntimeError as e:
+        raise PathValidationError(
+            f"validate output_dir: resolve failed: {output_dir} - {e}"
+        )
+
+    # Verify it's a directory
+    if not resolved_path.is_dir():
+        raise PathValidationError(
+            f"validate output_dir: path is not a directory: {output_dir}"
+        )
+
+    # Check writability - try creating a temporary file
+    try:
+        # Use mkstemp to create a unique temporary file atomically
+        # This avoids predictable filenames and doesn't follow pre-existing symlinks
+        fd, temp_path = tempfile.mkstemp(dir=str(resolved_path))
+        os.close(fd)
+        os.unlink(temp_path)
+    except PermissionError:
+        raise PathValidationError(
+            f"validate output_dir: writability check failed, directory not writable: {output_dir}"
+        )
+    except OSError as e:
+        raise PathValidationError(
+            f"validate output_dir: writability check failed: {output_dir} - {e}"
+        )
+
+    # Sandbox enforcement: output_dir must be within allowed directory
+    try:
+        resolved_path.relative_to(allowed_dir_resolved)
+    except ValueError:
+        # output_dir is not a descendant of allowed_dir
+        raise PathValidationError(
+            f"output_dir must be within the allowed directory: {allowed_dir_original}"
+        )
+
+    return resolved_path

mistral_ocr_mcp/server.py

@@ -0,0 +1,86 @@
+"""MCP server implementation for Mistral OCR."""
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .extraction import extract_markdown, extract_markdown_with_images
+
+
+# Create the MCP server instance
+mcp = FastMCP("Mistral OCR")
+
+
+@mcp.tool(name="extract_markdown")
+def extract_markdown_tool(file_path: str) -> str:
+    """Extract markdown text from a PDF or image file.
+
+    Args:
+        file_path: Absolute path to the input file (PDF or image)
+
+    Returns:
+        Extracted markdown content as a string
+    """
+    return extract_markdown(file_path)
+
+
+@mcp.tool(name="extract_markdown_with_images")
+def extract_markdown_with_images_tool(
+    file_path: str, output_dir: str
+) -> dict[str, Any]:
+    """Extract markdown with embedded images and save them as separate files.
+
+    Args:
+        file_path: Absolute path to the input file (PDF or image)
+        output_dir: Absolute path to an existing output directory (must be within allowed dir)
+
+    Returns:
+        Dictionary with:
+            - output_directory: Absolute path to the output subdirectory
+            - markdown_file: Absolute path to the content.md file
+            - images: List of saved image filenames (not full paths)
+    """
+    result = extract_markdown_with_images(file_path, output_dir)
+    return result
+
+
+def list_tools_impl() -> list[str]:
+    """List available tool names for testing purposes."""
+    return ["extract_markdown", "extract_markdown_with_images"]
+
+
+def call_tool_impl(name: str, arguments: dict[str, Any]) -> Any:
+    """Call a tool implementation for testing purposes.
+
+    Args:
+        name: Tool name to call
+        arguments: Tool arguments as a dictionary
+
+    Returns:
+        Tool result or raises an error
+
+    Raises:
+        ValueError: If tool name is unknown
+    """
+    if name == "extract_markdown":
+        if "file_path" not in arguments:
+            raise ValueError("Missing required argument: file_path")
+        return extract_markdown(arguments["file_path"])
+    elif name == "extract_markdown_with_images":
+        if "file_path" not in arguments:
+            raise ValueError("Missing required argument: file_path")
+        if "output_dir" not in arguments:
+            raise ValueError("Missing required argument: output_dir")
+        return extract_markdown_with_images(
+            arguments["file_path"], arguments["output_dir"]
+        )
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+
+def run() -> None:
+    """Run the MCP server.
+
+    This is a synchronous wrapper that starts the stdio server.
+    """
+    mcp.run()

mistral_ocr_mcp-0.1.3.dist-info/METADATA

@@ -0,0 +1,407 @@
+Metadata-Version: 2.4
+Name: mistral-ocr-mcp
+Version: 0.1.3
+Summary: MCP server for extracting text and images from documents using Mistral OCR API
+Project-URL: Homepage, https://github.com/ORDIS-Co-Ltd/mistral-ocr-mcp
+Project-URL: Repository, https://github.com/ORDIS-Co-Ltd/mistral-ocr-mcp
+Author: Ordis
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: mistralai>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Mistral OCR MCP Server
+
+A Model Context Protocol (MCP) server that provides tools for extracting text and images from PDF and image files using the Mistral OCR API.
+
+## Features
+
+- **Simple Text Extraction**: Extract markdown content from documents without handling images
+- **Full Extraction with Images**: Extract markdown and save embedded images to disk with proper relative links
+- **Security Sandbox**: Restricts file writes to a configured allowed directory
+- **Zero-Install Deployment**: Run with `uvx` without prior installation
+- **Supported Formats**: PDF (`.pdf`), PNG (`.png`), JPEG (`.jpg`, `.jpeg`), WebP (`.webp`), GIF (`.gif`)
+
+---
+
+## Quickstart
+
+Run the server directly with `uvx` (no installation required):
+
+```bash
+MISTRAL_API_KEY="your-api-key-here" \
+MISTRAL_OCR_ALLOWED_DIR="/absolute/path/to/allowed/directory" \
+uvx mistral-ocr-mcp
+```
+
+**Important**: `MISTRAL_OCR_ALLOWED_DIR` must be:
+- An **absolute path** (e.g., `/Users/username/documents`, not `~/documents`)
+- An **existing directory** on your filesystem
+- The location where you want to allow the server to write extracted images
+
+The server will start in stdio mode and wait for MCP client connections.
+
+---
+
+## Installation
+
+### For Use with MCP Clients
+
+Install via pip:
+
+```bash
+pip install mistral-ocr-mcp
+```
+
+Then configure your MCP client (e.g., Claude Desktop) to run:
+
+```bash
+mistral-ocr-mcp
+```
+
+### For Development
+
+Clone the repository and install with development dependencies:
+
+```bash
+git clone https://github.com/ORDIS-Co-Ltd/mistral-ocr-mcp
+cd mistral-ocr-multimedia-mcp
+pip install -e '.[dev]'
+```
+
+Run the server:
+
+```bash
+MISTRAL_API_KEY="your-key" \
+MISTRAL_OCR_ALLOWED_DIR="/path/to/allowed/dir" \
+python -m mistral_ocr_mcp
+```
+
+---
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `MISTRAL_API_KEY` | Your Mistral API key (never logged) | `sk-abc123...` |
+| `MISTRAL_OCR_ALLOWED_DIR` | Absolute path to allowed write directory | `/Users/username/workdir` |
+
+### Security Sandbox
+
+The server enforces a **write directory sandbox** to prevent unauthorized file writes:
+
+- **`extract_markdown`**: No write restrictions (read-only operation)
+- **`extract_markdown_with_images`**: The `output_dir` parameter **must** be within `MISTRAL_OCR_ALLOWED_DIR`
+
+**Validation Examples:**
+
+| `MISTRAL_OCR_ALLOWED_DIR` | `output_dir` | Result |
+|---------------------------|--------------|--------|
+| `/Users/username/workdir` | `/Users/username/workdir/project/output` | ✅ Allowed |
+| `/Users/username/workdir` | `/Users/username/workdir` | ✅ Allowed (exact match) |
+| `/Users/username/workdir` | `/Users/username/documents` | ❌ Rejected |
+| `/Users/username/workdir` | `/Users/username/workdir/../documents` | ❌ Rejected (resolves outside) |
+
+**Security Notes:**
+- All paths are canonicalized (symlinks resolved, `..` eliminated) before validation
+- Image filenames are sanitized to prevent path traversal attacks
+
+---
+
+## Client Configuration
+
+### Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "mistral-ocr": {
+      "command": "uvx",
+      "args": ["mistral-ocr-mcp"],
+      "env": {
+        "MISTRAL_API_KEY": "your-api-key-here",
+        "MISTRAL_OCR_ALLOWED_DIR": "/absolute/path/to/allowed/directory"
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add this to the `mcp` section of your configuration file:
+
+```json
+{
+  "mcp": {
+    "mistral-ocr": {
+      "type": "local",
+      "command": ["uvx", "mistral-ocr-mcp"],
+      "enabled": true,
+      "environment": {
+        "MISTRAL_API_KEY": "your-api-key-here",
+        "MISTRAL_OCR_ALLOWED_DIR": "/absolute/path/to/allowed/directory"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+If you use the Codex CLI, you can add the server with:
+
+```bash
+codex mcp add mistral-ocr -- uvx mistral-ocr-mcp
+```
+
+Make sure the environment variables `MISTRAL_API_KEY` and `MISTRAL_OCR_ALLOWED_DIR` are set in your shell environment.
+
+---
+
+## Tool Reference
+
+### Tool 1: `extract_markdown`
+
+Extract markdown content from a document **without** saving images.
+
+**Arguments:**
+
+```json
+{
+  "file_path": "/absolute/path/to/document.pdf"
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | `string` | Yes | Absolute path to input file (PDF or image) |
+
+**Returns:**
+
+```json
+"# Document Title\n\nExtracted markdown content from all pages..."
+```
+
+Returns a single string containing concatenated markdown from all pages.
+
+**Example:**
+
+```json
+{
+  "tool": "extract_markdown",
+  "arguments": {
+    "file_path": "/Users/username/documents/report.pdf"
+  }
+}
+```
+
+---
+
+### Tool 2: `extract_markdown_with_images`
+
+Extract markdown content **and** save embedded images to disk.
+
+**Arguments:**
+
+```json
+{
+  "file_path": "/absolute/path/to/document.pdf",
+  "output_dir": "/absolute/path/to/output/parent"
+}
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | `string` | Yes | Absolute path to input file (PDF or image) |
+| `output_dir` | `string` | Yes | Absolute path to output parent directory (must exist and be writable, must be within `MISTRAL_OCR_ALLOWED_DIR`) |
+
+**Returns:**
+
+```json
+{
+  "output_directory": "/absolute/path/to/output/parent/document",
+  "markdown_file": "/absolute/path/to/output/parent/document/content.md",
+  "images": ["img_abc123.png", "img_def456.jpeg"]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `output_directory` | `string` | Absolute path to created subdirectory |
+| `markdown_file` | `string` | Absolute path to `content.md` file |
+| `images` | `array[string]` | List of saved image filenames (not full paths) |
+
+**Behavior:**
+
+1. Creates a subdirectory named after the input file stem (e.g., `report` for `report.pdf`)
+2. If the subdirectory already exists, appends a timestamp: `report_20260102_143022`
+3. Saves all extracted images as `<sanitized_id>.<ext>` (e.g., `img_abc123.png`)
+4. Saves markdown to `content.md` with relative image links (e.g., `![](./img_abc123.png)`)
+
+**Example:**
+
+```json
+{
+  "tool": "extract_markdown_with_images",
+  "arguments": {
+    "file_path": "/Users/username/documents/quarterly-report.pdf",
+    "output_dir": "/Users/username/workdir/extracted"
+  }
+}
+```
+
+**Output Structure:**
+
+```
+/Users/username/workdir/extracted/
+  quarterly-report/
+    content.md          # Markdown with relative image links
+    img_abc123.png      # First extracted image
+    img_def456.jpeg     # Second extracted image
+```
+
+---
+
+## Example Client Usage
+
+Here's a minimal Python example using the MCP SDK to call the tools:
+
+```python
+import asyncio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+async def extract_document():
+    server_params = StdioServerParameters(
+        command="mistral-ocr-mcp",
+        env={
+            "MISTRAL_API_KEY": "your-api-key",
+            "MISTRAL_OCR_ALLOWED_DIR": "/Users/username/workdir"
+        }
+    )
+    
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            
+            # Simple extraction
+            result = await session.call_tool(
+                "extract_markdown",
+                arguments={"file_path": "/path/to/document.pdf"}
+            )
+            print(result.content[0].text)
+            
+            # Extraction with images
+            result = await session.call_tool(
+                "extract_markdown_with_images",
+                arguments={
+                    "file_path": "/path/to/document.pdf",
+                    "output_dir": "/Users/username/workdir/output"
+                }
+            )
+            print(result.content[0].text)
+
+asyncio.run(extract_document())
+```
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Missing required environment variable: MISTRAL_API_KEY` | `MISTRAL_API_KEY` not set | Set the environment variable before running the server |
+| `Missing required environment variable: MISTRAL_OCR_ALLOWED_DIR` | `MISTRAL_OCR_ALLOWED_DIR` not set | Set the environment variable to an absolute path |
+| `MISTRAL_OCR_ALLOWED_DIR must be an absolute path` | Relative path provided (e.g., `~/documents`) | Use an absolute path (e.g., `/Users/username/documents`) |
+| `MISTRAL_OCR_ALLOWED_DIR does not exist` | Directory does not exist on filesystem | Create the directory first: `mkdir -p /path/to/dir` |
+| `MISTRAL_OCR_ALLOWED_DIR is not a directory` | Path points to a file, not a directory | Ensure the path is a directory |
+| `validate file_path: must be an absolute path: {path}` | Relative path provided for input file | Use an absolute path (e.g., `/Users/username/file.pdf`) |
+| `validate file_path: resolve failed, path does not exist: {path}` | Input file does not exist | Check the file path and ensure the file exists |
+| `validate file_path: unsupported file type '{suffix}'. Supported types: ...` | File extension not supported | Use `.pdf`, `.png`, `.jpg`, `.jpeg`, `.webp`, or `.gif` |
+| `validate output_dir: resolve failed, path does not exist: {path}` | Output directory does not exist | Create the directory first: `mkdir -p {path}` |
+| `validate output_dir: path is not a directory: {path}` | Path points to a file, not a directory | Ensure the path is a directory |
+| `validate output_dir: writability check failed, directory not writable: {path}` | Output directory exists but is not writable | Check directory permissions: `chmod u+w {path}` |
+| `output_dir must be within the allowed directory` | `output_dir` is outside `MISTRAL_OCR_ALLOWED_DIR` | Use a path within the allowed directory |
+| `Mistral OCR request failed (status=401): {message}` | Invalid API key | Check your `MISTRAL_API_KEY` |
+| `Mistral OCR request failed (status=429): {message}` | Rate limit exceeded | Wait and retry, or check your API quota |
+
+---
+
+## Development
+
+### Install Development Dependencies
+
+```bash
+pip install -e '.[dev]'
+```
+
+### Run Tests
+
+Run the full test suite:
+
+```bash
+pytest
+```
+
+Run tests with verbose output:
+
+```bash
+pytest -v
+```
+
+Run tests in quiet mode:
+
+```bash
+pytest -q
+```
+
+### Project Structure
+
+```
+mistral-ocr-multimedia-mcp/
+├── src/
+│   └── mistral_ocr_mcp/
+│       ├── __init__.py
+│       ├── __main__.py          # Entry point
+│       ├── server.py            # MCP server and tool definitions
+│       ├── config.py            # Configuration loading and validation
+│       ├── extraction.py        # OCR orchestration logic
+│       ├── mistral_client.py    # Mistral API client
+│       ├── images.py            # Image parsing and saving
+│       ├── markdown_rewrite.py  # Markdown link rewriting
+│       └── path_sandbox.py      # Path validation and sandbox enforcement
+├── tests/                       # Unit tests
+├── pyproject.toml              # Package configuration
+└── README.md                   # This file
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+---
+
+## Links
+
+- **GitHub Repository**: https://github.com/ORDIS-Co-Ltd/mistral-ocr-mcp
+- **MCP Specification**: https://modelcontextprotocol.io
+- **Mistral AI**: https://mistral.ai

mistral_ocr_mcp-0.1.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+mistral_ocr_mcp/__init__.py,sha256=UwK-luoFhJsyps4rpij6BGZiWyxMXX-AL2q_7tWLF5k,196
+mistral_ocr_mcp/__main__.py,sha256=pDlN6SI9E51xUGgrAy6pJC_F1vEqI3vjIvDIGFOBqZ0,696
+mistral_ocr_mcp/config.py,sha256=eHm-eQq2jIbuQoLDPUsi8llE0HKyd1v_rYGrknfiAhM,2658
+mistral_ocr_mcp/extraction.py,sha256=wbRqjMGY86CiDPqEKYMP1rRYMJsxUDXG_PNBx9PeYRk,5408
+mistral_ocr_mcp/images.py,sha256=aIb3k8bNDtdPZ0zg19YJzB_aLWrb0pCw4UOJdYa8Xxk,5357
+mistral_ocr_mcp/markdown_rewrite.py,sha256=ktLnqEo1zwmMBE89N6VI557hAEsknANBC2sSs_ArauI,4245
+mistral_ocr_mcp/mistral_client.py,sha256=aCo6HjmibTuID3itHqGdVfxBpie9kMteVx3GsS6l3SY,4223
+mistral_ocr_mcp/path_sandbox.py,sha256=Xi5CuyTQvZ0L_9woTvkmttsbzdz6Sd8oRnlwjX79Eag,4377
+mistral_ocr_mcp/server.py,sha256=425FeAvFNLRGDXZm7a4g5ADQpMWNSp1_EWkrXlPJnO0,2585
+mistral_ocr_mcp-0.1.3.dist-info/METADATA,sha256=n8qinc4uKnB39GbH8XVpdKR0GNVQcqO4aYm9qyPD2tY,12059
+mistral_ocr_mcp-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mistral_ocr_mcp-0.1.3.dist-info/entry_points.txt,sha256=J-qJQ5P8-pJ6a8W7KXaesUuMFU3rFgYNyAsMCanQoqs,66
+mistral_ocr_mcp-0.1.3.dist-info/RECORD,,

mistral_ocr_mcp-0.1.3.dist-info/WHEEL

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

mistral_ocr_mcp-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mistral-ocr-mcp = mistral_ocr_mcp.__main__:main