rossum-mcp 0.3.4__py3-none-any.whl

rossum_mcp/__init__.py

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

rossum_mcp/logging_config.py

@@ -0,0 +1,141 @@
+"""Shared logging configuration for Rossum MCP/Agent with Redis integration."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from datetime import UTC, datetime
+from logging import LogRecord
+
+import redis
+
+
+class RedisHandler(logging.Handler):
+    """Custom logging handler that sends logs to Redis."""
+
+    def __init__(self, host: str, port: int = 6379, key_prefix: str = "logs", additional_fields: dict | None = None):
+        """Initialize Redis handler.
+
+        Args:
+            host: Redis host (e.g., "localhost")
+            port: Redis port (default: 6379)
+            key_prefix: Prefix for Redis keys
+            additional_fields: Additional fields to add to every log record
+        """
+        super().__init__()
+
+        self.client = redis.Redis(host=host, port=port, decode_responses=True)
+        self.key_prefix = key_prefix
+        self.additional_fields = additional_fields or {}
+
+    def emit(self, record: LogRecord) -> None:
+        """Emit a log record to Redis."""
+        if record.name.startswith("redis"):
+            return
+
+        try:
+            log_entry = {
+                "@timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+                "level": record.levelname,
+                "logger": record.name,
+                "message": record.getMessage(),
+                "module": record.module,
+                "function": record.funcName,
+                "line": record.lineno,
+                "thread": record.thread,
+                "thread_name": record.threadName,
+                **self.additional_fields,
+            }
+
+            for key, value in record.__dict__.items():
+                if key not in {
+                    "name",
+                    "msg",
+                    "args",
+                    "created",
+                    "filename",
+                    "funcName",
+                    "levelname",
+                    "levelno",
+                    "lineno",
+                    "module",
+                    "msecs",
+                    "message",
+                    "pathname",
+                    "process",
+                    "processName",
+                    "relativeCreated",
+                    "thread",
+                    "threadName",
+                    "exc_info",
+                    "exc_text",
+                    "stack_info",
+                    "taskName",
+                }:
+                    log_entry[key] = value
+
+            if record.exc_info:
+                log_entry["exception"] = self.format(record)
+
+            key = f"{self.key_prefix}:{datetime.now(UTC).strftime('%Y-%m-%d')}"
+            self.client.rpush(key, json.dumps(log_entry))
+            self.client.expire(key, 604800)  # 7 days
+        except Exception:
+            self.handleError(record)
+
+
+def setup_logging(
+    app_name: str = "rossum-app",
+    log_level: str = "DEBUG",
+    log_file: str | None = None,
+    use_console: bool = True,
+    redis_host: str | None = None,
+    redis_port: int | None = None,
+) -> logging.Logger:
+    """Configure logging with console, file, and optional Redis handlers.
+
+    Args:
+        app_name: Application name
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        use_console: Whether to add console handler (default: True)
+        redis_host: Redis host (default: from REDIS_HOST env var)
+        redis_port: Redis port (default: 6379)
+
+    Returns:
+        Configured root logger
+    """
+    root_logger = logging.getLogger()
+    root_logger.setLevel(getattr(logging, log_level.upper()))
+    root_logger.handlers.clear()
+
+    formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+    if use_console:
+        console = logging.StreamHandler(sys.stdout)
+        console.setFormatter(formatter)
+        root_logger.addHandler(console)
+
+    redis_host_val = redis_host or os.getenv("REDIS_HOST")
+    redis_port_val = redis_port or int(os.getenv("REDIS_PORT", "6379"))
+
+    if redis_host_val:
+        try:
+            redis_client = redis.Redis(host=redis_host_val, port=redis_port_val, socket_timeout=2)
+            redis_client.ping()
+
+            redis_handler = RedisHandler(
+                host=redis_host_val,
+                port=redis_port_val,
+                key_prefix="logs",
+                additional_fields={"application": app_name, "environment": os.getenv("ENVIRONMENT", "develop")},
+            )
+            redis_handler.client = redis_client
+            redis_handler.setLevel(logging.INFO)
+            root_logger.addHandler(redis_handler)
+            root_logger.info(f"Redis logging enabled: {redis_host_val}:{redis_port_val}")
+        except Exception as e:
+            root_logger.warning(f"Redis logging disabled: {e}")
+
+    return root_logger

rossum_mcp/server.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Rossum MCP Server
+
+Provides tools for uploading documents and retrieving annotations using Rossum API.
+Built with FastMCP for a cleaner, more Pythonic interface.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from fastmcp import FastMCP
+from rossum_api import AsyncRossumAPIClient
+from rossum_api.dtos import Token
+
+from rossum_mcp.logging_config import setup_logging
+from rossum_mcp.tools import (
+    register_annotation_tools,
+    register_document_relation_tools,
+    register_engine_tools,
+    register_hook_tools,
+    register_queue_tools,
+    register_relation_tools,
+    register_rule_tools,
+    register_schema_tools,
+    register_user_tools,
+    register_workspace_tools,
+)
+
+setup_logging(app_name="rossum-mcp-server", log_level="DEBUG", use_console=False)
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = os.environ["ROSSUM_API_BASE_URL"].rstrip("/")
+API_TOKEN = os.environ["ROSSUM_API_TOKEN"]
+MODE = os.environ.get("ROSSUM_MCP_MODE", "read-write").lower()
+
+if MODE not in ("read-only", "read-write"):
+    raise ValueError(f"Invalid ROSSUM_MCP_MODE: {MODE}. Must be 'read-only' or 'read-write'")
+
+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_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_document_relation_tools(mcp, client)
+register_relation_tools(mcp, client)
+register_rule_tools(mcp, client)
+register_user_tools(mcp, client)
+register_workspace_tools(mcp, client)
+
+
+def main() -> None:
+    """Main entry point for console script."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

rossum_mcp/tools/__init__.py

@@ -0,0 +1,27 @@
+"""FastMCP tool modules for Rossum MCP Server."""
+
+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.engines import register_engine_tools
+from rossum_mcp.tools.hooks import register_hook_tools
+from rossum_mcp.tools.queues import register_queue_tools
+from rossum_mcp.tools.relations import register_relation_tools
+from rossum_mcp.tools.rules import register_rule_tools
+from rossum_mcp.tools.schemas import register_schema_tools
+from rossum_mcp.tools.users import register_user_tools
+from rossum_mcp.tools.workspaces import register_workspace_tools
+
+__all__ = [
+    "register_annotation_tools",
+    "register_document_relation_tools",
+    "register_engine_tools",
+    "register_hook_tools",
+    "register_queue_tools",
+    "register_relation_tools",
+    "register_rule_tools",
+    "register_schema_tools",
+    "register_user_tools",
+    "register_workspace_tools",
+]

rossum_mcp/tools/annotations.py

@@ -0,0 +1,130 @@
+"""Annotation tools for Rossum MCP Server."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence  # noqa: TC003 - needed at runtime for FastMCP
+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_mcp.tools.base import is_read_write_mode
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+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
+    """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.",
+        }
+
+    @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
+
+    @mcp.tool(description="List annotations for a queue.")
+    async def list_annotations(
+        queue_id: int, status: str | None = "importing,to_review,confirmed,exported"
+    ) -> 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
+
+    @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'.",
+        }
+
+    @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.",
+        }
+
+    @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'.",
+        }

rossum_mcp/tools/base.py

@@ -0,0 +1,18 @@
+"""Base utilities for Rossum MCP tools."""
+
+from __future__ import annotations
+
+import os
+
+BASE_URL = os.environ.get("ROSSUM_API_BASE_URL", "").rstrip("/")
+MODE = os.environ.get("ROSSUM_MCP_MODE", "read-write").lower()
+
+
+def build_resource_url(resource_type: str, resource_id: int) -> str:
+    """Build a full URL for a Rossum API resource."""
+    return f"{BASE_URL}/{resource_type}/{resource_id}"
+
+
+def is_read_write_mode() -> bool:
+    """Check if server is in read-write mode."""
+    return MODE == "read-write"

rossum_mcp/tools/document_relations.py

@@ -0,0 +1,58 @@
+"""Document relation tools for Rossum MCP Server."""
+
+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
+)
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+logger = logging.getLogger(__name__)
+
+
+def register_document_relation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
+    """Register document relation-related tools with the FastMCP server."""
+
+    @mcp.tool(description="Retrieve document relation details.")
+    async def get_document_relation(document_relation_id: int) -> DocumentRelation:
+        """Retrieve document relation details."""
+        logger.debug(f"Retrieving document relation: document_relation_id={document_relation_id}")
+        document_relation: DocumentRelation = await client.retrieve_document_relation(document_relation_id)
+        return document_relation
+
+    @mcp.tool(
+        description="List all document relations with optional filters. Document relations introduce additional relations between annotations and documents (export, einvoice)."
+    )
+    async def list_document_relations(
+        id: int | None = None,
+        type: str | None = None,
+        annotation: int | None = None,
+        key: str | None = None,
+        documents: int | None = None,
+    ) -> list[DocumentRelation]:
+        """List all document relations with optional filters."""
+        logger.debug(
+            f"Listing document relations: id={id}, type={type}, annotation={annotation}, key={key}, documents={documents}"
+        )
+        filters: dict[str, int | str] = {}
+        if id is not None:
+            filters["id"] = id
+        if type is not None:
+            filters["type"] = type
+        if annotation is not None:
+            filters["annotation"] = annotation
+        if key is not None:
+            filters["key"] = key
+        if documents is not None:
+            filters["documents"] = documents
+
+        return [
+            document_relation
+            async for document_relation in client.list_document_relations(**filters)  # type: ignore[arg-type]
+        ]

rossum_mcp/tools/engines.py

@@ -0,0 +1,130 @@
+"""Engine tools for Rossum MCP Server."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Literal
+
+from rossum_api.domain_logic.resources import Resource
+from rossum_api.models.engine import (
+    Engine,  # noqa: TC002 - needed at runtime for FastMCP
+    EngineField,  # noqa: TC002 - needed at runtime for FastMCP
+    EngineFieldType,  # noqa: TC002 - needed at runtime for FastMCP
+)
+
+from rossum_mcp.tools.base import build_resource_url, is_read_write_mode
+
+type EngineType = Literal["extractor", "splitter"]
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+logger = logging.getLogger(__name__)
+
+
+def register_engine_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:  # noqa: C901
+    """Register engine-related tools with the FastMCP server."""
+
+    @mcp.tool(description="Retrieve a single engine by ID.")
+    async def get_engine(engine_id: int) -> Engine:
+        """Retrieve a single engine by ID."""
+        logger.debug(f"Retrieving engine: engine_id={engine_id}")
+        engine: Engine = await client.retrieve_engine(engine_id)
+        return engine
+
+    @mcp.tool(description="List all engines with optional filters.")
+    async def list_engines(
+        id: int | None = None, engine_type: EngineType | None = None, agenda_id: str | None = None
+    ) -> list[Engine]:
+        """List all engines with optional filters."""
+        logger.debug(f"Listing engines: id={id}, type={engine_type}, agenda_id={agenda_id}")
+        filters: dict[str, int | str] = {}
+        if id is not None:
+            filters["id"] = id
+        if engine_type is not None:
+            filters["type"] = engine_type
+        if agenda_id is not None:
+            filters["agenda_id"] = agenda_id
+        return [engine async for engine in client.list_engines(**filters)]  # type: ignore[arg-type]
+
+    @mcp.tool(description="Update engine settings.")
+    async def update_engine(engine_id: int, engine_data: dict) -> Engine | dict:
+        """Update an existing engine's settings."""
+        if not is_read_write_mode():
+            return {"error": "update_engine is not available in read-only mode"}
+
+        logger.debug(f"Updating engine: engine_id={engine_id}, data={engine_data}")
+        updated_engine_data = await client._http_client.update(Resource.Engine, engine_id, engine_data)
+        updated_engine: Engine = client._deserializer(Resource.Engine, updated_engine_data)
+        return updated_engine
+
+    @mcp.tool(
+        description="Create a new engine. IMPORTANT: When creating a new engine, check the schema to be used and create contained Engine fields immediately!"
+    )
+    async def create_engine(name: str, organization_id: int, engine_type: EngineType) -> Engine | dict:
+        """Create a new engine."""
+        if not is_read_write_mode():
+            return {"error": "create_engine is not available in read-only mode"}
+
+        if engine_type not in ("extractor", "splitter"):
+            raise ValueError(f"Invalid engine_type '{engine_type}'. Must be 'extractor' or 'splitter'")
+
+        logger.debug(f"Creating engine: name={name}, organization_id={organization_id}, type={engine_type}")
+        engine_data = {
+            "name": name,
+            "organization": build_resource_url("organizations", organization_id),
+            "type": engine_type,
+        }
+        engine_response = await client._http_client.create(Resource.Engine, engine_data)
+        engine: Engine = client._deserializer(Resource.Engine, engine_response)
+        return engine
+
+    @mcp.tool(description="Create engine field for each schema field. Must be called when creating engine + schema.")
+    async def create_engine_field(
+        engine_id: int,
+        name: str,
+        label: str,
+        field_type: EngineFieldType,
+        schema_ids: list[int],
+        tabular: bool = False,
+        multiline: str = "false",
+        subtype: str | None = None,
+        pre_trained_field_id: str | None = None,
+    ) -> EngineField | dict:
+        """Create a new engine field and link it to schemas."""
+        if not is_read_write_mode():
+            return {"error": "create_engine_field is not available in read-only mode"}
+
+        valid_types = ("string", "number", "date", "enum")
+        if field_type not in valid_types:
+            raise ValueError(f"Invalid field_type '{field_type}'. Must be one of: {', '.join(valid_types)}")
+        if not schema_ids:
+            raise ValueError("schema_ids cannot be empty - engine field must be linked to at least one schema")
+
+        logger.debug(
+            f"Creating engine field: engine_id={engine_id}, name={name}, type={field_type}, schemas={schema_ids}"
+        )
+        engine_field_data = {
+            "engine": build_resource_url("engines", engine_id),
+            "name": name,
+            "label": label,
+            "type": field_type,
+            "tabular": tabular,
+            "multiline": multiline,
+            "schemas": [build_resource_url("schemas", schema_id) for schema_id in schema_ids],
+        }
+        if subtype is not None:
+            engine_field_data["subtype"] = subtype
+        if pre_trained_field_id is not None:
+            engine_field_data["pre_trained_field_id"] = pre_trained_field_id
+
+        engine_field_response = await client._http_client.create(Resource.EngineField, engine_field_data)
+        engine_field: EngineField = client._deserializer(Resource.EngineField, engine_field_response)
+        return engine_field
+
+    @mcp.tool(description="Retrieve engine fields for a specific engine or all engine fields.")
+    async def get_engine_fields(engine_id: int | None = None) -> list[EngineField]:
+        """Retrieve engine fields for a specific engine or all engine fields."""
+        logger.debug(f"Retrieving engine fields: engine_id={engine_id}")
+        return [engine_field async for engine_field in client.retrieve_engine_fields(engine_id=engine_id)]