webcake-landing-mcp 1.0.13 → 1.0.15

package/README.md

@@ -1,4 +1,4 @@
-# 🍰 WebCake Landing MCP
+# <img src="docs/assets/webcake-icon.svg" alt="Webcake" width="26" height="26" align="absmiddle"> WebCake Landing MCP
 
 **English** · [Tiếng Việt](./README.vi.md)
 
@@ -58,13 +58,53 @@ persists it (source-only — the page opens in the editor where re-saving render
 
 | Method | Best for | Auth |
 |--------|----------|------|
-| **npx (local stdio)** — add to an IDE with one command | Daily use on your machine | browser `login`, a JWT, or none (reference tools) |
-| **Remote HTTP (`serve`)** — run as a connector behind a URL | A hosted/shared server (e.g. Coolify) | per-request `x-webcake-jwt` header / `?jwt=` |
+| **npx (local)** — runs on your machine | Personal daily use, full control | browser `login`, a JWT, or none (reference tools) |
+| **Hosted URL** — use our live server, nothing to install | No Node.js, teams, the claude.ai dialog | your personal `?jwt=` link / `x-webcake-jwt` header |
 
 The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
 
 > 🛠️ Prefer a shell-script installer (`install.sh`/`install.ps1`), a cloned local build, or hand-written per-IDE config? See **[docs/manual-install.md](docs/manual-install.md)**.
 
+## 🚀 Get connected — the 2 main ways
+
+Pick **one**. Both hand your AI tool (Claude, Cursor, …) the full Webcake landing toolkit. No coding.
+
+### ① `npx` — runs on your machine (recommended for personal use)
+
+Zero install, always the latest version. **One line** grabs your token *and* writes the IDE config:
+
+```bash
+npx -y webcake-landing-mcp install
+```
+
+Just want to run the server (configure by hand later)?
+
+```bash
+npx -y webcake-landing-mcp
+```
+
+✅ Best for: daily personal use, local development, full control. Needs Node.js 18+.
+
+### ② Remote URL `…/mcp?jwt=` — hosted, nothing to install
+
+Use the server we already host. Grab **your personal link** (your token is baked in) and paste it into your client's *Add custom connector* / config:
+
+```
+https://mcp.toolvn.io.vn/mcp?jwt=<YOUR_TOKEN>
+```
+
+Two ways to get the link:
+- **Easiest** — open **<https://webcake.io/mcp-remote>** in your Webcake dashboard → it builds & copies the link for you.
+- **By hand** — see the step-by-step guide below.
+
+You can also add extra params: `&env=prod`, `&org_id=…`, `&api_base=…`.
+
+✅ Best for: no Node.js, team/shared use, the **claude.ai** connector dialog (URL-only, no headers).
+⚠️ The link contains your personal token — treat it like a password, always use **HTTPS**.
+
+> 📖 **Full hand-config for every IDE** (Claude Desktop, Claude Code, Cursor, Windsurf, claude.ai…) is in the
+> step-by-step guide → **[docs/connect-mcp.md](docs/connect-mcp.md)** · Tiếng Việt: **[docs/ket-noi-mcp.md](docs/ket-noi-mcp.md)**.
+
 ## Install (npx)
 
 Once published to npm, the server runs straight from the registry — no clone, no build:
@@ -127,34 +167,25 @@ The MCP config is the same as the local one, but `command`/`args` point at `npx`
 > npx caches the package after the first run, so subsequent launches are fast. Use a pinned version
 > (`webcake-landing-mcp@1.0.0`) if you need a reproducible build.
 
-## Run as a remote connector (Streamable HTTP)
+## Use the hosted server — nothing to install
 
-The server also speaks the **remote MCP** (Streamable HTTP) transport, so it can be added through
-Claude's **"Add custom connector"** dialog via a URL — not just as a local stdio server.
+It's **already live** at **`https://mcp.toolvn.io.vn/mcp`** — we run it for you. No server to set up, no
+machine to keep awake. Just point your AI client at the URL and go.
 
-Start it in HTTP mode (default port `8787`, or set `PORT` / `--port`):
+**Grab your personal link** (your token is baked in) the easy way → open **<https://webcake.io/mcp-remote>**
+and hit **Copy**:
 
-```bash
-npx -y webcake-landing-mcp serve --port 8787
-# → MCP endpoint at http://localhost:8787/mcp   (GET / or /health returns a status JSON)
+```
+https://mcp.toolvn.io.vn/mcp?jwt=<YOUR_TOKEN>
 ```
 
-Expose it over **HTTPS** at a public URL (a reverse proxy, a tunnel like `ngrok http 8787`, or any
-host), then in Claude → **Add custom connector**:
-
-- **Name**: `webcake-landing`
-- **Remote MCP server URL**: `https://<your-host>/mcp`
-
-The dialog has no header field, so to pass a token through it, **put it in the URL**:
-`https://<your-host>/mcp?jwt=<ljwt>` (also accepts `&api_base=…`, `&org_id=…`, `&host=…`, `&app_base=…`).
-Give each person a URL with their own `jwt` → **per-user without OAuth**. An explicit `x-webcake-jwt` header
-still wins over the query. ⚠️ A token in a URL can land in access/proxy logs — require **HTTPS** and disable
-query-string logging on your reverse proxy; a header (or OAuth) is safer when the client supports it.
+Optional extras: `&env=prod`, `&org_id=…`, `&api_base=…`. Hand each teammate a link with their own `jwt` →
+per-user, no OAuth. ⚠️ The link carries your personal token — treat it like a password, always over **HTTPS**.
 
-### Auth — per-request, multi-user (no shared token)
+### Sending the token as a header (safer)
 
-In stdio mode the JWT comes from env. In HTTP mode each request carries the caller's **own** credentials
-via headers, so a hosted server is multi-user and never bakes in a shared secret:
+Clients that support headers should send the token as a header instead of putting it in the URL (so it never
+lands in logs). Any header that's missing falls back to the matching env var:
 
 | Header | Maps to | Notes |
 |--------|---------|-------|
@@ -164,61 +195,12 @@ via headers, so a hosted server is multi-user and never bakes in a shared secret
 | `x-webcake-api-base` | `WEBCAKE_API_BASE` | overrides the env preset's API base |
 | `x-webcake-app-base` | `WEBCAKE_APP_BASE` | overrides the env preset's app base |
 
-Any header that is absent falls back to the corresponding env var — so you can also run it **single-user**
-by setting `WEBCAKE_API_BASE` + `WEBCAKE_JWT` in the host's env and keeping the URL private.
-
-> ⚠️ The reference + generation tools (`get_generation_guide`, `list_elements`, `validate_page`, …) need
-> no secret; only the persistence tools (`create_page`, `update_page`, …) use the JWT. If a request has no
-> JWT, those tools return `missing_env` instead of touching the network.
->
-> Note: the claude.ai connector dialog has **no header field** (only OAuth, which this server does not
-> implement yet). Two ways around it: put the token in the URL as `?jwt=<ljwt>` (above — per-user, but the
-> token shows up in logs), or use a header-capable client (`mcp-remote --header …`, below). A token in the
-> server's env instead gives a shared **single-account** for everyone on that URL.
-
-### Test it locally (no public URL needed)
-
-`localhost` can't be used in the claude.ai dialog (Anthropic fetches the URL from its own servers). To try the
-running `serve` server on your machine:
-
-- **MCP Inspector** (GUI — easiest): `npx @modelcontextprotocol/inspector` → Transport **Streamable HTTP** →
-  URL `http://localhost:8787/mcp` → under Headers add `x-webcake-jwt` (+ `x-webcake-api-base`) → Connect → call tools.
-- **`mcp-remote`** (use the remote server from a stdio client like Claude Desktop, with headers):
-  ```json
-  { "mcpServers": { "webcake-remote": { "command": "npx",
-    "args": ["-y", "mcp-remote", "http://localhost:8787/mcp",
-             "--header", "x-webcake-jwt:<ljwt>",
-             "--header", "x-webcake-api-base:https://api.webcake.io"] } } }
-  ```
-- **curl**: `initialize` (read the `mcp-session-id` response header) → `tools/list` → `tools/call`, all with
-  `Accept: application/json, text/event-stream`.
-
-### Deploy on a VPS
-
-1. **Build + run as a service** — `/etc/systemd/system/webcake-mcp.service`:
-   ```ini
-   [Service]
-   WorkingDirectory=/opt/webcake-landing-mcp
-   ExecStart=/usr/bin/node dist/index.js serve --port 8787
-   Environment=WEBCAKE_API_BASE=https://api.webcake.io
-   Environment=WEBCAKE_JWT=<ljwt>          # single-account only — see auth note below
-   Restart=always
-   [Install]
-   WantedBy=multi-user.target
-   ```
-   `sudo systemctl enable --now webcake-mcp` (build once: `npm install && npm run build`).
-2. **HTTPS + domain** (claude.ai requires https) — e.g. Caddy auto-TLS, `/etc/caddy/Caddyfile`:
-   ```
-   mcp.yourdomain.com { reverse_proxy localhost:8787 }
-   ```
-3. **Add to claude.ai** → Remote MCP server URL = `https://mcp.yourdomain.com/mcp`.
-
-**Auth on a shared server:**
-- **Single-account** (works with the dialog today): `WEBCAKE_JWT` in the service env → everyone using the
-  connector shares that one Webcake account. Keep the URL private / gated; the token expires (~90 days).
-- **Per-user** (each person their own account): give each person a URL with their own `?jwt=<ljwt>` (works
-  through the dialog, but the token appears in logs), or use a header-capable client (`mcp-remote --header …`),
-  or add **OAuth** (not implemented) for the cleanest flow.
+> The reference + generation tools (`get_generation_guide`, `list_elements`, `validate_page`, …) need **no
+> token** — only the persistence tools (`create_page`, `update_page`, …) use it. Without a JWT, those return
+> `missing_env` instead of touching the network.
+
+> 📖 **Full step-by-step for every IDE** (Claude Desktop, Claude Code, Cursor, Windsurf, claude.ai) →
+> **[docs/connect-mcp.md](docs/connect-mcp.md)** · Tiếng Việt: **[docs/ket-noi-mcp.md](docs/ket-noi-mcp.md)**.
 
 ## Connect once — grab your token automatically (`login`)
 
@@ -243,8 +225,8 @@ It opens your browser → (log into Webcake if needed) → the token is saved to
 
 You're already logged in to Webcake in your browser, so `login` just opens a Webcake "connect"
 page that reads your **`ljwt`** (landing) cookie and hands the token back to a localhost callback —
-no copy-paste. The saved token is used by **both** the stdio server and a single-user `serve`
-deployment (env vars still take precedence). The landing JWT lasts ~90 days, so you rarely reconnect.
+no copy-paste. The saved token is then read automatically (env vars still take precedence).
+The landing JWT lasts ~90 days, so you rarely reconnect.
 
 Two URLs, don't mix them up:
 
@@ -270,7 +252,7 @@ For safety, only honor `redirect_uri` values on `http://127.0.0.1:*` / `http://l
 flow can also be done entirely in the SPA, no backend route needed.)
 
 > Multi-user remote (the claude.ai connector dialog) can't do this browser loopback — there each
-> user sends their own token via the `x-webcake-jwt` header (see the remote-connector section above).
+> user sends their own token via the `x-webcake-jwt` header (see the hosted-server section above).
 
 ## Environment Variables
 
@@ -301,15 +283,14 @@ truth for the API + app bases:
 | `prod` | `https://api.webcake.io` | `https://webcake.io` |
 
 ```bash
-node dist/index.js serve --env staging        # remote server on the staging backend
-node dist/index.js login --env local          # connect against your local SPA + API
-WEBCAKE_ENV=prod node dist/index.js           # stdio, prod (env var form)
+npx -y webcake-landing-mcp login --env local       # connect against your local SPA + API
+WEBCAKE_ENV=staging npx -y webcake-landing-mcp      # run against the staging backend
+WEBCAKE_ENV=prod npx -y webcake-landing-mcp         # prod (env var form)
 ```
 
-Explicit `WEBCAKE_API_BASE` / `WEBCAKE_APP_BASE` (or `--api-base`) still override the
-preset, field by field. On the remote HTTP server a client can override the server's
-environment per request with the **`x-webcake-env`** header or **`?env=`** query
-(e.g. `…/mcp?jwt=<token>&env=staging`) — so one server can serve multiple environments.
+Explicit `WEBCAKE_API_BASE` / `WEBCAKE_APP_BASE` (or `--api-base`) still override the preset, field
+by field. On the hosted server you can override the environment per request with the
+**`x-webcake-env`** header or **`?env=`** query (e.g. `…/mcp?jwt=<token>&env=staging`).
 
 ### How to get `WEBCAKE_JWT`
 
@@ -330,93 +311,8 @@ cloned-build variants, see **[docs/manual-install.md](docs/manual-install.md#con
 
 ## Usage Examples
 
-### Example 1: Build a new landing page from a brief
-
-**Prompt:**
-```
-Build me a WebCake landing page for "Acme Coffee" — a hero with a CTA, a 3-feature
-section, and a signup form. Persist it to my default org.
-```
-
-**AI agent will automatically:**
-
-**Step 1** — Call `get_generation_guide` to learn conventions (canvas, coordinate system, events, workflow)
-
-**Step 2** — Call `new_page_skeleton` for an empty top-level source, then `get_element` for each type it uses:
-
-```
-get_element({ type: "section" })
-get_element({ type: "text-block" })
-get_element({ type: "button" })
-get_element({ type: "form" })
-```
-
-**Step 3** — Assemble the full `{ page, popup, settings, options, cartConfigs }` JSON, then validate:
-
-```
-validate_page({ source })
-→ { ok: false, errors: ["BUTTON-2: event target 'POPUP-9' not found"] }   # fix every error, re-validate
-validate_page({ source })
-→ { ok: true, errors: [] }
-```
-
-**Step 4** — Persist (dry-run first, then for real):
-
-```
-list_organizations({})                          → pick the org
-create_page({ source })                         → dry-run preview (JWT masked)
-create_page({ source, dry_run: false })         → { page_id, editor_url, preview_url }
-```
-
-Open the page in the editor and re-save to render `app`/`app_css`.
-
----
-
-### Example 2: Edit an existing page
-
-**Prompt:**
-```
-On my "Acme Coffee" landing page, change the hero headline to "Freshly Roasted Daily"
-and make the CTA button green.
-```
-
-**AI agent edits surgically — never regenerates the whole tree:**
-
-```
-# Step 1: find the page
-list_pages({})
-→ [{ id: "page_42", name: "Acme Coffee", organization_id: "org_1", ... }]
-
-# Step 2: fetch its decoded source tree
-get_page({ page_id: "page_42" })
-
-# Step 3: change ONLY the headline text + button color, keep every other id/coordinate,
-#         then validate and write back
-validate_page({ source })                       → ok
-update_page({ page_id: "page_42", source })     → dry-run preview
-update_page({ page_id: "page_42", source, dry_run: false })
-```
-
----
-
-### Example 3: Inspect an element type before using it
-
-**Prompt:**
-```
-What specials does a form element need, and show me a valid example.
-```
-
-**AI agent calls:**
-
-```
-get_element({ type: "form" })
-→ {
-    hints: "Each input needs a unique specials.field_name…",
-    specials: { ... },
-    skeleton: { ... },     # structurally-valid default node
-    example: { ... }       # filled, realistic example
-  }
-```
+Three end-to-end walkthroughs — build a page from a brief, edit one surgically, and inspect
+an element type — live in **[docs/usage-examples.md](docs/usage-examples.md)**.
 
 ---
 

package/README.vi.md

@@ -1,4 +1,4 @@
-# 🍰 WebCake Landing MCP
+# <img src="docs/assets/webcake-icon.svg" alt="Webcake" width="26" height="26" align="absmiddle"> WebCake Landing MCP
 
 [English](./README.md) · **Tiếng Việt**
 
@@ -59,13 +59,53 @@ lưu lại sẽ render).
 
 | Cách | Hợp cho | Auth |
 |------|---------|------|
-| **npx (local stdio)** — gắn vào IDE bằng một lệnh | Dùng hằng ngày trên máy | browser `login`, JWT, hoặc không cần (tool tham chiếu) |
-| **Remote HTTP (`serve`)** — chạy như connector sau một URL | Server hosted/chia sẻ (vd Coolify) | header `x-webcake-jwt` mỗi request / `?jwt=` |
+| **npx (local)** — chạy trên máy bạn | Dùng cá nhân hằng ngày, toàn quyền | browser `login`, JWT, hoặc không cần (tool tham chiếu) |
+| **URL đã host sẵn** — dùng server tụi mình, không cài gì | Máy không có Node.js, dùng nhóm, dialog claude.ai | link `?jwt=` cá nhân / header `x-webcake-jwt` |
 
 Các **tool tham chiếu + generation** (`get_generation_guide`, `list_elements`, `validate_page`, …) chạy **zero config**; chỉ **tool lưu trữ** (`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizations`) mới cần token. Token ưu tiên theo thứ tự: **header mỗi request → biến env → file `auth.json`** (`login`).
 
 > 🛠️ Cần script cài (install.sh/.ps1), build từ clone, hay cấu hình IDE thủ công? Xem **[docs/manual-install.vi.md](docs/manual-install.vi.md)**.
 
+## 🚀 Kết nối — 2 cách chính
+
+Chọn **một** trong hai. Cả hai đều đưa toàn bộ bộ công cụ dựng landing Webcake vào AI của bạn (Claude, Cursor, …). Không cần code.
+
+### ① `npx` — chạy ngay trên máy bạn (nên dùng cho cá nhân)
+
+Không cần cài đặt, luôn bản mới nhất. **Một dòng** vừa lấy token vừa ghi cấu hình IDE:
+
+```bash
+npx -y webcake-landing-mcp install
+```
+
+Chỉ muốn chạy server (tự cấu hình sau)?
+
+```bash
+npx -y webcake-landing-mcp
+```
+
+✅ Hợp cho: dùng cá nhân hằng ngày, dev local, toàn quyền kiểm soát. Cần Node.js 18+.
+
+### ② URL remote `…/mcp?jwt=` — đã host sẵn, không cần cài gì
+
+Dùng server tụi mình đã host. Lấy **link cá nhân của bạn** (token gắn sẵn trong link) rồi dán vào ô *Add custom connector* / file cấu hình của client:
+
+```
+https://mcp.toolvn.io.vn/mcp?jwt=<TOKEN_CỦA_BẠN>
+```
+
+Hai cách lấy link:
+- **Dễ nhất** — mở **<https://webcake.io/mcp-remote>** trong dashboard Webcake → nó tự tạo & copy link cho bạn.
+- **Thủ công** — xem hướng dẫn từng bước bên dưới.
+
+Có thể thêm tham số: `&env=prod`, `&org_id=…`, `&api_base=…`.
+
+✅ Hợp cho: máy không có Node.js, dùng nhóm/chia sẻ, và **dialog connector của claude.ai** (chỉ nhập URL, không có header).
+⚠️ Link chứa token cá nhân — coi như mật khẩu, luôn dùng **HTTPS**.
+
+> 📖 **Hướng dẫn cấu hình thủ công đầy đủ cho mọi IDE** (Claude Desktop, Claude Code, Cursor, Windsurf, claude.ai…)
+> ở file riêng → **[docs/ket-noi-mcp.md](docs/ket-noi-mcp.md)** · English: **[docs/connect-mcp.md](docs/connect-mcp.md)**.
+
 ## Cài đặt (npx)
 
 Sau khi đã publish lên npm, server chạy thẳng từ registry — không clone, không build:
@@ -128,34 +168,24 @@ Cấu hình MCP giống bản local, chỉ khác `command`/`args` trỏ tới `n
 > npx cache lại package sau lần chạy đầu, nên các lần sau khởi động nhanh. Dùng phiên bản ghim
 > (`webcake-landing-mcp@1.0.0`) nếu cần build tái lập được.
 
-## Chạy như remote connector (Streamable HTTP)
+## Dùng server đã host sẵn — không cần cài gì
 
-Server còn nói được transport **remote MCP** (Streamable HTTP), nên có thể thêm qua dialog
-**"Add custom connector"** của Claude bằng một URL — không chỉ stdio local.
+Server **đã chạy sẵn** tại **`https://mcp.toolvn.io.vn/mcp`** — tụi mình lo hết. Không phải dựng server,
+không phải giữ máy luôn bật. Chỉ cần trỏ AI của bạn vào URL là xong.
 
-Chạy chế độ HTTP (port mặc định `8787`, hoặc đặt `PORT` / `--port`):
+**Lấy link cá nhân** (token gắn sẵn) cách dễ nhất → mở **<https://webcake.io/mcp-remote>** rồi bấm **Copy**:
 
-```bash
-npx -y webcake-landing-mcp serve --port 8787
-# → endpoint MCP tại http://localhost:8787/mcp   (GET / hoặc /health trả JSON trạng thái)
+```
+https://mcp.toolvn.io.vn/mcp?jwt=<TOKEN_CỦA_BẠN>
 ```
 
-Đưa ra **HTTPS** ở URL public (reverse proxy, tunnel như `ngrok http 8787`, hoặc host bất kỳ), rồi vào
-Claude → **Add custom connector**:
-
-- **Name**: `webcake-landing`
-- **Remote MCP server URL**: `https://<host-của-bạn>/mcp`
-
-Dialog không có ô header, nên muốn truyền token qua đó thì **để vào URL**:
-`https://<host-của-bạn>/mcp?jwt=<ljwt>` (nhận thêm `&api_base=…`, `&org_id=…`, `&host=…`, `&app_base=…`).
-Mỗi người một URL với `jwt` riêng → **per-user mà không cần OAuth**. Header `x-webcake-jwt` thật vẫn ưu tiên
-hơn query. ⚠️ Token nằm trong URL có thể lọt vào access/proxy log — **bắt buộc HTTPS** và tắt log query ở
-reverse proxy; dùng header (hoặc OAuth) an toàn hơn nếu client hỗ trợ.
+Tham số thêm: `&env=prod`, `&org_id=…`, `&api_base=…`. Mỗi đồng đội một link với `jwt` riêng → mỗi người một
+tài khoản, không cần OAuth. ⚠️ Link chứa token cá nhân — coi như mật khẩu, luôn dùng **HTTPS**.
 
-### Auth — mỗi request, đa người dùng (không token chung)
+### Gửi token qua header (an toàn hơn)
 
-Ở stdio JWT lấy từ env. Ở chế độ HTTP, mỗi request mang credential **riêng** của người gọi qua header,
-nên server hosted là đa người dùng và không nhúng secret chung:
+Client nào set được header thì nên gửi token qua header thay vì nhét vào URL (token không lọt vào log).
+Header nào thiếu sẽ fallback về biến env tương ứng:
 
 | Header | Tương ứng | Ghi chú |
 |--------|-----------|---------|
@@ -165,60 +195,12 @@ nên server hosted là đa người dùng và không nhúng secret chung:
 | `x-webcake-api-base` | `WEBCAKE_API_BASE` | ghi đè API base của preset |
 | `x-webcake-app-base` | `WEBCAKE_APP_BASE` | ghi đè app base của preset |
 
-Header nào thiếu thì fallback về biến env tương ứng — nên cũng chạy **một người dùng** được bằng cách đặt
-`WEBCAKE_API_BASE` + `WEBCAKE_JWT` trong env của host và giữ URL riêng tư.
-
-> ⚠️ Tool tham chiếu + generation (`get_generation_guide`, `list_elements`, `validate_page`, …) không cần
-> secret; chỉ tool lưu trữ (`create_page`, `update_page`, …) dùng JWT. Request không có JWT thì các tool đó
-> trả `missing_env` chứ không gọi mạng.
->
-> Lưu ý: dialog claude.ai **không có ô header** (chỉ có OAuth, mà server này **chưa làm**). Hai cách lách:
-> để token vào URL dạng `?jwt=<ljwt>` (như trên — per-user, nhưng token lộ trong log), hoặc dùng client hỗ trợ
-> header (`mcp-remote --header …`, bên dưới). Đặt token ở env server thì thành **single-account** chung cho mọi người trên URL đó.
-
-### Test ở local (không cần URL public)
-
-`localhost` không dùng được trong dialog claude.ai (Anthropic gọi URL từ server của họ). Để thử server `serve`
-chạy trên máy:
-
-- **MCP Inspector** (GUI — dễ nhất): `npx @modelcontextprotocol/inspector` → Transport **Streamable HTTP** →
-  URL `http://localhost:8787/mcp` → mục Headers thêm `x-webcake-jwt` (+ `x-webcake-api-base`) → Connect → bấm gọi tool.
-- **`mcp-remote`** (dùng server remote từ client stdio như Claude Desktop, kèm header):
-  ```json
-  { "mcpServers": { "webcake-remote": { "command": "npx",
-    "args": ["-y", "mcp-remote", "http://localhost:8787/mcp",
-             "--header", "x-webcake-jwt:<ljwt>",
-             "--header", "x-webcake-api-base:https://api.webcake.io"] } } }
-  ```
-- **curl**: `initialize` (đọc header `mcp-session-id` trả về) → `tools/list` → `tools/call`, tất cả kèm
-  `Accept: application/json, text/event-stream`.
-
-### Deploy lên VPS
-
-1. **Build + chạy như service** — `/etc/systemd/system/webcake-mcp.service`:
-   ```ini
-   [Service]
-   WorkingDirectory=/opt/webcake-landing-mcp
-   ExecStart=/usr/bin/node dist/index.js serve --port 8787
-   Environment=WEBCAKE_API_BASE=https://api.webcake.io
-   Environment=WEBCAKE_JWT=<ljwt>          # chỉ cho single-account — xem ghi chú auth dưới
-   Restart=always
-   [Install]
-   WantedBy=multi-user.target
-   ```
-   `sudo systemctl enable --now webcake-mcp` (build 1 lần: `npm install && npm run build`).
-2. **HTTPS + domain** (claude.ai bắt buộc https) — vd Caddy tự cấp TLS, `/etc/caddy/Caddyfile`:
-   ```
-   mcp.yourdomain.com { reverse_proxy localhost:8787 }
-   ```
-3. **Thêm vào claude.ai** → Remote MCP server URL = `https://mcp.yourdomain.com/mcp`.
-
-**Auth trên server chia sẻ:**
-- **Single-account** (dùng được với dialog ngay): đặt `WEBCAKE_JWT` ở env service → mọi người dùng connector
-  chung 1 tài khoản Webcake. Giữ URL riêng tư / có cổng chặn; token hết hạn (~90 ngày).
-- **Per-user** (mỗi người 1 account): cho mỗi người một URL với `?jwt=<ljwt>` riêng (chạy được qua dialog,
-  nhưng token lộ trong log), hoặc dùng client hỗ trợ header (`mcp-remote --header …`), hoặc thêm **OAuth**
-  (chưa làm) cho gọn nhất.
+> Tool tham chiếu + generation (`get_generation_guide`, `list_elements`, `validate_page`, …) **không cần
+> token** — chỉ tool lưu trữ (`create_page`, `update_page`, …) mới dùng. Không có JWT thì các tool đó trả
+> `missing_env` chứ không gọi mạng.
+
+> 📖 **Hướng dẫn từng bước cho mọi IDE** (Claude Desktop, Claude Code, Cursor, Windsurf, claude.ai) →
+> **[docs/ket-noi-mcp.md](docs/ket-noi-mcp.md)** · English: **[docs/connect-mcp.md](docs/connect-mcp.md)**.
 
 ## Kết nối một lần — tự lấy token (`login`)
 
@@ -239,8 +221,7 @@ Nó mở browser → (đăng nhập Webcake nếu cần) → token được lưu
 
 Bạn đang đăng nhập Webcake sẵn trong browser, nên `login` chỉ mở trang "connect" của Webcake — trang này
 đọc cookie **`ljwt`** (landing) và trả token về một callback loopback nội bộ — khỏi copy-paste. Token đã lưu
-được dùng bởi **cả** server stdio lẫn deploy `serve` một-người-dùng (env vẫn ưu tiên). Landing JWT sống ~90
-ngày nên hiếm khi phải kết nối lại.
+sẽ được tự đọc (env vẫn ưu tiên). Landing JWT sống ~90 ngày nên hiếm khi phải kết nối lại.
 
 Hai URL, đừng nhầm:
 
@@ -266,7 +247,7 @@ GET /mcp-connect?redirect_uri=<loopback>&state=<s>
 SPA cũng được, khỏi cần route backend.)
 
 > Remote đa người dùng (dialog claude.ai) không làm được browser loopback này — ở đó mỗi user gửi token riêng
-> qua header `x-webcake-jwt` (xem mục remote-connector ở trên).
+> qua header `x-webcake-jwt` (xem mục server đã host sẵn ở trên).
 
 ## Biến môi trường
 
@@ -297,15 +278,14 @@ cho API + app base (mặc định là `prod`):
 | `prod` *(mặc định)* | `https://api.webcake.io` | `https://webcake.io` |
 
 ```bash
-node dist/index.js serve --env staging        # server remote trỏ backend staging
-node dist/index.js login --env local          # đăng nhập vào SPA + API local
-WEBCAKE_ENV=prod node dist/index.js           # stdio, prod (dạng biến môi trường)
+npx -y webcake-landing-mcp login --env local       # đăng nhập vào SPA + API local
+WEBCAKE_ENV=staging npx -y webcake-landing-mcp      # chạy trỏ backend staging
+WEBCAKE_ENV=prod npx -y webcake-landing-mcp         # prod (dạng biến môi trường)
 ```
 
 `WEBCAKE_API_BASE` / `WEBCAKE_APP_BASE` (hoặc `--api-base`) tường minh vẫn ghi đè preset theo từng
-trường. Trên server HTTP remote, client có thể ghi đè môi trường của server theo từng request bằng
-header **`x-webcake-env`** hoặc query **`?env=`** (ví dụ `…/mcp?jwt=<token>&env=staging`) — nên một
-server phục vụ được nhiều môi trường.
+trường. Trên server đã host sẵn, bạn có thể ghi đè môi trường theo từng request bằng header
+**`x-webcake-env`** hoặc query **`?env=`** (ví dụ `…/mcp?jwt=<token>&env=staging`).
 
 ### Cách lấy `WEBCAKE_JWT`
 
@@ -324,93 +304,8 @@ Lệnh con `install` của npx (xem trên) tự ghi cấu hình đúng cho từn
 
 ## Ví dụ sử dụng
 
-### Ví dụ 1: Dựng landing page mới từ một brief
-
-**Prompt:**
-```
-Dựng cho tôi một landing page WebCake cho "Acme Coffee" — một hero có CTA, một mục 3 tính năng,
-và một form đăng ký. Lưu vào org mặc định của tôi.
-```
-
-**AI sẽ tự động:**
-
-**Bước 1** — Gọi `get_generation_guide` để học quy ước (canvas, hệ toạ độ, sự kiện, workflow)
-
-**Bước 2** — Gọi `new_page_skeleton` để có source top-level rỗng, rồi `get_element` cho từng loại element nó dùng:
-
-```
-get_element({ type: "section" })
-get_element({ type: "text-block" })
-get_element({ type: "button" })
-get_element({ type: "form" })
-```
-
-**Bước 3** — Lắp trọn JSON `{ page, popup, settings, options, cartConfigs }`, rồi kiểm tra:
-
-```
-validate_page({ source })
-→ { ok: false, errors: ["BUTTON-2: event target 'POPUP-9' not found"] }   # sửa hết lỗi, validate lại
-validate_page({ source })
-→ { ok: true, errors: [] }
-```
-
-**Bước 4** — Lưu (dry-run trước, rồi mới thật):
-
-```
-list_organizations({})                          → chọn org
-create_page({ source })                         → xem trước dry-run (JWT được che)
-create_page({ source, dry_run: false })         → { page_id, editor_url, preview_url }
-```
-
-Mở trang trong editor và lưu lại để render `app`/`app_css`.
-
----
-
-### Ví dụ 2: Sửa một trang có sẵn
-
-**Prompt:**
-```
-Trên landing page "Acme Coffee" của tôi, đổi headline hero thành "Freshly Roasted Daily"
-và làm nút CTA màu xanh lá.
-```
-
-**AI sửa đúng chỗ — không bao giờ dựng lại cả cây:**
-
-```
-# Bước 1: tìm trang
-list_pages({})
-→ [{ id: "page_42", name: "Acme Coffee", organization_id: "org_1", ... }]
-
-# Bước 2: lấy cây source đã decode
-get_page({ page_id: "page_42" })
-
-# Bước 3: chỉ đổi text headline + màu nút, giữ mọi id/toạ độ khác,
-#         rồi validate và ghi lại
-validate_page({ source })                       → ok
-update_page({ page_id: "page_42", source })     → xem trước dry-run
-update_page({ page_id: "page_42", source, dry_run: false })
-```
-
----
-
-### Ví dụ 3: Xem chi tiết một loại element trước khi dùng
-
-**Prompt:**
-```
-Một element form cần những specials gì, và cho tôi xem một ví dụ hợp lệ.
-```
-
-**AI gọi:**
-
-```
-get_element({ type: "form" })
-→ {
-    hints: "Mỗi input cần một specials.field_name duy nhất…",
-    specials: { ... },
-    skeleton: { ... },     # node mặc định hợp lệ về cấu trúc
-    example: { ... }       # ví dụ đã điền, thực tế
-  }
-```
+Ba luồng đầy đủ — dựng trang từ brief, sửa trang đúng chỗ, và xem chi tiết một loại element —
+nằm ở **[docs/usage-examples.vi.md](docs/usage-examples.vi.md)**.
 
 ---
 

package/dist/branding.js

@@ -0,0 +1,29 @@
+/**
+ * Brand icon for the MCP server, shared by both transports.
+ *
+ * Why this exists: an MCP client (e.g. the claude.ai custom-connector UI) shows
+ * a generic globe when it can't find an icon for the server. Two mechanisms can
+ * supply one, so we feed BOTH from this single source:
+ *   1. A favicon served over HTTP (`/favicon.ico` / `/favicon.svg`) — what
+ *      favicon-style clients fetch from the server's origin.
+ *   2. `serverInfo.icons` in the `initialize` result (MCP spec) — a self-contained
+ *      data URI so it works without the server knowing its own public URL.
+ *
+ * The mark is the official Webcake logo — the green tile with a white "W"
+ * (source: builderx_spa/src/assets/icon/webcake-small.svg).
+ */
+// The official Webcake icon: a Webcake-green (#1DB954) rounded tile with a white
+// "W" letterform. Kept inline (dependency-free) so it can be served raw AND
+// inlined as a data URI. Keep in sync with the SPA's webcake-small.svg.
+export const ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="28" height="28" viewBox="0 0 28 28" fill="none">' +
+    '<path d="M2.8285 3.64772C2.8285 3.64772 0.40187 14.238 2.8285 25.0176C2.8285 25.0176 13.5197 27.158 25.2727 25.0176C25.2727 25.0176 27.4716 14.1507 25.2727 3.65595C25.2727 3.64772 16.0217 1.34592 2.8285 3.64772Z" fill="#1DB954"/>' +
+    '<path d="M18.5722 19.0697H15.3989L14.4468 14.9073C14.4023 14.7328 14.3309 14.3865 14.2327 13.8684C14.1345 13.3503 14.0632 12.9167 14.0187 12.5677C13.9827 12.8509 13.9228 13.2032 13.8474 13.6231C13.7721 14.0429 13.6762 14.4299 13.6059 14.7756C13.5357 15.1214 13.1967 16.5555 12.6178 19.0565H9.4394L6.97852 9.50684H9.56784L10.6536 14.3064C10.8979 15.3656 11.0657 16.2086 11.1571 16.8354C11.2153 16.3963 11.3203 15.7926 11.4722 15.0242C11.624 14.2559 11.7656 13.6247 11.8969 13.1308L12.7737 9.51671H15.2551L16.1114 13.1308C16.2569 13.7087 16.4042 14.3788 16.5532 15.1362C16.7022 15.8936 16.8032 16.4534 16.8529 16.8354C16.9065 16.3513 17.0664 15.5116 17.3324 14.3162L18.4284 9.51671H21.0177L18.5722 19.0697Z" fill="white"/>' +
+    "</svg>";
+export const ICON_MIME = "image/svg+xml";
+// Self-contained data URI for serverInfo.icons (no public URL required).
+export const ICON_DATA_URI = `data:${ICON_MIME};base64,${Buffer.from(ICON_SVG).toString("base64")}`;
+// Public-facing identity reused across the server metadata.
+export const BRAND = {
+    title: "Webcake Landing",
+    websiteUrl: "https://webcake.io",
+};

package/dist/http.js

@@ -16,6 +16,7 @@ import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createServer } from "./server.js";
+import { ICON_SVG, ICON_MIME } from "./branding.js";
 const MCP_PATH = "/mcp";
 function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json" });
@@ -65,8 +66,25 @@ export async function startHttpServer(port) {
     const transports = new Map();
     const httpServer = createHttpServer(async (req, res) => {
         const path = (req.url ?? "").split("?")[0];
+        // Brand icon — clients (e.g. the claude.ai connector) fetch a favicon from the
+        // server origin; without one they show a generic globe. Served raw as SVG.
+        if (req.method === "GET" && (path === "/favicon.ico" || path === "/favicon.svg" || path === "/icon.svg")) {
+            res.writeHead(200, { "content-type": ICON_MIME, "cache-control": "public, max-age=86400" });
+            return res.end(ICON_SVG);
+        }
         // Lightweight health check for hosting platforms.
         if (req.method === "GET" && (path === "/" || path === "/health")) {
+            // A browser/connector probing the root with `Accept: text/html` gets a tiny
+            // page that links the favicon (helps icon discovery); programmatic probes
+            // (the container healthcheck uses `Accept: */*`) still get the JSON health.
+            const accept = String(req.headers["accept"] ?? "");
+            if (path === "/" && accept.includes("text/html")) {
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                return res.end(`<!doctype html><meta charset="utf-8"><title>Webcake Landing MCP</title>` +
+                    `<link rel="icon" type="${ICON_MIME}" href="/favicon.svg">` +
+                    `<body style="font-family:system-ui;padding:40px">` +
+                    `<h2>Webcake Landing MCP</h2><p>Streamable-HTTP MCP server. Endpoint: <code>${MCP_PATH}</code>.</p></body>`);
+            }
             return sendJson(res, 200, { ok: true, server: "webcake-landing", transport: "streamable-http", endpoint: MCP_PATH });
         }
         if (path !== MCP_PATH)

package/dist/server.js

@@ -9,8 +9,17 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { landingDomain } from "./domains/landing/index.js";
 import { registerTools } from "./tools/index.js";
+import { ICON_DATA_URI, ICON_MIME, BRAND } from "./branding.js";
 export function createServer() {
-    const server = new McpServer({ name: "webcake-landing", version: "1.0.0" }, { instructions: landingDomain.instructions });
+    const server = new McpServer({
+        name: "webcake-landing",
+        version: "1.0.0",
+        // Shown by MCP clients (e.g. the claude.ai connector) instead of a generic
+        // globe. icons is per the MCP spec; the data URI keeps it self-contained.
+        title: BRAND.title,
+        websiteUrl: BRAND.websiteUrl,
+        icons: [{ src: ICON_DATA_URI, mimeType: ICON_MIME, sizes: ["any"] }],
+    }, { instructions: landingDomain.instructions });
     registerTools(server, landingDomain);
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "type": "module",
   "bin": {