@open-loyalty/mcp-server 1.5.3 → 1.7.0

package/dist/tools/role/index.d.ts

@@ -0,0 +1,99 @@
+export { RoleListInputSchema, RoleCreateInputSchema, RoleGetInputSchema, RoleUpdateInputSchema, RoleDeleteInputSchema, } from "./schemas.js";
+export type { RolePermissionInput } from "./schemas.js";
+export { roleList, roleCreate, roleGet, roleUpdate, roleDelete, aclGetResources, } from "./handlers.js";
+import { roleList, roleCreate, roleGet, roleUpdate, roleDelete, aclGetResources } from "./handlers.js";
+export declare const roleToolDefinitions: readonly [{
+    readonly name: "ol_role_list";
+    readonly title: "List Roles";
+    readonly description: "List all roles with optional filtering. Returns paginated list of roles with id, name, permissions, master status, and default status.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        master: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        default: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    readonly handler: typeof roleList;
+}, {
+    readonly name: "ol_role_create";
+    readonly title: "Create Role";
+    readonly description: "Create a new role with permissions. Requires name. Optionally specify permissions (array of {resource, access, filterQuery}) and stores. Returns void on success (201 Created).";
+    readonly readOnly: false;
+    readonly idempotent: false;
+    readonly inputSchema: {
+        name: import("zod").ZodString;
+        permissions: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            resource: import("zod").ZodString;
+            access: import("zod").ZodString;
+            filterQuery: import("zod").ZodOptional<import("zod").ZodString>;
+        }, "strip", import("zod").ZodTypeAny, {
+            resource: string;
+            access: string;
+            filterQuery?: string | undefined;
+        }, {
+            resource: string;
+            access: string;
+            filterQuery?: string | undefined;
+        }>, "many">>;
+        stores: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+        default: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    readonly handler: typeof roleCreate;
+}, {
+    readonly name: "ol_role_get";
+    readonly title: "Get Role Details";
+    readonly description: "Get full role details by ID. Returns role with name, permissions array, master status, default status, and stores.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        roleId: import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>;
+    };
+    readonly handler: typeof roleGet;
+}, {
+    readonly name: "ol_role_update";
+    readonly title: "Update Role";
+    readonly description: "Update a role's name, permissions, or stores. Returns void on success (204 No Content).";
+    readonly readOnly: false;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        roleId: import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        permissions: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+            resource: import("zod").ZodString;
+            access: import("zod").ZodString;
+            filterQuery: import("zod").ZodOptional<import("zod").ZodString>;
+        }, "strip", import("zod").ZodTypeAny, {
+            resource: string;
+            access: string;
+            filterQuery?: string | undefined;
+        }, {
+            resource: string;
+            access: string;
+            filterQuery?: string | undefined;
+        }>, "many">>;
+        stores: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+        default: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    readonly handler: typeof roleUpdate;
+}, {
+    readonly name: "ol_role_delete";
+    readonly title: "Delete Role (Permanent)";
+    readonly description: "Delete a role by ID. Returns void on success (204 No Content). Cannot delete roles that are assigned to admin users.";
+    readonly readOnly: false;
+    readonly destructive: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        roleId: import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>;
+    };
+    readonly handler: typeof roleDelete;
+}, {
+    readonly name: "ol_acl_get_resources";
+    readonly title: "Get ACL Resources";
+    readonly description: "Get list of available ACL resources. Returns items with code and name for each resource type. Use this to discover available permissions before creating roles.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {};
+    readonly handler: typeof aclGetResources;
+}];

package/dist/tools/role/index.js

@@ -0,0 +1,65 @@
+// Re-export schemas and types
+export { RoleListInputSchema, RoleCreateInputSchema, RoleGetInputSchema, RoleUpdateInputSchema, RoleDeleteInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { roleList, roleCreate, roleGet, roleUpdate, roleDelete, aclGetResources, } from "./handlers.js";
+// Imports for tool definitions
+import { RoleListInputSchema, RoleCreateInputSchema, RoleGetInputSchema, RoleUpdateInputSchema, RoleDeleteInputSchema, } from "./schemas.js";
+import { roleList, roleCreate, roleGet, roleUpdate, roleDelete, aclGetResources, } from "./handlers.js";
+// Tool definitions
+export const roleToolDefinitions = [
+    {
+        name: "ol_role_list",
+        title: "List Roles",
+        description: "List all roles with optional filtering. Returns paginated list of roles with id, name, permissions, master status, and default status.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: RoleListInputSchema,
+        handler: roleList,
+    },
+    {
+        name: "ol_role_create",
+        title: "Create Role",
+        description: "Create a new role with permissions. Requires name. Optionally specify permissions (array of {resource, access, filterQuery}) and stores. Returns void on success (201 Created).",
+        readOnly: false,
+        idempotent: false,
+        inputSchema: RoleCreateInputSchema,
+        handler: roleCreate,
+    },
+    {
+        name: "ol_role_get",
+        title: "Get Role Details",
+        description: "Get full role details by ID. Returns role with name, permissions array, master status, default status, and stores.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: RoleGetInputSchema,
+        handler: roleGet,
+    },
+    {
+        name: "ol_role_update",
+        title: "Update Role",
+        description: "Update a role's name, permissions, or stores. Returns void on success (204 No Content).",
+        readOnly: false,
+        idempotent: true,
+        inputSchema: RoleUpdateInputSchema,
+        handler: roleUpdate,
+    },
+    {
+        name: "ol_role_delete",
+        title: "Delete Role (Permanent)",
+        description: "Delete a role by ID. Returns void on success (204 No Content). Cannot delete roles that are assigned to admin users.",
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        inputSchema: RoleDeleteInputSchema,
+        handler: roleDelete,
+    },
+    {
+        name: "ol_acl_get_resources",
+        title: "Get ACL Resources",
+        description: "Get list of available ACL resources. Returns items with code and name for each resource type. Use this to discover available permissions before creating roles.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: {},
+        handler: aclGetResources,
+    },
+];

package/dist/tools/role/schemas.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+export interface RolePermissionInput {
+    resource: string;
+    access: string;
+    filterQuery?: string;
+}
+export declare const RoleListInputSchema: {
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    master: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const RoleCreateInputSchema: {
+    name: z.ZodString;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        resource: z.ZodString;
+        access: z.ZodString;
+        filterQuery: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        resource: string;
+        access: string;
+        filterQuery?: string | undefined;
+    }, {
+        resource: string;
+        access: string;
+        filterQuery?: string | undefined;
+    }>, "many">>;
+    stores: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    default: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const RoleGetInputSchema: {
+    roleId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+};
+export declare const RoleUpdateInputSchema: {
+    roleId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    name: z.ZodOptional<z.ZodString>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        resource: z.ZodString;
+        access: z.ZodString;
+        filterQuery: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        resource: string;
+        access: string;
+        filterQuery?: string | undefined;
+    }, {
+        resource: string;
+        access: string;
+        filterQuery?: string | undefined;
+    }>, "many">>;
+    stores: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    default: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const RoleDeleteInputSchema: {
+    roleId: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+};

package/dist/tools/role/schemas.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+export const RoleListInputSchema = {
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 25)."),
+    name: z.string().optional().describe("Filter by role name."),
+    master: z.boolean().optional().describe("Filter by master role status."),
+    default: z.boolean().optional().describe("Filter by default role status."),
+};
+export const RoleCreateInputSchema = {
+    name: z.string().describe("Role name (required)."),
+    permissions: z.array(z.object({
+        resource: z.string().describe("Resource name (e.g., ANALYTICS, EVENTS). Use ol_acl_get_resources to discover all available resource codes."),
+        access: z.string().describe("Access level: VIEW (read-only) or MODIFY (read-write)."),
+        filterQuery: z.string().optional().describe("Optional filter query."),
+    })).optional().describe("Array of permission definitions."),
+    stores: z.array(z.string()).optional().describe("Store codes to assign access (e.g., ['DEFAULT'])."),
+    default: z.boolean().optional().describe("Whether this is a default role for new admins."),
+};
+export const RoleGetInputSchema = {
+    roleId: z.union([z.string(), z.number()]).describe("The role ID to retrieve."),
+};
+export const RoleUpdateInputSchema = {
+    roleId: z.union([z.string(), z.number()]).describe("The role ID to update."),
+    name: z.string().optional().describe("Role name."),
+    permissions: z.array(z.object({
+        resource: z.string().describe("Resource name. Use ol_acl_get_resources to discover all available resource codes."),
+        access: z.string().describe("Access level: VIEW (read-only) or MODIFY (read-write)."),
+        filterQuery: z.string().optional().describe("Optional filter query."),
+    })).optional().describe("Array of permission definitions."),
+    stores: z.array(z.string()).optional().describe("Store codes to assign access."),
+    default: z.boolean().optional().describe("Whether this is a default role."),
+};
+export const RoleDeleteInputSchema = {
+    roleId: z.union([z.string(), z.number()]).describe("The role ID to delete."),
+};

package/dist/tools/segment/handlers.js

@@ -1,5 +1,5 @@
 import { apiGet, apiPost, apiPut, apiDelete } from "../../client/http.js";
-import { formatApiError } from "../../utils/errors.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
 import { getStoreCode } from "../../config.js";
 const DEFAULT_TRANSACTION_COUNT_MAX = 999999;
 function normalizeSegmentParts(parts) {
@@ -71,6 +71,25 @@ export async function segmentCreate(input) {
         return { segmentId: response.segmentId };
     }
     catch (error) {
+        const axiosError = error;
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [
+            axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => `${e.path || ""}: ${e.message}`)
+        ].join(" ").toLowerCase();
+        if (allMessages.includes("type") && (allMessages.includes("choice is invalid") || allMessages.includes("not valid") || allMessages.includes("invalid"))) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_CRITERION_TYPE",
+                message: "Invalid criterion type in segment definition",
+                hint: "Valid criterion types: 'transaction_count' (purchase frequency), 'average_transaction_value', " +
+                    "'transaction_amount' (total spend), 'transaction_percent_in_period', 'purchase_in_period', " +
+                    "'bought_skus' (specific products), 'bought_labels' (product categories/tags), " +
+                    "'bought_makers' (brands), 'customer_list' (manual list), 'anniversary', 'last_purchase_n_days_before', " +
+                    "'customer_has_labels', 'customer_with_labels_values'. " +
+                    "NOTE: 'tier' and 'points_balance' are REJECTED by the API despite being documented.",
+                relatedTool: "ol_segment_create",
+            });
+        }
         throw formatApiError(error, "ol_segment_create");
     }
 }
@@ -81,6 +100,15 @@ export async function segmentGet(input) {
         return response;
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Segment '${input.segmentId}' not found`,
+                hint: "Use ol_segment_list() to find existing segments and their IDs.",
+                relatedTool: "ol_segment_get",
+            });
+        }
         throw formatApiError(error, "ol_segment_get");
     }
 }
@@ -99,6 +127,20 @@ export async function segmentUpdate(input) {
         await apiPut(`/${storeCode}/segment/${input.segmentId}`, { segment: segmentPayload });
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Segment '${input.segmentId}' not found`,
+                hint: "Use ol_segment_list() to find existing segments and their IDs.", relatedTool: "ol_segment_update" });
+        }
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [axiosError.response?.data?.message || "", ...apiErrors.map(e => `${e.path || ""}: ${e.message}`)].join(" ").toLowerCase();
+        if (allMessages.includes("type") && (allMessages.includes("choice is invalid") || allMessages.includes("not valid") || allMessages.includes("invalid"))) {
+            throw new OpenLoyaltyError({ code: "INVALID_CRITERION_TYPE", message: "Invalid criterion type in segment definition",
+                hint: "Valid criterion types: 'transaction_count', 'average_transaction_value', 'transaction_amount', " +
+                    "'purchase_in_period', 'bought_skus', 'bought_labels', 'bought_makers', 'customer_list', 'anniversary', " +
+                    "'last_purchase_n_days_before', 'customer_has_labels', 'customer_with_labels_values'.",
+                relatedTool: "ol_segment_update" });
+        }
         throw formatApiError(error, "ol_segment_update");
     }
 }
@@ -108,6 +150,11 @@ export async function segmentDelete(input) {
         await apiDelete(`/${storeCode}/segment/${input.segmentId}`);
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Segment '${input.segmentId}' not found`,
+                hint: "Use ol_segment_list() to find existing segments and their IDs.", relatedTool: "ol_segment_delete" });
+        }
         throw formatApiError(error, "ol_segment_delete");
     }
 }
@@ -140,6 +187,11 @@ export async function segmentGetMembers(input) {
         };
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Segment '${input.segmentId}' not found`,
+                hint: "Use ol_segment_list() to find existing segments and their IDs.", relatedTool: "ol_segment_get_members" });
+        }
         throw formatApiError(error, "ol_segment_get_members");
     }
 }
@@ -149,6 +201,11 @@ export async function segmentActivate(input) {
         await apiPost(`/${storeCode}/segment/${input.segmentId}/activate`, {});
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Segment '${input.segmentId}' not found`,
+                hint: "Use ol_segment_list() to find existing segments and their IDs.", relatedTool: "ol_segment_activate" });
+        }
         throw formatApiError(error, "ol_segment_activate");
     }
 }
@@ -158,6 +215,11 @@ export async function segmentDeactivate(input) {
         await apiPost(`/${storeCode}/segment/${input.segmentId}/deactivate`, {});
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Segment '${input.segmentId}' not found`,
+                hint: "Use ol_segment_list() to find existing segments and their IDs.", relatedTool: "ol_segment_deactivate" });
+        }
         throw formatApiError(error, "ol_segment_deactivate");
     }
 }
@@ -169,6 +231,11 @@ export async function segmentGetResources(input) {
         return { resources };
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Segment '${input.segmentId}' not found`,
+                hint: "Use ol_segment_list() to find existing segments and their IDs.", relatedTool: "ol_segment_get_resources" });
+        }
         throw formatApiError(error, "ol_segment_get_resources");
     }
 }

package/dist/tools/segment/index.d.ts

@@ -6,6 +6,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly title: "List Segments";
     readonly description: "List customer segments. Segments group members by criteria (purchase behavior, tier, location, etc). Use for campaign targeting and analytics.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         page: import("zod").ZodOptional<import("zod").ZodNumber>;
@@ -19,6 +20,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly title: "Create Segment";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         name: import("zod").ZodString;
@@ -176,6 +178,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly title: "Get Segment Details";
     readonly description: "Get full segment details including all parts and criteria configurations.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         segmentId: import("zod").ZodString;
@@ -186,6 +189,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly title: "Update Segment";
     readonly description: "Update segment configuration. Requires full segment definition (name, parts with criteria). Use segment_get first to retrieve current configuration.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         segmentId: import("zod").ZodString;
@@ -345,6 +349,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly description: "Permanently delete a segment. Cannot be undone. Check segment_get_resources first to see what uses this segment.";
     readonly readOnly: false;
     readonly destructive: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         segmentId: import("zod").ZodString;
@@ -355,6 +360,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly title: "Get Segment Members";
     readonly description: "Get members belonging to a segment. Returns paginated list of member details. Use for verifying segment criteria or exporting member lists.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         segmentId: import("zod").ZodString;
@@ -367,6 +373,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly title: "Activate Segment";
     readonly description: "Activate a segment. Active segments are used for campaign targeting and can be queried for members.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         segmentId: import("zod").ZodString;
@@ -377,6 +384,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly title: "Deactivate Segment";
     readonly description: "Deactivate a segment. Deactivated segments are not used for campaign targeting but retain their configuration.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         segmentId: import("zod").ZodString;
@@ -387,6 +395,7 @@ export declare const segmentToolDefinitions: readonly [{
     readonly title: "Get Segment Resources";
     readonly description: string;
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         segmentId: import("zod").ZodString;

package/dist/tools/segment/index.js

@@ -12,6 +12,7 @@ export const segmentToolDefinitions = [
         title: "List Segments",
         description: "List customer segments. Segments group members by criteria (purchase behavior, tier, location, etc). Use for campaign targeting and analytics.",
         readOnly: true,
+        idempotent: true,
         inputSchema: SegmentListInputSchema,
         handler: segmentList,
     },
@@ -24,8 +25,13 @@ export const segmentToolDefinitions = [
             "2. Threshold values -- min/max boundaries? (e.g., min=5 transactions captures frequent buyers; min=2 captures nearly everyone) " +
             "3. Intended use -- campaign targeting (activate immediately) or analytics only (can stay inactive)? " +
             "REQUIRED: name, parts array with criteria. Parts use OR logic, criteria within parts use AND logic. " +
+            "CRITERION FIELDS BY TYPE: " +
+            "transaction_count: { type: 'transaction_count', min: N, max: N } (both required, MCP auto-fills max=999999 if omitted). " +
+            "purchase_in_period: { type: 'purchase_in_period', days: N, min: N, max: N }. " +
+            "average_transaction_value: { type: 'average_transaction_value', min: N, max: N }. " +
             "NOTE: 'tier' and 'points_balance' types are REJECTED by the API despite being documented.",
         readOnly: false,
+        idempotent: false,
         inputSchema: SegmentCreateInputSchema,
         handler: segmentCreate,
     },
@@ -34,6 +40,7 @@ export const segmentToolDefinitions = [
         title: "Get Segment Details",
         description: "Get full segment details including all parts and criteria configurations.",
         readOnly: true,
+        idempotent: true,
         inputSchema: SegmentGetInputSchema,
         handler: segmentGet,
     },
@@ -42,6 +49,7 @@ export const segmentToolDefinitions = [
         title: "Update Segment",
         description: "Update segment configuration. Requires full segment definition (name, parts with criteria). Use segment_get first to retrieve current configuration.",
         readOnly: false,
+        idempotent: true,
         inputSchema: SegmentUpdateInputSchema,
         handler: segmentUpdate,
     },
@@ -51,6 +59,7 @@ export const segmentToolDefinitions = [
         description: "Permanently delete a segment. Cannot be undone. Check segment_get_resources first to see what uses this segment.",
         readOnly: false,
         destructive: true,
+        idempotent: true,
         inputSchema: SegmentDeleteInputSchema,
         handler: segmentDelete,
     },
@@ -59,6 +68,7 @@ export const segmentToolDefinitions = [
         title: "Get Segment Members",
         description: "Get members belonging to a segment. Returns paginated list of member details. Use for verifying segment criteria or exporting member lists.",
         readOnly: true,
+        idempotent: true,
         inputSchema: SegmentGetMembersInputSchema,
         handler: segmentGetMembers,
     },
@@ -67,6 +77,7 @@ export const segmentToolDefinitions = [
         title: "Activate Segment",
         description: "Activate a segment. Active segments are used for campaign targeting and can be queried for members.",
         readOnly: false,
+        idempotent: true,
         inputSchema: SegmentActivateInputSchema,
         handler: segmentActivate,
     },
@@ -75,6 +86,7 @@ export const segmentToolDefinitions = [
         title: "Deactivate Segment",
         description: "Deactivate a segment. Deactivated segments are not used for campaign targeting but retain their configuration.",
         readOnly: false,
+        idempotent: true,
         inputSchema: SegmentDeactivateInputSchema,
         handler: segmentDeactivate,
     },
@@ -84,6 +96,7 @@ export const segmentToolDefinitions = [
         description: "Get resources (campaigns, rewards, etc.) that use this segment for targeting. Check before deleting a segment. " +
             "NOTE: This endpoint may not be available in all API versions - if it returns NOT_FOUND, manually check campaigns and rewards that reference this segment.",
         readOnly: true,
+        idempotent: true,
         inputSchema: SegmentGetResourcesInputSchema,
         handler: segmentGetResources,
     },

package/dist/tools/segment/schemas.js

@@ -15,16 +15,19 @@ const SegmentCriterionInputSchema = z.object({
     type: z.string().describe("Criterion type. WORKING: 'transaction_count' (requires both min AND max; MCP auto-fills max if omitted). NOT WORKING: 'tier', 'points_balance' are rejected by the API."),
     criterionId: z.string().optional().describe("Criterion ID (optional, generated if not provided)."),
     // Common criterion data fields
-    days: z.number().optional().describe("Days for time-based criteria."),
+    days: z.number().optional().describe("Days for time-based criteria (e.g., 'in the last N days'). Used with transaction_count, purchase_period criteria."),
     fromDate: z.string().optional().describe("Start date (ISO format)."),
     toDate: z.string().optional().describe("End date (ISO format)."),
-    min: z.number().optional().describe("Minimum value. BUSINESS IMPACT: Too low a threshold (e.g., min=2 transactions) captures most members -- segment becomes too broad, wasting campaign budget."),
-    max: z.number().optional().describe("Maximum value. BUSINESS IMPACT: Too narrow a range (e.g., max=3 with min=3) captures very few members -- limited campaign impact."),
+    min: z.number().optional().describe("Minimum value (e.g., min=5 for 'at least 5 transactions'). Required for transaction_count type. BUSINESS IMPACT: Too low a threshold (e.g., min=2 transactions) captures most members -- segment becomes too broad, wasting campaign budget."),
+    max: z.number().optional().describe("Maximum value. Required for transaction_count type (MCP auto-fills max=999999 if omitted). BUSINESS IMPACT: Too narrow a range (e.g., max=3 with min=3) captures very few members -- limited campaign impact."),
     posIds: z.array(z.string()).optional().describe("POS IDs."),
     skus: z.array(z.string()).optional().describe("SKU codes."),
     makers: z.array(z.string()).optional().describe("Maker/brand names."),
-    labels: z.array(z.object({ key: z.string(), value: z.string() })).optional().describe("Label key-value pairs."),
-    tierIds: z.array(z.string()).optional().describe("Tier level IDs."),
+    labels: z.array(z.object({
+        key: z.string().describe("Label key (e.g., 'category', 'brand', 'channel')."),
+        value: z.string().describe("Label value to match (e.g., 'electronics', 'nike', 'online')."),
+    })).optional().describe("Label key-value pairs for label-based criteria."),
+    tierIds: z.array(z.string()).optional().describe("Tier level IDs. WARNING: 'tier' criterion type is NOT WORKING -- API rejects it. Use campaign audience targeting for tier-based segmentation instead."),
     campaignId: z.string().optional().describe("Campaign ID for campaign_completion criterion."),
     countries: z.array(z.string()).optional().describe("Country codes."),
     anniversaryType: z.string().optional().describe("Anniversary type."),

package/dist/tools/store/handlers.d.ts

@@ -0,0 +1,25 @@
+import type { Store, StoreListResponse } from "./schemas.js";
+export declare function storeList(input: {
+    page?: number;
+    perPage?: number;
+    active?: boolean;
+    name?: string;
+    code?: string;
+}): Promise<StoreListResponse>;
+export declare function storeCreate(input: {
+    code: string;
+    name: string;
+    currency?: string;
+    active?: boolean;
+}): Promise<{
+    storeId: string;
+}>;
+export declare function storeGet(input: {
+    storeId: string;
+}): Promise<Store>;
+export declare function storeUpdate(input: {
+    storeId: string;
+    name?: string;
+    active?: boolean;
+    currency?: string;
+}): Promise<void>;