rossum-mcp 0.3.4__py3-none-any.whl → 0.3.5__py3-none-any.whl

rossum_mcp/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.3.4"
+__version__ = "0.3.5"

rossum_mcp/server.py

@@ -18,6 +18,7 @@ from rossum_mcp.logging_config import setup_logging
 from rossum_mcp.tools import (
     register_annotation_tools,
     register_document_relation_tools,
+    register_email_template_tools,
     register_engine_tools,
     register_hook_tools,
     register_queue_tools,
@@ -49,6 +50,7 @@ register_queue_tools(mcp, client)
 register_schema_tools(mcp, client)
 register_engine_tools(mcp, client)
 register_hook_tools(mcp, client)
+register_email_template_tools(mcp, client)
 register_document_relation_tools(mcp, client)
 register_relation_tools(mcp, client)
 register_rule_tools(mcp, client)

rossum_mcp/tools/__init__.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from rossum_mcp.tools.annotations import register_annotation_tools
 from rossum_mcp.tools.document_relations import register_document_relation_tools
+from rossum_mcp.tools.email_templates import register_email_template_tools
 from rossum_mcp.tools.engines import register_engine_tools
 from rossum_mcp.tools.hooks import register_hook_tools
 from rossum_mcp.tools.queues import register_queue_tools
@@ -16,6 +17,7 @@ from rossum_mcp.tools.workspaces import register_workspace_tools
 __all__ = [
     "register_annotation_tools",
     "register_document_relation_tools",
+    "register_email_template_tools",
     "register_engine_tools",
     "register_hook_tools",
     "register_queue_tools",

rossum_mcp/tools/annotations.py

@@ -7,7 +7,7 @@ from collections.abc import Sequence  # noqa: TC003 - needed at runtime for Fast
 from pathlib import Path
 from typing import TYPE_CHECKING, Literal
 
-from rossum_api.models.annotation import Annotation  # noqa: TC002 - needed at runtime for FastMCP
+from rossum_api.models.annotation import Annotation
 
 from rossum_mcp.tools.base import is_read_write_mode
 
@@ -17,114 +17,151 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-# Fixed sideloads (critical for well-behaving agent)
 type Sideload = Literal["content", "document", "automation_blocker"]
 
 
-def register_annotation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:  # noqa: C901
+async def _upload_document(client: AsyncRossumAPIClient, file_path: str, queue_id: int) -> dict:
+    if not is_read_write_mode():
+        return {"error": "upload_document is not available in read-only mode"}
+
+    path = Path(file_path)
+    if not path.exists():
+        logger.error(f"File not found: {file_path}")
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    try:
+        task = (await client.upload_document(queue_id, [(str(path), path.name)]))[0]
+    except KeyError as e:
+        logger.error(f"Upload failed - unexpected API response format: {e!s}")
+        error_msg = (
+            f"Document upload failed - API response missing expected key {e!s}. "
+            f"This usually means either:\n"
+            f"1. The queue_id ({queue_id}) is invalid or you don't have access to it\n"
+            f"2. The Rossum API returned an error response\n"
+            f"Please verify:\n"
+            f"- The queue_id is correct and exists in your workspace\n"
+            f"- You have permission to upload documents to this queue\n"
+            f"- Your API token has the necessary permissions"
+        )
+        raise ValueError(error_msg) from e
+    except IndexError as e:
+        logger.error(f"Upload failed - no tasks returned: {e}")
+        raise ValueError(
+            f"Document upload failed - no tasks were created. This may indicate the queue_id ({queue_id}) is invalid."
+        ) from e
+    except Exception as e:
+        logger.error(f"Upload failed: {type(e).__name__}: {e}")
+        raise ValueError(f"Document upload failed: {type(e).__name__}: {e!s}") from e
+
+    return {
+        "task_id": task.id,
+        "task_status": task.status,
+        "queue_id": queue_id,
+        "message": "Document upload initiated. Use `list_annotations` to find the annotation ID for this queue.",
+    }
+
+
+async def _get_annotation(
+    client: AsyncRossumAPIClient, annotation_id: int, sideloads: Sequence[Sideload] = ()
+) -> Annotation:
+    logger.debug(f"Retrieving annotation: annotation_id={annotation_id}")
+    annotation: Annotation = await client.retrieve_annotation(annotation_id, sideloads)  # type: ignore[arg-type]
+    return annotation
+
+
+async def _list_annotations(
+    client: AsyncRossumAPIClient,
+    queue_id: int,
+    status: str | None = "importing,to_review,confirmed,exported",
+    ordering: Sequence[str] = (),
+    first_n: int | None = None,
+) -> list[Annotation]:
+    logger.debug(f"Listing annotations: queue_id={queue_id}, status={status}, ordering={ordering}, first_n={first_n}")
+    params: dict = {"queue": queue_id, "page_size": 100}
+    if status:
+        params["status"] = status
+    if ordering:
+        params["ordering"] = ordering
+
+    annotations_list: list[Annotation] = []
+    async for item in client.list_annotations(**params):
+        annotations_list.append(item)
+        if first_n is not None and len(annotations_list) >= first_n:
+            break
+    return annotations_list
+
+
+async def _start_annotation(client: AsyncRossumAPIClient, annotation_id: int) -> dict:
+    if not is_read_write_mode():
+        return {"error": "start_annotation is not available in read-only mode"}
+
+    logger.debug(f"Starting annotation: annotation_id={annotation_id}")
+    await client.start_annotation(annotation_id)
+    return {
+        "annotation_id": annotation_id,
+        "message": f"Annotation {annotation_id} started successfully. Status changed to 'reviewing'.",
+    }
+
+
+async def _bulk_update_annotation_fields(
+    client: AsyncRossumAPIClient, annotation_id: int, operations: list[dict]
+) -> dict:
+    if not is_read_write_mode():
+        return {"error": "bulk_update_annotation_fields is not available in read-only mode"}
+
+    logger.debug(f"Bulk updating annotation: annotation_id={annotation_id}, ops={operations}")
+    await client.bulk_update_annotation_data(annotation_id, operations)
+    return {
+        "annotation_id": annotation_id,
+        "operations_count": len(operations),
+        "message": f"Annotation {annotation_id} updated with {len(operations)} operations successfully.",
+    }
+
+
+async def _confirm_annotation(client: AsyncRossumAPIClient, annotation_id: int) -> dict:
+    if not is_read_write_mode():
+        return {"error": "confirm_annotation is not available in read-only mode"}
+
+    logger.debug(f"Confirming annotation: annotation_id={annotation_id}")
+    await client.confirm_annotation(annotation_id)
+    return {
+        "annotation_id": annotation_id,
+        "message": f"Annotation {annotation_id} confirmed successfully. Status changed to 'confirmed'.",
+    }
+
+
+def register_annotation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register annotation-related tools with the FastMCP server."""
 
     @mcp.tool(description="Upload a document to Rossum. Use list_annotations to get annotation ID.")
     async def upload_document(file_path: str, queue_id: int) -> dict:
-        """Upload a document to Rossum."""
-        if not is_read_write_mode():
-            return {"error": "upload_document is not available in read-only mode"}
-
-        path = Path(file_path)
-        if not path.exists():
-            logger.error(f"File not found: {file_path}")
-            raise FileNotFoundError(f"File not found: {file_path}")
-
-        try:
-            task = (await client.upload_document(queue_id, [(str(path), path.name)]))[0]
-        except KeyError as e:
-            logger.error(f"Upload failed - unexpected API response format: {e!s}")
-            error_msg = (
-                f"Document upload failed - API response missing expected key {e!s}. "
-                f"This usually means either:\n"
-                f"1. The queue_id ({queue_id}) is invalid or you don't have access to it\n"
-                f"2. The Rossum API returned an error response\n"
-                f"Please verify:\n"
-                f"- The queue_id is correct and exists in your workspace\n"
-                f"- You have permission to upload documents to this queue\n"
-                f"- Your API token has the necessary permissions"
-            )
-            raise ValueError(error_msg) from e
-        except IndexError as e:
-            logger.error(f"Upload failed - no tasks returned: {e}")
-            raise ValueError(
-                f"Document upload failed - no tasks were created. This may indicate the queue_id ({queue_id}) is invalid."
-            ) from e
-        except Exception as e:
-            logger.error(f"Upload failed: {type(e).__name__}: {e}")
-            raise ValueError(f"Document upload failed: {type(e).__name__}: {e!s}") from e
-
-        return {
-            "task_id": task.id,
-            "task_status": task.status,
-            "queue_id": queue_id,
-            "message": "Document upload initiated. Use `list_annotations` to find the annotation ID for this queue.",
-        }
+        return await _upload_document(client, file_path, queue_id)
 
     @mcp.tool(description="Retrieve annotation data. Use 'content' sideload to get extracted data.")
     async def get_annotation(annotation_id: int, sideloads: Sequence[Sideload] = ()) -> Annotation:
-        """Retrieve annotation data from Rossum."""
-        logger.debug(f"Retrieving annotation: annotation_id={annotation_id}")
-        annotation: Annotation = await client.retrieve_annotation(annotation_id, sideloads)  # type: ignore[arg-type]
-        return annotation
+        return await _get_annotation(client, annotation_id, sideloads)
 
-    @mcp.tool(description="List annotations for a queue.")
+    @mcp.tool(description="List annotations for a queue. Use ordering=['-created_at'] to sort by newest first.")
     async def list_annotations(
-        queue_id: int, status: str | None = "importing,to_review,confirmed,exported"
+        queue_id: int,
+        status: str | None = "importing,to_review,confirmed,exported",
+        ordering: Sequence[str] = (),
+        first_n: int | None = None,
     ) -> list[Annotation]:
-        """List annotations for a queue with optional filtering."""
-        logger.debug(f"Listing annotations: queue_id={queue_id}, status={status}")
-        params: dict = {"queue": queue_id, "page_size": 100}
-        if status:
-            params["status"] = status
-        annotations_list: list[Annotation] = [item async for item in client.list_annotations(**params)]
-        return annotations_list
+        return await _list_annotations(client, queue_id, status, ordering, first_n)
 
     @mcp.tool(description="Start annotation (move from 'to_review' to 'reviewing').")
     async def start_annotation(annotation_id: int) -> dict:
-        """Start annotation to move it to 'reviewing' status."""
-        if not is_read_write_mode():
-            return {"error": "start_annotation is not available in read-only mode"}
-
-        logger.debug(f"Starting annotation: annotation_id={annotation_id}")
-        await client.start_annotation(annotation_id)
-        return {
-            "annotation_id": annotation_id,
-            "message": f"Annotation {annotation_id} started successfully. Status changed to 'reviewing'.",
-        }
+        return await _start_annotation(client, annotation_id)
 
     @mcp.tool(
         description="Bulk update annotation fields. It can be used after `start_annotation` only. Use datapoint ID from content, NOT schema_id."
     )
     async def bulk_update_annotation_fields(annotation_id: int, operations: list[dict]) -> dict:
-        """Bulk update annotation field values using operations."""
-        if not is_read_write_mode():
-            return {"error": "bulk_update_annotation_fields is not available in read-only mode"}
-
-        logger.debug(f"Bulk updating annotation: annotation_id={annotation_id}, ops={operations}")
-        await client.bulk_update_annotation_data(annotation_id, operations)
-        return {
-            "annotation_id": annotation_id,
-            "operations_count": len(operations),
-            "message": f"Annotation {annotation_id} updated with {len(operations)} operations successfully.",
-        }
+        return await _bulk_update_annotation_fields(client, annotation_id, operations)
 
     @mcp.tool(
         description="Confirm annotation (move to 'confirmed'). It can be used after `bulk_update_annotation_fields`."
     )
     async def confirm_annotation(annotation_id: int) -> dict:
-        """Confirm annotation to move it to 'confirmed' status."""
-        if not is_read_write_mode():
-            return {"error": "confirm_annotation is not available in read-only mode"}
-
-        logger.debug(f"Confirming annotation: annotation_id={annotation_id}")
-        await client.confirm_annotation(annotation_id)
-        return {
-            "annotation_id": annotation_id,
-            "message": f"Annotation {annotation_id} confirmed successfully. Status changed to 'confirmed'.",
-        }
+        return await _confirm_annotation(client, annotation_id)

rossum_mcp/tools/base.py

@@ -3,10 +3,17 @@
 from __future__ import annotations
 
 import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
 
 BASE_URL = os.environ.get("ROSSUM_API_BASE_URL", "").rstrip("/")
 MODE = os.environ.get("ROSSUM_MCP_MODE", "read-write").lower()
 
+# Marker used to indicate omitted fields in list responses
+TRUNCATED_MARKER = "<omitted>"
+
 
 def build_resource_url(resource_type: str, resource_id: int) -> str:
     """Build a full URL for a Rossum API resource."""
@@ -16,3 +23,18 @@ def build_resource_url(resource_type: str, resource_id: int) -> str:
 def is_read_write_mode() -> bool:
     """Check if server is in read-write mode."""
     return MODE == "read-write"
+
+
+def truncate_dict_fields(data: dict[str, Any], fields: tuple[str, ...]) -> dict[str, Any]:
+    """Truncate specified fields in a dictionary to save context.
+
+    Returns a new dictionary with specified fields replaced by TRUNCATED_MARKER.
+    """
+    if not data:
+        return data
+
+    result = dict(data)
+    for field in fields:
+        if field in result:
+            result[field] = TRUNCATED_MARKER
+    return result

rossum_mcp/tools/document_relations.py

@@ -5,9 +5,7 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING
 
-from rossum_api.models.document_relation import (
-    DocumentRelation,  # noqa: TC002 - needed at runtime for FastMCP
-)
+from rossum_api.models.document_relation import DocumentRelation
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP

rossum_mcp/tools/email_templates.py

@@ -0,0 +1,131 @@
+"""Email template tools for Rossum MCP Server."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Literal
+
+from rossum_api.models.email_template import EmailTemplate
+
+from rossum_mcp.tools.base import is_read_write_mode
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+logger = logging.getLogger(__name__)
+
+EmailTemplateType = Literal["rejection", "rejection_default", "email_with_no_processable_attachments", "custom"]
+
+
+async def _get_email_template(client: AsyncRossumAPIClient, email_template_id: int) -> EmailTemplate:
+    email_template: EmailTemplate = await client.retrieve_email_template(email_template_id)
+    return email_template
+
+
+async def _list_email_templates(
+    client: AsyncRossumAPIClient,
+    queue_id: int | None = None,
+    type: EmailTemplateType | None = None,
+    name: str | None = None,
+    first_n: int | None = None,
+) -> list[EmailTemplate]:
+    filters: dict = {}
+    if queue_id is not None:
+        filters["queue"] = queue_id
+    if type is not None:
+        filters["type"] = type
+    if name is not None:
+        filters["name"] = name
+
+    if first_n is not None:
+        templates_iter = client.list_email_templates(**filters)
+        templates_list: list[EmailTemplate] = []
+        n = 0
+        while n < first_n:
+            templates_list.append(await anext(templates_iter))
+            n += 1
+    else:
+        templates_list = [template async for template in client.list_email_templates(**filters)]
+
+    return templates_list
+
+
+async def _create_email_template(
+    client: AsyncRossumAPIClient,
+    name: str,
+    queue: str,
+    subject: str,
+    message: str,
+    type: EmailTemplateType = "custom",
+    automate: bool = False,
+    to: list[dict[str, Any]] | None = None,
+    cc: list[dict[str, Any]] | None = None,
+    bcc: list[dict[str, Any]] | None = None,
+    triggers: list[str] | None = None,
+) -> EmailTemplate | dict:
+    if not is_read_write_mode():
+        return {"error": "create_email_template is not available in read-only mode"}
+
+    logger.debug(f"Creating email template: name={name}, queue={queue}, type={type}")
+
+    template_data: dict[str, Any] = {
+        "name": name,
+        "queue": queue,
+        "subject": subject,
+        "message": message,
+        "type": type,
+        "automate": automate,
+    }
+
+    if to is not None:
+        template_data["to"] = to
+    if cc is not None:
+        template_data["cc"] = cc
+    if bcc is not None:
+        template_data["bcc"] = bcc
+    if triggers is not None:
+        template_data["triggers"] = triggers
+
+    email_template: EmailTemplate = await client.create_new_email_template(template_data)
+    return email_template
+
+
+def register_email_template_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
+    """Register email template-related tools with the FastMCP server."""
+
+    @mcp.tool(
+        description="Retrieve a single email template by ID. Use list_email_templates first to find templates for a queue."
+    )
+    async def get_email_template(email_template_id: int) -> EmailTemplate:
+        return await _get_email_template(client, email_template_id)
+
+    @mcp.tool(
+        description="List all email templates with optional filtering. Email templates define automated or manual email responses sent from Rossum queues. Types: 'rejection' (for rejecting documents), 'rejection_default' (default rejection template), 'email_with_no_processable_attachments' (when email has no valid attachments), 'custom' (user-defined templates)."
+    )
+    async def list_email_templates(
+        queue_id: int | None = None,
+        type: EmailTemplateType | None = None,
+        name: str | None = None,
+        first_n: int | None = None,
+    ) -> list[EmailTemplate]:
+        return await _list_email_templates(client, queue_id, type, name, first_n)
+
+    @mcp.tool(
+        description="Create a new email template. Email templates can be automated (automate=True) to send emails automatically on specific triggers, or manual for user-initiated sending. The 'to', 'cc', and 'bcc' fields accept lists of recipient objects with 'type' ('annotator', 'constant', 'datapoint') and 'value' keys."
+    )
+    async def create_email_template(
+        name: str,
+        queue: str,
+        subject: str,
+        message: str,
+        type: EmailTemplateType = "custom",
+        automate: bool = False,
+        to: list[dict[str, Any]] | None = None,
+        cc: list[dict[str, Any]] | None = None,
+        bcc: list[dict[str, Any]] | None = None,
+        triggers: list[str] | None = None,
+    ) -> EmailTemplate | dict:
+        return await _create_email_template(
+            client, name, queue, subject, message, type, automate, to, cc, bcc, triggers
+        )