sbuilder-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+An MCP stdio server that designs and operates a Store Builder site.
+
+- **Full API reach in two tools.** `sb_api_find` searches a generated index of the
+  platform's 310 API operations — real parameter schemas, the credential each needs, and an
+  explicit flag when the platform's own document fails to describe a request body.
+  `sb_api_call` executes one, defaulting to a dry run.
+- **Page building.** An 85-element catalog carrying the platform's own AI hints
+  (`useWhen` / `avoidWhen` / `contentTips`), the live-edit patch primitive with its three
+  admission rules, and a builder that takes a whole nested section in one call.
+- **Four platform traps encoded as tested code**, each of which fails silently otherwise:
+  site overlays are excluded from every ROOT-level rule; global sections warn that edits
+  cascade; ROOT's children are held to `[header][middle][footer]`, which the platform
+  refuses every save without; and style writes go per breakpoint, because a visual quantity
+  written at base renders on the canvas and vanishes on publish.
+- **Live editing.** `sb_live_join` joins the editor's room as a visible peer — edits appear
+  in anyone's open editor as they happen. The client always yields: it never answers a
+  snapshot request and re-pulls on any divergence.
+- **Sight.** `sb_look` saves, renders through the platform's own renderer, and returns
+  screenshots plus the measured bounding box of every node.
+- **One credential.** `SB_TOKEN` alone opens everything, from the store's **Apps → AI agent**
+  screen.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Store Builder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# `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
+```
+
+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 — returns real parameter schemas, the credential each 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` | Which trait groups an element accepts, plus 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 |
+| `sb_publish` | Compile the draft into the live page (cascades to shared globals) |
+| `sb_review` | Every defect a visitor would see, each with the command that fixes it |
+| `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 |
+| `sb_bind` | Bind a node's content to real store data |
+
+Twenty-three tools, **310 API operations**. `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`.
+
+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/).
+
+## Designing safely
+
+Four 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.
+
+## Status
+
+All three phases shipped: authentication and full API reach; the page document, patch
+protocol, builder and the four traps; the live-edit socket, the yield rule, and the vision
+loop.
+
+Requires **Node ≥22** (the global `WebSocket`) and, for `sb_look` only, **system Google
+Chrome** — `playwright-core` bundles no browser, so installing downloads nothing.
+
+MIT.

package/README.vi.md

@@ -0,0 +1,137 @@
+# `sbuilder-mcp`
+
+Máy chủ MCP chạy trên **stdio**, cho phép một AI agent vận hành trọn vẹn một site
+[Store Builder](https://sbuilder.io.vn) — thiết kế trang, đổ dữ liệu thật vào, tự nhìn kết
+quả rồi xuất bản — mà không cần người bấm gì.
+
+*[English](./README.md)*
+
+## Cài đặt
+
+Một lệnh ghi server này vào mọi agent client trên máy bạn:
+
+```bash
+npx -y sbuilder-mcp install --token wbk_… --api https://your-host
+```
+
+Nó biết Claude Code, Claude Desktop, Cursor, Windsurf, VS Code và Codex, và cài vào những
+cái nó tìm thấy. Chỉ định bằng `--client cursor,codex`, hoặc diễn thử với `--dry-run`.
+
+Nó **gộp**: các server đã có trong file được giữ nguyên, thứ nó thay thế được chép sang
+`<file>.sbuilder-backup`, và một config nó không đọc được thì bị từ chối chứ không ghi đè —
+một file thừa dấu phẩy khả dĩ hơn nhiều một file đáng vứt, và đó chính là thứ bạn cần để sửa.
+
+Màn hình **Apps → AI agent** của cửa hàng đưa sẵn lệnh này kèm khoá.
+
+<details><summary>Hoặc tự cấu hình từng client</summary>
+
+```json
+{
+  "mcpServers": {
+    "sbuilder": {
+      "command": "npx",
+      "args": ["-y", "sbuilder-mcp"],
+      "env": { "SB_API": "https://api.your-host", "SB_TOKEN": "wbk_…" }
+    }
+  }
+}
+```
+
+</details>
+
+## Lấy khoá ở đâu
+
+Mở cửa hàng của bạn, vào **Apps → AI agent**, bấm **Tạo khoá**. Màn hình đó đưa luôn khối
+cấu hình cho client bạn dùng, khoá đã điền sẵn — cả mục này chỉ để bạn khỏi phải đọc.
+
+Một khoá là đủ. Nó với tới cả bề mặt đối tác (`/api/v1`) lẫn private site API, gồm tài liệu
+trang và socket live-edit, và bị chặn ba lớp ở mỗi request: scope của chính nó, role sống của
+thành viên đã tạo ra nó, và đúng một cửa hàng nó thuộc về.
+
+`SB_EMAIL` + `SB_PASSWORD` vẫn tuỳ chọn, và mua đúng một thứ: các lệnh **cấp tài khoản** —
+liệt kê site, quản lý thành viên và role — mà khoá cố ý không làm được, vì những thứ đó nghĩa
+là "tài khoản của người này".
+
+`SB_API` mặc định `http://localhost:8080`. Bí mật chỉ đọc từ biến môi trường.
+
+## Bộ tool
+
+| Tool | Làm gì |
+| --- | --- |
+| `sb_connect` | Đăng nhập, liệt kê site tài khoản vận hành được, báo đang có credential nào |
+| `sb_site_list` | Liệt kê site tài khoản vận hành được |
+| `sb_api_find` | Tìm operation theo ý định — trả về schema tham số thật, credential cần dùng, và cảnh báo rõ ràng khi tài liệu của nền tảng không mô tả request body |
+| `sb_api_call` | Chạy một operation. Mặc định chạy khô, không gửi gì |
+| `sb_page_open` | Mở một trang để sửa và trả về outline |
+| `sb_outline` | Trang đang mở dạng cây nén — không bao giờ dump tài liệu thô |
+| `sb_node_read` | Một node đầy đủ, kèm cảnh báo nếu nó là global dùng chung |
+| `sb_catalog_search` | Tìm element theo việc nó cần làm, dùng chính AI hints của nền tảng |
+| `sb_traits_for` | Element nhận nhóm trait nào, kèm default và luật chứa con |
+| `sb_add` | Thêm một element — hoặc cả cây con lồng nhau — trong một lần gọi |
+| `sb_set` | Ghi style/config/specials. Mặc định theo breakpoint |
+| `sb_move` | Chuyển node sang cha khác |
+| `sb_remove` | Xoá node và cả cây con |
+| `sb_duplicate` | Nhân bản một node và cả cây con dưới id mới, ngay sau bản gốc |
+| `sb_templates` | Section template đã lưu của cửa hàng — section thiết kế sẵn để bắt đầu |
+| `sb_template_use` | Thả một template vào trang |
+| `sb_page_list` | Mọi trang của site |
+| `sb_page_create` | Tạo một trang |
+| `sb_publish` | Biên dịch bản nháp thành trang live (lan sang global dùng chung) |
+| `sb_review` | Mọi khiếm khuyết người xem sẽ thấy, kèm lệnh sửa từng cái |
+| `sb_live_join` | Vào phòng live-edit của editor như một peer nhìn thấy được — sửa gì hiện ngay |
+| `sb_look` | Lưu, render, trả về ảnh chụp kèm box đo được của từng node |
+| `sb_bind` | Gắn nội dung một node vào dữ liệu cửa hàng thật |
+
+Hai mươi ba tool, **310 operation API**. `sb_api_find` là một chỉ mục chứ không phải mỗi endpoint một
+tool, nên danh sách tool vẫn ngắn trong khi mọi thứ nền tảng làm được vẫn với tới — và
+operation mới thêm bên nền tảng sẽ tự có sau lần `npm run codegen` kế tiếp.
+
+Tra cứu đầy đủ: [`docs/tools.vi.md`](./docs/tools.vi.md).
+
+## Cách nó không bị lệch
+
+Nền tảng có sẵn hai artifact đã sinh và đã commit. Một bước build đọc chúng từ một checkout
+rồi sinh ra catalog:
+
+```bash
+WB_REPO=/duong/dan/web_builder npm run codegen
+```
+
+Nhờ vậy repo này không vendor dòng code nào của nền tảng — nó chỉ phụ thuộc vào hai file dữ
+liệu có hợp đồng được bảo trì. `src/catalog/api.generated.ts` được commit, nên `npm install`
+không cần checkout nào cả.
+
+## Phát triển
+
+```bash
+npm run build     # tsc -> dist/
+npm test          # vitest
+npm run smoke     # tự kiểm offline; phải in ALL GOOD
+```
+
+Hướng dẫn đóng góp: [`CLAUDE.md`](./CLAUDE.md). Lý do thiết kế:
+[`docs/superpowers/specs/`](./docs/superpowers/specs/).
+
+## Thiết kế an toàn
+
+Bốn luật của nền tảng hỏng **im lặng** nếu client không biết, nên chúng được viết thành code
+có test chứ không phải lời khuyên:
+
+- **Thứ tự băng** — con của ROOT phải đọc `[header][middle][footer]`, sai là nền tảng từ
+  chối mọi lần lưu.
+- **Site overlay** (cart drawer, pop-up) được ghép lên ROOT lúc đọc và bóc ra lúc ghi; nó bị
+  loại khỏi mọi luật cấp ROOT và không sửa được qua bộ page tool.
+- **Global section** là master dùng chung — sửa một cái là đổi mọi trang mang nó, và publish
+  thì lan. Mọi kết quả đụng tới nó đều nói rõ.
+- **Mặc định responsive** — `sb_set` ghi theo breakpoint, vì một thiết kế nên đáp ứng. Base
+  là lớp dự phòng của cascade, không phải cái bẫy.
+
+## Trạng thái
+
+Cả ba giai đoạn đã xong: xác thực và với tới toàn bộ API; tài liệu trang, giao thức patch,
+builder và bốn cái bẫy; socket live-edit, luật nhường, và vòng lặp thị giác.
+
+Cần **Node ≥22** (WebSocket toàn cục) và, chỉ với `sb_look`, **Google Chrome của hệ thống** —
+`playwright-core` không kèm trình duyệt nào nên lúc cài không tải gì.
+
+MIT.