Skip to main content
Glama
brilliant-directories-mcp

brilliant-directories-mcp

Official

createWidget

Create reusable HTML/CSS/JS widgets to embed on pages or email templates via shortcodes, supporting bulk imports, migrations, or scripted generation with automatic cache refresh.

Instructions

Create a widget - Create a new widget (reusable HTML/CSS/JS component). Writes live data.

Cache refresh is automatic. Response includes auto_cache_refreshed: true after successful writes, or auto_cache_refresh: "scheduled" when the refresh is queued to run shortly together with other writes; both are normal and need no refreshSiteCache call. Only if auto_cache_refreshed: false, check auto_cache_refresh_error and retry refreshSiteCache once.

Use when: programmatically adding a new reusable block to embed as <div>[widget=Name]</div> on pages or email templates (a bare shortcode in a page editor is wrapped in <p> on the next admin save). Rare in practice - widgets are usually created via BD admin UI where the editor supports live preview. API creation is useful for bulk imports, cross-site migrations, or scripted widget generation.

Required: widget_name (should be unique per site).

widget_name format: alphanumeric + spaces + hyphens + plus + underscores only ([A-Za-z0-9 -+_]+). Special chars (slashes, dots, ampersands, quotes, brackets, etc.) break [widget=Name] shortcode resolution and are runtime-rejected by the wrapper. Examples: Mortgage Calculator, Service-Card, Email_Validator_v2, C++ Course.

Pre-check before create: BD does NOT enforce uniqueness on widget_name. Duplicates break [widget=Name] shortcode resolution - which widget renders at the shortcode is undefined. Do a server-side filter-find: listWidgets property=widget_name property_value=<proposed> property_operator==. Zero rows = name free; a site row = taken. An is_default true row is BD's own widget: creating its exact name replaces it on this site, only to customise it (e.g. a hero hook getDesignSettings names). Do NOT paginate unfiltered lists looking for the name - on sites with hundreds of custom widgets that burns rate limit for nothing.

On collision (auto-suffix flow): if the proposed name is taken, append -v2 and re-check. Still taken? Try -v3, -v4, ... up through -v10. First free suffix wins. Only if all 10 are taken, ask the user for a different base name. Never silently create a duplicate.

Route by type BEFORE writing values: decide what each piece of code is, then put it in the matching field — HTML → widget_data, CSS → widget_style, JS → widget_javascript. A self-contained block with all three concatenated into widget_data will save successfully but silently break: widget_data strips backslashes on render, mangling regex literals (\d, \s), string escapes (\n, \t), and unicode escapes (\u0022). The other two fields do not strip backslashes. Split by type from the start.

Common fields on create:

  • widget_data - the HTML content

  • widget_style - CSS (scoped to the widget via widget_class or div_id)

  • widget_javascript - JS (runs when widget is rendered on a page)

  • widget_html_element - wrapper element (default div)

See also: updateWidget (modify existing), listWidgets (check if name is taken first), getWidget (verify storage after create).

Writes live data: the widget is available immediately but does nothing until referenced by a [widget=Name] shortcode on a page or email template.

Returns: { status: "success", message: {...createdRecord}, auto_cache_refreshed?: true|false, auto_cache_refresh?: "scheduled", auto_cache_refresh_error?: "..." } including the new widget_id.

Post-create verification (recommended, especially when uncertain about routing): call getWidget once to confirm widget_data contains only HTML, widget_style contains your CSS, and widget_javascript contains your JS wrapped in <script>...</script>. If anything landed in the wrong field, call updateWidget to relocate before the user tests the widget. Proactive relocation here is correct and does NOT violate the "don't relocate without user-reported breakage" rule on updateWidget — that rule applies to subsequent edits, not to self-correcting your own just-created record.

For the full field list, see listWidgets.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "widget_name": "<widget_name>"
    },
    "name": "createWidget"
  }
}

Input Schema

NameRequiredDescriptionDefault
copy_ofNowidget_name of a widget to start from, BD's or this site's: the new widget gets its code, with your replace edits or whole fields applied. For a variant of an existing widget (other members, posts, order or count).
replaceNoWith copy_of: change part of the copied code: [{field, find, with}]. If find occurs more than once, add nth (1 = first) or all:true.
own_formNotrue: the required being added belongs to this widget's own form, not the homepage hero search
own_iconsNotrue: an icon in the hero search that the search recipe cannot place (a field holding two inputs, such as a price range)
widget_dataNoHTML only. No `<style>`, no `<script>` — render strips backslashes here (`\d`→`d`, `\n`→`n`, `\t`→`t`, `\\`→`\`). JS with stripped escapes throws SyntaxError on parse — every handler unbound, widget renders but no clicks/inputs work. Fix: relocate to `widget_javascript`, do not rewrite JS to avoid backslashes. Put CSS in `widget_style`, JS in `widget_javascript`. See **Rule: Widget code fields**.
widget_nameYes
widget_styleNoRaw CSS. No `<style>` wrapper — BD wraps at render. Wholly-wrapped value: outer wrapper stripped on storage; concatenated wrappers not stripped. See **Rule: Widget code fields**.
widget_javascriptNoJS with `<script>...</script>` wrapper required. BD does not auto-wrap; unwrapped content renders as inert text. No backslash-strip on this field — regex literals (`\d`, `\w`, `\s`) AND string escapes (`\n`, `\t`, `\\`) survive intact. See **Rule: Widget code fields**.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv6.59.691
    • addedInput schema / properties / own_form
      Added value: +{
      +  "description": "true: the required being added belongs to this widget's own form, not the homepage hero search",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / own_icons
      Added value: +{
      +  "description": "true: an icon in the hero search that the search recipe cannot place (a field holding two inputs, such as a price range)",
      +  "type": "boolean"
      +}
  2. Changed2 schema fields changedv6.59.638
    • addedInput schema / properties / copy_of
      Added value: +{
      +  "description": "widget_name of a widget to start from, BD's or this site's: the new widget gets its code, with your replace edits or whole fields applied. For a variant of an existing widget (other members, posts, order or count).",
      +  "type": "string"
      +}
    • addedInput schema / properties / replace
      Added value: +{
      +  "description": "With copy_of: change part of the copied code: [{field, find, with}]. If find occurs more than once, add nth (1 = first) or all:true.",
      +  "items": {
      +    "properties": {
      +      "all": {
      +        "type": "boolean"
      +      },
      +      "field": {
      +        "enum": [
      +          "widget_data",
      +          "widget_style",
      +          "widget_javascript"
      +        ],
      +        "type": "string"
      +      },
      +      "find": {
      +        "type": "string"
      +      },
      +      "nth": {
      +        "minimum": 1,
      +        "type": "integer"
      +      },
      +      "with": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "field",
      +      "find",
      +      "with"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  3. Changed2 schema fields changedv6.58.612
    • removedInput schema / properties / bootstrap_enabled
      Removed value: -{
      -  "enum": [
      -    0,
      -    1
      -  ],
      -  "type": "integer"
      -}
    • removedInput schema / properties / widget_viewport
      Removed value: -{
      -  "enum": [
      -    "front",
      -    "admin",
      -    "both"
      -  ],
      -  "type": "string"
      -}
  4. Addedv6.55.39
  5. Removedv6.55.19
  6. Addedv6.49.4
  7. Removedv6.48.1
  8. Addedv6.0.19
  9. Removedv6.0.18
  10. Changed1 schema field changed
    • changedInput schema / properties / widget_data / description
      Previous value: -"HTML content Pass raw HTML — do NOT wrap in `<![CDATA[...]]>`, do NOT escape as `&lt;` / `&gt;`, and do NOT include tool-call scaffolding tags (e.g. `<parameter name=\"...\">...</parameter>`, `<invoke>`, `<function_calls>`). BD stores the field value verbatim; any wrapper / escape / scaffolding renders as literal visible text."New value: +"Widget HTML content. **Widget-exempt from universal sanitization rules** - accepts arbitrary HTML/CSS/JS/iframes/PHP (widgets legitimately need JS and scoped CSS; anyone with API permission to write widgets already has admin capability). Supports PHP variables and `%%%template_tokens%%%`."
  11. Addedv6.0.7
  12. Removed
  13. First observedv1.0.0

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations it discloses a lot: automatic cache refresh with response flags, no uniqueness enforcement, a defined collision/auto-suffix flow, backslash-stripping that breaks JS in widget_data, and a recommended post-create verification step. This is well beyond what the annotations convey. Minor gap: it doesn't state auth/permission requirements explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Content is front-loaded with purpose and clearly sectioned with bold headers, so it scannable despite length. It's verbose and has some duplication (backslash stripping repeated in both body and schema), but for a mutation tool with real footguns most sentences earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition covers the full lifecycle: pre-check uniqueness, name format, field routing, cache-refresh response shape, and post-create verification. Combined with the 88%-covered schema, an agent has everything needed to call it correctly and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 88%, yet the description adds real meaning the schema lacks for widget_name (the [A-Za-z0-9 -+_]+ format, examples, uniqueness pre-check via listWidgets) and explains the routing rule for widget_data/style/javascript. It doesn't fully specify copy_of/replace behavior beyond the schema's own text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The definition opens with a specific verb+resource: 'Create a new widget (reusable HTML/CSS/JS component). Writes live data.' It explicitly distinguishes create from update/list/get in the 'See also' line, so an agent can tell it apart from siblings without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('programmatically adding a new reusable block... bulk imports, cross-site migrations, scripted generation') and when-not ('Rare in practice - widgets are usually created via BD admin UI'). It also names alternatives for adjacent tasks: updateWidget, listWidgets, getWidget.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools