Crystallize MCP

Crystallize MCP

Crystallize のヘッドレスコマース向け MCP サーバーです。AI エージェントがカタログ、商品、シェイプ、注文、顧客、テナント設定に対して読み取りと書き込みを行えます。Crystallize UI へのディープリンク、変更操作のドライランによる安全性、顧客データの PII マスキングを備えています。

Claude Code、Claude Desktop、Cursor、Windsurf、Copilot、および MCP 互換のすべてのクライアントで動作します。

はじめに

セットアップウィザード

対話型ウィザードで、設定、認証トークン、キーチェーンへの保存、PII モードをまとめて設定できます。

# Project-level — writes .mcp.json in the current directory (shared with your team)
npx @hayodev/crystallize-mcp --setup

# Global — registers via `claude mcp add` (Claude Code) or writes Claude Desktop config
npx @hayodev/crystallize-mcp --setup --global

手動設定

標準の MCP 設定です（どのクライアントでも動作します）。

{
  "mcpServers": {
    "crystallize": {
      "command": "npx",
      "args": ["-y", "@hayodev/crystallize-mcp@latest"],
      "env": {
        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant"
      }
    }
  }
}

PIM ツール（シェイプ、注文、顧客）を使用するには、CRYSTALLIZE_ACCESS_TOKEN_ID と CRYSTALLIZE_ACCESS_TOKEN_SECRET を env ブロックに追加してください。認証を参照してください。

claude mcp add crystallize \
  -e CRYSTALLIZE_TENANT_IDENTIFIER=your-tenant \
  -e CRYSTALLIZE_ACCESS_TOKEN_ID=your-token-id \
  -e CRYSTALLIZE_ACCESS_TOKEN_SECRET=your-token-secret \
  -- npx -y @hayodev/crystallize-mcp@latest

{
  "servers": {
    "crystallize": {
      "command": "npx",
      "args": ["-y", "@hayodev/crystallize-mcp@latest"],
      "env": {
        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant",
        "CRYSTALLIZE_ACCESS_TOKEN_ID": "your-token-id",
        "CRYSTALLIZE_ACCESS_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

git clone https://github.com/HayoDev/crystallize-mcp.git
cd crystallize-mcp
npm install && npm run build
npx . --setup --local   # writes .mcp.json pointing to ./build/

{
  "mcpServers": {
    "crystallize": {
      "command": "node",
      "args": ["/path/to/crystallize-mcp/build/src/bin/crystallize-mcp.js"],
      "env": {
        "CRYSTALLIZE_TENANT_IDENTIFIER": "your-tenant"
      }
    }
  }
}

ツール（16）

カタログ（4 ツール）

ディスカバリー（3 つのツール）

シェイプとテナント（3 つのツール、認証が必要）

注文（2 つのツール、認証が必要）

顧客（2 つのツール、認証が必要）

コンテンツ（2 つのツール、認証と書き込みモードが必要）

書き込みツール

書き込みツールを使用するには、CRYSTALLIZE_ACCESS_MODE=write（または admin）と、書き込み権限のあるトークンが必要です。

ドライランモード

CRYSTALLIZE_DRY_RUN=true を設定すると、変更を実行せずにプレビューできます。レスポンスには、変更される内容（変更ペイロード、変更前後の値、アイテムへのディープリンク）が正確に表示されます。

"env": {
  "CRYSTALLIZE_ACCESS_MODE": "write",
  "CRYSTALLIZE_DRY_RUN": "true"
}

プロンプトの例

アイテムを作成する：

「article シェイプを使って、タイトルを 'Getting Started' とする新しいブログ記事を /blog に作成してください」

トップレベルのコンポーネントを更新する：

「/products/summer-collection にあるアイテムを見つけて、説明を 'New summer arrivals' に更新してください」

コンテンツチャンク内のコンポーネントを更新する：

「/articles/my-post のアイテムを取得してから、hero.title を 'Updated Headline' に更新し、下書きを確認するためのディープリンクを教えてください」

変更の概要を含めて更新する：

「/articles/guides/my-guide のアイテムを取得し、タイトルコンポーネントを 'New Guide Title' に更新して、ディープリンクを教えてください。また、チャンク内のどのフィールドが変更され、どれが変更されなかったかを、変更前後の値とともに表で示してください」

エージェントは対象のコンポーネントを下書きのみで更新し、チャンク内のほかのすべてのコンポーネントを保持したうえで、次のような概要を返します。

公開は行われません。ディープリンクから Crystallize UI で変更内容を確認し、準備ができたら公開してください。

認証

カタログおよびディスカバリーツールは認証なしで動作します。CRYSTALLIZE_TENANT_IDENTIFIER を設定するだけです。

PIM ツール（シェイプ、テナント情報、注文、顧客）を使用するには、次の場所でアクセストークンを作成してください： https://app.crystallize.com/{tenant}/en/settings/access-tokens

注： Crystallize トークンは、作成者のユーザーから権限を引き継ぎます。エージェントのアクセスを読み取り専用に制限するには、読み取り専用ロールを持つユーザーでトークンを生成してください。Crystallize のロールをご覧ください。

環境変数

PII モード（オプトイン）

デフォルトでは、顧客データと注文データはすべてそのまま返されます（full）。データ最小化をオプトインするには、CRYSTALLIZE_PII_MODE を設定します。

list_customers、get_customer、list_orders、get_order に適用されます。カタログツールやシェイプツールには影響しません。

実際の顧客データを扱うチーム、GDPR 第 25 条への準拠（設計段階でのデータ最小化）、または AI が業務の遂行に生の連絡先情報を必要としない環境に適しています。一般的な使い方として、本番環境では masked、開発環境では full を設定します。

監査ログ（オプトイン）

構造化ログで各ツール呼び出しを記録するには、CRYSTALLIZE_AUDIT_LOG に絶対ファイルパスを設定します。

{
  "ts": "2026-04-03T14:38:41Z",
  "tool": "list_customers",
  "params": { "first": 10 },
  "result": "ok",
  "tenant": "my-store"
}

呼び出しごとに JSON を 1 行記録します。タイムスタンプ、ツール名、パラメーター、結果（ok／error）、テナントが含まれます。書き込みツールでは、監査証跡用に変更メタデータ（変更前／変更後の状態）も記録します。

Note: パラメーターはそのまま記録されるため、PII が含まれる場合があります。たとえば、searchTerm が [email protected] の場合や、customerIdentifier が含まれる場合です。監査ログファイルは機密データとして扱い、適切にアクセスを制限してください。パラメーターのスクラブ処理はロードマップにありますが、まだ実装されていません。

ログアグリゲーター（Datadog、CloudWatch、Splunk）に簡単にパイプできます。ただし、パイプラインで適切なアクセス制御を適用してください。

キーチェーンストレージ（任意）

セットアップウィザード（npx @hayodev/crystallize-mcp --setup）では、トークンを OS のキーチェーン（macOS Keychain、Windows Credential Manager、または Linux の libsecret）に保存できるため、設定ファイルにプレーンテキストで記載されることはありません。MCP サーバーは起動時にキーチェーンから認証情報を自動的に解決するため、追加の設定は不要です。

次のような場合に便利です。

• .mcp.json を git にコミットする場合 — キーチェーンに保存することで、トークンをリポジトリに含めずに済みます
• シークレットを設定ファイルにプレーンテキストで記載したくない場合 — 設定に必要なのは CRYSTALLIZE_TENANT_IDENTIFIER のみです

Claude Code で --setup --global を使用する場合、この機能が適用されるのは、キーチェーンストレージが利用可能で、かつ使用を選択した場合のみです。その場合、ウィザードはシークレット以外の環境変数のみを指定して claude mcp add を実行し、トークンは実行時にキーチェーンから読み取られるため、Claude Code の設定には記載されません。キーチェーンストレージが利用できない場合、または使用しないことを選択した場合、ウィザードはトークンの環境変数を claude mcp add に渡し、Claude Code がそれらをプレーンテキストで保存する可能性があります。

アクセスモード

CRYSTALLIZE_ACCESS_MODE は、起動時に MCP サーバーが登録するツールを制御します。

• read（デフォルト）— 読み取り専用ツールのみ
• write — コンテンツの作成およびコンポーネントの更新を含みます（ドライランに対応）
• admin — シェイプの変更やテナント設定など、すべてのアクセスを含みます

ディープリンク

すべてのレスポンスには、Crystallize UI へのクリック可能なリンクが含まれます。

• アイテム → app.crystallize.com/@{tenant}/{language}/catalogue/{type}/{itemId}
• シェイプ → app.crystallize.com/@{tenant}/{language}/settings/shapes/{identifier}
• 注文 → app.crystallize.com/@{tenant}/{language}/orders/{orderId}

言語部分には、サーバー起動時に読み込まれるテナントのデフォルト言語が自動的に設定されます。設定は不要です。language パラメーターを受け取るツール（カタログ、検索）では、API 呼び出しと生成されるリンクの両方に、指定された言語が使用されます。

開発

npm install
npm run build
npm run dev          # build + start
npm run lint         # oxlint
npm run format       # oxlint --fix + oxfmt
npm run typecheck    # tsc --noEmit
npm run test         # build + node --test

ライセンス

MIT