Cmssy

@cmssy/mcp-server

Cmssy CMS 用の MCP サーバーです。i18n に対応した AI によるページの作成と管理を実現します。

セットアップ

前提条件

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

最初の 2 つの結果が異なる場合、その食い違いが答えです。ウォーム状態の 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 は、最後の 2 項目に基づいてツール呼び出しごとに使用イベントを 1 件記録します。
• ファイルと 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 を実行してください。これにより、エージェントのコンテキストウィンドウがエコーされたコンテンツで埋まるのを防げます。

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	スラッグまたは 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	1 つのレイアウト領域の設定を指定します（マニフェストに基づいて検証され、他の領域には影響しません）

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 は update_block_content よりトークンを約 10 倍節約でき、 DB に書き込む前にマーカーの誤りを検出します。

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

操作は 3 種類です：insert_before、insert_after、replace_section。各 マーカーは完全に 1 回だけ一致する必要があります。一致が 0 回または 2 回以上の場合は、実際の一致数とともにエラーになります（適用が中途半端な状態で黙って処理されることはありません）。replace_section では、 startMarker は範囲に含まれ、endMarker は含まれません。

PAGES_EDIT 権限を持つ、@cmssy/cli に登録済みのワークスペースが必要です。 デフォルトの fieldPath は "content" です（docs-article の HTML 本文）。別の文字列フィールドにパッチを適用する場合は上書きしてください。

モデルツール（カスタムデータモデル）

AI エージェントは ModelDefinitions を定義し、そのレコードに対して CRUD 操作を行えます。スキーマとフィールドは @cmssy/types の PropertyField に従います。書き込みのたびに、レコードはモデルに照らして検証されます。

ツール	説明
list_models	ワークスペース内のすべての ModelDefinitions を一覧表示します
get_model	id（ObjectId）または slug でモデルを取得します
create_model	モデルを作成します（name、slug、fields、任意の statusField）
update_model	モデルの任意のフィールドを更新します（fields の変更によりスキーマが移行されます）
delete_model	モデルを削除します — そのすべてのレコードも連鎖的に削除されます
list_records	filter（JSON）、sort、ページネーション、任意の populate を指定してレコードを一覧表示します
get_record	id でレコードを取得します。会社レコードには VAT ID、確認情報、免除情報が含まれます
create_record	レコードを作成します。data はモデルのフィールドキーをキーとして指定します
update_record	レコードの data および／または status を更新します
delete_record	レコードを削除します
import_records	最大 1000 件のレコードを一括インポートします。{ importedCount, errors } を返します
bulk_update_records	最大 200 個の id、または filter に一致するすべてのレコードの 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	顧客のメールアドレス、メモ、PO 番号、配送先住所を更新します
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	在庫とバリアント情報を含む商品カタログ（データモデル上）
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.* ウェブフックがメールを送信します。
resend_customer_verification	確認待ちの顧客に新しい確認トークンを発行します。アプリのウェブフックがメールを送信します。
unlock_customer	サインイン失敗回数とロックアウト状態をクリアします。
set_customer_company_role	顧客に会社内のロールを付与します（admin は会社のすべての注文を、buyer は自分の注文を確認できます）。
set_customer_price_list	会社に所属していない顧客に価格リストを割り当てます。null を指定すると割り当てを解除します。

価格リストツール

価格リスト（Gold、Silver、ディーラー向けの各ティア）では、カタログ価格からの割引率と、商品またはバリアントごとの固定価格を設定して、購入者向けの価格を決めます。購入者には価格リストが1つ適用されます。企業のメンバーにはその企業のリストが適用され、企業に属さない顧客には個別のリストが適用されます。

ツール	説明
list_price_lists	すべての価格リストを、percentOff、固定価格の件数、割り当て件数、チャネルとともに取得します
get_price_list	1つのリストと、その固定価格のページを取得します（商品で絞り込み、カーソルページネーションに対応）
create_price_list	名前、任意の割引率、および公開先のチャネルを指定してリストを作成します
update_price_list	リスト名、percentOff、期間、またはチャネルを変更します（[]で公開を解除します）
delete_price_list	リストを削除し、すべての割り当てを解除します
set_price_list_entry	商品またはバリアント1つの固定価格を設定します。数量に応じた価格区分も任意で設定できます
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	企業のVAT丸め方法をper_lineまたはper_rateに設定します。null = ワークスペースの設定
set_company_vat_id	企業のEU VAT IDを設定またはクリアします。IDを変更すると、認証済みではなくなります
set_company_vat_verified	企業の確認済みVAT IDを認証または取り消します。リバースチャージに適用されます
set_company_tax_exemption	法的理由を指定して企業の注文をVATの対象外にします。nullで解除します

販売チャネルツール

販売チャネル（小売、飲食業、B2B）は、ストアフロントから送信されるキーです。このキーにより、そのチャネルに公開された価格リストを使って価格が決まります。商品ごとに、購入者個人または企業のリストが優先され、次にチャネルの期間指定リスト、基本リスト、最後にカタログの順で適用されます。リストはcreate_price_list／update_price_listのchannelsで公開します。

ツール	説明
list_sales_channels	すべてのチャネルを、キー、displayMode、priceAccess、有効なリスト、オープンカート数とともに取得します
get_sales_channel	1つのチャネルと、その公開済みリスト、nextChangeAt、activeCartCountを取得します
create_sales_channel	チャネルを作成します（作成後にキーは変更できません）。ワークスペースあたり最大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