# `sbuilder-mcp`

An MCP **stdio** server that lets an AI agent operate a [Store Builder](https://sbuilder.io.vn)
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](./README.vi.md)*

## Install

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

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

<details><summary>Or configure a client by hand</summary>

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

</details>

## 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; lists other pages with unpublished drafts (`publish_drafts` publishes them too) |
| `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_page_repair` | Rename a page root that is not `ROOT` (left by older seeds) so every editor build draws it — one page or the whole site |
| `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; `locale` sets the site's language |
| `sb_store` | Run a store flow that must happen in a fixed order — `checkout` (the four writes that make a working one), `checkout_sync` (the store's current payment and delivery methods into every existing order form, checkout page republished), `form` (any of the platform's 17 templates with its own field document), `chrome` (one shared header or footer on a real site menu — desktop menu, mobile drawer, cart and account icons), `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), `cart` (the site's cart drawer, when it has none; `relocalize` puts an existing one in the site's language) 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, **574 API operations** (197 of the 255 writes carrying a body shape read
off the handler), 122 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`](./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:

```bash
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

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

Contributor guide: [`CLAUDE.md`](./CLAUDE.md). Design rationale:
[`docs/superpowers/specs/`](./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.