Cmssy

@cmssy/mcp-server

适用于 Cmssy CMS 的 MCP 服务——支持 AI 驱动的页面创建与管理，并提供 i18n 支持。

设置

前置条件

1. 一个 Cmssy 工作区——免费套餐即可；购物车和结账功能需要 Pro
2. 一个 API 令牌（Dashboard > API Tokens，以 cs_ 开头）
3. 你的工作区 ID（Workspace Settings > General）

该服务默认与 https://api.cmssy.io 通信。只有在使用其他后端时才传入 --api-url。

添加到 Claude Code

在项目根目录的 .mcp.json 中添加：

{
  "mcpServers": {
    "cmssy": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@cmssy/mcp-server@latest",
        "--token",
        "cs_YOUR_TOKEN",
        "--workspace-id",
        "YOUR_WORKSPACE_ID"
      ]
    }
  }
}

环境变量

你也可以设置以下变量来代替 CLI 参数：

• CMSSY_API_TOKEN — API 令牌（cs_xxx）
• CMSSY_WORKSPACE_ID — 工作区 ID
• CMSSY_API_URL — API URL（可选；默认值为 https://api.cmssy.io，因此只有在使用可自托管后端时才设置）

检查当前运行的构建版本

--version 和 --help 无需令牌，因此即使服务 尚未配置也会返回结果。针对客户端启动时使用的同一配置运行 该标记，从 mcp.json 中复制配置：

npx -y @cmssy/mcp-server --version          # what an unpinned config runs
npx -y @cmssy/mcp-server@latest --version   # what the registry serves today
npm view @cmssy/mcp-server version          # the newest published version

前两个结果可能不一致，而这种不一致本身就是答案：已热启动的 npx 缓存中保存着未锁定版本的配置先前解析到的构建版本，而 @latest 会重新解析并报告最新版本。因此，@latest --version 无法诊断 过期缓存——它反而会掩盖问题。如果工具因 API 本应提供的字段而失败，请先检查未锁定版本的配置，再进行比较。

可以运行 npx clear-npx-cache 清除缓存；也可以在配置中锁定版本，这样就无需诊断缓存问题。

隐私政策

完整政策：https://www.cmssy.com/privacy。联系方式：[email protected]。

• 此服务收集什么：不收集任何自身数据。它不保留本地数据库、不写入文件，也不会向任何分析服务发送数据。
• 发送什么以及发送到哪里：每次工具调用都会向 Cmssy API（除非设置了 CMSSY_API_URL，否则为 https://api.cmssy.io）发出一个 GraphQL 请求，其中包含你的 API 令牌、工作区 ID、工具参数、客户端名称和版本，以及正在运行的工具名称。Cmssy API 会根据最后两项信息，为每次工具调用记录一条使用事件。
• 文件和 URL：upload_media 只会读取你提供的本地文件路径，或下载你提供的 URL，然后将字节上传到 API 返回的 Cmssy 存储 URL。它不会访问其他文件。
• 使用情况和存储：Cmssy API 会按照上述政策所述，在欧盟存储工作区内容（页面、记录、媒体、订单、客户）。内容不会被出售，也不会用于训练 AI 模型。
• 与第三方共享：此服务只与 Cmssy API 和 Cmssy 存储 URL 通信，此外还会访问你提供给 upload_media 的任何 URL。Cmssy 服务自身使用的第三方服务列于该政策中。
• 数据保留：调用返回后，此服务不会保留任何内容。工作区数据会一直保留，直到你将其删除或关闭账户；保留期限详见该政策。
• 你的令牌：令牌具有创建者所拥有成员的权限。你可以随时前往 Dashboard > API Tokens 撤销令牌。

响应格式（写入工具）

从 0.6.0 开始，大多数写入工具都接受可选参数 response：

• response: "minimal"（默认值）——返回简短确认信息（约 200 字节）： 页面工具返回 {id, slug, hasUnpublishedChanges, updatedAt}， 区块工具返回 {pageId, blockId, hasUnpublishedChanges, updatedAt}， 表单工具返回 {id, slug, status, updatedAt}， 模型工具返回 {id, slug, updatedAt}， 记录工具返回 {id, status, updatedAt}， 订单工具返回 {id, orderNumber, status, paymentStatus, fulfillmentStatus, total, balanceDue, currency, updatedAt}， 折扣工具返回 {id, code, type, value, enabled, updatedAt}。
• response: "full"——返回完整的变更响应（0.6 之前的行为）。

只有在需要内联获取写入后的状态时才使用 "full"；否则，请改为调用 get_page/get_form/get_model/get_record。这样可以避免回显内容占满 Agent 的上下文窗口。

接受 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、close_order、reopen_order、 create_return、approve_return、reject_return、cancel_return、 receive_return、refund_return、complete_return、update_return_tracking、 create_shipment、update_shipment、 set_order_pipeline_stage、record_order_invoice、 record_order_invoice_correction、create_discount、 update_discount、set_discount_enabled。

patch_block_content 和各类 delete_* / 仅更改状态的工具 （update_form_submission_status、import_records） 已会返回简短确认信息，不接受 response。

可用工具

读取工具

工具	描述
list_pages	带层级结构的页面树（可选 search 筛选条件）
get_page	按 slug 或 id 获取完整页面，包含区块、i18n 内容和区域设置（自身的 regionSettings 及含继承来源的解析后 resolvedRegions）
get_site_config	语言、导航、网站名称
get_workspace_info	工作区名称、方案、限制
list_media	媒体库列表
list_trashed_pages	页面回收站：已删除的组、删除者、子树大小，以及各项的清除时间（删除后 30 天）

写入工具

工具	描述
create_page	创建新页面
update_page_blocks	设置页面的完整区块数组
update_page_settings	更新页面元数据和 SEO
publish_page	发布页面
unpublish_page	取消发布页面
delete_page	将页面及其子树移至回收站，可在 30 天内恢复
restore_page	将回收站中的页面组恢复为未发布的草稿
revert_to_published	丢弃草稿，恢复为已发布版本

区块辅助工具

工具	描述
add_block_to_page	在指定位置插入区块（自动生成 UUID 和翻译）
update_block_content	将内容合并到现有区块
patch_block_content	精准修补 HTML（在唯一标记附近插入／替换）
remove_block_from_page	按 ID 移除区块
update_page_layout	更新布局区块和覆盖项
update_region_settings	设置一个布局区域的设置（根据清单验证；不影响其他区域）

update_region_settings

区域（布局位置）设置由工作区的布局清单声明，并在写入时根据清单进行验证。该工具读取页面当前的 layoutRegionSettings，只替换指定区域，然后将整个列表写回，因此相邻区域会保留其值（清单不再声明的 区域条目，以及区域架构不再包含的键，会在过程中被移除——这与管理编辑器执行的清理相同）。对于未知区域、未知键，或在未声明设置的区域中传入非空 values（此类区域仅接受 values: {}），后端会原样返回其 BAD_USER_INPUT 消息；如果存在 blockWarnings，也会一并返回。

{ "pageId": "...", "region": "sidebar", "values": { "width": "wide" } }

子页面会继承区域设置，除非它们设置了自己的值—— get_page 会在 resolvedRegions 中显示每个区域的生效值 （settingsAreInherited、settingsSourcePageId）。

patch_block_content

对于较长 HTML 内容字符串（例如 docs-article 正文）的小幅编辑， patch_block_content 所需 token 约为 update_block_content 的十分之一， 并且会在写入数据库前捕获标记错误。

{
  "pageId": "...",
  "blockId": "...",
  "locale": "en",
  "operations": [
    {
      "op": "insert_before",
      "marker": "<h2>Environment Variables</h2>",
      "html": "<hr><h2>cmssy skills install</h2><p>...</p>",
    },
  ],
}

共有三种操作：insert_before、insert_after、replace_section。每个 标记都必须恰好匹配一次——匹配 0 次或 2 次以上都会报错并显示 实际匹配数（不会出现静默的部分应用状态）。对于 replace_section， startMarker 包含在范围内，endMarker 不包含在范围内。

需要由 @cmssy/cli 注册的工作区，并具有 PAGES_EDIT 权限。 默认 fieldPath 为 "content"（docs-article 上的 HTML 正文）；如果要修补其他字符串字段， 请覆盖此值。

模型工具（自定义数据模型）

AI Agent 可以定义 ModelDefinition 并对其记录执行 CRUD 操作。架构/字段遵循 @cmssy/types 中的 PropertyField；每次写入时都会根据模型验证记录。

工具	描述
list_models	列出工作区中的所有 ModelDefinition
get_model	按 ID（ObjectId）或 slug 获取模型
create_model	创建模型（name、slug、fields、可选的 statusField）
update_model	更新模型的任意字段（字段变更会触发架构迁移）
delete_model	删除模型——同时删除其所有记录
list_records	使用筛选条件（JSON）、排序、分页和可选的填充来列出记录
get_record	按 ID 获取记录；公司记录包含其 VAT ID、验证状态和豁免信息
create_record	创建记录；data 以模型字段键为键
update_record	更新记录的 data 和/或变更其状态
delete_record	删除记录
import_records	批量导入最多 1000 条记录；返回 { importedCount, errors }
bulk_update_records	对最多 200 个 ID 或所有符合筛选条件的记录设置 data 和/或 status

根据操作类型，需要工作区权限 MODELS_VIEW（读取）/ MODELS_CREATE / MODELS_EDIT / MODELS_DELETE。

商务工具（订单、购物车、折扣）

管理店面的订单、购物车和折扣码。**所有金额字段均为整数最小货币单位（分）。**订单/折扣写入工具接受 response 参数（参见响应格式）。

工具	描述
list_orders	按付款／履约／配送／状态、仓库队列、客户、货币、日期列出订单；通过 skip／limit 分页
get_order	获取订单及其商品、付款、包裹、发票和更正发票、税费汇总与处理方式、销售渠道，以及为其定价的价格表
get_order_pipeline	获取工作区可配置的订单流程阶段
create_manual_order	创建由管理员录入的订单，可选填写配送地址
edit_order	替换订单的商品行（重新计算总额）
update_order_details	更新客户邮箱、备注、采购订单编号和配送地址
mark_order_paid	记录全额付款（手动对账，不验证支付服务提供商）
record_order_payment	记录针对应付余额的部分付款
refund_order	退款（全额退款，或通过 amount 指定部分退款）
cancel_order	取消订单
close_order	将订单标记为已完成；如果付款或履约进度落后，则自动重新打开
reopen_order	重新打开已关闭的订单
create_return	创建退货：商品行、数量、原因和退货包裹追踪信息
approve_return	批准客户申请的退货
reject_return	拒绝退货申请
cancel_return	取消尚未退款的退货
receive_return	按商品行记录收到的数量，以及退回库存的数量
refund_return	记录退货退款
complete_return	关闭已收货但未退款的退货
update_return_tracking	设置退货包裹的承运商和追踪编号
create_shipment	为订单添加包裹（承运商、追踪编号、链接、状态）
update_shipment	更改包裹状态或追踪信息，并为其历史记录添加备注
set_order_pipeline_stage	将订单移至某个流程阶段
record_order_invoice	为订单关联发票（编号、URL、服务提供商）
record_order_invoice_correction	为已开票订单关联更正发票（贷项通知单）
list_carts	列出购物车（管理员视图，可选按状态筛选），并显示其销售渠道
delete_carts	永久删除 1 至 100 个购物车，全部删除或一个也不删
list_discounts	列出折扣码（按启用状态／类型／代码筛选）
get_discount	按 ID 获取折扣
create_discount	创建折扣（percentage／fixed／free_shipping）
update_discount	部分更新（代码／类型／货币；代码使用后即锁定）
set_discount_enabled	启用或停用折扣
list_products	商品目录，包含库存和变体信息（基于 Data Model）
bulk_update_products	批量设置或调整所选商品的状态、库存或价格
bulk_delete_products	批量删除所选商品记录
set_product_tiers	设置商品记录级别的批量价格阶梯
set_product_variants	替换商品的全部变体
set_product_currency_prices	替换商品在其他货币中的价格和价格阶梯，以及变体的各币种价格，不更改库存
产品是自定义数据模型的记录；这些工具在通用记录工具的基础上，增加了与产品相关的库存和变体读取，以及批量写入功能。批量工具可针对明确的 ids 列表，或所有符合 filter 条件的记录（allMatching: true）。不支持单独写入变体库存，也没有独立的库存变更工具——库存通过 patch.setStock / patch.adjustStock 批量设置或调整。

需要工作区权限：ORDERS_VIEW / ORDERS_MANAGE（订单）、CARTS_VIEW（购物车）、DISCOUNTS_VIEW / DISCOUNTS_MANAGE（折扣）、MODELS_VIEW / MODELS_EDIT / MODELS_DELETE（产品）。

客户工具

客户是在网站上登录的账户——即启用了账户的模型记录，而不是管理工作区的团队（list_team）。

工具	描述
list_customers	列出客户及其状态、验证情况、最近登录时间、公司和订单统计信息（分页）
get_customer	获取一位客户的账户摘要及其个人资料记录数据
suspend_customer	阻止登录并结束所有活动会话（订单和购物车会保留）
unsuspend_customer	允许已暂停的客户重新登录
send_customer_password_reset	向活跃客户发放重置令牌；应用的 account.* webhook 会发送邮件
resend_customer_verification	向待验证客户发放新的验证令牌；应用的 webhook 会发送邮件
unlock_customer	清除登录失败计数和锁定状态
set_customer_company_role	为客户分配公司角色（admin 可查看公司的所有订单，buyer 只能查看自己的订单）
set_customer_price_list	为没有所属公司的客户分配价格表；null 表示取消分配

价格清单工具

价格清单（Gold、Silver、经销商层级）按目录价格的折扣百分比，以及每个产品或变体的固定价格，为买家定价。每位买家使用一个清单：公司的成员使用公司的清单；没有关联公司的客户使用自己的清单。

工具	说明
list_price_lists	列出所有价格清单，包括 percentOff、固定价格数量、分配数量和渠道
get_price_list	获取一个清单及其一页固定价格（按产品筛选，使用游标分页）
create_price_list	创建清单，设置名称、可选折扣百分比，以及发布到哪些渠道
update_price_list	重命名清单、更改其 percentOff、时间窗口或渠道（[] 表示取消发布）
delete_price_list	删除清单并取消其在所有位置的分配
set_price_list_entry	为一个产品或变体设置固定价格，可选设置批量折扣阶梯
set_price_list_entries	一次性新增或更新最多 1000 个固定价格，要么全部成功，要么全部不生效
remove_price_list_entries	按产品／变体移除最多 1000 个固定价格
set_company_price_list	为公司记录分配价格清单；所有成员均使用该清单；null 表示取消分配
set_company_price_display_mode	设置公司买家查看净价还是含税价；null = 默认值（净价）
set_company_tax_rounding	设置公司的增值税舍入方式：per_line 或 per_rate；null = 工作区设置
set_company_vat_id	设置或清除公司的欧盟增值税 ID；更改 ID 后将不再通过验证
set_company_vat_verified	确认或撤销对公司增值税 ID 的核验；此设置会影响反向征税
set_company_tax_exemption	以合法理由免除公司订单的增值税；null 表示清除

销售渠道工具

销售渠道（零售、餐饮、B2B）是店面发送的一个键，用于从已发布到该渠道的价格清单中获取价格：对于每个产品，优先使用买家个人或公司清单，其次是该渠道设有日期的清单，再其次是该渠道的基础清单，最后是目录价格。使用 create_price_list / update_price_list 的 channels 发布清单。

工具	说明
list_sales_channels	列出所有渠道，包括 key、displayMode、priceAccess、启用的清单和未结购物车数量
get_sales_channel	获取一个渠道及其已发布清单、nextChangeAt 和 activeCartCount
create_sales_channel	创建渠道（创建后 key 固定）；每个工作区最多 20 个
update_sales_channel	重命名渠道或更改其 displayMode 或 priceAccess
delete_sales_channel	删除渠道、取消发布其清单，并放弃其未结购物车

Webhook 工具

管理出站事件 Webhook。create_webhook 和 rotate_webhook_secret 只会返回一次签名密钥，之后无法再次获取。

工具	描述
list_webhooks	列出 Webhook 端点（永不返回密钥）
list_webhook_deliveries	最近的投递尝试（待处理/成功/失败）
list_webhook_event_types	可订阅事件的权威允许列表
create_webhook	创建端点；返回端点和密钥（仅一次）
update_webhook	部分更新；传入 enabled 以启用/停用
rotate_webhook_secret	轮换签名密钥（新密钥仅返回一次）
delete_webhook	删除端点

需要工作区权限 WEBHOOKS_VIEW（读取）/ WEBHOOKS_MANAGE （创建、更新、轮换、删除）。

资源

URI	描述
cmssy://sitemap	完整页面树的 JSON
cmssy://workspace	工作区信息和站点配置

示例工作流

> 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

托管服务端（库）

createHostedServer 会在不持有令牌且不使用磁盘的主机上提供相同的工具。每个工具都需要一个 workspace（<orgSlug>/<workspaceSlug>）；list_workspaces 会列出连接可使用的工作区。该包只检查 workspace 的格式，以下所有事项都由主机负责：

• resolveWorkspace(workspace) 是授权环节。 每次调用时都要检查调用方是否仍是该工作区的成员，以及该连接是否已获授权访问该工作区。对于“工作区不存在”和“该工作区不属于你”，应抛出相同的消息，以免拒绝请求时泄露哪些工作区存在。
• 执行器负责限定范围。 它返回的 CmssyApi（createCmssyApi(execute, workspaceId)）会以该用户身份在该工作区中执行每个文档；该包不会发送任何用于限定范围的信息。
• fetchUrl 是 SSRF 防护边界。 拒绝私有、环回和链路本地地址，并对每次重定向重新检查。读取时，该包会将正文大小限制为 50MB。

开发

pnpm install
pnpm dev -- --token cs_xxx --workspace-id xxx --api-url http://localhost:4000