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

rossum_mcp/__init__.py

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

rossum_mcp/server.py

@@ -29,6 +29,7 @@ from rossum_mcp.tools import (
     register_user_tools,
     register_workspace_tools,
 )
+from rossum_mcp.tools.base import get_mcp_mode, set_mcp_mode
 
 setup_logging(app_name="rossum-mcp-server", log_level="DEBUG", use_console=False)
 
@@ -36,12 +37,8 @@ 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")
+logger.info(f"Rossum MCP Server starting in {get_mcp_mode()} mode")
 
 mcp = FastMCP("rossum-mcp-server")
 client = AsyncRossumAPIClient(base_url=BASE_URL, credentials=Token(token=API_TOKEN))
@@ -60,6 +57,22 @@ register_user_tools(mcp, client)
 register_workspace_tools(mcp, client)
 
 
+@mcp.tool(description="Get the current MCP operation mode (read-only or read-write).")
+async def get_mcp_mode_tool() -> dict:
+    return {"mode": get_mcp_mode()}
+
+
+@mcp.tool(
+    description="Set the MCP operation mode. Use 'read-only' to disable write operations, 'read-write' to enable them."
+)
+async def set_mcp_mode_tool(mode: str) -> dict:
+    try:
+        set_mcp_mode(mode)
+        return {"message": f"MCP mode set to '{get_mcp_mode()}'"}
+    except ValueError as e:
+        return {"error": str(e)}
+
+
 def main() -> None:
     """Main entry point for console script."""
     mcp.run()

rossum_mcp/tools/base.py

@@ -13,11 +13,30 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 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>"
 
+VALID_MODES = ("read-only", "read-write")
+
+_mcp_mode = os.environ.get("ROSSUM_MCP_MODE", "read-write").lower()
+if _mcp_mode not in VALID_MODES:
+    raise ValueError(f"Invalid ROSSUM_MCP_MODE: {_mcp_mode}. Must be one of: {VALID_MODES}")
+
+
+def get_mcp_mode() -> str:
+    """Return the current MCP mode."""
+    return _mcp_mode
+
+
+def set_mcp_mode(mode: str) -> None:
+    """Set the MCP mode (case-insensitive)."""
+    global _mcp_mode
+    normalized = mode.lower()
+    if normalized not in VALID_MODES:
+        raise ValueError(f"Invalid mode '{mode}'. Must be one of: {VALID_MODES}")
+    _mcp_mode = normalized
+
 
 def build_resource_url(resource_type: str, resource_id: int) -> str:
     """Build a full URL for a Rossum API resource."""
@@ -26,7 +45,7 @@ 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"
+    return _mcp_mode == "read-write"
 
 
 def truncate_dict_fields(data: dict[str, Any], fields: tuple[str, ...]) -> dict[str, Any]:

rossum_mcp/tools/catalog.py

@@ -139,6 +139,9 @@ TOOL_CATALOG: dict[str, ToolCategory] = {
         tools=[
             ToolInfo("get_rule", "Retrieve rule details"),
             ToolInfo("list_rules", "List validation rules"),
+            ToolInfo("create_rule", "Create validation rule", read_only=False),
+            ToolInfo("update_rule", "Full update rule (PUT)", read_only=False),
+            ToolInfo("patch_rule", "Partial update rule (PATCH)", read_only=False),
             ToolInfo("delete_rule", "Delete rule", read_only=False),
         ],
         keywords=["rule", "validation", "constraint"],

rossum_mcp/tools/rules.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal, TypedDict
 
+from rossum_api.domain_logic.resources import Resource
 from rossum_api.models.rule import Rule
 
-from rossum_mcp.tools.base import delete_resource
+from rossum_mcp.tools.base import build_resource_url, delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -16,6 +17,42 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+RuleActionType = Literal[
+    "show_message",
+    "add_automation_blocker",
+    "add_validation_source",
+    "change_queue",
+    "send_email",
+    "hide_field",
+    "show_field",
+    "show_hide_field",
+    "change_status",
+    "add_label",
+    "remove_label",
+    "custom",
+]
+
+
+class RuleActionPayload(TypedDict, total=False):
+    """Payload for rule actions. Fields depend on action type."""
+
+    type: Literal["info", "warning", "error"]  # for show_message
+    content: str  # message content or template
+    schema_id: str  # target field schema_id
+    queue_url: str  # for change_queue
+    status: str  # for change_status
+    label: str  # for add_label/remove_label
+
+
+class RuleAction(TypedDict):
+    """Rule action definition."""
+
+    id: str  # unique action identifier
+    type: RuleActionType
+    event: Literal["validation"]
+    payload: RuleActionPayload
+
+
 async def _get_rule(client: AsyncRossumAPIClient, rule_id: int) -> Rule:
     logger.debug(f"Retrieving rule: rule_id={rule_id}")
     rule: Rule = await client.retrieve_rule(rule_id)
@@ -41,6 +78,108 @@ async def _list_rules(
     return rules_list
 
 
+async def _create_rule(
+    client: AsyncRossumAPIClient,
+    name: str,
+    schema_id: int,
+    trigger_condition: str,
+    actions: list[RuleAction],
+    enabled: bool = True,
+    queue_ids: list[int] | None = None,
+) -> Rule | dict:
+    if not is_read_write_mode():
+        return {"error": "create_rule is not available in read-only mode"}
+
+    schema_url = build_resource_url("schemas", schema_id)
+    logger.info(f"Creating rule: name={name}, schema_id={schema_id}, enabled={enabled}")
+
+    rule_data: dict = {
+        "name": name,
+        "schema": schema_url,
+        "trigger_condition": trigger_condition,
+        "actions": actions,
+        "enabled": enabled,
+    }
+
+    if queue_ids is not None:
+        rule_data["queues"] = [build_resource_url("queues", qid) for qid in queue_ids]
+
+    logger.debug(f"Rule creation payload: {rule_data}")
+    rule: Rule = await client.create_new_rule(rule_data)
+    logger.info(f"Successfully created rule: id={rule.id}, name={rule.name}")
+    return rule
+
+
+async def _update_rule(
+    client: AsyncRossumAPIClient,
+    rule_id: int,
+    name: str,
+    trigger_condition: str,
+    actions: list[RuleAction],
+    enabled: bool,
+    queue_ids: list[int] | None = None,
+) -> Rule | dict:
+    """Full update (PUT) - all fields required."""
+    if not is_read_write_mode():
+        return {"error": "update_rule is not available in read-only mode"}
+
+    logger.info(f"Updating rule: rule_id={rule_id}, name={name}")
+    existing_rule: Rule = await client.retrieve_rule(rule_id)
+
+    rule_data: dict = {
+        "name": name,
+        "schema": existing_rule.schema,
+        "trigger_condition": trigger_condition,
+        "actions": actions,
+        "enabled": enabled,
+    }
+
+    if queue_ids is not None:
+        rule_data["queues"] = [build_resource_url("queues", qid) for qid in queue_ids]
+
+    logger.debug(f"Rule update payload: {rule_data}")
+    await client._http_client.update(Resource.Rule, rule_id, rule_data)
+    updated_rule: Rule = await client.retrieve_rule(rule_id)
+    logger.info(f"Successfully updated rule: id={updated_rule.id}")
+    return updated_rule
+
+
+async def _patch_rule(
+    client: AsyncRossumAPIClient,
+    rule_id: int,
+    name: str | None = None,
+    trigger_condition: str | None = None,
+    actions: list[RuleAction] | None = None,
+    enabled: bool | None = None,
+    queue_ids: list[int] | None = None,
+) -> Rule | dict:
+    """Partial update (PATCH) - only provided fields are updated."""
+    if not is_read_write_mode():
+        return {"error": "patch_rule is not available in read-only mode"}
+
+    logger.info(f"Patching rule: rule_id={rule_id}")
+
+    patch_data: dict = {}
+    if name is not None:
+        patch_data["name"] = name
+    if trigger_condition is not None:
+        patch_data["trigger_condition"] = trigger_condition
+    if actions is not None:
+        patch_data["actions"] = actions
+    if enabled is not None:
+        patch_data["enabled"] = enabled
+    if queue_ids is not None:
+        patch_data["queues"] = [build_resource_url("queues", qid) for qid in queue_ids]
+
+    if not patch_data:
+        return {"error": "No fields provided to update"}
+
+    logger.debug(f"Rule patch payload: {patch_data}")
+    updated_rule: Rule = await client.update_part_rule(rule_id, patch_data)
+    logger.info(f"Successfully patched rule: id={updated_rule.id}")
+    return updated_rule
+
+
 async def _delete_rule(client: AsyncRossumAPIClient, rule_id: int) -> dict:
     return await delete_resource("rule", rule_id, client.delete_rule)
 
@@ -58,6 +197,45 @@ def register_rule_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     ) -> list[Rule]:
         return await _list_rules(client, schema_id, organization_id, enabled)
 
+    @mcp.tool(
+        description="Create a new rule. Rules automate field operations based on trigger conditions (TxScript formulas like 'field.amount > 1000'). Actions require: id (unique str), type (show_message|hide_field|show_field|change_status|custom|etc), event (validation), payload (dict with type, content, schema_id for show_message). queue_ids limits rule to specific queues."
+    )
+    async def create_rule(
+        name: str,
+        schema_id: int,
+        trigger_condition: str,
+        actions: list[RuleAction],
+        enabled: bool = True,
+        queue_ids: list[int] | None = None,
+    ) -> Rule | dict:
+        return await _create_rule(client, name, schema_id, trigger_condition, actions, enabled, queue_ids)
+
+    @mcp.tool(
+        description="Full update of a rule (PUT). All fields required. Use patch_rule for partial updates. queue_ids limits rule to specific queues."
+    )
+    async def update_rule(
+        rule_id: int,
+        name: str,
+        trigger_condition: str,
+        actions: list[RuleAction],
+        enabled: bool,
+        queue_ids: list[int] | None = None,
+    ) -> Rule | dict:
+        return await _update_rule(client, rule_id, name, trigger_condition, actions, enabled, queue_ids)
+
+    @mcp.tool(
+        description="Partial update of a rule (PATCH). Only provided fields are updated. queue_ids limits rule to specific queues (empty list removes all)."
+    )
+    async def patch_rule(
+        rule_id: int,
+        name: str | None = None,
+        trigger_condition: str | None = None,
+        actions: list[RuleAction] | None = None,
+        enabled: bool | None = None,
+        queue_ids: list[int] | None = None,
+    ) -> Rule | dict:
+        return await _patch_rule(client, rule_id, name, trigger_condition, actions, enabled, queue_ids)
+
     @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/__init__.py

@@ -0,0 +1,182 @@
+"""Schema tools for Rossum MCP Server."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rossum_api.models.schema import Schema
+
+from rossum_mcp.tools.schemas.models import (
+    DatapointType,
+    NodeCategory,
+    SchemaDatapoint,
+    SchemaMultivalue,
+    SchemaNode,
+    SchemaNodeUpdate,
+    SchemaTreeNode,
+    SchemaTuple,
+)
+from rossum_mcp.tools.schemas.operations import (
+    create_schema,
+    delete_schema,
+    get_schema,
+    get_schema_tree_structure,
+    list_schemas,
+    patch_schema,
+    prune_schema_fields,
+    update_schema,
+)
+from rossum_mcp.tools.schemas.patching import (
+    PatchOperation,
+    _apply_add_operation,
+    _apply_remove_operation,
+    _apply_update_operation,
+    _find_node_anywhere,
+    _find_node_in_children,
+    _find_parent_children_list,
+    _get_section_children_as_list,
+    apply_schema_patch,
+)
+from rossum_mcp.tools.schemas.pruning import (
+    _collect_all_field_ids,
+    _collect_ancestor_ids,
+    _extract_schema_tree,
+    _remove_fields_from_content,
+)
+from rossum_mcp.tools.schemas.validation import (
+    MAX_ID_LENGTH,
+    VALID_DATAPOINT_TYPES,
+    VALID_UI_CONFIGURATION_EDIT,
+    VALID_UI_CONFIGURATION_TYPES,
+    SchemaValidationError,
+    _validate_datapoint,
+    _validate_id,
+    _validate_multivalue,
+    _validate_node,
+    _validate_section,
+    _validate_tuple,
+    sanitize_schema_content,
+)
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+    from rossum_api import AsyncRossumAPIClient
+
+__all__ = [
+    "MAX_ID_LENGTH",
+    "VALID_DATAPOINT_TYPES",
+    "VALID_UI_CONFIGURATION_EDIT",
+    "VALID_UI_CONFIGURATION_TYPES",
+    "DatapointType",
+    "NodeCategory",
+    "PatchOperation",
+    "SchemaDatapoint",
+    "SchemaMultivalue",
+    "SchemaNode",
+    "SchemaNodeUpdate",
+    "SchemaTreeNode",
+    "SchemaTuple",
+    "SchemaValidationError",
+    "_apply_add_operation",
+    "_apply_remove_operation",
+    "_apply_update_operation",
+    "_collect_all_field_ids",
+    "_collect_ancestor_ids",
+    "_extract_schema_tree",
+    "_find_node_anywhere",
+    "_find_node_in_children",
+    "_find_parent_children_list",
+    "_get_section_children_as_list",
+    "_remove_fields_from_content",
+    "_validate_datapoint",
+    "_validate_id",
+    "_validate_multivalue",
+    "_validate_node",
+    "_validate_section",
+    "_validate_tuple",
+    "apply_schema_patch",
+    "create_schema",
+    "delete_schema",
+    "get_schema",
+    "get_schema_tree_structure",
+    "list_schemas",
+    "patch_schema",
+    "prune_schema_fields",
+    "register_schema_tools",
+    "sanitize_schema_content",
+    "update_schema",
+]
+
+
+def register_schema_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
+    """Register schema-related tools with the FastMCP server."""
+    from rossum_mcp.tools.schemas import operations as ops  # noqa: PLC0415 - avoid circular import
+
+    @mcp.tool(description="Retrieve schema details.")
+    async def get_schema(schema_id: int) -> Schema | dict:
+        return await ops.get_schema(client, schema_id)
+
+    @mcp.tool(description="List all schemas with optional filters.")
+    async def list_schemas(name: str | None = None, queue_id: int | None = None) -> list[Schema]:
+        return await ops.list_schemas(client, name, queue_id)
+
+    @mcp.tool(description="Update schema, typically for field-level thresholds.")
+    async def update_schema(schema_id: int, schema_data: dict) -> Schema | dict:
+        return await ops.update_schema(client, schema_id, schema_data)
+
+    @mcp.tool(description="Create a schema. Must have ≥1 section with children (datapoints).")
+    async def create_schema(name: str, content: list[dict]) -> Schema | dict:
+        return await ops.create_schema(client, name, content)
+
+    @mcp.tool(
+        description="""Patch schema nodes (add/update/remove fields in a schema).
+
+You MUST load `schema-patching` skill first to avoid errors.
+
+Operations:
+- add: Create new field. Requires parent_id (section or tuple id) and node_data.
+- update: Modify existing field. Requires node_data with fields to change.
+- remove: Delete field. Only requires node_id.
+
+Node types for add:
+- Datapoint (simple field): {"label": "Field Name", "category": "datapoint", "type": "string|number|date|enum"}
+- Enum field: Include "options": [{"value": "v1", "label": "Label 1"}, ...]
+- Multivalue (table): {"label": "Table", "category": "multivalue", "children": <tuple>}
+- Tuple (table row): {"id": "row_id", "label": "Row", "category": "tuple", "children": [<datapoints with id>]}
+
+Important: Datapoints inside a tuple MUST have an "id" field. Section-level datapoints get id from node_id parameter.
+"""
+    )
+    async def patch_schema(
+        schema_id: int,
+        operation: PatchOperation,
+        node_id: str,
+        node_data: SchemaNode | SchemaNodeUpdate | None = None,
+        parent_id: str | None = None,
+        position: int | None = None,
+    ) -> Schema | dict:
+        return await ops.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] | dict:
+        return await ops.get_schema_tree_structure(client, schema_id)
+
+    @mcp.tool(
+        description="""Remove multiple fields from schema at once. Efficient for pruning unwanted fields during setup.
+
+Use fields_to_keep OR fields_to_remove (not both):
+- fields_to_keep: Keep only these field IDs (plus sections). All others removed.
+- fields_to_remove: Remove these specific field IDs.
+
+Returns dict with removed_fields and remaining_fields lists. Sections cannot be removed."""
+    )
+    async def prune_schema_fields(
+        schema_id: int,
+        fields_to_keep: list[str] | None = None,
+        fields_to_remove: list[str] | None = None,
+    ) -> dict:
+        return await ops.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 ops.delete_schema(client, schema_id)

rossum_mcp/tools/schemas/models.py

@@ -0,0 +1,151 @@
+"""Schema dataclass models for Rossum MCP Server."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Literal
+
+DatapointType = Literal["string", "number", "date", "enum", "button"]
+NodeCategory = Literal["datapoint", "multivalue", "tuple"]
+
+
+@dataclass
+class SchemaDatapoint:
+    """A datapoint node for schema patch operations.
+
+    Use for adding/updating fields that capture or display values.
+    When used inside a tuple (table), id is required.
+    """
+
+    label: str
+    id: str | None = None
+    category: Literal["datapoint"] = "datapoint"
+    type: DatapointType | None = None
+    rir_field_names: list[str] | None = None
+    default_value: str | None = None
+    score_threshold: float | None = None
+    hidden: bool = False
+    disable_prediction: bool = False
+    can_export: bool = True
+    constraints: dict | None = None
+    options: list[dict] | None = None
+    ui_configuration: dict | None = None
+    formula: str | None = None
+    prompt: str | None = None
+    context: list[str] | None = None
+    width: int | None = None
+    stretch: bool | None = None
+
+    def to_dict(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+@dataclass
+class SchemaTuple:
+    """A tuple node for schema patch operations.
+
+    Use within multivalue to define table row structure with multiple columns.
+    """
+
+    id: str
+    label: str
+    children: list[SchemaDatapoint]
+    category: Literal["tuple"] = "tuple"
+    hidden: bool = False
+
+    def to_dict(self) -> dict:
+        """Convert to dict, excluding None values."""
+        result: dict = {"id": self.id, "category": self.category, "label": self.label}
+        if self.hidden:
+            result["hidden"] = self.hidden
+        result["children"] = [child.to_dict() for child in self.children]
+        return result
+
+
+@dataclass
+class SchemaMultivalue:
+    """A multivalue node for schema patch operations.
+
+    Use for repeating fields or tables. Children is a single Tuple or Datapoint (NOT a list).
+    The id is optional here since it gets set from node_id in patch_schema.
+    """
+
+    label: str
+    children: SchemaTuple | SchemaDatapoint
+    id: str | None = None
+    category: Literal["multivalue"] = "multivalue"
+    rir_field_names: list[str] | None = None
+    min_occurrences: int | None = None
+    max_occurrences: int | None = None
+    hidden: bool = False
+
+    def to_dict(self) -> dict:
+        """Convert to dict, excluding None values."""
+        result: dict = {"label": self.label, "category": self.category}
+        if self.id:
+            result["id"] = self.id
+        if self.rir_field_names:
+            result["rir_field_names"] = self.rir_field_names
+        if self.min_occurrences is not None:
+            result["min_occurrences"] = self.min_occurrences
+        if self.max_occurrences is not None:
+            result["max_occurrences"] = self.max_occurrences
+        if self.hidden:
+            result["hidden"] = self.hidden
+        result["children"] = self.children.to_dict()
+        return result
+
+
+@dataclass
+class SchemaNodeUpdate:
+    """Partial update for an existing schema node.
+
+    Only include fields you want to update - all fields are optional.
+    """
+
+    label: str | None = None
+    type: DatapointType | None = None
+    score_threshold: float | None = None
+    hidden: bool | None = None
+    disable_prediction: bool | None = None
+    can_export: bool | None = None
+    default_value: str | None = None
+    rir_field_names: list[str] | None = None
+    constraints: dict | None = None
+    options: list[dict] | None = None
+    ui_configuration: dict | None = None
+    formula: str | None = None
+    prompt: str | None = None
+    context: list[str] | None = None
+    width: int | None = None
+    stretch: bool | None = None
+    min_occurrences: int | None = None
+    max_occurrences: int | None = None
+
+    def to_dict(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+@dataclass
+class SchemaTreeNode:
+    """Lightweight schema node for tree structure display."""
+
+    id: str
+    label: str
+    category: str
+    type: str | None = None
+    children: list[SchemaTreeNode] | None = None
+
+    def to_dict(self) -> dict:
+        """Convert to dict, excluding None values."""
+        result: dict = {"id": self.id, "label": self.label, "category": self.category}
+        if self.type:
+            result["type"] = self.type
+        if self.children:
+            result["children"] = [child.to_dict() for child in self.children]
+        return result
+
+
+SchemaNode = SchemaDatapoint | SchemaMultivalue | SchemaTuple