createTopCategory

Create a category - Create a new TOP-level member category. Writes live data.

A Top Category is the highest level of the 3-tier member classification (e.g., "Restaurants"). It populates the profession_id field on user records. Backed by BD's list_professions table.

Use when: explicitly building out the site's taxonomy BEFORE members exist. If you're creating members and want categories to be auto-created by name, skip this and pass profession_name directly to createUser - BD auto-creates missing top-level categories on member-create.

Required: name, filename.

Pre-check before create: BD does NOT enforce uniqueness on filename. Two top categories with the same slug -> which one resolves at /filename is undefined. Do a server-side filter-find: listTopCategories property=filename property_value=<proposed> property_operator==. Zero rows = slug free; >=1 row = taken. Do NOT paginate unfiltered lists - filtered lookup is one tiny response. If taken: reuse via updateTopCategory, OR ask the user, OR pick an alternate filename and re-check. Wrapper safety net: on a missed pre-check, the wrapper auto-suffixes filename on collision (-1...-20) and surfaces the suffix in the response. Pre-checking still preferred — auto-suffix surprises the caller in URL-sensitive workflows.

Parameter guidance:

• name - human-readable (e.g. "Restaurants", "Dentists")

• filename - URL-slug form (e.g. "restaurants") used in public member profile URLs

• desc, keywords, icon, sort_order, lead_price, image - all optional

See also: listTopCategories (list all), getTopCategory (by ID), createSubCategory (add a sub-category under this top).

Writes live data: changes are immediately visible on the public site.

Returns: { status: "success", message: {...createdRecord} } including the new profession_id. Use that value to populate users_data.profession_id on member records.

Common workflow - full 3-tier setup ("create Restaurants -> Sushi -> assign Alice"):

1. createTopCategory with name="Restaurants", filename="restaurants" -> returns profession_id (e.g. 42)

2. createSubCategory with name="Sushi", profession_id=42, filename="sushi" -> returns service_id (e.g. 17)

3. Assign Alice: updateUser with user_id=<Alice>, profession_id=42, services="17" (simple), OR createMemberSubCategoryLink with user_id=<Alice>, service_id=17, avg_price=..., specialty=1 (with per-link metadata)

How a member gets classified on their public profile:

• users_data.profession_id -> points at a single Top Category (the member's primary classification; shown in URL slug)

• users_data.services -> CSV of Sub Category IDs the member is tagged with (multiple allowed; simpler than the join table)

• rel_services rows (Member ↔ Sub Category links) -> used when you need per-link metadata like avg_price, specialty, num_completed. Optional; most sites use just the CSV field.

Sub-sub-categories: createSubCategory with master_id=<parent service_id> creates a Sub Category nested under another Sub Category (a "sub-sub"). master_id=0 (default) means the Sub Category sits directly under a Top Category (the profession_id).

There is NO createProfession or createService tool in this MCP — those are BD's internal table names. Use createTopCategory / createSubCategory instead (BD's table-name → tool-name mapping is documented in Rule: Table to endpoint).