brilliant-directories-mcp 6.40.21 → 6.40.23

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.
package/index.js CHANGED
@@ -1335,9 +1335,42 @@ function validatePathParamIds(toolPath, args) {
1335
1335
  // rgb()/rgba(), all-digit sizes like 16) before validateHeroEnumsInArgs
1336
1336
  // rejects anything still invalid. Only applies to createWebPage / updateWebPage.
1337
1337
  // Mirrored in Worker's `src/index.ts`. Keep in sync.
1338
- const HERO_LINK_COLOR_VALUES = new Set(["primary", "info", "success", "warning", "danger", "default", "secondary"]);
1339
- const HERO_LINK_SIZE_VALUES = new Set(["", "btn-lg", "btn-xl"]);
1338
+ // Hero/h1/h2 enum table — every enum-typed field on createWebPage /
1339
+ // updateWebPage that BD persists verbatim to users_meta and renders into CSS
1340
+ // classes or template logic. BD does NOT validate any of these server-side.
1341
+ // An invalid value (e.g. hero_alignment="flex-start", h1_font_weight="bold",
1342
+ // hero_column_width="13") gets stored as-is and breaks rendering — sometimes
1343
+ // silently, sometimes with broken CSS classes that look right but don't match
1344
+ // BD's stylesheet selectors. Fix: validate against the enum set BEFORE
1345
+ // forwarding to BD. Same lists as the spec — keep in sync if BD adds values.
1346
+ // Discrete-range fields from BD's admin UI dropdowns. Generated programmatically
1347
+ // to keep the table readable. Source of truth: BD admin form `<select>` options
1348
+ // for each field (verified live 2026-04-25).
1349
+ const HERO_PADDING_STEPS = Array.from({ length: 21 }, (_, i) => String(i * 10)); // 0..200 step 10
1350
+ const H1_FONT_SIZE_STEPS = Array.from({ length: 51 }, (_, i) => String(30 + i)); // 30..80 step 1
1351
+ const H2_FONT_SIZE_STEPS = Array.from({ length: 41 }, (_, i) => String(20 + i)); // 20..60 step 1
1352
+ const HERO_CONTENT_FONT_SIZE_STEPS = Array.from({ length: 21 }, (_, i) => String(10 + i)); // 10..30 step 1
1353
+ const HERO_ENUM_FIELDS = {
1354
+ hero_link_color: ["primary", "info", "success", "warning", "danger", "default", "secondary"],
1355
+ hero_link_size: ["", "btn-lg", "btn-xl"],
1356
+ hero_link_target_blank: ["0", "1"],
1357
+ hero_alignment: ["left", "center", "right"],
1358
+ hero_column_width: ["3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
1359
+ hero_background_image_size: ["mobile-ready", "standard"],
1360
+ hero_hide_banner_ad: ["0", "1"],
1361
+ hero_content_overlay_opacity: ["0.0", "0.1", "0.2", "0.3", "0.4", "0.5", "0.6", "0.7", "0.8", "0.9", "1"],
1362
+ hero_top_padding: HERO_PADDING_STEPS,
1363
+ hero_bottom_padding: HERO_PADDING_STEPS,
1364
+ h1_font_size: H1_FONT_SIZE_STEPS,
1365
+ h2_font_size: H2_FONT_SIZE_STEPS,
1366
+ hero_content_font_size: HERO_CONTENT_FONT_SIZE_STEPS,
1367
+ h1_font_weight: ["300", "400", "600", "800"],
1368
+ h2_font_weight: ["300", "400", "600", "800"],
1369
+ };
1370
+ const HERO_LINK_COLOR_VALUES = new Set(HERO_ENUM_FIELDS.hero_link_color);
1371
+ const HERO_LINK_SIZE_VALUES = new Set(HERO_ENUM_FIELDS.hero_link_size);
1340
1372
  const HERO_ENUM_TOOLS = new Set(["createWebPage", "updateWebPage"]);
1373
+
1341
1374
  /** Coerce common agent mistakes before validate — BD builds `btn-${color}` + size class verbatim. */
1342
1375
  function sanitizeHeroCtaEnumsInArgs(toolName, args) {
1343
1376
  if (!HERO_ENUM_TOOLS.has(toolName) || !args || typeof args !== "object") return;
@@ -1365,16 +1398,17 @@ function sanitizeHeroCtaEnumsInArgs(toolName, args) {
1365
1398
  }
1366
1399
  }
1367
1400
  }
1401
+
1368
1402
  function validateHeroEnumsInArgs(toolName, args) {
1369
1403
  if (!HERO_ENUM_TOOLS.has(toolName) || !args || typeof args !== "object") return null;
1370
- if (args.hero_link_color !== undefined && args.hero_link_color !== null && args.hero_link_color !== "") {
1371
- if (!HERO_LINK_COLOR_VALUES.has(String(args.hero_link_color))) {
1372
- return `hero_link_color must be one of: primary, info, success, warning, danger, default, secondary (you sent: "${args.hero_link_color}"). Invalid values produce broken CSS classes like btn-${args.hero_link_color} — BD does not validate server-side.`;
1373
- }
1374
- }
1375
- if (args.hero_link_size !== undefined && args.hero_link_size !== null) {
1376
- if (!HERO_LINK_SIZE_VALUES.has(String(args.hero_link_size))) {
1377
- return `hero_link_size must be one of: "" (Normal), btn-lg (Large), btn-xl (Extra Large) (you sent: "${args.hero_link_size}"). Invalid values render as a broken class verbatim — BD does not validate server-side.`;
1404
+ for (const [field, allowed] of Object.entries(HERO_ENUM_FIELDS)) {
1405
+ const v = args[field];
1406
+ if (v === undefined || v === null) continue;
1407
+ // Empty string is allowed only if "" is in the enum (e.g. hero_link_size).
1408
+ if (v === "" && !allowed.includes("")) continue;
1409
+ const s = String(v);
1410
+ if (!allowed.includes(s)) {
1411
+ return `${field} must be one of: ${allowed.map((x) => `"${x}"`).join(", ")} (you sent: "${s}"). Invalid values are persisted verbatim — BD does not validate server-side, so the value renders as a broken CSS class or breaks the hero layout.`;
1378
1412
  }
1379
1413
  }
1380
1414
  return null;
@@ -2001,22 +2035,38 @@ async function main() {
2001
2035
  }
2002
2036
  }
2003
2037
 
2004
- // TRANSPORT STABILITY GUARD — auto-throttle heavy reads on USER_READ_TOOLS.
2005
- // When ANY include_* flag is true, each row balloons to ~5-10KB (nested
2006
- // schemas: subscription, services, photos, transactions, profession). At
2007
- // limit=50 a single response can exceed 300KB, which the MCP transport
2008
- // (stdio buffer, Streamable HTTP, SSE) intermittently truncates without
2009
- // a clean error — agents see silent timeouts. Cap at 25 when heavy
2010
- // includes are active. Adjustment, not rejection: agent always gets
2011
- // results; a `_throttled` warning in the response teaches it.
2038
+ // TRANSPORT STABILITY GUARD — auto-throttle heavy reads.
2039
+ //
2040
+ // When ANY include_* flag is true, each row balloons (users: ~5-10KB
2041
+ // with subscription/services/photos/transactions schemas; web pages:
2042
+ // 14-41KB with content+code blobs). At limit=50 a single response can
2043
+ // exceed 300KB-2MB, which the MCP transport (stdio buffer, Streamable
2044
+ // HTTP, SSE) intermittently truncates without a clean error — agents
2045
+ // see silent timeouts. Cap progressively and add a `_throttled` warning.
2046
+ // Adjustment, not rejection: agent always gets results; the warning
2047
+ // teaches them to paginate or drop heavy includes.
2048
+ //
2049
+ // Throttle tiers:
2050
+ // USER_READ_TOOLS + any include_* flag → cap limit at 25
2051
+ // listWebPages + any include_* flag → cap limit at 25
2052
+ // listWebPages + include_content AND include_code → cap limit at 10 (worst case — both heavy buckets)
2012
2053
  let _throttleWarning = null;
2013
- if (isUserReadTool && args && typeof args === "object") {
2054
+ if (args && typeof args === "object") {
2014
2055
  const heavyActive = Object.values(includeFlags).some((v) => v === true || v === "1" || v === 1);
2015
2056
  const requested = Number(args.limit);
2016
- if (heavyActive && Number.isFinite(requested) && requested > 25) {
2057
+ if (isUserReadTool && heavyActive && Number.isFinite(requested) && requested > 25) {
2017
2058
  _throttleWarning = `limit reduced from ${requested} to 25 because heavy include_* flag is set. To get more rows: (1) paginate with next_page, (2) drop include_* for a lean enumeration first then call getUser per-record for the few you need enriched, or (3) call without include_* and re-query specific user_ids individually.`;
2018
2059
  args.limit = 25;
2019
2060
  console.error(`[throttle] ${name}: ${_throttleWarning}`);
2061
+ } else if (name === "listWebPages" && heavyActive && Number.isFinite(requested)) {
2062
+ const bothHeavy = (includeFlags.include_content === true || includeFlags.include_content === "1" || includeFlags.include_content === 1) &&
2063
+ (includeFlags.include_code === true || includeFlags.include_code === "1" || includeFlags.include_code === 1);
2064
+ const cap = bothHeavy ? 10 : 25;
2065
+ if (requested > cap) {
2066
+ _throttleWarning = `limit reduced from ${requested} to ${cap} because ${bothHeavy ? "BOTH include_content AND include_code are set (heaviest combo — pages can be 30-40KB each)" : "a heavy include_* flag is set"}. To get more rows: (1) paginate with next_page, (2) drop include_* for a lean enumeration first then call getWebPage per-record for the few you need enriched, or (3) split the read — separate calls with include_content=true and include_code=true.`;
2067
+ args.limit = cap;
2068
+ console.error(`[throttle] ${name}: ${_throttleWarning}`);
2069
+ }
2020
2070
  }
2021
2071
  }
2022
2072
 
@@ -2167,6 +2217,56 @@ async function main() {
2167
2217
  };
2168
2218
  }
2169
2219
 
2220
+ // Duplicate-filename guard for createWebPage. BD does NOT enforce
2221
+ // unique `filename` on `list_seo` — two creates with the same slug
2222
+ // both succeed and the public URL renders one of them non-deterministically
2223
+ // (silent destructive: agent thinks the new page is live but it may
2224
+ // be the OLD one shadowing it). Pre-check via listWebPages — one
2225
+ // small filtered query — and reject if a row exists. Bypass with
2226
+ // `force_duplicate_filename=true` for the rare legitimate case
2227
+ // (e.g. intentional shadow page, internal fork).
2228
+ if (name === "createWebPage" && args && typeof args === "object" && args.filename) {
2229
+ const force = args.force_duplicate_filename === true || args.force_duplicate_filename === "1" || args.force_duplicate_filename === 1;
2230
+ if (force) {
2231
+ delete args.force_duplicate_filename; // never forward to BD
2232
+ } else {
2233
+ try {
2234
+ const dupCheck = await makeRequest(
2235
+ config,
2236
+ "GET",
2237
+ "/api/v2/list_seo/get",
2238
+ { property: "filename", property_value: String(args.filename), property_operator: "=", limit: 1 },
2239
+ null
2240
+ );
2241
+ const rows = dupCheck && dupCheck.body && Array.isArray(dupCheck.body.message) ? dupCheck.body.message : [];
2242
+ const existing = rows.find((r) => r && String(r.filename) === String(args.filename));
2243
+ if (existing) {
2244
+ return {
2245
+ content: [{ type: "text", text: `filename '${args.filename}' already exists at seo_id=${existing.seo_id}. Use updateWebPage(seo_id=${existing.seo_id}, ...) to modify, or pick a unique slug. Bypass with force_duplicate_filename=true if you genuinely need a duplicate (rare).` }],
2246
+ isError: true,
2247
+ };
2248
+ }
2249
+ } catch (err) {
2250
+ console.error(`[createWebPage] duplicate-filename pre-check failed (${err && err.message ? err.message : "unknown"}); proceeding with create — caller should manually verify uniqueness post-create.`);
2251
+ }
2252
+ }
2253
+ }
2254
+
2255
+ // Thin-content soft warning: createWebPage with NO title, h1, meta_desc,
2256
+ // or content (and no override) leaves a publicly-live blank page that
2257
+ // Google may index as thin content. Don't reject — there are legit
2258
+ // placeholder/draft flows. Just attach a `_thin_content_warning` to the
2259
+ // response body so the agent and human user notice. Only fires for
2260
+ // seo_type=content (homepage / search-results / data_category have
2261
+ // their own template-driven content).
2262
+ let _thinContentWarning = null;
2263
+ if (name === "createWebPage" && args && typeof args === "object" && args.seo_type === "content") {
2264
+ const has = (k) => args[k] !== undefined && args[k] !== null && String(args[k]).trim() !== "";
2265
+ if (!has("title") && !has("h1") && !has("meta_desc") && !has("content")) {
2266
+ _thinContentWarning = `createWebPage created a page with no title, h1, meta_desc, or content. content_active defaults to 1 — the page is publicly live and Google may index it as thin content. Provide at least one of those fields, or pass content_active=0 to keep it hidden until populated.`;
2267
+ }
2268
+ }
2269
+
2170
2270
  // EAV split: peel hero/EAV fields off updateWebPage args before the
2171
2271
  // parent update. Flushed via users_meta after the parent succeeds.
2172
2272
  const { direct: eavDirect, eav: eavQueued, route: eavRoute } = splitEavParams(name, args || {});
@@ -2219,6 +2319,31 @@ async function main() {
2219
2319
  }
2220
2320
  }
2221
2321
 
2322
+ // Rewrite BD's misleading "list_seo not found" 404 into something
2323
+ // agents can act on. BD returns this string for both single-record
2324
+ // misses and empty filtered lists, which agents misread as "the
2325
+ // list_seo TABLE is missing" (a system-level failure) and abort
2326
+ // retries. Distinguish + rephrase:
2327
+ // - getWebPage with a non-existent seo_id → "No list_seo record
2328
+ // with seo_id=N" (still error; clear that the record is the
2329
+ // thing missing, not the table).
2330
+ // - listWebPages with a filter that matches nothing → status
2331
+ // "success" with empty message array + total=0 (success because
2332
+ // the query worked correctly, it just found nothing).
2333
+ if (result.body && typeof result.body === "object" && result.body.status === "error" && result.body.message === "list_seo not found") {
2334
+ if (name === "getWebPage") {
2335
+ const id = args && args.seo_id !== undefined ? args.seo_id : "?";
2336
+ result.body.message = `No list_seo record with seo_id=${id}.`;
2337
+ } else if (name === "listWebPages") {
2338
+ // Empty filter result is success, not error.
2339
+ result.body.status = "success";
2340
+ result.body.message = [];
2341
+ result.body.total = result.body.total || 0;
2342
+ result.body.current_page = result.body.current_page || 1;
2343
+ result.body.total_pages = result.body.total_pages || 0;
2344
+ }
2345
+ }
2346
+
2222
2347
  // Apply lean-response shaping. Reads honor include_* flags; writes
2223
2348
  // are always lean (create/update echoes trimmed to a small keep-set).
2224
2349
  if (result.body) {
@@ -2237,6 +2362,11 @@ async function main() {
2237
2362
  if (_throttleWarning && result.body && typeof result.body === "object") {
2238
2363
  result.body._throttled = _throttleWarning;
2239
2364
  }
2365
+ // Attach thin-content warning on createWebPage if no SEO/title fields
2366
+ // were set (page goes live but Google may index as thin content).
2367
+ if (_thinContentWarning && result.body && typeof result.body === "object") {
2368
+ result.body._thin_content_warning = _thinContentWarning;
2369
+ }
2240
2370
 
2241
2371
  // Auto-refresh site cache after successful cache-gated writes.
2242
2372
  // Lenient: annotation-only on failure; never fails the parent response.
@@ -8957,7 +8957,7 @@
8957
8957
  "post": {
8958
8958
  "operationId": "createWebPage",
8959
8959
  "summary": "Create a page",
8960
- "description": "Create a `list_seo` page record. Writes live data.\n\n**Cache refresh is automatic.** Every successful `createWebPage` / `updateWebPage` triggers `refreshCache(scope=web_pages)` server-side; the response includes `auto_cache_refreshed: true`. Do not call `refreshSiteCache` manually after — it's already done. If `auto_cache_refreshed: false` appears in the response, the write succeeded but cache flush failed; check `auto_cache_refresh_error` and retry `refreshSiteCache` once.\n\n**Required fields:** `seo_type`, `filename`, `date_updated` (format `YYYYMMDDHHmmss`, set current time - BD does not auto-populate).\n\n**Pre-check mandatory:** BD does NOT enforce unique `filename`. Two creates with the same slug both succeed and produce two `list_seo` rows; which one renders is undefined. Before every call: `listWebPages property=filename property_value=<slug> property_operator==`. If exists, `updateWebPage` the existing record OR pick a unique slug (append `-2`, `-3`). Do NOT skip the check.\n\n**Asset field routing (mandatory - Froala strips mismatched content silently):**\n\n- `content` - body HTML. No `<style>`/`<script>` tags. Supports `[widget=Name]` shortcodes + `%%%token%%%`.\n\n- `content_css` - raw CSS rules. NO `<style>` wrapper. Scope to a unique page class; never target `.container`/`.froala-table`/`.image-placeholder` (reserved). Do NOT use `@import` (causes FOUC/CLS - use `content_head` `<link>` tag instead).\n\n- `content_footer_html` - JavaScript, pixels, analytics embeds (`<script>` tags OK here). IIFE-wrap + scope.\n\n- `content_head` - head-only deps (`<link>`, `<meta>`, JSON-LD, external stylesheets, fonts).\n\n- `content_footer` - MISLEADING NAME. NOT footer HTML. Page-access gate enum: `\"\"` (public), `\"members_only\"`, `\"digital_products\"`.\n\n- Hero banner -> `enable_hero_section` + `hero_*` + `h1_*`/`h2_*` fields.\n\nAll asset fields accept raw content verbatim. No CDATA, no `<parameter>`/`<invoke>`/`<function_calls>` scaffolding, no entity-escaped HTML — forbidden anywhere in the value, not just as wrappers. Server strips these as a safety net; do not rely on it.\n\n**SVG/canvas prohibited in `content`** - Froala strips them. Charts/diagrams go in a custom Widget, embedded via `[widget=Name]` shortcode.\n\n**`seo_type` values:** `home` (system-seeded; cannot CREATE homepage, only `updateWebPage`), `content` (generic static page), `profile_search_results` (member search override - see workflow below), `data_category` (post search), `custom_widget_page`, `password_retrieval_page`, `unsubscribed`.\n\n**Hero section - when `enable_hero_section` = `1` or `2`, agent enabling it must apply safe defaults for text readability:**\n\n- `h1_font_color=\"rgb(255,255,255)\"`, `h2_font_color=\"rgb(255,255,255)\"` (white text)\n\n- `hero_content_overlay_color=\"rgb(0,0,0)\"`, `hero_content_overlay_opacity=\"0.5\"` (dimmed overlay)\n\n- `hero_top_padding=\"100\"`, `hero_bottom_padding=\"100\"` (breathing room)\n\n- `hero_column_width=\"8\"` (70% width — matches admin UI default)\n\n- All color fields RGB ONLY (`rgb(0,0,0)`) - hex not accepted.\n\n- Hero `h1_*`/`h2_*` fields style ONLY the hero banner; H1/H2 TEXT comes from the record's top-level `h1`/`h2` fields.\n\n- Hero image: content-relevant Pexels stock photo (free license, no attribution). See image URL rule (imported field — bare URL, no query string). Never `picsum.photos`/`lorempixel`/`placekitten`.\n\n- Hero gap-fix CSS (`seo_type=content` ONLY): add `.hero_section_container + div.clearfix-lg {display:none}` to `content_css` to close BD's 40px clearfix gap. **Never add this rule on any other `seo_type`** - on `profile_search_results` / `data_category` the clearfix provides needed spacing before live search-results; hiding it causes results to butt-join the hero.\n\n- Hero is cache-gated — but `createWebPage`/`updateWebPage` auto-refresh handles it; no separate call needed.\n\n- **Homepage hero is BENIGN**: `seo_id=1` stores hero fields but the homepage template does NOT render them. Skip hero fields on homepage unless user explicitly asks.\n\n**`profile_search_results` SEO pages - thin-content remedy workflow:**\n\nUsed to override BD's auto-generated dynamic search URLs (e.g. `california/beverly-hills/plumbers`) with static custom SEO copy. Creating a `list_seo` row with a matching `filename` takes over the public URL.\n\n**CRITICAL - `filename` MUST be a real slug BD's dynamic router recognizes.** Every segment must come from live lookups; arbitrary slugs (`foo-bar`, `my-cool-page`) return HTTP 404 even with `content_active=1`. Segment sources (hierarchy, left-parents droppable, `/` separators, NO leading slash):\n\n- country: `listCountries` -> lowercase `country_name`, spaces -> hyphens (e.g. `united-states`). NO stored slug.\n\n- state: `listStates` -> `state_filename`\n\n- city: `listCities` -> `city_filename`\n\n- top_cat: `listTopCategories` -> `filename`\n\n- sub_cat: `listSubCategories` -> `filename`\n\nCountry-only slug (e.g. `united-states` alone) does NOT render for `profile_search_results` - country only works as a LEFT-PARENT PREFIX. For arbitrary-URL static pages use `seo_type=content` (content routes at any filename).\n\n**Workflow for \"add SEO to [category] in [location]\":**\n1. Resolve each human name to its slug via the relevant `list*` endpoint (exact-match `=`).\n2. For ambiguous inputs (e.g. \"Beverly Hills plumbers\" - could be `beverly-hills/plumbers` or `california/beverly-hills/plumbers`), ask user which variant.\n3. Pre-check: `listWebPages property=filename property_value=<slug> property_operator==`. Exists -> `updateWebPage`. Missing -> `createWebPage` with fields below.\n4. **Required defaults on create and every update** (unless user overrides):\n - `seo_type=profile_search_results`\n - `content_active=1`\n - `custom_html_placement=4` (Below Body Content - safest for boilerplate intro without disrupting live results)\n - `form_name=\"Member Search Result\"` (sidebar - Master Default; do NOT use `Member Profile Page`, that's for profile pages)\n - `menu_layout=3` (Left Slim sidebar position)\n - `date_updated=<current YYYYMMDDHHmmss>` (every write)\n - `updated_by` - recommended (e.g. `\"AI Agent\"`, `\"API\"`)\n - `enable_hero_section=1` + content-relevant Pexels `hero_image` + the 6 readability safe-defaults from the hero rule (white H1/H2, `rgb(0,0,0)` overlay at 0.5, 100/100 padding). Most end-users don't know to ask for a hero; thin-SEO pages underperform without one. User can opt out with `enable_hero_section=0`. (Cache flush is automatic post-write.)\n5. **Auto-generate SEO meta for the specific combo - don't leave blank:**\n - `title` - 50-60 chars ideal, <=70 max. Pattern: `\"[Category] in [City], [State] | [Site Name]\"`.\n - `meta_desc` - 150-160 chars ideal, <=170 max. 1-2 sentence pitch with location + CTA.\n - `meta_keywords` - ~200 chars, comma-separated (no spaces).\n - `facebook_title` - 55-60 chars, differ from `title` (more conversational).\n - `facebook_desc` - 110-125 chars, punchier than `meta_desc`.\n - Do NOT auto-set `facebook_image` (needs uploaded asset).\n6. **H1/H2 double-render trap:** if hero enabled AND `content` contains `<h1>`/`<h2>`, both render. Either set `h1`/`h2` fields and omit from `content`, or put in `content` and leave fields blank. Never both.\n7. **No max-width wrappers in `content` or `content_css`** on `profile_search_results` pages. BD's layout already provides the outer container; adding `max-width: 960px; margin: auto` double-constrains to a narrow strip. Let content flow at natural container width.\n8. `custom_html_placement` is only meaningful on `profile_search_results` (and `data_category`). Ignored on `content` pages.\n\n**SEO content for categories:** route to `createWebPage seo_type=profile_search_results` (NOT `updateTopCategory.desc` / `updateSubCategory.desc` - those are internal labels, not rendered).\n\n**`list_seo` EAV fields** (18+ fields stored in `users_meta`, NOT direct columns): `linked_post_category`, `linked_post_type`, `disable_preview_screenshot`, `disable_css_stylesheets`, `hero_content_overlay_opacity`, `hero_link_target_blank`, `hero_background_image_size`, `hero_link_size`, `hero_link_color`, `hero_content_font_size`, `hero_section_content`, `hero_column_width`, `h2_font_weight`, `h1_font_weight`, `h2_font_size`, `h1_font_size`, `hero_link_text`, `hero_link_url`. BD's `list_seo` EAV layer may include more fields beyond these 18 - detection is reliable: after any `updateWebPage`, re-GET and compare stored value to what you sent; if it didn't persist, fall back to the EAV path. On CREATE, all fields write correctly. On UPDATE, the EAV path silently drops these - write via `updateUserMeta`/`createUserMeta` with `database=list_seo`. EAV write workflow per field: (1) `listUserMeta` with `database=list_seo`, `database_id=<seo_id>`, `key=<field>` -> if `meta_id` found, `updateUserMeta(meta_id, value=<new>)`; (2) not found -> `createUserMeta(database=list_seo, database_id=<seo_id>, key=<field>, value=<new>)`. Reads merge automatically via `getWebPage`/`listWebPages`. On `deleteWebPage`: BD does NOT cascade - run orphan cleanup per the top-level users_meta rule (`listUserMeta` filtered by `database=list_seo`+`database_id=<deleted seo_id>`, then `deleteUserMeta` each match).\n\n**See also:** `listWebPages`, `updateWebPage`, `createRedirect` (preserve SEO on slug changes).\n\n**Returns:** `{ status: \"success\", message: {...createdRecord}, auto_cache_refreshed: true|false, auto_cache_refresh_error?: \"...\" }` including `seo_id`. `auto_cache_refreshed` reports whether the automatic cache flush succeeded; if `false`, `auto_cache_refresh_error` explains why and the agent should retry `refreshSiteCache` manually once.",
8960
+ "description": "Create a `list_seo` page record. Writes live data.\n\n**Cache refresh is automatic.** Every successful `createWebPage` / `updateWebPage` triggers `refreshCache(scope=web_pages)` server-side; the response includes `auto_cache_refreshed: true`. Do not call `refreshSiteCache` manually after — it's already done. If `auto_cache_refreshed: false` appears in the response, the write succeeded but cache flush failed; check `auto_cache_refresh_error` and retry `refreshSiteCache` once.\n\n**Required fields:** `seo_type`, `filename`, `date_updated` (format `YYYYMMDDHHmmss`, set current time - BD does not auto-populate).\n\n**Filename uniqueness — auto-checked by the wrapper.** BD does NOT enforce unique `filename`, so the wrapper auto-pre-checks `listWebPages` for an existing slug before forwarding the create. If a row exists, the create is rejected with the existing `seo_id` so the agent can `updateWebPage` instead. Bypass with `force_duplicate_filename=true` for the rare legitimate case (intentional shadow page, internal fork).\n\n**Thin-content warning:** if no `title`, `h1`, `meta_desc`, or `content` is set on a `seo_type=content` create, a `_warning` field is attached to the response. The page is still created (`content_active` defaults to 1, so it goes live publicly) — Google may index it as thin content. Provide at least one of those fields, or set `content_active=0` to keep the page hidden until populated.\n\n**Asset field routing (mandatory - Froala strips mismatched content silently):**\n\n- `content` - body HTML. No `<style>`/`<script>` tags. Supports `[widget=Name]` shortcodes + `%%%token%%%`.\n\n- `content_css` - raw CSS rules. NO `<style>` wrapper. Scope to a unique page class; never target `.container`/`.froala-table`/`.image-placeholder` (reserved). Do NOT use `@import` (causes FOUC/CLS - use `content_head` `<link>` tag instead).\n\n- `content_footer_html` - JavaScript, pixels, analytics embeds (`<script>` tags OK here). IIFE-wrap + scope.\n\n- `content_head` - head-only deps (`<link>`, `<meta>`, JSON-LD, external stylesheets, fonts).\n\n- `content_footer` - MISLEADING NAME. NOT footer HTML. Page-access gate enum: `\"\"` (public), `\"members_only\"`, `\"digital_products\"`.\n\n- Hero banner -> `enable_hero_section` + `hero_*` + `h1_*`/`h2_*` fields.\n\nAll asset fields accept raw content verbatim. No CDATA, no `<parameter>`/`<invoke>`/`<function_calls>` scaffolding, no entity-escaped HTML — forbidden anywhere in the value, not just as wrappers. Server strips these as a safety net; do not rely on it.\n\n**SVG/canvas prohibited in `content`** - Froala strips them. Charts/diagrams go in a custom Widget, embedded via `[widget=Name]` shortcode.\n\n**`seo_type` values:** `home` (system-seeded; cannot CREATE homepage, only `updateWebPage`), `content` (generic static page), `profile_search_results` (member search override - see workflow below), `data_category` (post search), `custom_widget_page`, `password_retrieval_page`, `unsubscribed`.\n\n**Hero section - when `enable_hero_section` = `1` or `2`, agent enabling it must apply safe defaults for text readability:**\n\n- `h1_font_color=\"rgb(255,255,255)\"`, `h2_font_color=\"rgb(255,255,255)\"` (white text)\n\n- `hero_content_overlay_color=\"rgb(0,0,0)\"`, `hero_content_overlay_opacity=\"0.5\"` (dimmed overlay)\n\n- `hero_top_padding=\"100\"`, `hero_bottom_padding=\"100\"` (breathing room)\n\n- `hero_column_width=\"8\"` (70% width — matches admin UI default)\n\n- All color fields RGB ONLY (`rgb(0,0,0)`) - hex not accepted.\n\n- Hero `h1_*`/`h2_*` fields style ONLY the hero banner; H1/H2 TEXT comes from the record's top-level `h1`/`h2` fields.\n\n- Hero image: content-relevant Pexels stock photo (free license, no attribution). See image URL rule (imported field — bare URL, no query string). Never `picsum.photos`/`lorempixel`/`placekitten`.\n\n- Hero gap-fix CSS (`seo_type=content` ONLY): add `.hero_section_container + div.clearfix-lg {display:none}` to `content_css` to close BD's 40px clearfix gap. **Never add this rule on any other `seo_type`** - on `profile_search_results` / `data_category` the clearfix provides needed spacing before live search-results; hiding it causes results to butt-join the hero.\n\n- Hero is cache-gated — but `createWebPage`/`updateWebPage` auto-refresh handles it; no separate call needed.\n\n- **Homepage hero is BENIGN**: `seo_id=1` stores hero fields but the homepage template does NOT render them. Skip hero fields on homepage unless user explicitly asks.\n\n**`profile_search_results` SEO pages - thin-content remedy workflow:**\n\nUsed to override BD's auto-generated dynamic search URLs (e.g. `california/beverly-hills/plumbers`) with static custom SEO copy. Creating a `list_seo` row with a matching `filename` takes over the public URL.\n\n**CRITICAL - `filename` MUST be a real slug BD's dynamic router recognizes.** Every segment must come from live lookups; arbitrary slugs (`foo-bar`, `my-cool-page`) return HTTP 404 even with `content_active=1`. Segment sources (hierarchy, left-parents droppable, `/` separators, NO leading slash):\n\n- country: `listCountries` -> lowercase `country_name`, spaces -> hyphens (e.g. `united-states`). NO stored slug.\n\n- state: `listStates` -> `state_filename`\n\n- city: `listCities` -> `city_filename`\n\n- top_cat: `listTopCategories` -> `filename`\n\n- sub_cat: `listSubCategories` -> `filename`\n\nCountry-only slug (e.g. `united-states` alone) does NOT render for `profile_search_results` - country only works as a LEFT-PARENT PREFIX. For arbitrary-URL static pages use `seo_type=content` (content routes at any filename).\n\n**Workflow for \"add SEO to [category] in [location]\":**\n1. Resolve each human name to its slug via the relevant `list*` endpoint (exact-match `=`).\n2. For ambiguous inputs (e.g. \"Beverly Hills plumbers\" - could be `beverly-hills/plumbers` or `california/beverly-hills/plumbers`), ask user which variant.\n3. Pre-check: `listWebPages property=filename property_value=<slug> property_operator==`. Exists -> `updateWebPage`. Missing -> `createWebPage` with fields below.\n4. **Required defaults on create and every update** (unless user overrides):\n - `seo_type=profile_search_results`\n - `content_active=1`\n - `custom_html_placement=4` (Below Body Content - safest for boilerplate intro without disrupting live results)\n - `form_name=\"Member Search Result\"` (sidebar - Master Default; do NOT use `Member Profile Page`, that's for profile pages)\n - `menu_layout=3` (Left Slim sidebar position)\n - `date_updated=<current YYYYMMDDHHmmss>` (every write)\n - `updated_by` - recommended (e.g. `\"AI Agent\"`, `\"API\"`)\n - `enable_hero_section=1` + content-relevant Pexels `hero_image` + the 6 readability safe-defaults from the hero rule (white H1/H2, `rgb(0,0,0)` overlay at 0.5, 100/100 padding). Most end-users don't know to ask for a hero; thin-SEO pages underperform without one. User can opt out with `enable_hero_section=0`. (Cache flush is automatic post-write.)\n5. **Auto-generate SEO meta for the specific combo - don't leave blank:**\n - `title` - 50-60 chars ideal, <=70 max. Pattern: `\"[Category] in [City], [State] | [Site Name]\"`.\n - `meta_desc` - 150-160 chars ideal, <=170 max. 1-2 sentence pitch with location + CTA.\n - `meta_keywords` - ~200 chars, comma-separated (no spaces).\n - `facebook_title` - 55-60 chars, differ from `title` (more conversational).\n - `facebook_desc` - 110-125 chars, punchier than `meta_desc`.\n - Do NOT auto-set `facebook_image` (needs uploaded asset).\n6. **H1/H2 double-render trap:** if hero enabled AND `content` contains `<h1>`/`<h2>`, both render. Either set `h1`/`h2` fields and omit from `content`, or put in `content` and leave fields blank. Never both.\n7. **No max-width wrappers in `content` or `content_css`** on `profile_search_results` pages. BD's layout already provides the outer container; adding `max-width: 960px; margin: auto` double-constrains to a narrow strip. Let content flow at natural container width.\n8. `custom_html_placement` is only meaningful on `profile_search_results` (and `data_category`). Ignored on `content` pages.\n\n**SEO content for categories:** route to `createWebPage seo_type=profile_search_results` (NOT `updateTopCategory.desc` / `updateSubCategory.desc` - those are internal labels, not rendered).\n\n**`list_seo` EAV fields — auto-routed by the wrapper, no special handling.** Pass any field on `createWebPage` / `updateWebPage` directly; if it's an EAV-stored field (e.g. `hero_*`, `h1_*`, `h2_*`, `linked_post_category`, `disable_*`), the wrapper routes the write through `users_meta` automatically. Response includes an `eav_results` array confirming which EAV fields were written. Reads merge automatically via `getWebPage`/`listWebPages`. On `deleteWebPage`: BD does NOT cascade — run orphan cleanup per the top-level users_meta rule (`listUserMeta` filtered by `database=list_seo`+`database_id=<deleted seo_id>`, then `deleteUserMeta` each match).\n\n**See also:** `listWebPages`, `updateWebPage`, `createRedirect` (preserve SEO on slug changes).\n\n**Returns:** `{ status: \"success\", message: {...createdRecord}, auto_cache_refreshed: true|false, auto_cache_refresh_error?: \"...\" }` including `seo_id`. `auto_cache_refreshed` reports whether the automatic cache flush succeeded; if `false`, `auto_cache_refresh_error` explains why and the agent should retry `refreshSiteCache` manually once.",
8961
8961
  "tags": [
8962
8962
  "Pages"
8963
8963
  ],
@@ -9195,7 +9195,7 @@
9195
9195
  "hero_content_overlay_opacity": {
9196
9196
  "type": "string",
9197
9197
  "enum": ["0.0", "0.1", "0.2", "0.3", "0.4", "0.5", "0.6", "0.7", "0.8", "0.9", "1"],
9198
- "description": "Opacity of `hero_content_overlay_color` layer, 0.1 increments from `0.0` (transparent) to `1` (opaque). Admin UI labels 0-10. Default `0.4`.\n\n**EAV-STORED** (one of 18 `list_seo` fields stored in `users_meta`, not a direct column) - `createWebPage` writes correctly, but `updateWebPage` silently drops. On updates, write via `updateUserMeta`/`createUserMeta` with `database=list_seo`, `database_id=<seo_id>`, `key=hero_content_overlay_opacity`, then `refreshSiteCache`. Per top-level users_meta compound-identity rule, all meta calls require `database` + `database_id` together."
9198
+ "description": "Opacity of `hero_content_overlay_color` layer, 0.1 increments from `0.0` (transparent) to `1` (opaque). Admin UI labels 0-10. Default `0.4`. EAV-routed by the wrapper — pass on `updateWebPage` directly, no manual `updateUserMeta` needed."
9199
9199
  },
9200
9200
  "hero_top_padding": {
9201
9201
  "type": "string",
@@ -9556,7 +9556,7 @@
9556
9556
  "hero_content_overlay_opacity": {
9557
9557
  "type": "string",
9558
9558
  "enum": ["0.0", "0.1", "0.2", "0.3", "0.4", "0.5", "0.6", "0.7", "0.8", "0.9", "1"],
9559
- "description": "Opacity of `hero_content_overlay_color` layer, 0.1 increments from `0.0` (transparent) to `1` (opaque). Admin UI labels 0-10. Default `0.4`.\n\n**EAV-STORED** (one of 18 `list_seo` fields stored in `users_meta`, not a direct column) - `createWebPage` writes correctly, but `updateWebPage` silently drops. On updates, write via `updateUserMeta`/`createUserMeta` with `database=list_seo`, `database_id=<seo_id>`, `key=hero_content_overlay_opacity`, then `refreshSiteCache`. Per top-level users_meta compound-identity rule, all meta calls require `database` + `database_id` together."
9559
+ "description": "Opacity of `hero_content_overlay_color` layer, 0.1 increments from `0.0` (transparent) to `1` (opaque). Admin UI labels 0-10. Default `0.4`. EAV-routed by the wrapper — pass on `updateWebPage` directly, no manual `updateUserMeta` needed."
9560
9560
  },
9561
9561
  "hero_top_padding": {
9562
9562
  "type": "string",
@@ -457,24 +457,9 @@ Treat these as a single atomic recipe, not a menu. If you're tempted to skip one
457
457
 
458
458
  A single mistake here can cascade-destroy member data, plan metadata, and page settings that happen to share the same ID across unrelated tables.
459
459
 
460
- **WebPage users_meta field-update workaround (CRITICAL).** BD's `list_seo` table has a mix of DIRECT columns and EAV-stored fields in the `users_meta` table (keyed by `database=list_seo` + `database_id=<seo_id>` + `key=<field>`).
460
+ **WebPage EAV fields — auto-routed by the wrapper, no special handling needed.** BD's `list_seo` table mixes direct columns with EAV-stored fields in `users_meta`. BD's REST API itself silently ignores EAV fields on `updateWebPage`, but the MCP wrapper auto-detects them and routes the writes through `users_meta` for you. Just call `updateWebPage` with whatever fields you want to set; the response includes an `eav_results` array confirming which EAV fields were written. Reads merge automatically — `getWebPage` / `listWebPages` return the merged record at top level.
461
461
 
462
- - On CREATE: `createWebPage` writes ALL fields correctly - direct columns AND users_meta rows are seeded together.
463
- - On UPDATE: `updateWebPage` only writes the direct columns - **users_meta-stored fields are SILENTLY IGNORED** (the write succeeds but the new value doesn't persist, live-verified).
464
-
465
- **EAV-backed fields that MUST be updated via `updateUserMeta`** (not `updateWebPage`):
466
-
467
- `linked_post_category`, `linked_post_type`, `disable_preview_screenshot`, `disable_css_stylesheets`, `hero_content_overlay_opacity`, `hero_link_target_blank`, `hero_background_image_size`, `hero_link_size`, `hero_link_color`, `hero_content_font_size`, `hero_section_content`, `hero_column_width`, `h2_font_weight`, `h1_font_weight`, `h2_font_size`, `h1_font_size`, `hero_link_text`, `hero_link_url`.
468
-
469
- **This is a verified-live list; BD's `list_seo` EAV layer may include additional columns beyond these 18.** Reliable detection: after `updateWebPage`, re-GET and compare; if the value didn't persist, fall back to the EAV path. Any GET-returned `list_seo` field can be written via EAV.
470
-
471
- **Update workflow for each EAV field:**
472
-
473
- 1. `listUserMeta` with compound filter — send all three conditions server-side in one call: `property[]=database&property_value[]=list_seo&property_operator[]==&property[]=database_id&property_value[]=<seo_id>&property_operator[]==&property[]=key&property_value[]=<field>&property_operator[]==`. Returns the existing `meta_id` (or empty if unprovisioned).
474
- 2. If found -> `updateUserMeta(meta_id=..., database=list_seo, database_id=<seo_id>, value=<new value>)`.
475
- 3. If not found -> the WebPage doesn't have that EAV key provisioned. BD auto-seeds these on `createWebPage`; a missing row means the field is unsupported on this site. Confirm the field name; do NOT manually create a row (`createUserMeta` is intentionally not exposed as a tool).
476
-
477
- **Reads merge automatically:** `getWebPage` / `listWebPages` return the merged record including users_meta values at the top level. You do NOT need to query UserMeta separately for reads.
462
+ EAV-backed fields auto-routed (verified live): `linked_post_category`, `linked_post_type`, `disable_preview_screenshot`, `disable_css_stylesheets`, `hero_content_overlay_opacity`, `hero_link_target_blank`, `hero_background_image_size`, `hero_link_size`, `hero_link_color`, `hero_content_font_size`, `hero_section_content`, `hero_column_width`, `h2_font_weight`, `h1_font_weight`, `h2_font_size`, `h1_font_size`, `hero_link_text`, `hero_link_url`. Do NOT call `updateUserMeta` directly for these — `updateWebPage` is the right tool.
478
463
 
479
464
  **Delete cleanup:** `deleteWebPage` deletes the `list_seo` row but does NOT cascade-delete the corresponding users_meta rows. After `deleteWebPage(seo_id)`:
480
465
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "brilliant-directories-mcp",
3
3
  "mcpName": "io.github.brilliantdirectories/brilliant-directories-mcp",
4
- "version": "6.40.21",
4
+ "version": "6.40.23",
5
5
  "description": "Official MCP server for Brilliant Directories — manage members, posts, leads, reviews, and more.",
6
6
  "main": "index.js",
7
7
  "bin": {