Crystallize MCP

结晶MCP

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"
      }
    }
  }
}

添加 CRYSTALLIZE_ACCESS_TOKEN_ID 和 CRYSTALLIZE_ACCESS_TOKEN_SECRET 到 env PIM工具块（形状、订单、客户）。看 认证.

Claude Code (CLI)

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

使用 --scope project 写信给 .mcp.json （与您的团队分享）或 --scope user 供所有项目个人使用。

Claude Desktop

将标准配置添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）。

Cursor

将标准配置添加到光标MCP设置中(~/.cursor/mcp.json 或项目层面 .cursor/mcp.json).

VS Code / GitHub Copilot

将标准配置添加到 .vscode/mcp.json 在您的项目根目录中。

{
  "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"
      }
    }
  }
}

Windsurf

将标准配置添加到 ~/.codeium/windsurf/mcp_config.json.

Gemini CLI

将标准配置添加到 ~/.gemini/settings.json.

JetBrains AI Assistant

将标准配置添加到 .junie/mcp.json 在您的项目根目录中。

Warp

将标准配置添加到 ~/.warp/mcp.json.

Raycast

在Raycast中打开“安装MCP服务器”并填写：

• 命令: npx
• 参数: -y @hayodev/crystallize-mcp@latest
• 环境：添加 CRYSTALLIZE_TENANT_IDENTIFIER 你的代币变量

或者在打开命令之前复制上面的标准配置JSON——Raycast将自动填充表单。

From source (maintainers)

这 --local 标志是开发crystale mcp本身。它写 .mcp.json 指向本地构建输出-- 仅从repo根运行此操作:

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/

或者将您的MCP客户端直接指向内置的入口点：

{
  "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个工具，需要auth+write模式）

编写工具

需要编写工具 CRYSTALLIZE_ACCESS_MODE=write （或 admin)以及具有写入权限的令牌。

干运行模式

集 CRYSTALLIZE_DRY_RUN=true 在不执行突变的情况下预览突变。响应确切地显示了会发生什么变化——突变有效载荷、前后值以及与该项的深度链接：

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

示例提示

创建项目：

“使用标题为“入门”的文章形状在/blog下创建一篇新的博客文章”

更新顶级组件：

“在/products/夏季系列中找到该商品，并将其描述更新为‘夏季新品’”

更新内容块内的组件：

“在/articles/my post上获取该项目，然后将hero.title更新为“更新的标题”，并给我深度链接以查看草稿”

更新变更摘要：

“在/articles/guides/my guide中获取项目，将其标题组件更新为“新指南标题”，给我一个深度链接，并显示一个表，其中块中哪些字段发生了更改，哪些字段保持不变，前后值不变”

代理将在中更新目标组件 仅草案，保留块中的所有同级组件，并返回一个摘要，如下所示：

不会进行发布——您可以通过深度链接查看Crystallize UI中的更改，并在准备就绪时发布。

认证

目录和查找工具无需身份验证即可工作——只需设置 CRYSTALLIZE_TENANT_IDENTIFIER.

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

注： Crystallize令牌继承了创建它们的用户的权限。要将代理限制为只读访问，请在具有只读角色的用户下生成令牌。看 结晶角色.

环境变量

PII模式（选择加入）

默认情况下，所有客户和订单数据都按原样返回(full).集 CRYSTALLIZE_PII_MODE 选择数据最小化：

适用于 list_customers, get_customer, list_orders，以及 get_order对目录或形状工具没有影响。

与处理真实客户数据的团队、GDPR第25条合规性（设计数据最小化）或人工智能不需要原始联系方式来完成工作的环境相关。一个常见的模式是 masked 关于生产和 full 在dev上。

审核日志（选择加入）

集 CRYSTALLIZE_AUDIT_LOG 到绝对文件路径，以便对每个工具调用进行结构化日志记录：

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

每次调用一行JSON——时间戳、工具名称、参数、结果(ok/error)和租户。写入工具还会记录变异元数据（状态之前/之后）以进行审计跟踪。

注： 参数按原样记录，可能包含PII，例如 searchTerm 的 hani@example.com 或一个 customerIdentifier.将审计日志文件视为敏感数据，并相应地限制访问。参数清理已在路线图上，但尚未实施。

易于通过管道连接到日志聚合器（Datadog、CloudWatch、Splunk），但要确保您的管道通过适当的访问控制来处理文件。

钥匙链存储（可选）

安装向导(npx @hayodev/crystallize-mcp --setup)可以将令牌存储在操作系统密钥链（macOS密钥链、Windows凭据管理器或Linux上的libsecret）中，这样它们就不会以纯文本形式出现在配置文件中。MCP服务器在启动时自动解析密钥链中的凭据，无需额外配置。

这在以下情况下很有用：

• 你的 .mcp.json 致力于git --keychain将令牌排除在存储库之外
• 您不希望在纯文本配置文件中包含机密 --配置只需要 CRYSTALLIZE_TENANT_IDENTIFIER

当使用 --setup --global 对于Claude Code，这仅适用于密钥链存储可用并且您选择加入的情况：在这种情况下，向导将运行 claude mcp add 只有非秘密的env变量，令牌在运行时从密钥链读取，所以它们不会出现在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}

语言段是从租户的默认语言自动设置的，在服务器启动时引导——不需要配置。接受a的工具 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

许可证

麻省理工学院