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

rossum_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rossum MCP Server Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rossum_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: rossum-mcp
+Version: 1.0.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 :: 5 - Production/Stable
+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
+License-File: LICENSE
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: pydantic>2.0.0
+Requires-Dist: rossum-api>=3.8.0
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0.0; extra == "docs"
+Requires-Dist: sphinx>=7.0.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.25.0; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
+Provides-Extra: tests
+Requires-Dist: coverage>=7.0.0; extra == "tests"
+Requires-Dist: pytest>=7.0.0; extra == "tests"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "tests"
+Requires-Dist: pytest-cov>=4.0.0; extra == "tests"
+Requires-Dist: redis>=7.0.0; extra == "tests"
+Provides-Extra: all
+Requires-Dist: coverage>=7.0.0; extra == "all"
+Requires-Dist: fastmcp>=2.0.0; extra == "all"
+Requires-Dist: myst-parser>=2.0.0; extra == "all"
+Requires-Dist: pydantic>2.0.0; extra == "all"
+Requires-Dist: pytest>=7.0.0; extra == "all"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
+Requires-Dist: redis>=7.0.0; extra == "all"
+Requires-Dist: rossum-api>=3.8.0; extra == "all"
+Requires-Dist: sphinx>=7.0.0; extra == "all"
+Requires-Dist: sphinx-autodoc-typehints>=1.25.0; extra == "all"
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == "all"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "all"
+Dynamic: license-file
+
+# Rossum MCP Server
+
+<div align="center">
+
+**MCP server for AI-powered Rossum document processing. 56 tools for queues, schemas, hooks, engines, and more.**
+
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://stancld.github.io/rossum-agents/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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-agents/branch/master/graph/badge.svg?flag=rossum-mcp)](https://codecov.io/gh/stancld/rossum-agents)
+[![MCP Tools](https://img.shields.io/badge/MCP_Tools-56-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>
+
+> [!NOTE]
+> This is not an official Rossum project. It is a community-developed integration built on top of the Rossum API.
+
+> [!NOTE]
+> API is stable starting from 1.0.0. Breaking changes will follow SemVer (released as 2.0.0+).
+
+## Quick Start
+
+```bash
+# Set environment variables
+export ROSSUM_API_TOKEN="your-api-token"
+export ROSSUM_API_BASE_URL="https://api.elis.rossum.ai/v1"
+
+# Run the MCP server
+uv pip install rossum-mcp
+rossum-mcp
+```
+
+Or run from source:
+
+```bash
+git clone https://github.com/stancld/rossum-agents.git
+cd rossum-mcp/rossum-mcp
+uv sync
+python rossum_mcp/server.py
+```
+
+## Claude Desktop Configuration
+
+Configure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):
+
+```json
+{
+  "mcpServers": {
+    "rossum": {
+      "command": "python",
+      "args": ["/path/to/rossum-mcp/rossum-mcp/rossum_mcp/server.py"],
+      "env": {
+        "ROSSUM_API_TOKEN": "your-api-token",
+        "ROSSUM_API_BASE_URL": "https://api.elis.rossum.ai/v1",
+        "ROSSUM_MCP_MODE": "read-write"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ROSSUM_API_TOKEN` | Yes | Your Rossum API authentication token |
+| `ROSSUM_API_BASE_URL` | Yes | Base URL for the Rossum API |
+| `ROSSUM_MCP_MODE` | No | `read-write` (default) or `read-only` |
+
+### Read-Only Mode
+
+Set `ROSSUM_MCP_MODE=read-only` to disable all CREATE, UPDATE, and UPLOAD operations. Only GET and LIST operations will be available.
+
+## Available Tools
+
+The server provides **56 tools** organized into categories:
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Document Processing** | 7 | Upload documents, retrieve/update/confirm/delete annotations |
+| **Queue Management** | 9 | Create, configure, delete, and list queues |
+| **Schema Management** | 8 | Define, modify, and delete field structures |
+| **Engine Management** | 6 | Configure extraction and splitting engines |
+| **Extensions & Rules** | 11 | Webhooks, serverless functions, business rules |
+| **Workspace Management** | 4 | Organize and delete workspaces |
+| **User Management** | 3 | List users and roles |
+| **Relations** | 4 | Annotation and document relations |
+| **Email Templates** | 3 | Automated email responses |
+| **Tool Discovery** | 1 | Dynamic tool loading |
+
+<details>
+<summary><strong>Tool List by Category</strong></summary>
+
+**Document Processing:**
+`upload_document`, `get_annotation`, `list_annotations`, `start_annotation`, `bulk_update_annotation_fields`, `confirm_annotation`, `delete_annotation`
+
+**Queue Management:**
+`get_queue`, `list_queues`, `get_queue_schema`, `get_queue_engine`, `create_queue`, `create_queue_from_template`, `get_queue_template_names`, `update_queue`, `delete_queue`
+
+**Schema Management:**
+`get_schema`, `list_schemas`, `create_schema`, `update_schema`, `patch_schema`, `get_schema_tree_structure`, `prune_schema_fields`, `delete_schema`
+
+**Engine Management:**
+`get_engine`, `list_engines`, `create_engine`, `update_engine`, `create_engine_field`, `get_engine_fields`
+
+**Extensions & Rules:**
+`get_hook`, `list_hooks`, `create_hook`, `update_hook`, `list_hook_templates`, `create_hook_from_template`, `list_hook_logs`, `delete_hook`, `get_rule`, `list_rules`, `delete_rule`
+
+**Workspace Management:**
+`get_workspace`, `list_workspaces`, `create_workspace`, `delete_workspace`
+
+**User Management:**
+`get_user`, `list_users`, `list_user_roles`
+
+**Relations:**
+`get_relation`, `list_relations`, `get_document_relation`, `list_document_relations`
+
+**Email Templates:**
+`get_email_template`, `list_email_templates`, `create_email_template`
+
+**Tool Discovery:**
+`list_tool_categories`
+
+</details>
+
+For detailed API documentation with parameters and examples, see [TOOLS.md](TOOLS.md).
+
+## Annotation Workflow
+
+Documents progress through these states:
+
+```
+importing → to_review → reviewing → confirmed → exporting → exported
+```
+
+**Key points:**
+- Wait for `to_review` before processing
+- Call `start_annotation` before updating fields
+- Call `confirm_annotation` to finalize
+
+## Example Workflows
+
+### Upload and Monitor
+
+```python
+# 1. Upload document
+upload_document(file_path="/path/to/invoice.pdf", queue_id=12345)
+
+# 2. Get annotation ID
+annotations = list_annotations(queue_id=12345)
+
+# 3. Check status
+annotation = get_annotation(annotation_id=annotations[0].id)
+```
+
+### Update Fields
+
+```python
+# 1. Start annotation (moves to 'reviewing')
+start_annotation(annotation_id=12345)
+
+# 2. Get content with field IDs
+annotation = get_annotation(annotation_id=12345, sideloads=['content'])
+
+# 3. Update fields using datapoint IDs
+bulk_update_annotation_fields(
+    annotation_id=12345,
+    operations=[{"op": "replace", "id": 67890, "value": {"content": {"value": "INV-001"}}}]
+)
+
+# 4. Confirm
+confirm_annotation(annotation_id=12345)
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Resources
+
+- [Full Documentation](https://stancld.github.io/rossum-agents/)
+- [Tools Reference](TOOLS.md)
+- [Rossum API Documentation](https://elis.rossum.ai/api/docs/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Main Repository](https://github.com/stancld/rossum-agents)

rossum_mcp-1.0.0/README.md

@@ -0,0 +1,192 @@
+# Rossum MCP Server
+
+<div align="center">
+
+**MCP server for AI-powered Rossum document processing. 56 tools for queues, schemas, hooks, engines, and more.**
+
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://stancld.github.io/rossum-agents/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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-agents/branch/master/graph/badge.svg?flag=rossum-mcp)](https://codecov.io/gh/stancld/rossum-agents)
+[![MCP Tools](https://img.shields.io/badge/MCP_Tools-56-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>
+
+> [!NOTE]
+> This is not an official Rossum project. It is a community-developed integration built on top of the Rossum API.
+
+> [!NOTE]
+> API is stable starting from 1.0.0. Breaking changes will follow SemVer (released as 2.0.0+).
+
+## Quick Start
+
+```bash
+# Set environment variables
+export ROSSUM_API_TOKEN="your-api-token"
+export ROSSUM_API_BASE_URL="https://api.elis.rossum.ai/v1"
+
+# Run the MCP server
+uv pip install rossum-mcp
+rossum-mcp
+```
+
+Or run from source:
+
+```bash
+git clone https://github.com/stancld/rossum-agents.git
+cd rossum-mcp/rossum-mcp
+uv sync
+python rossum_mcp/server.py
+```
+
+## Claude Desktop Configuration
+
+Configure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):
+
+```json
+{
+  "mcpServers": {
+    "rossum": {
+      "command": "python",
+      "args": ["/path/to/rossum-mcp/rossum-mcp/rossum_mcp/server.py"],
+      "env": {
+        "ROSSUM_API_TOKEN": "your-api-token",
+        "ROSSUM_API_BASE_URL": "https://api.elis.rossum.ai/v1",
+        "ROSSUM_MCP_MODE": "read-write"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ROSSUM_API_TOKEN` | Yes | Your Rossum API authentication token |
+| `ROSSUM_API_BASE_URL` | Yes | Base URL for the Rossum API |
+| `ROSSUM_MCP_MODE` | No | `read-write` (default) or `read-only` |
+
+### Read-Only Mode
+
+Set `ROSSUM_MCP_MODE=read-only` to disable all CREATE, UPDATE, and UPLOAD operations. Only GET and LIST operations will be available.
+
+## Available Tools
+
+The server provides **56 tools** organized into categories:
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Document Processing** | 7 | Upload documents, retrieve/update/confirm/delete annotations |
+| **Queue Management** | 9 | Create, configure, delete, and list queues |
+| **Schema Management** | 8 | Define, modify, and delete field structures |
+| **Engine Management** | 6 | Configure extraction and splitting engines |
+| **Extensions & Rules** | 11 | Webhooks, serverless functions, business rules |
+| **Workspace Management** | 4 | Organize and delete workspaces |
+| **User Management** | 3 | List users and roles |
+| **Relations** | 4 | Annotation and document relations |
+| **Email Templates** | 3 | Automated email responses |
+| **Tool Discovery** | 1 | Dynamic tool loading |
+
+<details>
+<summary><strong>Tool List by Category</strong></summary>
+
+**Document Processing:**
+`upload_document`, `get_annotation`, `list_annotations`, `start_annotation`, `bulk_update_annotation_fields`, `confirm_annotation`, `delete_annotation`
+
+**Queue Management:**
+`get_queue`, `list_queues`, `get_queue_schema`, `get_queue_engine`, `create_queue`, `create_queue_from_template`, `get_queue_template_names`, `update_queue`, `delete_queue`
+
+**Schema Management:**
+`get_schema`, `list_schemas`, `create_schema`, `update_schema`, `patch_schema`, `get_schema_tree_structure`, `prune_schema_fields`, `delete_schema`
+
+**Engine Management:**
+`get_engine`, `list_engines`, `create_engine`, `update_engine`, `create_engine_field`, `get_engine_fields`
+
+**Extensions & Rules:**
+`get_hook`, `list_hooks`, `create_hook`, `update_hook`, `list_hook_templates`, `create_hook_from_template`, `list_hook_logs`, `delete_hook`, `get_rule`, `list_rules`, `delete_rule`
+
+**Workspace Management:**
+`get_workspace`, `list_workspaces`, `create_workspace`, `delete_workspace`
+
+**User Management:**
+`get_user`, `list_users`, `list_user_roles`
+
+**Relations:**
+`get_relation`, `list_relations`, `get_document_relation`, `list_document_relations`
+
+**Email Templates:**
+`get_email_template`, `list_email_templates`, `create_email_template`
+
+**Tool Discovery:**
+`list_tool_categories`
+
+</details>
+
+For detailed API documentation with parameters and examples, see [TOOLS.md](TOOLS.md).
+
+## Annotation Workflow
+
+Documents progress through these states:
+
+```
+importing → to_review → reviewing → confirmed → exporting → exported
+```
+
+**Key points:**
+- Wait for `to_review` before processing
+- Call `start_annotation` before updating fields
+- Call `confirm_annotation` to finalize
+
+## Example Workflows
+
+### Upload and Monitor
+
+```python
+# 1. Upload document
+upload_document(file_path="/path/to/invoice.pdf", queue_id=12345)
+
+# 2. Get annotation ID
+annotations = list_annotations(queue_id=12345)
+
+# 3. Check status
+annotation = get_annotation(annotation_id=annotations[0].id)
+```
+
+### Update Fields
+
+```python
+# 1. Start annotation (moves to 'reviewing')
+start_annotation(annotation_id=12345)
+
+# 2. Get content with field IDs
+annotation = get_annotation(annotation_id=12345, sideloads=['content'])
+
+# 3. Update fields using datapoint IDs
+bulk_update_annotation_fields(
+    annotation_id=12345,
+    operations=[{"op": "replace", "id": 67890, "value": {"content": {"value": "INV-001"}}}]
+)
+
+# 4. Confirm
+confirm_annotation(annotation_id=12345)
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Resources
+
+- [Full Documentation](https://stancld.github.io/rossum-agents/)
+- [Tools Reference](TOOLS.md)
+- [Rossum API Documentation](https://elis.rossum.ai/api/docs/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Main Repository](https://github.com/stancld/rossum-agents)

{rossum_mcp-0.4.0 → rossum_mcp-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rossum-mcp"
-version = "0.4.0"
+version = "1.0.0"
 description = "MCP server for AI-powered Rossum orchestration: document workflows, debug pipelines automatically, and configure intelligent document processing through natural language."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -14,7 +14,7 @@ authors = [
 ]
 keywords = ["mcp", "rossum", "document-processing"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
@@ -25,9 +25,9 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "fastmcp>2.0.0",
+    "fastmcp>=2.0.0",
     "pydantic>2.0.0",
-    "rossum-api>=3.7.0",
+    "rossum-api>=3.8.0",
 ]
 
 [project.scripts]
@@ -50,13 +50,13 @@ tests = [
 ]
 all = [
     "coverage>=7.0.0",
-    "fastmcp>=1.0.0",
+    "fastmcp>=2.0.0",
     "myst-parser>=2.0.0",
     "pydantic>2.0.0",
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "redis>=7.0.0",
-    "rossum-api>=3.7.0",
+    "rossum-api>=3.8.0",
     "sphinx>=7.0.0",
     "sphinx-autodoc-typehints>=1.25.0",
     "sphinx-copybutton>=0.5.2",
@@ -67,8 +67,14 @@ all = [
 where = ["."]
 include = ["rossum_mcp*"]
 
-[tool.uv.sources]
-rossum-api = { git = "https://github.com/stancld/rossum-api.git", rev = "ds-feat-hook-logs"}
+
 
 [tool.coverage.run]
 omit = ["rossum_mcp/server.py"]
+
+[tool.pytest.ini_options]
+markers = [
+    "unit: marks tests as unit tests",
+    "integration: marks tests as integration tests (require API access)",
+]
+asyncio_mode = "auto"

{rossum_mcp-0.4.0 → rossum_mcp-1.0.0}/rossum_mcp/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.4.0"
+__version__ = "1.0.0"

{rossum_mcp-0.4.0 → rossum_mcp-1.0.0}/rossum_mcp/tools/annotations.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Literal
 
 from rossum_api.models.annotation import Annotation
 
-from rossum_mcp.tools.base import is_read_write_mode
+from rossum_mcp.tools.base import delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -130,6 +130,12 @@ async def _confirm_annotation(client: AsyncRossumAPIClient, annotation_id: int)
     }
 
 
+async def _delete_annotation(client: AsyncRossumAPIClient, annotation_id: int) -> dict:
+    return await delete_resource(
+        "annotation", annotation_id, client.delete_annotation, f"Annotation {annotation_id} moved to 'deleted' status"
+    )
+
+
 def register_annotation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register annotation-related tools with the FastMCP server."""
 
@@ -165,3 +171,7 @@ def register_annotation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> Non
     )
     async def confirm_annotation(annotation_id: int) -> dict:
         return await _confirm_annotation(client, annotation_id)
+
+    @mcp.tool(description="Delete an annotation. Moves to 'deleted' status (soft delete).")
+    async def delete_annotation(annotation_id: int) -> dict:
+        return await _delete_annotation(client, annotation_id)

rossum_mcp-1.0.0/rossum_mcp/tools/base.py

@@ -0,0 +1,73 @@
+"""Base utilities for Rossum MCP tools."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from typing import Any
+
+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>"
+
+
+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"
+
+
+def truncate_dict_fields(data: dict[str, Any], fields: tuple[str, ...]) -> dict[str, Any]:
+    """Truncate specified fields in a dictionary to save context.
+
+    Returns a new dictionary with specified fields replaced by TRUNCATED_MARKER.
+    """
+    if not data:
+        return data
+
+    result = dict(data)
+    for field in fields:
+        if field in result:
+            result[field] = TRUNCATED_MARKER
+    return result
+
+
+async def delete_resource(
+    resource_type: str,
+    resource_id: int,
+    delete_fn: Callable[[int], Awaitable[None]],
+    success_message: str | None = None,
+) -> dict:
+    """Generic delete operation with read-only mode check.
+
+    Args:
+        resource_type: Name of the resource (e.g., "queue", "workspace")
+        resource_id: ID of the resource to delete
+        delete_fn: Async function that performs the deletion
+        success_message: Custom success message. If None, uses default format.
+
+    Returns:
+        Dict with "message" on success or "error" in read-only mode.
+    """
+    tool_name = f"delete_{resource_type}"
+    if not is_read_write_mode():
+        return {"error": f"{tool_name} is not available in read-only mode"}
+
+    logger.debug(f"Deleting {resource_type}: {resource_type}_id={resource_id}")
+    await delete_fn(resource_id)
+
+    if success_message is None:
+        success_message = f"{resource_type.title()} {resource_id} deleted successfully"
+    return {"message": success_message}