rossum-mcp 0.3.4__tar.gz → 0.4.0__tar.gz

{rossum_mcp-0.3.4/rossum_mcp.egg-info → rossum_mcp-0.4.0}/PKG-INFO

@@ -1,10 +1,19 @@
 Metadata-Version: 2.4
 Name: rossum-mcp
-Version: 0.3.4
+Version: 0.4.0
 Summary: MCP server for AI-powered Rossum orchestration: document workflows, debug pipelines automatically, and configure intelligent document processing through natural language.
 Author-email: "Dan Stancl (Rossum AI)" <daniel.stancl@gmail.com>
 License: MIT
 Keywords: mcp,rossum,document-processing
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 Requires-Dist: fastmcp>2.0.0
@@ -43,17 +52,31 @@ Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "all"
 [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://stancld.github.io/rossum-mcp/)
 [![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)
-[![MCP Tools](https://img.shields.io/badge/MCP_Tools-39-blue.svg)](#available-tools)
+[![PyPI - rossum-mcp](https://img.shields.io/pypi/v/rossum-mcp?label=rossum-mcp)](https://pypi.org/project/rossum-mcp/)
+[![Coverage](https://codecov.io/gh/stancld/rossum-mcp/branch/master/graph/badge.svg?flag=rossum-mcp)](https://codecov.io/gh/stancld/rossum-mcp)
+[![MCP Tools](https://img.shields.io/badge/MCP_Tools-50-blue.svg)](#available-tools)
+
 [![Rossum API](https://img.shields.io/badge/Rossum-API-orange.svg)](https://github.com/rossumai/rossum-api)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 
 </div>
 
 A Model Context Protocol (MCP) server that provides tools for uploading documents and retrieving annotations using the Rossum API. Built with Python and the official [rossum-api](https://github.com/rossumai/rossum-api).
 
+> [!NOTE]
+> This is not an official Rossum project. It is a community-developed integration built on top of the Rossum API.
+
+> [!WARNING]
+> This project is in early stage development. Breaking changes to both implementation and agent behavior are expected.
+
 ## Features
 
-### Document Processing
+<details>
+<summary><strong>Document Processing (6 tools)</strong></summary>
+
 - **upload_document**: Upload a document to Rossum for processing
 - **get_annotation**: Retrieve annotation data for a previously uploaded document
 - **list_annotations**: List all annotations for a queue with optional filtering
@@ -61,9 +84,16 @@ A Model Context Protocol (MCP) server that provides tools for uploading document
 - **bulk_update_annotation_fields**: Bulk update annotation field values using JSON Patch operations
 - **confirm_annotation**: Confirm annotation to move it to 'confirmed' status
 
-### Queue & Schema Management
+</details>
+
+<details>
+<summary><strong>Queue & Schema Management (13 tools)</strong></summary>
+
 - **get_queue**: Retrieve queue details including schema_id
+- **list_queues**: List all queues with optional filtering by workspace or name
 - **get_schema**: Retrieve schema details and content
+- **list_schemas**: List all schemas with optional filtering by name or queue
+- **get_schema_tree_structure**: Get lightweight tree view of schema with only ids, labels, categories, and types
 - **get_queue_schema**: Retrieve complete schema for a queue in a single call
 - **get_queue_engine**: Retrieve engine information for a queue
 - **create_queue**: Create a new queue with schema and optional engine assignment
@@ -71,18 +101,31 @@ A Model Context Protocol (MCP) server that provides tools for uploading document
 - **update_queue**: Update queue settings including automation thresholds
 - **update_schema**: Update schema with field-level automation thresholds
 - **patch_schema**: Add, update, or remove individual schema nodes without replacing entire content
+- **prune_schema_fields**: Efficiently remove multiple fields from schema at once (for organization setup)
+
+</details>
+
+<details>
+<summary><strong>Workspace Management (3 tools)</strong></summary>
 
-### Workspace Management
 - **get_workspace**: Retrieve workspace details by ID
 - **list_workspaces**: List all workspaces with optional filtering
 - **create_workspace**: Create a new workspace
 
-### User Management
+</details>
+
+<details>
+<summary><strong>User Management (3 tools)</strong></summary>
+
 - **get_user**: Retrieve user details by ID
 - **list_users**: List users with optional filtering by username, email, etc.
 - **list_user_roles**: List all user roles (permission groups) in the organization
 
-### Engine Management
+</details>
+
+<details>
+<summary><strong>Engine Management (6 tools)</strong></summary>
+
 - **get_engine**: Retrieve engine details by ID
 - **list_engines**: List all engines with optional filters
 - **create_engine**: Create a new engine (extractor or splitter)
@@ -90,7 +133,11 @@ A Model Context Protocol (MCP) server that provides tools for uploading document
 - **create_engine_field**: Create engine fields and link them to schemas
 - **get_engine_fields**: Retrieve engine fields for a specific engine or all engine fields
 
-### Extensions & Rules
+</details>
+
+<details>
+<summary><strong>Extensions & Rules (9 tools)</strong></summary>
+
 - **get_hook**: Get hook/extension details
 - **list_hooks**: List webhooks and serverless functions (extensions)
 - **create_hook**: Create webhooks or serverless function hooks for custom logic
@@ -101,12 +148,34 @@ A Model Context Protocol (MCP) server that provides tools for uploading document
 - **get_rule**: Get business rule details
 - **list_rules**: List business rules with trigger conditions and actions
 
-### Relations Management
+</details>
+
+<details>
+<summary><strong>Email Templates (3 tools)</strong></summary>
+
+- **get_email_template**: Retrieve email template details by ID
+- **list_email_templates**: List email templates with optional filtering by queue, type, or name
+- **create_email_template**: Create email templates for automated or manual email sending
+
+</details>
+
+<details>
+<summary><strong>Relations Management (4 tools)</strong></summary>
+
 - **get_relation**: Retrieve relation details by ID
 - **list_relations**: List all relations between annotations (edit, attachment, duplicate)
 - **get_document_relation**: Retrieve document relation details by ID
 - **list_document_relations**: List all document relations (export, einvoice)
 
+</details>
+
+<details>
+<summary><strong>Tool Discovery (1 tool)</strong></summary>
+
+- **list_tool_categories**: List all available tool categories with descriptions, tool names, and keywords for dynamic tool loading
+
+</details>
+
 ## Prerequisites
 
 - Python 3.12 or higher
@@ -160,10 +229,11 @@ uv sync --extra tests  # Testing only
 
 When `ROSSUM_MCP_MODE` is set to `read-only`, only read operations are available:
 - **Annotations:** `get_annotation`, `list_annotations`
-- **Queues:** `get_queue`, `get_queue_schema`, `get_queue_engine`
-- **Schemas:** `get_schema`
+- **Queues:** `get_queue`, `list_queues`, `get_queue_schema`, `get_queue_engine`
+- **Schemas:** `get_schema`, `list_schemas`
 - **Engines:** `get_engine`, `list_engines`, `get_engine_fields`
 - **Hooks:** `get_hook`, `list_hooks`, `list_hook_templates`, `list_hook_logs`
+- **Email Templates:** `get_email_template`, `list_email_templates`
 - **Users:** `get_user`, `list_users`, `list_user_roles`
 - **Rules:** `get_rule`, `list_rules`
 - **Relations:** `get_relation`, `list_relations`
@@ -373,6 +443,46 @@ Retrieves queue details including the schema_id.
 **Parameters:**
 - `queue_id` (integer, required): Rossum queue ID to retrieve
 
+#### list_queues
+
+Lists all queues with optional filtering by workspace or name.
+
+**Parameters:**
+- `workspace_id` (integer, optional): Filter by workspace ID
+- `name` (string, optional): Filter by queue name
+
+**Returns:**
+```json
+[
+  {
+    "id": 12345,
+    "name": "Invoice Processing",
+    "url": "https://elis.rossum.ai/api/v1/queues/12345",
+    "workspace": "https://elis.rossum.ai/api/v1/workspaces/100",
+    "schema": "https://elis.rossum.ai/api/v1/schemas/200",
+    "inbox": "https://elis.rossum.ai/api/v1/inboxes/300",
+    "status": "active",
+    "locale": "en_GB",
+    "automation_enabled": true
+  }
+]
+```
+
+**Example usage:**
+```python
+# List all queues
+all_queues = list_queues()
+
+# List queues in a specific workspace
+workspace_queues = list_queues(workspace_id=100)
+
+# List queues by name
+named_queues = list_queues(name="Invoice Processing")
+
+# Combine filters
+filtered_queues = list_queues(workspace_id=100, name="Invoice")
+```
+
 #### get_schema
 
 Retrieves schema details including the schema content/structure.
@@ -380,6 +490,44 @@ Retrieves schema details including the schema content/structure.
 **Parameters:**
 - `schema_id` (integer, required): Rossum schema ID to retrieve
 
+#### list_schemas
+
+Lists all schemas with optional filtering by name or queue.
+
+**Parameters:**
+- `name` (string, optional): Filter by schema name
+- `queue_id` (integer, optional): Filter by queue ID
+
+**Returns:**
+```json
+[
+  {
+    "id": 12345,
+    "name": "Invoice Schema",
+    "url": "https://elis.rossum.ai/api/v1/schemas/12345",
+    "queues": ["https://elis.rossum.ai/api/v1/queues/100"],
+    "content": "<omitted>",
+    "metadata": {},
+    "modified_at": "2025-01-15T10:00:00Z"
+  }
+]
+```
+
+**Example usage:**
+```python
+# List all schemas
+all_schemas = list_schemas()
+
+# List schemas by name
+named_schemas = list_schemas(name="Invoice Schema")
+
+# List schemas used by a specific queue
+queue_schemas = list_schemas(queue_id=100)
+
+# Combine filters
+filtered_schemas = list_schemas(name="Invoice", queue_id=100)
+```
+
 #### get_queue_schema
 
 Retrieves the complete schema for a queue in a single call. This is the recommended way to get a queue's schema.
@@ -1454,6 +1602,216 @@ annotation_doc_relations = list_document_relations(annotation=100)
 document_relations = list_document_relations(documents=200)
 ```
 
+### Email Templates
+
+#### get_email_template
+
+Retrieves details of a specific email template by its ID.
+
+**Parameters:**
+- `email_template_id` (integer, required): Email template ID
+
+**Returns:**
+```json
+{
+  "id": 1500,
+  "name": "Rejection Email",
+  "url": "https://elis.rossum.ai/api/v1/email_templates/1500",
+  "queue": "https://elis.rossum.ai/api/v1/queues/8199",
+  "organization": "https://elis.rossum.ai/api/v1/organizations/1",
+  "subject": "Document Rejected",
+  "message": "<p>Your document has been rejected.</p>",
+  "type": "rejection",
+  "enabled": true,
+  "automate": false,
+  "triggers": [],
+  "to": [{"type": "annotator", "value": ""}],
+  "cc": [],
+  "bcc": []
+}
+```
+
+**Example usage:**
+```python
+# Get email template details
+template = get_email_template(email_template_id=1500)
+```
+
+#### list_email_templates
+
+Lists all email templates with optional filters. Email templates define automated or manual email responses sent from Rossum queues.
+
+**Parameters:**
+- `queue_id` (integer, optional): Filter by queue ID
+- `type` (string, optional): Filter by template type ('rejection', 'rejection_default', 'email_with_no_processable_attachments', 'custom')
+- `name` (string, optional): Filter by template name
+- `first_n` (integer, optional): Limit results to first N templates
+
+**Returns:**
+```json
+{
+  "count": 2,
+  "results": [
+    {
+      "id": 1500,
+      "name": "Rejection Email",
+      "type": "rejection",
+      "queue": "https://elis.rossum.ai/api/v1/queues/8199",
+      "automate": false
+    },
+    {
+      "id": 1501,
+      "name": "No Attachments Notification",
+      "type": "email_with_no_processable_attachments",
+      "queue": "https://elis.rossum.ai/api/v1/queues/8199",
+      "automate": true
+    }
+  ]
+}
+```
+
+**Example usage:**
+```python
+# List all email templates
+all_templates = list_email_templates()
+
+# List email templates for a specific queue
+queue_templates = list_email_templates(queue_id=8199)
+
+# List rejection templates
+rejection_templates = list_email_templates(type="rejection")
+
+# List first 5 templates
+first_templates = list_email_templates(first_n=5)
+```
+
+#### create_email_template
+
+Creates a new email template. Templates can be automated to send emails automatically on specific triggers, or manual for user-initiated sending.
+
+**Parameters:**
+- `name` (string, required): Name of the email template
+- `queue` (string, required): URL of the queue to associate with
+- `subject` (string, required): Email subject line
+- `message` (string, required): Email body (HTML supported)
+- `type` (string, optional): Template type - 'rejection', 'rejection_default', 'email_with_no_processable_attachments', 'custom' (default: 'custom')
+- `automate` (boolean, optional): If true, email is sent automatically on trigger (default: false)
+- `to` (array, optional): List of recipient objects with 'type' and 'value' keys
+- `cc` (array, optional): List of CC recipient objects
+- `bcc` (array, optional): List of BCC recipient objects
+- `triggers` (array, optional): List of trigger URLs
+
+**Recipient object types:**
+- `{"type": "annotator", "value": ""}` - Send to the document annotator
+- `{"type": "constant", "value": "email@example.com"}` - Send to a fixed email address
+- `{"type": "datapoint", "value": "email_field_id"}` - Send to email from a datapoint field
+
+**Returns:**
+```json
+{
+  "id": 1502,
+  "name": "Custom Notification",
+  "url": "https://elis.rossum.ai/api/v1/email_templates/1502",
+  "queue": "https://elis.rossum.ai/api/v1/queues/8199",
+  "subject": "Document Processed",
+  "message": "<p>Your document has been processed.</p>",
+  "type": "custom",
+  "automate": true,
+  "to": [{"type": "constant", "value": "notifications@example.com"}]
+}
+```
+
+**Example usage:**
+```python
+# Create a simple custom email template
+template = create_email_template(
+    name="Processing Complete",
+    queue="https://elis.rossum.ai/api/v1/queues/8199",
+    subject="Document Processing Complete",
+    message="<p>Your document has been successfully processed.</p>"
+)
+
+# Create an automated rejection template
+template = create_email_template(
+    name="Auto Rejection",
+    queue="https://elis.rossum.ai/api/v1/queues/8199",
+    subject="Document Rejected",
+    message="<p>Your document could not be processed.</p>",
+    type="rejection",
+    automate=True,
+    to=[{"type": "annotator", "value": ""}]
+)
+
+# Create template with multiple recipients
+template = create_email_template(
+    name="Team Notification",
+    queue="https://elis.rossum.ai/api/v1/queues/8199",
+    subject="New Document",
+    message="<p>A new document has arrived.</p>",
+    to=[{"type": "constant", "value": "team@example.com"}],
+    cc=[{"type": "datapoint", "value": "sender_email"}]
+)
+```
+
+### Tool Discovery
+
+#### list_tool_categories
+
+Lists all available tool categories with their descriptions, tool names, and keywords. This enables dynamic tool loading where agents can discover and load only the tools they need for a specific task.
+
+**Parameters:**
+None
+
+**Returns:**
+```json
+[
+  {
+    "name": "annotations",
+    "description": "Document processing: upload, retrieve, update, and confirm annotations",
+    "tool_count": 6,
+    "tools": [
+      {"name": "upload_document", "description": "Upload document to queue"},
+      {"name": "get_annotation", "description": "Retrieve annotation with extracted data"}
+    ],
+    "keywords": ["annotation", "document", "upload", "extract", "confirm", "review"]
+  },
+  {
+    "name": "queues",
+    "description": "Queue management: create, configure, and list document processing queues",
+    "tool_count": 8,
+    "tools": [
+      {"name": "get_queue", "description": "Retrieve queue details"},
+      {"name": "list_queues", "description": "List all queues"}
+    ],
+    "keywords": ["queue", "inbox", "connector"]
+  }
+]
+```
+
+**Available Categories:**
+- `annotations` - Document processing tools (6 tools)
+- `queues` - Queue management tools (8 tools)
+- `schemas` - Schema management tools (7 tools)
+- `engines` - AI engine management tools (6 tools)
+- `hooks` - Extensions/webhooks tools (7 tools)
+- `email_templates` - Email template tools (3 tools)
+- `document_relations` - Document relation tools (2 tools)
+- `relations` - Annotation relation tools (2 tools)
+- `rules` - Validation rule tools (2 tools)
+- `users` - User management tools (3 tools)
+- `workspaces` - Workspace management tools (3 tools)
+
+**Example usage:**
+```python
+# Discover all tool categories
+categories = list_tool_categories()
+
+# Find categories by keyword matching
+for category in categories:
+    if "schema" in category["keywords"]:
+        print(f"Found: {category['name']} with {category['tool_count']} tools")
+```
+
 ## Annotation Status Workflow
 
 When a document is uploaded, the annotation progresses through various states: