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.

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:

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

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Sharkbits from gravatar.com Sharkbits

Credits

Author: Keith Shark

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cascade_cms_rest_mcp-0.2.2.tar.gz (27.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

cascade_cms_rest_mcp-0.2.2-py3-none-any.whl (20.1 kB view details)

Uploaded Python 3

File details

Details for the file cascade_cms_rest_mcp-0.2.2.tar.gz.

File metadata

  • Download URL: cascade_cms_rest_mcp-0.2.2.tar.gz
  • Upload date:
  • Size: 27.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for cascade_cms_rest_mcp-0.2.2.tar.gz
Algorithm Hash digest
SHA256 aff9a87473286cd0cc459987c4a4041f734f7f1f97d29f1f904fe71a9e447fca
MD5 7ecf4de78cbeaae1101df4381e40de62
BLAKE2b-256 d33e98d5ff62eb188d587715e2c614eb955cff38e955df328ea683ae8dfb17cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for cascade_cms_rest_mcp-0.2.2.tar.gz:

Publisher: release.yml on Sharkdroid/cascade-cms-tools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cascade_cms_rest_mcp-0.2.2-py3-none-any.whl.

File metadata

File hashes

Hashes for cascade_cms_rest_mcp-0.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 3528f5e37a635ab0750dc158cedfaebe27863543ebd2f91e115c882a51afe540
MD5 2cb0152f1ed1a527d803902428b64c5c
BLAKE2b-256 d953b00a45eda9d0d5703fbda67134c000d1b08cfe5c0d1e5785ed1fd49680f6

See more details on using hashes here.

Provenance

The following attestation bundles were made for cascade_cms_rest_mcp-0.2.2-py3-none-any.whl:

Publisher: release.yml on Sharkdroid/cascade-cms-tools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.2 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page