@open-loyalty/mcp-server 1.0.0

package/dist/client/http.js

@@ -0,0 +1,69 @@
+import axios from "axios";
+import { getConfig } from "../config.js";
+let client = null;
+// For testing: reset the client singleton
+export function resetHttpClient() {
+    client = null;
+}
+// For testing: get the underlying axios instance
+export function getAxiosInstance() {
+    return getClient();
+}
+function getClient() {
+    if (client) {
+        return client;
+    }
+    const config = getConfig();
+    client = axios.create({
+        baseURL: config.apiUrl,
+        timeout: 30000,
+        headers: {
+            "Content-Type": "application/json",
+        },
+    });
+    client.interceptors.request.use((requestConfig) => {
+        const cfg = getConfig();
+        requestConfig.headers.set("X-AUTH-TOKEN", cfg.apiToken);
+        return requestConfig;
+    }, (error) => {
+        console.error("Request interceptor error:", error.message);
+        return Promise.reject(error);
+    });
+    client.interceptors.response.use((response) => response, (error) => {
+        if (error.response) {
+            const status = error.response.status;
+            const data = error.response.data;
+            console.error(`API Error [${status}]:`, JSON.stringify(data, null, 2));
+            if (status === 401) {
+                throw new Error("Authentication failed (401): Invalid or expired API token. " +
+                    "Please check your OPENLOYALTY_API_TOKEN environment variable.");
+            }
+            if (status === 403) {
+                throw new Error("Access denied (403): You do not have permission to access this resource. " +
+                    "Please check your API token permissions.");
+            }
+        }
+        return Promise.reject(error);
+    });
+    return client;
+}
+export async function apiGet(url) {
+    const response = await getClient().get(url);
+    return response.data;
+}
+export async function apiPost(url, data) {
+    const response = await getClient().post(url, data);
+    return response.data;
+}
+export async function apiPut(url, data) {
+    const response = await getClient().put(url, data);
+    return response.data;
+}
+export async function apiDelete(url) {
+    const response = await getClient().delete(url);
+    return response.data;
+}
+export async function apiPatch(url, data) {
+    const response = await getClient().patch(url, data);
+    return response.data;
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+declare const ConfigSchema: z.ZodObject<{
+    apiUrl: z.ZodString;
+    apiToken: z.ZodString;
+    defaultStoreCode: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    apiUrl: string;
+    apiToken: string;
+    defaultStoreCode: string;
+}, {
+    apiUrl: string;
+    apiToken: string;
+    defaultStoreCode: string;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function getConfig(): Config;
+export {};

package/dist/config.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+const ConfigSchema = z.object({
+    apiUrl: z.string().url(),
+    apiToken: z.string().min(1),
+    defaultStoreCode: z.string().min(1),
+});
+let config = null;
+export function getConfig() {
+    if (config) {
+        return config;
+    }
+    const apiUrl = process.env.OPENLOYALTY_API_URL;
+    const apiToken = process.env.OPENLOYALTY_API_TOKEN;
+    const defaultStoreCode = process.env.OPENLOYALTY_DEFAULT_STORE_CODE;
+    if (!apiUrl) {
+        throw new Error("Missing required environment variable: OPENLOYALTY_API_URL. " +
+            "Please set this to your Open Loyalty API URL (e.g., https://api.openloyalty.io)");
+    }
+    if (!apiToken) {
+        throw new Error("Missing required environment variable: OPENLOYALTY_API_TOKEN. " +
+            "Please set this to your Open Loyalty API authentication token");
+    }
+    if (!defaultStoreCode) {
+        throw new Error("Missing required environment variable: OPENLOYALTY_DEFAULT_STORE_CODE. " +
+            "Please set this to your default store code (e.g., default)");
+    }
+    const result = ConfigSchema.safeParse({
+        apiUrl,
+        apiToken,
+        defaultStoreCode,
+    });
+    if (!result.success) {
+        const errors = result.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join(", ");
+        throw new Error(`Invalid configuration: ${errors}`);
+    }
+    config = result.data;
+    return config;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { getConfig } from "./config.js";
+async function main() {
+    try {
+        getConfig();
+    }
+    catch (error) {
+        console.error("Configuration error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+declare const SERVER_INSTRUCTIONS = "\nOpen Loyalty MCP Server - Complete Loyalty Program Management\n\n## Domain Model\n\nMember (loyalty program participant)\n  \u2514\u2500\u2500 Points (wallet balance, transfers)\n  \u2514\u2500\u2500 Tier (current level: Bronze, Silver, Gold)\n  \u2514\u2500\u2500 Transactions (purchase history)\n  \u2514\u2500\u2500 Rewards (redeemed coupons)\n  \u2514\u2500\u2500 Achievements (gamification progress)\n  \u2514\u2500\u2500 Badges (visual rewards from achievements)\n\nTierSet (loyalty program structure)\n  \u2514\u2500\u2500 Conditions (criteria: activeUnits, totalSpending)\n  \u2514\u2500\u2500 Tiers (levels with thresholds)\n\nWalletType (points currency configuration)\n\nReward (redeemable items)\n  \u2514\u2500\u2500 Categories (reward groupings)\n\nCampaign (automated points/rewards rules)\n  \u2514\u2500\u2500 Type (earning, spending, custom, instant_reward)\n  \u2514\u2500\u2500 Trigger (transaction, custom_event, points_transfer)\n  \u2514\u2500\u2500 Rules (SKU, category, transaction amount conditions)\n  \u2514\u2500\u2500 Effects (give_points, multiply_points, percentage_discount)\n  \u2514\u2500\u2500 Targeting (segments, tiers for audience)\n\nSegment (member audience grouping)\n  \u2514\u2500\u2500 Parts (groups of criteria - OR logic between parts)\n      \u2514\u2500\u2500 Criteria (conditions - AND logic within part)\n          Types: purchase_period, transaction_count, average_transaction,\n                 anniversary, last_purchase_days, tier\n\nAchievement (gamification goals)\n  \u2514\u2500\u2500 Trigger (transaction, custom_event, points_transfer, referral, login)\n  \u2514\u2500\u2500 CompleteRule (periodGoal, period type, unique counting)\n  \u2514\u2500\u2500 Badge (visual reward when completed)\n\nBadge (visual recognition)\n  \u2514\u2500\u2500 Linked to achievements via badgeTypeId\n  \u2514\u2500\u2500 Auto-created when referenced by achievement\n\n## Key Workflows\n\n### 1. Create 3-tier Loyalty Program:\nwallet_type_list \u2192 tierset_create \u2192 tierset_get \u2192 tierset_update_tiers\n\n### 2. Register and Reward Member:\nmember_create \u2192 points_add (welcome bonus) \u2192 member_get (verify)\n\n### 3. Record Purchase and Earn Points:\ntransaction_create (with customerData) \u2192 triggers campaigns \u2192 points auto-added\n\n### 4. Redeem Reward:\nreward_list \u2192 reward_buy (deducts points) \u2192 reward_redeem (mark coupon used)\n\n### 5. Assign Unmatched Transaction:\ntransaction_list (matched=false) \u2192 transaction_assign_member \u2192 points earned\n\n### 6. Check Member Tier Progress:\nmember_get_tier_progress \u2192 shows current tier, next tier, progress %\n\n### 7. Double Points for VIP Members:\nsegment_create (with tier criteria for VIP level) \u2192 campaign_create (targeting that segment with give_points effect and multiplier: 2)\n\n### 8. Purchase Achievement with Badge:\nbadge_list (find or note badgeTypeId) \u2192 achievement_create (trigger: transaction, periodGoal for amount, badgeTypeId)\n\n### 9. Create Targeted Promotion:\nsegment_create (define audience) \u2192 campaign_create (type: earning, target: segment, segmentIds: [segmentId])\n\n### 10. Track Member Gamification:\nachievement_list_member_achievements \u2192 badge_get_member_badges \u2192 achievement_get_member_progress\n\n## Discovery Paths:\n- Members: member_list \u2192 member_get \u2192 points_get_balance\n- Tiers: tierset_list \u2192 tierset_get \u2192 tierset_get_tiers\n- Rewards: reward_category_list \u2192 reward_list \u2192 reward_get\n- Transactions: transaction_list \u2192 transaction_get\n- Campaigns: campaign_list \u2192 campaign_get \u2192 campaign_simulate\n- Segments: segment_list \u2192 segment_get \u2192 segment_get_members \u2192 campaign_create (audience targeting)\n- Achievements: achievement_list \u2192 badge_list \u2192 achievement_create (with badge)\n- Member Gamification: achievement_list_member_achievements \u2192 badge_get_member_badges\n\n## Important Patterns:\n- conditionId REQUIRED for tier thresholds - call tierset_get after tierset_create\n- Points operations: check balance with points_get_balance before spending\n- Reward flow: reward_buy returns couponCode, use reward_redeem to mark used\n- Transactions auto-match to members via customerData (email, phone, loyaltyCardNumber)\n\n### Pagination:\n- Traditional pagination: use page + perPage params\n- Cursor pagination: provide cursor from previous response for efficient deep pagination\n- Cursor-enabled tools: member_list, transaction_list, points_get_history\n- First scroll request: cursor=\"\" (empty string)\n- Subsequent requests: use cursor value from previous response\n- When cursor provided, page param is ignored\n\n### Campaign Patterns:\n- Campaign types: earning (earn points), spending (spend points), custom (custom events), instant_reward\n- Triggers: transaction (purchase), custom_event, points_transfer, referral, registration\n- Effects: give_points, multiply_points, percentage_discount, fixed_discount\n- Target campaigns to segments or tiers using target: \"segment\" and segmentIds array\n\n### Segment Patterns:\n- Parts use OR logic (member matches ANY part)\n- Criteria within a part use AND logic (member must match ALL criteria in that part)\n- Common criteria: purchase_period (spending), transaction_count, average_transaction, anniversary, last_purchase_days, tier\n\n### Achievement Patterns:\n- Triggers: transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, registration, profile_update, login\n- periodGoal sets the target (e.g., 5 purchases, 1000 points spent)\n- period defines timeframe: day, week, month, year, forever\n- Link to badge via badgeTypeId - badge auto-created if doesn't exist\n- uniqueAttribute for counting distinct values (e.g., unique products)\n\n## Phase 3: Analytics, Admin, Roles & Stores\n\n### Domain Model (Extended)\n\nAdmin (system user)\n  \u2514\u2500\u2500 Roles (permission sets)\n      \u2514\u2500\u2500 Permissions (resource + access level)\n  \u2514\u2500\u2500 API Keys (programmatic access)\n\nStore (multi-tenant container)\n  \u2514\u2500\u2500 Members, Campaigns, Rewards (isolated per store)\n\nAudit Log (compliance tracking)\n  \u2514\u2500\u2500 eventType, entityType, entityId, username, timestamp\n\n### Analytics Workflows:\n\n#### 11. Get Program Overview:\nanalytics_dashboard \u2192 analytics_tiers \u2192 analytics_members\n\n#### 12. Analyze Points Economy:\nanalytics_points \u2192 analytics_units (per wallet) \u2192 points_get_histogram\n\n#### 13. Measure Campaign Performance:\nanalytics_campaigns \u2192 analytics_campaign_detail (specific campaign)\n\n#### 14. Track Transactions:\nanalytics_transactions \u2192 transaction_list (details)\n\n### Aggregation Queries (Top Spenders, Purchase Analysis):\n\nIMPORTANT: For queries like \"top 5 spenders in July 2025\", use this approach:\n\n#### 15. Find Top Spenders by Date Range:\n1. transaction_list(purchasedAtFrom, purchasedAtTo, perPage=50, cursor='') - returns customerId with each transaction\n2. Use cursor pagination to fetch ALL pages - even if there are 1000+ transactions\n3. Aggregate grossValue by customerId in your code\n4. Sort by total spent, take top N\n5. member_get for each top spender to get names/details\n\nCRITICAL - DO NOT TRY TO BE SMART OR OPTIMIZE:\n- ALWAYS iterate through ALL pages using cursor pagination - this is the ONLY correct approach\n- DO NOT skip pages or try to sample data - you will get inaccurate results\n- DO NOT use transaction_get individually - transaction_list already includes customerId\n- DO NOT try to find \"smarter\" analytics endpoints - they don't exist for per-customer aggregation\n- Large datasets (1000+ transactions) are normal - just keep paginating until cursor is empty\n- Start with cursor='' (empty string), use returned cursor for next request, repeat until done\n\nExample: Top 5 spenders July 2025\n- First request: transaction_list(purchasedAtFrom: \"2025-07-01\", purchasedAtTo: \"2025-07-31\", perPage: 50, cursor: \"\")\n- Each result includes: transactionId, grossValue, customerId, purchasedAt\n- Keep fetching with returned cursor until response has no cursor or empty transactions\n- Even if there are 1500 transactions (30 pages), iterate through ALL of them\n- Group by customerId, sum grossValue, sort descending, take 5\n\n### Admin & Security Workflows:\n\n#### 15. Create Admin with Limited Role:\nacl_get_resources \u2192 role_create \u2192 admin_create (with roleId)\n\n#### 16. Generate API Key for Integration:\nadmin_get \u2192 apikey_create \u2192 SAVE TOKEN IMMEDIATELY (shown once!)\n\n#### 17. Audit User Actions:\naudit_list (filter by username/entity) \u2192 audit_export (compliance report)\n\n### Store Multi-Tenancy:\n\n#### 18. Create New Store:\nstore_create \u2192 configure campaigns/tiers \u2192 member_create (with storeCode)\n\n### Analytics Query Patterns:\n- All analytics tools support dateFrom/dateTo ISO date filters\n- analytics_dashboard: high-level program metrics\n- analytics_units: wallet-specific metrics (requires walletTypeCode)\n- analytics_campaign_detail: detailed metrics for single campaign\n\n### Admin \u2192 Role \u2192 Permission Model:\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502  Admin  \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 Role \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 Permission \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n     \u2502                            \u2502\n     \u2502                       resource + access\n     \u2502                       (VIEW, MODIFY, etc.)\n     \u25BC\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 API Key \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n### Store Multi-Tenancy:\n- Each store is isolated: members, campaigns, rewards, transactions\n- storeCode parameter routes requests to correct tenant\n- Default store used when storeCode omitted\n\n## Phase 4: Webhooks, Import & Export\n\n### Domain Model (Extended)\n\nWebhook Subscription (event notification)\n  \u2514\u2500\u2500 eventName (event to subscribe to)\n  \u2514\u2500\u2500 url (callback endpoint)\n  \u2514\u2500\u2500 headers (custom HTTP headers)\n\nImport (bulk data upload)\n  \u2514\u2500\u2500 type: member, groupValue, segmentMembers, unitTransferAdding, etc.\n  \u2514\u2500\u2500 status: pending, processing, succeed, failed\n  \u2514\u2500\u2500 items (individual row results)\n\nExport (bulk data download)\n  \u2514\u2500\u2500 type: campaignCode, member, memberTier, memberSegment, rewardFulfillment\n  \u2514\u2500\u2500 status: pending, done, failed, error\n  \u2514\u2500\u2500 CSV file (when status='done')\n\n### Webhook Workflows:\n\n#### 19. Subscribe to Member Events for CRM Sync:\nwebhook_events \u2192 webhook_create (eventName: 'member.created', url: 'https://crm.example.com/webhook')\n\n#### 20. List and Manage Subscriptions:\nwebhook_list \u2192 webhook_get \u2192 webhook_update or webhook_delete\n\n### Import Workflows:\n\n#### 21. Bulk Import Members from CSV:\nimport_create (type: 'member', fileContent: CSV data) \u2192 import_list \u2192 import_get (check status)\n\n#### 22. Bulk Add Points to Members:\nimport_create (type: 'unitTransferAdding', fileContent: CSV) \u2192 poll import_get until complete\n\n### Export Workflows:\n\n#### 23. Export Campaign Codes:\nexport_create (type: 'campaignCode', filters: { campaignId }) \u2192 poll export_get (until status='done') \u2192 export_download\n\n#### 24. Export Member Data:\nexport_create (type: 'member') \u2192 export_get \u2192 export_download (returns CSV)\n\n### Webhook Patterns:\n- Use webhook_events to discover available event types before subscribing\n- API uses wrapper: { webhookSubscription: { eventName, url, headers? } }\n- Common events: member.created, member.updated, transaction.created, reward.purchased\n\n### Import Patterns:\n- Import is async: create returns importId, poll status with import_get\n- CSV format required - provide plain text, not base64\n- Types: member, groupValue, segmentMembers, unitTransferAdding, unitTransferSpending, transaction, campaignCode, rewardCoupon\n\n### Export Patterns:\n- Export is async: create returns exportId, poll status until 'done'\n- API body wrapper varies by type: { campaignCode: { filters... } }\n- Only call export_download when status='done'\n- Types: campaignCode, member, memberTier, memberSegment, rewardFulfillment\n";
+export declare function createServer(): McpServer;
+export { SERVER_INSTRUCTIONS };

package/dist/server.js

@@ -0,0 +1,334 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { getAllTools, getToolHandler, toolMetadata } 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
+`;
+export function createServer() {
+    const server = new McpServer({
+        name: "openloyalty",
+        version: "1.0.0",
+    });
+    const tools = getAllTools();
+    for (const tool of tools) {
+        const metadata = toolMetadata[tool.name];
+        server.registerTool(tool.name, {
+            title: metadata?.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: metadata?.annotations,
+        }, async (args) => {
+            const handler = getToolHandler(tool.name);
+            if (!handler) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Tool handler not found: ${tool.name}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            try {
+                const result = await handler(args);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: result === undefined ? "Success" : JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                let errorText;
+                if (error instanceof OpenLoyaltyError) {
+                    errorText = `Error: ${error.message}\nCode: ${error.code}\nHint: ${error.hint}`;
+                }
+                else {
+                    errorText = `Error: ${error instanceof Error ? error.message : String(error)}`;
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: errorText,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    return server;
+}
+export { SERVER_INSTRUCTIONS };