@cmssy/mcp-server
MCP server for Cmssy CMS — enables AI-driven page creation and management with i18n support.
Setup
Prerequisites
- Your Cmssy backend API URL (e.g.
https://api.your-cmssy.com)
- An API token (create in Dashboard > API Tokens, starts with
cs_)
- Your workspace ID
Add to Claude Code
Add to .mcp.json in your project root:
{
"mcpServers": {
"cmssy": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cmssy/mcp-server@latest",
"--token",
"cs_YOUR_TOKEN",
"--workspace-id",
"YOUR_WORKSPACE_ID",
"--api-url",
"https://api.your-cmssy.com"
]
}
}
}
Environment Variables
Instead of CLI args, you can set:
CMSSY_API_TOKEN — API token (cs_xxx)CMSSY_WORKSPACE_ID — Workspace IDCMSSY_API_URL — API URL (optional; defaults to https://api.cmssy.io, so set it only for a self-hosted backend)
Checking which build is running
--version and --help need no token, so they answer even when the server is
not configured. Run the flag against the same spec your client launches,
copied out of your mcp.json:
npx -y @cmssy/mcp-server --version
npx -y @cmssy/mcp-server@latest --version
npm view @cmssy/mcp-server version
The first two can disagree, and that disagreement is the answer: a warm npx
cache holds the build an unpinned spec resolved to earlier, while @latest
re-resolves and reports the newest one. So @latest --version cannot diagnose
a stale cache - it is the command that hides it. Ask the unpinned spec first
when a tool fails on a field the API should serve, then compare.
Clearing the cache is npx clear-npx-cache, or pin the version in your config
so nothing has to be diagnosed.
As of 0.6.0, most write tools accept an optional response arg:
response: "minimal" (default) - returns a small ack (~200 bytes):
{id, slug, hasUnpublishedChanges, updatedAt} for page tools,
{pageId, blockId, hasUnpublishedChanges, updatedAt} for block tools,
{id, slug, status, updatedAt} for form tools,
{id, slug, updatedAt} for model tools,
{id, status, updatedAt} for record tools,
{id, orderNumber, status, paymentStatus, fulfillmentStatus, total, balanceDue, currency, updatedAt} for order tools,
{id, code, type, value, enabled, updatedAt} for discount tools.response: "full" - returns the full mutation response (pre-0.6 behavior).
Use "full" only if you need the post-write state inline; otherwise issue a
follow-up get_page/get_form/get_model/get_record. This keeps agent
context windows from being eaten by echoed content.
Tools that accept response: create_page, update_page_blocks,
update_page_settings, publish_page, unpublish_page, revert_to_published,
update_page_layout, add_block_to_page, update_block_content,
remove_block_from_page, create_form, update_form, create_model,
update_model, create_record, update_record, create_manual_order,
edit_order, update_order_details, mark_order_paid, record_order_payment,
refund_order, cancel_order, transition_order_fulfillment,
set_order_pipeline_stage, record_order_invoice, create_discount,
update_discount, set_discount_enabled.
patch_block_content and the various delete_* / status-only tools
(update_form_submission_status, import_records)
already returned a compact ack and don't take response.
| Tool | Description |
|---|
list_pages | Page tree with hierarchy (optional search filter) |
get_page | Full page with blocks, i18n content and region settings (own regionSettings + resolved resolvedRegions with inheritance source) by slug or id |
get_site_config | Languages, navigation, site name |
get_workspace_info | Workspace name, plan, limits |
list_media | Media library listing |
| Tool | Description |
|---|
create_page | Create a new page |
update_page_blocks | Set full blocks array on a page |
update_page_settings | Update page metadata and SEO |
publish_page | Publish a page |
unpublish_page | Unpublish a page |
delete_page | Delete a page |
revert_to_published | Discard draft, revert to published |
| Tool | Description |
|---|
add_block_to_page | Insert a block at position (auto-generates UUID + translations) |
update_block_content | Merge content into an existing block |
patch_block_content | Surgical HTML patch (insert/replace around unique markers) |
remove_block_from_page | Remove a block by ID |
update_page_layout | Update layout blocks and overrides |
update_region_settings | Set one layout region's settings (manifest-validated; other regions untouched) |
update_region_settings
Region (layout position) settings are declared by the workspace's layout
manifest and validated against it on write. The tool reads the page's current
layoutRegionSettings, replaces only the named region and writes the whole
list back, so sibling regions keep their values (entries for regions the
manifest no longer declares, and keys a region's schema no longer has, are
dropped on the way - the same pruning the admin editor does). The backend's own
BAD_USER_INPUT message is returned verbatim for an unknown region, an unknown
key, or a non-empty values on a region that declares no settings (such a
region accepts values: {} only); blockWarnings are surfaced when present.
{ "pageId": "...", "region": "sidebar", "values": { "width": "wide" } }
Child pages inherit a region's settings unless they set their own -
get_page shows the effective value per region in resolvedRegions
(settingsAreInherited, settingsSourcePageId).
patch_block_content
For small edits on long HTML content strings (e.g. a docs-article body),
patch_block_content is ~10x cheaper in tokens than update_block_content
and catches marker mistakes before anything writes to the DB.
{
"pageId": "...",
"blockId": "...",
"locale": "en",
"operations": [
{
"op": "insert_before",
"marker": "<h2>Environment Variables</h2>",
"html": "<hr><h2>cmssy skills install</h2><p>...</p>",
},
],
}
Three ops: insert_before, insert_after, replace_section. Every
marker must match exactly once - 0 or 2+ matches error out with the
actual count (no silent half-applied state). For replace_section,
startMarker is inclusive and endMarker is exclusive.
Requires @cmssy/cli-registered workspace with PAGES_EDIT permission.
Default fieldPath is "content" (the HTML body on docs-article); override
if patching a different string field.
AI agents can define ModelDefinitions and CRUD their records. Schema/fields
follow PropertyField from @cmssy/types; records are validated against the
model on every write.
| Tool | Description |
|---|
list_models | List all ModelDefinitions in the workspace |
get_model | Get a model by id (ObjectId) or slug |
create_model | Create a model (name, slug, fields, optional statusField) |
update_model | Update any field of a model (fields change triggers schema migrate) |
delete_model | Delete a model — cascades to all its records |
list_records | List records with filter (JSON), sort, pagination, optional populate |
get_record | Get a record by id |
create_record | Create a record; data keyed by model field keys |
update_record | Update a record's data and/or transition its status |
delete_record | Delete a record |
import_records | Bulk import up to 1000 records; returns { importedCount, errors } |
Requires workspace permissions MODELS_VIEW (read) / MODELS_CREATE /
MODELS_EDIT / MODELS_DELETE depending on the operation.
Manage the storefront's orders, carts, and discount codes. All money fields
are integer minor units (cents). Order/discount write tools accept the
response arg (see Response shape).
| Tool | Description |
|---|
list_orders | List orders (filter by payment/fulfillment status, customer, dates) |
get_order | Get an order with items, payments, and tax summary |
get_order_pipeline | Get the workspace's configurable order pipeline stages |
create_manual_order | Create an admin-entered order |
edit_order | Replace an order's line items (recomputes totals) |
update_order_details | Update customer email, notes, and tracking |
mark_order_paid | Record a full payment (manual reconciliation, no provider verify) |
record_order_payment | Record a partial payment against the balance due |
refund_order | Refund an order (full, or partial with amount) |
cancel_order | Cancel an order |
transition_order_fulfillment | Move an order to a new fulfillment status (with optional tracking) |
set_order_pipeline_stage | Move an order to a pipeline stage |
record_order_invoice | Attach an invoice (number, url, provider) to an order |
list_carts | List shopping carts (admin view, optional status filter) |
list_discounts | List discount codes (filter by enabled/type/code) |
get_discount | Get a discount by id |
create_discount | Create a discount (percentage / fixed / free_shipping) |
update_discount | Partial update (code/type/currency lock once the code is used) |
set_discount_enabled | Enable or disable a discount |
list_products | Product catalog with stock + variant info (over a Data Model) |
bulk_update_products | Bulk set/adjust status, stock, or price on selected products |
bulk_delete_products | Bulk-delete selected product records |
Products are records of a Custom Data Model; these tools add product-aware
stock/variant reads and bulk writes on top of the generic record tools. The
bulk tools target an explicit ids list or everything matching a filter
(allMatching: true). There is no per-variant stock write and no standalone
inventory mutation - stock is set/adjusted in bulk via patch.setStock /
patch.adjustStock.
Requires workspace permissions ORDERS_VIEW / ORDERS_MANAGE (orders),
CARTS_VIEW (carts), DISCOUNTS_VIEW / DISCOUNTS_MANAGE (discounts),
MODELS_VIEW / MODELS_EDIT / MODELS_DELETE (products).
Customers are the accounts that sign in to the site - records of a model
with accounts enabled - not the team that manages the workspace
(list_team).
| Tool | Description |
|---|
list_customers | List customers with status, verification, last login, company and order stats (paginated) |
get_customer | One customer's account summary plus the profile record's data |
suspend_customer | Block sign-in and end every live session (orders and carts stay) |
unsuspend_customer | Let a suspended customer sign in again |
send_customer_password_reset | Email an active customer the forgot-password reset link |
resend_customer_verification | Issue and email a fresh verification link to a pending customer |
unlock_customer | Clear the failed sign-in counter and lockout |
Manage outbound event webhooks. create_webhook and rotate_webhook_secret
return the signing secret once - it cannot be retrieved again.
| Tool | Description |
|---|
list_webhooks | List webhook endpoints (secrets never returned) |
list_webhook_deliveries | Recent delivery attempts (pending/success/failed) |
list_webhook_event_types | The authoritative allowlist of subscribable events |
create_webhook | Create an endpoint; returns the endpoint + secret (once) |
update_webhook | Partial update; pass enabled to enable/disable |
rotate_webhook_secret | Rotate the signing secret (returns new secret once) |
delete_webhook | Delete an endpoint |
Requires workspace permissions WEBHOOKS_VIEW (read) / WEBHOOKS_MANAGE
(create, update, rotate, delete).
Resources
| URI | Description |
|---|
cmssy://sitemap | Full page tree as JSON |
cmssy://workspace | Workspace info + site config |
Example Workflow
> List all pages in my workspace
> Search for pages matching "blog"
> Show me the available block types
> Which pages still use block types the site no longer registers?
> Create a new "Features" page with content in English and Polish
> Add a hero block to the Features page
> Publish the Features page
Development
pnpm install
pnpm dev -- --token cs_xxx --workspace-id xxx --api-url http://localhost:4000