@open-loyalty/mcp-server 1.5.3 → 1.7.0

package/dist/tools/import/handlers.js

@@ -0,0 +1,123 @@
+import { apiGet } from "../../client/http.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import { getConfig, getStoreCode } from "../../config.js";
+import axios from "axios";
+import FormDataNode from "form-data";
+export async function importCreate(input) {
+    const config = getConfig();
+    const storeCode = getStoreCode(input.storeCode);
+    // Determine file extension and content type
+    // API accepts: application/xml, text/xml for member imports; text/csv for others
+    const fileName = input.fileName || "import.xml";
+    const isXml = fileName.endsWith('.xml') || input.fileContent.trim().startsWith('<?xml') || input.fileContent.trim().startsWith('<');
+    const contentType = isXml ? "application/xml" : "text/csv";
+    // Create form data for multipart upload using Node.js form-data package
+    // API expects field name "import[file]" per documentation
+    const formData = new FormDataNode();
+    formData.append("import[file]", Buffer.from(input.fileContent), {
+        filename: fileName,
+        contentType: contentType,
+    });
+    try {
+        const response = await axios.post(`${config.apiUrl}/${storeCode}/import/${input.type}`, formData, {
+            headers: {
+                "X-AUTH-TOKEN": config.apiToken,
+                ...formData.getHeaders(),
+            },
+        });
+        return response.data;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 400) {
+            const allMessages = [error.response?.data?.message || "", ...(error.response?.data?.errors || []).map((e) => e.message)].join(" ").toLowerCase();
+            if (allMessages.includes("file") || allMessages.includes("format") || allMessages.includes("invalid") || allMessages.includes("parse")) {
+                throw new OpenLoyaltyError({ code: "INVALID_FILE_FORMAT", message: "The import file content is invalid or in the wrong format",
+                    hint: `For '${input.type}' imports: member imports typically use XML format, others use CSV. Ensure the file content is properly formatted and the fileName extension (.xml or .csv) matches the content type.`,
+                    relatedTool: "ol_import_create" });
+            }
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "Cannot create import - store not found",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_import_create",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "IMPORT_PERMISSION_DENIED",
+                message: "You don't have permission to create imports",
+                hint: "Bulk imports require the IMPORT:MODIFY permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_import_create",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 413) {
+            throw new OpenLoyaltyError({
+                code: "FILE_TOO_LARGE",
+                message: "The import file is too large",
+                hint: "Split the file into smaller chunks and import each chunk separately. Most import endpoints accept files up to 10MB.",
+                relatedTool: "ol_import_create",
+            });
+        }
+        throw formatApiError(error, "ol_import_create");
+    }
+}
+export async function importList(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.page)
+        params.append("_page", String(input.page));
+    if (input.perPage)
+        params.append("_itemsOnPage", String(input.perPage));
+    if (input.importId)
+        params.append("importId", input.importId);
+    if (input.type)
+        params.append("type", input.type);
+    const queryString = params.toString();
+    const url = `/${storeCode}/import${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "Cannot list imports - store not found",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_import_list",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "IMPORT_PERMISSION_DENIED",
+                message: "You don't have permission to view imports",
+                hint: "Import access requires the IMPORT:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_import_list",
+            });
+        }
+        throw formatApiError(error, "ol_import_list");
+    }
+}
+export async function importGet(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.page)
+        params.append("_page", String(input.page));
+    if (input.perPage)
+        params.append("_itemsOnPage", String(input.perPage));
+    const queryString = params.toString();
+    const url = `/${storeCode}/import/${input.importId}${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Import '${input.importId}' not found`,
+                hint: "Use ol_import_list() to find existing imports and their IDs.", relatedTool: "ol_import_get" });
+        }
+        throw formatApiError(error, "ol_import_get");
+    }
+}

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

@@ -0,0 +1,45 @@
+export { ImportCreateInputSchema, ImportListInputSchema, ImportGetInputSchema, } from "./schemas.js";
+export type { Import, ImportItem, ImportListResponse, ImportDetailsResponse, } from "./schemas.js";
+export { importCreate, importList, importGet, } from "./handlers.js";
+import { importCreate, importList, importGet } from "./handlers.js";
+export declare const importToolDefinitions: readonly [{
+    readonly name: "ol_import_create";
+    readonly title: "Create Bulk Import";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly idempotent: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        type: import("zod").ZodEnum<["member", "groupValue", "segmentMembers", "unitTransferAdding", "unitTransferSpending", "transaction", "campaignCode", "rewardCoupon"]>;
+        fileContent: import("zod").ZodString;
+        fileName: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof importCreate;
+}, {
+    readonly name: "ol_import_list";
+    readonly title: "List Imports";
+    readonly description: "List imports with optional filtering. Returns paginated list of imports with importId, type, uploadedDate, fileName, and status information.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+        importId: import("zod").ZodOptional<import("zod").ZodString>;
+        type: import("zod").ZodOptional<import("zod").ZodEnum<["member", "groupValue", "segmentMembers", "unitTransferAdding", "unitTransferSpending", "transaction", "campaignCode", "rewardCoupon"]>>;
+    };
+    readonly handler: typeof importList;
+}, {
+    readonly name: "ol_import_get";
+    readonly title: "Get Import Details";
+    readonly description: "Get import details and individual item statuses. Returns paginated list of import items with their success/failure status and error messages.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        importId: import("zod").ZodString;
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    readonly handler: typeof importGet;
+}];

package/dist/tools/import/index.js

@@ -0,0 +1,41 @@
+// Re-export schemas and types
+export { ImportCreateInputSchema, ImportListInputSchema, ImportGetInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { importCreate, importList, importGet, } from "./handlers.js";
+// Imports for tool definitions
+import { ImportCreateInputSchema, ImportListInputSchema, ImportGetInputSchema, } from "./schemas.js";
+import { importCreate, importList, importGet, } from "./handlers.js";
+// Tool definitions
+export const importToolDefinitions = [
+    {
+        name: "ol_import_create",
+        title: "Create Bulk Import",
+        description: "Create a new bulk import from file content (CSV or XML). Returns importId for async tracking. " +
+            "Import types: member (member data - typically XML), groupValue (group values), segmentMembers (segment membership), " +
+            "unitTransferAdding (add points), unitTransferSpending (spend points), transaction (transactions), " +
+            "campaignCode (campaign codes), rewardCoupon (reward coupons). " +
+            "Provide plain text file content (CSV or XML). Format is auto-detected from content or fileName extension.",
+        readOnly: false,
+        idempotent: false,
+        inputSchema: ImportCreateInputSchema,
+        handler: importCreate,
+    },
+    {
+        name: "ol_import_list",
+        title: "List Imports",
+        description: "List imports with optional filtering. Returns paginated list of imports with importId, type, uploadedDate, fileName, and status information.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: ImportListInputSchema,
+        handler: importList,
+    },
+    {
+        name: "ol_import_get",
+        title: "Get Import Details",
+        description: "Get import details and individual item statuses. Returns paginated list of import items with their success/failure status and error messages.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: ImportGetInputSchema,
+        handler: importGet,
+    },
+];

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

@@ -0,0 +1,57 @@
+import { z } from "zod";
+export interface Import {
+    importId: string;
+    type?: string;
+    uploadedDate?: string;
+    fileName?: string;
+    itemsToImport?: number;
+    user?: string;
+    errorMessage?: string;
+    additionalData?: Record<string, string>;
+}
+export interface ImportItem {
+    importId?: string;
+    status?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    message?: string;
+    entity?: {
+        id?: string;
+        data?: Record<string, unknown>;
+    };
+}
+export interface ImportListResponse {
+    items: Import[];
+    total?: {
+        all?: number | string;
+        filtered?: number | string;
+        estimated?: boolean | number;
+    };
+}
+export interface ImportDetailsResponse {
+    items: ImportItem[];
+    total?: {
+        all?: number | string;
+        filtered?: number | string;
+        estimated?: boolean | number;
+    };
+}
+export declare const ImportCreateInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<["member", "groupValue", "segmentMembers", "unitTransferAdding", "unitTransferSpending", "transaction", "campaignCode", "rewardCoupon"]>;
+    fileContent: z.ZodString;
+    fileName: z.ZodOptional<z.ZodString>;
+};
+export declare const ImportListInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    importId: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["member", "groupValue", "segmentMembers", "unitTransferAdding", "unitTransferSpending", "transaction", "campaignCode", "rewardCoupon"]>>;
+};
+export declare const ImportGetInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    importId: z.ZodString;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+};

package/dist/tools/import/schemas.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+export const ImportCreateInputSchema = {
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
+    type: z.enum([
+        "member",
+        "groupValue",
+        "segmentMembers",
+        "unitTransferAdding",
+        "unitTransferSpending",
+        "transaction",
+        "campaignCode",
+        "rewardCoupon",
+    ]).describe("Import type. Options: member, groupValue, segmentMembers, unitTransferAdding, unitTransferSpending, transaction, campaignCode, rewardCoupon."),
+    fileContent: z.string().describe("File content as plain text (not base64 encoded). Accepts CSV (comma-separated rows) or XML format. " +
+        "For member imports, XML is the standard format. Auto-detected based on content or fileName extension."),
+    fileName: z.string().optional().describe("Optional file name for the import (default: import.xml). Use .xml extension for XML content, .csv for CSV content."),
+};
+export const ImportListInputSchema = {
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 25)."),
+    importId: z.string().optional().describe("Filter by import ID."),
+    type: z.enum([
+        "member",
+        "groupValue",
+        "segmentMembers",
+        "unitTransferAdding",
+        "unitTransferSpending",
+        "transaction",
+        "campaignCode",
+        "rewardCoupon",
+    ]).optional().describe("Filter by import type."),
+};
+export const ImportGetInputSchema = {
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
+    importId: z.string().describe("The import ID (UUID) to retrieve."),
+    page: z.number().optional().describe("Page number for import items (default: 1)."),
+    perPage: z.number().optional().describe("Items per page for import items (default: 25)."),
+};

package/dist/tools/index.d.ts

@@ -6,6 +6,7 @@ export interface ToolDefinition {
     description: string;
     readOnly: boolean;
     destructive?: boolean;
+    idempotent?: boolean;
     inputSchema: ZodShape;
     handler: (args: Record<string, unknown>) => Promise<unknown>;
 }

package/dist/tools/index.js

@@ -8,20 +8,20 @@ import { transactionToolDefinitions } from "./transaction/index.js";
 import { campaignToolDefinitions } from "./campaign/index.js";
 import { segmentToolDefinitions } from "./segment/index.js";
 import { achievementToolDefinitions } from "./achievement/index.js";
-import { badgeToolDefinitions } from "./badge.js";
+import { badgeToolDefinitions } from "./badge/index.js";
 // Phase 3 tools
-import { analyticsToolDefinitions } from "./analytics.js";
-import { adminToolDefinitions } from "./admin.js";
-import { roleToolDefinitions } from "./role.js";
-import { apiKeyToolDefinitions } from "./apikey.js";
-import { auditToolDefinitions } from "./audit.js";
-import { storeToolDefinitions } from "./store.js";
+import { analyticsToolDefinitions } from "./analytics/index.js";
+import { adminToolDefinitions } from "./admin/index.js";
+import { roleToolDefinitions } from "./role/index.js";
+import { apiKeyToolDefinitions } from "./apikey/index.js";
+import { auditToolDefinitions } from "./audit/index.js";
+import { storeToolDefinitions } from "./store/index.js";
 // Phase 4 tools
-import { webhookToolDefinitions } from "./webhook.js";
-import { importToolDefinitions } from "./import.js";
-import { exportToolDefinitions } from "./export.js";
+import { webhookToolDefinitions } from "./webhook/index.js";
+import { importToolDefinitions } from "./import/index.js";
+import { exportToolDefinitions } from "./export/index.js";
 // Custom event tools (needed for custom_event trigger in campaigns/achievements)
-import { customEventToolDefinitions } from "./custom-event.js";
+import { customEventToolDefinitions } from "./custom-event/index.js";
 // Referral tools (needed for referral tracking between members)
 import { referralToolDefinitions } from "./referral/index.js";
 // Collect all tool definitions

package/dist/tools/member/handlers.js

@@ -153,6 +153,11 @@ export async function memberUpdate(input) {
         await apiPut(`/${storeCode}/member/${input.memberId}`, { customer: payload });
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Member '${input.memberId}' not found`,
+                hint: "Use ol_member_list() to search for the member by email, name, or phone.", relatedTool: "ol_member_update" });
+        }
         throw formatApiError(error, "ol_member_update");
     }
 }
@@ -162,6 +167,11 @@ export async function memberActivate(input) {
         await apiPost(`/${storeCode}/member/${input.memberId}/activate`);
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Member '${input.memberId}' not found`,
+                hint: "Use ol_member_list() to search for the member by email, name, or phone.", relatedTool: "ol_member_activate" });
+        }
         throw formatApiError(error, "ol_member_activate");
     }
 }
@@ -171,6 +181,11 @@ export async function memberDeactivate(input) {
         await apiPost(`/${storeCode}/member/${input.memberId}/deactivate`);
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Member '${input.memberId}' not found`,
+                hint: "Use ol_member_list() to search for the member by email, name, or phone.", relatedTool: "ol_member_deactivate" });
+        }
         throw formatApiError(error, "ol_member_deactivate");
     }
 }
@@ -180,6 +195,11 @@ export async function memberDelete(input) {
         await apiDelete(`/${storeCode}/member/${input.memberId}`);
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Member '${input.memberId}' not found`,
+                hint: "Use ol_member_list() to search for the member by email, name, or phone.", relatedTool: "ol_member_delete" });
+        }
         throw formatApiError(error, "ol_member_delete");
     }
 }
@@ -206,6 +226,11 @@ export async function memberGetTierProgress(input) {
         };
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Member '${input.memberId}' not found`,
+                hint: "Use ol_member_list() to search for the member by email, name, or phone.", relatedTool: "ol_member_get_tier_progress" });
+        }
         throw formatApiError(error, "ol_member_get_tier_progress");
     }
 }
@@ -248,6 +273,11 @@ export async function memberRemoveManualTier(input) {
         await apiPost(`/${storeCode}/member/${input.memberId}/remove-manually-level`);
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Member '${input.memberId}' not found`,
+                hint: "Use ol_member_list() to search for the member by email, name, or phone.", relatedTool: "ol_member_remove_manual_tier" });
+        }
         throw formatApiError(error, "ol_member_remove_manual_tier");
     }
 }

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

@@ -6,6 +6,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Register New Member";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         email: import("zod").ZodString;
@@ -44,6 +45,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Get Member Profile";
     readonly description: "Get member details including profile, points balance, and tier status. Use memberId from member_create or member_list.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -54,6 +56,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Search Members";
     readonly description: string;
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         cursor: import("zod").ZodOptional<import("zod").ZodString>;
@@ -72,6 +75,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Update Member Profile";
     readonly description: "Update member profile fields. Cannot change email. Use member_get first to see current values.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -109,6 +113,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Activate Member Account";
     readonly description: "Activate a member account. Inactive members cannot earn or spend points.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -119,6 +124,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Deactivate Member Account";
     readonly description: "Deactivate a member account. Deactivated members cannot earn or spend points but retain their balance.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -130,6 +136,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly description: "Permanently removes member and all associated data. Cannot be undone. Use for GDPR compliance or member requests.";
     readonly readOnly: false;
     readonly destructive: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -140,6 +147,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Check Tier Progress";
     readonly description: "Get member tier progression status showing current tier and progress to next. Returns currentValue, requiredValue, and progressPercent.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -150,6 +158,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Assign Tier to Member";
     readonly description: "Manually assign a tier level to a member, overriding automatic tier calculation. Use tierset_get_tiers to find available levelId values.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -161,6 +170,7 @@ export declare const memberToolDefinitions: readonly [{
     readonly title: "Remove Manual Tier Assignment";
     readonly description: "Remove manually assigned tier from member, restoring automatic tier calculation based on conditions.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;

package/dist/tools/member/index.js

@@ -14,6 +14,7 @@ export const memberToolDefinitions = [
             "REQUIRED: email (must be unique). OPTIONAL: firstName, lastName, phone, birthDate (YYYY-MM-DD), gender, loyaltyCardNumber. " +
             "NOTE: agreement1 (terms) and agreement2 (marketing consent) are consent decisions -- never default these to true without explicit user approval.",
         readOnly: false,
+        idempotent: false,
         inputSchema: MemberCreateInputSchema,
         handler: memberCreate,
     },
@@ -22,6 +23,7 @@ export const memberToolDefinitions = [
         title: "Get Member Profile",
         description: "Get member details including profile, points balance, and tier status. Use memberId from member_create or member_list.",
         readOnly: true,
+        idempotent: true,
         inputSchema: MemberGetInputSchema,
         handler: memberGet,
     },
@@ -31,6 +33,7 @@ export const memberToolDefinitions = [
         description: "Search and list members with optional filters. Use member_get for full details of a specific member. " +
             "Supports cursor pagination: provide 'cursor' from previous response to get next page.",
         readOnly: true,
+        idempotent: true,
         inputSchema: MemberListInputSchema,
         handler: memberList,
     },
@@ -39,6 +42,7 @@ export const memberToolDefinitions = [
         title: "Update Member Profile",
         description: "Update member profile fields. Cannot change email. Use member_get first to see current values.",
         readOnly: false,
+        idempotent: true,
         inputSchema: MemberUpdateInputSchema,
         handler: memberUpdate,
     },
@@ -47,6 +51,7 @@ export const memberToolDefinitions = [
         title: "Activate Member Account",
         description: "Activate a member account. Inactive members cannot earn or spend points.",
         readOnly: false,
+        idempotent: true,
         inputSchema: MemberIdInputSchema,
         handler: memberActivate,
     },
@@ -55,6 +60,7 @@ export const memberToolDefinitions = [
         title: "Deactivate Member Account",
         description: "Deactivate a member account. Deactivated members cannot earn or spend points but retain their balance.",
         readOnly: false,
+        idempotent: true,
         inputSchema: MemberIdInputSchema,
         handler: memberDeactivate,
     },
@@ -64,6 +70,7 @@ export const memberToolDefinitions = [
         description: "Permanently removes member and all associated data. Cannot be undone. Use for GDPR compliance or member requests.",
         readOnly: false,
         destructive: true,
+        idempotent: true,
         inputSchema: MemberIdInputSchema,
         handler: memberDelete,
     },
@@ -72,6 +79,7 @@ export const memberToolDefinitions = [
         title: "Check Tier Progress",
         description: "Get member tier progression status showing current tier and progress to next. Returns currentValue, requiredValue, and progressPercent.",
         readOnly: true,
+        idempotent: true,
         inputSchema: MemberIdInputSchema,
         handler: memberGetTierProgress,
     },
@@ -80,6 +88,7 @@ export const memberToolDefinitions = [
         title: "Assign Tier to Member",
         description: "Manually assign a tier level to a member, overriding automatic tier calculation. Use tierset_get_tiers to find available levelId values.",
         readOnly: false,
+        idempotent: true,
         inputSchema: MemberAssignTierInputSchema,
         handler: memberAssignTier,
     },
@@ -88,6 +97,7 @@ export const memberToolDefinitions = [
         title: "Remove Manual Tier Assignment",
         description: "Remove manually assigned tier from member, restoring automatic tier calculation based on conditions.",
         readOnly: false,
+        idempotent: true,
         inputSchema: MemberIdInputSchema,
         handler: memberRemoveManualTier,
     },

package/dist/tools/member/schemas.js

@@ -6,17 +6,17 @@ export const MemberCreateInputSchema = {
     lastName: z.string().optional().describe("Member last name."),
     phone: z.string().optional().describe("Member phone number."),
     birthDate: z.string().optional().describe("Member birth date (YYYY-MM-DD format)."),
-    gender: z.enum(["male", "female", "not_disclosed"]).optional().describe("Member gender."),
+    gender: z.enum(["male", "female", "not_disclosed"]).optional().describe("Member gender. Valid values: 'male', 'female', 'not_disclosed'."),
     loyaltyCardNumber: z.string().optional().describe("Loyalty card number. Auto-generated if not provided."),
     agreement1: z.boolean().optional().describe("Terms acceptance. BUSINESS DECISION: Legal requirement. Cannot default to true without explicit consent from the member."),
     agreement2: z.boolean().optional().describe("Marketing consent. BUSINESS IMPACT: GDPR violation risk. Defaulting marketing consent to true without explicit approval can result in fines up to 4% of annual revenue or EUR 20M. NEVER silently default to true."),
     agreement3: z.boolean().optional().describe("Additional agreement. Depends on store configuration."),
     address: z.object({
-        street: z.string().optional(),
-        city: z.string().optional(),
-        postal: z.string().optional(),
-        country: z.string().optional(),
-        province: z.string().optional(),
+        street: z.string().optional().describe("Street address (e.g., '123 Main St')."),
+        city: z.string().optional().describe("City name."),
+        postal: z.string().optional().describe("Postal/ZIP code."),
+        country: z.string().optional().describe("Country name or ISO 3166-1 code (e.g., 'US', 'Poland')."),
+        province: z.string().optional().describe("State, province, or region."),
     }).optional().describe("Member address."),
 };
 export const MemberGetInputSchema = {
@@ -42,13 +42,13 @@ export const MemberUpdateInputSchema = {
     lastName: z.string().optional().describe("Member last name."),
     phone: z.string().optional().describe("Member phone number."),
     birthDate: z.string().optional().describe("Member birth date (YYYY-MM-DD format)."),
-    gender: z.enum(["male", "female", "not_disclosed"]).optional().describe("Member gender."),
+    gender: z.enum(["male", "female", "not_disclosed"]).optional().describe("Member gender. Valid values: 'male', 'female', 'not_disclosed'."),
     address: z.object({
-        street: z.string().optional(),
-        city: z.string().optional(),
-        postal: z.string().optional(),
-        country: z.string().optional(),
-        province: z.string().optional(),
+        street: z.string().optional().describe("Street address (e.g., '123 Main St')."),
+        city: z.string().optional().describe("City name."),
+        postal: z.string().optional().describe("Postal/ZIP code."),
+        country: z.string().optional().describe("Country name or ISO 3166-1 code (e.g., 'US', 'Poland')."),
+        province: z.string().optional().describe("State, province, or region."),
     }).optional().describe("Member address."),
     agreement1: z.boolean().optional().describe("Terms acceptance. BUSINESS DECISION: Legal requirement. Cannot default to true without explicit consent."),
     agreement2: z.boolean().optional().describe("Marketing consent. BUSINESS IMPACT: GDPR violation risk. Changing marketing consent requires explicit member approval."),
@@ -61,5 +61,5 @@ export const MemberIdInputSchema = {
 export const MemberAssignTierInputSchema = {
     storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     memberId: z.string().describe("The member ID (UUID)."),
-    levelId: z.string().describe("The tier level ID (UUID) to assign."),
+    levelId: z.string().describe("The tier level ID (UUID) to assign. Use ol_tierset_get_tiers(tierSetId) to find valid levelId values."),
 };