Store Builder

sbuilder-mcp

一个 MCP stdio 服务，让 AI Agent 能端到端操作 Store Builder 网站——设计页面、填入真实数据、查看效果并发布——全程无需人工点击。

Tiếng Việt

安装

只需一条命令，即可将此服务安装到计算机上的每个 Agent 客户端：

npx -y sbuilder-mcp install --token wbk_… --api https://your-host --site site_…

它支持 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code 和 Codex，并会安装到它找到的客户端中。使用 --client cursor,codex 指定客户端，或使用 --dry-run 预演。遇到不认识的选项时，它会拒绝执行，而不是忽略——一个悄无声息、什么也不做的标志，比不存在的标志更糟。

--site 是可选参数，但值得传入：一个密钥只属于一个站点，因此它会被写入 SB_SITE，之后每个工具都会默认使用该站点。不传入时，模型就必须在整个会话中携带站点 ID，而它只能通过列出页面并读取其中一个页面来获取。

--site-name "Your Store" 会与它一同设置为 SB_SITE_NAME。它只是一个标签，并非地址——不会根据它解析任何内容——但它可以让 Agent 向你复述商店名称，而不是复述一个由你无法选择的 32 位字符 ID。只要商店有名称，Apps → AI agent 页面就会附加这个名称。

它会合并配置：这些文件中已有的服务会保留；任何被替换的内容都会复制到 <file>.sbuilder-backup；无法解析的配置会被拒绝，而不是覆盖——带有尾随逗号的文件远比值得丢弃的文件常见，而且这正是你需要修复的问题。

商店的 Apps → AI agent 页面会提供这条命令，并预先填入密钥。

{
  "mcpServers": {
    "sbuilder": {
      "command": "npx",
      "args": ["-y", "sbuilder-mcp"],
      "env": { "SB_API": "https://api.your-host", "SB_TOKEN": "wbk_…", "SB_SITE": "site_…" }
    }
  }
}

获取密钥

打开商店，前往 Apps → AI agent，然后点击 Create key。该页面会提供适用于你客户端的配置块，并预先填入密钥——有了它，你就不必阅读本节了。

一个密钥就够了。它可以访问合作方接口（/api/v1）和私有站点 API，包括页面文档和实时编辑套接字；并且每次请求都会受到三方面限制：密钥自身的作用域、创建密钥的成员当前的角色，以及密钥所属的唯一商店。

SB_EMAIL + SB_PASSWORD 仍然是可选项；它们唯一提供的功能是执行账户级调用——列出你的站点、管理成员和角色。密钥有意不能执行这些操作，因为它们代表的是“此人的账户”。

SB_API 默认为 http://localhost:8080。密钥只从环境变量中读取。

sb_media_upload 的照片搜索无需在此处提供密钥：它会调用平台自己的 GET /api/sites/{siteId}/images/search，由平台在此服务已持有的凭据后方轮换使用一组服务商密钥。运营者只需在服务器上设置 PEXELS_API_KEYS 即可启用（用逗号分隔；可在 https://www.pexels.com/api/ 免费获取密钥）。如果未配置任何密钥，搜索会返回“不可用”，并告知调用方自行查找照片并传入 URL，之后平台会在服务器端获取该照片。本客户端有意不提供备用服务商：否则就会把平台存在的意义——替用户保管的密钥——放进每一份安装中。

工具

每个结果都是精简的 JSON，每条指令在每个进程中只会说一次，每个工具都带有 MCP 注释——遵循这些注释的客户端不会再要求用户确认读取操作。

完整参考文档：docs/tools.md。构建器原生支持的功能及其边界：docs/capabilities.md。

如何保持同步

平台会发布两个生成后并提交的构件。构建步骤从检出目录中读取它们并生成目录：

WB_REPO=/path/to/web_builder npm run codegen

因此，本仓库不会包含任何平台代码——它依赖的是两个遵循维护中契约的数据文件。src/catalog/api.generated.ts 已提交，因此 npm install 完全不需要检出目录。

开发

npm run build     # tsc -> dist/
npm test          # vitest
npm run smoke     # offline self-test; must print ALL GOOD

贡献者指南：CLAUDE.md。设计原理： docs/superpowers/specs/。

发布

对 main 的推送只要涉及 src/**，就会自动发布 （.github/workflows/auto-release.yml）：先运行门禁检查（构建、测试、冒烟测试），再根据提交主题确定版本号升级——feat 表示次版本，BREAKING CHANGE 或 ! 表示主版本，其他情况表示补丁版本——Claude 会用两种语言编写更新日志条目， 同步 server.json，将发布提交为 chore(release): vX.Y.Z 并打上标签， 然后发布到 npm、作为 GitHub Release 发布，并通过 GitHub OIDC 发布到 MCP Registry。 workflow_dispatch 会运行相同流程，并使用你选择的版本升级类型。提交主题中包含 chore(release): 或 release: v 的提交会被跳过，因此发布不会触发另一次发布。

此工作流需要在 prod 环境中配置两个仓库密钥：NPM_ACCESS_TOKEN 和 CLAUDE_CODE_OAUTH_TOKEN。Registry 步骤无需任何密钥。

npm run release（scripts/release.mjs）是离线路径——适用于没有 CI 的机器，或在轮换密钥期间进行发布。它运行相同的门禁检查，并写入相同的 ## [x.y.z] - date 更新日志标题，因此两种方式的结果始终一致。

安全设计

如果客户端不了解五条平台规则，就会静默失败，因此我们将它们编写为经过测试的代码，而不是建议：

• Band 顺序——ROOT 的子项必须按 [header][middle][footer] 排列，否则平台会拒绝每次保存。
• 站点叠加层（购物车抽屉、弹出窗口）在读取时会合成到 ROOT 上，在写入时会被剥离；它们不受任何 ROOT 层级规则约束，也无法通过页面工具编辑。
• 全局区块是共享主控项——编辑一个会更改所有包含它的页面，发布时也会级联。任何涉及全局区块的结果都会说明这一点。
• 默认响应式——sb_set 会按断点写入，因为设计应该能够响应变化。Base 是级联中的回退层，不是陷阱。
• 应用区块——市场应用的子树在读取时会合成到页面上，在保存时会还原为一个引用节点，因此对其内部的编辑会悄无声息地丢失。所有写入都会拒绝修改其内部；大纲会将区块根节点标记为 app: true。

状态

三个阶段均已交付：身份验证和完整 API 访问；页面文档、补丁协议、构建器及五个陷阱；实时编辑套接字、让出规则和视觉循环。此后新增了：精简所有结果的令牌用量，以及自动完成的发布流程。

需要 Node ≥22（提供全局 WebSocket），并且只有 sb_look 需要系统安装的 Google Chrome——playwright-core 不捆绑浏览器，因此安装时不会下载任何内容。

MIT。