webcake-landing-mcp 1.0.9 → 1.0.11

package/README.md

@@ -54,80 +54,18 @@ valid element/page skeletons, a page validator, and tools to create or edit page
 The AI agent produces the full `{ page, popup, settings, options, cartConfigs }` JSON; `create_page`
 persists it (source-only — the page opens in the editor where re-saving renders it).
 
-## Setup methods (pick one)
+## Two ways to run
 
-| # | Method | Best for | Auth | Jump to |
-|---|--------|----------|------|---------|
-| 1 | **Local stdio** — add to an IDE (Claude Desktop / Cursor / …) via `npx` or a built file | Daily use on your machine | env `WEBCAKE_JWT`, or `login`, or none (reference tools) | [IDE config](#configuration-by-ide--ai-tool) |
-| 2 | **`login`** — grab the token through the browser (no copy-paste) | Avoiding a manual token paste (stdio / single-user remote) | browser session → saved `auth.json` | [Connect once](#connect-once--grab-your-token-automatically-login) |
-| 3 | **Remote HTTP (`serve`)** — run as an HTTP server, test with MCP Inspector / `mcp-remote` / curl | Trying the remote transport locally | per-request `x-webcake-jwt` header, or env | [Remote](#run-as-a-remote-connector-streamable-http) |
-| 4 | **VPS + claude.ai connector** — deploy public HTTPS, add as a custom connector | Sharing one hosted server | single-account (env token); per-user needs OAuth (not implemented) | [Deploy on a VPS](#deploy-on-a-vps) |
-
-Two **run forms** apply to any method: **`npx -y webcake-landing-mcp …`** (no clone, auto-updates) or **`node /abs/path/dist/index.js …`** (a cloned build — run `npm run build` first). The IDE configs below show the local form; swap `command`/`args` for the npx form to use CDN mode.
+| 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=` |
 
 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`).
 
-## Quick Install (Recommended)
-
-Run the auto-install script — it handles everything: clone, install dependencies, build, and configure your IDE.
-
-### macOS / Linux
-
-If you already cloned the repo:
-```bash
-./install.sh
-```
-
-Or download and run directly:
-```bash
-curl -fsSL https://raw.githubusercontent.com/vuluu2k/webcake-landing-mcp/main/install.sh -o install.sh && bash install.sh
-```
-
-The installer is interactive: it asks where to install (default `~/.webcake-landing-mcp`), prompts for
-the env vars (`WEBCAKE_API_BASE`, `WEBCAKE_JWT`, `WEBCAKE_ORG_ID` — all optional, Enter to skip), then
-lets you pick which IDE(s) to configure: `claude-desktop`, `claude-code`, `cursor`, `windsurf`, `augment`,
-`codex`, or all.
+> 🛠️ 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)**.
 
-Uninstall (removes the MCP server entry from every configured IDE):
-```bash
-./install.sh --uninstall
-```
-
-### Windows (PowerShell)
-
-If you already cloned the repo:
-```powershell
-.\install.ps1
-```
-
-Or download and run directly:
-```powershell
-irm https://raw.githubusercontent.com/vuluu2k/webcake-landing-mcp/main/install.ps1 -OutFile install.ps1; .\install.ps1
-```
-
-Uninstall:
-```powershell
-.\install.ps1 --uninstall
-```
-
----
-
-## Update
-
-Update to the latest version:
-
-```bash
-cd ~/.webcake-landing-mcp   # or wherever you installed it
-git pull
-npm install
-npm run build
-```
-
-Then restart your IDE.
-
----
-
-## Run without cloning (npx)
+## Install (npx)
 
 Once published to npm, the server runs straight from the registry — no clone, no build:
 
@@ -143,18 +81,18 @@ npx -y github:vuluu2k/webcake-landing-mcp
 
 ### Auto-configure your IDE (`install` subcommand)
 
-`npx` only **runs** the server — unlike `install.sh`/`install.ps1`, it does not write the MCP
-config into your IDE. The bundled `install` subcommand does that step for you, no clone needed:
+`npx` only **runs** the server — unlike the [shell installers](docs/manual-install.md), it does not
+write the MCP config into your IDE. The bundled `install` subcommand does that step for you, no clone needed:
 
 ```bash
-# Interactive — asks for env + which IDE(s) step by step
+# Interactive — pick environment, log in via browser (or paste a JWT), pick IDE(s)
 npx -y webcake-landing-mcp install
 
-# Non-interactive — configure every supported IDE at once
-npx -y webcake-landing-mcp install --ide all --jwt <your-jwt> --api-base http://localhost:5800
+# Non-interactive — configure every supported IDE at once (env + token via flags)
+npx -y webcake-landing-mcp install --ide all --env prod --jwt <your-jwt>
 
-# Just one IDE
-npx -y webcake-landing-mcp install --ide cursor --jwt <your-jwt>
+# Local dev — point at your local stack (localhost:5800 / :5173)
+npx -y webcake-landing-mcp install --ide cursor --env local --jwt <your-jwt>
 
 # Remove the server from every IDE config
 npx -y webcake-landing-mcp uninstall
@@ -162,8 +100,10 @@ npx -y webcake-landing-mcp uninstall
 
 It writes a `webcake-landing` entry (using the `npx` launch form below) into the right config file
 for each target: `claude-desktop`, `claude-code`, `cursor`, `windsurf`, `augment` (VS Code), `codex`,
-or `all`. Flags: `--ide`, `--api-base`, `--jwt`, `--org-id`, `--host`, `--app-base`, `--npx`/`--local`,
-`-y`. Run `npx -y webcake-landing-mcp --help` for the full list.
+or `all`. Interactively it asks for the **environment** (`local`/`staging`/`prod`, which sets the API +
+app URLs) and whether to **log in via the browser or paste a JWT**. Flags: `--ide`, `--env`, `--jwt`,
+`--org-id`, `--api-base`/`--app-base` (advanced overrides), `--npx`/`--local`, `-y`. Run
+`npx -y webcake-landing-mcp install --help` for the full list.
 
 ### Manual config
 
@@ -176,7 +116,7 @@ The MCP config is the same as the local one, but `command`/`args` point at `npx`
       "command": "npx",
       "args": ["-y", "webcake-landing-mcp"],
       "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
+        "WEBCAKE_ENV": "prod",
         "WEBCAKE_JWT": "<your-jwt>"
       }
     }
@@ -219,10 +159,10 @@ via headers, so a hosted server is multi-user and never bakes in a shared secret
 | Header | Maps to | Notes |
 |--------|---------|-------|
 | `x-webcake-jwt` (or `Authorization: Bearer <jwt>`) | `WEBCAKE_JWT` | the account token — sent per request |
+| `x-webcake-env` | `WEBCAKE_ENV` | named environment (`local`/`staging`/`prod`) |
 | `x-webcake-org-id` | `WEBCAKE_ORG_ID` | default org |
-| `x-webcake-api-base` | `WEBCAKE_API_BASE` | usually set once via env on the host instead |
-| `x-webcake-host` | `WEBCAKE_HOST` | Phoenix host-routing header |
-| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | editor/preview URL base |
+| `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.
@@ -280,19 +220,6 @@ running `serve` server on your machine:
   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.
 
-## Manual Setup (local)
-
-```bash
-git clone https://github.com/vuluu2k/webcake-landing-mcp.git
-cd webcake-landing-mcp
-npm install        # postinstall `prepare` builds dist/ automatically
-npm run build      # (re)build: tsc -> dist/ + copies src/**/*.json (page-schema.json) into dist/
-npm run smoke      # offline self-test of factory + validator (prints "ALL GOOD")
-```
-
-The reference/validation tools work with **zero config**. Env vars are only needed for the persistence
-tools (`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizations`).
-
 ## Connect once — grab your token automatically (`login`)
 
 Instead of copying a JWT by hand, run:
@@ -301,7 +228,11 @@ Instead of copying a JWT by hand, run:
 # Production — zero config (defaults: connect via webcake.io, API via api.webcake.io):
 npx -y webcake-landing-mcp login
 
-# Local dev — point at your local SPA (5173) + API (5800):
+# Local dev / staging — pick a named environment (see Environments below):
+node dist/index.js login --env local      # SPA :5173 + API :5800
+node dist/index.js login --env staging    # staging.webcake.io + api.staging.webcake.io
+
+# …or point at custom URLs explicitly (these override --env):
 node dist/index.js login \
   --connect-url http://localhost:5173/mcp-connect \
   --api-base http://localhost:5800
@@ -317,9 +248,8 @@ deployment (env vars still take precedence). The landing JWT lasts ~90 days, so
 
 Two URLs, don't mix them up:
 
-- **Connect page = the SPA** (`--connect-url` / `WEBCAKE_CONNECT_URL`): `https://webcake.io/mcp-connect`
-  in prod, `http://localhost:5173/mcp-connect` locally. Otherwise derived from `WEBCAKE_APP_BASE` +
-  `/mcp-connect`, defaulting to `https://webcake.io/mcp-connect`.
+- **Connect page = the SPA** (`--connect-url`): derived from the `--env` app base + `/mcp-connect`
+  (`https://webcake.io/mcp-connect` for prod, `http://localhost:5173/mcp-connect` for local). Override with `--connect-url`.
 - **API base = the backend** (`--api-base` / `WEBCAKE_API_BASE`): `https://api.webcake.io` in prod,
   `http://localhost:5800` locally. Defaults to `https://api.webcake.io`.
 
@@ -346,12 +276,11 @@ flow can also be done entirely in the SPA, no backend route needed.)
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `WEBCAKE_API_BASE` | No* | Backend base URL, e.g. `http://localhost:5800`. Required to persist. |
+| `WEBCAKE_ENV` | No | Named environment: `local` \| `staging` \| `prod`. Fills in `WEBCAKE_API_BASE` + `WEBCAKE_APP_BASE` from a preset (see table below). Also settable with the `--env <name>` flag. Explicit vars win. |
+| `WEBCAKE_API_BASE` | No* | Backend base URL, e.g. `http://localhost:5800`. Required to persist (or set `WEBCAKE_ENV`). |
 | `WEBCAKE_JWT` | No* | Account JWT (dashboard auth). Required to persist — expires, refresh when needed. |
 | `WEBCAKE_ORG_ID` | No | Default organization id for `create_page` (overridden by its `organization_id` arg). Omit → personal page. |
-| `WEBCAKE_HOST` | No | Optional `Host` header (Phoenix routes by host, e.g. `builder.localhost`). |
 | `WEBCAKE_APP_BASE` | No | Optional base used to build editor/preview URLs in the result. |
-| `WEBCAKE_CONNECT_URL` | No | The SPA "connect" page for `login` (default `https://webcake.io/mcp-connect`; else `WEBCAKE_APP_BASE` + `/mcp-connect`). |
 | `WEBCAKE_CONFIG_DIR` | No | Dir for the saved `auth.json` written by `login` (default `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` and `WEBCAKE_JWT` are only needed for the persistence tools. The reference and
@@ -360,183 +289,44 @@ flow can also be done entirely in the SPA, no backend route needed.)
 > Persisting writes a real page to whatever `WEBCAKE_API_BASE` points at, using the JWT as that account.
 > Start against local/staging.
 
-### How to get `WEBCAKE_JWT`
-
-1. Open the WebCake builder dashboard and log in
-2. Open DevTools (`F12` or `Cmd + Option + I`)
-3. Go to the **Network** tab > click any page
-4. Find an API request (e.g. `@me`, `organizations`…)
-5. In **Request Headers**, copy the value after `Authorization: Bearer ` → this is your `WEBCAKE_JWT`
-6. Use the `list_organizations` tool to list orgs and pick `WEBCAKE_ORG_ID`
-
----
-
-## Configuration by IDE / AI Tool
+### Environments (`--env` / `WEBCAKE_ENV`)
 
-> Replace `/absolute-path/webcake-landing-mcp/dist/index.js` below with the actual path where you
-> cloned/built the repo. Example: `/Users/username/webcake-landing-mcp/dist/index.js`.
-> Run `npm run build` first so `dist/` exists.
+Instead of setting both base URLs by hand, pick a named environment — one source of
+truth for the API + app bases:
 
-### 1. Claude Desktop
-
-Open Settings > Developer > Edit Config, or edit the file directly:
-
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>",
-        "WEBCAKE_HOST": "builder.localhost",
-        "WEBCAKE_APP_BASE": "http://builder.localhost:5800"
-      }
-    }
-  }
-}
-```
-
-Restart Claude Desktop. The MCP tools will appear in the chat input (hammer icon).
-
----
-
-### 2. Claude Code (CLI)
-
-Run in terminal — **local** build:
+| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) |
+|-------------------------|-------------------------------|-------------------------------|
+| `local` | `http://localhost:5800` | `http://localhost:5173` |
+| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` |
+| `prod` | `https://api.webcake.io` | `https://webcake.io` |
 
 ```bash
-claude mcp add webcake-landing \
-  -e WEBCAKE_API_BASE=http://localhost:5800 \
-  -e WEBCAKE_JWT=<your-jwt> \
-  -e WEBCAKE_HOST=builder.localhost \
-  -- node /absolute-path/webcake-landing-mcp/dist/index.js
+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)
 ```
 
-Or **CDN / npx** (no clone):
+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.
 
-```bash
-claude mcp add webcake-landing \
-  -e WEBCAKE_API_BASE=http://localhost:5800 \
-  -e WEBCAKE_JWT=<your-jwt> \
-  -- npx -y webcake-landing-mcp
-```
-
-Or create `.claude.json` at project root (or `~/.claude.json` globally):
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>"
-      }
-    }
-  }
-}
-```
-
-Verify:
-```bash
-claude mcp list
-```
-
----
-
-### 3. Cursor
-
-Create `.cursor/mcp.json` at project root (or `~/.cursor/mcp.json` globally):
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>"
-      }
-    }
-  }
-}
-```
-
-Restart Cursor and check Settings > MCP Servers for **"Connected"** status.
-
----
-
-### 4. Windsurf
-
-Create `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>"
-      }
-    }
-  }
-}
-```
-
-Restart Windsurf. Type `@` in Cascade chat to see `webcake-landing` tools.
-
----
-
-### 5. Augment (VS Code Extension)
-
-Open Command Palette: `Cmd + Shift + P` > **"Augment: Edit MCP Settings"**, then add:
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>"
-      }
-    }
-  }
-}
-```
+### How to get `WEBCAKE_JWT`
 
-Restart VS Code.
+1. Open the WebCake builder dashboard and log in
+2. Open DevTools (`F12` or `Cmd + Option + I`)
+3. Go to the **Network** tab > click any page
+4. Find an API request (e.g. `@me`, `organizations`…)
+5. In **Request Headers**, copy the value after `Authorization: Bearer ` → this is your `WEBCAKE_JWT`
+6. Use the `list_organizations` tool to list orgs and pick `WEBCAKE_ORG_ID`
 
 ---
 
-### 6. Codex (OpenAI CLI)
-
-Add to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.webcake-landing]
-command = "node"
-args = ["/absolute-path/webcake-landing-mcp/dist/index.js"]
-env = { "WEBCAKE_API_BASE" = "http://localhost:5800", "WEBCAKE_JWT" = "<your-jwt>" }
-```
+## Per-IDE config
 
-Verify:
-```bash
-codex mcp list
-```
-
----
+The npx **`install`** subcommand (above) writes the right config for each IDE automatically. For
+hand-written config (Claude Desktop, Claude Code, Cursor, Windsurf, Augment, Codex) and the
+cloned-build variants, see **[docs/manual-install.md](docs/manual-install.md#configuration-by-ide--ai-tool)**.
 
 ## Usage Examples
 

package/README.vi.md

@@ -55,79 +55,18 @@ element/trang hợp lệ, bộ kiểm tra trang, và các tool để tạo/sửa
 `{ page, popup, settings, options, cartConfigs }`; `create_page` lưu nó (chỉ-source — trang mở trong editor,
 lưu lại sẽ render).
 
-## Các cách setup (chọn một)
+## Hai cách chạy
 
-| # | Cách | Hợp cho | Auth | Xem |
-|---|------|---------|------|-----|
-| 1 | **Local stdio** — gắn vào IDE (Claude Desktop / Cursor / …) qua `npx` hoặc file build | Dùng hằng ngày trên máy | env `WEBCAKE_JWT`, hoặc `login`, hoặc không cần (tool tham chiếu) | [Cấu hình IDE](#cấu-hình-theo-ide--công-cụ-ai) |
-| 2 | **`login`** — tự lấy token qua browser (khỏi copy-paste) | Khỏi dán token tay (stdio / remote 1 người) | session browser → file `auth.json` | [Kết nối một lần](#kết-nối-một-lần--tự-lấy-token-login) |
-| 3 | **Remote HTTP (`serve`)** — chạy như HTTP server, test bằng MCP Inspector / `mcp-remote` / curl | Thử transport remote ở local | header `x-webcake-jwt` mỗi request, hoặc env | [Remote](#chạy-như-remote-connector-streamable-http) |
-| 4 | **VPS + claude.ai connector** — deploy HTTPS public, thêm làm custom connector | Chia sẻ 1 server hosted | single-account (token env); per-user cần OAuth (chưa có) | [Deploy lên VPS](#deploy-lên-vps) |
-
-Hai **dạng chạy** áp dụng cho mọi cách: **`npx -y webcake-landing-mcp …`** (không clone, tự cập nhật) hoặc **`node /abs/path/dist/index.js …`** (bản đã clone & build — chạy `npm run build` trước). Cấu hình IDE bên dưới dùng dạng local; đổi `command`/`args` sang dạng npx để dùng CDN.
+| 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=` |
 
 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ài nhanh (Khuyến nghị)
-
-Chạy script tự cài — lo trọn gói: clone, cài dependencies, build, và cấu hình IDE của bạn.
-
-### macOS / Linux
-
-Nếu bạn đã clone repo:
-```bash
-./install.sh
-```
-
-Hoặc tải & chạy trực tiếp:
-```bash
-curl -fsSL https://raw.githubusercontent.com/vuluu2k/webcake-landing-mcp/main/install.sh -o install.sh && bash install.sh
-```
-
-Trình cài tương tác: hỏi nơi cài (mặc định `~/.webcake-landing-mcp`), hỏi các biến môi trường
-(`WEBCAKE_API_BASE`, `WEBCAKE_JWT`, `WEBCAKE_ORG_ID` — đều tuỳ chọn, Enter để bỏ qua), rồi cho bạn chọn
-IDE cần cấu hình: `claude-desktop`, `claude-code`, `cursor`, `windsurf`, `augment`, `codex`, hoặc tất cả.
+> 🛠️ 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)**.
 
-Gỡ cài (xoá entry MCP server khỏi mọi IDE đã cấu hình):
-```bash
-./install.sh --uninstall
-```
-
-### Windows (PowerShell)
-
-Nếu bạn đã clone repo:
-```powershell
-.\install.ps1
-```
-
-Hoặc tải & chạy trực tiếp:
-```powershell
-irm https://raw.githubusercontent.com/vuluu2k/webcake-landing-mcp/main/install.ps1 -OutFile install.ps1; .\install.ps1
-```
-
-Gỡ cài:
-```powershell
-.\install.ps1 --uninstall
-```
-
----
-
-## Cập nhật
-
-Cập nhật lên bản mới nhất:
-
-```bash
-cd ~/.webcake-landing-mcp   # hoặc nơi bạn đã cài
-git pull
-npm install
-npm run build
-```
-
-Rồi khởi động lại IDE.
-
----
-
-## Chạy không cần clone (npx)
+## Cài đặt (npx)
 
 Sau khi đã publish lên npm, server chạy thẳng từ registry — không clone, không build:
 
@@ -143,27 +82,29 @@ npx -y github:vuluu2k/webcake-landing-mcp
 
 ### Tự cấu hình IDE (lệnh con `install`)
 
-`npx` chỉ **chạy** server — khác với `install.sh`/`install.ps1`, nó không ghi cấu hình MCP vào IDE.
+`npx` chỉ **chạy** server — khác với [script cài đặt](docs/manual-install.vi.md), nó không ghi cấu hình MCP vào IDE.
 Lệnh con `install` đi kèm sẽ làm hộ bạn bước đó, không cần clone:
 
 ```bash
-# Tương tác — hỏi env + chọn IDE từng bước
+# Tương tác — chọn môi trường, đăng nhập qua trình duyệt (hoặc dán JWT), chọn IDE
 npx -y webcake-landing-mcp install
 
-# Không tương tác — cấu hình mọi IDE hỗ trợ cùng lúc
-npx -y webcake-landing-mcp install --ide all --jwt <your-jwt> --api-base http://localhost:5800
+# Không tương tác — cấu hình mọi IDE hỗ trợ cùng lúc (env + token qua cờ)
+npx -y webcake-landing-mcp install --ide all --env prod --jwt <your-jwt>
 
-# Chỉ một IDE
-npx -y webcake-landing-mcp install --ide cursor --jwt <your-jwt>
+# Local dev — trỏ vào stack local của bạn (localhost:5800 / :5173)
+npx -y webcake-landing-mcp install --ide cursor --env local --jwt <your-jwt>
 
 # Gỡ server khỏi mọi cấu hình IDE
 npx -y webcake-landing-mcp uninstall
 ```
 
 Nó ghi entry `webcake-landing` (dùng dạng khởi chạy `npx` bên dưới) vào đúng file cấu hình của từng IDE:
-`claude-desktop`, `claude-code`, `cursor`, `windsurf`, `augment` (VS Code), `codex`, hoặc `all`. Cờ:
-`--ide`, `--api-base`, `--jwt`, `--org-id`, `--host`, `--app-base`, `--npx`/`--local`, `-y`. Chạy
-`npx -y webcake-landing-mcp --help` để xem đầy đủ.
+`claude-desktop`, `claude-code`, `cursor`, `windsurf`, `augment` (VS Code), `codex`, hoặc `all`. Khi tương
+tác, nó hỏi **môi trường** (`local`/`staging`/`prod` — mặc định `prod`, dùng để đặt API + app URL) và cho
+chọn **đăng nhập qua trình duyệt hay dán JWT**. Cờ: `--ide`, `--env`, `--jwt`, `--org-id`,
+`--api-base`/`--app-base` (ghi đè nâng cao), `--npx`/`--local`, `-y`. Chạy
+`npx -y webcake-landing-mcp install --help` để xem đầy đủ.
 
 ### Cấu hình thủ công
 
@@ -176,7 +117,7 @@ Cấu hình MCP giống bản local, chỉ khác `command`/`args` trỏ tới `n
       "command": "npx",
       "args": ["-y", "webcake-landing-mcp"],
       "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
+        "WEBCAKE_ENV": "prod",
         "WEBCAKE_JWT": "<your-jwt>"
       }
     }
@@ -219,9 +160,10 @@ nên server hosted là đa người dùng và không nhúng secret chung:
 | Header | Tương ứng | Ghi chú |
 |--------|-----------|---------|
 | `x-webcake-jwt` (hoặc `Authorization: Bearer <jwt>`) | `WEBCAKE_JWT` | token tài khoản — gửi mỗi request |
+| `x-webcake-env` | `WEBCAKE_ENV` | môi trường có tên (`local`/`staging`/`prod`) |
 | `x-webcake-org-id` | `WEBCAKE_ORG_ID` | org mặc định |
-| `x-webcake-api-base` | `WEBCAKE_API_BASE` | thường set 1 lần qua env trên host |
-| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | base URL editor/preview |
+| `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ư.
@@ -278,19 +220,6 @@ chạy trên máy:
   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.
 
-## Cài thủ công (local)
-
-```bash
-git clone https://github.com/vuluu2k/webcake-landing-mcp.git
-cd webcake-landing-mcp
-npm install        # postinstall `prepare` tự build dist/
-npm run build      # (re)build: tsc -> dist/ + copy src/**/*.json (page-schema.json) vào dist/
-npm run smoke      # self-test offline của factory + validator (in "ALL GOOD")
-```
-
-Các tool tham chiếu/kiểm tra chạy với **zero config**. Biến môi trường chỉ cần cho các tool lưu trữ
-(`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizations`).
-
 ## Kết nối một lần — tự lấy token (`login`)
 
 Thay vì copy JWT bằng tay, chạy:
@@ -315,9 +244,8 @@ ngày nên hiếm khi phải kết nối lại.
 
 Hai URL, đừng nhầm:
 
-- **Trang connect = SPA** (`--connect-url` / `WEBCAKE_CONNECT_URL`): `https://webcake.io/mcp-connect` ở prod,
-  `http://localhost:5173/mcp-connect` ở local. Nếu không, suy ra từ `WEBCAKE_APP_BASE` + `/mcp-connect`,
-  mặc định `https://webcake.io/mcp-connect`.
+- **Trang connect = SPA** (`--connect-url`): suy ra từ app base của `--env` + `/mcp-connect`
+  (`https://webcake.io/mcp-connect` ở prod, `http://localhost:5173/mcp-connect` ở local). Ghi đè bằng `--connect-url`.
 - **API base = backend** (`--api-base` / `WEBCAKE_API_BASE`): `https://api.webcake.io` ở prod,
   `http://localhost:5800` ở local. Mặc định `https://api.webcake.io`.
 
@@ -344,12 +272,11 @@ SPA cũng được, khỏi cần route backend.)
 
 | Biến | Bắt buộc | Mô tả |
 |----------|----------|-------------|
-| `WEBCAKE_API_BASE` | Không* | Base URL backend, ví dụ `http://localhost:5800`. Cần để lưu trang. |
+| `WEBCAKE_ENV` | Không | Môi trường có tên: `local` \| `staging` \| `prod`. Điền sẵn `WEBCAKE_API_BASE` + `WEBCAKE_APP_BASE` từ preset (xem bảng bên dưới). Cũng đặt được qua cờ `--env <name>`. Biến tường minh sẽ thắng. |
+| `WEBCAKE_API_BASE` | Không* | Base URL backend, ví dụ `http://localhost:5800`. Cần để lưu trang (hoặc đặt `WEBCAKE_ENV`). |
 | `WEBCAKE_JWT` | Không* | JWT tài khoản (auth dashboard). Cần để lưu trang — sẽ hết hạn, làm mới khi cần. |
 | `WEBCAKE_ORG_ID` | Không | Organization mặc định cho `create_page` (bị ghi đè bởi tham số `organization_id`). Bỏ trống → trang cá nhân. |
-| `WEBCAKE_HOST` | Không | Header `Host` tuỳ chọn (Phoenix route theo host, ví dụ `builder.localhost`). |
 | `WEBCAKE_APP_BASE` | Không | Base tuỳ chọn để dựng URL editor/preview trong kết quả. |
-| `WEBCAKE_CONNECT_URL` | Không | Trang "connect" (SPA) cho `login` (mặc định `https://webcake.io/mcp-connect`; nếu không thì `WEBCAKE_APP_BASE` + `/mcp-connect`). |
 | `WEBCAKE_CONFIG_DIR` | Không | Thư mục chứa `auth.json` do `login` ghi (mặc định `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` và `WEBCAKE_JWT` chỉ cần cho các tool lưu trữ. Các tool tham chiếu và kiểm tra
@@ -358,183 +285,42 @@ SPA cũng được, khỏi cần route backend.)
 > Lưu trang sẽ ghi một trang thật vào nơi `WEBCAKE_API_BASE` trỏ tới, dùng JWT làm tài khoản đó.
 > Hãy bắt đầu với local/staging.
 
-### Cách lấy `WEBCAKE_JWT`
-
-1. Mở dashboard builder WebCake và đăng nhập
-2. Mở DevTools (`F12` hoặc `Cmd + Option + I`)
-3. Vào tab **Network** > click một trang bất kỳ
-4. Tìm một request API (ví dụ `@me`, `organizations`…)
-5. Trong **Request Headers**, copy giá trị sau `Authorization: Bearer ` → đó là `WEBCAKE_JWT`
-6. Dùng tool `list_organizations` để liệt kê org và chọn `WEBCAKE_ORG_ID`
-
----
-
-## Cấu hình theo IDE / công cụ AI
-
-> Thay `/absolute-path/webcake-landing-mcp/dist/index.js` bên dưới bằng đường dẫn thật nơi bạn đã
-> clone/build repo. Ví dụ: `/Users/username/webcake-landing-mcp/dist/index.js`.
-> Chạy `npm run build` trước để `dist/` tồn tại.
-
-### 1. Claude Desktop
-
-Mở Settings > Developer > Edit Config, hoặc sửa file trực tiếp:
-
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>",
-        "WEBCAKE_HOST": "builder.localhost",
-        "WEBCAKE_APP_BASE": "http://builder.localhost:5800"
-      }
-    }
-  }
-}
-```
-
-Khởi động lại Claude Desktop. Các tool MCP sẽ hiện trong ô chat (biểu tượng búa).
-
----
-
-### 2. Claude Code (CLI)
-
-Chạy trong terminal — bản **local**:
-
-```bash
-claude mcp add webcake-landing \
-  -e WEBCAKE_API_BASE=http://localhost:5800 \
-  -e WEBCAKE_JWT=<your-jwt> \
-  -e WEBCAKE_HOST=builder.localhost \
-  -- node /absolute-path/webcake-landing-mcp/dist/index.js
-```
-
-Hoặc **CDN / npx** (không clone):
-
-```bash
-claude mcp add webcake-landing \
-  -e WEBCAKE_API_BASE=http://localhost:5800 \
-  -e WEBCAKE_JWT=<your-jwt> \
-  -- npx -y webcake-landing-mcp
-```
+### Môi trường (`--env` / `WEBCAKE_ENV`)
 
-Hoặc tạo `.claude.json` ở thư mục gốc dự án (hoặc `~/.claude.json` toàn cục):
+Thay vì đặt thủ công cả hai base URL, hãy chọn một môi trường có tên — một nguồn sự thật duy nhất
+cho API + app base (mặc định là `prod`):
 
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>"
-      }
-    }
-  }
-}
-```
+| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) |
+|-------------------------|-------------------------------|-------------------------------|
+| `local` | `http://localhost:5800` | `http://localhost:5173` |
+| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` |
+| `prod` *(mặc định)* | `https://api.webcake.io` | `https://webcake.io` |
 
-Kiểm tra:
 ```bash
-claude mcp list
+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)
 ```
 
----
-
-### 3. Cursor
+`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.
 
-Tạo `.cursor/mcp.json` ở gốc dự án (hoặc `~/.cursor/mcp.json` toàn cục):
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>"
-      }
-    }
-  }
-}
-```
-
-Khởi động lại Cursor và xem Settings > MCP Servers để thấy trạng thái **"Connected"**.
-
----
-
-### 4. Windsurf
-
-Tạo `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>"
-      }
-    }
-  }
-}
-```
-
-Khởi động lại Windsurf. Gõ `@` trong chat Cascade để thấy các tool `webcake-landing`.
-
----
-
-### 5. Augment (Extension VS Code)
-
-Mở Command Palette: `Cmd + Shift + P` > **"Augment: Edit MCP Settings"**, rồi thêm:
-
-```json
-{
-  "mcpServers": {
-    "webcake-landing": {
-      "command": "node",
-      "args": ["/absolute-path/webcake-landing-mcp/dist/index.js"],
-      "env": {
-        "WEBCAKE_API_BASE": "http://localhost:5800",
-        "WEBCAKE_JWT": "<your-jwt>"
-      }
-    }
-  }
-}
-```
+### Cách lấy `WEBCAKE_JWT`
 
-Khởi động lại VS Code.
+1. Mở dashboard builder WebCake và đăng nhập
+2. Mở DevTools (`F12` hoặc `Cmd + Option + I`)
+3. Vào tab **Network** > click một trang bất kỳ
+4. Tìm một request API (ví dụ `@me`, `organizations`…)
+5. Trong **Request Headers**, copy giá trị sau `Authorization: Bearer ` → đó là `WEBCAKE_JWT`
+6. Dùng tool `list_organizations` để liệt kê org và chọn `WEBCAKE_ORG_ID`
 
 ---
 
-### 6. Codex (OpenAI CLI)
-
-Thêm vào `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.webcake-landing]
-command = "node"
-args = ["/absolute-path/webcake-landing-mcp/dist/index.js"]
-env = { "WEBCAKE_API_BASE" = "http://localhost:5800", "WEBCAKE_JWT" = "<your-jwt>" }
-```
+## Cấu hình theo IDE
 
-Kiểm tra:
-```bash
-codex mcp list
-```
-
----
+Lệnh con `install` của npx (xem trên) tự ghi cấu hình đúng cho từng IDE. Nếu muốn tự viết tay cấu hình cho Claude Desktop, Claude Code, Cursor, Windsurf, Augment, hay Codex — và cả dạng dùng file build từ clone — xem **[docs/manual-install.vi.md](docs/manual-install.vi.md#cấu-hình-theo-ide--công-cụ-ai)**.
 
 ## Ví dụ sử dụng
 

package/dist/auth/login.js

@@ -11,7 +11,7 @@
  *      which the stdio/http server then reads automatically.
  *
  * Backend contract (added to landing_page_backend — owned by the user):
- *   GET {WEBCAKE_CONNECT_URL}?redirect_uri=<loopback>&state=<s>
+ *   GET <connect-url>?redirect_uri=<loopback>&state=<s>   (connect-url = appBase + /mcp-connect)
  *     → read cookie `jwt` → 302 to <redirect_uri>?token=<jwt>&state=<s>
  *       (or 302 to the login page first, then back). Restrict redirect_uri to
  *       http://127.0.0.1:* / http://localhost:* for safety.
@@ -19,13 +19,7 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
-import { saveSavedConfig } from "../persistence/config.js";
-// Production defaults — the connect page lives on the SPA (webcake.io), the API
-// lives on api.webcake.io. For local dev override with --connect-url / --api-base
-// (e.g. http://localhost:5173/mcp-connect and http://localhost:5800) or the
-// WEBCAKE_APP_BASE / WEBCAKE_API_BASE env vars.
-const DEFAULT_CONNECT_URL = "https://webcake.io/mcp-connect";
-const DEFAULT_API_BASE = "https://api.webcake.io";
+import { saveSavedConfig, resolveEnv, ENVIRONMENTS } from "../persistence/config.js";
 function parseArgs(argv) {
     const get = (name) => {
         const i = argv.indexOf(name);
@@ -53,21 +47,20 @@ function openBrowser(url) {
 const SUCCESS_HTML = `<!doctype html><meta charset="utf-8"><title>Connected</title>
 <body style="font-family:system-ui;text-align:center;padding:48px">
 <h2>✓ Connected to Webcake</h2><p>You can close this tab and return to your terminal.</p></body>`;
-function resolveConnectUrl(opts) {
+function resolveConnectUrl(opts, appBase) {
     if (opts.connectUrl)
-        return opts.connectUrl;
-    if (process.env.WEBCAKE_CONNECT_URL)
-        return process.env.WEBCAKE_CONNECT_URL;
-    // The connect page is on the SPA (WEBCAKE_APP_BASE), NOT the API base.
-    const appBase = process.env.WEBCAKE_APP_BASE;
-    if (appBase)
-        return `${appBase.replace(/\/+$/, "")}/mcp-connect`;
-    return DEFAULT_CONNECT_URL;
+        return opts.connectUrl; // explicit --connect-url override
+    // The connect page is on the SPA (appBase, from the env preset), NOT the API base.
+    return `${appBase.replace(/\/+$/, "")}/mcp-connect`;
 }
 export async function runLogin(argv) {
     const opts = parseArgs(argv);
-    const connectUrl = resolveConnectUrl(opts);
-    const apiBase = opts.apiBase || process.env.WEBCAKE_API_BASE || DEFAULT_API_BASE;
+    // Named environment (set by the global --env flag / WEBCAKE_ENV); prod is the
+    // zero-config default. Explicit --api-base / WEBCAKE_APP_BASE still win per field.
+    const preset = resolveEnv(process.env.WEBCAKE_ENV) ?? ENVIRONMENTS.prod;
+    const apiBase = opts.apiBase || process.env.WEBCAKE_API_BASE || preset.apiBase;
+    const appBase = process.env.WEBCAKE_APP_BASE || preset.appBase;
+    const connectUrl = resolveConnectUrl(opts, appBase);
     const state = randomBytes(16).toString("hex");
     await new Promise((resolve, reject) => {
         const server = createServer((req, res) => {
@@ -83,15 +76,13 @@ export async function runLogin(argv) {
             }
             const path = saveSavedConfig({
                 jwt: token,
-                ...(apiBase ? { base: apiBase.replace(/\/+$/, "") } : {}),
+                base: apiBase.replace(/\/+$/, ""),
+                appBase: appBase.replace(/\/+$/, ""),
                 ...(opts.orgId ? { orgId: opts.orgId } : {}),
                 savedAt: new Date().toISOString(),
             });
             res.writeHead(200, { "content-type": "text/html" }).end(SUCCESS_HTML);
-            console.error(`\n✓ Connected. Token saved to ${path}`);
-            if (!apiBase) {
-                console.error("  tip: also set WEBCAKE_API_BASE (or pass --api-base) so the server knows the backend URL.");
-            }
+            console.error(`\n✓ Connected. Token saved to ${path} (api ${apiBase}).`);
             server.close();
             resolve();
         });

package/dist/http.js

@@ -39,9 +39,9 @@ async function readBody(req) {
 // require HTTPS, and disable query-string logging on your reverse proxy.
 const QUERY_AUTH = {
     jwt: "x-webcake-jwt",
+    env: "x-webcake-env",
     api_base: "x-webcake-api-base",
     org_id: "x-webcake-org-id",
-    host: "x-webcake-host",
     app_base: "x-webcake-app-base",
 };
 function applyQueryAuth(req) {

package/dist/index.js

@@ -17,7 +17,40 @@
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
+import { ENVIRONMENTS, ENV_NAMES, isEnvName } from "./persistence/config.js";
+/**
+ * Global `--env <local|staging|prod>` flag (or `--env=<name>`): selects the API +
+ * app base URLs from a named preset by setting WEBCAKE_ENV, which readConfig + login
+ * then pick up. Explicit WEBCAKE_API_BASE / WEBCAKE_APP_BASE still win. An unknown
+ * value from the flag fails fast; an unknown WEBCAKE_ENV is dropped so explicit
+ * bases (or per-request headers) still resolve. stderr only — stdout is the MCP channel.
+ */
+function applyEnvFlag(argv) {
+    let fromFlag;
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--env")
+            fromFlag = argv[i + 1];
+        else if (a.startsWith("--env="))
+            fromFlag = a.slice("--env=".length);
+    }
+    const name = fromFlag ?? process.env.WEBCAKE_ENV;
+    if (!name)
+        return;
+    if (!isEnvName(name)) {
+        console.error(`[webcake] unknown environment "${name}". Valid: ${ENV_NAMES.join(", ")}.`);
+        if (fromFlag)
+            process.exit(1); // explicit flag typo → fail fast
+        delete process.env.WEBCAKE_ENV; // bad WEBCAKE_ENV → ignore, fall through to explicit bases
+        return;
+    }
+    process.env.WEBCAKE_ENV = name;
+    const p = ENVIRONMENTS[name];
+    console.error(`[webcake] environment "${name}" — api ${p.apiBase}, app ${p.appBase}`);
+}
 async function main() {
+    // Resolve the named environment (--env / WEBCAKE_ENV) before any config is read.
+    applyEnvFlag(process.argv);
     // Subcommand dispatch: `webcake-landing-mcp install|uninstall` runs the
     // bundled IDE installer instead of starting the MCP server. Default (no
     // subcommand) starts the stdio server as usual.

package/dist/install.js

@@ -22,6 +22,8 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
+import { ENVIRONMENTS, isEnvName } from "./persistence/config.js";
+import { runLogin } from "./auth/login.js";
 const NAME = "webcake-landing";
 const PKG = "webcake-landing-mcp";
 const HOME = homedir();
@@ -63,8 +65,6 @@ function parseArgs(argv) {
             o.jwt = next();
         else if (a.startsWith("--org-id") || a.startsWith("--org"))
             o.orgId = next();
-        else if (a.startsWith("--host"))
-            o.host = next();
         else if (a.startsWith("--app-base"))
             o.appBase = next();
         else if (a === "--help" || a === "-h")
@@ -290,18 +290,18 @@ function printHelp() {
 ${c.bold}webcake-landing-mcp install${c.reset} — configure the MCP server in your IDE(s)
 
 ${c.bold}Usage${c.reset}
-  npx -y ${PKG} install                 # interactive (asks step by step)
-  npx -y ${PKG} install --ide all       # non-interactive, all IDEs
-  npx -y ${PKG} install --ide claude-code --jwt <JWT> --api-base http://localhost:5800
+  npx -y ${PKG} install                 # interactive: pick environment, log in (or paste a JWT), pick IDEs
+  npx -y ${PKG} install --ide all       # non-interactive, all IDEs (defaults to --env prod)
+  npx -y ${PKG} install --ide claude-code --env local --jwt <JWT>
   npx -y ${PKG} uninstall               # remove from every IDE config
 
 ${c.bold}Flags${c.reset}
   --ide <list>      comma list: claude-desktop, claude-code, cursor, windsurf, augment, codex, all
-  --api-base <url>  WEBCAKE_API_BASE (default http://localhost:5800)
-  --jwt <token>     WEBCAKE_JWT (account token; optional, needed to persist)
-  --org-id <id>     WEBCAKE_ORG_ID (optional)
-  --host <host>     WEBCAKE_HOST (optional)
-  --app-base <url>  WEBCAKE_APP_BASE (optional)
+  --env <name>      WEBCAKE_ENV: local | staging | prod (default prod) — sets the API + app base URLs
+  --jwt <token>     WEBCAKE_JWT (account token; optional — or log in via the browser interactively)
+  --org-id <id>     WEBCAKE_ORG_ID (optional default organization)
+  --api-base <url>  override the --env API base (advanced)
+  --app-base <url>  override the --env app base (advanced)
   --npx | --local   force the launch command form (default: auto-detect)
   -y, --yes         accept defaults, skip confirmations
   --uninstall       remove the server from all IDE configs
@@ -317,36 +317,70 @@ export async function runInstaller(argv) {
     log(`\n${c.cyan}${c.bold}Webcake Landing MCP — installer${c.reset}`);
     log(`${c.gray}Build & edit Webcake landing pages from a prompt. 12 tools.${c.reset}`);
     const interactive = !o.ide && process.stdin.isTTY && process.stdout.isTTY;
-    // 1) env
-    const env = {};
-    let apiBase = o.apiBase ?? process.env.WEBCAKE_API_BASE ?? "";
-    let jwt = o.jwt ?? process.env.WEBCAKE_JWT ?? "";
-    let orgId = o.orgId ?? process.env.WEBCAKE_ORG_ID ?? "";
-    const host = o.host ?? process.env.WEBCAKE_HOST ?? "";
-    const appBase = o.appBase ?? process.env.WEBCAKE_APP_BASE ?? "";
-    if (interactive) {
-        log(`\n${c.bold}1) Config${c.reset} ${c.gray}(Enter to skip — reference tools work with no creds)${c.reset}`);
-        apiBase =
-            (await ask(`  WEBCAKE_API_BASE [${apiBase || "http://localhost:5800"}]: `)) ||
-                apiBase ||
-                "http://localhost:5800";
-        jwt = (await ask(`  WEBCAKE_JWT (account token, optional): `)) || jwt;
-        orgId = (await ask(`  WEBCAKE_ORG_ID (optional): `)) || orgId;
+    // 1) environment — one choice sets the API + app base URLs (replaces the old
+    //    separate WEBCAKE_API_BASE / WEBCAKE_APP_BASE prompts). The global --env flag
+    //    / WEBCAKE_ENV is already validated in index.ts (applyEnvFlag).
+    let envName = isEnvName(process.env.WEBCAKE_ENV) ? process.env.WEBCAKE_ENV : "prod";
+    if (interactive && !isEnvName(process.env.WEBCAKE_ENV)) {
+        log(`\n${c.bold}1) Environment${c.reset} ${c.gray}(sets the Webcake API + app URLs)${c.reset}`);
+        log(`  1) prod      ${c.gray}${ENVIRONMENTS.prod.apiBase}${c.reset}  ${c.gray}(default)${c.reset}`);
+        log(`  2) staging   ${c.gray}${ENVIRONMENTS.staging.apiBase}${c.reset}`);
+        log(`  3) local     ${c.gray}${ENVIRONMENTS.local.apiBase}${c.reset}`);
+        const pick = (await ask("  Select [1=prod, Enter to accept]: ")).trim();
+        envName = { "1": "prod", "2": "staging", "3": "local" }[pick] ?? "prod";
+    }
+    process.env.WEBCAKE_ENV = envName; // so `login` below connects to the same environment
+    const preset = ENVIRONMENTS[envName];
+    // 2) authentication — interactively ASK how to authenticate: browser login (token
+    //    saved to ~/.webcake-landing-mcp/auth.json) or a pasted JWT. An explicit --jwt
+    //    skips the prompt; a non-TTY falls back to the WEBCAKE_JWT env var (for scripted
+    //    installs). Reference/validation tools work with no auth at all.
+    let jwt = o.jwt ?? "";
+    let authNote = jwt ? "JWT (from --jwt)" : "";
+    if (interactive && !jwt) {
+        log(`\n${c.bold}2) Authentication${c.reset} ${c.gray}(only needed to save pages to your account)${c.reset}`);
+        log(`  1) Log in via browser   ${c.gray}(recommended — opens Webcake, saves a token)${c.reset}`);
+        log(`  2) Paste a JWT token`);
+        log(`  3) Skip for now         ${c.gray}(reference/validation tools still work)${c.reset}`);
+        const pick = (await ask("  Select [1]: ")).trim() || "1";
+        if (pick === "1") {
+            info(`Connecting to ${preset.appBase} …`);
+            try {
+                await runLogin([]); // reads WEBCAKE_ENV for the connect URL + API base; saves auth.json
+                authNote = "browser login (saved to auth.json)";
+            }
+            catch (e) {
+                warn(`Login didn't complete (${e?.message ?? e}). Paste a JWT now, or run \`${PKG} login\` later.`);
+                jwt = (await ask("  WEBCAKE_JWT (or Enter to skip): ")).trim();
+            }
+        }
+        else if (pick === "2") {
+            jwt = (await ask("  WEBCAKE_JWT: ")).trim();
+        }
     }
-    else if (!apiBase) {
-        apiBase = "http://localhost:5800";
+    else if (!interactive) {
+        jwt = jwt || process.env.WEBCAKE_JWT || ""; // scripted / CI: fall back to ambient env
+    }
+    if (!authNote)
+        authNote = jwt ? "JWT" : "none — reference tools only";
+    // 3) optional default organization for create_page
+    let orgId = o.orgId ?? process.env.WEBCAKE_ORG_ID ?? "";
+    if (interactive && !orgId) {
+        orgId = (await ask(`\n${c.bold}3) WEBCAKE_ORG_ID${c.reset} ${c.gray}(optional, Enter to skip): ${c.reset}`)).trim();
     }
-    if (apiBase)
-        env.WEBCAKE_API_BASE = apiBase;
+    // env block written into IDE configs: WEBCAKE_ENV drives the URLs. A pasted JWT is
+    // written too; a browser login lives in auth.json instead. --api-base/--app-base/
+    // --host stay as advanced overrides for non-standard setups.
+    const env = { WEBCAKE_ENV: envName };
     if (jwt)
         env.WEBCAKE_JWT = jwt;
     if (orgId)
         env.WEBCAKE_ORG_ID = orgId;
-    if (host)
-        env.WEBCAKE_HOST = host;
-    if (appBase)
-        env.WEBCAKE_APP_BASE = appBase;
-    // 2) which IDEs
+    if (o.apiBase)
+        env.WEBCAKE_API_BASE = o.apiBase;
+    if (o.appBase)
+        env.WEBCAKE_APP_BASE = o.appBase;
+    // 4) which IDEs
     let ides = [];
     if (o.ide) {
         ides = o.ide
@@ -355,7 +389,7 @@ export async function runInstaller(argv) {
             .filter(Boolean);
     }
     else if (interactive) {
-        log(`\n${c.bold}2) Which IDE(s) to configure?${c.reset}`);
+        log(`\n${c.bold}4) Which IDE(s) to configure?${c.reset}`);
         log("  1) Claude Desktop   2) Claude Code (CLI)   3) Cursor");
         log("  4) Windsurf         5) Augment (VS Code)   6) Codex");
         log("  7) All              0) Skip");
@@ -383,13 +417,13 @@ export async function runInstaller(argv) {
         warn("No IDE selected — skipping configuration.");
         return;
     }
-    // 3) write
+    // 5) write
     const launch = resolveLaunch(o);
-    log(`\n${c.bold}3) Writing config${c.reset} ${c.gray}(launch: ${launch.command} ${launch.args.join(" ")})${c.reset}`);
+    log(`\n${c.bold}5) Writing config${c.reset} ${c.gray}(launch: ${launch.command} ${launch.args.join(" ")})${c.reset}`);
     runConfigure(ides, launch, env);
-    // 4) summary
+    // 6) summary
     log(`\n${c.green}${c.bold}✓ Done.${c.reset}`);
-    log(`  ${c.gray}API base : ${apiBase || "(unset)"}${c.reset}`);
-    log(`  ${c.gray}JWT      : ${jwt ? jwt.slice(0, 8) + "…" : "(unset — reference tools still work)"}${c.reset}`);
+    log(`  ${c.gray}Environment : ${envName}  (api ${o.apiBase || preset.apiBase})${c.reset}`);
+    log(`  ${c.gray}Auth        : ${authNote}${c.reset}`);
     log(`  Restart your IDE, then ask the AI: “Build a Webcake landing page”.\n`);
 }

package/dist/persistence/config.js

@@ -12,19 +12,44 @@
  * { config: null, missing } when required values are absent so the persistence
  * tools can report exactly what to provide.
  *
+ *   WEBCAKE_ENV       optional named environment (local|staging|prod) — fills in the
+ *                     API + app base URLs from a preset (see ENVIRONMENTS below). An
+ *                     explicit WEBCAKE_API_BASE / WEBCAKE_APP_BASE still wins over it.
  *   WEBCAKE_API_BASE  e.g. http://localhost:5800   (required to call the backend)
  *   WEBCAKE_JWT       the account JWT               (required to call the backend)
  *   WEBCAKE_ORG_ID    optional default organization id for create_page
- *   WEBCAKE_HOST      optional Host header override (Phoenix routes by host)
  *   WEBCAKE_APP_BASE  optional base for editor/preview URLs in the result
  *   WEBCAKE_CONFIG_DIR  optional dir for the saved auth.json (default ~/.webcake-landing-mcp)
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+/**
+ * Named deployment environments — the single source of truth for the API + app
+ * base URLs. Selecting one (via the `--env` flag, WEBCAKE_ENV, the `x-webcake-env`
+ * header, or `?env=` in the URL) fills in both bases so callers don't repeat them.
+ * Explicit WEBCAKE_API_BASE / WEBCAKE_APP_BASE (or per-request overrides) win over
+ * the preset. `apiBase` is the backend; `appBase` is the SPA (editor/preview/connect).
+ */
+export const ENVIRONMENTS = {
+    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173" },
+    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io" },
+    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io" },
+};
+export const ENV_NAMES = Object.keys(ENVIRONMENTS);
+/** True when `v` names a known environment (local|staging|prod). */
+export function isEnvName(v) {
+    return typeof v === "string" && Object.prototype.hasOwnProperty.call(ENVIRONMENTS, v);
+}
+/** The base URLs for a named environment, or undefined when the name is absent/unknown. */
+export function resolveEnv(name) {
+    return isEnvName(name) ? ENVIRONMENTS[name] : undefined;
+}
 export function readConfig(overrides = {}) {
     const saved = readSavedConfig();
-    const base = overrides.base ?? process.env.WEBCAKE_API_BASE ?? saved.base;
+    // A named environment supplies default base URLs; explicit values still win.
+    const preset = resolveEnv(overrides.env ?? process.env.WEBCAKE_ENV);
+    const base = overrides.base ?? process.env.WEBCAKE_API_BASE ?? preset?.apiBase ?? saved.base;
     const jwt = overrides.jwt ?? process.env.WEBCAKE_JWT ?? saved.jwt;
     const missing = [];
     if (!base)
@@ -38,8 +63,7 @@ export function readConfig(overrides = {}) {
             base: base.replace(/\/+$/, ""),
             jwt: jwt,
             orgId: overrides.orgId ?? process.env.WEBCAKE_ORG_ID ?? saved.orgId,
-            host: overrides.host ?? process.env.WEBCAKE_HOST ?? saved.host,
-            appBase: (overrides.appBase ?? process.env.WEBCAKE_APP_BASE ?? saved.appBase)?.replace(/\/+$/, ""),
+            appBase: (overrides.appBase ?? process.env.WEBCAKE_APP_BASE ?? preset?.appBase ?? saved.appBase)?.replace(/\/+$/, ""),
         },
         missing: [],
     };
@@ -53,9 +77,9 @@ function header(headers, name) {
  * send its own credentials per request instead of a server-wide env token:
  *   x-webcake-jwt        the account JWT (or `Authorization: Bearer <jwt>`)
  *   x-webcake-org-id     organization id
- *   x-webcake-api-base   backend base URL (usually set once via env instead)
- *   x-webcake-host       Host header override
- *   x-webcake-app-base   editor/preview URL base
+ *   x-webcake-env        named environment (local|staging|prod) for the base URLs
+ *   x-webcake-api-base   backend base URL (overrides the env preset)
+ *   x-webcake-app-base   editor/preview URL base (overrides the env preset)
  * Any header that is absent falls back to the corresponding env var in readConfig.
  */
 export function configFromHeaders(headers) {
@@ -65,8 +89,8 @@ export function configFromHeaders(headers) {
         base: header(headers, "x-webcake-api-base"),
         jwt: header(headers, "x-webcake-jwt") ?? bearer,
         orgId: header(headers, "x-webcake-org-id"),
-        host: header(headers, "x-webcake-host"),
         appBase: header(headers, "x-webcake-app-base"),
+        env: header(headers, "x-webcake-env"),
     };
 }
 /** Directory for the saved auth file (override with WEBCAKE_CONFIG_DIR). */

package/dist/persistence/webcake-client.js

@@ -10,8 +10,6 @@ function authHeaders(config, orgId) {
         Authorization: `Bearer ${config.jwt}`,
         Cookie: `jwt=${config.jwt}`,
     };
-    if (config.host)
-        headers["Host"] = config.host;
     const org = orgId ?? config.orgId;
     if (org != null && `${org}` !== "")
         headers["x-org-id"] = `${org}`;

package/dist/smoke.js

@@ -4,6 +4,7 @@
  */
 import { createElement, CONTAINER_TYPES, FIELD_TYPES, LIBRARY, ELEMENT_TYPES, ELEMENTS, } from "./domains/landing/elements/index.js";
 import { validatePage, pageSchema } from "./domains/landing/validate.js";
+import { readConfig, resolveEnv, ENV_NAMES } from "./persistence/config.js";
 let failures = 0;
 const check = (name, cond, extra) => {
     if (cond) {
@@ -208,5 +209,21 @@ const bindingsGood = {
 };
 const rbg = validatePage(bindingsGood);
 check("clean form has no binding warnings", rbg.warnings.length === 0, rbg.warnings);
+console.log("== config: named environment presets (local/staging/prod) ==");
+{
+    // Deterministic: isolate from any ambient WEBCAKE_* and the saved auth.json on the dev box.
+    for (const k of ["WEBCAKE_API_BASE", "WEBCAKE_APP_BASE", "WEBCAKE_ENV", "WEBCAKE_JWT", "WEBCAKE_ORG_ID"])
+        delete process.env[k];
+    process.env.WEBCAKE_CONFIG_DIR = "/nonexistent/webcake-smoke";
+    check("env names are local/staging/prod", setEq(new Set(ENV_NAMES), ["local", "staging", "prod"]), ENV_NAMES);
+    check("staging preset resolves to api+app bases", resolveEnv("staging")?.apiBase === "https://api.staging.webcake.io" && resolveEnv("staging")?.appBase === "https://staging.webcake.io");
+    check("unknown env name → undefined", resolveEnv("bogus") === undefined);
+    const prod = readConfig({ env: "prod", jwt: "t" }).config;
+    check("readConfig(env=prod) fills api+app base", prod?.base === "https://api.webcake.io" && prod?.appBase === "https://webcake.io", prod);
+    const local = readConfig({ env: "local", jwt: "t" }).config;
+    check("readConfig(env=local) fills api+app base", local?.base === "http://localhost:5800" && local?.appBase === "http://localhost:5173", local);
+    check("explicit base overrides the preset", readConfig({ env: "prod", base: "http://x:1", jwt: "t" }).config?.base === "http://x:1");
+    check("unknown env leaves base missing", readConfig({ env: "bogus", jwt: "t" }).missing.includes("WEBCAKE_API_BASE"));
+}
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "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": {