bricks-mcp-server 0.8.0 → 0.13.0

package/README.md

@@ -66,7 +66,7 @@ WP_URL=https://yoursite.tld WP_USER=you WP_APP_PASSWORD="…" npx -y bricks-mcp-
 
 ## Tools
 
-`bricks_ping`, `bricks_list_pages`, `bricks_get_page`, `bricks_update_page`, `bricks_create_page`, `bricks_list_templates`, `bricks_create_template`, `bricks_get_global_classes`, `bricks_update_global_classes`, `bricks_get_theme_styles`, `bricks_list_media`, `bricks_reindex_query_filters`.
+`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):
 
@@ -77,3 +77,13 @@ Highlights (server ≥0.5.0, plugin ≥0.7.0):
 ## 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`.
+- Signed preview URLs expire after 60–900 seconds and must be treated as bearer secrets.

package/dist/contracts.js

@@ -0,0 +1,59 @@
+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 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 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))
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "expected_hash and value are required for replace" }); });
+export const globalClassOperationSchema = z.discriminatedUnion("op", [z.object({ op: z.literal("add"), class: z.record(z.any()) }), z.object({ op: z.literal("update"), id: z.string().min(1), changes: z.record(z.any()) }), z.object({ op: z.literal("delete"), id: z.string().min(1) })]);
+export const globalClassOperationsSchema = z.object({ expected_hash: z.string().length(64), operations: z.array(globalClassOperationSchema).min(1) });
+export const manageTemplateSchema = z.object({ id: z.number().int().positive(), action: z.enum(["get", "update", "clone", "delete"]), expected_modified: z.string().optional(), title: z.string().optional(), status: z.enum(["draft", "publish", "private"]).optional(), type: z.string().optional(), content: z.array(z.any()).optional(), settings: z.record(z.any()).optional(), conditions: z.array(z.any()).optional(), force: z.boolean().optional() }).superRefine((v, ctx) => { if (v.action === "update" && !v.expected_modified)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "expected_modified is required for update" }); });
+export const previewUrlSchema = z.object({ id: z.number().int().positive(), ttl: z.number().int().min(60).max(900).optional() });
+export function buildToolRequest(name, args) {
+    if (name === "bricks_update_page") {
+        const parsed = updatePageSchema.parse(args);
+        const { id, ...body } = parsed;
+        return { path: `/pages/${id}`, method: "PUT", body };
+    }
+    if (name === "bricks_apply_element_operations") {
+        const parsed = applyElementOperationsSchema.parse(args);
+        const { id, ...body } = parsed;
+        return { path: `/pages/${id}/element-operations`, method: "POST", body };
+    }
+    if (name === "bricks_get_element") {
+        const id = z.number().int().positive().parse(args.id);
+        const elementId = z.string().min(1).parse(args.element_id);
+        return { path: `/pages/${id}/elements/${elementId}`, method: "GET", query: args.field ? { field: String(args.field) } : undefined };
+    }
+    if (name === "bricks_get_design_context") {
+        const parsed = designContextSchema.parse(args);
+        return { path: "/design-context", method: "GET", query: { ...(parsed.include ? { include: parsed.include.join(",") } : {}), ...(parsed.compact ? { compact: "true" } : {}) } };
+    }
+    if (name === "bricks_manage_global_data") {
+        const parsed = globalDataUpdateSchema.parse(args);
+        const { scope, action, ...body } = parsed;
+        return action === "get" ? { path: `/global-data/${scope}`, method: "GET" } : { path: `/global-data/${scope}`, method: "PUT", body };
+    }
+    if (name === "bricks_apply_global_class_operations")
+        return { path: "/global-classes/operations", method: "POST", body: globalClassOperationsSchema.parse(args) };
+    if (name === "bricks_manage_template") {
+        const parsed = manageTemplateSchema.parse(args);
+        const { id, ...body } = parsed;
+        return { path: `/templates/${id}/manage`, method: "POST", body };
+    }
+    if (name === "bricks_get_preview_url") {
+        const parsed = previewUrlSchema.parse(args);
+        return { path: `/preview/${parsed.id}`, method: "GET", query: parsed.ttl ? { ttl: String(parsed.ttl) } : undefined };
+    }
+    if (name === "bricks_upload_media")
+        return { path: "/media", method: "POST", body: uploadMediaSchema.parse(args) };
+    if (name === "bricks_find_media_usage")
+        return { path: `/media/${z.number().int().positive().parse(args.id)}/usage`, method: "GET" };
+    if (name === "bricks_delete_media")
+        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 }; }

package/dist/index.js

@@ -33,8 +33,15 @@ 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.8.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "bricks-mcp-server", version: "0.13.0" }, { 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"),
+    },
     {
         name: "bricks_ping",
         description: "Verify the WordPress connection and report which site you're connected to (wp_url + site that answered), Bricks + WP version.",
@@ -289,6 +296,45 @@ const tools = [
         handler: async (args) => wpRequest("/media", { query: args }),
     },
     {
+        name: "bricks_upload_media",
+        description: "Upload media from one public URL or base64. Blocks SSRF, unsafe MIME, files over 10 MB, and SVG.",
+        inputSchema: { type: "object", properties: { url: { type: "string" }, base64: { type: "string" }, filename: { type: "string" }, title: { type: "string" }, alt: { type: "string" } }, additionalProperties: false },
+        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_find_media_usage",
+        description: "Find posts and Bricks data that reference an attachment. Call before deletion.",
+        inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"], additionalProperties: false },
+        schema: z.object({ id: z.number().int().positive() }),
+        handler: async (args) => wpRequest(`/media/${args.id}/usage`),
+    },
+    {
+        name: "bricks_delete_media",
+        description: "Delete an unused attachment. Trash by default; force:true is permanent and default-off.",
+        inputSchema: { type: "object", properties: { id: { type: "number" }, force: { type: "boolean" } }, required: ["id"], additionalProperties: false },
+        schema: z.object({ id: z.number().int().positive(), force: z.boolean().optional() }),
+        handler: async (args) => wpRequest(`/media/${args.id}`, { method: "DELETE", query: args.force ? { force: "true" } : undefined }),
+    }, {
+        name: "bricks_get_element",
+        description: "Read one Bricks element and its complete descendant subtree without loading the full page tree.",
+        inputSchema: { type: "object", properties: { id: { type: "number" }, element_id: { type: "string" }, field: { type: "string", description: "content (default), header, or footer" } }, required: ["id", "element_id"], additionalProperties: false },
+        schema: z.object({ id: z.number().int().positive(), element_id: z.string().min(1), field: z.enum(["content", "header", "footer"]).optional() }),
+        handler: async (args) => wpRequest(`/pages/${args.id}/elements/${args.element_id}`, { query: args.field ? { field: args.field } : undefined }),
+    },
+    {
+        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) }),
+        handler: async (args) => { const { id, ...body } = args; return wpRequest(`/pages/${id}/element-operations`, { method: "POST", body }); },
+    }, {
+        name: "bricks_get_design_context",
+        description: "Read selected Bricks design-system sections: classes, variables, palettes, theme styles, breakpoints, components, and global settings. Use compact:true for counts/names only and include to control token usage.",
+        inputSchema: { type: "object", properties: { include: { type: "array", items: { type: "string" } }, compact: { type: "boolean" } }, additionalProperties: false },
+        schema: z.object({ include: z.array(z.enum(["classes", "variables", "palettes", "theme_styles", "breakpoints", "components", "global_settings"])).optional(), compact: z.boolean().optional() }),
+        handler: async (args) => wpRequest("/design-context", { query: { include: args.include?.join(","), compact: args.compact ? "true" : undefined } }),
+    }, {
         name: "bricks_reindex_query_filters",
         description: "Regenerate the Bricks Query Filters index. Call this after writing/editing any filter-* element via MCP — filters don't render until the index is rebuilt.",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
@@ -327,6 +373,33 @@ const tools = [
         handler: async (args) => wpRequest("/templates", { method: "POST", body: args }),
     },
     {
+        name: "bricks_manage_global_data",
+        description: "Read or safely replace one versioned Bricks global-data scope. Call action:get first for the current value/hash, then action:replace with expected_hash; dry-run and snapshot policy apply.",
+        inputSchema: { type: "object", properties: { scope: { type: "string", enum: ["global-variables", "color-palettes", "theme-styles", "components", "breakpoints"] }, action: { type: "string", enum: ["get", "replace"] }, expected_hash: { type: "string" }, value: { type: ["array", "object"] } }, required: ["scope", "action"], additionalProperties: false },
+        schema: z.object({ scope: z.enum(["global-variables", "color-palettes", "theme-styles", "components", "breakpoints"]), action: z.enum(["get", "replace"]), expected_hash: z.string().length(64).optional(), value: z.union([z.array(z.any()), z.record(z.any())]).optional() }).refine(v => v.action !== "replace" || (Boolean(v.expected_hash) && v.value !== undefined), "expected_hash and value are required for replace"),
+        handler: async (args) => { const { scope, action, ...body } = args; return action === "get" ? wpRequest(`/global-data/${scope}`) : wpRequest(`/global-data/${scope}`, { method: "PUT", body }); },
+    },
+    {
+        name: "bricks_apply_global_class_operations",
+        description: "Atomically add, update, or delete individual global classes without replacing the entire class library. Requires the hash from bricks_get_global_classes and rejects duplicate names or IDs.",
+        inputSchema: { type: "object", properties: { expected_hash: { type: "string" }, operations: { type: "array", items: { type: "object" } } }, required: ["expected_hash", "operations"], additionalProperties: false },
+        schema: z.object({ expected_hash: z.string().length(64), operations: z.array(z.object({ op: z.enum(["add", "update", "delete"]) }).passthrough()).min(1) }),
+        handler: async (args) => wpRequest("/global-classes/operations", { method: "POST", body: args }),
+    },
+    {
+        name: "bricks_manage_template",
+        description: "Long-tail template dispatcher: get full template data, update atomically with expected_modified, clone, or trash/delete. Updates create a Bricks-compatible WordPress revision and snapshots.",
+        inputSchema: { type: "object", properties: { id: { type: "number" }, action: { type: "string", enum: ["get", "update", "clone", "delete"] }, expected_modified: { type: "string" }, title: { type: "string" }, status: { type: "string" }, type: { type: "string" }, content: { type: "array" }, settings: { type: "object" }, conditions: { type: "array" }, force: { type: "boolean" } }, required: ["id", "action"], additionalProperties: false },
+        schema: z.object({ id: z.number().int().positive(), action: z.enum(["get", "update", "clone", "delete"]), expected_modified: z.string().optional(), title: z.string().optional(), status: z.enum(["draft", "publish", "private"]).optional(), type: z.string().optional(), content: z.array(z.any()).optional(), settings: z.record(z.any()).optional(), conditions: z.array(z.any()).optional(), force: z.boolean().optional() }).refine(v => v.action !== "update" || Boolean(v.expected_modified), "expected_modified is required for update"),
+        handler: async (args) => { const { id, action, ...body } = args; return action === "get" ? wpRequest(`/templates/${id}`) : wpRequest(`/templates/${id}/manage`, { method: "POST", body: { action, ...body } }); },
+    },
+    {
+        name: "bricks_get_preview_url",
+        description: "Generate a short-lived signed bearer URL (60–900 seconds) for visually checking a draft, private page, or template in a browser. Treat the URL as a secret until it expires.",
+        inputSchema: { type: "object", properties: { id: { type: "number" }, ttl: { type: "number", minimum: 60, maximum: 900 } }, required: ["id"], additionalProperties: false },
+        schema: z.object({ id: z.number().int().positive(), ttl: z.number().int().min(60).max(900).optional() }),
+        handler: async (args) => wpRequest(`/preview/${args.id}`, { query: args.ttl ? { ttl: String(args.ttl) } : undefined }),
+    }, {
         name: "bricks_get_global_classes",
         description: "Read Bricks global classes and their categories — useful before editing pages so styling stays consistent.",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
@@ -358,11 +431,43 @@ const tools = [
         handler: async () => wpRequest("/theme-styles"),
     },
 ];
+// MCP tool annotations (readOnlyHint / destructiveHint / idempotentHint) so
+// clients can calibrate approval prompts. "Destructive" here means the write
+// overwrites or removes existing data (even though the plugin snapshots first);
+// additive creates are non-destructive.
+const TOOL_ANNOTATIONS = {
+    bricks_start_here: { readOnlyHint: true },
+    bricks_ping: { readOnlyHint: true },
+    bricks_get_schema: { readOnlyHint: true },
+    bricks_list_pages: { readOnlyHint: true },
+    bricks_get_page: { readOnlyHint: true },
+    bricks_list_templates: { readOnlyHint: true },
+    bricks_manage_global_data: { readOnlyHint: false, destructiveHint: true },
+    bricks_apply_global_class_operations: { readOnlyHint: false, destructiveHint: true },
+    bricks_manage_template: { readOnlyHint: false, destructiveHint: true },
+    bricks_get_preview_url: { readOnlyHint: true },
+    bricks_get_global_classes: { readOnlyHint: true },
+    bricks_get_theme_styles: { readOnlyHint: true },
+    bricks_get_design_context: { readOnlyHint: true },
+    bricks_get_element: { readOnlyHint: true },
+    bricks_apply_element_operations: { readOnlyHint: false, destructiveHint: true },
+    bricks_list_media: { readOnlyHint: true },
+    bricks_find_media_usage: { readOnlyHint: true },
+    bricks_upload_media: { readOnlyHint: false, destructiveHint: false },
+    bricks_delete_media: { readOnlyHint: false, destructiveHint: true },
+    bricks_create_page: { readOnlyHint: false, destructiveHint: false },
+    bricks_create_template: { readOnlyHint: false, destructiveHint: false },
+    bricks_reindex_query_filters: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    bricks_update_page: { readOnlyHint: false, destructiveHint: true },
+    bricks_update_global_classes: { readOnlyHint: false, destructiveHint: true },
+    bricks_delete_page: { readOnlyHint: false, destructiveHint: true },
+};
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map(({ name, description, inputSchema }) => ({
         name,
         description,
         inputSchema,
+        annotations: TOOL_ANNOTATIONS[name],
     })),
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {

package/package.json

@@ -1,45 +1,47 @@
-{
-  "name": "bricks-mcp-server",
-  "version": "0.8.0",
-  "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": {
-    "bricks-mcp-server": "dist/index.js",
-    "bricks-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsc --watch",
-    "setup": "node dist/index.js setup",
-    "doctor": "node dist/index.js doctor",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "bricks",
-    "bricks-builder",
-    "wordpress",
-    "claude",
-    "claude-code",
-    "ai"
-  ],
-  "author": "Juan Leonardo",
-  "license": "GPL-2.0-or-later",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@types/node": "^20.12.0",
-    "typescript": "^5.5.0"
-  }
-}
+{
+  "name": "bricks-mcp-server",
+  "version": "0.13.0",
+  "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": {
+    "bricks-mcp-server": "dist/index.js",
+    "bricks-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "setup": "node dist/index.js setup",
+    "doctor": "node dist/index.js doctor",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bricks",
+    "bricks-builder",
+    "wordpress",
+    "claude",
+    "claude-code",
+    "ai"
+  ],
+  "author": "Juan Leonardo",
+  "license": "GPL-2.0-or-later",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "bricks-ai-workspace": "file:..",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "typescript": "^5.5.0"
+  }
+}