bricks-mcp-server 0.14.0 → 0.15.0-beta.2

package/README.md

@@ -1,89 +1,101 @@
-# bricks-mcp-server
-
-Provider-agnostic **MCP server** that exposes [Bricks Builder](https://bricksbuilder.io/) data — pages, templates, global classes and theme styles — as tools for any MCP-compatible AI client (Claude Code, Codex CLI, etc.).
-
-It talks to a companion WordPress plugin (**Bricks MCP Bridge**) over the REST API, authenticated with a WordPress Application Password. No AI API key ever lives in WordPress; all model calls happen in your client.
-
-## Quick start
-
-No clone or build needed — `npx` runs it on demand. The fastest path is the guided wizard:
-
-```bash
-npx -y bricks-mcp-server setup
-```
-
-It asks for your site URL, opens the Application Password authorization flow, tests the connection, and writes your client config.
-
-### Manual registration (Claude Code)
-
-```bash
-claude mcp add bricks -s user \
-  -e WP_URL=https://yoursite.tld \
-  -e WP_USER=your-wp-username \
-  -e WP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
-  -- npx -y bricks-mcp-server
-```
-
-Or in `~/.claude.json` under `mcpServers`:
-
-```json
-{
-  "mcpServers": {
-    "bricks": {
-      "command": "npx",
-      "args": ["-y", "bricks-mcp-server"],
-      "env": {
-        "WP_URL": "https://yoursite.tld",
-        "WP_USER": "your-wp-username",
-        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
-      }
-    }
-  }
-}
-```
-
-## Requirements
-
-- Node.js ≥ 18
-- A WordPress site running **Bricks Builder** with the **Bricks MCP Bridge** plugin installed and active.
-- A WordPress Application Password for a user with the `edit_pages` capability.
-
-## Commands
-
-| Command | Purpose |
-|---|---|
-| `npx -y bricks-mcp-server` | Run the MCP stdio server (what your client invokes). |
-| `npx -y bricks-mcp-server setup` | Interactive setup wizard. |
-| `npx -y bricks-mcp-server doctor` | Diagnose connection problems with specific fixes. |
-
-## Diagnostics
-
-If the connection fails, `doctor` pinpoints the exact cause — unreachable site, stripped `Authorization` header, bad credentials, missing capability, or plugin not installed:
-
-```bash
-WP_URL=https://yoursite.tld WP_USER=you WP_APP_PASSWORD="…" npx -y bricks-mcp-server doctor
-```
-
-## Tools
-
-`bricks_start_here`, `bricks_ping`, page/element/media tools, `bricks_get_design_context`, `bricks_manage_global_data`, `bricks_apply_global_class_operations`, `bricks_manage_template`, `bricks_get_preview_url`, and Query Filters reindexing.
-
-Highlights (server ≥0.5.0, plugin ≥0.7.0):
-
-- **Optimistic locking** — `bricks_get_page` returns `modified`; pass it as `expected_modified` on `bricks_update_page` to get a 409 instead of overwriting edits made in the builder since you read the page.
-- **`bricks_create_page`** — create pages/posts/CPT entries (draft by default), optionally with Bricks content.
-- **`bricks_ping`** echoes the effective `WP_URL`/user and warns when the configured host doesn't match the site that answered (stale config, redirect, proxy).
-
-## License
-
-GPL-2.0-or-later
+# bricks-mcp-server
+
+> Local beta 0.15.0-beta.2 requires Bridge 0.18.0-beta.2 (`guarded-v2`) for writes.
+> New in beta.2: `bricks_update_media`, `bricks_get_page` with `fields`/`subtree`/`compact`,
+> `op: duplicate`, `verbose` on `bricks_start_here`/`bricks_ping`, and `server_upgrade_required`
+> when the bridge announces a newer `min_server_version`.
+> This version has not been published. Run the compiled `dist/index.js` to test it.
+> `BRICKS_PROFILES_FILE` supports explicit per-call `site_id` profiles with
+> `{url,user,password_env}` entries. Credentials stay in environment variables.
+> Use `bricks_list_sites` to discover profiles; no shared active-site state exists.
+> Element property patches need `expected_exists`/`expected` and a stable
+> `operation_id`. Structural edits additionally require `expected_modified` and
+> `expected_hash`. Read back every change. Full replacements require explicit permission.
+
+Provider-agnostic **MCP server** that exposes [Bricks Builder](https://bricksbuilder.io/) data — pages, templates, global classes and theme styles — as tools for any MCP-compatible AI client (Claude Code, Codex CLI, etc.).
+
+It talks to a companion WordPress plugin (**Bricks MCP Bridge**) over the REST API, authenticated with a WordPress Application Password. No AI API key ever lives in WordPress; all model calls happen in your client.
+
+## Quick start
+
+No clone or build needed — `npx` runs it on demand. The fastest path is the guided wizard:
+
+```bash
+npx -y bricks-mcp-server setup
+```
+
+It asks for your site URL, opens the Application Password authorization flow, tests the connection, and writes your client config.
+
+### Manual registration (Claude Code)
+
+```bash
+claude mcp add bricks -s user \
+  -e WP_URL=https://yoursite.tld \
+  -e WP_USER=your-wp-username \
+  -e WP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
+  -- npx -y bricks-mcp-server
+```
+
+Or in `~/.claude.json` under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "bricks": {
+      "command": "npx",
+      "args": ["-y", "bricks-mcp-server"],
+      "env": {
+        "WP_URL": "https://yoursite.tld",
+        "WP_USER": "your-wp-username",
+        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js ≥ 18
+- A WordPress site running **Bricks Builder** with the **Bricks MCP Bridge** plugin installed and active.
+- A WordPress Application Password for a user with the `edit_pages` capability.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `npx -y bricks-mcp-server` | Run the MCP stdio server (what your client invokes). |
+| `npx -y bricks-mcp-server setup` | Interactive setup wizard. |
+| `npx -y bricks-mcp-server doctor` | Diagnose connection problems with specific fixes. |
+
+## Diagnostics
+
+If the connection fails, `doctor` pinpoints the exact cause — unreachable site, stripped `Authorization` header, bad credentials, missing capability, or plugin not installed:
+
+```bash
+WP_URL=https://yoursite.tld WP_USER=you WP_APP_PASSWORD="…" npx -y bricks-mcp-server doctor
+```
+
+## Tools
+
+`bricks_start_here`, `bricks_ping`, page/element/media tools, `bricks_get_design_context`, `bricks_manage_global_data`, `bricks_apply_global_class_operations`, `bricks_manage_template`, `bricks_get_preview_url`, and Query Filters reindexing.
+
+Highlights (server ≥0.5.0, plugin ≥0.7.0):
+
+- **Optimistic locking** — `bricks_get_page` returns `modified`; pass it as `expected_modified` on `bricks_update_page` to get a 409 instead of overwriting edits made in the builder since you read the page.
+- **`bricks_create_page`** — create pages/posts/CPT entries (draft by default), optionally with Bricks content.
+- **`bricks_ping`** echoes the effective `WP_URL`/user and warns when the configured host doesn't match the site that answered (stale config, redirect, proxy).
+
+## License
+
+GPL-2.0-or-later
 
 ### Media safety
 
-Use bricks_upload_media for URL/base64 uploads, bricks_find_media_usage before deletion, and bricks_delete_media only after references are cleared. Private URLs, SVG, unsafe MIME types, and files over 10 MB are rejected.
-### Lote 6 safety
-
-- Call `bricks_manage_global_data` with `action: "get"`, then reuse its `hash` in `action: "replace"`.
-- Prefer `bricks_apply_global_class_operations` over full-array replacement.
-- `bricks_manage_template` supports get/update/clone/delete; updates require `expected_modified`.
+Use bricks_upload_media for URL/base64 uploads, bricks_find_media_usage before deletion, and bricks_delete_media only after references are cleared. Private URLs, SVG, unsafe MIME types, and files over 10 MB are rejected.
+### Lote 6 safety
+
+- Call `bricks_manage_global_data` with `action: "get"`, then reuse its `hash` in `action: "replace"`.
+- Prefer `bricks_apply_global_class_operations` over full-array replacement.
+- `bricks_manage_template` supports get/update/clone/delete; updates require `expected_modified`.
 - Signed preview URLs expire after 60–900 seconds and must be treated as bearer secrets.

package/dist/contracts.js

@@ -1,8 +1,19 @@
 import { z } from "zod";
-export const updatePageSchema = z.object({ id: z.number().int().positive(), expected_modified: z.string().optional(), title: z.string().optional(), status: z.enum(["draft", "publish", "private", "pending"]).optional(), post_content: z.string().optional(), excerpt: z.string().optional(), date: z.string().optional(), featured_media: z.number().int().nonnegative().optional(), terms: z.record(z.any()).optional(), acf: z.record(z.any()).optional(), meta: z.record(z.any()).optional(), content: z.array(z.any()).optional(), header: z.array(z.any()).optional(), footer: z.array(z.any()).optional(), settings: z.record(z.any()).optional() });
+export const SERVER_VERSION = "0.15.0-beta.2";
+export const updatePageSchema = z.object({ id: z.number().int().positive(), expected_modified: z.string().min(1), expected_version: z.string().length(64), replace_document: z.boolean().optional(), title: z.string().optional(), status: z.enum(["draft", "publish", "private", "pending"]).optional(), post_content: z.string().optional(), excerpt: z.string().optional(), date: z.string().optional(), featured_media: z.number().int().nonnegative().optional(), terms: z.record(z.any()).optional(), acf: z.record(z.any()).optional(), meta: z.record(z.any()).optional(), content: z.array(z.any()).optional(), header: z.array(z.any()).optional(), footer: z.array(z.any()).optional(), settings: z.record(z.any()).optional() });
 export const uploadMediaSchema = z.object({ url: z.string().url().optional(), base64: z.string().min(1).optional(), filename: z.string().min(1).optional(), title: z.string().optional(), alt: z.string().optional() }).refine(v => Boolean(v.url) !== Boolean(v.base64), "Provide exactly one source: url or base64.");
-export const elementOperationSchema = z.discriminatedUnion("op", [z.object({ op: z.literal("insert"), element: z.record(z.any()), parent: z.union([z.string(), z.number()]).optional(), position: z.number().int().nonnegative().optional() }), z.object({ op: z.literal("update"), id: z.string().min(1), changes: z.record(z.any()) }), z.object({ op: z.literal("move"), id: z.string().min(1), parent: z.union([z.string(), z.number()]), position: z.number().int().nonnegative().optional() }), z.object({ op: z.literal("delete"), id: z.string().min(1) })]);
-export const applyElementOperationsSchema = z.object({ id: z.number().int().positive(), expected_modified: z.string().min(1), field: z.enum(["content", "header", "footer"]).optional(), operations: z.array(elementOperationSchema).min(1) });
+export const getPageSchema = z.object({ id: z.number().int().positive(), fields: z.array(z.enum(["content", "header", "footer", "settings"])).min(1).optional(), subtree: z.string().min(1).optional(), compact: z.boolean().optional() });
+export const updateMediaSchema = z.object({ id: z.number().int().positive(), alt: z.string().max(1000).optional(), title: z.string().max(1000).optional(), caption: z.string().max(5000).optional(), description: z.string().max(20000).optional() }).refine(v => [v.alt, v.title, v.caption, v.description].some(x => x !== undefined), "Provide at least one of: alt, title, caption, description.");
+export const verboseSchema = z.object({ verbose: z.boolean().optional() });
+export const elementPositionSchema = z.union([z.number().int().nonnegative(), z.enum(["first", "start", "top", "prepend", "last", "end", "bottom", "append", "before", "after"])]);
+export const propertyPatchSchema = z.object({ path: z.string().regex(/^\/(settings\/[^/].*|label)$/), expected_exists: z.boolean(), expected: z.unknown().optional(), value: z.unknown().optional(), remove: z.boolean().optional() }).strict().superRefine((v, ctx) => { if (v.expected_exists && !Object.hasOwn(v, "expected"))
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "expected is required" }); if (!v.remove && !Object.hasOwn(v, "value"))
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "value or remove:true is required" }); });
+export const elementOperationSchema = z.discriminatedUnion("op", [z.object({ op: z.literal("patch"), id: z.string().min(1), patches: z.array(propertyPatchSchema).min(1).max(100) }), z.object({ op: z.literal("insert"), element: z.record(z.any()), parent: z.union([z.string(), z.number()]).optional(), position: elementPositionSchema.optional(), target: z.string().min(1).optional() }), z.object({ op: z.literal("update"), id: z.string().min(1), changes: z.record(z.any()), mode: z.enum(["merge", "deep", "replace"]).optional() }), z.object({ op: z.literal("move"), id: z.string().min(1), parent: z.union([z.string(), z.number()]).optional(), position: elementPositionSchema.optional(), target: z.string().min(1).optional() }), z.object({ op: z.literal("delete"), id: z.string().min(1) }), z.object({ op: z.literal("duplicate"), id: z.string().min(1), parent: z.union([z.string(), z.number()]).optional(), position: elementPositionSchema.optional(), target: z.string().min(1).optional() })]).superRefine((v, ctx) => { if ((v.op === "insert" || v.op === "move" || v.op === "duplicate") && (v.position === "before" || v.position === "after") && !v.target)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: `position "${v.position}" requires a sibling id in "target"` }); });
+export const applyElementOperationsSchema = z.object({ id: z.number().int().positive(), expected_modified: z.string().min(1).optional(), expected_hash: z.string().length(64).optional(), operation_id: z.string().regex(/^[a-zA-Z0-9_-]{16,80}$/).optional(), dry_run: z.boolean().optional(), field: z.enum(["content", "header", "footer"]).optional(), operations: z.array(elementOperationSchema).min(1).max(100) }).superRefine((v, ctx) => { if (!v.dry_run && !v.operation_id)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "operation_id is required" }); if (v.operations.some(o => o.op !== "patch") && (!v.expected_modified || !v.expected_hash))
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "expected_modified and expected_hash are required for structural/merge operations" }); });
 export const designContextSchema = z.object({ include: z.array(z.enum(["classes", "variables", "palettes", "theme_styles", "breakpoints", "components", "global_settings"])).optional(), compact: z.boolean().optional() });
 export const globalScopeSchema = z.enum(["global-variables", "color-palettes", "theme-styles", "components", "breakpoints"]);
 export const globalDataUpdateSchema = z.object({ scope: globalScopeSchema, action: z.enum(["get", "replace"]), expected_hash: z.string().length(64).optional(), value: z.array(z.any()).or(z.record(z.any())).optional() }).superRefine((v, ctx) => { if (v.action === "replace" && (!v.expected_hash || v.value === undefined))
@@ -68,6 +79,20 @@ export function buildToolRequest(name, args) {
         const query = { scope, ...(post_id ? { post_id: String(post_id) } : {}) };
         return action === "get" ? { path: "/custom-css", method: "GET", query } : { path: "/custom-css", method: "PUT", query, body };
     }
+    if (name === "bricks_get_page") {
+        const parsed = getPageSchema.parse(args);
+        const query = { ...(parsed.fields ? { fields: parsed.fields.join(",") } : {}), ...(parsed.subtree ? { subtree: parsed.subtree } : {}), ...(parsed.compact ? { compact: "true" } : {}) };
+        return { path: `/pages/${parsed.id}`, method: "GET", query: Object.keys(query).length ? query : undefined };
+    }
+    if (name === "bricks_update_media") {
+        const parsed = updateMediaSchema.parse(args);
+        const { id, ...body } = parsed;
+        return { path: `/media/${id}`, method: "PATCH", body };
+    }
+    if (name === "bricks_start_here" || name === "bricks_ping") {
+        const parsed = verboseSchema.parse(args);
+        return { path: name === "bricks_start_here" ? "/start-here" : "/ping", method: "GET", query: parsed.verbose ? { verbose: "true" } : undefined };
+    }
     if (name === "bricks_upload_media")
         return { path: "/media", method: "POST", body: uploadMediaSchema.parse(args) };
     if (name === "bricks_find_media_usage")
@@ -76,4 +101,13 @@ export function buildToolRequest(name, args) {
         return { path: `/media/${z.number().int().positive().parse(args.id)}`, method: "DELETE", query: args.force ? { force: "true" } : undefined };
     throw new Error(`Unsupported tool request: ${name}`);
 }
-export function negotiateCapabilities(startHere) { const c = startHere.capabilities ?? {}; return { canWrite: !c.dry_run && !c.allowlist?.read_only, canUploadMedia: c.media_upload !== false, canForceDelete: c.force_delete_allowed === true, acf: c.acf_active === true, queryFilters: c.query_filters === true }; }
+/** Compares dotted versions with an optional prerelease: 0.15.0-beta.2 < 0.15.0 < 0.15.1. */
+export function compareVersions(a, b) { const split = (v) => { const [core, pre] = v.split("-", 2); return { core: core.split(".").map(n => parseInt(n, 10) || 0), pre }; }; const x = split(a), y = split(b); for (let i = 0; i < Math.max(x.core.length, y.core.length); i++) {
+    const d = (x.core[i] ?? 0) - (y.core[i] ?? 0);
+    if (d)
+        return Math.sign(d);
+} if (x.pre === y.pre)
+    return 0; if (x.pre === undefined)
+    return 1; if (y.pre === undefined)
+    return -1; return x.pre.localeCompare(y.pre, undefined, { numeric: true }) < 0 ? -1 : x.pre.localeCompare(y.pre, undefined, { numeric: true }) > 0 ? 1 : 0; }
+export function negotiateCapabilities(startHere) { const c = startHere.capabilities ?? {}; return { canWrite: !c.dry_run && !c.allowlist?.read_only, canUpdateMedia: Array.isArray(c.allowlist?.enabled) ? c.allowlist.enabled.includes("media_update") : c.allowlist?.items?.media_update?.enabled === true, canUploadMedia: c.media_upload !== false, canForceDelete: c.force_delete_allowed === true, acf: c.acf_active === true, queryFilters: c.query_filters === true }; }

package/dist/index.js

@@ -3,7 +3,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { wpRequest, loadConfig, diagnose, formatDiagnosis } from "./wp-client.js";
+import { wpRequest, loadConfig, diagnose, formatDiagnosis, WPError } from "./wp-client.js";
+import { SERVER_VERSION, getPageSchema, updateMediaSchema, verboseSchema, elementOperationSchema, applyElementOperationsSchema, updatePageSchema, uploadMediaSchema, manageTemplateSchema, revisionsSchema, customCssSchema, globalDataUpdateSchema, globalClassOperationsSchema, dynamicDataSchema, previewUrlSchema, designContextSchema } from "./contracts.js";
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { listSites, selectProfile, requestContext } from './profiles.js';
 /** Extract the hostname from a URL, or null if it can't be parsed. */
 function hostOf(url) {
     try {
@@ -33,26 +36,26 @@ if (subcommand === "doctor" || subcommand === "diagnose") {
 if (process.env.WP_URL) {
     console.error(`[bricks-mcp] target WP_URL=${process.env.WP_URL} WP_USER=${process.env.WP_USER ?? "?"}`);
 }
-const server = new Server({ name: "bricks-mcp-server", version: "0.14.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "bricks-mcp-server", version: SERVER_VERSION }, { capabilities: { tools: {} } });
 const tools = [
     {
         name: "bricks_start_here",
         description: "CALL THIS FIRST, once per session, before any other bricks_* tool. Returns everything needed to work on this site safely: site identity, capabilities (dry-run state, ACF, query filters), the content model (post types + taxonomies + ACF fields), a design-system summary, existing templates, and the working rules that prevent the classic Bricks failure modes (write conflicts, wrong template fields, un-indexed filters, clobbered global classes).",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
-        schema: z.object({}),
-        handler: async () => wpRequest("/start-here"),
+        schema: verboseSchema,
+        handler: async (args) => wpRequest("/start-here", { query: args.verbose ? { verbose: "true" } : undefined }),
     },
     {
         name: "bricks_ping",
-        description: "Verify the WordPress connection and report which site you're connected to (wp_url + site that answered), Bricks + WP version.",
+        description: "Verify the WordPress connection and report which site you're connected to (wp_url + site that answered), Bricks + WP + plugin version. verbose:true includes the full capability registry.",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
-        schema: z.object({}),
-        handler: async () => {
+        schema: verboseSchema,
+        handler: async (args) => {
             // Echo the config this *process* was launched with, up front. If Claude
             // Code is still holding a stale config (old process not restarted after a
             // site switch), wp_url makes it obvious without guessing from permalinks.
             const { baseUrl, user } = loadConfig();
-            const res = (await wpRequest("/ping"));
+            const res = (await wpRequest("/ping", { query: args.verbose ? { verbose: "true" } : undefined }));
             const configHost = hostOf(baseUrl);
             const siteHost = typeof res.site_url === "string" ? hostOf(res.site_url) : null;
             const mismatch = configHost !== null && siteHost !== null && configHost !== siteHost;
@@ -110,15 +113,15 @@ const tools = [
     },
     {
         name: "bricks_get_page",
-        description: "Get a page/post/template by ID, including its Bricks content/header/footer/settings JSON. The response includes `modified` — pass it as expected_modified on bricks_update_page to avoid clobbering edits made in the builder since you read it.",
+        description: "Get a page/post/template by ID, including its Bricks content/header/footer/settings JSON. On large pages narrow the read: fields (e.g. [\"content\"]), subtree (an element id: only it and its descendants) and compact:true (structure without settings). Hashes always describe the full tree. The response includes `modified` — pass it as expected_modified on bricks_update_page to avoid clobbering edits made in the builder since you read it.",
         inputSchema: {
             type: "object",
             properties: { id: { type: "number" } },
             required: ["id"],
             additionalProperties: false,
         },
-        schema: z.object({ id: z.number().int().positive() }),
-        handler: async (args) => wpRequest(`/pages/${args.id}`),
+        schema: getPageSchema,
+        handler: async (args) => wpRequest(`/pages/${args.id}`, { query: { fields: args.fields?.join(","), subtree: args.subtree, compact: args.compact ? "true" : undefined } }),
     },
     {
         name: "bricks_update_page",
@@ -302,6 +305,13 @@ const tools = [
         schema: z.object({ url: z.string().url().optional(), base64: z.string().min(1).optional(), filename: z.string().min(1).optional(), title: z.string().optional(), alt: z.string().optional() }).refine(v => Boolean(v.url) !== Boolean(v.base64), "Provide exactly one source."),
         handler: async (args) => wpRequest("/media", { method: "POST", body: args }),
     },
+    {
+        name: "bricks_update_media",
+        description: "Edit alt text, title, caption or description of an existing attachment. Pass expected_version from bricks_list_media; a 409 write_conflict means list again and retry.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        schema: updateMediaSchema,
+        handler: async (args) => { const { id, ...body } = args; return wpRequest(`/media/${id}`, { method: "PATCH", body }); },
+    },
     {
         name: "bricks_find_media_usage",
         description: "Find posts and Bricks data that reference an attachment. Call before deletion.",
@@ -324,9 +334,9 @@ const tools = [
     },
     {
         name: "bricks_apply_element_operations",
-        description: "Atomically apply insert/update/move/delete operations to one Bricks element tree. Requires expected_modified. The whole batch validates before one snapshot and one write; dry-run returns the diff without persistence.",
-        inputSchema: { type: "object", properties: { id: { type: "number" }, expected_modified: { type: "string" }, field: { type: "string" }, operations: { type: "array", items: { type: "object" } } }, required: ["id", "expected_modified", "operations"], additionalProperties: false },
-        schema: z.object({ id: z.number().int().positive(), expected_modified: z.string().min(1), field: z.enum(["content", "header", "footer"]).optional(), operations: z.array(z.object({ op: z.enum(["insert", "update", "move", "delete"]) }).passthrough()).min(1) }),
+        description: "Atomically apply insert/update/move/delete operations to one Bricks element tree. Requires expected_modified. The whole batch validates before one snapshot and one write; dry-run returns the diff without persistence.\n\nOrdering: `position` accepts an index, or first/last, or before/after combined with `target` (a sibling id). Omitting it appends last. Root sections (parent 0) are ordered too — they render in tree order, so use position/target there as well.\n\ninsert: {op, element, parent?, position?, target?} — parent defaults to element.parent (0 = root).\nupdate: {op, id, changes, mode?} — changes may carry settings/label and `children` ONLY to reorder the existing ids; changing parent/id needs move or delete. mode \"merge\" (default) replaces each top-level key inside a group, so passing settings.link swaps the whole link object and drops stale flags; \"deep\" merges recursively; \"replace\" swaps whole groups. null removes a key at any depth.\nmove: {op, id, parent?, position?, target?} — parent defaults to the element's CURRENT parent; pass 0 explicitly to promote to root.\ndelete: {op, id} — removes the element and all its descendants.",
+        inputSchema: { type: "object", properties: { id: { type: "number" }, expected_modified: { type: "string" }, field: { type: "string", description: "content (default), header, or footer" }, operations: { type: "array", items: { type: "object", properties: { op: { type: "string", enum: ["insert", "update", "move", "delete"] }, id: { type: "string", description: "target element id (update/move/delete)" }, element: { type: "object", description: "element object to insert" }, parent: { description: "parent id, or 0 for root" }, position: { description: "index, or first/last, or before/after (needs target)" }, target: { type: "string", description: "sibling id for before/after" }, changes: { type: "object", description: "fields to apply (update)" }, mode: { type: "string", enum: ["merge", "deep", "replace"], description: "how changes are applied; default merge" } }, required: ["op"] } } }, required: ["id", "expected_modified", "operations"], additionalProperties: false },
+        schema: z.object({ id: z.number().int().positive(), expected_modified: z.string().min(1), field: z.enum(["content", "header", "footer"]).optional(), operations: z.array(elementOperationSchema).min(1) }),
         handler: async (args) => { const { id, ...body } = args; return wpRequest(`/pages/${id}/element-operations`, { method: "POST", body }); },
     }, {
         name: "bricks_get_design_context",
@@ -456,6 +466,8 @@ const tools = [
         schema: z.object({
             classes: z.array(z.any()).optional(),
             categories: z.array(z.any()).optional(),
+            expected_hash: z.string().length(64),
+            expected_categories_hash: z.string().length(64).optional(),
         }),
         handler: async (args) => wpRequest("/global-classes", { method: "PUT", body: args }),
     },
@@ -494,6 +506,7 @@ const TOOL_ANNOTATIONS = {
     bricks_list_media: { readOnlyHint: true },
     bricks_find_media_usage: { readOnlyHint: true },
     bricks_upload_media: { readOnlyHint: false, destructiveHint: false },
+    bricks_update_media: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
     bricks_delete_media: { readOnlyHint: false, destructiveHint: true },
     bricks_create_page: { readOnlyHint: false, destructiveHint: false },
     bricks_create_template: { readOnlyHint: false, destructiveHint: false },
@@ -502,31 +515,52 @@ const TOOL_ANNOTATIONS = {
     bricks_update_global_classes: { readOnlyHint: false, destructiveHint: true },
     bricks_delete_page: { readOnlyHint: false, destructiveHint: true },
 };
+const changeSchema = z.object({ id: z.number().int().positive(), action: z.enum(['list', 'get', 'propose', 'apply', 'undo']), change_id: z.number().int().positive().optional(), field: z.enum(['content', 'header', 'footer']).optional(), expected_modified: z.string().optional(), expected_hash: z.string().length(64).optional(), operations: z.array(elementOperationSchema).min(1).max(100).optional(), page: z.number().int().positive().optional() }).superRefine((v, c) => { if (v.action === 'propose' && !v.operations)
+    c.addIssue({ code: z.ZodIssueCode.custom, message: 'operations required' }); if (['get', 'apply', 'undo'].includes(v.action) && !v.change_id)
+    c.addIssue({ code: z.ZodIssueCode.custom, message: 'change_id required' }); });
+const schemaOverrides = {
+    bricks_update_page: updatePageSchema, bricks_apply_element_operations: applyElementOperationsSchema,
+    bricks_upload_media: uploadMediaSchema, bricks_manage_template: manageTemplateSchema,
+    bricks_manage_revisions: revisionsSchema, bricks_manage_custom_css: customCssSchema,
+    bricks_manage_global_data: globalDataUpdateSchema, bricks_apply_global_class_operations: globalClassOperationsSchema,
+    bricks_resolve_dynamic_data: dynamicDataSchema, bricks_get_preview_url: previewUrlSchema, bricks_get_design_context: designContextSchema,
+    bricks_get_page: getPageSchema, bricks_update_media: updateMediaSchema, bricks_start_here: verboseSchema, bricks_ping: verboseSchema,
+};
+const catalog = tools.map(t => ({ ...t, schema: schemaOverrides[t.name] ?? t.schema }));
+const extraTools = [
+    { name: 'bricks_list_sites', description: 'List configured site profiles without credentials. With profiles enabled, pass an explicit site_id to every other tool.', schema: z.object({}), handler: async () => ({ sites: listSites() }), annotations: { readOnlyHint: true } },
+    { name: 'bricks_manage_changes', description: 'List/get element history, propose changes for human review in WordPress, apply approved proposals, or undo property changes conditionally. Cannot approve proposals. Structural undo requires revision recovery. Propose does not change page content.', schema: changeSchema, handler: async (args) => { const { id, ...body } = args; return wpRequest(`/pages/${id}/changes`, args.action === 'list' ? { query: args.page ? { page: String(args.page) } : undefined } : { method: 'POST', body }); }, annotations: { readOnlyHint: false, destructiveHint: true } },
+];
+function publicSchema(schema) {
+    const json = zodToJsonSchema(schema, { $refStrategy: 'none' });
+    delete json.$schema;
+    json.properties = { ...json.properties, site_id: { type: 'string', description: 'Required with BRICKS_PROFILES_FILE; explicit target, never a global active site.' }, expected_version: { type: 'string', description: 'Version returned by get_page, required for non-granular existing-post writes.' }, replace_document: { type: 'boolean', description: 'Explicit whole-document replacement, requires separate WordPress permission.' } };
+    return json;
+}
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: tools.map(({ name, description, inputSchema }) => ({
-        name,
-        description,
-        inputSchema,
-        annotations: TOOL_ANNOTATIONS[name],
-    })),
+    tools: [...catalog.map(t => ({ name: t.name, description: t.name === 'bricks_apply_element_operations' ? 'Edit by ID; prefer op:patch with JSON Pointer, expected_exists and expected old value. It preserves unrelated changes. Stable operation_id required for writes. op:duplicate {id, parent?, position?, target?} copies an element with its descendants under new ids, right after the original by default. Other operations require expected_modified plus expected_hash from the same read. Use dry_run for preview.' : t.description, inputSchema: publicSchema(t.schema), annotations: TOOL_ANNOTATIONS[t.name] })), ...extraTools.map(t => ({ name: t.name, description: t.description, inputSchema: publicSchema(t.schema), annotations: t.annotations }))],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const tool = tools.find((t) => t.name === request.params.name);
+    const tool = [...catalog, ...extraTools].find((t) => t.name === request.params.name);
     if (!tool) {
         throw new Error(`Unknown tool: ${request.params.name}`);
     }
-    const parsed = tool.schema.parse(request.params.arguments ?? {});
     try {
-        const result = await tool.handler(parsed);
+        const raw = request.params.arguments ?? {};
+        const parsed = tool.schema.parse(raw);
+        const run = async () => tool.handler(parsed);
+        const client = server.getClientVersion();
+        const result = tool.name === 'bricks_list_sites' ? await run() : await requestContext.run({ ...selectProfile(typeof raw.site_id === 'string' ? raw.site_id : undefined), expectedVersion: typeof raw.expected_version === 'string' ? raw.expected_version : undefined, replaceDocument: raw.replace_document === true, client: `${client?.name ?? 'unknown'} ${client?.version ?? ''} / bricks-mcp-server` }, run);
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
         };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return {
             isError: true,
-            content: [{ type: "text", text: message }],
+            content: [{ type: "text", text: JSON.stringify(err instanceof WPError ? { code: err.code, message, http_status: err.httpStatus, ...err.details } : { code: err instanceof z.ZodError ? 'validation_failed' : 'client_error', message, retryable: false }) }],
         };
     }
 });

package/dist/profiles.js

@@ -0,0 +1,40 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+export const requestContext = new AsyncLocalStorage();
+function validate(profile) {
+    const url = new URL(profile.url);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+        throw new Error('Invalid site profile URL.');
+    if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
+        throw new Error('Remote sites require HTTPS.');
+    if (!profile.user || !profile.password)
+        throw new Error('Site profile credentials are missing.');
+    return { ...profile, url: profile.url.replace(/\/$/, '') };
+}
+/** Read once per call, never mutate process.env or a global active site. */
+export function readProfiles() {
+    const file = process.env.BRICKS_PROFILES_FILE;
+    if (!file)
+        return { default: validate({ url: process.env.WP_URL ?? '', user: process.env.WP_USER ?? '', password: process.env.WP_APP_PASSWORD ?? '' }) };
+    if (!isAbsolute(file))
+        throw new Error('BRICKS_PROFILES_FILE must be an absolute path outside the repository.');
+    const raw = JSON.parse(readFileSync(file, 'utf8'));
+    const profiles = Object.create(null);
+    for (const [id, profile] of Object.entries(raw)) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(id) || !profile.password_env)
+            throw new Error('Invalid profile: use a stable id and password_env.');
+        profiles[id] = validate({ url: profile.url, user: profile.user, password: process.env[profile.password_env] ?? '' });
+    }
+    return profiles;
+}
+export function selectProfile(siteId) {
+    const profiles = readProfiles();
+    const id = siteId ?? (process.env.BRICKS_PROFILES_FILE ? '' : 'default');
+    if (!id || !Object.hasOwn(profiles, id))
+        throw new Error('Choose an explicit site_id from bricks_list_sites.');
+    return { site: profiles[id], siteId: id };
+}
+export function listSites() {
+    return Object.entries(readProfiles()).map(([site_id, p]) => ({ site_id, url: p.url, user: p.user }));
+}

package/dist/wp-client.js

@@ -1,6 +1,24 @@
+import { requestContext } from './profiles.js';
+import { SERVER_VERSION, compareVersions } from './contracts.js';
 const REQUIRED_ENV = ["WP_URL", "WP_USER", "WP_APP_PASSWORD"];
+export class WPError extends Error {
+    code;
+    httpStatus;
+    details;
+    constructor(code, message, httpStatus, details = {}) {
+        super(message);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.details = details;
+    }
+}
 /** Read config from env. Throws a friendly error listing what's missing. */
 export function loadConfig() {
+    const selected = requestContext.getStore()?.site;
+    if (selected) {
+        const appPassword = selected.password.replace(/\s+/g, '');
+        return { baseUrl: selected.url, user: selected.user, appPassword, auth: Buffer.from(`${selected.user}:${appPassword}`).toString('base64') };
+    }
     const missing = REQUIRED_ENV.filter((k) => !process.env[k]);
     if (missing.length) {
         throw new Error(`Missing required env vars: ${missing.join(", ")}. Set them in your MCP server config.`);
@@ -11,8 +29,39 @@ export function loadConfig() {
     const auth = Buffer.from(`${user}:${appPassword}`).toString("base64");
     return { baseUrl, user, appPassword, auth };
 }
+/** Bridge identity per site, reused for a minute so each write does not pay a bootstrap round trip. */
+const protocolChecks = new Map();
+const PROTOCOL_CHECK_TTL_MS = 60_000;
+/** Forgets verified sites, e.g. after reconnecting or in tests. */
+export function clearWriteProtocolCache() {
+    protocolChecks.clear();
+}
+async function checkWriteProtocol(baseUrl) {
+    const checkedAt = protocolChecks.get(baseUrl);
+    if (checkedAt && Date.now() - checkedAt < PROTOCOL_CHECK_TTL_MS)
+        return;
+    const bootstrap = await wpRequest('/start-here');
+    if (bootstrap.site?.write_protocol !== 'guarded-v2' || bootstrap.site.site_url?.replace(/\/$/, '') !== baseUrl) {
+        throw new WPError('bridge_upgrade_required', 'This server requires a guarded-v2 bridge on the selected site before sending writes.', 409, { retryable: false, next_action: 'Update the Bricks MCP Bridge plugin on the site, then run bricks_start_here.' });
+    }
+    const minimum = bootstrap.site.min_server_version;
+    if (minimum && compareVersions(SERVER_VERSION, minimum) < 0) {
+        throw new WPError('server_upgrade_required', `The bridge on this site (${bootstrap.site.plugin_version ?? 'unknown'}) requires bricks-mcp-server ${minimum} or newer; this is ${SERVER_VERSION}.`, 426, { retryable: false, next_action: `Update bricks-mcp-server to ${minimum} or newer and restart the MCP client.` });
+    }
+    protocolChecks.set(baseUrl, Date.now());
+}
 export async function wpRequest(path, opts = {}) {
     const { baseUrl, auth } = loadConfig();
+    const context = requestContext.getStore();
+    // Fail closed when an older bridge cannot enforce the new write contract.
+    if (opts.method && opts.method !== 'GET') {
+        await checkWriteProtocol(baseUrl);
+    }
+    const body = opts.method && opts.method !== 'GET' ? {
+        ...(opts.body && typeof opts.body === 'object' ? opts.body : {}),
+        ...(context?.expectedVersion ? { expected_version: context.expectedVersion } : {}),
+        ...(context?.replaceDocument ? { replace_document: true } : {}),
+    } : opts.body;
     const url = new URL(`${baseUrl}/wp-json/bricks-mcp/v1${path}`);
     if (opts.query) {
         for (const [k, v] of Object.entries(opts.query)) {
@@ -24,12 +73,16 @@ export async function wpRequest(path, opts = {}) {
     try {
         res = await fetch(url, {
             method: opts.method ?? "GET",
+            redirect: 'error',
+            signal: AbortSignal.timeout(30000),
             headers: {
                 Authorization: `Basic ${auth}`,
                 "Content-Type": "application/json",
                 Accept: "application/json",
+                'X-Bricks-Site': baseUrl,
+                'X-Bricks-Client': context?.client ?? 'bricks-mcp-server',
             },
-            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
         });
     }
     catch (err) {
@@ -44,7 +97,7 @@ export async function wpRequest(path, opts = {}) {
         json = text ? JSON.parse(text) : null;
     }
     catch {
-        throw new Error(`WP returned non-JSON (status ${res.status}): ${text.slice(0, 300)}`);
+        throw new Error(`WP returned non-JSON (status ${res.status}). Check the site's REST endpoint and server logs.`);
     }
     if (!res.ok) {
         const code = json && typeof json === "object" && "code" in json
@@ -53,21 +106,13 @@ export async function wpRequest(path, opts = {}) {
         const message = (json && typeof json === "object" && "message" in json
             ? json.message
             : null) ?? `HTTP ${res.status}`;
-        // On auth/route failures, run the diagnostic ladder so the user gets an
-        // actionable cause instead of the opaque WordPress error.
-        if (res.status === 401 || res.status === 403 || res.status === 404) {
-            const diag = await diagnose().catch(() => null);
-            if (diag && diag.problem) {
-                throw new Error(formatDiagnosis(diag));
-            }
-        }
-        throw new Error(`WP error: ${message}${code ? ` (${code})` : ""}`);
+        throw new WPError(code ?? 'http_error', message, res.status, json?.data ?? {});
     }
     return json;
 }
 async function tryFetch(url, headers = {}) {
     try {
-        const res = await fetch(url, { headers: { Accept: "application/json", ...headers } });
+        const res = await fetch(url, { headers: { Accept: "application/json", ...headers }, redirect: 'error', signal: AbortSignal.timeout(15000) });
         let body;
         try {
             body = (await res.json());
@@ -87,7 +132,7 @@ async function tryFetch(url, headers = {}) {
  * credentials valid? → user has capability? → plugin installed?
  */
 export async function diagnose() {
-    const missing = REQUIRED_ENV.filter((k) => !process.env[k]);
+    const missing = requestContext.getStore() ? [] : REQUIRED_ENV.filter((k) => !process.env[k]);
     if (missing.length) {
         return {
             step: "missing_env",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bricks-mcp-server",
-  "version": "0.14.0",
+  "version": "0.15.0-beta.2",
   "description": "Provider-agnostic MCP server that exposes Bricks Builder pages, templates, global classes and theme styles as tools. Works with any MCP-compatible client (Claude Code, Codex CLI, etc.).",
   "type": "module",
   "bin": {
@@ -37,8 +37,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "bricks-ai-workspace": "file:..",
-    "zod": "^3.23.8"
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.5"
   },
   "devDependencies": {
     "@types/node": "^20.12.0",