brilliant-directories-mcp 5.3.0 → 5.3.2

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.
@@ -4447,7 +4447,7 @@
4447
4447
  }
4448
4448
  }
4449
4449
  },
4450
- "description": "Paginated enumeration of widget records. Read-only.\n\n**Use when:** discovering the reusable HTML components available for embedding in pages (`[widget=Name]` shortcode) or email templates.\n\n**Pagination:** cursor-based. Pass `limit` (default 25, max 100) and `page` token from the previous response's `next_page`. Do not assume integer offsets.\n\n**Filter/sort:** `property` + `property_value` + `property_operator` (`=`, `LIKE`, `>`, `<`, `>=`, `<=`) to filter; `order_column` + `order_type` (`ASC`/`DESC`) to sort.\n\n**See also:** `getWidget` (single record by ID).\n\n**Returns:** `{ status: \"success\", total, current_page, total_pages, next_page, prev_page, message: [...records] }`. Each record is the full resource object.\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4450
+ "description": "Paginated enumeration of widget records. Read-only.\n\n**Use when:** discovering the reusable HTML/CSS/JS components available for embedding in pages (via `[widget=Name]` shortcode), email templates, or for rendering on external sites via `renderWidget`. For fetching one specific widget by ID use `getWidget`.\n\n**Pagination:** cursor-based. Pass `limit` (default 25, max 100) and `page` token from the previous response's `next_page`. Do not assume integer offsets.\n\n**Filter/sort:** `property` + `property_value` + `property_operator` (`=`, `LIKE`, `>`, `<`, `>=`, `<=`) to filter; `order_column` + `order_type` (`ASC`/`DESC`) to sort. Useful filter: `widget_viewport=front` to list only public-facing widgets.\n\n**See also:** `getWidget` (single by ID), `createWidget` (add new), `renderWidget` (get rendered output instead of raw source).\n\n**Returns:** `{ status: \"success\", total, current_page, total_pages, next_page, prev_page, message: [...records] }`. Each record has all the widget fields below.\n\n\n**Widget object fields (from BD support article 12000108056):**\n\n| Field | Type | Description |\n|---|---|---|\n| `widget_id` | integer | Primary key (read-only) |\n| `widget_name` | string | Widget name/label — REQUIRED on create; unique per site |\n| `widget_type` | string | Widget classification (default: `Widget`) |\n| `widget_data` | text | Widget HTML content |\n| `widget_style` | text | Widget CSS styles |\n| `widget_javascript` | text | Widget JavaScript code |\n| `widget_settings` | text | Configuration (JSON or serialized) |\n| `widget_values` | text | Widget variable values |\n| `widget_class` | string | CSS class names applied to container |\n| `widget_viewport` | string | Where widget appears: `front`, `admin`, `both` |\n| `widget_html_element` | string | Container element (default: `div`) |\n| `div_id` | string | HTML ID attribute for container |\n| `short_code` | string | Shortcode reference for this widget |\n| `bootstrap_enabled` | integer | `1` if Bootstrap framework loaded |\n| `ssl_enabled` | integer | `1` if SSL/HTTPS required |\n| `mobile_enabled` | integer | `1` if mobile viewport enabled |\n| `file_type` | string | File type of the widget |\n| `revision_timestamp` | timestamp | Last modified (auto-updated) |\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4451
4451
  }
4452
4452
  },
4453
4453
  "/api/v2/data_widgets/get/{widget_id}": {
@@ -4479,7 +4479,7 @@
4479
4479
  }
4480
4480
  }
4481
4481
  },
4482
- "description": "Fetch a single widget record. Read-only.\n\n**Use when:** fetching one widget's HTML source for edit.\n\n**Required:** `widget_id`.\n\n**See also:** `listWidgets` (enumerate many).\n\n**Returns:** `{ status: \"success\", message: [{...record}] }` — the `message` array contains 1 record when found. Empty or HTTP 404 when not found.\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4482
+ "description": "Fetch a single widget record by `widget_id`. Returns the raw HTML/CSS/JS source. Read-only.\n\n**Use when:** you have a `widget_id` (from `listWidgets` or admin) and want the widget's SOURCE code to edit or audit. For the RENDERED output (with template variables expanded), use `renderWidget` instead.\n\n**Required:** `widget_id` (path parameter).\n\n**See also:** `listWidgets` (enumerate), `renderWidget` (rendered output), `updateWidget` (modify).\n\n**Returns:** `{ status: \"success\", message: [{...record}] }` — the `message` array contains 1 record with all widget fields (`widget_data` = HTML, `widget_style` = CSS, `widget_javascript` = JS, plus metadata).\n\n\n**Widget object fields (from BD support article 12000108056):**\n\n| Field | Type | Description |\n|---|---|---|\n| `widget_id` | integer | Primary key (read-only) |\n| `widget_name` | string | Widget name/label — REQUIRED on create; unique per site |\n| `widget_type` | string | Widget classification (default: `Widget`) |\n| `widget_data` | text | Widget HTML content |\n| `widget_style` | text | Widget CSS styles |\n| `widget_javascript` | text | Widget JavaScript code |\n| `widget_settings` | text | Configuration (JSON or serialized) |\n| `widget_values` | text | Widget variable values |\n| `widget_class` | string | CSS class names applied to container |\n| `widget_viewport` | string | Where widget appears: `front`, `admin`, `both` |\n| `widget_html_element` | string | Container element (default: `div`) |\n| `div_id` | string | HTML ID attribute for container |\n| `short_code` | string | Shortcode reference for this widget |\n| `bootstrap_enabled` | integer | `1` if Bootstrap framework loaded |\n| `ssl_enabled` | integer | `1` if SSL/HTTPS required |\n| `mobile_enabled` | integer | `1` if mobile viewport enabled |\n| `file_type` | string | File type of the widget |\n| `revision_timestamp` | timestamp | Last modified (auto-updated) |\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4483
4483
  }
4484
4484
  },
4485
4485
  "/api/v2/data_widgets/create": {
@@ -4538,7 +4538,7 @@
4538
4538
  }
4539
4539
  }
4540
4540
  },
4541
- "description": "Create a new widget record. Writes live data.\n\n**Use when:** building a new reusable HTML block. Rare — usually configured via BD admin UI.\n\n**Required:** `widget_name`.\n\n**Enums:** `widget_viewport`: `front`, `admin`, `both`; `bootstrap_enabled`: `0`, `1`.\n\n**See also:** `updateWidget` (modify existing).\n\n**Writes live data:** confirm intent with the user for bulk operations. Changes are immediately visible on the live site.\n\n**Returns:** `{ status: \"success\", message: {...createdRecord} }` — includes the server-assigned ID (e.g., `user_id`, `post_id`). Use this ID for follow-up operations.\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4541
+ "description": "Create a new widget (reusable HTML/CSS/JS component). Writes live data.\n\n**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.\n\n**Required:** `widget_name` (unique per site).\n\n**Common fields on create:**\n- `widget_data` — the HTML content\n- `widget_style` — CSS (scoped to the widget via `widget_class` or `div_id`)\n- `widget_javascript` — JS (runs when widget is rendered on a page)\n- `widget_viewport` — `front` (public), `admin` (admin panel only), or `both`\n- `bootstrap_enabled=1` — ensures Bootstrap framework loaded when this widget is rendered\n- `widget_html_element` — wrapper element (default `div`)\n\n**See also:** `updateWidget` (modify existing), `listWidgets` (check if name is taken first), `renderWidget` (test the output after create).\n\n**Writes live data:** the widget is available immediately but does nothing until referenced by a `[widget=Name]` shortcode on a page/email OR rendered directly via `renderWidget`.\n\n**Returns:** `{ status: \"success\", message: {...createdRecord} }` including the new `widget_id`.\n\n\n**Widget object fields (from BD support article 12000108056):**\n\n| Field | Type | Description |\n|---|---|---|\n| `widget_id` | integer | Primary key (read-only) |\n| `widget_name` | string | Widget name/label — REQUIRED on create; unique per site |\n| `widget_type` | string | Widget classification (default: `Widget`) |\n| `widget_data` | text | Widget HTML content |\n| `widget_style` | text | Widget CSS styles |\n| `widget_javascript` | text | Widget JavaScript code |\n| `widget_settings` | text | Configuration (JSON or serialized) |\n| `widget_values` | text | Widget variable values |\n| `widget_class` | string | CSS class names applied to container |\n| `widget_viewport` | string | Where widget appears: `front`, `admin`, `both` |\n| `widget_html_element` | string | Container element (default: `div`) |\n| `div_id` | string | HTML ID attribute for container |\n| `short_code` | string | Shortcode reference for this widget |\n| `bootstrap_enabled` | integer | `1` if Bootstrap framework loaded |\n| `ssl_enabled` | integer | `1` if SSL/HTTPS required |\n| `mobile_enabled` | integer | `1` if mobile viewport enabled |\n| `file_type` | string | File type of the widget |\n| `revision_timestamp` | timestamp | Last modified (auto-updated) |\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4542
4542
  }
4543
4543
  },
4544
4544
  "/api/v2/data_widgets/update": {
@@ -4584,7 +4584,7 @@
4584
4584
  }
4585
4585
  }
4586
4586
  },
4587
- "description": "Update an existing widget record by ID. Fields omitted are untouched. Writes live data.\n\n**Use when:** editing widget HTML or settings.\n\n**Required:** `widget_id`.\n\n**See also:** `createWidget` (add new), `deleteWidget` (remove permanently).\n\n**Writes live data:** confirm intent with the user for bulk operations. Changes are immediately visible on the live site.\n\n**Returns:** `{ status: \"success\", message: {...updatedRecord} }` — the full updated record after changes applied.\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4587
+ "description": "Update an existing widget by `widget_id`. Fields omitted are untouched. Writes live data.\n\n**Use when:** editing widget HTML (`widget_data`), CSS (`widget_style`), JS (`widget_javascript`), or metadata. Any page or email referencing this widget via `[widget=Name]` shortcode will render the updated content on next view (BD caches server-side — `refreshSiteCache` may be needed for immediate propagation in some themes).\n\n**Required:** `widget_id`.\n\n**Common edits:**\n- Content: `widget_data`, `widget_style`, `widget_javascript`\n- Visibility: `widget_viewport` (`front`/`admin`/`both`)\n- Framework: `bootstrap_enabled`, `mobile_enabled`, `ssl_enabled`\n\n**See also:** `createWidget` (add new), `deleteWidget` (remove), `renderWidget` (preview post-edit output).\n\n**Writes live data:** edits go live immediately for new page loads.\n\n**Returns:** `{ status: \"success\", message: {...updatedRecord} }`.\n\n\n**Widget object fields (from BD support article 12000108056):**\n\n| Field | Type | Description |\n|---|---|---|\n| `widget_id` | integer | Primary key (read-only) |\n| `widget_name` | string | Widget name/label — REQUIRED on create; unique per site |\n| `widget_type` | string | Widget classification (default: `Widget`) |\n| `widget_data` | text | Widget HTML content |\n| `widget_style` | text | Widget CSS styles |\n| `widget_javascript` | text | Widget JavaScript code |\n| `widget_settings` | text | Configuration (JSON or serialized) |\n| `widget_values` | text | Widget variable values |\n| `widget_class` | string | CSS class names applied to container |\n| `widget_viewport` | string | Where widget appears: `front`, `admin`, `both` |\n| `widget_html_element` | string | Container element (default: `div`) |\n| `div_id` | string | HTML ID attribute for container |\n| `short_code` | string | Shortcode reference for this widget |\n| `bootstrap_enabled` | integer | `1` if Bootstrap framework loaded |\n| `ssl_enabled` | integer | `1` if SSL/HTTPS required |\n| `mobile_enabled` | integer | `1` if mobile viewport enabled |\n| `file_type` | string | File type of the widget |\n| `revision_timestamp` | timestamp | Last modified (auto-updated) |\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4588
4588
  }
4589
4589
  },
4590
4590
  "/api/v2/data_widgets/delete": {
@@ -4624,14 +4624,14 @@
4624
4624
  }
4625
4625
  }
4626
4626
  },
4627
- "description": "Permanently delete a widget record by ID. Destructive — cannot be undone via API.\n\n**Use when:** removing an unused widget. Any `[widget=Name]` shortcodes referencing it on pages/emails will render as empty or broken — audit first.\n\n**Required:** `widget_id`.\n\n**See also:** `updateWidget` (modify without removing).\n\n**Destructive:** confirm intent with the user before bulk use. No soft-delete via API — records removed are not recoverable.\n\n**Returns:** `{ status: \"success\", message: \"record was deleted\" }`. No body beyond the confirmation string.\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4627
+ "description": "Permanently delete a widget by `widget_id`. Destructive — cannot be undone via API.\n\n**Use when:** removing an unused widget. For \"disable without deleting\" use `updateWidget` with `widget_viewport=admin` (hides from public pages) — preserves the source for later use.\n\n**Destructive caveat:** any page or email using `[widget=Name]` shortcode referencing the deleted widget will render as empty or broken at that spot. Audit with `listWidgets` + check page content for shortcodes referencing this widget's `widget_name` or `short_code` before deleting.\n\n**Required:** `widget_id`.\n\n**See also:** `updateWidget` with `widget_viewport=admin` (reversible hide).\n\n**Returns:** `{ status: \"success\", message: \"data_widgets record was deleted\" }`.\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._"
4628
4628
  }
4629
4629
  },
4630
4630
  "/api/v2/data_widgets/render": {
4631
4631
  "post": {
4632
4632
  "operationId": "renderWidget",
4633
4633
  "summary": "Render a widget to HTML",
4634
- "description": "Returns rendered HTML output with all template variables processed.\n\n**Use when:** fetching the RENDERED HTML output of a widget (with all shortcodes/tokens expanded) rather than its raw source. Useful for previewing in an external tool or scraping a widget's current state.\n\n**Required:** `widget_id`.\n\n**Parameter interactions:**\n- Returns rendered HTML for the named widget — side effect: may execute widget-specific PHP (database queries, cache lookups). Use carefully in loops\n\n**Returns:** `{ status: \"success\"|\"error\", message: ... }` — BD's standard response envelope.\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._",
4634
+ "description": "Return the RENDERED HTML output of a widget with all template variables processed. Read-only from the widget's perspective, but may have side effects (see below).\n\n**Use when:** previewing a widget's output during editing, embedding rendered BD widget content on an EXTERNAL site (the main real-world use case — render-on-request for external embeds), or scraping a widget's current state for caching/screenshot purposes. For fetching the raw SOURCE code instead, use `getWidget`.\n\n**Required:** either `widget_id` OR `widget_name` (pass one — both are supported per BD docs for lookup).\n\n**Prerequisite from BD docs:** *\"The widget needs to be customized to get the widget output.\"* — if the widget hasn't been customized/saved at least once in the BD admin, this endpoint may return empty output. Verify with `getWidget` first if rendering returns nothing.\n\n**Side effects:** rendering executes widget-specific PHP server-side — may trigger database queries, cache lookups, third-party API calls, or counter increments depending on what the widget does. Use carefully inside loops or batch operations.\n\n**See also:** `getWidget` (raw source), `listWidgets` (discover widgets), `updateWidget` (edit then re-render).\n\n**Returns (distinct from standard envelope):**\n```\n{\n \"status\": \"success\",\n \"message\": \"Widget rendered successfully\",\n \"name\": \"My Widget Name\",\n \"output\": \"<div class=\\\"widget\\\">...fully rendered HTML...</div>\"\n}\n```\nNote: `name` and `output` are TOP-LEVEL siblings of `message`, NOT nested inside it. The `output` field contains the full rendered HTML including any `widget_data` HTML + expanded template tokens. CSS and JS declared on the widget are NOT included in `output` — fetch them separately via `getWidget` if needed for external embedding.\n\n**Error response shape:** `{ \"status\": \"error\", \"message\": \"Widget not found\", \"name\": \"\", \"output\": \"\" }`. When the widget doesn't exist or isn't customized, expect empty `name` and `output` strings.\n\n**Example use case — rendering a BD widget on an external site:**\n```\n1. createWidget on BD with your HTML/CSS/JS\n2. On external site, fetch via POST /api/v2/data_widgets/render with widget_id\n3. Parse the response's 'output' field → inject into external page DOM\n4. If you need the CSS/JS, fetch via getWidget and include separately\n```\n\n_Auth: `X-Api-Key` header. Rate limit: 100 req/60s (on 429, back off 60s). Errors: `{ \"status\": \"error\", \"message\": \"...\" }` with standard HTTP codes._",
4635
4635
  "tags": [
4636
4636
  "Widgets"
4637
4637
  ],
@@ -4641,12 +4641,13 @@
4641
4641
  "application/x-www-form-urlencoded": {
4642
4642
  "schema": {
4643
4643
  "type": "object",
4644
- "required": [
4645
- "widget_id"
4646
- ],
4647
4644
  "properties": {
4648
4645
  "widget_id": {
4649
4646
  "type": "integer"
4647
+ },
4648
+ "widget_name": {
4649
+ "type": "string",
4650
+ "description": "Alternative to `widget_id` — pass either one. Widget name lookup is case-sensitive and must match exactly."
4650
4651
  }
4651
4652
  }
4652
4653
  }
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": "5.3.0",
4
+ "version": "5.3.2",
5
5
  "description": "Official MCP server for Brilliant Directories — manage members, posts, leads, reviews, and more.",
6
6
  "main": "index.js",
7
7
  "bin": {