rossum-mcp 1.1.0__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.1.0"
+__version__ = "1.1.1"

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

rossum_mcp/tools/schemas/operations.py

@@ -0,0 +1,183 @@
+"""Schema CRUD operations for Rossum MCP Server."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, is_dataclass
+from typing import TYPE_CHECKING, Any
+
+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, delete_resource, is_read_write_mode
+from rossum_mcp.tools.schemas.models import SchemaNode, SchemaNodeUpdate  # noqa: TC001 - needed at runtime for FastMCP
+from rossum_mcp.tools.schemas.patching import PatchOperation, 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 sanitize_schema_content
+
+if TYPE_CHECKING:
+    from rossum_api import AsyncRossumAPIClient
+
+logger = logging.getLogger(__name__)
+
+
+def _truncate_schema_for_list(schema: Schema) -> Schema:
+    """Truncate content field in schema to save context in list responses."""
+    from dataclasses import replace  # noqa: PLC0415 - avoid circular import with models
+
+    return replace(schema, content=TRUNCATED_MARKER)
+
+
+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
+
+
+async def list_schemas(
+    client: AsyncRossumAPIClient, name: str | None = None, queue_id: int | None = None
+) -> list[Schema]:
+    logger.debug(f"Listing schemas: name={name}, queue_id={queue_id}")
+    filters: dict[str, int | str] = {}
+    if name is not None:
+        filters["name"] = name
+    if queue_id is not None:
+        filters["queue"] = queue_id
+
+    schemas = [schema async for schema in client.list_schemas(**filters)]  # type: ignore[arg-type]
+    return [_truncate_schema_for_list(schema) for schema in schemas]
+
+
+async def update_schema(client: AsyncRossumAPIClient, schema_id: int, schema_data: dict) -> Schema | dict:
+    if not is_read_write_mode():
+        return {"error": "update_schema is not available in read-only mode"}
+
+    logger.debug(f"Updating schema: schema_id={schema_id}")
+    await client._http_client.update(Resource.Schema, schema_id, schema_data)
+    updated_schema: Schema = await client.retrieve_schema(schema_id)
+    return updated_schema
+
+
+async def create_schema(client: AsyncRossumAPIClient, name: str, content: list[dict]) -> Schema | dict:
+    if not is_read_write_mode():
+        return {"error": "create_schema is not available in read-only mode"}
+
+    logger.debug(f"Creating schema: name={name}")
+    sanitized_content = sanitize_schema_content(content)
+    schema_data = {"name": name, "content": sanitized_content}
+    schema: Schema = await client.create_new_schema(schema_data)
+    return schema
+
+
+async def patch_schema(
+    client: AsyncRossumAPIClient,
+    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:
+    if not is_read_write_mode():
+        return {"error": "patch_schema is not available in read-only mode"}
+
+    if operation not in ("add", "update", "remove"):
+        return {"error": f"Invalid operation '{operation}'. Must be 'add', 'update', or 'remove'."}
+
+    logger.debug(f"Patching schema: schema_id={schema_id}, operation={operation}, node_id={node_id}")
+
+    node_data_dict: dict | None = None
+    if node_data is not None:
+        if isinstance(node_data, dict):
+            node_data_dict = node_data
+        elif hasattr(node_data, "to_dict"):
+            node_data_dict = node_data.to_dict()
+        else:
+            node_data_dict = asdict(node_data)
+
+    current_schema: dict = await client._http_client.request_json("GET", f"schemas/{schema_id}")
+    content_list = current_schema.get("content", [])
+    if not isinstance(content_list, list):
+        return {"error": "Unexpected schema content format"}
+
+    try:
+        patched_content = apply_schema_patch(
+            content=content_list,
+            operation=operation,
+            node_id=node_id,
+            node_data=node_data_dict,
+            parent_id=parent_id,
+            position=position,
+        )
+    except ValueError as e:
+        return {"error": str(e)}
+
+    sanitized_content = sanitize_schema_content(patched_content)
+    await client._http_client.update(Resource.Schema, schema_id, {"content": sanitized_content})
+    updated_schema: Schema = await client.retrieve_schema(schema_id)
+    return updated_schema
+
+
+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
+    ]
+    return _extract_schema_tree(content_dicts)
+
+
+async def prune_schema_fields(
+    client: AsyncRossumAPIClient,
+    schema_id: int,
+    fields_to_keep: list[str] | None = None,
+    fields_to_remove: list[str] | None = None,
+) -> dict:
+    if not is_read_write_mode():
+        return {"error": "prune_schema_fields is not available in read-only mode"}
+
+    if fields_to_keep and fields_to_remove:
+        return {"error": "Specify fields_to_keep OR fields_to_remove, not both"}
+    if not fields_to_keep and not fields_to_remove:
+        return {"error": "Must specify fields_to_keep or fields_to_remove"}
+
+    current_schema: dict = await client._http_client.request_json("GET", f"schemas/{schema_id}")
+    content = current_schema.get("content", [])
+    if not isinstance(content, list):
+        return {"error": "Unexpected schema content format"}
+    all_ids = _collect_all_field_ids(content)
+
+    section_ids = {s.get("id") for s in content if s.get("category") == "section"}
+
+    if fields_to_keep:
+        fields_to_keep_set = set(fields_to_keep) | section_ids
+        ancestor_ids = _collect_ancestor_ids(content, fields_to_keep_set)
+        fields_to_keep_set |= ancestor_ids
+        remove_set = all_ids - fields_to_keep_set
+    else:
+        remove_set = set(fields_to_remove) - section_ids  # type: ignore[arg-type]
+
+    if not remove_set:
+        return {"removed_fields": [], "remaining_fields": sorted(all_ids)}
+
+    pruned_content, removed = _remove_fields_from_content(content, remove_set)
+    await client._http_client.update(Resource.Schema, schema_id, {"content": pruned_content})
+
+    remaining_ids = _collect_all_field_ids(pruned_content)
+    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)