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

rossum_mcp/__init__.py

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

rossum_mcp/server.py

@@ -17,7 +17,9 @@ from rossum_api.dtos import Token
 from rossum_mcp.logging_config import setup_logging
 from rossum_mcp.tools import (
     register_annotation_tools,
+    register_discovery_tools,
     register_document_relation_tools,
+    register_email_template_tools,
     register_engine_tools,
     register_hook_tools,
     register_queue_tools,
@@ -44,11 +46,13 @@ logger.info(f"Rossum MCP Server starting in {MODE} mode")
 mcp = FastMCP("rossum-mcp-server")
 client = AsyncRossumAPIClient(base_url=BASE_URL, credentials=Token(token=API_TOKEN))
 
+register_discovery_tools(mcp)
 register_annotation_tools(mcp, client)
 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

@@ -3,7 +3,15 @@
 from __future__ import annotations
 
 from rossum_mcp.tools.annotations import register_annotation_tools
+from rossum_mcp.tools.catalog import (
+    TOOL_CATALOG,
+    ToolCategory,
+    ToolInfo,
+    get_catalog_summary,
+)
+from rossum_mcp.tools.discovery import register_discovery_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
@@ -14,8 +22,14 @@ from rossum_mcp.tools.users import register_user_tools
 from rossum_mcp.tools.workspaces import register_workspace_tools
 
 __all__ = [
+    "TOOL_CATALOG",
+    "ToolCategory",
+    "ToolInfo",
+    "get_catalog_summary",
     "register_annotation_tools",
+    "register_discovery_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/catalog.py

@@ -0,0 +1,169 @@
+"""Tool catalog for dynamic tool discovery.
+
+Provides lightweight metadata for all MCP tools organized by category.
+This is the single source of truth for tool categorization - the agent
+fetches this catalog from MCP to avoid data duplication.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ToolInfo:
+    """Lightweight tool metadata for catalog."""
+
+    name: str
+    description: str
+
+
+@dataclass
+class ToolCategory:
+    """A category of related tools."""
+
+    name: str
+    description: str
+    tools: list[ToolInfo]
+    keywords: list[str]
+
+
+# Tool catalog organized by functional category
+# Keywords enable automatic pre-loading based on user request text
+TOOL_CATALOG: dict[str, ToolCategory] = {
+    "annotations": ToolCategory(
+        name="annotations",
+        description="Document processing: upload, retrieve, update, and confirm annotations",
+        tools=[
+            ToolInfo("upload_document", "Upload document to queue"),
+            ToolInfo("get_annotation", "Retrieve annotation with extracted data"),
+            ToolInfo("list_annotations", "List annotations for a queue"),
+            ToolInfo("start_annotation", "Start annotation (to_review -> reviewing)"),
+            ToolInfo("bulk_update_annotation_fields", "Bulk update annotation fields"),
+            ToolInfo("confirm_annotation", "Confirm annotation (-> confirmed)"),
+        ],
+        keywords=["annotation", "document", "upload", "extract", "confirm", "review"],
+    ),
+    "queues": ToolCategory(
+        name="queues",
+        description="Queue management: create, configure, and list document processing queues",
+        tools=[
+            ToolInfo("get_queue", "Retrieve queue details"),
+            ToolInfo("list_queues", "List all queues"),
+            ToolInfo("get_queue_schema", "Get queue's schema"),
+            ToolInfo("get_queue_engine", "Get queue's AI engine"),
+            ToolInfo("create_queue", "Create a queue"),
+            ToolInfo("update_queue", "Update queue settings"),
+            ToolInfo("get_queue_template_names", "List available queue templates"),
+            ToolInfo("create_queue_from_template", "Create queue from template"),
+        ],
+        keywords=["queue", "inbox", "connector"],
+    ),
+    "schemas": ToolCategory(
+        name="schemas",
+        description="Schema management: define and modify document field structures",
+        tools=[
+            ToolInfo("get_schema", "Retrieve schema details"),
+            ToolInfo("list_schemas", "List all schemas"),
+            ToolInfo("update_schema", "Update schema"),
+            ToolInfo("create_schema", "Create new schema"),
+            ToolInfo("patch_schema", "Add/update/remove schema fields"),
+            ToolInfo("get_schema_tree_structure", "Get lightweight schema tree"),
+            ToolInfo("prune_schema_fields", "Bulk remove schema fields"),
+        ],
+        keywords=["schema", "field", "datapoint", "section", "multivalue", "tuple"],
+    ),
+    "engines": ToolCategory(
+        name="engines",
+        description="AI engine management: create and configure extraction/splitting engines",
+        tools=[
+            ToolInfo("get_engine", "Retrieve engine details"),
+            ToolInfo("list_engines", "List all engines"),
+            ToolInfo("update_engine", "Update engine settings"),
+            ToolInfo("create_engine", "Create new engine"),
+            ToolInfo("create_engine_field", "Create engine field mapping"),
+            ToolInfo("get_engine_fields", "List engine fields"),
+        ],
+        keywords=["engine", "ai", "extractor", "splitter", "training"],
+    ),
+    "hooks": ToolCategory(
+        name="hooks",
+        description="Extensions/webhooks: create and manage automation hooks",
+        tools=[
+            ToolInfo("get_hook", "Retrieve hook details with code"),
+            ToolInfo("list_hooks", "List all hooks for a queue"),
+            ToolInfo("create_hook", "Create new hook"),
+            ToolInfo("update_hook", "Update hook configuration"),
+            ToolInfo("list_hook_logs", "View hook execution logs"),
+            ToolInfo("list_hook_templates", "List Rossum Store templates"),
+            ToolInfo("create_hook_from_template", "Create hook from template"),
+        ],
+        keywords=["hook", "extension", "webhook", "automation", "function", "serverless"],
+    ),
+    "email_templates": ToolCategory(
+        name="email_templates",
+        description="Email templates: configure automated email responses",
+        tools=[
+            ToolInfo("get_email_template", "Retrieve email template"),
+            ToolInfo("list_email_templates", "List email templates"),
+            ToolInfo("create_email_template", "Create email template"),
+        ],
+        keywords=["email", "template", "notification", "rejection"],
+    ),
+    "document_relations": ToolCategory(
+        name="document_relations",
+        description="Document relations: manage export/einvoice document links",
+        tools=[
+            ToolInfo("get_document_relation", "Retrieve document relation"),
+            ToolInfo("list_document_relations", "List document relations"),
+        ],
+        keywords=["document relation", "export", "einvoice"],
+    ),
+    "relations": ToolCategory(
+        name="relations",
+        description="Annotation relations: manage edit/attachment/duplicate links",
+        tools=[
+            ToolInfo("get_relation", "Retrieve relation details"),
+            ToolInfo("list_relations", "List annotation relations"),
+        ],
+        keywords=["relation", "duplicate", "attachment", "edit"],
+    ),
+    "rules": ToolCategory(
+        name="rules",
+        description="Validation rules: manage schema validation rules",
+        tools=[
+            ToolInfo("get_rule", "Retrieve rule details"),
+            ToolInfo("list_rules", "List validation rules"),
+        ],
+        keywords=["rule", "validation", "constraint"],
+    ),
+    "users": ToolCategory(
+        name="users",
+        description="User management: list users and roles",
+        tools=[
+            ToolInfo("get_user", "Retrieve user details"),
+            ToolInfo("list_users", "List users with filters"),
+            ToolInfo("list_user_roles", "List available user roles"),
+        ],
+        keywords=["user", "role", "permission", "token_owner"],
+    ),
+    "workspaces": ToolCategory(
+        name="workspaces",
+        description="Workspace management: organize queues into workspaces",
+        tools=[
+            ToolInfo("get_workspace", "Retrieve workspace details"),
+            ToolInfo("list_workspaces", "List all workspaces"),
+            ToolInfo("create_workspace", "Create new workspace"),
+        ],
+        keywords=["workspace", "organization"],
+    ),
+}
+
+
+def get_catalog_summary() -> str:
+    """Get a compact text summary of all tool categories for the system prompt."""
+    lines = ["Available MCP tool categories (use `list_tool_categories` for details):"]
+    for category in TOOL_CATALOG.values():
+        tool_names = ", ".join(t.name for t in category.tools)
+        lines.append(f"- **{category.name}**: {category.description} [{tool_names}]")
+    return "\n".join(lines)

rossum_mcp/tools/discovery.py

@@ -0,0 +1,36 @@
+"""Discovery tools for dynamic tool loading.
+
+Provides MCP tool to explore available tool categories and their metadata.
+The agent uses this to fetch the catalog and load tools on-demand.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING
+
+from rossum_mcp.tools.catalog import TOOL_CATALOG
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_discovery_tools(mcp: FastMCP) -> None:
+    """Register discovery tools with the FastMCP server."""
+
+    @mcp.tool(
+        description="List all available tool categories with descriptions, tool names, and keywords. "
+        "Use this to discover what tools are available, then use load_tool_category to load "
+        "tools from specific categories before using them."
+    )
+    async def list_tool_categories() -> list[dict]:
+        return [
+            {
+                "name": category.name,
+                "description": category.description,
+                "tool_count": len(category.tools),
+                "tools": [asdict(tool) for tool in category.tools],
+                "keywords": category.keywords,
+            }
+            for category in TOOL_CATALOG.values()
+        ]

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