An MCP stdio server that lets an AI agent operate a Store Builder site end to end — design its pages, fill them with real data, look at the result, and publish it — with no human clicking anything.

Tiếng Việt

Install

One command writes this server into every agent client on your machine:

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

It knows Claude Code, Claude Desktop, Cursor, Windsurf, VS Code and Codex, and installs into the ones it finds. Name them with --client cursor,codex, or rehearse with --dry-run. An option it does not know is refused, not ignored — a flag that silently does nothing is worse than one that does not exist.

--site is optional and worth passing: a key belongs to exactly one site, so it is written as SB_SITE and every tool then defaults to it. Without it the model has to carry the id through the session, which it can only get by listing pages and reading one back.

--site-name "Your Store" rides alongside it as SB_SITE_NAME. It is a label, never an address — nothing resolves by it — but it lets the agent say the store's name back to you instead of a 32-character id you did not choose. The Apps → AI agent screen appends it whenever the store has a name.

It merges: the servers already in those files stay, whatever it replaces is copied to <file>.sbuilder-backup, and a config it cannot parse is refused rather than overwritten — a file with a trailing comma is far likelier than one worth discarding, and it is what you need to fix it.

The store's Apps → AI agent screen hands you this command with the key already in it.

Or configure a client by hand

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

Getting the key

Open your store, go to Apps → AI agent, and press Create key. That screen hands you the config block for your client with the key already in it — this whole section is what it saves you reading.

One key is all you need. It reaches both the partner surface (/api/v1) and the private site API, including the page document and the live-edit socket, and it is bounded three ways on every request: its own scopes, the live role of the member who created it, and the single store it belongs to.

SB_EMAIL + SB_PASSWORD remain optional, and buy exactly one thing: account-level calls — listing your sites, managing members and roles — which a key deliberately cannot make, because those mean "this person's account".

SB_API defaults to http://localhost:8080. Secrets are read from the environment only.

sb_media_upload's photo search needs no key here: it calls the platform's own GET /api/sites/{siteId}/images/search, which runs a rotated pool of provider keys behind the credential this server already holds. An operator enables it by setting PEXELS_API_KEYS on the SERVER (comma separated; free keys at https://www.pexels.com/api/). With none configured the search answers "unavailable" and tells the caller to find a photograph by its own means and pass the URL — which the platform then fetches server-side. There is deliberately no fallback provider in this client: one would put the very key the platform exists to hold back into every install.

Tools

Tool	What it does
`sb_connect`	Log in, list the sites this account can operate, report which credentials are present
`sb_site_list`	List the sites this account can operate
`sb_api_find`	Find API operations by intent — one line per match — then read one operation's call sheet by id: real parameter schemas, the credential it needs, and the body's fields read off the handler that decodes them, each carrying the trap its own doc comment records
`sb_api_call`	Execute an operation, or any route by method+path; dry run by default. Field selection and local result pagination
`sb_page_open`	Open a page for editing and return its outline
`sb_outline`	The open page as a compressed tree — never a raw document dump
`sb_node_read`	One node in full, with a warning if it is a shared global
`sb_catalog_search`	Find an element by what it should do, using the platform's own AI hints
`sb_traits_for`	An element's inspector — tabs, groups, controls and what each declared one writes — plus its AI hints, defaults and containment rules
`sb_add`	Add an element — or a whole nested subtree — in one call
`sb_set`	Write style/config/specials. Per breakpoint by default
`sb_move`	Move a node to another parent
`sb_remove`	Remove a node and its subtree
`sb_duplicate`	Copy a node and its subtree under fresh ids, right after the original
`sb_templates`	The store's saved section templates, plus the BUILT-IN layouts — hero, feature trio, stats, FAQ, CTA band, product shelf, category strip, brand wall, trust band — composed against the page's own tokens
`sb_template_use`	Instantiate a template into a page
`sb_page_list`	Every page on the site
`sb_page_create`	Create a page — a store type arrives with the editor's own starting document; `type` is the route for checkout, product, category, post, course
`sb_publish`	Compile the draft into the live page (cascades to shared globals), report which revision went live, and with `verify` check the origin is serving it
`sb_page_state`	Which of a page's three copies is which — the DRAFT the editor canvas shows, the PUBLISHED row the storefront serves, and this session's — plus whether the editor will render the canvas BLANK, and where the recovery points are
`sb_review`	Every defect a visitor would see, each with its fix, plus the five gaps between this store and a paid order
`sb_media_list`	The site's media library
`sb_media_upload`	Add an image and get its URL — a local path, a URL the platform fetches, or a SEARCH for real photographs you read and pick from, one or several at a time
`sb_live_join`	Join the editor's live-edit room as a visible peer — edits then appear live
`sb_look`	Save, render, and return screenshots plus measured node boxes and layout defects measured on the render
`sb_event`	Give a node a click action — open the cart, go to a page, open a pop-up
`sb_bind`	Bind a node's content to real store data, or make a button add to the cart
`sb_import`	Read a page from any public URL and add its structure and content to the open page as real elements, styled with THIS page's own tokens — a translation, not a clone
`sb_import_site`	Read a WHOLE site from one URL — its sitemap, or the links on that page — and give each page found its own draft page here, built from this site's tokens; the entry page's own colours and type scale also patch into this SITE'S theme, so it stops being purely a read
`sb_theme`	Read or patch the site's palette and type scale — the layer every style preset resolves from, so one token repaints every page
`sb_store`	Run a store flow that must happen in a fixed order — `checkout` (the four writes that make a working one), `form` (any of the platform's 17 templates with its own field document), `chrome` (one shared header or footer), `menu` (a menu node bound to the site's menu, its links resolved), `overlay_attach` (a pop-up or quick view on the open page) and `app` (a built-in app plus the pages it needs), `global_attach` / `global_detach` (put an EXISTING shared section on the open page, or take it off)
`sb_undo`	Put back what a PUT replaced. The SECOND answer for a page, not the only one: the platform has versions, history and restore (`sb_api_find` "page versions"), which outlive this process — reach for those first and use this for every other shaped PUT

Twenty-eight tools, 560 API operations (193 of the 251 writes carrying a body shape read off the handler), 113 elements, 79 binding sources. sb_api_find is an index rather than a tool per endpoint, so the tool list stays short while everything the platform can do stays reachable — and operations added to the platform arrive with the next npm run codegen.

Every result is compact JSON, every directive is said once per process, and every tool carries MCP annotations — a client that honours them stops asking a person to confirm a read.

Full reference: docs/tools.md.

How it stays in sync

The platform publishes two generated, committed artifacts. A build step reads them out of a checkout and emits the catalog:

WB_REPO=/path/to/web_builder npm run codegen

So this repository vendors no platform code — it depends on two data files with a maintained contract. src/catalog/api.generated.ts is committed, so npm install needs no checkout at all.

Development

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

Contributor guide: CLAUDE.md. Design rationale: docs/superpowers/specs/.

Release

A push to main that touches src/** releases on its own (.github/workflows/auto-release.yml): the gate runs (build, test, smoke), the version bump is read off the commit subject — feat is minor, BREAKING CHANGE or ! is major, anything else is patch — Claude writes the changelog entry in both languages, server.json is synced, the release is committed as chore(release): vX.Y.Z and tagged, then published to npm, as a GitHub Release, and to the MCP Registry through GitHub OIDC. workflow_dispatch runs the same flow with a bump you choose. A commit whose subject contains chore(release): or release: v is skipped, so a release never triggers another.

The workflow needs two repository secrets in the prod environment: NPM_ACCESS_TOKEN and CLAUDE_CODE_OAUTH_TOKEN. The registry step needs none.

npm run release (scripts/release.mjs) is the offline path — a machine with no CI, or a release cut while a secret is being rotated. It runs the same gate and writes the same ## [x.y.z] - date changelog heading, so the two never disagree.

Designing safely

Five platform rules fail silently if a client does not know them, so they are encoded here as tested code rather than advice:

Band order — ROOT's children must read [header][middle][footer], or the platform refuses every save.
Site overlays (the cart drawer, pop-ups) are composed onto ROOT on read and stripped on write; they are excluded from every ROOT-level rule and cannot be edited through the page tools.
Global sections are shared masters — editing one changes every page carrying it, and publishing cascades. Any result touching one says so.
Responsive by default — sb_set writes per breakpoint, because a design should respond. Base is the cascade's fallback layer, not a trap.
App blocks — a marketplace app's subtree is composed onto the page on read and reduced back to one reference node on save, so an edit inside it is lost without a word. Every write refuses the interior; the outline flags the block root app: true.

Status

All three phases shipped: authentication and full API reach; the page document, patch protocol, builder and the five traps; the live-edit socket, the yield rule, and the vision loop. Since then: a token diet across every result, and releases that cut themselves.

Requires Node ≥22 (the global WebSocket) and, for sb_look only, system Google Chrome — playwright-core bundles no browser, so installing downloads nothing.

MIT.