Skip to main content
Glama
brilliantdirectories

brilliant-directories-mcp

Official
by brilliantdirectories
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
JavaScript
Remote

createWidget

Add a reusable HTML, CSS, and JS widget to a directory site by supplying a unique name, so it can be embedded via shortcode on pages or emails.

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; no manual refreshSiteCache call needed. If auto_cache_refreshed: false, check auto_cache_refresh_error and retry refreshSiteCache once.

Use when: programmatically adding a new reusable block to embed via [widget=Name] shortcode on pages or email templates. 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; >=1 row = taken. 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_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.

Input Schema

NameRequiredDescriptionDefault
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.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"
-}
  2. Addedv6.55.39
  3. Removedv6.55.19
  4. Addedv6.49.4
  5. Removedv6.48.1
  6. Addedv6.0.19
  7. Removedv6.0.18
  8. 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%%%`."
  9. Addedv6.0.7
  10. Removed
  11. First observedv1.0.0

TDQS

A4.7/5.0
Behavior4/5

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true) by disclosing that writes go live immediately, that cache refresh is automatic with an auto_cache_refresh_error fallback path, and that widget_name uniqueness is NOT enforced server-side. It does not, however, state auth/permission requirements or rate-limit characteristics, which would matter for an openWorld write tool.

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?

Bold headers and front-loaded ordering make it scannable, and every section addresses a real failure mode. It is nonetheless long, with the backslash-strip hazard restated in the description and again in the schema, and the closing paragraph spends several sentences adjudicating an updateWidget rule rather than describing this tool.

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?

For a 4-parameter write tool with no output schema, the definition covers inputs, name-format constraints, pre-check, collision handling, return shape, and a verification step. Nothing an agent needs to call it correctly is missing.

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

Parameters5/5

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

Schema coverage is 75%, and the description fills the gap substantively: it gives the widget_name character-class regex with concrete examples, explains that widget_data strips backslashes (with the regex/escape failure mode), that widget_style must be unwrapped CSS, and that widget_javascript requires a <script> wrapper. This routing guidance is meaning well beyond the schema 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?

States a specific verb and resource ('Create a new widget (reusable HTML/CSS/JS component)') and immediately distinguishes scope from siblings such as updateWidget, getWidget and listWidgets. An agent can tell what this does without opening the schema.

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?

Explicit 'Use when' clause, an admission that the operation is rare in practice with the UI alternative named, a mandatory pre-check procedure (server-side filter-find via listWidgets), an explicit anti-pattern (do not paginate unfiltered lists), and a deterministic collision-resolution flow. Alternatives and when-not-to-use are both covered.

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