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

rossum_mcp/__init__.py

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

rossum_mcp/tools/annotations.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Literal
 
 from rossum_api.models.annotation import Annotation
 
-from rossum_mcp.tools.base import is_read_write_mode
+from rossum_mcp.tools.base import delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -130,6 +130,12 @@ async def _confirm_annotation(client: AsyncRossumAPIClient, annotation_id: int)
     }
 
 
+async def _delete_annotation(client: AsyncRossumAPIClient, annotation_id: int) -> dict:
+    return await delete_resource(
+        "annotation", annotation_id, client.delete_annotation, f"Annotation {annotation_id} moved to 'deleted' status"
+    )
+
+
 def register_annotation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register annotation-related tools with the FastMCP server."""
 
@@ -165,3 +171,7 @@ def register_annotation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> Non
     )
     async def confirm_annotation(annotation_id: int) -> dict:
         return await _confirm_annotation(client, annotation_id)
+
+    @mcp.tool(description="Delete an annotation. Moves to 'deleted' status (soft delete).")
+    async def delete_annotation(annotation_id: int) -> dict:
+        return await _delete_annotation(client, annotation_id)

rossum_mcp/tools/base.py

@@ -2,12 +2,16 @@
 
 from __future__ import annotations
 
+import logging
 import os
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
     from typing import Any
 
+logger = logging.getLogger(__name__)
+
 BASE_URL = os.environ.get("ROSSUM_API_BASE_URL", "").rstrip("/")
 MODE = os.environ.get("ROSSUM_MCP_MODE", "read-write").lower()
 
@@ -38,3 +42,32 @@ def truncate_dict_fields(data: dict[str, Any], fields: tuple[str, ...]) -> dict[
         if field in result:
             result[field] = TRUNCATED_MARKER
     return result
+
+
+async def delete_resource(
+    resource_type: str,
+    resource_id: int,
+    delete_fn: Callable[[int], Awaitable[None]],
+    success_message: str | None = None,
+) -> dict:
+    """Generic delete operation with read-only mode check.
+
+    Args:
+        resource_type: Name of the resource (e.g., "queue", "workspace")
+        resource_id: ID of the resource to delete
+        delete_fn: Async function that performs the deletion
+        success_message: Custom success message. If None, uses default format.
+
+    Returns:
+        Dict with "message" on success or "error" in read-only mode.
+    """
+    tool_name = f"delete_{resource_type}"
+    if not is_read_write_mode():
+        return {"error": f"{tool_name} is not available in read-only mode"}
+
+    logger.debug(f"Deleting {resource_type}: {resource_type}_id={resource_id}")
+    await delete_fn(resource_id)
+
+    if success_message is None:
+        success_message = f"{resource_type.title()} {resource_id} deleted successfully"
+    return {"message": success_message}

rossum_mcp/tools/catalog.py

@@ -16,6 +16,7 @@ class ToolInfo:
 
     name: str
     description: str
+    read_only: bool = True
 
 
 @dataclass
@@ -35,12 +36,13 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
         name="annotations",
         description="Document processing: upload, retrieve, update, and confirm annotations",
         tools=[
-            ToolInfo("upload_document", "Upload document to queue"),
+            ToolInfo("upload_document", "Upload document to queue", read_only=False),
             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)"),
+            ToolInfo("start_annotation", "Start annotation (to_review -> reviewing)", read_only=False),
+            ToolInfo("bulk_update_annotation_fields", "Bulk update annotation fields", read_only=False),
+            ToolInfo("confirm_annotation", "Confirm annotation (-> confirmed)", read_only=False),
+            ToolInfo("delete_annotation", "Delete annotation (soft delete)", read_only=False),
         ],
         keywords=["annotation", "document", "upload", "extract", "confirm", "review"],
     ),
@@ -52,10 +54,11 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
             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("create_queue", "Create a queue", read_only=False),
+            ToolInfo("update_queue", "Update queue settings", read_only=False),
             ToolInfo("get_queue_template_names", "List available queue templates"),
-            ToolInfo("create_queue_from_template", "Create queue from template"),
+            ToolInfo("create_queue_from_template", "Create queue from template", read_only=False),
+            ToolInfo("delete_queue", "Delete queue (24h delayed)", read_only=False),
         ],
         keywords=["queue", "inbox", "connector"],
     ),
@@ -65,11 +68,12 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
         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("update_schema", "Update schema", read_only=False),
+            ToolInfo("create_schema", "Create new schema", read_only=False),
+            ToolInfo("patch_schema", "Add/update/remove schema fields", read_only=False),
             ToolInfo("get_schema_tree_structure", "Get lightweight schema tree"),
-            ToolInfo("prune_schema_fields", "Bulk remove schema fields"),
+            ToolInfo("prune_schema_fields", "Bulk remove schema fields", read_only=False),
+            ToolInfo("delete_schema", "Delete schema", read_only=False),
         ],
         keywords=["schema", "field", "datapoint", "section", "multivalue", "tuple"],
     ),
@@ -79,9 +83,9 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
         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("update_engine", "Update engine settings", read_only=False),
+            ToolInfo("create_engine", "Create new engine", read_only=False),
+            ToolInfo("create_engine_field", "Create engine field mapping", read_only=False),
             ToolInfo("get_engine_fields", "List engine fields"),
         ],
         keywords=["engine", "ai", "extractor", "splitter", "training"],
@@ -92,11 +96,12 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
         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("create_hook", "Create new hook", read_only=False),
+            ToolInfo("update_hook", "Update hook configuration", read_only=False),
             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"),
+            ToolInfo("create_hook_from_template", "Create hook from template", read_only=False),
+            ToolInfo("delete_hook", "Delete hook", read_only=False),
         ],
         keywords=["hook", "extension", "webhook", "automation", "function", "serverless"],
     ),
@@ -106,7 +111,7 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
         tools=[
             ToolInfo("get_email_template", "Retrieve email template"),
             ToolInfo("list_email_templates", "List email templates"),
-            ToolInfo("create_email_template", "Create email template"),
+            ToolInfo("create_email_template", "Create email template", read_only=False),
         ],
         keywords=["email", "template", "notification", "rejection"],
     ),
@@ -126,7 +131,7 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
             ToolInfo("get_relation", "Retrieve relation details"),
             ToolInfo("list_relations", "List annotation relations"),
         ],
-        keywords=["relation", "duplicate", "attachment", "edit"],
+        keywords=["relation", "duplicate", "attachment"],
     ),
     "rules": ToolCategory(
         name="rules",
@@ -134,6 +139,7 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
         tools=[
             ToolInfo("get_rule", "Retrieve rule details"),
             ToolInfo("list_rules", "List validation rules"),
+            ToolInfo("delete_rule", "Delete rule", read_only=False),
         ],
         keywords=["rule", "validation", "constraint"],
     ),
@@ -153,7 +159,8 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
         tools=[
             ToolInfo("get_workspace", "Retrieve workspace details"),
             ToolInfo("list_workspaces", "List all workspaces"),
-            ToolInfo("create_workspace", "Create new workspace"),
+            ToolInfo("create_workspace", "Create new workspace", read_only=False),
+            ToolInfo("delete_workspace", "Delete workspace", read_only=False),
         ],
         keywords=["workspace", "organization"],
     ),

rossum_mcp/tools/discovery.py

@@ -21,7 +21,8 @@ def register_discovery_tools(mcp: FastMCP) -> None:
     @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."
+        "tools from specific categories before using them. Tools with read_only=false are write "
+        "operations (create, update, delete)."
     )
     async def list_tool_categories() -> list[dict]:
         return [

rossum_mcp/tools/email_templates.py

@@ -38,15 +38,11 @@ async def _list_email_templates(
     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)]
+    templates_list: list[EmailTemplate] = []
+    async for template in client.list_email_templates(**filters):
+        templates_list.append(template)
+        if first_n is not None and len(templates_list) >= first_n:
+            break
 
     return templates_list
 

rossum_mcp/tools/hooks.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Annotated, Any, Literal
 
 from rossum_api.models.hook import Hook, HookRunData, HookType
 
-from rossum_mcp.tools.base import TRUNCATED_MARKER, is_read_write_mode
+from rossum_mcp.tools.base import TRUNCATED_MARKER, delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -56,15 +56,11 @@ async def _list_hooks(
     if active is not None:
         filters["active"] = active
 
-    if first_n is not None:
-        hooks_iter = client.list_hooks(**filters)
-        hooks_list: list[Hook] = []
-        n = 0
-        while n < first_n:
-            hooks_list.append(await anext(hooks_iter))
-            n += 1
-    else:
-        hooks_list = [hook async for hook in client.list_hooks(**filters)]
+    hooks_list: list[Hook] = []
+    async for hook in client.list_hooks(**filters):
+        hooks_list.append(hook)
+        if first_n is not None and len(hooks_list) >= first_n:
+            break
 
     return hooks_list
 
@@ -238,6 +234,10 @@ async def _create_hook_from_template(
     return {"error": "Hook wasn't likely created. Hook ID not available."}
 
 
+async def _delete_hook(client: AsyncRossumAPIClient, hook_id: int) -> dict:
+    return await delete_resource("hook", hook_id, client.delete_hook)
+
+
 def register_hook_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register hook-related tools with the FastMCP server."""
 
@@ -256,7 +256,7 @@ def register_hook_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
         return await _list_hooks(client, queue_id, active, first_n)
 
     @mcp.tool(
-        description="Create a new hook. If token_owner is provided, organization_group_admin users CANNOT be used (API will reject)."
+        description="Create a new hook. For function hooks: 'source' in config is auto-renamed to 'function', runtime defaults to 'python3.12', timeout_s is capped at 60s. If token_owner is provided, organization_group_admin users CANNOT be used."
     )
     async def create_hook(
         name: str,
@@ -341,3 +341,7 @@ def register_hook_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
         token_owner: str | None = None,
     ) -> Hook | dict:
         return await _create_hook_from_template(client, name, hook_template_id, queues, events, token_owner)
+
+    @mcp.tool(description="Delete a hook.")
+    async def delete_hook(hook_id: int) -> dict:
+        return await _delete_hook(client, hook_id)

rossum_mcp/tools/queues.py

@@ -14,7 +14,7 @@ from rossum_api.models.engine import Engine
 from rossum_api.models.queue import Queue
 from rossum_api.models.schema import Schema
 
-from rossum_mcp.tools.base import build_resource_url, is_read_write_mode, truncate_dict_fields
+from rossum_mcp.tools.base import build_resource_url, delete_resource, is_read_write_mode, truncate_dict_fields
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -46,10 +46,15 @@ async def _get_queue(client: AsyncRossumAPIClient, queue_id: int) -> Queue:
 
 
 async def _list_queues(
-    client: AsyncRossumAPIClient, workspace_id: int | None = None, name: str | None = None
+    client: AsyncRossumAPIClient,
+    id: str | None = None,
+    workspace_id: int | None = None,
+    name: str | None = None,
 ) -> list[Queue]:
-    logger.debug(f"Listing queues: workspace_id={workspace_id}, name={name}")
+    logger.debug(f"Listing queues: id={id}, workspace_id={workspace_id}, name={name}")
     filters: dict[str, int | str] = {}
+    if id is not None:
+        filters["id"] = id
     if workspace_id is not None:
         filters["workspace"] = workspace_id
     if name is not None:
@@ -155,6 +160,12 @@ async def _update_queue(client: AsyncRossumAPIClient, queue_id: int, queue_data:
     return cast("Queue", client._deserializer(Resource.Queue, updated_queue_data))
 
 
+async def _delete_queue(client: AsyncRossumAPIClient, queue_id: int) -> dict:
+    return await delete_resource(
+        "queue", queue_id, client.delete_queue, f"Queue {queue_id} scheduled for deletion (starts after 24 hours)"
+    )
+
+
 # Available template names for create_queue_from_template
 QueueTemplateName = Literal[
     "EU Demo Template",
@@ -227,9 +238,11 @@ def register_queue_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     async def get_queue(queue_id: int) -> Queue:
         return await _get_queue(client, queue_id)
 
-    @mcp.tool(description="List all queues with optional filters.")
-    async def list_queues(workspace_id: int | None = None, name: str | None = None) -> list[Queue]:
-        return await _list_queues(client, workspace_id, name)
+    @mcp.tool(description="List all queues with optional filters. id accepts comma-separated values (e.g. '1,2,3').")
+    async def list_queues(
+        id: str | None = None, workspace_id: int | None = None, name: str | None = None
+    ) -> list[Queue]:
+        return await _list_queues(client, id, workspace_id, name)
 
     @mcp.tool(description="Retrieve queue schema.")
     async def get_queue_schema(queue_id: int) -> Schema:
@@ -272,6 +285,12 @@ def register_queue_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     async def update_queue(queue_id: int, queue_data: dict) -> Queue | dict:
         return await _update_queue(client, queue_id, queue_data)
 
+    @mcp.tool(
+        description="Delete a queue. Deletion starts after 24 hours. Also deletes all related objects (annotations, documents)."
+    )
+    async def delete_queue(queue_id: int) -> dict:
+        return await _delete_queue(client, queue_id)
+
     @mcp.tool(description="Get available queue template names for create_queue_from_template.")
     async def get_queue_template_names() -> list[str]:
         return list(QUEUE_TEMPLATE_NAMES)

rossum_mcp/tools/rules.py

@@ -7,6 +7,8 @@ from typing import TYPE_CHECKING
 
 from rossum_api.models.rule import Rule
 
+from rossum_mcp.tools.base import delete_resource
+
 if TYPE_CHECKING:
     from fastmcp import FastMCP
     from rossum_api import AsyncRossumAPIClient
@@ -39,6 +41,10 @@ async def _list_rules(
     return rules_list
 
 
+async def _delete_rule(client: AsyncRossumAPIClient, rule_id: int) -> dict:
+    return await delete_resource("rule", rule_id, client.delete_rule)
+
+
 def register_rule_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register rule-related tools with the FastMCP server."""
 
@@ -51,3 +57,7 @@ def register_rule_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
         schema_id: int | None = None, organization_id: int | None = None, enabled: bool | None = None
     ) -> list[Rule]:
         return await _list_rules(client, schema_id, organization_id, enabled)
+
+    @mcp.tool(description="Delete a rule.")
+    async def delete_rule(rule_id: int) -> dict:
+        return await _delete_rule(client, rule_id)

rossum_mcp/tools/schemas.py

@@ -7,10 +7,11 @@ import logging
 from dataclasses import asdict, dataclass, is_dataclass, replace
 from typing import TYPE_CHECKING, Any, Literal
 
+from rossum_api import APIClientError
 from rossum_api.domain_logic.resources import Resource
 from rossum_api.models.schema import Schema
 
-from rossum_mcp.tools.base import TRUNCATED_MARKER, is_read_write_mode
+from rossum_mcp.tools.base import TRUNCATED_MARKER, delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -427,9 +428,14 @@ def apply_schema_patch(
     return content
 
 
-async def _get_schema(client: AsyncRossumAPIClient, schema_id: int) -> Schema:
-    schema: Schema = await client.retrieve_schema(schema_id)
-    return schema
+async def _get_schema(client: AsyncRossumAPIClient, schema_id: int) -> Schema | dict:
+    try:
+        schema: Schema = await client.retrieve_schema(schema_id)
+        return schema
+    except APIClientError as e:
+        if e.status_code == 404:
+            return {"error": f"Schema {schema_id} not found"}
+        raise
 
 
 @dataclass
@@ -666,8 +672,10 @@ async def _patch_schema(
     return updated_schema
 
 
-async def _get_schema_tree_structure(client: AsyncRossumAPIClient, schema_id: int) -> list[dict]:
+async def _get_schema_tree_structure(client: AsyncRossumAPIClient, schema_id: int) -> list[dict] | dict:
     schema = await _get_schema(client, schema_id)
+    if isinstance(schema, dict):
+        return schema
     content_dicts: list[dict[str, Any]] = [
         asdict(section) if is_dataclass(section) else dict(section)  # type: ignore[arg-type]
         for section in schema.content
@@ -715,11 +723,15 @@ async def _prune_schema_fields(
     return {"removed_fields": sorted(removed), "remaining_fields": sorted(remaining_ids)}
 
 
+async def _delete_schema(client: AsyncRossumAPIClient, schema_id: int) -> dict:
+    return await delete_resource("schema", schema_id, client.delete_schema)
+
+
 def register_schema_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register schema-related tools with the FastMCP server."""
 
     @mcp.tool(description="Retrieve schema details.")
-    async def get_schema(schema_id: int) -> Schema:
+    async def get_schema(schema_id: int) -> Schema | dict:
         return await _get_schema(client, schema_id)
 
     @mcp.tool(description="List all schemas with optional filters.")
@@ -764,7 +776,7 @@ Important: Datapoints inside a tuple MUST have an "id" field. Section-level data
         return await _patch_schema(client, schema_id, operation, node_id, node_data, parent_id, position)
 
     @mcp.tool(description="Get lightweight tree structure of schema with only ids, labels, categories, and types.")
-    async def get_schema_tree_structure(schema_id: int) -> list[dict]:
+    async def get_schema_tree_structure(schema_id: int) -> list[dict] | dict:
         return await _get_schema_tree_structure(client, schema_id)
 
     @mcp.tool(
@@ -782,3 +794,7 @@ Returns dict with removed_fields and remaining_fields lists. Sections cannot be
         fields_to_remove: list[str] | None = None,
     ) -> dict:
         return await _prune_schema_fields(client, schema_id, fields_to_keep, fields_to_remove)
+
+    @mcp.tool(description="Delete a schema. Fails if schema is linked to a queue or annotation (HTTP 409).")
+    async def delete_schema(schema_id: int) -> dict:
+        return await _delete_schema(client, schema_id)

rossum_mcp/tools/workspaces.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 
 from rossum_api.models.workspace import Workspace
 
-from rossum_mcp.tools.base import build_resource_url, is_read_write_mode
+from rossum_mcp.tools.base import build_resource_url, delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -59,6 +59,10 @@ async def _create_workspace(
     return workspace
 
 
+async def _delete_workspace(client: AsyncRossumAPIClient, workspace_id: int) -> dict:
+    return await delete_resource("workspace", workspace_id, client.delete_workspace)
+
+
 def register_workspace_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register workspace-related tools with the FastMCP server."""
 
@@ -73,3 +77,7 @@ def register_workspace_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None
     @mcp.tool(description="Create a new workspace.")
     async def create_workspace(name: str, organization_id: int, metadata: dict | None = None) -> Workspace | dict:
         return await _create_workspace(client, name, organization_id, metadata)
+
+    @mcp.tool(description="Delete a workspace. Fails if workspace contains queues.")
+    async def delete_workspace(workspace_id: int) -> dict:
+        return await _delete_workspace(client, workspace_id)