@open-loyalty/mcp-server 1.0.3 → 1.3.1

package/dist/server.js

@@ -1,290 +1,57 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { getAllTools, getToolHandler, toolMetadata } from "./tools/index.js";
+import { z } from "zod";
+import { getAllTools, getToolHandler } from "./tools/index.js";
 import { OpenLoyaltyError } from "./utils/errors.js";
-const SERVER_INSTRUCTIONS = `
-Open Loyalty MCP Server - Complete Loyalty Program Management
-
-## Domain Model
-
-Member (loyalty program participant)
-  └── Points (wallet balance, transfers)
-  └── Tier (current level: Bronze, Silver, Gold)
-  └── Transactions (purchase history)
-  └── Rewards (redeemed coupons)
-  └── Achievements (gamification progress)
-  └── Badges (visual rewards from achievements)
-
-TierSet (loyalty program structure)
-  └── Conditions (criteria: activeUnits, totalSpending)
-  └── Tiers (levels with thresholds)
-
-WalletType (points currency configuration)
-
-Reward (redeemable items)
-  └── Categories (reward groupings)
-
-Campaign (automated points/rewards rules)
-  └── Type (earning, spending, custom, instant_reward)
-  └── Trigger (transaction, custom_event, points_transfer)
-  └── Rules (SKU, category, transaction amount conditions)
-  └── Effects (give_points, multiply_points, percentage_discount)
-  └── Targeting (segments, tiers for audience)
-
-Segment (member audience grouping)
-  └── Parts (groups of criteria - OR logic between parts)
-      └── Criteria (conditions - AND logic within part)
-          Types: purchase_period, transaction_count, average_transaction,
-                 anniversary, last_purchase_days, tier
-
-Achievement (gamification goals)
-  └── Trigger (transaction, custom_event, points_transfer, referral, login)
-  └── CompleteRule (periodGoal, period type, unique counting)
-  └── Badge (visual reward when completed)
-
-Badge (visual recognition)
-  └── Linked to achievements via badgeTypeId
-  └── Auto-created when referenced by achievement
-
-## Key Workflows
-
-### 1. Create 3-tier Loyalty Program:
-wallet_type_list → tierset_create → tierset_get → tierset_update_tiers
-
-### 2. Register and Reward Member:
-member_create → points_add (welcome bonus) → member_get (verify)
-
-### 3. Record Purchase and Earn Points:
-transaction_create (with customerData) → triggers campaigns → points auto-added
-
-### 4. Redeem Reward:
-reward_list → reward_buy (deducts points) → reward_redeem (mark coupon used)
-
-### 5. Assign Unmatched Transaction:
-transaction_list (matched=false) → transaction_assign_member → points earned
-
-### 6. Check Member Tier Progress:
-member_get_tier_progress → shows current tier, next tier, progress %
-
-### 7. Double Points for VIP Members:
-segment_create (with tier criteria for VIP level) → campaign_create (targeting that segment with give_points effect and multiplier: 2)
-
-### 8. Purchase Achievement with Badge:
-badge_list (find or note badgeTypeId) → achievement_create (trigger: transaction, periodGoal for amount, badgeTypeId)
-
-### 9. Create Targeted Promotion:
-segment_create (define audience) → campaign_create (type: earning, target: segment, segmentIds: [segmentId])
-
-### 10. Track Member Gamification:
-achievement_list_member_achievements → badge_get_member_badges → achievement_get_member_progress
-
-## Discovery Paths:
-- Members: member_list → member_get → points_get_balance
-- Tiers: tierset_list → tierset_get → tierset_get_tiers
-- Rewards: reward_category_list → reward_list → reward_get
-- Transactions: transaction_list → transaction_get
-- Campaigns: campaign_list → campaign_get → campaign_simulate
-- Segments: segment_list → segment_get → segment_get_members → campaign_create (audience targeting)
-- Achievements: achievement_list → badge_list → achievement_create (with badge)
-- Member Gamification: achievement_list_member_achievements → badge_get_member_badges
-
-## Important Patterns:
-- conditionId REQUIRED for tier thresholds - call tierset_get after tierset_create
-- Points operations: check balance with points_get_balance before spending
-- Reward flow: reward_buy returns couponCode, use reward_redeem to mark used
-- Transactions auto-match to members via customerData (email, phone, loyaltyCardNumber)
-
-### Pagination:
-- Traditional pagination: use page + perPage params
-- Cursor pagination: provide cursor from previous response for efficient deep pagination
-- Cursor-enabled tools: member_list, transaction_list, points_get_history
-- First scroll request: cursor="" (empty string)
-- Subsequent requests: use cursor value from previous response
-- When cursor provided, page param is ignored
-
-### Campaign Patterns:
-- Campaign types: earning (earn points), spending (spend points), custom (custom events), instant_reward
-- Triggers: transaction (purchase), custom_event, points_transfer, referral, registration
-- Effects: give_points, multiply_points, percentage_discount, fixed_discount
-- Target campaigns to segments or tiers using target: "segment" and segmentIds array
-
-### Segment Patterns:
-- Parts use OR logic (member matches ANY part)
-- Criteria within a part use AND logic (member must match ALL criteria in that part)
-- Common criteria: purchase_period (spending), transaction_count, average_transaction, anniversary, last_purchase_days, tier
-
-### Achievement Patterns:
-- Triggers: transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, registration, profile_update, login
-- periodGoal sets the target (e.g., 5 purchases, 1000 points spent)
-- period defines timeframe: day, week, month, year, forever
-- Link to badge via badgeTypeId - badge auto-created if doesn't exist
-- uniqueAttribute for counting distinct values (e.g., unique products)
-
-## Phase 3: Analytics, Admin, Roles & Stores
-
-### Domain Model (Extended)
-
-Admin (system user)
-  └── Roles (permission sets)
-      └── Permissions (resource + access level)
-  └── API Keys (programmatic access)
-
-Store (multi-tenant container)
-  └── Members, Campaigns, Rewards (isolated per store)
-
-Audit Log (compliance tracking)
-  └── eventType, entityType, entityId, username, timestamp
-
-### Analytics Workflows:
-
-#### 11. Get Program Overview:
-analytics_dashboard → analytics_tiers → analytics_members
-
-#### 12. Analyze Points Economy:
-analytics_points → analytics_units (per wallet) → points_get_histogram
-
-#### 13. Measure Campaign Performance:
-analytics_campaigns → analytics_campaign_detail (specific campaign)
-
-#### 14. Track Transactions:
-analytics_transactions → transaction_list (details)
-
-### Aggregation Queries (Top Spenders, Purchase Analysis):
-
-IMPORTANT: For queries like "top 5 spenders in July 2025", use this approach:
-
-#### 15. Find Top Spenders by Date Range:
-1. transaction_list(purchasedAtFrom, purchasedAtTo, perPage=50, cursor='') - returns customerId with each transaction
-2. Use cursor pagination to fetch ALL pages - even if there are 1000+ transactions
-3. Aggregate grossValue by customerId in your code
-4. Sort by total spent, take top N
-5. member_get for each top spender to get names/details
-
-CRITICAL - DO NOT TRY TO BE SMART OR OPTIMIZE:
-- ALWAYS iterate through ALL pages using cursor pagination - this is the ONLY correct approach
-- DO NOT skip pages or try to sample data - you will get inaccurate results
-- DO NOT use transaction_get individually - transaction_list already includes customerId
-- DO NOT try to find "smarter" analytics endpoints - they don't exist for per-customer aggregation
-- Large datasets (1000+ transactions) are normal - just keep paginating until cursor is empty
-- Start with cursor='' (empty string), use returned cursor for next request, repeat until done
-
-Example: Top 5 spenders July 2025
-- First request: transaction_list(purchasedAtFrom: "2025-07-01", purchasedAtTo: "2025-07-31", perPage: 50, cursor: "")
-- Each result includes: transactionId, grossValue, customerId, purchasedAt
-- Keep fetching with returned cursor until response has no cursor or empty transactions
-- Even if there are 1500 transactions (30 pages), iterate through ALL of them
-- Group by customerId, sum grossValue, sort descending, take 5
-
-### Admin & Security Workflows:
-
-#### 15. Create Admin with Limited Role:
-acl_get_resources → role_create → admin_create (with roleId)
-
-#### 16. Generate API Key for Integration:
-admin_get → apikey_create → SAVE TOKEN IMMEDIATELY (shown once!)
-
-#### 17. Audit User Actions:
-audit_list (filter by username/entity) → audit_export (compliance report)
-
-### Store Multi-Tenancy:
-
-#### 18. Create New Store:
-store_create → configure campaigns/tiers → member_create (with storeCode)
-
-### Analytics Query Patterns:
-- All analytics tools support dateFrom/dateTo ISO date filters
-- analytics_dashboard: high-level program metrics
-- analytics_units: wallet-specific metrics (requires walletTypeCode)
-- analytics_campaign_detail: detailed metrics for single campaign
-
-### Admin → Role → Permission Model:
-┌─────────┐     ┌──────┐     ┌────────────┐
-│  Admin  │────▶│ Role │────▶│ Permission │
-└─────────┘     └──────┘     └────────────┘
-     │                            │
-     │                       resource + access
-     │                       (VIEW, MODIFY, etc.)
-     ▼
-┌─────────┐
-│ API Key │
-└─────────┘
-
-### Store Multi-Tenancy:
-- Each store is isolated: members, campaigns, rewards, transactions
-- storeCode parameter routes requests to correct tenant
-- Default store used when storeCode omitted
-
-## Phase 4: Webhooks, Import & Export
-
-### Domain Model (Extended)
-
-Webhook Subscription (event notification)
-  └── eventName (event to subscribe to)
-  └── url (callback endpoint)
-  └── headers (custom HTTP headers)
-
-Import (bulk data upload)
-  └── type: member, groupValue, segmentMembers, unitTransferAdding, etc.
-  └── status: pending, processing, succeed, failed
-  └── items (individual row results)
-
-Export (bulk data download)
-  └── type: campaignCode, member, memberTier, memberSegment, rewardFulfillment
-  └── status: pending, done, failed, error
-  └── CSV file (when status='done')
-
-### Webhook Workflows:
-
-#### 19. Subscribe to Member Events for CRM Sync:
-webhook_events → webhook_create (eventName: 'member.created', url: 'https://crm.example.com/webhook')
-
-#### 20. List and Manage Subscriptions:
-webhook_list → webhook_get → webhook_update or webhook_delete
-
-### Import Workflows:
-
-#### 21. Bulk Import Members from CSV:
-import_create (type: 'member', fileContent: CSV data) → import_list → import_get (check status)
-
-#### 22. Bulk Add Points to Members:
-import_create (type: 'unitTransferAdding', fileContent: CSV) → poll import_get until complete
-
-### Export Workflows:
-
-#### 23. Export Campaign Codes:
-export_create (type: 'campaignCode', filters: { campaignId }) → poll export_get (until status='done') → export_download
-
-#### 24. Export Member Data:
-export_create (type: 'member') → export_get → export_download (returns CSV)
-
-### Webhook Patterns:
-- Use webhook_events to discover available event types before subscribing
-- API uses wrapper: { webhookSubscription: { eventName, url, headers? } }
-- Common events: member.created, member.updated, transaction.created, reward.purchased
-
-### Import Patterns:
-- Import is async: create returns importId, poll status with import_get
-- CSV format required - provide plain text, not base64
-- Types: member, groupValue, segmentMembers, unitTransferAdding, unitTransferSpending, transaction, campaignCode, rewardCoupon
-
-### Export Patterns:
-- Export is async: create returns exportId, poll status until 'done'
-- API body wrapper varies by type: { campaignCode: { filters... } }
-- Only call export_download when status='done'
-- Types: campaignCode, member, memberTier, memberSegment, rewardFulfillment
-`;
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
+/**
+ * Convert an inputSchema object (Record<string, ZodType>) to a Zod object schema.
+ * This allows centralized validation of all tool inputs.
+ */
+function createZodSchema(inputSchema) {
+    return z.object(inputSchema);
+}
+const TOOL_WRAPPER_KEYS = {
+    ol_tierset_create: "tierSet",
+    ol_tierset_update: "tierSet",
+    ol_campaign_create: "campaign",
+    ol_campaign_update: "campaign",
+};
+function normalizeToolInput(toolName, args) {
+    if (!args || typeof args !== "object" || Array.isArray(args)) {
+        return args;
+    }
+    const wrapperKey = TOOL_WRAPPER_KEYS[toolName];
+    if (!wrapperKey) {
+        return args;
+    }
+    const record = args;
+    const wrapped = record[wrapperKey];
+    if (!wrapped || typeof wrapped !== "object" || Array.isArray(wrapped)) {
+        return args;
+    }
+    const { [wrapperKey]: _wrapper, ...rest } = record;
+    const merged = {
+        ...rest,
+        ...wrapped,
+    };
+    return merged;
+}
 export function createServer() {
     const server = new McpServer({
         name: "openloyalty",
-        version: "1.0.0",
+        version: "1.3.0",
     });
     const tools = getAllTools();
     for (const tool of tools) {
-        const metadata = toolMetadata[tool.name];
         server.registerTool(tool.name, {
-            title: metadata?.title,
+            title: tool.title,
             description: tool.description,
             inputSchema: tool.inputSchema,
-            annotations: metadata?.annotations,
+            annotations: {
+                readOnlyHint: tool.readOnly,
+                destructiveHint: tool.destructive,
+                openWorldHint: true,
+            },
         }, async (args) => {
             const handler = getToolHandler(tool.name);
             if (!handler) {
@@ -299,12 +66,35 @@ export function createServer() {
                 };
             }
             try {
-                const result = await handler(args);
+                // Validate input against the tool's Zod schema
+                const schema = createZodSchema(tool.inputSchema);
+                let parseResult = schema.safeParse(args);
+                if (!parseResult.success) {
+                    const normalizedArgs = normalizeToolInput(tool.name, args);
+                    if (normalizedArgs !== args) {
+                        const retryResult = schema.safeParse(normalizedArgs);
+                        if (retryResult.success) {
+                            parseResult = retryResult;
+                        }
+                    }
+                }
+                if (!parseResult.success) {
+                    const issues = parseResult.error.issues
+                        .map((i) => `${i.path.join(".") || "input"}: ${i.message}`)
+                        .join("; ");
+                    throw new OpenLoyaltyError({
+                        code: "VALIDATION_ERROR",
+                        message: "Invalid input parameters",
+                        hint: `Fix the following validation errors: ${issues}`,
+                        relatedTool: tool.name,
+                    });
+                }
+                const result = await handler(parseResult.data);
                 return {
                     content: [
                         {
                             type: "text",
-                            text: result === undefined ? "Success" : JSON.stringify(result, null, 2),
+                            text: result === undefined ? "Success" : JSON.stringify(result, null, process.env.MCP_DEBUG === "true" ? 2 : undefined),
                         },
                     ],
                 };

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

@@ -0,0 +1,117 @@
+import { AchievementListItem } from "../../types/schemas/achievement.js";
+export declare function achievementList(input: {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+    active?: boolean;
+    name?: string;
+}): Promise<{
+    achievements: AchievementListItem[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+interface AchievementCreateInput {
+    storeCode?: string;
+    translations: Record<string, {
+        name: string;
+        description?: string;
+    }>;
+    active?: boolean;
+    activity?: {
+        startsAt?: string;
+        endsAt?: string;
+        operator?: string;
+    };
+    limit?: {
+        value?: number;
+        interval?: {
+            type: string;
+            value?: number;
+        };
+    };
+    rules: Array<Record<string, unknown>>;
+    badgeTypeId?: string;
+}
+export declare function achievementCreate(input: AchievementCreateInput): Promise<{
+    achievementId: string;
+}>;
+export declare function achievementGet(input: {
+    storeCode?: string;
+    achievementId: string;
+}): Promise<Record<string, unknown>>;
+interface AchievementUpdateInput {
+    storeCode?: string;
+    achievementId: string;
+    translations: Record<string, {
+        name: string;
+        description?: string;
+    }>;
+    active?: boolean;
+    activity?: {
+        startsAt?: string;
+        endsAt?: string;
+        operator?: string;
+    };
+    limit?: {
+        value?: number;
+        interval?: {
+            type: string;
+            value?: number;
+        };
+    };
+    rules: Array<Record<string, unknown>>;
+    badgeTypeId?: string;
+}
+export declare function achievementUpdate(input: AchievementUpdateInput): Promise<void>;
+interface AchievementPatchInput {
+    storeCode?: string;
+    achievementId: string;
+    active?: boolean;
+    translations?: Record<string, {
+        name?: string;
+        description?: string;
+    }>;
+}
+export declare function achievementPatch(input: AchievementPatchInput): Promise<void>;
+export interface AchievementMemberProgress {
+    achievementId: string;
+    achievementName?: string;
+    achievementDescription?: string;
+    limitReached?: boolean;
+    memberProgress: {
+        completedCount: number;
+        rules: Array<{
+            achievementRuleId: string;
+            periodGoal: number;
+            currentPeriodValue: number;
+            consecutivePeriods?: number;
+            completedConsecutivePeriods?: number;
+            periodType?: string;
+            type?: string;
+            trigger?: string;
+            periodValue?: number;
+        }>;
+    };
+}
+export declare function achievementGetMemberProgress(input: {
+    storeCode?: string;
+    memberId: string;
+    achievementId: string;
+}): Promise<AchievementMemberProgress>;
+export declare function achievementListMemberAchievements(input: {
+    storeCode?: string;
+    memberId: string;
+    page?: number;
+    perPage?: number;
+    name?: string;
+    achievementId?: string;
+}): Promise<{
+    achievements: AchievementMemberProgress[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export {};

package/dist/tools/achievement/handlers.js

@@ -0,0 +1,161 @@
+import { apiGet, apiPost, apiPut, apiPatch } from "../../client/http.js";
+import { formatApiError } from "../../utils/errors.js";
+import { getStoreCode } from "../../config.js";
+export async function achievementList(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.active !== undefined)
+        params.append("active", String(input.active));
+    if (input.name)
+        params.append("name", input.name);
+    const queryString = params.toString();
+    const url = `/${storeCode}/achievement${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const achievements = (response.items || []).map((item) => ({
+            achievementId: item.achievementId,
+            name: item.name,
+            active: item.active,
+            createdAt: item.createdAt,
+            badgeTypeId: item.badgeTypeId,
+        }));
+        const total = response.total || {};
+        return {
+            achievements,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_achievement_list");
+    }
+}
+export async function achievementCreate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const achievementPayload = {
+        translations: input.translations,
+        rules: input.rules,
+    };
+    if (input.active !== undefined)
+        achievementPayload.active = input.active;
+    if (input.activity)
+        achievementPayload.activity = input.activity;
+    if (input.limit)
+        achievementPayload.limit = input.limit;
+    if (input.badgeTypeId)
+        achievementPayload.badgeTypeId = input.badgeTypeId;
+    try {
+        // CRITICAL: Wrap body as { achievement: {...} }
+        const response = await apiPost(`/${storeCode}/achievement`, { achievement: achievementPayload });
+        return { achievementId: response.achievementId };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_achievement_create");
+    }
+}
+export async function achievementGet(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/achievement/${input.achievementId}`);
+        return response;
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_achievement_get");
+    }
+}
+export async function achievementUpdate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const achievementPayload = {
+        translations: input.translations,
+        rules: input.rules,
+    };
+    if (input.active !== undefined)
+        achievementPayload.active = input.active;
+    if (input.activity)
+        achievementPayload.activity = input.activity;
+    if (input.limit)
+        achievementPayload.limit = input.limit;
+    if (input.badgeTypeId !== undefined)
+        achievementPayload.badgeTypeId = input.badgeTypeId;
+    try {
+        // CRITICAL: Wrap body as { achievement: {...} }
+        await apiPut(`/${storeCode}/achievement/${input.achievementId}`, { achievement: achievementPayload });
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_achievement_update");
+    }
+}
+export async function achievementPatch(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const achievementPayload = {};
+    if (input.active !== undefined)
+        achievementPayload.active = input.active;
+    if (input.translations)
+        achievementPayload.translations = input.translations;
+    try {
+        // CRITICAL: Wrap body as { achievement: {...} }
+        await apiPatch(`/${storeCode}/achievement/${input.achievementId}`, { achievement: achievementPayload });
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_achievement_patch");
+    }
+}
+export async function achievementGetMemberProgress(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        // Try the member achievements list endpoint with achievementId filter
+        // The direct /achievement/{id} endpoint may not exist
+        const response = await apiGet(`/${storeCode}/member/${input.memberId}/achievement?achievementId=${input.achievementId}`);
+        // Return first matching achievement
+        const achievements = response.items || [];
+        if (achievements.length === 0) {
+            // If no achievements found, return empty progress
+            return {
+                achievementId: input.achievementId,
+                memberProgress: {
+                    completedCount: 0,
+                    rules: [],
+                },
+            };
+        }
+        return achievements[0];
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_achievement_get_member_progress");
+    }
+}
+export async function achievementListMemberAchievements(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.name)
+        params.append("name", input.name);
+    if (input.achievementId)
+        params.append("achievementId", input.achievementId);
+    const queryString = params.toString();
+    const url = `/${storeCode}/member/${input.memberId}/achievement${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const achievements = response.items || [];
+        const total = response.total || {};
+        return {
+            achievements,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_achievement_list_member_achievements");
+    }
+}