Loyalty MCP Server

A loyalty-program layer for ADK-Rust Enterprise agents. 18 MCP tools over members, a points ledger, tiers, a rewards catalog, redemptions, and promotional offers — for membership, points-balance, and rewards agents.

What It Does

The points ledger is the source of truth. Every balance change — earn, redeem, adjust, expire, reversal — is an append-only ledger entry carrying the running balance, so a member's balance is always reconstructable and auditable.

Members with membership numbers, status, tier, current balance, and lifetime points
Points — earn from spend (with tier + offer multipliers), direct awards, manual adjustments, expiry; never goes negative
Tiers — Bronze → Silver → Gold → Platinum, derived from lifetime points (redemptions spend balance but never demote), each with an earn multiplier
Rewards catalog — points cost, optional minimum tier, optional inventory
Redemptions — validates tier/inventory/balance, debits via the ledger; cancelling refunds points and restores inventory
Offers — promotional bonus-earn multipliers, optionally tier-targeted

Architecture

Loyalty MCP Architecture

Tiers

| Tier | Lifetime points | Earn multiplier | |------|-----------------|-----------------| | Bronze | 0 | 1.0× | | Silver | 1,000 | 1.25× | | Gold | 5,000 | 1.5× | | Platinum | 20,000 | 2.0× |

Tools (18)

Members (5)

enroll_member · get_member · find_member · set_member_status · get_balance (with tier progress)

Points (5)

| Tool | What It Does | |------|-------------| | earn_points | Earn from spend; applies tier + active-offer multipliers | | award_points | Direct credit (signup bonus, goodwill) | | adjust_points | Manual +/- adjustment (never below zero) | | expire_points | Expire points from the balance | | get_ledger | Auditable points history (running balance) |

Rewards & Redemptions (5)

create_reward · list_rewards (tier-filtered) · redeem_reward · set_redemption_status (cancel refunds) · get_redemptions

Offers (3)

create_offer · list_offers · set_offer_active

Example

> enroll_member(name: "Test Member", contact_ref: "ref:test")   → MBR-1009 (bronze)

> earn_points(member_id: "MBR-1009", spend: 2000, reference: "order:9")
  → 4000 pts  (2000 × 1.0 tier × 2.0 "Double Points" offer) · balance 4000

> get_balance(member_id: "MBR-1009")
  → tier: silver · points_to_next_tier: 1000 → gold

> list_rewards(member_id: "MBR-1009")     ← only tier-eligible rewards
> redeem_reward(member_id: "MBR-1009", reward_id: "RWD-1006")   → RDM-1011 (pending)

> get_ledger(member_id: "MBR-1009")
  → earn  +4000 → 4000
    redeem -500 → 3500          ← running balance, always reconstructable

Installation

1. Build

git clone https://github.com/zavora-ai/mcp-loyalty
cd mcp-loyalty
cargo build --release

2. Add to your MCP client

Claude Desktop / Kiro / Cursor / Windsurf:

{
  "mcpServers": {
    "loyalty": {
      "command": "/path/to/mcp-loyalty"
    }
  }
}

3. Use it

> find_member(name: "alice")
> get_balance(member_id: "MBR-1001")
> list_rewards(member_id: "MBR-1001")

Governance & Data Handling

Gated points writes — earn_points, award_points, adjust_points, expire_points, redeem_reward, and set_redemption_status require approval in production (they move points of monetary value); reads are read_only.
Balance integrity — all changes go through the ledger; the balance can never go negative, and cancellations are reversed via compensating entries.
No raw PII — members carry a contact reference, not necessarily raw contact details.
Integration scaffold — the in-memory store is for development; back it with a durable store and bind actors to authenticated identities in production.

MCP Server Manifest

server_id = "mcp_loyalty"
display_name = "Loyalty"
version = "1.0.0"
domain = "operations"
risk_level = "medium"
writes_allowed = "gated"
transports = ["stdio"]

Contributors

|
_{James Karanja Maina} | |:---:|

License

Apache-2.0 — see LICENSE for details.

Part of the ADK-Rust Enterprise MCP server ecosystem.

Registry Compliance

This server implements the ADK MCP SDK contract:

HealthCheck — async health probe for registry monitoring
mcp-server.toml — manifest declaring tools, risk classes, and approval gates
Structured tracing — RUST_LOG env-filter for observability

MCP Servers