rossum-mcp 0.3.4__py3-none-any.whl

rossum_mcp/tools/hooks.py

@@ -0,0 +1,265 @@
+"""Hook tools for Rossum MCP Server."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Annotated, Any, Literal
+
+from rossum_api.models.hook import (  # noqa: TC002 - needed at runtime for FastMCP
+    Hook,
+    HookRunData,
+    HookType,
+)
+
+from rossum_mcp.tools.base import is_read_write_mode
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+type Timestamp = Annotated[str, "ISO 8601 timestamp (e.g., '2024-01-15T10:30:00Z')"]
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HookTemplate:
+    """Represents a hook template from Rossum Store.
+
+    Hook templates provide pre-built extension configurations that can be
+    used to quickly create hooks with standard functionality.
+    """
+
+    id: int
+    url: str
+    name: str
+    description: str
+    type: str
+    events: list[str]
+    config: dict[str, Any]
+    settings_schema: dict[str, Any] | None
+    guide: str | None
+    use_token_owner: bool
+
+
+def register_hook_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:  # noqa: C901
+    """Register hook-related tools with the FastMCP server."""
+
+    @mcp.tool(
+        description="Retrieve a single hook by ID. Use list_hooks first to get all hooks for a queue - only use get_hook if you need additional details for a specific hook not returned by list_hooks. For Python-based function hooks, the source code is accessible via hook.config['code']."
+    )
+    async def get_hook(hook_id: int) -> Hook:
+        hook: Hook = await client.retrieve_hook(hook_id)
+        return hook
+
+    @mcp.tool(
+        description="List all hooks/extensions for a queue. ALWAYS use this first when you need information about hooks on a queue - it returns complete hook details including code, config, and settings in a single call. Only use get_hook afterward if you need details not present in the list response. For Python-based function hooks, the source code is accessible via hook.config['code']."
+    )
+    async def list_hooks(
+        queue_id: int | None = None, active: bool | None = None, first_n: int | None = None
+    ) -> list[Hook]:
+        filters: dict = {}
+        if queue_id is not None:
+            filters["queue"] = queue_id
+        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)]
+
+        return hooks_list
+
+    # NOTE: We explicitly document token_owner restrictions in the tool description because
+    # Sonnet 4.5 respects tool descriptions more reliably than instructions in system prompts.
+    @mcp.tool(
+        description="Create a new hook. If token_owner is provided, organization_group_admin users CANNOT be used (API will reject)."
+    )
+    async def create_hook(
+        name: str,
+        type: HookType,
+        queues: list[str] | None = None,
+        events: list[str] | None = None,
+        config: dict | None = None,
+        settings: dict | None = None,
+        secret: str | None = None,
+    ) -> Hook | dict:
+        if not is_read_write_mode():
+            return {"error": "create_hook is not available in read-only mode"}
+
+        hook_data: dict[str, Any] = {"name": name, "type": type, "sideload": ["schemas"]}
+
+        if queues is not None:
+            hook_data["queues"] = queues
+        if events is not None:
+            hook_data["events"] = events
+        if config is None:
+            config = {}
+        if type == "function" and "source" in config:
+            config["function"] = config.pop("source")
+        if type == "function" and "runtime" not in config:
+            config["runtime"] = "python3.12"
+        if "timeout_s" in config and config["timeout_s"] > 60:
+            config["timeout_s"] = 60
+        hook_data["config"] = config
+        if settings is not None:
+            hook_data["settings"] = settings
+        if secret is not None:
+            hook_data["secret"] = secret
+
+        hook: Hook = await client.create_new_hook(hook_data)
+        return hook
+
+    @mcp.tool(
+        description="Update an existing hook. Use this to modify hook properties like name, queues, config, events, or settings. Only provide the fields you want to change - other fields will remain unchanged."
+    )
+    async def update_hook(
+        hook_id: int,
+        name: str | None = None,
+        queues: list[str] | None = None,
+        events: list[str] | None = None,
+        config: dict | None = None,
+        settings: dict | None = None,
+        active: bool | None = None,
+    ) -> Hook | dict:
+        if not is_read_write_mode():
+            return {"error": "update_hook is not available in read-only mode"}
+
+        logger.debug(f"Updating hook: hook_id={hook_id}")
+
+        # Fetch existing hook data first (PUT requires all fields)
+        existing_hook: Hook = await client.retrieve_hook(hook_id)
+        hook_data: dict[str, Any] = {
+            "name": existing_hook.name,
+            "queues": existing_hook.queues,
+            "events": list(existing_hook.events),
+            "config": dict(existing_hook.config) if existing_hook.config else {},
+        }
+
+        # Override with provided values
+        if name is not None:
+            hook_data["name"] = name
+        if queues is not None:
+            hook_data["queues"] = queues
+        if events is not None:
+            hook_data["events"] = events
+        if config is not None:
+            hook_data["config"] = config
+        if settings is not None:
+            hook_data["settings"] = settings
+        if active is not None:
+            hook_data["active"] = active
+
+        updated_hook: Hook = await client.update_part_hook(hook_id, hook_data)
+        return updated_hook
+
+    @mcp.tool(
+        description="List hook execution logs. Use this to debug hook executions, monitor performance, and troubleshoot errors. Logs are retained for 7 days. Returns at most 100 logs per call."
+    )
+    async def list_hook_logs(
+        hook_id: int | None = None,
+        queue_id: int | None = None,
+        annotation_id: int | None = None,
+        email_id: int | None = None,
+        log_level: Literal["INFO", "ERROR", "WARNING"] | None = None,
+        status: str | None = None,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        timestamp_before: Timestamp | None = None,
+        timestamp_after: Timestamp | None = None,
+        start_before: Timestamp | None = None,
+        start_after: Timestamp | None = None,
+        end_before: Timestamp | None = None,
+        end_after: Timestamp | None = None,
+        search: str | None = None,
+        page_size: int | None = None,
+    ) -> list[HookRunData]:
+        filter_mapping: dict[str, Any] = {
+            "hook": hook_id,
+            "queue": queue_id,
+            "annotation": annotation_id,
+            "email": email_id,
+            "log_level": log_level,
+            "status": status,
+            "status_code": status_code,
+            "request_id": request_id,
+            "timestamp_before": timestamp_before,
+            "timestamp_after": timestamp_after,
+            "start_before": start_before,
+            "start_after": start_after,
+            "end_before": end_before,
+            "end_after": end_after,
+            "search": search,
+            "page_size": page_size,
+        }
+        filters = {k: v for k, v in filter_mapping.items() if v is not None}
+
+        # list_hook_run_data is available from ds-feat-hook-logs branch
+        return [
+            log
+            async for log in client.list_hook_run_data(**filters)  # type: ignore[attr-defined]
+        ]
+
+    @mcp.tool(
+        description="List available hook templates from Rossum Store. Hook templates provide pre-built extension configurations (e.g., data validation, field mapping, notifications) that can be used to quickly create hooks instead of writing code from scratch. Use list_hook_templates first to find a suitable template, then use create_hook_from_template to create a hook based on that template."
+    )
+    async def list_hook_templates() -> list[HookTemplate]:
+        templates: list[HookTemplate] = []
+        async for item in client.request_paginated("hook_templates"):
+            url = item["url"]
+            templates.append(
+                HookTemplate(
+                    id=int(url.split("/")[-1]),
+                    url=url,
+                    name=item["name"],
+                    description=item.get("description", ""),
+                    type=item["type"],
+                    events=[],
+                    config={},
+                    settings_schema=item.get("settings_schema"),
+                    guide="<truncated>",
+                    use_token_owner=item.get("use_token_owner", False),
+                )
+            )
+        return templates
+
+    # NOTE: We explicitly document token_owner restrictions in the tool description because
+    # Sonnet 4.5 respects tool descriptions more reliably than instructions in system prompts.
+    @mcp.tool(
+        description="Create a hook from a Rossum Store template. Uses pre-built configurations from the Rossum Store. The 'events' parameter is optional and can override template defaults. If the template has 'use_token_owner=True', a valid 'token_owner' user URL is required - use list_users to find one. CRITICAL RESTRICTION: organization_group_admin users are FORBIDDEN as token_owner - the API returns HTTP 400 error."
+    )
+    async def create_hook_from_template(
+        name: str,
+        hook_template_id: int,
+        queues: list[str],
+        events: list[str] | None = None,
+        token_owner: str | None = None,
+    ) -> Hook | dict:
+        if not is_read_write_mode():
+            return {"error": "create_hook_from_template is not available in read-only mode"}
+
+        logger.debug(f"Creating hook from template: name={name}, template_id={hook_template_id}")
+
+        # Build the hook template URL and fetch template to get its config
+        hook_template_url = f"{client._http_client.base_url.rstrip('/')}/hook_templates/{hook_template_id}"
+
+        hook_data: dict[str, Any] = {"name": name, "hook_template": hook_template_url, "queues": queues}
+        if events is not None:
+            hook_data["events"] = events
+        if token_owner is not None:
+            hook_data["token_owner"] = token_owner
+
+        result = await client._http_client.request_json("POST", "hooks/create", json=hook_data)
+
+        # Return the created hook
+        if hook_id := result.get("id"):
+            hook: Hook = await client.retrieve_hook(hook_id)
+            return hook
+        return {"error": "Hook wasn't likely created. Hook ID not available."}

rossum_mcp/tools/queues.py

@@ -0,0 +1,133 @@
+"""Queue tools for Rossum MCP Server."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING
+
+from rossum_api import APIClientError
+from rossum_api.domain_logic.resources import Resource
+from rossum_api.models import deserialize_default
+from rossum_api.models.engine import Engine  # noqa: TC002 - needed at runtime for FastMCP
+from rossum_api.models.queue import Queue  # noqa: TC002 - needed at runtime for FastMCP
+from rossum_api.models.schema import Schema  # noqa: TC002 - needed at runtime for FastMCP
+
+from rossum_mcp.tools.base import build_resource_url, is_read_write_mode
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+logger = logging.getLogger(__name__)
+
+
+def register_queue_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:  # noqa: C901
+    """Register queue-related tools with the FastMCP server."""
+
+    @mcp.tool(description="Retrieve queue details.")
+    async def get_queue(queue_id: int) -> Queue:
+        """Retrieve queue details."""
+        logger.debug(f"Retrieving queue: queue_id={queue_id}")
+        queue: Queue = await client.retrieve_queue(queue_id)
+        return queue
+
+    @mcp.tool(description="Retrieve queue schema.")
+    async def get_queue_schema(queue_id: int) -> Schema:
+        """Retrieve complete schema for a queue."""
+        logger.debug(f"Retrieving queue schema: queue_id={queue_id}")
+        queue: Queue = await client.retrieve_queue(queue_id)
+        schema_url = queue.schema
+        schema_id = int(schema_url.rstrip("/").split("/")[-1])
+        schema: Schema = await client.retrieve_schema(schema_id)
+        return schema
+
+    @mcp.tool(description="Retrieve queue engine. Returns None if no engine assigned.")
+    async def get_queue_engine(queue_id: int) -> Engine | dict:
+        """Retrieve complete engine information for a queue."""
+        logger.debug(f"Retrieving queue engine: queue_id={queue_id}")
+        queue: Queue = await client.retrieve_queue(queue_id)
+
+        engine_url = None
+        if queue.dedicated_engine:
+            engine_url = queue.dedicated_engine
+        elif queue.generic_engine:
+            engine_url = queue.generic_engine
+        elif queue.engine:
+            engine_url = queue.engine
+
+        if not engine_url:
+            return {"message": "No engine assigned to this queue"}
+
+        try:
+            if isinstance(engine_url, str):
+                engine_id = int(engine_url.rstrip("/").split("/")[-1])
+                engine: Engine = await client.retrieve_engine(engine_id)
+            else:
+                engine = deserialize_default(Resource.Engine, engine_url)
+        except APIClientError as e:
+            if e.status_code == 404:
+                return {"message": f"Engine not found (engine URL: {engine_url})"}
+            raise
+
+        return engine
+
+    @mcp.tool(description="Create a queue.")
+    async def create_queue(
+        name: str,
+        workspace_id: int,
+        schema_id: int,
+        engine_id: int | None = None,
+        inbox_id: int | None = None,
+        connector_id: int | None = None,
+        locale: str = "en_GB",
+        automation_enabled: bool = False,
+        automation_level: str = "never",
+        training_enabled: bool = True,
+        splitting_screen_feature_flag: bool = False,
+    ) -> Queue | dict:
+        """Create a new queue with schema and optional engine assignment."""
+        if not is_read_write_mode():
+            return {"error": "create_queue is not available in read-only mode"}
+
+        logger.debug(
+            f"Creating queue: name={name}, workspace_id={workspace_id}, schema_id={schema_id}, engine_id={engine_id}"
+        )
+
+        queue_data: dict = {
+            "name": name,
+            "workspace": build_resource_url("workspaces", workspace_id),
+            "schema": build_resource_url("schemas", schema_id),
+            "locale": locale,
+            "automation_enabled": automation_enabled,
+            "automation_level": automation_level,
+            "training_enabled": training_enabled,
+        }
+
+        if engine_id is not None:
+            queue_data["engine"] = build_resource_url("engines", engine_id)
+        if inbox_id is not None:
+            queue_data["inbox"] = build_resource_url("inboxes", inbox_id)
+        if connector_id is not None:
+            queue_data["connector"] = build_resource_url("connectors", connector_id)
+        if splitting_screen_feature_flag:
+            if os.environ.get("SPLITTING_SCREEN_FLAG_NAME") and os.environ.get("SPLITTING_SCREEN_FLAG_VALUE"):
+                queue_data["settings"] = {
+                    os.environ["SPLITTING_SCREEN_FLAG_NAME"]: os.environ["SPLITTING_SCREEN_FLAG_VALUE"]
+                }
+            else:
+                logger.error("Splitting screen failed to update")
+
+        queue: Queue = await client.create_new_queue(queue_data)
+        return queue
+
+    @mcp.tool(description="Update queue settings.")
+    async def update_queue(queue_id: int, queue_data: dict) -> Queue | dict:
+        """Update an existing queue with new settings."""
+        if not is_read_write_mode():
+            return {"error": "update_queue is not available in read-only mode"}
+
+        logger.debug(f"Updating queue: queue_id={queue_id}, data={queue_data}")
+        updated_queue_data = await client._http_client.update(Resource.Queue, queue_id, queue_data)
+        updated_queue: Queue = client._deserializer(Resource.Queue, updated_queue_data)
+        return updated_queue

rossum_mcp/tools/relations.py

@@ -0,0 +1,56 @@
+"""Relation tools for Rossum MCP Server."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from rossum_api.domain_logic.resources import Resource
+from rossum_api.models.relation import (
+    Relation,  # noqa: TC002 - needed at runtime for FastMCP
+    RelationType,  # noqa: TC002 - needed at runtime for FastMCP
+)
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+logger = logging.getLogger(__name__)
+
+
+def register_relation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
+    """Register relation-related tools with the FastMCP server."""
+
+    @mcp.tool(description="Retrieve relation details.")
+    async def get_relation(relation_id: int) -> Relation:
+        """Retrieve relation details."""
+        logger.debug(f"Retrieving relation: relation_id={relation_id}")
+        relation_data = await client._http_client.fetch_one(Resource.Relation, relation_id)
+        relation_obj: Relation = client._deserializer(Resource.Relation, relation_data)
+        return relation_obj
+
+    @mcp.tool(
+        description="List all relations with optional filters. Relations introduce common relations between annotations (edit, attachment, duplicate)."
+    )
+    async def list_relations(
+        id: int | None = None,
+        type: RelationType | None = None,
+        parent: int | None = None,
+        key: str | None = None,
+        annotation: int | None = None,
+    ) -> list[Relation]:
+        """List all relations with optional filters."""
+        logger.debug(f"Listing relations: id={id}, type={type}, parent={parent}, key={key}, annotation={annotation}")
+        filters: dict[str, int | str] = {}
+        if id is not None:
+            filters["id"] = id
+        if type is not None:
+            filters["type"] = type
+        if parent is not None:
+            filters["parent"] = parent
+        if key is not None:
+            filters["key"] = key
+        if annotation is not None:
+            filters["annotation"] = annotation
+
+        return [relation async for relation in client.list_relations(**filters)]  # type: ignore[arg-type]

rossum_mcp/tools/rules.py

@@ -0,0 +1,42 @@
+"""Rule tools for Rossum MCP Server."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from rossum_api.models.rule import Rule  # noqa: TC002 - needed at runtime for FastMCP
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+logger = logging.getLogger(__name__)
+
+
+def register_rule_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
+    """Register rule-related tools with the FastMCP server."""
+
+    @mcp.tool(description="Retrieve rule details.")
+    async def get_rule(rule_id: int) -> Rule:
+        """Retrieve rule details."""
+        logger.debug(f"Retrieving rule: rule_id={rule_id}")
+        rule: Rule = await client.retrieve_rule(rule_id)
+        return rule
+
+    @mcp.tool(description="List all rules.")
+    async def list_rules(
+        schema_id: int | None = None, organization_id: int | None = None, enabled: bool | None = None
+    ) -> list[Rule]:
+        """List all rules, optionally filtered by schema, organization, and enabled status."""
+        logger.debug(f"Listing rules: schema_id={schema_id}, organization_id={organization_id}, enabled={enabled}")
+        filters: dict = {}
+        if schema_id is not None:
+            filters["schema"] = schema_id
+        if organization_id is not None:
+            filters["organization"] = organization_id
+        if enabled is not None:
+            filters["enabled"] = enabled
+
+        rules_list: list[Rule] = [rule async for rule in client.list_rules(**filters)]
+        return rules_list