Store Builder

sbuilder-mcp

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 .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

Thirty-eight tools, 949 API operations (354 of the 441 writes carrying a body shape read off the handler), 124 elements, 96 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. What the builder supports natively, and where it stops: docs/capabilities.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