# Store Builder

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/vuluu2k/sbuilder-mcp  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/store-builder

## Description
Design, fill with real store data, render and publish Store Builder pages from an AI agent.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "store-builder": {
    "command": "npx",
    "args": ["-y","store-builder"]
  }
}
```

## Documentation & README

# `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](https://github.com/vuluu2k/sbuilder-mcp/blob/HEAD/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
```

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

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_…" }
    }
  }
}
```

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

## 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 an explicit note when the platform's document fails to describe a request body |
| `sb_api_call` | Execute one operation. Defaults to a dry run that sends nothing |
| `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 — designed sections to start from |
| `sb_template_use` | Instantiate a template into a page |
| `sb_page_list` | Every page on the site |
| `sb_page_create` | Create a page; `type` is the route for checkout, product, category, post, course |
| `sb_publish` | Compile the draft into the live page (cascades to shared globals) |
| `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 — the only route, the upload is multipart |
| `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_bind` | Bind a node's content to real store data |

Twenty-five tools, **412 API operations**, 106 elements, 77 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`](https://github.com/vuluu2k/sbuilder-mcp/blob/HEAD/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`](https://github.com/vuluu2k/sbuilder-mcp/blob/HEAD/CLAUDE.md). Design rationale:
[`docs/superpowers/specs/`](https://github.com/vuluu2k/sbuilder-mcp/blob/HEAD/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.