Crystallize MCP

Crystallize MCP

面向 Crystallize 无头商务的 MCP 服务。为 AI Agent 提供对目录、产品、形状、订单、客户和租户配置的读写权限，并支持跳转回 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 形状，在 /blog 下创建一篇标题为 ‘Getting Started’ 的新博客文章”

更新顶层组件：

“找到 /products/summer-collection 中的项目，并将其描述更新为 ‘New summer arrivals’”

更新内容块中的组件：

“获取 /articles/my-post 中的项目，然后将 hero.title 更新为 ‘Updated Headline’，并提供用于查看草稿的深层链接”

附带变更摘要进行更新：

“获取 /articles/guides/my-guide 中的项目，将其 title 组件更新为 ‘New Guide Title’，提供深层链接，并用表格展示内容块中哪些字段发生了变更、哪些保持不变，以及变更前后的值”

Agent 只会更新目标组件的草稿，保留内容块中的所有同级组件，并返回类似以下摘要：

不会发布任何内容——你可以通过深层链接在 Crystallize 界面中查看变更，并在准备就绪后发布。

身份验证

目录和发现工具无需身份验证，只需设置 CRYSTALLIZE_TENANT_IDENTIFIER。

对于 PIM 工具（类型、租户信息、订单、客户），请在以下位置创建访问令牌： https://app.crystallize.com/{tenant}/en/settings/access-tokens

注意： Crystallize 令牌继承创建者的权限。如需将 Agent 限制为只读访问，请使用具有只读角色的用户生成令牌。请参阅 Crystallize 角色。

环境变量

PII 模式（选择启用）

默认情况下，所有客户和订单数据都会原样返回（full）。将 CRYSTALLIZE_PII_MODE 设为相应值，可选择启用数据最小化：

适用于处理真实客户数据的团队、需遵守 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，包含时间戳、工具名称、参数、结果（ok/error）和租户。写入工具还会记录变更元数据（变更前后的状态），用于审计追踪。

**注意：**参数会原样记录，可能包含个人身份信息（PII），例如值为 [email protected] 的 searchTerm 或 customerIdentifier。请将审计日志文件视为敏感数据，并采取相应措施限制访问。参数脱敏功能已列入路线图，但尚未实现。

可轻松将日志传输至日志聚合器（Datadog、CloudWatch、Splunk），但请确保你的管道对文件实施了适当的访问控制。

钥匙串存储（可选）

设置向导（npx @hayodev/crystallize-mcp --setup）可以将令牌存储在操作系统钥匙串（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 参数的工具（catalogue、search）会在 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