@open-loyalty/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Open Loyalty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,654 @@
+# Open Loyalty MCP Server
+
+MCP (Model Context Protocol) server for interacting with Open Loyalty API. This server enables AI agents like Claude to manage loyalty programs, members, points, rewards, and transactions.
+
+## Prerequisites
+
+- Node.js 18 or later
+- An Open Loyalty account with API access
+
+## Installation
+
+### Via npm (Recommended)
+
+```bash
+npm install -g @openloyalty/mcp-server
+```
+
+Or use directly with npx (no installation required):
+
+```bash
+npx @openloyalty/mcp-server
+```
+
+### From Source
+
+```bash
+git clone https://github.com/openloyalty/mcp-server.git
+cd mcp-server
+npm install
+npm run build
+```
+
+## Configuration
+
+The server requires the following environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `OPENLOYALTY_API_URL` | Your Open Loyalty API URL (e.g., `https://api.openloyalty.io`) |
+| `OPENLOYALTY_API_TOKEN` | Your API authentication token |
+| `OPENLOYALTY_DEFAULT_STORE_CODE` | Default store code (e.g., `default`) |
+
+For local development, create a `.env` file based on `.env.example`:
+
+```bash
+cp .env.example .env
+```
+
+## Claude Desktop Configuration
+
+Add this to your Claude Desktop configuration file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Using npx (Recommended)
+
+```json
+{
+  "mcpServers": {
+    "openloyalty": {
+      "command": "npx",
+      "args": ["-y", "@openloyalty/mcp-server"],
+      "env": {
+        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
+        "OPENLOYALTY_API_TOKEN": "your-api-token",
+        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
+      }
+    }
+  }
+}
+```
+
+### Using Global Installation
+
+```json
+{
+  "mcpServers": {
+    "openloyalty": {
+      "command": "openloyalty-mcp",
+      "env": {
+        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
+        "OPENLOYALTY_API_TOKEN": "your-api-token",
+        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
+      }
+    }
+  }
+}
+```
+
+### Using Local Build
+
+```json
+{
+  "mcpServers": {
+    "openloyalty": {
+      "command": "node",
+      "args": ["/path/to/mcp-server/dist/index.js"],
+      "env": {
+        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
+        "OPENLOYALTY_API_TOKEN": "your-api-token",
+        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Run in development mode
+npm run dev
+
+# Build for production
+npm run build
+
+# Run tests
+npm test
+
+# Type checking
+npm run typecheck
+```
+
+## Available Tools (112 total)
+
+### Wallet Types (2 tools)
+- `openloyalty_wallet_type_list` - List all wallet types (point currencies)
+- `openloyalty_wallet_type_get` - Get details for a specific wallet type
+
+### Tier Sets (6 tools)
+- `openloyalty_tierset_list` - List all tier sets
+- `openloyalty_tierset_create` - Create a new tier set
+- `openloyalty_tierset_get` - Get tier set details with condition IDs
+- `openloyalty_tierset_update` - Update tier set metadata
+- `openloyalty_tierset_update_tiers` - Define tier thresholds
+- `openloyalty_tierset_get_tiers` - Get all tiers in a tier set
+
+### Members (10 tools)
+- `openloyalty_member_create` - Register a new loyalty program member
+- `openloyalty_member_get` - Get member details including profile, points balance, and tier status
+- `openloyalty_member_list` - Search and list members with optional filters
+- `openloyalty_member_update` - Update member profile fields
+- `openloyalty_member_activate` - Activate a deactivated member
+- `openloyalty_member_deactivate` - Deactivate an active member
+- `openloyalty_member_delete` - Permanently remove member (GDPR compliance)
+- `openloyalty_member_get_tier_progress` - Get tier progression status
+- `openloyalty_member_assign_tier` - Manually assign tier to member
+- `openloyalty_member_remove_manual_tier` - Remove manual tier assignment
+
+### Points (6 tools)
+- `openloyalty_points_add` - Add points to member wallet (with optional expiration/lock)
+- `openloyalty_points_spend` - Deduct points from member wallet
+- `openloyalty_points_transfer` - Transfer points between members (P2P)
+- `openloyalty_points_get_balance` - Get member points balance breakdown
+- `openloyalty_points_get_history` - Get points transaction history
+- `openloyalty_points_get_histogram` - Get points histogram for visualization
+
+### Rewards (9 tools)
+- `openloyalty_reward_list` - List available rewards
+- `openloyalty_reward_create` - Create a new reward
+- `openloyalty_reward_get` - Get reward details
+- `openloyalty_reward_update` - Update reward configuration
+- `openloyalty_reward_activate` - Activate a reward
+- `openloyalty_reward_deactivate` - Deactivate a reward
+- `openloyalty_reward_buy` - Purchase reward for member (deducts points)
+- `openloyalty_reward_redeem` - Mark coupon as used
+- `openloyalty_reward_category_list` - List reward categories
+
+### Transactions (4 tools)
+- `openloyalty_transaction_create` - Record a purchase transaction
+- `openloyalty_transaction_get` - Get transaction details
+- `openloyalty_transaction_list` - List transactions with filters
+- `openloyalty_transaction_assign_member` - Assign unmatched transaction to member
+
+### Campaigns (12 tools)
+- `openloyalty_campaign_list` - List all campaigns with optional filters
+- `openloyalty_campaign_create` - Create campaign to automate engagement
+- `openloyalty_campaign_get` - Get full campaign configuration
+- `openloyalty_campaign_update` - Update campaign (full replacement)
+- `openloyalty_campaign_patch` - Patch campaign (active/displayOrder only)
+- `openloyalty_campaign_delete` - Permanently delete a campaign
+- `openloyalty_campaign_simulate` - Preview campaign effects without executing
+- `openloyalty_campaign_generate_codes` - Generate redemption codes
+- `openloyalty_campaign_list_codes` - List redemption codes
+- `openloyalty_campaign_get_available` - Get campaigns available for member
+- `openloyalty_campaign_get_visible` - Get campaigns visible to member
+- `openloyalty_campaign_get_leaderboard` - Get campaign leaderboard
+
+### Segments (9 tools)
+- `openloyalty_segment_list` - List customer segments
+- `openloyalty_segment_create` - Create segment to group members
+- `openloyalty_segment_get` - Get segment details with criteria
+- `openloyalty_segment_update` - Update segment configuration
+- `openloyalty_segment_delete` - Permanently delete a segment
+- `openloyalty_segment_get_members` - Get members matching segment
+- `openloyalty_segment_activate` - Activate a segment
+- `openloyalty_segment_deactivate` - Deactivate a segment
+- `openloyalty_segment_get_resources` - Get resources associated with segment
+
+### Achievements (7 tools)
+- `openloyalty_achievement_list` - List achievements
+- `openloyalty_achievement_create` - Create achievement for gamification
+- `openloyalty_achievement_get` - Get achievement details
+- `openloyalty_achievement_update` - Update achievement (full replacement)
+- `openloyalty_achievement_patch` - Patch achievement (active/displayOrder)
+- `openloyalty_achievement_get_member_progress` - Get member's progress on achievement
+- `openloyalty_achievement_list_member_achievements` - List member's achievements
+
+### Badges (4 tools)
+- `openloyalty_badge_list` - List badge types
+- `openloyalty_badge_get` - Get badge type details
+- `openloyalty_badge_update` - Update badge type configuration
+- `openloyalty_badge_get_member_badges` - Get badges earned by member
+
+### Analytics (9 tools)
+- `openloyalty_analytics_tiers` - Get tier distribution with member counts
+- `openloyalty_analytics_members` - Get member statistics (new, active, inactive)
+- `openloyalty_analytics_points` - Get points statistics (issued, spent, expired)
+- `openloyalty_analytics_transactions` - Get transaction statistics
+- `openloyalty_analytics_referrals` - Get referral program statistics
+- `openloyalty_analytics_campaigns` - Get campaign performance metrics
+- `openloyalty_analytics_dashboard` - Get dashboard overview metrics
+- `openloyalty_analytics_units` - Get wallet-specific metrics
+- `openloyalty_analytics_campaign_detail` - Get detailed campaign analytics
+
+### Admin Users (6 tools)
+- `openloyalty_admin_list` - List admin users
+- `openloyalty_admin_create` - Create admin user
+- `openloyalty_admin_get` - Get admin user details
+- `openloyalty_admin_update` - Update admin user profile
+- `openloyalty_admin_change_password` - Change admin password
+- `openloyalty_admin_get_permissions` - Get admin permissions
+
+### Roles/ACL (6 tools)
+- `openloyalty_role_list` - List roles
+- `openloyalty_role_create` - Create role with permissions
+- `openloyalty_role_get` - Get role details
+- `openloyalty_role_update` - Update role
+- `openloyalty_role_delete` - Delete role
+- `openloyalty_acl_get_resources` - Get available ACL resources and actions
+
+### API Keys (3 tools)
+- `openloyalty_apikey_create` - Create API key (token shown once!)
+- `openloyalty_apikey_list` - List API keys for admin
+- `openloyalty_apikey_delete` - Delete API key
+
+### Audit Logs (2 tools)
+- `openloyalty_audit_list` - List audit log entries
+- `openloyalty_audit_export` - Export audit logs
+
+### Stores (4 tools)
+- `openloyalty_store_list` - List stores
+- `openloyalty_store_create` - Create store for multi-tenancy
+- `openloyalty_store_get` - Get store details
+- `openloyalty_store_update` - Update store configuration
+
+### Webhooks (6 tools)
+- `openloyalty_webhook_list` - List webhook subscriptions
+- `openloyalty_webhook_create` - Create webhook subscription for event notifications
+- `openloyalty_webhook_get` - Get webhook subscription details
+- `openloyalty_webhook_update` - Update webhook subscription
+- `openloyalty_webhook_delete` - Delete webhook subscription
+- `openloyalty_webhook_events` - List available webhook event types
+
+### Import (3 tools)
+- `openloyalty_import_create` - Create bulk import from CSV
+- `openloyalty_import_list` - List imports with status
+- `openloyalty_import_get` - Get import details and item statuses
+
+### Export (4 tools)
+- `openloyalty_export_create` - Create data export (async)
+- `openloyalty_export_list` - List exports with status
+- `openloyalty_export_get` - Get export status and details
+- `openloyalty_export_download` - Download export CSV (when status='done')
+
+## Example Workflows
+
+### 1. Create 3-Tier Loyalty Program
+
+```
+openloyalty_wallet_type_list
+openloyalty_tierset_create({ name: "VIP Program", conditions: [{ attribute: "activeUnits", walletType: "points" }] })
+openloyalty_tierset_get({ tierSetId: "..." })
+openloyalty_tierset_update_tiers({
+  tierSetId: "...",
+  tiers: [
+    { name: "Bronze", conditions: [{ conditionId: "xxx", value: 400 }] },
+    { name: "Silver", conditions: [{ conditionId: "xxx", value: 800 }] },
+    { name: "Gold", conditions: [{ conditionId: "xxx", value: 1200 }] }
+  ]
+})
+```
+
+### 2. Full Member Lifecycle
+
+```
+// Register member
+openloyalty_member_create({ email: "john@example.com", firstName: "John", lastName: "Doe" })
+
+// Add welcome bonus
+openloyalty_points_add({ memberId: "...", points: 100, comment: "Welcome bonus" })
+
+// Record purchase (auto-earns points via campaigns)
+openloyalty_transaction_create({
+  header: { documentNumber: "INV-001", purchasedAt: "2024-01-15T10:00:00Z" },
+  items: [{ sku: "PROD-1", name: "Widget", grossValue: 99.99, category: "Electronics" }],
+  customerData: { email: "john@example.com" }
+})
+
+// Check tier progress
+openloyalty_member_get_tier_progress({ memberId: "..." })
+```
+
+### 3. Reward Redemption Flow
+
+```
+// List available rewards
+openloyalty_reward_list({ active: true })
+
+// Check member balance
+openloyalty_points_get_balance({ memberId: "..." })
+
+// Purchase reward (deducts points, returns coupon code)
+openloyalty_reward_buy({ rewardId: "...", memberId: "..." })
+
+// Later: mark coupon as used
+openloyalty_reward_redeem({ memberId: "...", couponCode: "COUP-ABC123" })
+```
+
+### 4. Assign Unmatched Transaction
+
+```
+// Find unmatched transactions
+openloyalty_transaction_list({ matched: false })
+
+// Assign to member (triggers point campaigns)
+openloyalty_transaction_assign_member({ documentNumber: "INV-999", loyaltyCardNumber: "CARD-123" })
+```
+
+### 5. Create Double Points Campaign for Gold Tier
+
+```
+// First, find the Gold tier level ID
+openloyalty_tierset_get_tiers({ tierSetId: "..." })
+
+// Create a segment targeting Gold tier members
+openloyalty_segment_create({
+  name: "Gold Members",
+  parts: [{
+    criteria: [{
+      type: "tier",
+      tierIds: ["gold-level-id"]
+    }]
+  }]
+})
+
+// Create campaign with double points effect
+openloyalty_campaign_create({
+  type: "direct",
+  trigger: "transaction",
+  translations: { en: { name: "Double Points for Gold", description: "Gold members earn 2x points" } },
+  activity: { startsAt: "2024-01-01T00:00:00Z" },
+  rules: [{
+    name: "Double points",
+    effects: [{
+      effect: "give_points",
+      pointsRule: { multiplier: 2 }
+    }]
+  }],
+  audience: {
+    target: "segment",
+    segments: ["segment-id"]
+  },
+  active: true
+})
+
+// Test the campaign before it triggers
+openloyalty_campaign_simulate({
+  trigger: "transaction",
+  transaction: { grossValue: 100 },
+  customer: { email: "gold-member@example.com" }
+})
+```
+
+### 6. Create VIP Segment Based on Transaction Count
+
+```
+// Create segment for members with 10+ transactions
+openloyalty_segment_create({
+  name: "VIP Customers",
+  description: "Members with 10 or more purchases",
+  parts: [{
+    criteria: [{
+      type: "transaction_count",
+      min: 10
+    }]
+  }],
+  active: true
+})
+
+// Check segment membership
+openloyalty_segment_get_members({ segmentId: "..." })
+
+// Use for campaign targeting
+openloyalty_campaign_create({
+  type: "direct",
+  trigger: "transaction",
+  translations: { en: { name: "VIP Bonus" } },
+  activity: { startsAt: "2024-01-01T00:00:00Z" },
+  rules: [{
+    name: "VIP Bonus Points",
+    effects: [{ effect: "give_points", pointsRule: { value: 50 } }]
+  }],
+  audience: { target: "segment", segments: ["vip-segment-id"] },
+  active: true
+})
+```
+
+### 7. Create Purchase Achievement with Badge
+
+```
+// Create an achievement for making 5 purchases
+openloyalty_achievement_create({
+  translations: { en: { name: "Frequent Shopper", description: "Make 5 purchases" } },
+  rules: [{
+    trigger: "transaction",
+    completeRule: {
+      periodGoal: 5,
+      period: { type: "forever" }
+    }
+  }],
+  badgeTypeId: "shopper-badge-id",
+  active: true
+})
+
+// Check member progress
+openloyalty_achievement_get_member_progress({ memberId: "...", achievementId: "..." })
+
+// List all member achievements and badges
+openloyalty_achievement_list_member_achievements({ memberId: "..." })
+openloyalty_badge_get_member_badges({ memberId: "..." })
+```
+
+### 8. Segment Logic: OR vs AND
+
+```
+// Parts use OR logic - member matches if ANY part matches
+// Criteria within parts use AND logic - must match ALL criteria in that part
+
+// Example: (Gold tier AND 1000+ points) OR (10+ transactions)
+openloyalty_segment_create({
+  name: "High Value Members",
+  parts: [
+    {
+      // Part 1: Gold tier with high balance
+      criteria: [
+        { type: "tier", tierIds: ["gold-level-id"] },
+        { type: "points_balance", min: 1000 }
+      ]
+    },
+    {
+      // Part 2: Frequent shoppers (OR with Part 1)
+      criteria: [
+        { type: "transaction_count", min: 10 }
+      ]
+    }
+  ]
+})
+```
+
+### 9. Create Read-Only Analyst Role
+
+```
+// Discover available ACL resources and actions
+openloyalty_acl_get_resources()
+
+// Create a role with VIEW-only permissions
+openloyalty_role_create({
+  name: "Analyst",
+  permissions: [
+    { resource: "ANALYTICS", access: "VIEW" },
+    { resource: "MEMBER", access: "VIEW" },
+    { resource: "TRANSACTION", access: "VIEW" },
+    { resource: "CAMPAIGN", access: "VIEW" }
+  ]
+})
+
+// Create admin with analyst role
+openloyalty_admin_create({
+  email: "analyst@company.com",
+  password: "SecurePass123!",
+  firstName: "Data",
+  lastName: "Analyst",
+  roles: ["analyst-role-id"]
+})
+```
+
+### 10. Generate API Key for Integration
+
+```
+// Get admin to create API key for
+openloyalty_admin_list({ email: "integration@company.com" })
+
+// Create API key - CRITICAL: Save the token immediately!
+openloyalty_apikey_create({
+  adminId: "admin-uuid",
+  name: "CRM Integration Key",
+  expirationDate: "2025-12-31"
+})
+// Response includes token that is ONLY shown once
+
+// List API keys (tokens not shown)
+openloyalty_apikey_list({ adminId: "admin-uuid" })
+```
+
+### 11. Analyze Program Performance
+
+```
+// Get high-level dashboard metrics
+openloyalty_analytics_dashboard()
+
+// Analyze tier distribution
+openloyalty_analytics_tiers({ dateFrom: "2024-01-01", dateTo: "2024-12-31" })
+
+// Check points economy
+openloyalty_analytics_points({ dateFrom: "2024-01-01", dateTo: "2024-12-31" })
+
+// Analyze specific campaign
+openloyalty_analytics_campaign_detail({ campaignId: "campaign-uuid" })
+
+// Get wallet-specific metrics
+openloyalty_analytics_units({ walletTypeCode: "points" })
+```
+
+### 12. Audit User Actions
+
+```
+// List recent audit entries
+openloyalty_audit_list({ perPage: 50 })
+
+// Filter by specific user
+openloyalty_audit_list({ username: "admin@company.com" })
+
+// Filter by entity type and date range
+openloyalty_audit_list({
+  entityType: "MEMBER",
+  dateFrom: "2024-01-01",
+  dateTo: "2024-01-31"
+})
+
+// Export audit logs for compliance
+openloyalty_audit_export({
+  dateFrom: "2024-01-01",
+  dateTo: "2024-12-31"
+})
+```
+
+### 13. Multi-Tenant Store Setup
+
+```
+// Create a new store for a region
+openloyalty_store_create({
+  code: "EU",
+  name: "European Store",
+  currency: "EUR",
+  active: true
+})
+
+// List all stores
+openloyalty_store_list()
+
+// Use storeCode in subsequent operations
+openloyalty_member_create({
+  email: "customer@eu.example.com",
+  firstName: "Jean",
+  lastName: "Dupont",
+  storeCode: "EU"
+})
+```
+
+### 14. Subscribe to Member Events for CRM Sync
+
+```
+// Discover available event types
+openloyalty_webhook_events()
+
+// Subscribe to member creation events
+openloyalty_webhook_create({
+  eventName: "member.created",
+  url: "https://crm.example.com/webhooks/loyalty",
+  headers: [
+    { headerName: "Authorization", headerValue: "Bearer crm-token" }
+  ]
+})
+
+// List current subscriptions
+openloyalty_webhook_list()
+
+// Update subscription URL
+openloyalty_webhook_update({
+  webhookSubscriptionId: "...",
+  url: "https://crm-v2.example.com/webhooks/loyalty"
+})
+```
+
+### 15. Bulk Import Members from CSV
+
+```
+// Create import with CSV content
+openloyalty_import_create({
+  type: "member",
+  fileContent: "email,firstName,lastName\njohn@example.com,John,Doe\njane@example.com,Jane,Smith",
+  fileName: "members.csv"
+})
+
+// Poll import status
+openloyalty_import_list({ type: "member" })
+
+// Check individual item statuses
+openloyalty_import_get({ importId: "..." })
+```
+
+### 16. Export Campaign Codes and Download
+
+```
+// Create export for campaign codes
+openloyalty_export_create({
+  type: "campaignCode",
+  filters: { campaignId: "campaign-uuid" }
+})
+
+// Poll until status is 'done'
+openloyalty_export_get({ exportId: "..." })
+
+// Download the CSV file
+openloyalty_export_download({ exportId: "..." })
+```
+
+### 17. Bulk Add Points via Import
+
+```
+// Create import for adding points to multiple members
+openloyalty_import_create({
+  type: "unitTransferAdding",
+  fileContent: "loyaltyCardNumber,points,comment\nCARD-001,500,Promotion bonus\nCARD-002,500,Promotion bonus"
+})
+
+// Check import progress
+openloyalty_import_get({ importId: "..." })
+```
+
+## License
+
+MIT

package/dist/client/http.d.ts

@@ -0,0 +1,8 @@
+import { AxiosInstance } from "axios";
+export declare function resetHttpClient(): void;
+export declare function getAxiosInstance(): AxiosInstance;
+export declare function apiGet<T>(url: string): Promise<T>;
+export declare function apiPost<T>(url: string, data?: unknown): Promise<T>;
+export declare function apiPut<T>(url: string, data?: unknown): Promise<T>;
+export declare function apiDelete<T>(url: string): Promise<T>;
+export declare function apiPatch<T>(url: string, data?: unknown): Promise<T>;