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.

Published on npm as @open-loyalty/mcp-server. The badge above shows the latest published release. Install with @latest to select that release, or replace it with a specific version to pin your setup.

Prerequisites

• Node.js 18 or later
• An Open Loyalty account with API access

Installation

Via npm (Recommended)

npm install -g @open-loyalty/mcp-server@latest

Or use directly with npx (no installation required):

npx -y @open-loyalty/mcp-server@latest

Claude Desktop one-click install (.mcpb)

The easiest way to install for Claude Desktop is the prebuilt .mcpb bundle. It includes the server and its dependencies, so no Node.js or npm setup is required.

1. Download the latest bundle: openloyalty-mcp.mcpb
2. Open the downloaded file, or drag it into the Extensions/Settings area of Claude Desktop to install it.
3. When prompted, enter your Open Loyalty API URL and API token.

The bundle is also available through jsDelivr. To pin a specific release, replace @latest in either download URL with the version you want to install.

Updating an existing installation

• Global npm installation: rerun npm install -g @open-loyalty/mcp-server@latest.
• npx: use @open-loyalty/mcp-server@latest in your MCP client's server configuration, as shown below. A configuration pinned to a version keeps using that version until you change it.
• Claude Desktop bundle: download the latest .mcpb above and install it again to update the extension.

After updating, restart the MCP server or your MCP client to load the new code. An already running server continues using its loaded version. To check the latest version available on npm, run:

npm view @open-loyalty/mcp-server version

For a global installation, check the installed version with:

npm ls -g @open-loyalty/mcp-server --depth=0

From Source

git clone https://github.com/OpenLoyalty/openloyalty-mcp.git
cd openloyalty-mcp/openloyalty-mcp
npm install
npm run build

Configuration

The server requires the following environment variables:

| Variable | Required | Description | |----------|----------|-------------| | OPENLOYALTY_API_URL | Yes | Your Open Loyalty API URL (e.g., https://api.openloyalty.io) | | OPENLOYALTY_API_TOKEN | Yes | Your API authentication token | | OPENLOYALTY_DEFAULT_STORE_CODE | No | Pins every call to one store code. Leave empty for multi-tenant use, where storeCode is required per call. | | OPENLOYALTY_CONFIRM_TENANT_WRITES | No | true asks the user to confirm the tenant before each write. Multi-tenant mode only; fails closed. |

Store code (tenant) modes

OPENLOYALTY_DEFAULT_STORE_CODE decides how the store code — Open Loyalty's tenant identifier — is chosen. There is no implicit default fallback.

• Pinned (value set): tenant-scoped calls run against that store code. A call that passes a different code is rejected rather than silently redirected, so a mismatch is visible instead of writing to the wrong tenant.
• Multi-tenant (left empty): storeCode is a required parameter on every tenant-scoped tool. The MCP SDK validates it against the advertised schema before the handler runs, so a call without a tenant never reaches the API. The server also instructs the agent to ask which tenant to work in before its first call, to carry that code through the conversation, and to switch whenever the user names a different tenant ("add a member in tenant XYZ"). ol_store_list lists the available codes.

Store and language management (ol_store_*, ol_language_*) is global and takes no storeCode in either mode — a pin is not an authorization boundary around the whole server.

Enforcement, beyond the prompt:

| Mechanism | What it catches | |---|---| | storeCode required in the advertised schema (multi-tenant) | A call with no tenant — rejected on the wire, no API request | | Mismatch check in getStoreCode() (pinned) | A call naming a tenant other than the pin — rejected, not rewritten | | Applied to store code: <code> block on every write result | A write that landed in the wrong tenant — visible in the result | | Widgets carry the tenant from the data they rendered | Button-triggered writes (redeem, create) inheriting the wrong tenant | | OPENLOYALTY_CONFIRM_TENANT_WRITES=true (opt-in) | A valid-but-wrong tenant — the user confirms the store before each write |

Without the confirmation setting, a valid-but-wrong store code supplied by the agent still goes through; the write echo is what surfaces it, after the fact.

Confirm the tenant before each write (optional)

OPENLOYALTY_CONFIRM_TENANT_WRITES=true — "Ask me to confirm the store before each write" in the extension settings — holds every data-changing call until the user confirms which tenant it applies to, over MCP elicitation. The answer comes from the client's own UI, not from the model, so it is a real check on the agent's tenant choice rather than a restatement of it.

It applies only when the default store code is empty: with a pinned store the tenant is not the agent's to get wrong, and the setting is ignored.

It fails closed. If the client does not support elicitation, or the dialog errors, is declined or cancelled, the write is blocked and nothing is sent. Reads are never held up.

Automatic rate-limit recovery

The client queues upstream requests and automatically handles temporary rate limits, including when an agent calls several analytics tools in parallel:

• A 429 pauses the shared upstream queue, including new calls and retries. The client respects Retry-After in seconds or HTTP-date form, without shortening it to the backoff cap. Without that header it uses exponential backoff and jitter, starting at one second and capped at 15 seconds.
• After a rate limit, requests resume one at a time through the token bucket. The rate halves once per cooldown window, down to one request per second; successful traffic adds one request per second after each 30 seconds without another rate limit, up to the normal 10 requests per second. At most six upstream requests can be in flight. Other requests already in flight when a 429 arrives are allowed to finish.
• Each upstream operation allows at most six retries, with a 45-second deadline for starting attempts. A longer Retry-After is returned as RATE_LIMITED without retrying early; the shared cooldown still applies to subsequent calls. Calls that expire in the queue are removed and never sent later. An attempt already sent retains its normal HTTP timeout, so total elapsed time can exceed 45 seconds; tools that fetch multiple pages also perform multiple operations.
• Reads also retry 503 responses. Writes retry explicit 429 rejections, but do not replay on 503 or network failures, where the write might have taken effect already.

Repeated GETs are deduped while in flight and cached briefly in memory. Successful mutations clear the read cache to avoid stale follow-up reads.

These controls are shared by all tools in one MCP server process. Separate clients/processes and other integrations can still consume the same upstream quota. Persistent limits can still return RATE_LIMITED; the MCP server cannot increase the API's quota.

Local environment file

For local development, create a .env file based on .env.example:

cp .env.example .env

Claude Desktop Configuration

The server communicates over stdio. Add it to your MCP client (Claude Desktop, Claude Code, Cursor) using one of the configurations below.

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)

{
  "mcpServers": {
    "openloyalty": {
      "command": "npx",
      "args": ["-y", "@open-loyalty/mcp-server@latest"],
      "env": {
        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
        "OPENLOYALTY_API_TOKEN": "your-api-token",
        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
      }
    }
  }
}

Using Global Installation

{
  "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

{
  "mcpServers": {
    "openloyalty": {
      "command": "node",
      "args": ["/path/to/openloyalty-mcp/dist/index.js"],
      "env": {
        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
        "OPENLOYALTY_API_TOKEN": "your-api-token",
        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
      }
    }
  }
}

Development

# Run the server in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

Available Tools (152 total)

146 API tools, listed below, plus 6 interactive app widgets (campaign builder, dashboard, member profile, rewards catalog, tier visualizer, transaction timeline). npm run sync:manifest is the source of truth for the count.

Wallet Types (4 tools)

• ol_wallet_type_list - List all available wallet types (point currencies)
• ol_wallet_type_get - Get full details for a specific wallet type by ID
• ol_wallet_type_create - Create a new point currency (wallet type)
• ol_wallet_type_update - Update an existing wallet type's configuration

Tier Sets (6 tools)

• ol_tierset_list - List all tier sets
• ol_tierset_create - Create a tier set (container for all tiers)
• ol_tierset_get - Get tier set details including condition IDs
• ol_tierset_update - Update tier set metadata
• ol_tierset_update_tiers - Add all tiers to a tier set in one call
• ol_tierset_get_tiers - Get all tiers in a tier set

Members (12 tools)

• ol_member_create - Register a new loyalty program member
• ol_member_get - Get member details including profile, points balance, and tier status
• ol_member_list - Search and list members with optional filters
• ol_member_update - Update member profile fields (PUT; cannot touch identifiers, custom fields, or labels)
• ol_member_patch - Partial update, including email/phone/loyalty card, custom fields, and labels
• ol_member_activate - Activate a member account
• ol_member_deactivate - Deactivate a member account
• ol_member_delete - Permanently remove member and all associated data
• ol_member_anonymize - GDPR-compliant anonymization of all member PII
• ol_member_get_tier_progress - Get a member's tier progression status
• ol_member_assign_tier - Manually assign a tier level to a member
• ol_member_remove_manual_tier - Remove manually assigned tier from member

Points (10 tools)

• ol_points_add - Add points to a member's wallet manually
• ol_points_spend - Deduct points from member wallet
• ol_points_transfer - Transfer points from one member to another (P2P)
• ol_points_block - Block (freeze) points from a member's active balance
• ol_points_unblock - Release a blocked points transfer back to active balance
• ol_points_cancel - Cancel a specific points transfer, reversing the movement
• ol_points_expire - Manually expire a points transfer before its natural expiry
• ol_points_get_balance - Get member points balance breakdown
• ol_points_get_history - Get points transaction history for a member
• ol_points_get_histogram - Get points histogram data for visualization

Rewards (14 tools)

• ol_reward_list - List available rewards
• ol_reward_create - Create a new reward that members can redeem with points
• ol_reward_get - Get full reward details including configuration and coupon settings
• ol_reward_update - Update reward configuration
• ol_reward_activate - Activate a reward, making it available to redeem
• ol_reward_deactivate - Deactivate a reward, hiding it from members
• ol_reward_buy - Purchase reward for member, deducting points
• ol_reward_redeem - Mark coupon as used
• ol_reward_category_list - List reward categories
• ol_reward_category_create - Create a new reward category
• ol_reward_category_update - Update a reward category's name, status, or sort order
• ol_reward_photo_upload - Attach a photo to a reward
• ol_reward_photo_delete - Permanently delete a photo from a reward
• ol_member_get_issued_rewards - List rewards redeemed/issued to a specific member

Redemptions (6 tools)

• ol_redemption_get - Get a single issued reward with its current status
• ol_redemption_get_status_history - Full status-change history for an issued reward
• ol_redemption_change_status - Change one issued reward's status, with optional comment
• ol_redemption_change_status_bulk - Change status for many issued rewards; reports per-item outcome (a 200 can still contain failed rows)
• ol_redemption_cancel - Cancel an issued reward
• ol_redemption_draw - Perform the fortune-wheel draw for an issued reward

Transactions (4 tools)

• ol_transaction_create - Record a purchase transaction
• ol_transaction_get - Get transaction details
• ol_transaction_list - List transactions with filters
• ol_transaction_assign_member - Assign unmatched transaction to member

Campaigns (13 tools)

• ol_campaign_list - List all campaigns with optional filters
• ol_campaign_create - Create campaign (earning rule) to automate engagement
• ol_campaign_get - Get full campaign configuration
• ol_campaign_update - Full update of campaign configuration
• ol_campaign_patch - Partial update (active/displayOrder only)
• ol_campaign_delete - Permanently delete a campaign
• ol_campaign_simulate - Simulate campaign effects without executing
• ol_campaign_generate_codes - Generate unique redemption codes for a campaign
• ol_campaign_list_codes - List redemption codes for a campaign
• ol_campaign_get_available - Get campaigns available to a member
• ol_campaign_get_visible - Get campaigns visible to a member
• ol_campaign_get_leaderboard - Get leaderboard rankings for a campaign
• ol_member_get_challenge_progress - Get a member's progress on all challenges

Segments (9 tools)

• ol_segment_list - List customer segments
• ol_segment_create - Create segment to group members by behavior or attributes
• ol_segment_get - Get full segment details including parts and criteria
• ol_segment_update - Update segment configuration
• ol_segment_delete - Permanently delete a segment
• ol_segment_get_members - Get members belonging to a segment
• ol_segment_activate - Activate a segment
• ol_segment_deactivate - Deactivate a segment
• ol_segment_get_resources - List resources associated with an existing segment

Achievements (7 tools)

• ol_achievement_list - List achievements
• ol_achievement_create - Create achievement for gamification
• ol_achievement_get - Get achievement details
• ol_achievement_update - Update achievement (full replacement)
• ol_achievement_patch - Patch achievement (active/displayOrder)
• ol_achievement_get_member_progress - Get member's progress on achievement
• ol_achievement_list_member_achievements - List member's achievements

Badges (4 tools)

• ol_badge_list - List badge types
• ol_badge_get - Get badge type details
• ol_badge_update - Update badge type configuration
• ol_badge_get_member_badges - Get badges earned by member

Analytics (9 tools)

• ol_analytics_tiers - Get tier distribution with member counts
• ol_analytics_members - Get member statistics (new, active, inactive)
• ol_analytics_points - Get points statistics (issued, spent, expired)
• ol_analytics_transactions - Get transaction statistics
• ol_analytics_referrals - Get referral program statistics
• ol_analytics_campaigns - Get campaign performance metrics
• ol_analytics_dashboard - Get dashboard overview metrics
• ol_analytics_units - Get wallet-specific metrics
• ol_analytics_campaign_detail - Get detailed campaign analytics

Audit Logs (2 tools)

• ol_audit_list - List audit log entries
• ol_audit_export - Export audit logs

Stores (6 tools)

• ol_store_list - List stores
• ol_store_create - Create store for multi-tenancy
• ol_store_get - Get store details
• ol_store_update - Update store configuration
• ol_store_get_settings - Get the loyalty program settings for the current store
• ol_store_update_settings - Update loyalty program settings (partial PATCH)

Webhooks (6 tools)

• ol_webhook_list - List webhook subscriptions
• ol_webhook_create - Create webhook subscription for event notifications
• ol_webhook_get - Get webhook subscription details
• ol_webhook_update - Update webhook subscription
• ol_webhook_delete - Delete webhook subscription
• ol_webhook_events - List available webhook event types

Import (3 tools)

• ol_import_create - Create bulk import from CSV
• ol_import_list - List imports with status
• ol_import_get - Get import details and item statuses

Export (4 tools)

• ol_export_create - Create data export (async)
• ol_export_list - List exports with status
• ol_export_get - Get export status and details
• ol_export_download - Download export CSV (when status='done')

Custom Events (7 tools)

• ol_custom_event_schema_create - Create a new custom event schema
• ol_custom_event_schema_list - List available custom event schemas
• ol_custom_event_schema_get - Get details of a custom event schema including its fields
• ol_custom_event_schema_update - Update an existing custom event schema
• ol_custom_event_schema_activate - Activate or deactivate a custom event schema
• ol_custom_event_send - Send a custom event for a member
• ol_custom_event_list - List custom events that have been sent

Referrals (3 tools)

• ol_referral_create - Create a referral relationship between members
• ol_referral_list - List referral relationships with optional filters
• ol_referral_delete - Delete a referral relationship for a member

Channels (5 tools)

• ol_channel_list - List sales channels (e.g. Mobile App, Point of Sale, Web)
• ol_channel_create - Create a new sales channel
• ol_channel_get - Get full details of a specific channel by channelId
• ol_channel_update - Update a channel's name, identifier, or description
• ol_channel_delete - Permanently delete a channel

Languages (5 tools)

• ol_language_list - List all configured languages
• ol_language_create - Add a new language to the platform
• ol_language_get - Get details of a specific language by its locale code
• ol_language_update - Update a language's name, sort order, or default status
• ol_language_delete - Delete a language

Group of Values (6 tools)

• ol_group_of_values_list - List all groups of values
• ol_group_of_values_create - Create a new group of values container
• ol_group_of_values_update - Update a group's name, description, or active status
• ol_group_value_add - Add an individual value to a group of values
• ol_group_value_update - Update an individual value's string or description
• ol_group_value_delete - Permanently delete an individual value from a group

Context (1 tool)

• ol_context_get - Get current store state (wallet types, tier sets, segments, campaigns, rewards) in one call

Interactive App Views (6 tools)

• ol_dashboard_app - Interactive loyalty program dashboard with tier, points, and campaign charts
• ol_member_profile_app - Interactive member profile card with tier badge and points balance
• ol_rewards_catalog_app - Interactive rewards catalog with category and affordability filtering
• ol_tier_visualizer_app - Interactive visualization of loyalty tier structures
• ol_transaction_timeline_app - Interactive timeline of a member's transactions and point movements
• ol_campaign_builder_app - Interactive multi-step wizard for creating loyalty campaigns

Example Workflows

1. Create 3-Tier Loyalty Program

ol_wallet_type_list
// Note: conditions use `attribute` (not `type`) and walletType expects the wallet CODE (e.g., "default"), not the UUID.
ol_tierset_create({ name: "VIP Program", conditions: [{ attribute: "activeUnits", walletType: "points" }] })
ol_tierset_get({ tierSetId: "..." })
ol_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
ol_member_create({ email: "[email protected]", firstName: "John", lastName: "Doe" })

// Add welcome bonus
ol_points_add({ memberId: "...", points: 100, comment: "Welcome bonus" })

// Record purchase (auto-earns points via campaigns)
ol_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: "[email protected]" }
})

// Check tier progress
ol_member_get_tier_progress({ memberId: "..." })

3. Reward Redemption Flow

// List available rewards
ol_reward_list({ active: true })

// Check member balance
ol_points_get_balance({ memberId: "..." })

// Purchase reward (deducts points, returns coupon code)
ol_reward_buy({ rewardId: "...", memberId: "..." })

// Later: mark coupon as used
ol_reward_redeem({ memberId: "...", couponCode: "COUP-ABC123" })

4. Assign Unmatched Transaction

// Find unmatched transactions
ol_transaction_list({ matched: false })

// Assign to member (triggers point campaigns)
ol_transaction_assign_member({ documentNumber: "INV-999", loyaltyCardNumber: "CARD-123" })

5. Create Double Points Campaign for Gold Tier

// First, find the Gold tier level ID
ol_tierset_get_tiers({ tierSetId: "..." })

// Create a segment targeting Gold tier members
ol_segment_create({
  name: "Gold Members",
  parts: [{
    criteria: [{
      type: "tier",
      tierIds: ["gold-level-id"]
    }]
  }]
})

// Create campaign with double points effect
ol_campaign_create({
  type: "direct",
  trigger: "transaction",
  translations: { en: { name: "Double Points for Gold", description: "Gold members earn 2x points" } },
  // Required: activity.startsAt, rules[].name. Use effects[].effect (not type). pointsRule is a STRING expression (not an object).
  activity: { startsAt: "2024-01-01T00:00:00Z" },
  rules: [{
    name: "Double points",
    effects: [{
      effect: "give_points",
      pointsRule: "transaction.grossValue * 2"
    }]
  }],
  audience: {
    target: "segment",
    segments: ["segment-id"]
  },
  active: true
})

// Test the campaign before it triggers
ol_campaign_simulate({
  trigger: "transaction",
  transaction: { grossValue: 100 },
  customer: { email: "[email protected]" }
})

6. Create VIP Segment Based on Transaction Count

// Create segment for members with 10+ transactions
ol_segment_create({
  name: "VIP Customers",
  description: "Members with 10 or more purchases",
  parts: [{
    criteria: [{
      type: "transaction_count",
      min: 10
    }]
  }],
  active: true
})

// Check segment membership
ol_segment_get_members({ segmentId: "..." })

// Use for campaign targeting
ol_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: "50" }]
  }],
  audience: { target: "segment", segments: ["vip-segment-id"] },
  active: true
})

7. Create Purchase Achievement with Badge

// Create an achievement for making 5 purchases
ol_achievement_create({
  translations: { en: { name: "Frequent Shopper", description: "Make 5 purchases" } },
  rules: [{
    type: "direct",
    trigger: "transaction",
    aggregation: { type: "quantity" },
    completeRule: {
      periodGoal: 5,
      period: { type: "day", consecutive: 1 }
    }
  }],
  badgeTypeId: "shopper-badge-id",
  active: true
})

// Check member progress
ol_achievement_get_member_progress({ memberId: "...", achievementId: "..." })

// List all member achievements and badges
ol_achievement_list_member_achievements({ memberId: "..." })
ol_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: (10+ transactions) OR (5-9 transactions)
ol_segment_create({
  name: "High Value Members",
  parts: [
    {
      // Part 1: Frequent shoppers
      criteria: [
        { type: "transaction_count", min: 10, max: 999999 }
      ]
    },
    {
      // Part 2: Moderately frequent shoppers (OR with Part 1)
      criteria: [
        { type: "transaction_count", min: 5, max: 9 }
      ]
    }
  ]
})

9. Analyze Program Performance

// Get high-level dashboard metrics
ol_analytics_dashboard()

// Analyze tier distribution
ol_analytics_tiers({ dateFrom: "2024-01-01", dateTo: "2024-12-31" })

// Check points economy
ol_analytics_points({ dateFrom: "2024-01-01", dateTo: "2024-12-31" })

// Analyze specific campaign
ol_analytics_campaign_detail({ campaignId: "campaign-uuid" })

// Get wallet-specific metrics
ol_analytics_units({ walletTypeCode: "points" })

10. Audit User Actions

// List recent audit entries
ol_audit_list({ perPage: 50 })

// Filter by specific user
ol_audit_list({ username: "[email protected]" })

// Filter by entity type and date range
ol_audit_list({
  entityType: "MEMBER",
  dateFrom: "2024-01-01",
  dateTo: "2024-01-31"
})

// Export audit logs for compliance
ol_audit_export({
  dateFrom: "2024-01-01",
  dateTo: "2024-12-31"
})

11. Multi-Tenant Store Setup

// Create a new store for a region
ol_store_create({
  code: "EU",
  name: "European Store",
  currency: "EUR",
  active: true
})

// List all stores
ol_store_list()

// Use storeCode in subsequent operations
ol_member_create({
  email: "[email protected]",
  firstName: "Jean",
  lastName: "Dupont",
  storeCode: "EU"
})

12. Subscribe to Member Events for CRM Sync

// Discover available event types
ol_webhook_events()

// Subscribe to member creation events
ol_webhook_create({
  eventName: "member.created",
  url: "https://crm.example.com/webhooks/loyalty",
  headers: [
    { headerName: "Authorization", headerValue: "Bearer crm-token" }
  ]
})

// List current subscriptions
ol_webhook_list()

// Update subscription URL
ol_webhook_update({
  webhookSubscriptionId: "...",
  url: "https://crm-v2.example.com/webhooks/loyalty"
})

13. Bulk Import Members from CSV

// Create import with CSV content
ol_import_create({
  type: "member",
  fileContent: "email,firstName,lastName\[email protected],John,Doe\[email protected],Jane,Smith",
  fileName: "members.csv"
})

// Poll import status
ol_import_list({ type: "member" })

// Check individual item statuses
ol_import_get({ importId: "..." })

14. Export Campaign Codes and Download

// Create export for campaign codes
ol_export_create({
  type: "campaignCode",
  filters: { campaignId: "campaign-uuid" }
})

// Poll until status is 'done'
ol_export_get({ exportId: "..." })

// Download the CSV file
ol_export_download({ exportId: "..." })

15. Bulk Add Points via Import

// Create import for adding points to multiple members
ol_import_create({
  type: "unitTransferAdding",
  fileContent: "loyaltyCardNumber,points,comment\nCARD-001,500,Promotion bonus\nCARD-002,500,Promotion bonus"
})

// Check import progress
ol_import_get({ importId: "..." })

Spec drift check

The repo vendors a snapshot of the core-framework OpenAPI spec at spec/openapi.yaml (provenance: spec/spec-meta.json). A drift gate compares it against the endpoints the MCP actually calls, scanned from src/ at check time:

npm run spec:check             # CI gate: fails on dead/wrong endpoints, NEW gaps, or STALE allowlist entries
npm run spec:report            # human-readable coverage summary grouped by domain
npm run spec:update-allowlist  # regenerate spec/coverage-allowlist.json from current gaps

The gate fails when:

• the MCP calls an endpoint that does not exist in the spec (dead/wrong call);
• a spec operation has no tool and is not listed in spec/coverage-allowlist.json (a NEW coverage gap);
• an allowlist entry is now covered by a tool (a STALE entry — prune with npm run spec:update-allowlist).

It also runs as a vitest suite (tests/spec/spec-drift.test.ts), so npm test catches drift too.

Never re-vendor the spec and run npm run spec:update-allowlist in the same commit. When core-framework adds endpoints, re-vendoring makes each one a new gap and the gate fails — that failure is the whole point: it is the only thing that surfaces backend additions. Regenerating the allowlist in the same commit swallows them silently, and the diff reads as routine churn. Split into two commits and the allowlist diff shows a reviewer exactly which endpoints the backend added, forcing a decision on each.

Re-vendoring the spec (when the backend API changes):

1. In core-framework, bundle/locate the single-file spec: doc/openapi.yaml.
2. Copy it over spec/openapi.yaml, update spec/spec-meta.json (commit hash, date, shasum -a 256 spec/openapi.yaml), and commit just that.
3. Run npm run spec:check and read the failures — each new gap is an endpoint the backend added.
4. For each one, either implement a tool or deliberately allowlist it (npm run spec:update-allowlist), and commit that as a separate commit so the allowlist diff is reviewable on its own.

Closing a coverage gap: after implementing a tool for an allowlisted endpoint, remove its entry from spec/coverage-allowlist.json (or run npm run spec:update-allowlist) — the gate fails on stale entries, so this is enforced, not optional.

Links

• GitHub: OpenLoyalty/openloyalty-mcp
• Open Loyalty: openloyalty.io
• MCP Protocol: modelcontextprotocol.io

License

MIT