webcake-storefront-mcp 1.41.0 → 1.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { withCode } from "../builder/element-schema.js";
2
3
  import { resolvePreviewUrl, draftPreviewUrl } from "../config.js";
3
4
  import { captureScreenshot, resolveMicrolinkKey, resolveScreenshotProxyBase } from "../persistence/screenshot-client.js";
4
5
  import { validatePage, missingBreakpoints } from "../builder/page.js";
@@ -22,7 +23,8 @@ export async function preflightSite(api) {
22
23
  // write (missing/duplicate id, native-first volume…) already publishes today, so it only warns.
23
24
  const judge = (name, src, v) => {
24
25
  const shape = checkShape(src);
25
- const crash = shape.errors.filter((e) => !shape.editorOnly.includes(e)); // the live site blanks
26
+ // validatePage tags shape errors "[SHAPE] …"; compare in that form.
27
+ const crash = shape.errors.filter((e) => !shape.editorOnly.includes(e)).map((e) => withCode("SHAPE", e)); // the live site blanks
26
28
  const fatal = (v.errors || []).filter((e) => crash.includes(e));
27
29
  const rest = (v.errors || []).filter((e) => !crash.includes(e));
28
30
  errors.push(...fatal.slice(0, 10).map((e) => `${name}: ${e}`));
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import { elementSchema, suggestType, valueRules } from "../builder/element-schema.js";
2
3
  import { z } from "zod";
3
4
  import { BUILD_GUIDE } from "../builder/guide.js";
4
5
  import { PAGE_SCHEMA } from "../builder/page-schema.js";
@@ -173,9 +174,17 @@ export function registerBuilderTools(server, api, handle) {
173
174
  server.tool("get_build_guide", "Get the BuilderX page authoring guide: page shape, the grid layout model, styling, breakpoints, forms/data, and the build workflow. Read this before building or heavily editing a page.", {}, () => handle(async () => ({ guide: BUILD_GUIDE })));
174
175
  server.tool("get_page_schema", "Get the authoritative JSON Schema (Draft 2020-12) for a page source `{ sections: [...] }` — the structural contract for every node (id/type/specials/runtime{style,config}/children/events/bindings) in the CSS-grid model. Use it as the shape to emit; validate_page enforces the semantic rules.", {}, () => handle(async () => PAGE_SCHEMA));
175
176
  server.tool("list_elements", "List all BuilderX element/component types you can place on a page, grouped by category with a one-line summary and whether each is a container.", {}, () => handle(async () => listElements()));
176
- server.tool("get_element", "Get the full detail of an element type: category, container flag, summary, an ATTRIBUTES reference (the meaningful specials/config keys + their purpose/allowed values, events, and dataset binding targets), and a live skeleton node (the authoritative default shape) you can copy and edit. Read this before authoring/editing an element so you set the right keys.", {
177
+ server.tool("get_element", "Get the full detail of an element type: category, container flag, summary, an ATTRIBUTES reference (the meaningful specials/config keys + their purpose, events, and dataset binding targets), VALUE_RULES (per key: allowed values `one of …` that validate_page enforces, values `seen` on real pages, and non-string value types), PARENTS when it must sit inside a given container, and a live skeleton node (the authoritative default shape) you can copy and edit. Read this before authoring/editing an element so you set the right keys.", {
177
178
  type: z.string().describe("Element type, e.g. 'text', 'button', 'grid-product'"),
178
- }, ({ type }) => handle(async () => getElement(type)));
179
+ }, ({ type }) => handle(async () => {
180
+ const el = getElement(type);
181
+ if (el.error) {
182
+ const guess = suggestType(type);
183
+ return guess ? { ...el, did_you_mean: guess } : el;
184
+ }
185
+ const parents = elementSchema(type)?.parents;
186
+ return { ...el, ...(parents ? { parents } : {}), value_rules: valueRules(type) };
187
+ }));
179
188
  server.tool("list_events", "List every interaction EVENT you can attach to a node: the triggers (eventName: click/hover/success/submit/…) and the actions (open_page, scroll_to, toggle, open_popup, add_to_cart, buy_now, phone_call, open_link, …) with the exact extra fields each action needs. Attach via new_element/new_section opts.events (ids are auto-minted, e.g. opts.events=[{ action:'add_to_cart', open_page:'cart' }]).", {}, () => handle(async () => describeEventsCatalog()));
180
189
  server.tool("list_bindings", "List every dynamic-data BINDING target: the datasets (product, cart_item, order, order_item, post, category, customer, customer_address, …) and their exact field names ('product::product_price', …), which page type each needs (store/member/blog), and how repeater children (grid-product, cart-items, post-list) bind per-item. Attach via new_element opts.bindings (ids auto-minted, e.g. opts.bindings=[{ target:'product::product_price' }]).", {}, () => handle(async () => describeBindingsCatalog()));
181
190
  server.tool("new_element", "Build a single structurally-valid element node from the real builder factory. Returns the node — edit its specials/style, then place it in a section's children.", {
@@ -207,7 +216,7 @@ Example children: [{ "type":"container", "children":[{"type":"image","opts":{...
207
216
  containerOpts: container_opts || {},
208
217
  })));
209
218
  server.tool("new_page_skeleton", "Return an empty but valid page source: { sections: [] }. Add sections built with new_section, then save with build_page.", {}, () => handle(async () => newPageSkeleton()));
210
- server.tool("validate_page", "Validate a page source ({ sections: [...] }). Returns errors (block saving: duplicate/missing ids, missing types) and warnings (unknown types, form fields without field_name, dangling event targets) plus stats. Always run this before build_page.", {
219
+ server.tool("validate_page", "Validate a page source ({ sections: [...] }) against every element's schema. Each message reads `[CODE] #id (type) where: problem → fix`. errors block saving (duplicate/missing ids, renderer-crash shapes…); warnings render wrong (UNKNOWN_KEY invented/misspelled key, STYLE_KEY not a CSS property, TYPE_MISMATCH, BAD_VALUE outside the allowed values, BAD_PARENT, OUTSIDE_FORM, FIELD_NAME, EVENT/BINDING problems…). Repeated warnings are collapsed per code; summary.by_code counts all. Always run this before build_page and fix by code.", {
211
220
  source: z.any().describe("Page source object or JSON string"),
212
221
  }, ({ source }) => handle(async () => {
213
222
  const parsed = parseSource(source);
@@ -33,6 +33,7 @@ import { registerBuilderTools } from "./builder.js";
33
33
  import { registerBuilderExtraTools } from "./builder-extras.js";
34
34
  import { registerPageDraftTools } from "./page-draft.js";
35
35
  import { registerSitePlanTools } from "./site-plans.js";
36
+ import { registerApiGatewayTools } from "./api-gateway.js";
36
37
  /** Tool groups. `core` groups load natively; the rest are reached via search_tools + invoke_tool. */
37
38
  export const GROUPS = [
38
39
  { name: "session", title: "Session & apps", core: true, desc: "Connection context, site switch, app install/list, result cache" },
@@ -87,6 +88,7 @@ const MODULES = [
87
88
  ["web", registerBuilderExtraTools],
88
89
  ["web", registerPageDraftTools],
89
90
  ["site_config", registerSitePlanTools],
91
+ ["session", registerApiGatewayTools],
90
92
  ];
91
93
  /** Captures server.tool(...) calls into a registry instead of registering them. */
92
94
  class ToolCollector {
@@ -129,7 +131,7 @@ const READ_ONLY = /^(list|get|search|read|query|find|count|semantic|check|valida
129
131
  const DESTRUCTIVE = /^(delete|remove|uninstall|empty|clear|block|unblock|refuse)_/;
130
132
  const ADDITIVE = /^(create|add|upload|install|invite|duplicate|save)_/;
131
133
  export function toolAnnotations(name) {
132
- if (READ_ONLY.test(name))
134
+ if (READ_ONLY.test(name) || name === "api_find" || name === "api_get")
133
135
  return { readOnlyHint: true };
134
136
  if (DESTRUCTIVE.test(name))
135
137
  return { readOnlyHint: false, destructiveHint: true };
@@ -168,7 +170,9 @@ export function installTools(server, api, handle, opts = {}) {
168
170
  let nativeCount = 0;
169
171
  for (const e of collector.entries) {
170
172
  if (native.has(e.group)) {
171
- server.tool(e.name, e.description, e.shape, toolAnnotations(e.name), e.handler);
173
+ // .strict(): an argument the tool doesn't take is REFUSED with its name, not silently
174
+ // dropped (a dropped page_id/site_id made a call act on the wrong page).
175
+ server.registerTool(e.name, { description: e.description, inputSchema: z.object(e.shape).strict(), annotations: toolAnnotations(e.name) }, e.handler);
172
176
  nativeCount++;
173
177
  }
174
178
  }
@@ -260,7 +264,7 @@ courses, sale channels, automation…). Returns name, group, description and JSO
260
264
  if (readOnlyOnly && !toolAnnotations(name).readOnlyHint) {
261
265
  return errorResult(`Error: "${name}" is not read-only — run it with invoke_tool.`);
262
266
  }
263
- const parsed = z.object(e.shape).safeParse(args ?? {});
267
+ const parsed = z.object(e.shape).strict().safeParse(args ?? {});
264
268
  if (!parsed.success) {
265
269
  const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
266
270
  return errorResult(`Error: invalid arguments for "${name}": ${issues}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webcake-storefront-mcp",
3
- "version": "1.41.0",
3
+ "version": "1.42.0",
4
4
  "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
5
5
  "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
6
6
  "license": "MIT",
@@ -30,6 +30,8 @@
30
30
  "dev": "tsc --watch",
31
31
  "dev:guide": "node scripts/preview-guide.mjs",
32
32
  "smoke": "node dist/smoke.js",
33
+ "mine-elements": "node scripts/mine-element-keys.mjs",
34
+ "gen-api": "node scripts/gen-api-catalog.mjs",
33
35
  "prepare": "npm run build",
34
36
  "prepublishOnly": "npm run build && npm run smoke",
35
37
  "test": "node --test \"test/*.test.mjs\""