cascade-cms-rest-mcp 0.2.2__tar.gz

cascade_cms_rest_mcp-0.2.2/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Agents
+.claude/
+CLAUDE.md
+
+# intermediate skill files (regenerated from the tracked .skill zip)
+skill/cascade-script-writer/
+
+# Cache
+cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Environment / secrets
+.env
+mcp/tests/output.txt
+
+# Editors
+.vscode/
+.idea/
+
+# OS
+.DS_Store

cascade_cms_rest_mcp-0.2.2/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: cascade-cms-rest-mcp
+Version: 0.2.2
+Summary: Read-only MCP server exposing a Hannon Hill Cascade CMS server to MCP clients
+Author: Keith Shark
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: cascade-cms-rest>=3.1.3
+Requires-Dist: mcp<3,>=2.1.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cascade-cms-rest-mcp
+
+A local, read-only [MCP](https://modelcontextprotocol.io) server exposing a
+Hannon Hill Cascade CMS server to MCP clients (Claude Desktop, Claude Code,
+etc.), built on top of [`cascade-cms-rest`](https://pypi.org/project/cascade-cms-rest/).
+
+Six tools, all read-only — no tool in this server can perform a write
+operation, even indirectly:
+
+| Tool | Purpose |
+|---|---|
+| `cascade_search` | Search a site for assets by text |
+| `cascade_read_asset` | Read a single asset by id or by site+path |
+| `cascade_get_data_structure` | A data-bound asset's field schema, resolved from its bound content type/data definition |
+| `cascade_get_page_config` | A data-bound asset's page configuration names/regions |
+| `cascade_root_container_id` | The root container id (e.g. Data Definitions folder) for an asset type on a site |
+| `cascade_list_sites` | List every site on the server |
+
+`cascade_get_data_structure` and `cascade_get_page_config` are
+**schema-authoritative**: they resolve field/group/config names from the
+asset's *bound content type or data definition*, not by sampling the one
+asset instance you point them at — so the result is the full schema-valid
+set, not just whatever happens to be populated on that instance.
+
+This is a different, easily-confused thing from the *library's*
+`Asset.get_data_structure()` method (used inside generated scripts, not by
+this server) — that one is instance/leaf-only. See the skill's
+`references/asset_api.md` for that distinction, and note that this server is
+read-only by design: *writing* structured data still goes through the
+skill's script-writing path (see its `callback-structured-data-edit.py`
+template).
+
+## Known limitation
+
+`resolve_data_definition()` (`src/cascade_cms_rest_mcp/resolution.py`)
+resolves a data-bound asset's data definition two ways: via
+`contentTypeId → contentType.dataDefinitionId` (confirmed against a real
+payload), and via a direct `dataDefinitionId` field on the asset itself
+(present in the code as a fallback, but not yet confirmed against any real
+fixture — harmless no-op if the field is absent). If you hit a data-bound
+asset where resolution fails unexpectedly, this direct-field path is the
+first thing to check.
+
+## Configuration
+
+Required environment variables (same names `CascadeWrapperBase` already
+expects — no new credential-naming surface):
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `CASCADE_API_KEY` | Yes | Cascade API key |
+| `CASCADE_URL` | Yes | e.g. `https://your-cascade-host:8443` |
+| `SERVER` | No | Cosmetic — log-file naming, defaults to `default` |
+| `CASCADE_MCP_CACHE_DIR` | No | Overrides the default `~/.cache/cascade-cms-mcp` response-cache location |
+
+The server fails fast at startup (not on first tool call) if `CASCADE_API_KEY`
+or `CASCADE_URL` is missing.
+
+## Client configuration
+
+Install from PyPI (`pip install cascade-cms-rest-mcp`) or run it directly
+with `uvx` — no local checkout needed — then point your MCP client at it:
+
+```json
+{
+  "mcpServers": {
+    "cascade-cms": {
+      "command": "uvx",
+      "args": ["cascade-cms-rest-mcp"],
+      "env": {
+        "CASCADE_API_KEY": "...",
+        "CASCADE_URL": "https://your-cascade-host:8443"
+      }
+    }
+  }
+}
+```
+
+To run against a local checkout of this repo instead of the published
+package (e.g. testing an unreleased change), use `uvx --from ./mcp
+cascade-cms-rest-mcp` or point `args` at `["--from", "/path/to/cascade-cms-tools/mcp", "cascade-cms-rest-mcp"]`.
+
+## Development
+
+```bash
+pip install -e "./mcp[dev]"   # from the repo root
+pytest
+ruff check .
+mypy mcp/src/
+```
+
+`tests/smoke_test.py` is a manual, human-run script against a real dev
+Cascade site (not collected by pytest) — see its own docstring.

cascade_cms_rest_mcp-0.2.2/README.md

@@ -0,0 +1,93 @@
+# cascade-cms-rest-mcp
+
+A local, read-only [MCP](https://modelcontextprotocol.io) server exposing a
+Hannon Hill Cascade CMS server to MCP clients (Claude Desktop, Claude Code,
+etc.), built on top of [`cascade-cms-rest`](https://pypi.org/project/cascade-cms-rest/).
+
+Six tools, all read-only — no tool in this server can perform a write
+operation, even indirectly:
+
+| Tool | Purpose |
+|---|---|
+| `cascade_search` | Search a site for assets by text |
+| `cascade_read_asset` | Read a single asset by id or by site+path |
+| `cascade_get_data_structure` | A data-bound asset's field schema, resolved from its bound content type/data definition |
+| `cascade_get_page_config` | A data-bound asset's page configuration names/regions |
+| `cascade_root_container_id` | The root container id (e.g. Data Definitions folder) for an asset type on a site |
+| `cascade_list_sites` | List every site on the server |
+
+`cascade_get_data_structure` and `cascade_get_page_config` are
+**schema-authoritative**: they resolve field/group/config names from the
+asset's *bound content type or data definition*, not by sampling the one
+asset instance you point them at — so the result is the full schema-valid
+set, not just whatever happens to be populated on that instance.
+
+This is a different, easily-confused thing from the *library's*
+`Asset.get_data_structure()` method (used inside generated scripts, not by
+this server) — that one is instance/leaf-only. See the skill's
+`references/asset_api.md` for that distinction, and note that this server is
+read-only by design: *writing* structured data still goes through the
+skill's script-writing path (see its `callback-structured-data-edit.py`
+template).
+
+## Known limitation
+
+`resolve_data_definition()` (`src/cascade_cms_rest_mcp/resolution.py`)
+resolves a data-bound asset's data definition two ways: via
+`contentTypeId → contentType.dataDefinitionId` (confirmed against a real
+payload), and via a direct `dataDefinitionId` field on the asset itself
+(present in the code as a fallback, but not yet confirmed against any real
+fixture — harmless no-op if the field is absent). If you hit a data-bound
+asset where resolution fails unexpectedly, this direct-field path is the
+first thing to check.
+
+## Configuration
+
+Required environment variables (same names `CascadeWrapperBase` already
+expects — no new credential-naming surface):
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `CASCADE_API_KEY` | Yes | Cascade API key |
+| `CASCADE_URL` | Yes | e.g. `https://your-cascade-host:8443` |
+| `SERVER` | No | Cosmetic — log-file naming, defaults to `default` |
+| `CASCADE_MCP_CACHE_DIR` | No | Overrides the default `~/.cache/cascade-cms-mcp` response-cache location |
+
+The server fails fast at startup (not on first tool call) if `CASCADE_API_KEY`
+or `CASCADE_URL` is missing.
+
+## Client configuration
+
+Install from PyPI (`pip install cascade-cms-rest-mcp`) or run it directly
+with `uvx` — no local checkout needed — then point your MCP client at it:
+
+```json
+{
+  "mcpServers": {
+    "cascade-cms": {
+      "command": "uvx",
+      "args": ["cascade-cms-rest-mcp"],
+      "env": {
+        "CASCADE_API_KEY": "...",
+        "CASCADE_URL": "https://your-cascade-host:8443"
+      }
+    }
+  }
+}
+```
+
+To run against a local checkout of this repo instead of the published
+package (e.g. testing an unreleased change), use `uvx --from ./mcp
+cascade-cms-rest-mcp` or point `args` at `["--from", "/path/to/cascade-cms-tools/mcp", "cascade-cms-rest-mcp"]`.
+
+## Development
+
+```bash
+pip install -e "./mcp[dev]"   # from the repo root
+pytest
+ruff check .
+mypy mcp/src/
+```
+
+`tests/smoke_test.py` is a manual, human-run script against a real dev
+Cascade site (not collected by pytest) — see its own docstring.

cascade_cms_rest_mcp-0.2.2/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cascade-cms-rest-mcp"
+version = "0.2.2"
+description = "Read-only MCP server exposing a Hannon Hill Cascade CMS server to MCP clients"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Keith Shark" }]
+dependencies = [
+    "cascade-cms-rest>=3.1.3",
+    "mcp>=2.1.0,<3",
+]
+
+[project.scripts]
+cascade-cms-rest-mcp = "cascade_cms_rest_mcp.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest", "mypy", "ruff"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cascade_cms_rest_mcp"]

cascade_cms_rest_mcp-0.2.2/src/cascade_cms_rest_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""cascade-cms-rest-mcp - a local, read-only MCP server wrapping cascade_cms.
+
+Lives in its own repo/project (cascade-cms-tools/mcp/), not inside
+cascade-cms-rest itself: the `mcp` SDK dependency, and this package's own
+release cadence, are both independent of the library it wraps. A normal
+`pip install cascade-cms-rest` is completely unaffected by this package's
+existence.
+"""

cascade_cms_rest_mcp-0.2.2/src/cascade_cms_rest_mcp/config.py

@@ -0,0 +1,56 @@
+"""Environment/config wiring for the MCP server, matching CascadeWrapperBase's
+existing expectations exactly - no new credential-naming surface.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from cascade_cms.wrapper import EnvironmentVars
+
+# The two hard requirements. SERVER is cosmetic (log-file naming) and
+# defaults, matching every existing skill template's convention.
+_REQUIRED_VARS = ("CASCADE_API_KEY", "CASCADE_URL")
+
+
+def load_environment_variables() -> EnvironmentVars:
+    """Read credentials from os.environ, or raise SystemExit naming exactly
+    what's missing. Call this at server startup, before the MCP session
+    starts - fail fast, not on first tool call.
+    """
+    missing = [name for name in _REQUIRED_VARS if not os.environ.get(name)]
+    if missing:
+        raise SystemExit(
+            "cascade-cms-rest-mcp: missing required environment variable(s): "
+            + ", ".join(missing)
+            + '. Set these in your MCP client\'s "env" block, e.g. '
+            '{"CASCADE_API_KEY": "...", "CASCADE_URL": "https://your-cascade-host"}.'
+        )
+    return EnvironmentVars(
+        API_KEY=os.environ["CASCADE_API_KEY"],
+        CASCADE_URL=os.environ["CASCADE_URL"],
+        SERVER=os.environ.get("SERVER", "default"),
+    )
+
+
+def cache_configuration() -> dict[str, object]:
+    """`configurationVariables` for CascadeWrapperBase.
+
+    Uses an explicit, stable cache path rather than the library's
+    CWD-relative `./cache/cache.sqlite` default, since an MCP client
+    (uvx, Claude Desktop, ...) launches this process from an unpredictable
+    working directory - a relative path would scatter cache dirs.
+    Override with CASCADE_MCP_CACHE_DIR for advanced use / testing.
+    """
+    cache_dir = Path(
+        os.environ.get(
+            "CASCADE_MCP_CACHE_DIR", str(Path.home() / ".cache" / "cascade-cms-mcp")
+        )
+    )
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return {
+        "cache_name": str(cache_dir / "cache.sqlite"),
+        "allowed_codes": (200,),
+        "allowed_methods": ("GET",),
+    }

cascade_cms_rest_mcp-0.2.2/src/cascade_cms_rest_mcp/data_structure.py

@@ -0,0 +1,116 @@
+"""Parse a Cascade data-definition's `xml` field (a `system-data-structure`
+document) into a generic, schema-authoritative tree, and locate groups/fields
+within it.
+
+The element vocabulary observed across three real data-definition documents
+(group, text, asset, shared-field, radio-item, dropdown-item - confirmed via
+direct inspection, not assumed) is broad and open-ended: 15+ distinct attribute
+names across those six tags. Rather than hand-model every possible Cascade field
+type/widget (risking a wrong guess for a shape not yet seen), every element is
+represented uniformly as `{"tag": ..., "attributes": {...}, "children": [...]}`,
+losing no information. `group` elements are containers (children are more schema
+nodes); any other tag is a leaf field (children, if present, are `radio-item`/
+`dropdown-item` option entries, not further schema nodes).
+"""
+
+from __future__ import annotations
+
+import io
+import xml.etree.ElementTree as ET
+from typing import Any
+
+
+def build_tree(xml_text: str) -> dict[str, Any]:
+    """Parse a `system-data-structure` XML document into the generic tree shape.
+
+    Uses `iterparse(events=("start", "end"))` with an explicit stack, clearing
+    each element on its "end" event - the standard memory-bounded iterparse
+    idiom, avoiding a full DOM build for a large document. Comments (there are
+    several in real data definitions, e.g. `<!--<group ...>-->`) are never
+    emitted with just ("start", "end") in the events tuple, so no special
+    handling is needed to skip them.
+    """
+    stack: list[tuple[dict[str, Any], list[dict[str, Any]]]] = []
+    root: dict[str, Any] | None = None
+    for event, elem in ET.iterparse(io.StringIO(xml_text), events=("start", "end")):
+        if event == "start":
+            node: dict[str, Any] = {"tag": elem.tag}
+            stack.append((node, []))
+        else:
+            node, children = stack.pop()
+            if elem.attrib:
+                node["attributes"] = dict(elem.attrib)
+            if children:
+                node["children"] = children
+            if stack:
+                stack[-1][1].append(node)
+            else:
+                root = node
+            elem.clear()
+    assert root is not None
+    return root
+
+
+def _identifier(node: dict[str, Any]) -> str | None:
+    return node.get("attributes", {}).get("identifier")
+
+
+def find_group(tree: dict[str, Any], group_identifier: str) -> dict[str, Any] | None:
+    """Recursive descent for the first `group` node whose `identifier` matches."""
+    if tree.get("tag") == "group" and _identifier(tree) == group_identifier:
+        return tree
+    for child in tree.get("children", []):
+        found = find_group(child, group_identifier)
+        if found is not None:
+            return found
+    return None
+
+
+def find_node(
+    group_node: dict[str, Any], node_identifier: str
+) -> dict[str, Any] | None:
+    """DFS within a matched group's children for a leaf field (any non-`group`
+    tag) whose `identifier` matches, descending into nested `group` children
+    (never itself a match - `node_identifier` names a field, not a group)."""
+    for child in group_node.get("children", []):
+        if child.get("tag") != "group" and _identifier(child) == node_identifier:
+            return child
+        if child.get("tag") == "group":
+            found = find_node(child, node_identifier)
+            if found is not None:
+                return found
+    return None
+
+
+def list_children(group_node: dict[str, Any]) -> list[dict[str, Any]]:
+    """Immediate children of a matched group, as a compact directory listing -
+    sorted alphabetically by identifier for a scannable, deterministic order
+    (not raw XML tree-walk order)."""
+    entries = [
+        {
+            "tag": child.get("tag"),
+            "identifier": _identifier(child),
+            "label": child.get("attributes", {}).get("label"),
+            "type": child.get("attributes", {}).get("type"),
+        }
+        for child in group_node.get("children", [])
+    ]
+    return sorted(entries, key=lambda e: e["identifier"] or "")
+
+
+def collect_group_identifiers(tree: dict[str, Any]) -> list[str]:
+    """Every group identifier anywhere in the tree, sorted alphabetically.
+    Uncapped - truncation for display is applied at the presentation layer,
+    not baked into this walk, so `total_count` stays truthful."""
+    identifiers: list[str] = []
+
+    def _walk(node: dict[str, Any]) -> None:
+        if node.get("tag") == "group":
+            identifier = _identifier(node)
+            if identifier:
+                identifiers.append(identifier)
+        for child in node.get("children", []):
+            _walk(child)
+
+    _walk(tree)
+    return sorted(identifiers)

cascade_cms_rest_mcp-0.2.2/src/cascade_cms_rest_mcp/errors.py

@@ -0,0 +1,223 @@
+"""Translate Cascade-level failures (CascadeError values, or exceptions that
+leaked out of submit_requests) into self-correcting MCP ToolErrors. Every
+message here names what was tried, what's actually available, and/or which
+tool to call next - never a bare "not found" or raw traceback.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cascade_cms.cmstypes import Asset, CascadeError, IdentifierType, Path
+from mcp.server.mcpserver.exceptions import ToolError
+
+from . import security
+from .formatting import format_names_for_message, sort_by_relevance
+
+
+def describe_identifier(identifier: IdentifierType | Path) -> str:
+    if isinstance(identifier, IdentifierType):
+        return f"{identifier.get_type} {identifier.get_id}"
+    site = identifier.get("siteName")
+    return f"{identifier['asset_type']} at {site}:{identifier['path']}"
+
+
+def single_result(results: list[Any], *, context: str) -> Any:
+    """Unwrap a one-chain `submit_requests()` result.
+
+    A top-level `submit_requests()` failure returns `[]` (see
+    `CascadeWrapperBase.submit_requests`), so this raises a ToolError instead
+    of letting `results[0]` raise a bare IndexError.
+    """
+    if not results:
+        raise ToolError(
+            f"{context}: no response was received from Cascade - this usually means a "
+            "connectivity or session-level failure rather than a bad request. Check "
+            "CASCADE_URL and CASCADE_API_KEY, confirm the server is reachable, and retry."
+        )
+    return results[0]
+
+
+def search_failure_error(result: CascadeError | Exception) -> ToolError:
+    if isinstance(result, CascadeError):
+        message = (
+            result.message
+            or "Cascade reported a search failure with no further detail."
+        )
+        return ToolError(f"cascade_search failed: {message}")
+    return ToolError(
+        f"cascade_search failed unexpectedly ({result}). This usually indicates a "
+        "connectivity/credential problem rather than a bad query - check CASCADE_URL "
+        "and CASCADE_API_KEY."
+    )
+
+
+def blocked_asset_type_error(asset_type: str, *, context: str) -> ToolError:
+    if security.is_asset_type_blocked(asset_type):
+        return ToolError(
+            f"{context}: asset type '{asset_type}' is not accessible via this server. "
+            "Access to users, groups, roles, and messages is restricted to protect "
+            "confidential information (usernames, hashed passwords, permission "
+            "matrices). If you need to work with permissions or user management, "
+            "describe the requirement to the user and ask them to handle it "
+            "manually rather than through this tool."
+        )
+    return ToolError(
+        f"{context}: asset type '{asset_type}' is not currently supported by this "
+        "server's allowlist. If this is a real Cascade asset type that should be "
+        "accessible, it needs to be added to ALLOWED_ASSET_TYPES in "
+        "cascade_cms_rest_mcp/security.py."
+    )
+
+
+def read_asset_error(
+    identifier: IdentifierType | Path,
+    result: CascadeError | Exception,
+    *,
+    context: str = "cascade_read_asset",
+    purpose: str | None = None,
+) -> ToolError:
+    described = describe_identifier(identifier)
+    target = f" ({purpose})" if purpose else ""
+    if isinstance(result, CascadeError):
+        message = result.message or "asset not found"
+        return ToolError(
+            f"{context} failed to read {described}{target}: {message}. "
+            "Try cascade_search first to confirm the correct id/type/path, then retry "
+            "cascade_read_asset with its result."
+        )
+    return ToolError(
+        f"{context} failed unexpectedly reading {described}{target} ({result}). This usually "
+        "indicates a connectivity/credential problem - check CASCADE_URL and CASCADE_API_KEY."
+    )
+
+
+def no_resolvable_reference_error(
+    asset: Asset, tried_fields: list[str], *, context: str
+) -> ToolError:
+    tried = ", ".join(tried_fields)
+    available = format_names_for_message(sorted(asset._data.keys())) or "(none)"
+    return ToolError(
+        f"{context}: could not resolve a reference from this asset - tried field(s) {tried}, "
+        f"none present. Fields actually on this asset: {available}. Try "
+        'cascade_read_asset(format="detailed") to inspect it directly.'
+    )
+
+
+def no_xml_field_error(data_definition: Asset, *, context: str) -> ToolError:
+    return ToolError(
+        f"{context}: data definition {data_definition.get('id')} has no 'xml' field, so its "
+        'schema can\'t be parsed. Try cascade_read_asset(format="detailed") on it directly to '
+        "inspect what it actually contains."
+    )
+
+
+def group_not_found_error(
+    data_definition: Asset, available_groups: list[str], group: str, *, context: str
+) -> ToolError:
+    available = (
+        format_names_for_message(sort_by_relevance(available_groups, group)) or "(none)"
+    )
+    return ToolError(
+        f"{context}: group '{group}' not found in data definition "
+        f"{data_definition.get('id')}. Available groups: {available}."
+    )
+
+
+def node_not_found_error(
+    data_definition: Asset,
+    group: str,
+    available_identifiers: list[str],
+    node_identifier: str,
+    *,
+    context: str,
+) -> ToolError:
+    available = (
+        format_names_for_message(
+            sort_by_relevance(available_identifiers, node_identifier)
+        )
+        or "(none)"
+    )
+    return ToolError(
+        f"{context}: field '{node_identifier}' not found in group '{group}' of data definition "
+        f"{data_definition.get('id')}. Available fields in this group: {available}."
+    )
+
+
+def config_name_not_found_error(
+    content_type: Asset,
+    available_names: list[str],
+    configuration_name: str,
+    *,
+    context: str,
+) -> ToolError:
+    available = (
+        format_names_for_message(sort_by_relevance(available_names, configuration_name))
+        or "(none)"
+    )
+    return ToolError(
+        f"{context}: page configuration '{configuration_name}' not found for content type "
+        f"{content_type.get('name')}. Available configurations: {available}."
+    )
+
+
+def page_region_not_found_error(
+    asset: Asset,
+    configuration_name: str,
+    page_region: str,
+    available_regions: list[str],
+    *,
+    context: str,
+) -> ToolError:
+    available = (
+        format_names_for_message(sort_by_relevance(available_regions, page_region))
+        or "(none)"
+    )
+    return ToolError(
+        f"{context}: region '{page_region}' not found in configuration '{configuration_name}' "
+        f"on this asset instance. This can mean the configuration name is valid but this "
+        f"particular asset was never authored with content for this region, not that the name "
+        f"is wrong. Regions present on this instance: {available}."
+    )
+
+
+def page_region_requires_configuration_name_error(*, context: str) -> ToolError:
+    return ToolError(
+        f"{context}: page_region was given without configuration_name - a region only makes "
+        "sense within a specific configuration. Supply configuration_name too, or omit "
+        "page_region to list available configurations first."
+    )
+
+
+def not_a_site_error(asset: Asset, *, context: str) -> ToolError:
+    return ToolError(
+        f"{context}: expected a site asset, but read a '{asset.internal_type}' asset "
+        f"({asset.get('name')!r}) instead. Root container ids only exist on site assets - "
+        "pass the identifier/path of the site itself."
+    )
+
+
+def no_root_container_error(site: Asset, asset_type: str, *, context: str) -> ToolError:
+    available = format_names_for_message(sorted(Asset._ROOT_CONTAINER_FIELDS.keys()))
+    return ToolError(
+        f"{context}: '{asset_type}' has no known root container field on site "
+        f"{site.get('name')!r}. Supported asset_type values: {available}."
+    )
+
+
+def list_sites_failure_error(result: CascadeError | Exception) -> ToolError:
+    if isinstance(result, CascadeError):
+        message = (
+            result.message
+            or "Cascade reported a listSites failure with no further detail."
+        )
+        return ToolError(f"cascade_list_sites failed: {message}")
+    return ToolError(
+        f"cascade_list_sites failed unexpectedly ({result}). This usually indicates a "
+        "connectivity/credential problem - check CASCADE_URL and CASCADE_API_KEY."
+    )
+
+
+def unexpected_failure_error(tool_name: str, exc: Exception) -> ToolError:
+    """Last-resort translation so no tool body can let a raw traceback leak."""
+    return ToolError(f"{tool_name} failed unexpectedly: {exc}")