feat: Add text processing background worker for telling client about progress

nextcloud_mcp_server/app.py

@@ -72,6 +72,7 @@ def initialize_document_processors():
                 timeout=unst_config["timeout"],
                 default_strategy=unst_config["strategy"],
                 default_languages=unst_config["languages"],
+                progress_interval=unst_config.get("progress_interval", 10),
             )
             registry.register(processor, priority=10)
             logger.info(f"Registered Unstructured processor: {unst_config['api_url']}")

nextcloud_mcp_server/config.py

@@ -90,6 +90,7 @@ def get_document_processor_config() -> dict[str, Any]:
                 for lang in os.getenv("UNSTRUCTURED_LANGUAGES", "eng,deu").split(",")
                 if lang.strip()
             ],
+            "progress_interval": int(os.getenv("PROGRESS_INTERVAL", "10")),
         }
 
     # Tesseract configuration

nextcloud_mcp_server/document_processors/base.py

@@ -1,6 +1,7 @@
 """Abstract base class for document processing plugins."""
 
 from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
 from typing import Any, Optional
 
 from pydantic import BaseModel
@@ -71,6 +72,9 @@ class DocumentProcessor(ABC):
         content_type: str,
         filename: Optional[str] = None,
         options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
     ) -> ProcessingResult:
         """Process a document and extract text.
 
@@ -79,6 +83,11 @@ class DocumentProcessor(ABC):
             content_type: MIME type of the document
             filename: Optional filename for format detection
             options: Processor-specific options (e.g., OCR language, strategy)
+            progress_callback: Optional async callback for progress updates.
+                Called as: await progress_callback(progress, total, message)
+                - progress: Current progress value (monotonically increasing)
+                - total: Optional total value (None if unknown)
+                - message: Optional human-readable status message
 
         Returns:
             ProcessingResult with extracted text and metadata

nextcloud_mcp_server/document_processors/custom_http.py

@@ -1,6 +1,7 @@
 """Generic HTTP API processor wrapper for custom document processing services."""
 
 import logging
+from collections.abc import Awaitable, Callable
 from typing import Any, Optional
 
 import httpx
@@ -70,6 +71,9 @@ class CustomHTTPProcessor(DocumentProcessor):
         content_type: str,
         filename: Optional[str] = None,
         options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
     ) -> ProcessingResult:
         """Process via custom HTTP API.
 

nextcloud_mcp_server/document_processors/registry.py

@@ -1,6 +1,7 @@
 """Central registry for document processors."""
 
 import logging
+from collections.abc import Awaitable, Callable
 from typing import Any, Optional
 
 from .base import DocumentProcessor, ProcessingResult, ProcessorError
@@ -113,6 +114,9 @@ class ProcessorRegistry:
         filename: Optional[str] = None,
         processor_name: Optional[str] = None,
         options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
     ) -> ProcessingResult:
         """Process a document using available processors.
 
@@ -122,6 +126,7 @@ class ProcessorRegistry:
             filename: Optional filename for format detection
             processor_name: Force specific processor (or None for auto-select)
             options: Processing options passed to processor
+            progress_callback: Optional async callback for progress updates
 
         Returns:
             ProcessingResult with extracted text and metadata
@@ -148,7 +153,9 @@ class ProcessorRegistry:
         logger.info(f"Processing with '{processor.name}' processor")
 
         # Process
-        return await processor.process(content, content_type, filename, options)
+        return await processor.process(
+            content, content_type, filename, options, progress_callback
+        )
 
 
 # Global registry instance

nextcloud_mcp_server/document_processors/tesseract.py

@@ -2,6 +2,7 @@
 
 import logging
 import shutil
+from collections.abc import Awaitable, Callable
 from typing import Any, Optional
 
 from .base import DocumentProcessor, ProcessingResult, ProcessorError
@@ -86,6 +87,9 @@ class TesseractProcessor(DocumentProcessor):
         content_type: str,
         filename: Optional[str] = None,
         options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
     ) -> ProcessingResult:
         """Process image via Tesseract OCR.
 

nextcloud_mcp_server/document_processors/unstructured.py

@@ -2,8 +2,11 @@
 
 import io
 import logging
+import time
+from collections.abc import Awaitable, Callable
 from typing import Any, Optional
 
+import anyio
 import httpx
 
 from .base import DocumentProcessor, ProcessingResult, ProcessorError
@@ -47,6 +50,7 @@ class UnstructuredProcessor(DocumentProcessor):
         timeout: int = 120,
         default_strategy: str = "auto",
         default_languages: Optional[list[str]] = None,
+        progress_interval: int = 10,
     ):
         """Initialize Unstructured processor.
 
@@ -55,15 +59,18 @@ class UnstructuredProcessor(DocumentProcessor):
             timeout: Request timeout in seconds (default: 120)
             default_strategy: Default parsing strategy - "auto", "fast", or "hi_res"
             default_languages: Default OCR language codes (e.g., ["eng", "deu"])
+            progress_interval: Seconds between progress updates (default: 10)
         """
         self.api_url = api_url
         self.timeout = timeout
         self.default_strategy = default_strategy
         self.default_languages = default_languages or ["eng"]
+        self.progress_interval = progress_interval
 
         logger.info(
             f"Initialized UnstructuredProcessor: {api_url}, "
-            f"strategy={default_strategy}, languages={self.default_languages}"
+            f"strategy={default_strategy}, languages={self.default_languages}, "
+            f"progress_interval={progress_interval}s"
         )
 
     @property
@@ -74,23 +81,65 @@ class UnstructuredProcessor(DocumentProcessor):
     def supported_mime_types(self) -> set[str]:
         return self.SUPPORTED_TYPES
 
-    async def process(
+    async def _run_progress_poller(
+        self,
+        stop_event: anyio.Event,
+        progress_callback: Callable[
+            [float, Optional[float], Optional[str]], Awaitable[None]
+        ],
+        start_time: float,
+    ):
+        """Run progress poller that reports status every N seconds.
+
+        Args:
+            stop_event: Event to signal when processing is complete
+            progress_callback: Async callback to report progress
+            start_time: Time when processing started (from time.time())
+        """
+        logger.debug("Starting progress poller")
+        while not stop_event.is_set():
+            try:
+                # Wait for the event to be set, with a timeout equal to progress_interval
+                with anyio.fail_after(self.progress_interval):
+                    await stop_event.wait()
+                # If wait() finished, the event was set (processing complete)
+                break
+            except TimeoutError:
+                # Timeout occurred - time to send a progress update
+                if not stop_event.is_set():  # Double-check in case of race condition
+                    elapsed = int(time.time() - start_time)
+                    message = (
+                        f"Processing document with unstructured... ({elapsed}s elapsed)"
+                    )
+                    try:
+                        await progress_callback(
+                            progress=float(elapsed),
+                            total=None,  # Unknown total duration
+                            message=message,
+                        )
+                        logger.debug(f"Progress update sent: {elapsed}s elapsed")
+                    except Exception as e:
+                        logger.warning(f"Failed to send progress update: {e}")
+        logger.debug("Progress poller stopped")
+
+    async def _make_api_request(
         self,
         content: bytes,
         content_type: str,
-        filename: Optional[str] = None,
-        options: Optional[dict[str, Any]] = None,
+        filename: Optional[str],
+        strategy: str,
+        languages: list[str],
+        extract_image_block_types: Optional[list[str]],
     ) -> ProcessingResult:
-        """Process document via Unstructured API.
+        """Make the actual API request to Unstructured.
 
         Args:
             content: Document bytes
             content_type: MIME type
-            filename: Optional filename for format detection
-            options: Processing options:
-                - strategy: "auto", "fast", or "hi_res" (default: from init)
-                - languages: List of language codes (default: from init)
-                - extract_image_block_types: Types of image elements to extract
+            filename: Optional filename
+            strategy: Processing strategy
+            languages: OCR languages
+            extract_image_block_types: Image element types to extract
 
         Returns:
             ProcessingResult with extracted text and metadata
@@ -98,13 +147,6 @@ class UnstructuredProcessor(DocumentProcessor):
         Raises:
             ProcessorError: If processing fails
         """
-        options = options or {}
-
-        # Extract options with defaults
-        strategy = options.get("strategy", self.default_strategy)
-        languages = options.get("languages", self.default_languages)
-        extract_image_block_types = options.get("extract_image_block_types")
-
         # Prepare multipart request
         files = {
             "files": (
@@ -178,6 +220,81 @@ class UnstructuredProcessor(DocumentProcessor):
             logger.error(f"Unstructured API processing failed: {e}")
             raise ProcessorError(f"Processing failed: {str(e)}") from e
 
+    async def process(
+        self,
+        content: bytes,
+        content_type: str,
+        filename: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        progress_callback: Optional[
+            Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+        ] = None,
+    ) -> ProcessingResult:
+        """Process document via Unstructured API.
+
+        Args:
+            content: Document bytes
+            content_type: MIME type
+            filename: Optional filename for format detection
+            options: Processing options:
+                - strategy: "auto", "fast", or "hi_res" (default: from init)
+                - languages: List of language codes (default: from init)
+                - extract_image_block_types: Types of image elements to extract
+            progress_callback: Optional async callback for progress updates
+
+        Returns:
+            ProcessingResult with extracted text and metadata
+
+        Raises:
+            ProcessorError: If processing fails
+        """
+        options = options or {}
+
+        # Extract options with defaults
+        strategy = options.get("strategy", self.default_strategy)
+        languages = options.get("languages", self.default_languages)
+        extract_image_block_types = options.get("extract_image_block_types")
+
+        # If no progress callback, just make the request directly
+        if progress_callback is None:
+            return await self._make_api_request(
+                content=content,
+                content_type=content_type,
+                filename=filename,
+                strategy=strategy,
+                languages=languages,
+                extract_image_block_types=extract_image_block_types,
+            )
+
+        # With progress callback: run API request + progress poller concurrently
+        stop_event = anyio.Event()
+        start_time = time.time()
+        result = None
+
+        async def capture_result():
+            nonlocal result
+            try:
+                result = await self._make_api_request(
+                    content=content,
+                    content_type=content_type,
+                    filename=filename,
+                    strategy=strategy,
+                    languages=languages,
+                    extract_image_block_types=extract_image_block_types,
+                )
+            finally:
+                # Signal poller to stop after API request completes
+                stop_event.set()
+
+        # Run both tasks concurrently using anyio task groups
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(capture_result)
+            tg.start_soon(
+                self._run_progress_poller, stop_event, progress_callback, start_time
+            )
+
+        return result
+
     async def health_check(self) -> bool:
         """Check if Unstructured API is available.
 

nextcloud_mcp_server/server/webdav.py

@@ -85,7 +85,10 @@ def configure_webdav_tools(mcp: FastMCP):
             try:
                 logger.info(f"Parsing document '{path}' of type '{content_type}'")
                 parsed_text, metadata = await parse_document(
-                    content, content_type, filename=path
+                    content,
+                    content_type,
+                    filename=path,
+                    progress_callback=ctx.report_progress,
                 )
                 return {
                     "path": path,

nextcloud_mcp_server/utils/document_parser.py

@@ -2,6 +2,7 @@
 
 import base64
 import logging
+from collections.abc import Awaitable, Callable
 from typing import Optional, Tuple
 
 from nextcloud_mcp_server.config import get_document_processor_config
@@ -35,7 +36,12 @@ def is_parseable_document(content_type: Optional[str]) -> bool:
 
 
 async def parse_document(
-    content: bytes, content_type: Optional[str], filename: Optional[str] = None
+    content: bytes,
+    content_type: Optional[str],
+    filename: Optional[str] = None,
+    progress_callback: Optional[
+        Callable[[float, Optional[float], Optional[str]], Awaitable[None]]
+    ] = None,
 ) -> Tuple[str, dict]:
     """Parse a document using registered processors.
 
@@ -46,6 +52,7 @@ async def parse_document(
         content: The document content as bytes
         content_type: The MIME type of the document
         filename: Optional filename to help with format detection
+        progress_callback: Optional async callback for progress updates during long operations
 
     Returns:
         Tuple of (parsed_text, metadata) where:
@@ -73,6 +80,7 @@ async def parse_document(
             content=content,
             content_type=content_type,
             filename=filename,
+            progress_callback=progress_callback,
         )
 
         logger.info(f"Successfully parsed document with '{result.processor}' processor")