cascade-cms-rest-mcp

A local, read-only MCP server exposing a Hannon Hill Cascade CMS server to MCP clients (Claude Desktop, Claude Code, etc.), built on top of cascade-cms-rest.

Seven tools, all read-only — no tool in this server can perform a write operation, even indirectly:

cascade_query_asset exists because cascade_read_asset's concise mode only collapses top-level fields, and its only narrowing hints are two page/content-type-specific field names (structuredData, pageConfigurations) — every other shape (metadata sets in particular, whose nested layout varies per metadata set definition) otherwise has no narrowed-read option short of format="detailed" dumping the entire payload. cascade_query_asset takes a small, safe path-query string — parsed via Python's ast module (never eval'd) — such as metadata.dynamicFields[0].value, metadata["dynamicFields"][0], a "*" wildcard over a list/dict, or find("identifier") to search the whole asset for a key by name at any depth — and returns only the matched sub-value(s), each tagged with its resolved path for a follow-up query.

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):

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:

{
  "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

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.