@baasix/baasix 0.1.50 → 0.1.52

package/dist/services/MCPService.js

@@ -83,10 +83,99 @@ function errorResult(error) {
     };
 }
 // ==================== MCP Server Creation ====================
+// Map every tool to its action category: "read" | "create" | "update" | "delete"
+const TOOL_ACTION_MAP = {
+    // Schema Management
+    baasix_list_schemas: "read",
+    baasix_get_schema: "read",
+    baasix_export_schemas: "read",
+    baasix_create_schema: "create",
+    baasix_import_schemas: "create",
+    baasix_add_index: "create",
+    baasix_create_relationship: "create",
+    baasix_update_schema: "update",
+    baasix_update_relationship: "update",
+    baasix_delete_schema: "delete",
+    baasix_remove_index: "delete",
+    baasix_delete_relationship: "delete",
+    // Item Management
+    baasix_list_items: "read",
+    baasix_get_item: "read",
+    baasix_create_item: "create",
+    baasix_update_item: "update",
+    baasix_delete_item: "delete",
+    // File Management
+    baasix_list_files: "read",
+    baasix_get_file_info: "read",
+    baasix_delete_file: "delete",
+    // Authentication / Session
+    baasix_auth_status: "read",
+    baasix_refresh_auth: "read",
+    baasix_login: "create",
+    baasix_logout: "delete",
+    baasix_get_current_user: "read",
+    baasix_register_user: "create",
+    baasix_send_invite: "create",
+    baasix_verify_invite: "read",
+    baasix_send_magic_link: "create",
+    baasix_get_user_tenants: "read",
+    baasix_switch_tenant: "update",
+    // Reports and Analytics
+    baasix_generate_report: "read",
+    baasix_collection_stats: "read",
+    // Notifications
+    baasix_list_notifications: "read",
+    baasix_send_notification: "create",
+    baasix_mark_notification_seen: "update",
+    // Settings
+    baasix_get_settings: "read",
+    baasix_update_settings: "update",
+    // Email Templates
+    baasix_list_templates: "read",
+    baasix_get_template: "read",
+    baasix_update_template: "update",
+    // Permissions
+    baasix_list_roles: "read",
+    baasix_list_permissions: "read",
+    baasix_get_permission: "read",
+    baasix_get_permissions: "read",
+    baasix_create_permission: "create",
+    baasix_update_permission: "update",
+    baasix_delete_permission: "delete",
+    baasix_reload_permissions: "read",
+    baasix_update_permissions: "update",
+    // Utilities
+    baasix_server_info: "read",
+    baasix_sort_items: "update",
+};
+/**
+ * Parse MCP_ENABLED_ACTIONS env var.
+ * Accepts a comma-separated list of: "all", "read", "create", "update", "delete"
+ * Returns null when all actions are enabled (default), or a Set of enabled action strings.
+ */
+function parseEnabledActions() {
+    const raw = (env.get("MCP_ENABLED_ACTIONS") || "all").toLowerCase().trim();
+    const actions = raw.split(",").map((a) => a.trim()).filter(Boolean);
+    if (actions.includes("all"))
+        return null; // null = everything enabled
+    return new Set(actions);
+}
+/**
+ * Check if a tool should be registered based on MCP_ENABLED_ACTIONS.
+ */
+function isToolEnabled(toolName, enabledActions) {
+    if (!enabledActions)
+        return true; // "all"
+    const action = TOOL_ACTION_MAP[toolName];
+    if (!action)
+        return true; // unknown tools stay enabled
+    return enabledActions.has(action);
+}
 /**
  * Create and configure the MCP server with all Baasix tools
  */
 export function createMCPServer() {
+    const enabledActions = parseEnabledActions();
     const server = new McpServer({
         name: "Baasix Backend-as-a-Service",
         version: "0.1.0",
@@ -181,7 +270,16 @@ Call baasix_create_schema with:
     // All schema tools call the REST routes via HTTP with the session's bearer token.
     // This ensures route-level validation, processSchemaFlags, permission checks and cache
     // invalidation are applied exactly once (in the route) — zero duplicated logic.
-    server.tool("baasix_list_schemas", "List all database tables (collections) and their schema definitions. Use this to discover what tables exist. System tables are prefixed with 'baasix_'.", {
+    /**
+     * Conditionally register a tool based on MCP_ENABLED_ACTIONS.
+     * Wraps server.tool() — if the tool's action category is not enabled, skips registration entirely.
+     */
+    function registerTool(name, ...rest) {
+        if (!isToolEnabled(name, enabledActions))
+            return;
+        server.tool(name, ...rest);
+    }
+    registerTool("baasix_list_schemas", "List all database tables (collections) and their schema definitions. Use this to discover what tables exist. System tables are prefixed with 'baasix_'.", {
         search: z.string().optional().describe("Search term to filter schemas by collection name"),
         page: z.number().optional().default(1).describe("Page number for pagination"),
         limit: z.number().optional().default(10).describe("Number of schemas per page"),
@@ -203,7 +301,7 @@ Call baasix_create_schema with:
             return errorResult(res.error || 'Failed to list schemas');
         return successResult(res.data);
     });
-    server.tool("baasix_get_schema", `Get the full schema definition (columns, types, constraints, relationships, indexes) for a specific database table/collection.
+    registerTool("baasix_get_schema", `Get the full schema definition (columns, types, constraints, relationships, indexes) for a specific database table/collection.
 
 IMPORTANT: Always call this BEFORE using baasix_update_schema to get the current schema.
 The update_schema tool performs a full replacement, so you need the complete current schema to avoid losing existing fields.`, {
@@ -215,7 +313,7 @@ The update_schema tool performs a full replacement, so you need the complete cur
             return errorResult(res.error || `Schema '${collection}' not found`);
         return successResult(res.data);
     });
-    server.tool("baasix_create_schema", `CREATE A NEW DATABASE TABLE. This is the tool to use when asked to "create a table", "create a collection", "add a new model", or "define a new entity".
+    registerTool("baasix_create_schema", `CREATE A NEW DATABASE TABLE. This is the tool to use when asked to "create a table", "create a collection", "add a new model", or "define a new entity".
 
 This creates both the schema definition AND the actual PostgreSQL table with all specified columns.
 
@@ -258,7 +356,7 @@ schema: { "timestamps": true, "fields": { "id": { "type": "UUID", "primaryKey":
             collectionName: collection,
         });
     });
-    server.tool("baasix_update_schema", `Modify an existing database table — add new columns, change column types, or remove columns.
+    registerTool("baasix_update_schema", `Modify an existing database table — add new columns, change column types, or remove columns.
 Use this when asked to 'add a field', 'add a column', or 'alter a table'.
 
 ⚠️ CRITICAL: This performs a FULL REPLACEMENT of the schema definition, NOT a merge.
@@ -310,7 +408,7 @@ EXAMPLE — Adding a "description" field to an existing "products" table that ha
             return errorResult(res.error || `Failed to update collection '${collection}'`);
         return successResult({ success: true, message: `Collection '${collection}' updated successfully` });
     });
-    server.tool("baasix_delete_schema", `DROP/DELETE an entire database table and all its data permanently.
+    registerTool("baasix_delete_schema", `DROP/DELETE an entire database table and all its data permanently.
 Use this when asked to 'drop a table', 'delete a collection', or 'remove a table'.
 
 ⚠️ WARNING: This is destructive and irreversible. The table, all its data, indexes, and relationships will be permanently deleted.
@@ -323,7 +421,7 @@ Do NOT use this to remove a column — use baasix_update_schema instead to modif
             return errorResult(res.error || `Failed to delete collection '${collection}'`);
         return successResult({ success: true, message: `Collection '${collection}' deleted successfully` });
     });
-    server.tool("baasix_add_index", `Add a database index to a table for better query performance.
+    registerTool("baasix_add_index", `Add a database index to a table for better query performance.
 This is an ADDITIVE operation — it only adds the new index without affecting existing indexes or schema fields.
 Supports btree (default), hash, gin, and gist index types.
 
@@ -357,7 +455,7 @@ EXAMPLE — Add a GIN index for JSONB or array fields:
             return errorResult(res.error || `Failed to add index to '${collection}'`);
         return successResult({ success: true, message: `Index added to '${collection}' successfully` });
     });
-    server.tool("baasix_remove_index", "Remove an existing index from a database table. This only removes the index — it does NOT delete any data or columns. Use baasix_get_schema first to see the list of existing indexes if you don't know the index name.", {
+    registerTool("baasix_remove_index", "Remove an existing index from a database table. This only removes the index — it does NOT delete any data or columns. Use baasix_get_schema first to see the list of existing indexes if you don't know the index name.", {
         collection: z.string().describe("Collection name"),
         indexName: z.string().describe("Name of the index to remove"),
     }, async (args, extra) => {
@@ -367,7 +465,7 @@ EXAMPLE — Add a GIN index for JSONB or array fields:
             return errorResult(res.error || `Failed to remove index '${indexName}' from '${collection}'`);
         return successResult({ success: true, message: `Index '${indexName}' removed from '${collection}'` });
     });
-    server.tool("baasix_create_relationship", `Create a foreign key / relationship between two database tables. Use this when asked to 'link tables', 'add a foreign key', 'create a relation', or 'connect collections'.
+    registerTool("baasix_create_relationship", `Create a foreign key / relationship between two database tables. Use this when asked to 'link tables', 'add a foreign key', 'create a relation', or 'connect collections'.
 
 RELATIONSHIP TYPES:
 - M2O (Many-to-One / BelongsTo): Adds a foreign key column. Example: products.category_Id → categories.id
@@ -410,7 +508,7 @@ relationshipData: { "name": "category", "type": "M2O", "target": "categories", "
             message: `Relationship '${relationshipData.name}' created on '${sourceCollection}'`,
         });
     });
-    server.tool("baasix_delete_relationship", `Remove a foreign key / relationship from a database table.
+    registerTool("baasix_delete_relationship", `Remove a foreign key / relationship from a database table.
 This drops the foreign key constraint and the FK column (e.g., category_Id) from the source table.
 For M2M relationships, this also removes the junction table.
 
@@ -425,13 +523,13 @@ Do NOT confuse with baasix_delete_schema (which deletes an entire table).`, {
             return errorResult(res.error || `Failed to remove relationship '${fieldName}' from '${sourceCollection}'`);
         return successResult({ success: true, message: `Relationship '${fieldName}' removed from '${sourceCollection}'` });
     });
-    server.tool("baasix_export_schemas", "Export all table definitions as JSON for backup or migration.", {}, async (_args, extra) => {
+    registerTool("baasix_export_schemas", "Export all table definitions as JSON for backup or migration.", {}, async (_args, extra) => {
         const res = await callRoute('GET', '/schemas-export', extra);
         if (!res.ok)
             return errorResult(res.error || 'Failed to export schemas');
         return successResult(res.data);
     });
-    server.tool("baasix_import_schemas", "Import table definitions from JSON data to recreate tables.", {
+    registerTool("baasix_import_schemas", "Import table definitions from JSON data to recreate tables.", {
         schemas: z.record(z.any()).describe("Schema data to import"),
     }, async (args, extra) => {
         const { schemas } = args;
@@ -465,7 +563,7 @@ Do NOT confuse with baasix_delete_schema (which deletes an entire table).`, {
         }
     });
     // ==================== Item Management Tools ====================
-    server.tool("baasix_list_items", `Query/list/fetch rows from a database table. Use this when asked to 'get data', 'list records', 'query items', 'search', or 'fetch rows' from any table.
+    registerTool("baasix_list_items", `Query/list/fetch rows from a database table. Use this when asked to 'get data', 'list records', 'query items', 'search', or 'fetch rows' from any table.
 
 NOTE: For analytics, summaries, totals, sums, averages, counts, min/max, grouped reports, or dashboards → use baasix_generate_report instead. Use this tool (list_items) for fetching actual row data.
 
@@ -592,7 +690,7 @@ Supports same operators and dynamic variables as filter.
             return errorResult(error);
         }
     });
-    server.tool("baasix_get_item", `Get a single row/record by its ID from a database table. Optionally include related data from linked tables.
+    registerTool("baasix_get_item", `Get a single row/record by its ID from a database table. Optionally include related data from linked tables.
 
 FIELDS — use dot notation to include related data:
 - ["*"] → all columns on this table
@@ -619,7 +717,7 @@ The primary key is always returned.`, {
             return errorResult(error);
         }
     });
-    server.tool("baasix_create_item", `Insert a new row/record into a database table. Use this when asked to 'add data', 'insert a record', or 'create an entry'.
+    registerTool("baasix_create_item", `Insert a new row/record into a database table. Use this when asked to 'add data', 'insert a record', or 'create an entry'.
 
 Pass field values as a key-value object. For UUID primary keys with UUIDV4 default, you can omit the id field — it will be auto-generated.
 For tables with timestamps: true, createdAt and updatedAt are auto-managed.
@@ -640,7 +738,7 @@ EXAMPLE: collection: "products", data: {"name": "Widget", "price": 9.99, "catego
             return errorResult(error);
         }
     });
-    server.tool("baasix_update_item", `Update/modify an existing row/record in a database table by its ID. Only pass the fields you want to change — unspecified fields remain unchanged.
+    registerTool("baasix_update_item", `Update/modify an existing row/record in a database table by its ID. Only pass the fields you want to change — unspecified fields remain unchanged.
 
 For tables with timestamps: true, updatedAt is automatically updated.
 For foreign key fields, use the "_Id" suffixed column name (e.g., category_Id).`, {
@@ -659,7 +757,7 @@ For foreign key fields, use the "_Id" suffixed column name (e.g., category_Id).`
             return errorResult(error);
         }
     });
-    server.tool("baasix_delete_item", "Delete a row/record from a database table by its ID. For tables with paranoid: true (soft delete), the record is marked as deleted (deletedAt is set) rather than permanently removed.", {
+    registerTool("baasix_delete_item", "Delete a row/record from a database table by its ID. For tables with paranoid: true (soft delete), the record is marked as deleted (deletedAt is set) rather than permanently removed.", {
         collection: z.string().describe("Table/collection name"),
         id: z.string().describe("Row ID (UUID) to delete"),
     }, async (args, extra) => {
@@ -675,7 +773,7 @@ For foreign key fields, use the "_Id" suffixed column name (e.g., category_Id).`
         }
     });
     // ==================== File Management Tools ====================
-    server.tool("baasix_list_files", `List uploaded files with metadata (filename, size, type, dimensions, storage location).
+    registerTool("baasix_list_files", `List uploaded files with metadata (filename, size, type, dimensions, storage location).
 
 Filter examples:
 By type: {"type": {"startsWith": "image/"}}
@@ -704,7 +802,7 @@ Public files only: {"isPublic": {"eq": true}}`, {
             return errorResult(error);
         }
     });
-    server.tool("baasix_get_file_info", "Get detailed metadata about a specific uploaded file — filename, size, MIME type, dimensions, storage location, and who uploaded it.", {
+    registerTool("baasix_get_file_info", "Get detailed metadata about a specific uploaded file — filename, size, MIME type, dimensions, storage location, and who uploaded it.", {
         id: z.string().describe("File UUID"),
     }, async (args, extra) => {
         const { id } = args;
@@ -718,7 +816,7 @@ Public files only: {"isPublic": {"eq": true}}`, {
             return errorResult(error);
         }
     });
-    server.tool("baasix_delete_file", "Delete an uploaded file by its UUID. Removes both the file record and the actual file from storage.", {
+    registerTool("baasix_delete_file", "Delete an uploaded file by its UUID. Removes both the file record and the actual file from storage.", {
         id: z.string().describe("File UUID"),
     }, async (args, extra) => {
         const { id } = args;
@@ -733,7 +831,7 @@ Public files only: {"isPublic": {"eq": true}}`, {
         }
     });
     // ==================== Permission Tools ====================
-    server.tool("baasix_list_roles", "List all user roles with their IDs, names, and descriptions. Use this to get role UUIDs needed for permission tools. Default roles: 'administrator' (full access), 'public' (unauthenticated access). Custom roles can be created for granular access control.", {}, async (_args, extra) => {
+    registerTool("baasix_list_roles", "List all user roles with their IDs, names, and descriptions. Use this to get role UUIDs needed for permission tools. Default roles: 'administrator' (full access), 'public' (unauthenticated access). Custom roles can be created for granular access control.", {}, async (_args, extra) => {
         try {
             const res = await callRoute('GET', '/items/baasix_Role?limit=-1', extra);
             if (!res.ok)
@@ -744,7 +842,7 @@ Public files only: {"isPublic": {"eq": true}}`, {
             return errorResult(error);
         }
     });
-    server.tool("baasix_list_permissions", `List all access control permission rules with optional filtering.
+    registerTool("baasix_list_permissions", `List all access control permission rules with optional filtering.
 
 Each permission defines: role_Id (which role), collection (which table), action (create/read/update/delete), fields (which columns), conditions (row-level security), defaultValues (auto-set values), and relConditions (related table security).
 
@@ -780,7 +878,7 @@ Permissions for a table: {"collection": {"eq": "products"}}`, {
             return errorResult(error);
         }
     });
-    server.tool("baasix_create_permission", `Grant a role permission to perform an action on a table. Use this to set up access control (RBAC + row-level security).
+    registerTool("baasix_create_permission", `Grant a role permission to perform an action on a table. Use this to set up access control (RBAC + row-level security).
 
 First use baasix_list_roles to get the role UUID, then create permissions for that role.
 
@@ -862,7 +960,7 @@ role_Id: "<uuid>", collection: "posts", action: "update", fields: ["title", "con
             return errorResult(error);
         }
     });
-    server.tool("baasix_update_permission", `Update an existing permission rule. Only pass the fields you want to change — unspecified fields remain unchanged.
+    registerTool("baasix_update_permission", `Update an existing permission rule. Only pass the fields you want to change — unspecified fields remain unchanged.
 
 See baasix_create_permission for full documentation of conditions, relConditions, defaultValues, and fields options.
 Use baasix_list_permissions or baasix_get_permissions to find the permission ID to update.`, {
@@ -886,7 +984,7 @@ Use baasix_list_permissions or baasix_get_permissions to find the permission ID
             return errorResult(error);
         }
     });
-    server.tool("baasix_delete_permission", "Delete a permission rule by its UUID. This revokes the access it granted. The permission cache is automatically reloaded.", {
+    registerTool("baasix_delete_permission", "Delete a permission rule by its UUID. This revokes the access it granted. The permission cache is automatically reloaded.", {
         id: z.string().describe("Permission UUID — get from baasix_list_permissions or baasix_get_permissions"),
     }, async (args, extra) => {
         const { id } = args;
@@ -900,7 +998,7 @@ Use baasix_list_permissions or baasix_get_permissions to find the permission ID
             return errorResult(error);
         }
     });
-    server.tool("baasix_reload_permissions", "Force-reload the permission cache from the database. Normally not needed as create/update/delete permission tools auto-reload. Use this if permissions seem stale.", {}, async (_args, extra) => {
+    registerTool("baasix_reload_permissions", "Force-reload the permission cache from the database. Normally not needed as create/update/delete permission tools auto-reload. Use this if permissions seem stale.", {}, async (_args, extra) => {
         try {
             const res = await callRoute('POST', '/permissions/reload', extra);
             if (!res.ok)
@@ -912,7 +1010,7 @@ Use baasix_list_permissions or baasix_get_permissions to find the permission ID
         }
     });
     // ==================== Settings Tools ====================
-    server.tool("baasix_get_settings", "Get application settings. Pass a key to get a specific setting, or omit to get all settings. Settings include project info, auth config, email config, etc.", {
+    registerTool("baasix_get_settings", "Get application settings. Pass a key to get a specific setting, or omit to get all settings. Settings include project info, auth config, email config, etc.", {
         key: z.string().optional().describe("Specific setting key to retrieve (e.g., 'project_name', 'auth_password_policy'). Omit for all settings."),
     }, async (args, extra) => {
         const { key } = args;
@@ -927,7 +1025,7 @@ Use baasix_list_permissions or baasix_get_permissions to find the permission ID
             return errorResult(error);
         }
     });
-    server.tool("baasix_update_settings", "Update application settings. Pass an object with the settings keys and their new values. Only specified keys are updated.", {
+    registerTool("baasix_update_settings", "Update application settings. Pass an object with the settings keys and their new values. Only specified keys are updated.", {
         settings: z.record(z.any()).describe("Settings to update as {key: value}. Use baasix_get_settings first to see available keys."),
     }, async (args, extra) => {
         const { settings } = args;
@@ -945,7 +1043,7 @@ Use baasix_list_permissions or baasix_get_permissions to find the permission ID
         }
     });
     // ==================== Email Template Tools ====================
-    server.tool("baasix_list_templates", "List all email templates (invitation, password reset, welcome, etc.).", {
+    registerTool("baasix_list_templates", "List all email templates (invitation, password reset, welcome, etc.).", {
         filter: z.record(z.any()).optional().describe("Filter criteria"),
         page: z.number().optional().default(1).describe("Page number"),
         limit: z.number().optional().default(10).describe("Templates per page"),
@@ -969,7 +1067,7 @@ Use baasix_list_permissions or baasix_get_permissions to find the permission ID
             return errorResult(error);
         }
     });
-    server.tool("baasix_get_template", "Get a specific email template by ID", {
+    registerTool("baasix_get_template", "Get a specific email template by ID", {
         id: z.string().describe("Template ID (UUID)"),
     }, async (args, extra) => {
         const { id } = args;
@@ -983,7 +1081,7 @@ Use baasix_list_permissions or baasix_get_permissions to find the permission ID
             return errorResult(error);
         }
     });
-    server.tool("baasix_update_template", `Update an email template's subject, description, or body content.
+    registerTool("baasix_update_template", `Update an email template's subject, description, or body content.
 
 TEMPLATE TYPES:
 - magic_link: Magic link authentication emails
@@ -1014,7 +1112,7 @@ AVAILABLE VARIABLES:
         }
     });
     // ==================== Notification Tools ====================
-    server.tool("baasix_list_notifications", "List in-app notifications for the current authenticated user. Filter by seen/unseen status to find unread notifications.", {
+    registerTool("baasix_list_notifications", "List in-app notifications for the current authenticated user. Filter by seen/unseen status to find unread notifications.", {
         page: z.number().optional().default(1).describe("Page number"),
         limit: z.number().optional().default(10).describe("Notifications per page. Use -1 for all."),
         seen: z.boolean().optional().describe("Filter: true = only seen, false = only unseen, omit = all"),
@@ -1038,7 +1136,7 @@ AVAILABLE VARIABLES:
             return errorResult(error);
         }
     });
-    server.tool("baasix_mark_notification_seen", "Mark a notification as seen/read by its UUID.", {
+    registerTool("baasix_mark_notification_seen", "Mark a notification as seen/read by its UUID.", {
         id: z.string().describe("Notification UUID"),
     }, async (args, extra) => {
         const { id } = args;
@@ -1053,7 +1151,7 @@ AVAILABLE VARIABLES:
         }
     });
     // ==================== Utility Tools ====================
-    server.tool("baasix_server_info", "Get server health, version, uptime, and memory usage.", {}, async (_args, _extra) => {
+    registerTool("baasix_server_info", "Get server health, version, uptime, and memory usage.", {}, async (_args, _extra) => {
         try {
             const info = {
                 name: "baasix",
@@ -1074,7 +1172,7 @@ AVAILABLE VARIABLES:
             return errorResult(error);
         }
     });
-    server.tool("baasix_sort_items", `Reorder a row within a sortable table — move it before or after another row. The table must have a "sort" field.
+    registerTool("baasix_sort_items", `Reorder a row within a sortable table — move it before or after another row. The table must have a "sort" field.
 
 MODE:
 - "before" (default): Places item directly before the target row
@@ -1110,7 +1208,7 @@ EXAMPLE: Move task "abc" before task "xyz":
             return errorResult(error);
         }
     });
-    server.tool("baasix_generate_report", `Run an aggregate/analytics query on a database table. ALWAYS use this tool (not baasix_list_items) when the user asks for sums, totals, counts, averages, min/max, grouped data, dashboards, reports, or any analytics/summary query.
+    registerTool("baasix_generate_report", `Run an aggregate/analytics query on a database table. ALWAYS use this tool (not baasix_list_items) when the user asks for sums, totals, counts, averages, min/max, grouped data, dashboards, reports, or any analytics/summary query.
 
 QUERY OPTIONS:
 - fields: Columns to return. Default ["*"]. Use dot notation for relations: ["category.name", "status"].
@@ -1195,7 +1293,7 @@ EXAMPLES:
         }
     });
     // ==================== Collection Stats Tool ====================
-    server.tool("baasix_collection_stats", `Run multiple aggregate queries across different tables in a single call. Each query uses the full report engine (filter, aggregate, groupBy, etc.).
+    registerTool("baasix_collection_stats", `Run multiple aggregate queries across different tables in a single call. Each query uses the full report engine (filter, aggregate, groupBy, etc.).
 
 Each stats entry requires:
 - name: A unique label for this stat in the results (e.g. "total_orders", "active_users")
@@ -1240,7 +1338,7 @@ EXAMPLES:
         }
     });
     // ==================== Send Notification Tool ====================
-    server.tool("baasix_send_notification", "Send an in-app notification to one or more users by their user UUIDs. Notifications appear in the user's notification list and can be marked as seen.", {
+    registerTool("baasix_send_notification", "Send an in-app notification to one or more users by their user UUIDs. Notifications appear in the user's notification list and can be marked as seen.", {
         recipients: z.array(z.string()).describe("Array of user UUIDs to notify"),
         title: z.string().describe("Notification title"),
         message: z.string().describe("Notification message body"),
@@ -1267,7 +1365,7 @@ EXAMPLES:
         }
     });
     // ==================== Get Permission Tool ====================
-    server.tool("baasix_get_permission", "Get a specific permission rule by its UUID. Returns the full permission object including role_Id, collection, action, fields, conditions, defaultValues, and relConditions.", {
+    registerTool("baasix_get_permission", "Get a specific permission rule by its UUID. Returns the full permission object including role_Id, collection, action, fields, conditions, defaultValues, and relConditions.", {
         id: z.string().describe("Permission UUID"),
     }, async (args, extra) => {
         const { id } = args;
@@ -1282,7 +1380,7 @@ EXAMPLES:
         }
     });
     // ==================== Get Permissions for Role Tool ====================
-    server.tool("baasix_get_permissions", `Get all permission rules assigned to a specific role. Shows which tables the role can access and what actions (create/read/update/delete) are allowed, including any row-level security conditions, field restrictions, default values, and relationship conditions.
+    registerTool("baasix_get_permissions", `Get all permission rules assigned to a specific role. Shows which tables the role can access and what actions (create/read/update/delete) are allowed, including any row-level security conditions, field restrictions, default values, and relationship conditions.
 
 Accepts either the role name (e.g., "editor", "public") or the role UUID.`, {
         role: z.string().describe("Role name (e.g., 'editor', 'public') or role UUID"),
@@ -1320,7 +1418,7 @@ Accepts either the role name (e.g., "editor", "public") or the role UUID.`, {
         }
     });
     // ==================== Update Permissions for Role Tool ====================
-    server.tool("baasix_update_permissions", `Bulk set/update access control permissions for a role — define which tables a role can create, read, update, or delete. Creates new permissions or updates existing ones. Automatically reloads the permission cache.
+    registerTool("baasix_update_permissions", `Bulk set/update access control permissions for a role — define which tables a role can create, read, update, or delete. Creates new permissions or updates existing ones. Automatically reloads the permission cache.
 
 Accepts role name (e.g., "editor") or role UUID. Each permission in the array specifies a table + action combination.
 If a permission for that role+table+action already exists, it is updated. Otherwise, a new one is created.
@@ -1404,7 +1502,7 @@ permissions: [{"collection": "posts", "action": "read", "conditions": {"author_I
         }
     });
     // ==================== Auth Tools ====================
-    server.tool("baasix_get_current_user", `Get the currently authenticated user's profile, role, and permissions.
+    registerTool("baasix_get_current_user", `Get the currently authenticated user's profile, role, and permissions.
 
 Use fields to include related data:
 - ["*"] → all user fields
@@ -1445,7 +1543,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(error);
         }
     });
-    server.tool("baasix_register_user", "Register a new user", {
+    registerTool("baasix_register_user", "Register a new user", {
         email: z.string().email().describe("User email address"),
         password: z.string().describe("User password"),
         firstName: z.string().optional().describe("User first name"),
@@ -1470,7 +1568,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(axiosError.response?.data?.message || axiosError.message || "Unknown error");
         }
     });
-    server.tool("baasix_send_invite", "Send an invitation to a user", {
+    registerTool("baasix_send_invite", "Send an invitation to a user", {
         email: z.string().email().describe("Email address to invite"),
         role_Id: z.string().describe("Role ID to assign"),
         tenant_Id: z.string().optional().describe("Tenant ID"),
@@ -1493,7 +1591,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(axiosError.response?.data?.message || axiosError.message || "Unknown error");
         }
     });
-    server.tool("baasix_verify_invite", "Verify an invitation token", {
+    registerTool("baasix_verify_invite", "Verify an invitation token", {
         token: z.string().describe("Invitation token"),
         link: z.string().url().optional().describe("Application URL to validate"),
     }, async (args, _extra) => {
@@ -1512,7 +1610,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(axiosError.response?.data?.message || axiosError.message || "Unknown error");
         }
     });
-    server.tool("baasix_send_magic_link", "Send magic link or code for authentication", {
+    registerTool("baasix_send_magic_link", "Send magic link or code for authentication", {
         email: z.string().email().describe("User email address"),
         link: z.string().url().optional().describe("Application URL for magic link"),
         mode: z.enum(["link", "code"]).optional().default("link").describe("Magic authentication mode"),
@@ -1533,7 +1631,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(axiosError.response?.data?.message || axiosError.message || "Unknown error");
         }
     });
-    server.tool("baasix_get_user_tenants", "Get available tenants for the current user", {}, async (_args, _extra) => {
+    registerTool("baasix_get_user_tenants", "Get available tenants for the current user", {}, async (_args, _extra) => {
         try {
             const { default: axios } = await import("axios");
             const baseUrl = `http://localhost:${env.get("PORT") || "8056"}`;
@@ -1545,7 +1643,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(axiosError.response?.data?.message || axiosError.message || "Unknown error");
         }
     });
-    server.tool("baasix_switch_tenant", "Switch to a different tenant context", {
+    registerTool("baasix_switch_tenant", "Switch to a different tenant context", {
         tenant_Id: z.string().describe("Tenant ID to switch to"),
     }, async (args, _extra) => {
         const { tenant_Id } = args;
@@ -1563,7 +1661,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
         }
     });
     // ==================== Auth Status & Session Tools ====================
-    server.tool("baasix_auth_status", "Check if the current MCP session is authenticated, and show the current user, role, and admin status.", {}, async (_args, extra) => {
+    registerTool("baasix_auth_status", "Check if the current MCP session is authenticated, and show the current user, role, and admin status.", {}, async (_args, extra) => {
         try {
             const accountability = getAccountability(extra);
             return successResult({
@@ -1578,7 +1676,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(error);
         }
     });
-    server.tool("baasix_login", "Authenticate with email and password to get admin or role-based access. Required before performing write operations if not already authenticated via headers.", {
+    registerTool("baasix_login", "Authenticate with email and password to get admin or role-based access. Required before performing write operations if not already authenticated via headers.", {
         email: z.string().email().describe("User email address"),
         password: z.string().describe("User password"),
     }, async (args, extra) => {
@@ -1628,7 +1726,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(axiosError.response?.data?.message || axiosError.message || "Login failed");
         }
     });
-    server.tool("baasix_logout", "Logout and invalidate current session", {}, async (_args, extra) => {
+    registerTool("baasix_logout", "Logout and invalidate current session", {}, async (_args, extra) => {
         try {
             // Remove MCP session if exists
             if (extra.sessionId) {
@@ -1641,7 +1739,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
             return errorResult(err.message || "Logout failed");
         }
     });
-    server.tool("baasix_refresh_auth", "Refresh authentication token", {
+    registerTool("baasix_refresh_auth", "Refresh authentication token", {
         refreshToken: z.string().optional().describe("Refresh token (if not using cookies)"),
     }, async (_args, extra) => {
         try {
@@ -1661,7 +1759,7 @@ Returns authenticated: false if no user is logged in (public/anonymous access).`
         }
     });
     // ==================== Update Relationship Tool ====================
-    server.tool("baasix_update_relationship", "Modify an existing foreign key / relationship between two database tables (change delete behavior, alias, etc.).", {
+    registerTool("baasix_update_relationship", "Modify an existing foreign key / relationship between two database tables (change delete behavior, alias, etc.).", {
         sourceCollection: z.string().describe("Source collection name"),
         relationshipName: z.string().describe("Relationship field name to update"),
         relationshipData: z