@open-loyalty/mcp-server 1.0.3 → 1.3.1

package/dist/tools/segment.js

@@ -1,18 +1,21 @@
 import { z } from "zod";
 import { apiGet, apiPost, apiPut, apiDelete } from "../client/http.js";
 import { formatApiError } from "../utils/errors.js";
-import { getConfig } from "../config.js";
+import { getStoreCode } from "../config.js";
 // Input Schemas
 export const SegmentListInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 10)."),
     active: z.boolean().optional().describe("Filter by active status."),
     name: z.string().optional().describe("Filter by segment name."),
 };
 // Criterion input schema - flexible to support all criterion types
+// NOTE: Only certain criterion types are supported by the API.
+// WORKING: transaction_count (requires both min AND max; MCP will auto-fill max if omitted)
+// NOT WORKING: tier, points_balance (rejected by API despite being documented)
 const SegmentCriterionInputSchema = z.object({
-    type: z.string().describe("Criterion type (e.g., 'tier', 'transaction_count', 'points_balance')."),
+    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."),
@@ -37,18 +40,18 @@ const SegmentPartInputSchema = z.object({
     criteria: z.array(SegmentCriterionInputSchema).describe("Criteria for this part (AND logic)."),
 });
 export const SegmentCreateInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     name: z.string().describe("Segment name (required)."),
     description: z.string().optional().describe("Segment description."),
     active: z.boolean().optional().describe("Whether segment is active (default: false)."),
     parts: z.array(SegmentPartInputSchema).describe("Segment parts. Parts use OR logic (ANY part matches), criteria within parts use AND logic (ALL criteria must match)."),
 };
 export const SegmentGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     segmentId: z.string().describe("The segment ID (UUID) to retrieve."),
 };
 export const SegmentUpdateInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     segmentId: z.string().describe("The segment ID (UUID) to update."),
     name: z.string().describe("Segment name."),
     description: z.string().optional().describe("Segment description."),
@@ -56,31 +59,30 @@ export const SegmentUpdateInputSchema = {
     parts: z.array(SegmentPartInputSchema).describe("Segment parts."),
 };
 export const SegmentDeleteInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     segmentId: z.string().describe("The segment ID (UUID) to delete."),
 };
 export const SegmentGetMembersInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     segmentId: z.string().describe("The segment ID (UUID) to get members for."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),
 };
 export const SegmentActivateInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     segmentId: z.string().describe("The segment ID (UUID) to activate."),
 };
 export const SegmentDeactivateInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     segmentId: z.string().describe("The segment ID (UUID) to deactivate."),
 };
 export const SegmentGetResourcesInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     segmentId: z.string().describe("The segment ID (UUID) to get associated resources for."),
 };
 // Handler functions
 export async function segmentList(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     const params = new URLSearchParams();
     if (input.page)
         params.append("_page", String(input.page));
@@ -112,15 +114,32 @@ export async function segmentList(input) {
         };
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_list");
+        throw formatApiError(error, "ol_segment_list");
     }
 }
+const DEFAULT_TRANSACTION_COUNT_MAX = 999999;
+function normalizeSegmentParts(parts) {
+    return parts.map((part) => ({
+        ...part,
+        criteria: part.criteria.map((criterion) => {
+            if (!criterion || typeof criterion !== "object") {
+                return criterion;
+            }
+            const normalized = { ...criterion };
+            if (normalized.type === "transaction_count" &&
+                normalized.min !== undefined &&
+                normalized.max === undefined) {
+                normalized.max = DEFAULT_TRANSACTION_COUNT_MAX;
+            }
+            return normalized;
+        }),
+    }));
+}
 export async function segmentCreate(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     const segmentPayload = {
         name: input.name,
-        parts: input.parts,
+        parts: normalizeSegmentParts(input.parts),
     };
     if (input.description)
         segmentPayload.description = input.description;
@@ -132,26 +151,24 @@ export async function segmentCreate(input) {
         return { segmentId: response.segmentId };
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_create");
+        throw formatApiError(error, "ol_segment_create");
     }
 }
 export async function segmentGet(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     try {
         const response = await apiGet(`/${storeCode}/segment/${input.segmentId}`);
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_get");
+        throw formatApiError(error, "ol_segment_get");
     }
 }
 export async function segmentUpdate(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     const segmentPayload = {
         name: input.name,
-        parts: input.parts,
+        parts: normalizeSegmentParts(input.parts),
     };
     if (input.description !== undefined)
         segmentPayload.description = input.description;
@@ -162,22 +179,20 @@ export async function segmentUpdate(input) {
         await apiPut(`/${storeCode}/segment/${input.segmentId}`, { segment: segmentPayload });
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_update");
+        throw formatApiError(error, "ol_segment_update");
     }
 }
 export async function segmentDelete(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     try {
         await apiDelete(`/${storeCode}/segment/${input.segmentId}`);
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_delete");
+        throw formatApiError(error, "ol_segment_delete");
     }
 }
 export async function segmentGetMembers(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     const params = new URLSearchParams();
     if (input.page)
         params.append("_page", String(input.page));
@@ -205,94 +220,113 @@ export async function segmentGetMembers(input) {
         };
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_get_members");
+        throw formatApiError(error, "ol_segment_get_members");
     }
 }
 export async function segmentActivate(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     try {
         await apiPost(`/${storeCode}/segment/${input.segmentId}/activate`, {});
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_activate");
+        throw formatApiError(error, "ol_segment_activate");
     }
 }
 export async function segmentDeactivate(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     try {
         await apiPost(`/${storeCode}/segment/${input.segmentId}/deactivate`, {});
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_deactivate");
+        throw formatApiError(error, "ol_segment_deactivate");
     }
 }
 export async function segmentGetResources(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     try {
         const response = await apiGet(`/${storeCode}/segment/${input.segmentId}/resources`);
         const resources = response.items || response.resources || [];
         return { resources };
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_segment_get_resources");
+        throw formatApiError(error, "ol_segment_get_resources");
     }
 }
 // Tool definitions
 export const segmentToolDefinitions = [
     {
-        name: "openloyalty_segment_list",
+        name: "ol_segment_list",
+        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,
         inputSchema: SegmentListInputSchema,
         handler: segmentList,
     },
     {
-        name: "openloyalty_segment_create",
-        description: "Create segment to group members. Parts use OR logic (member matches if ANY part matches). Criteria within parts use AND logic (must match ALL criteria in that part). Common criteria: tier, transaction_count, points_balance, country. Example - VIP segment: parts: [{ criteria: [{ type: 'tier', tierIds: ['gold-level-id'] }] }]",
+        name: "ol_segment_create",
+        title: "Create Segment",
+        description: "Create segment to group members. Parts use OR logic (member matches if ANY part matches). Criteria within parts use AND logic (must match ALL criteria in that part). " +
+            "WORKING criterion types: 'transaction_count' (requires BOTH min AND max). " +
+            "NOT WORKING: 'tier', 'points_balance' are rejected by the API. " +
+            "Example - High activity segment: parts: [{ criteria: [{ type: 'transaction_count', min: 5, max: 999999 }] }]",
+        readOnly: false,
         inputSchema: SegmentCreateInputSchema,
         handler: segmentCreate,
     },
     {
-        name: "openloyalty_segment_get",
+        name: "ol_segment_get",
+        title: "Get Segment Details",
         description: "Get full segment details including all parts and criteria configurations.",
+        readOnly: true,
         inputSchema: SegmentGetInputSchema,
         handler: segmentGet,
     },
     {
-        name: "openloyalty_segment_update",
+        name: "ol_segment_update",
+        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,
         inputSchema: SegmentUpdateInputSchema,
         handler: segmentUpdate,
     },
     {
-        name: "openloyalty_segment_delete",
+        name: "ol_segment_delete",
+        title: "Delete Segment (Permanent)",
         description: "Permanently delete a segment. Cannot be undone. Check segment_get_resources first to see what uses this segment.",
+        readOnly: false,
+        destructive: true,
         inputSchema: SegmentDeleteInputSchema,
         handler: segmentDelete,
     },
     {
-        name: "openloyalty_segment_get_members",
+        name: "ol_segment_get_members",
+        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,
         inputSchema: SegmentGetMembersInputSchema,
         handler: segmentGetMembers,
     },
     {
-        name: "openloyalty_segment_activate",
+        name: "ol_segment_activate",
+        title: "Activate Segment",
         description: "Activate a segment. Active segments are used for campaign targeting and can be queried for members.",
+        readOnly: false,
         inputSchema: SegmentActivateInputSchema,
         handler: segmentActivate,
     },
     {
-        name: "openloyalty_segment_deactivate",
+        name: "ol_segment_deactivate",
+        title: "Deactivate Segment",
         description: "Deactivate a segment. Deactivated segments are not used for campaign targeting but retain their configuration.",
+        readOnly: false,
         inputSchema: SegmentDeactivateInputSchema,
         handler: segmentDeactivate,
     },
     {
-        name: "openloyalty_segment_get_resources",
+        name: "ol_segment_get_resources",
+        title: "Get Segment Resources",
         description: "Get resources (campaigns, rewards, etc.) that use this segment for targeting. Check before deleting a segment.",
+        readOnly: true,
         inputSchema: SegmentGetResourcesInputSchema,
         handler: segmentGetResources,
     },

package/dist/tools/store.d.ts

@@ -61,8 +61,10 @@ export declare function storeUpdate(input: {
     currency?: string;
 }): Promise<void>;
 export declare const storeToolDefinitions: readonly [{
-    readonly name: "openloyalty_store_list";
+    readonly name: "ol_store_list";
+    readonly title: "List Stores";
     readonly description: "List all stores with optional filtering. Returns paginated list of stores with storeId, code, name, currency, and active status. Stores enable multi-tenant loyalty programs. Each store has independent members, campaigns, and settings.";
+    readonly readOnly: true;
     readonly inputSchema: {
         page: z.ZodOptional<z.ZodNumber>;
         perPage: z.ZodOptional<z.ZodNumber>;
@@ -72,8 +74,10 @@ export declare const storeToolDefinitions: readonly [{
     };
     readonly handler: typeof storeList;
 }, {
-    readonly name: "openloyalty_store_create";
+    readonly name: "ol_store_create";
+    readonly title: "Create Store";
     readonly description: "Create a new store for multi-tenant setup. Requires unique code and name. Returns storeId on success.";
+    readonly readOnly: false;
     readonly inputSchema: {
         code: z.ZodString;
         name: z.ZodString;
@@ -82,15 +86,19 @@ export declare const storeToolDefinitions: readonly [{
     };
     readonly handler: typeof storeCreate;
 }, {
-    readonly name: "openloyalty_store_get";
+    readonly name: "ol_store_get";
+    readonly title: "Get Store Details";
     readonly description: "Get full store configuration by ID. Returns storeId, code, name, currency, active status, and timestamps.";
+    readonly readOnly: true;
     readonly inputSchema: {
         storeId: z.ZodString;
     };
     readonly handler: typeof storeGet;
 }, {
-    readonly name: "openloyalty_store_update";
+    readonly name: "ol_store_update";
+    readonly title: "Update Store";
     readonly description: "Update store configuration. Can update name, currency, and active status. Returns void on success (204 No Content).";
+    readonly readOnly: false;
     readonly inputSchema: {
         storeId: z.ZodString;
         name: z.ZodOptional<z.ZodString>;

package/dist/tools/store.js

@@ -44,7 +44,7 @@ export async function storeList(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_store_list");
+        throw formatApiError(error, "ol_store_list");
     }
 }
 export async function storeCreate(input) {
@@ -61,7 +61,7 @@ export async function storeCreate(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_store_create");
+        throw formatApiError(error, "ol_store_create");
     }
 }
 export async function storeGet(input) {
@@ -70,7 +70,7 @@ export async function storeGet(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_store_get");
+        throw formatApiError(error, "ol_store_get");
     }
 }
 export async function storeUpdate(input) {
@@ -85,32 +85,40 @@ export async function storeUpdate(input) {
         await apiPut(`/store/${input.storeId}`, { store: payload });
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_store_update");
+        throw formatApiError(error, "ol_store_update");
     }
 }
 // Tool definitions
 export const storeToolDefinitions = [
     {
-        name: "openloyalty_store_list",
+        name: "ol_store_list",
+        title: "List Stores",
         description: "List all stores with optional filtering. Returns paginated list of stores with storeId, code, name, currency, and active status. Stores enable multi-tenant loyalty programs. Each store has independent members, campaigns, and settings.",
+        readOnly: true,
         inputSchema: StoreListInputSchema,
         handler: storeList,
     },
     {
-        name: "openloyalty_store_create",
+        name: "ol_store_create",
+        title: "Create Store",
         description: "Create a new store for multi-tenant setup. Requires unique code and name. Returns storeId on success.",
+        readOnly: false,
         inputSchema: StoreCreateInputSchema,
         handler: storeCreate,
     },
     {
-        name: "openloyalty_store_get",
+        name: "ol_store_get",
+        title: "Get Store Details",
         description: "Get full store configuration by ID. Returns storeId, code, name, currency, active status, and timestamps.",
+        readOnly: true,
         inputSchema: StoreGetInputSchema,
         handler: storeGet,
     },
     {
-        name: "openloyalty_store_update",
+        name: "ol_store_update",
+        title: "Update Store",
         description: "Update store configuration. Can update name, currency, and active status. Returns void on success (204 No Content).",
+        readOnly: false,
         inputSchema: StoreUpdateInputSchema,
         handler: storeUpdate,
     },

package/dist/tools/tierset.d.ts

@@ -167,8 +167,10 @@ export declare function tiersetGetTiers(input: TierSetGetInput): Promise<{
     };
 }>;
 export declare const tiersetToolDefinitions: readonly [{
-    readonly name: "openloyalty_tierset_list";
+    readonly name: "ol_tierset_list";
+    readonly title: "List Loyalty Programs";
     readonly description: "List all tier sets. Use tierset_get to fetch conditions needed for defining tiers. Returns tierSetId, name, active status, and tier count for each tier set.";
+    readonly readOnly: true;
     readonly inputSchema: {
         storeCode: z.ZodOptional<z.ZodString>;
         page: z.ZodOptional<z.ZodNumber>;
@@ -176,8 +178,10 @@ export declare const tiersetToolDefinitions: readonly [{
     };
     readonly handler: typeof tiersetList;
 }, {
-    readonly name: "openloyalty_tierset_create";
-    readonly description: "Create a new tier set (loyalty program structure). After creation, call tierset_get to obtain conditionId values, then tierset_update_tiers to define tier thresholds. Conditions define what metrics are used for tier progression (e.g., activeUnits for points balance).";
+    readonly name: "ol_tierset_create";
+    readonly title: "Create Loyalty Program";
+    readonly description: string;
+    readonly readOnly: false;
     readonly inputSchema: {
         storeCode: z.ZodOptional<z.ZodString>;
         name: z.ZodString;
@@ -206,16 +210,20 @@ export declare const tiersetToolDefinitions: readonly [{
     };
     readonly handler: typeof tiersetCreate;
 }, {
-    readonly name: "openloyalty_tierset_get";
+    readonly name: "ol_tierset_get";
+    readonly title: "Get Loyalty Program Details";
     readonly description: "Get tier set details including conditionId values needed for tierset_update_tiers. Returns the full tier set with conditions array containing conditionId for each condition.";
+    readonly readOnly: true;
     readonly inputSchema: {
         storeCode: z.ZodOptional<z.ZodString>;
         tierSetId: z.ZodString;
     };
     readonly handler: typeof tiersetGet;
 }, {
-    readonly name: "openloyalty_tierset_update";
+    readonly name: "ol_tierset_update";
+    readonly title: "Update Loyalty Program";
     readonly description: "Update tier set metadata (name, description, active status, downgrade settings). Does not modify tiers - use tierset_update_tiers for that.";
+    readonly readOnly: false;
     readonly inputSchema: {
         storeCode: z.ZodOptional<z.ZodString>;
         tierSetId: z.ZodString;
@@ -235,8 +243,10 @@ export declare const tiersetToolDefinitions: readonly [{
     };
     readonly handler: typeof tiersetUpdate;
 }, {
-    readonly name: "openloyalty_tierset_update_tiers";
+    readonly name: "ol_tierset_update_tiers";
+    readonly title: "Configure Tier Thresholds";
     readonly description: "Define tier thresholds for a tier set. PREREQUISITE: Call tierset_get first to obtain conditionId values. Each tier's conditions array uses conditionId from the parent tier set plus a threshold value.\n\nExample for a 3-tier program with points-based progression:\n- Bronze tier: conditions: [{ conditionId: \"xxx\", value: 400 }]\n- Silver tier: conditions: [{ conditionId: \"xxx\", value: 800 }]\n- Gold tier: conditions: [{ conditionId: \"xxx\", value: 1200 }]\n\nThe conditionId must match one from tierset_get response.";
+    readonly readOnly: false;
     readonly inputSchema: {
         storeCode: z.ZodOptional<z.ZodString>;
         tierSetId: z.ZodString;
@@ -277,8 +287,10 @@ export declare const tiersetToolDefinitions: readonly [{
     };
     readonly handler: typeof tiersetUpdateTiers;
 }, {
-    readonly name: "openloyalty_tierset_get_tiers";
+    readonly name: "ol_tierset_get_tiers";
+    readonly title: "Get Tier Configuration";
     readonly description: "Get all tiers in a tier set. Returns levelId values that can be used for campaign targeting. Includes each tier's name and condition thresholds.";
+    readonly readOnly: true;
     readonly inputSchema: {
         storeCode: z.ZodOptional<z.ZodString>;
         tierSetId: z.ZodString;