brilliant-directories-mcp 6.2.0 → 6.3.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.
package/index.js CHANGED
@@ -690,9 +690,31 @@ async function main() {
690
690
  ``,
691
691
  `Rate limit: 100 req/60s (raisable to 1000/min via BD support). Each call takes ~1-3 seconds round-trip, so bulk jobs add up to real minutes — tell the user an honest estimate upfront (e.g. 500 records ≈ 10-15 minutes). On 429, wait 60s+ before retrying — BD's window resets every 60s, so shorter backoffs just burn failing calls. Call \`verifyToken\` before large jobs to confirm the key works and check headroom, avoiding half-run imports.`,
692
692
  ``,
693
- `Pagination (all \`list*\` and \`search*\` endpoints only): \`limit\` (default 25, max 100) + \`page\` as an opaque cursor token taken from the previous response's \`next_page\` field. Never numeric offsets like \`page=2\`. Single-record \`get*\`, create/update/delete don't paginate.`,
693
+ `API key permissions are per-endpoint, toggled in BD Admin → Developer Hub on the key. A 403 "API Key does not have permission to access this endpoint" means THIS key is missing THIS endpoint. Asymmetry is normal — e.g. \`createUser\` may be enabled (it silently auto-creates missing top categories via \`profession_name\`) while \`listTopCategories\` is not. \`verifyToken\` confirms the key is valid but does NOT validate the endpoint set, so a multi-endpoint job can pass \`verifyToken\` and still 403 mid-run. On a 403, tell the user the exact denied endpoint and ask them to enable it in Developer Hub; don't substitute a different endpoint. (Distinct from an invalid/revoked key, which fails \`verifyToken\` outright.)`,
694
+ ``,
695
+ `Pagination (all \`list*\` and \`search*\` endpoints only): \`limit\` (default 25, max 100) + \`page\` as an opaque cursor token taken from the previous response's \`next_page\` field. Never numeric offsets like \`page=2\`. Single-record \`get*\`, create/update/delete don't paginate. Gotchas: (1) \`next_page\` is often non-empty even on the last page — stop when \`current_page >= total_pages\` OR \`message.length === 0\`, NOT when \`next_page === ""\`; (2) \`total\` can drift across consecutive calls on active sites — treat it as approximate; (3) don't change \`limit\` mid-traversal — \`total_pages\` is computed from the cursor's baked-in page size, and changing \`limit\` on an existing cursor miscounts pages; restart from a fresh cursor when changing page size.`,
696
+ ``,
697
+ `Filter properties (\`property\` / \`property_value\` / \`property_operator\`) must reference ACTUAL field names on the resource — never guess. If you don't know what's filterable, call the resource's fields endpoint first (\`getUserFields\`, \`getSingleImagePostFields\`, \`getMultiImagePostFields\`, etc.) which returns the authoritative field list for that site (includes custom fields). Two important BD behaviors on \`list*\` endpoints: (1) the error envelope \`{status: "error", message: "<X> not found", total: 0}\` is returned for BAD FILTERS (nonexistent \`property\` or \`order_column\`), BAD CURSORS, AND LEGITIMATELY EMPTY RESULTS — all indistinguishable. Treat it as "zero results + maybe malformed input"; don't assume the endpoint is broken. Observed variants of \`<X>\`: \`user\`, \`record\`, \`data_categories\`, and other internal table names. (2) Right now, the RELIABLE operator is \`=\` (exact match, case-insensitive on string columns via MariaDB's default \`utf8_general_ci\` collation). Other operators (\`LIKE\`, \`!=\`, \`in\`, \`not_in\`, \`not_like\`, \`is_null\`, \`is_not_null\`, \`between\`) are listed in the schema but behavior varies per endpoint — \`LIKE\` on \`email\` returned "user not found" even with \`%foo%\` wildcards in live tests. An expanded operator set (including full LIKE support) is in QA and shipping shortly. For now: use \`=\` for filters, or enumerate unfiltered with client-side filtering. Do NOT rely on \`LIKE\` returning results across columns.`,
698
+ ``,
699
+ `Filter by category/taxonomy = filter by ID, not name. \`listUsers\` takes \`property=profession_id\` (a numeric \`list_professions\` row), not a category name string. If the caller gave you a category name, chain: \`listTopCategories\` → match \`name\` → grab \`profession_id\` → then \`listUsers\`. Same principle for subscription/plan filters: use \`subscription_id\`, discover via \`listMembershipPlans\`. For sub-category filtering on users, prefer \`listMemberSubCategoryLinks\` filtered by \`service_id\` to get \`user_id\`s, then fetch those users — don't try to LIKE-match the CSV \`service\` column on users.`,
700
+ ``,
701
+ `Multi-condition filters use array syntax: \`property[]=x&property_value[]=1&property[]=y&property_value[]=2&property_operator[]=OR&property_logic[]==\`. Use for \`users_meta\` OR-across-values queries (multiple values for the same meta key) or any multi-field OR/AND filter. NOTE: the MCP tool schema exposes only the single-value \`property\`/\`property_value\`/\`property_operator\` parameters — to send array-style filters via this MCP, you need to construct the request directly (the array params won't round-trip through the tool's single-value schema). For simple AND of 2 conditions, prefer narrowing with the primary filter and post-filtering results client-side.`,
702
+ ``,
703
+ `Post category values are per-post-type dropdowns configured by the site admin — NOT a global taxonomy, and there is no \`createPostCategory\` tool. Before setting \`post_category\` on a post create/update, call \`getSingleImagePostFields\` (by \`form_name\`) or \`getPostTypeCustomFields\` (by \`data_id\`) and read the allowed values from the schema. Pass only values that appear there. If the user names a category not in the list, ask whether to pick the closest existing option or have them add it in BD admin first — don't invent values. (This is different from member categories, which ARE created via the API via \`createTopCategory\`/\`createSubCategory\` or auto-created by \`createUser\`.)`,
704
+ ``,
705
+ `Lead routing — when to override auto-match: \`createLead\` accepts \`users_to_match\` (comma-separated member IDs or emails, mixed allowed). When set, BD bypasses the normal category/location/service-area auto-matching and routes the lead to ONLY those members. Use when the caller already knows who should receive the lead (external routing logic, round-robin assignment, VIP escalation). Typically paired with \`auto_match=1\` (runs the match step inline) and \`send_lead_email_notification=1\` (fires the matched-member email) — without the email flag, matches are recorded silently.`,
694
706
  ``,
695
707
  `Writes are live and immediately visible on the public site. Confirm before any destructive or mass-modification operation. For reversible removal, prefer \`updateUser\` with \`active=3\` (Canceled) over \`deleteUser\` — the record stays queryable and can be reactivated.`,
708
+ ``,
709
+ `Never wrap ANY field value in \`<![CDATA[...]]>\`, and never entity-escape HTML as \`&lt;\`/\`&gt;\`. BD stores every field verbatim — wrappers and escapes get saved as literal text. For HTML-accepting fields (\`about_me\`, \`post_content\`, \`group_desc\`, \`widget_data\`, \`email_body\`, page \`content\`, etc.) pass raw HTML directly. For plain-text fields, pass plain text. No XML conventions, no HTML-entity encoding.`,
710
+ ``,
711
+ `Write-time params ECHO on reads. Fields like \`profession_name\`, \`services\`, \`credit_action\`, \`credit_amount\`, \`member_tag_action\`, \`member_tags\`, \`create_new_categories\`, \`auto_image_import\` appear on read responses when they were set on a recent write — they are NOT canonical state, just residual input from the last write. Canonical state lives elsewhere: \`profession_id\` + \`profession_schema\` (top category), \`services_schema\` (sub-categories), \`credit_balance\` (current balance as dollar-formatted string like \`"$35.00"\`), \`tags\` array (current tags). Don't build logic that reads these echo fields as truth.`,
712
+ ``,
713
+ `Response typing quirks to defend against: (1) BD returns primary keys and counts as STRINGIFIED integers (\`user_id: "1"\`, \`total: "114"\`) but pagination positions (\`current_page\`, \`total_pages\`) as real NUMBERS — coerce before comparison. (2) Several empty/absent collection-like fields come back as the literal boolean \`false\` instead of \`null\`/\`[]\`/\`{}\` — observed on user records: \`card_info\`, \`tags\`, \`photos_schema\`, \`services_schema\`, \`profession_schema\`, \`transactions\`, \`subscription_details\`, \`user_clicks_schema.clicks\`. Check \`!x || x === false || (Array.isArray(x) && x.length === 0)\` before accessing nested properties. (3) \`filename_hidden\` on user records is NOT reliable — on legacy records it can contain a different member's slug; always use \`filename\` for profile URLs, never \`filename_hidden\`. (4) \`last_login\` = \`"1970-01-01T00:00:00+00:00"\` means never-logged-in, not an actual 1970 login. (5) Unpaid invoice \`datepaid\` = \`"0000-00-00 00:00:00"\` (MariaDB zero-date) — don't parse as ISO; treat \`datepaid.startsWith("0000")\` as "unpaid." (6) \`credit_balance\` is a dollar-formatted string like \`"$35.00"\` or \`"-$24.50"\` (negative allowed — BD doesn't reject deducts that exceed current balance); parse with \`/^(-)?\\$(\\d+\\.\\d{2})$/\`.`,
714
+ ``,
715
+ `Sensitive fields present in read responses: user records include \`password\` (bcrypt hash), \`token\` (member auth token), and \`cookie\` (session value) — redact before logging responses. There are TWO one-char-different fields: \`user_id\` (numeric PK, stringified — e.g. \`"1"\`) is the canonical identifier; \`userid\` (a cookie-like hash or null) is a legacy form-context field, ignore it.`,
716
+ ``,
717
+ `\`filename\` fields (on users, posts, pages) are NOT stable across updates. BD regenerates the slug when inputs that influence it change — e.g. \`updateUser\` can rewrite a member's \`filename\` from \`/us/city/slug\` to \`/us/city/category/slug\` after a category change. This is expected behavior, not a bug. If you're embedding profile/post URLs in other content (a blog article, email, redirect, another member's bio), write/publish that content AFTER all updates to the referenced records are done, OR re-fetch \`filename\` via \`getUser\`/\`getSingleImagePost\`/\`getWebPage\` right before you use it. Never cache a \`filename\` across an update cycle.`,
696
718
  ].join("\n"),
697
719
  }
698
720
  );