@storelayer/mcp-server 0.1.0 → 0.2.0

package/SKILL.md

@@ -0,0 +1,276 @@
+# Store Layer MCP Server — Skill Guide for Claude Desktop
+
+You have access to the **Store Layer** MCP server, which lets you manage loyalty programs, promotions, wallets, users, events, referrals, and more for a specific project.
+
+## How It Works
+
+All tools are dynamically loaded from the Store Layer API. Tool names use underscores (e.g., `promotions_evaluate_cart`). Tools that require a `userId` parameter operate on a specific external user's data.
+
+---
+
+## Available Tools by Domain
+
+### External Users (`external_users`)
+| Tool | Description |
+|------|-------------|
+| `external_users_get_user` | Get a user by ID |
+| `external_users_list_users` | List users with pagination |
+| `external_users_lookup_user` | Smart lookup: tries ID match, then email fallback |
+| `external_users_register` | Register a new user |
+| `external_users_update` | Update a user |
+| `external_users_remove` | Remove a user |
+
+### Wallet (`wallet`) — all require `userId`
+| Tool | Description |
+|------|-------------|
+| `wallet_get_balance` | Get balance for all asset types |
+| `wallet_list_transactions` | List transaction history with filters |
+| `wallet_credit` | Add assets (points, tokens, etc.) |
+| `wallet_debit` | Remove assets |
+
+### Loyalty Events (`events`)
+| Tool | Description |
+|------|-------------|
+| `events_get` | Get a single event by ID |
+| `events_list` | List events with filters (type, status, pagination) |
+| `events_get_stats` | Aggregate stats: total, processed, pending |
+
+### Referral (`referral`)
+| Tool | Description |
+|------|-------------|
+| `referral_get_config` | Get referral program config |
+| `referral_list_codes` | List referral codes with filters |
+| `referral_get_code_by_referrer` | Look up code by referrer ID |
+| `referral_validate_code` | Check if a code is valid |
+| `referral_list_referrals` | List referral records |
+| `referral_list_events` | List referral audit events |
+| `referral_get_stats` | Aggregate stats |
+| `referral_get_leaderboard` | Leaderboard ranked by referrals |
+| `referral_create_code` | Create a referral code |
+| `referral_apply_code` | Apply a code for a referee |
+| `referral_deactivate_code` | Deactivate a code |
+
+### Project (`project`)
+| Tool | Description |
+|------|-------------|
+| `project_get_config` | Get project config (currency, timezone, settings) |
+| `project_list_rules` | List loyalty rules |
+| `project_get_rule` | Get a single rule by ID |
+| `project_list_integrations` | List integrations |
+| `project_list_resources` | List resource definitions |
+| `project_add_rule` | Create a loyalty rule |
+| `project_update_rule` | Update a rule |
+| `project_remove_rule` | Delete a rule |
+| `project_test_conditions` | Test conditions against sample data |
+
+### Promotions (`promotions`)
+| Tool | Description |
+|------|-------------|
+| `promotions_list` | List promotions with filters |
+| `promotions_get_active` | Get all active promotions |
+| `promotions_list_coupons` | List coupons |
+| `promotions_list_usage` | List usage/redemption records |
+| `promotions_get_stats` | Stats for a specific promotion |
+| `promotions_get_aggregate_stats` | Aggregate stats across all promotions |
+| `promotions_create` | Create a promotion |
+| `promotions_create_coupon` | Create a coupon for a promotion |
+| `promotions_record_usage` | Record a redemption |
+| `promotions_evaluate_cart` | **Evaluate a cart against active promotions** |
+
+### Support (`support`)
+| Tool | Description |
+|------|-------------|
+| `support_get_ticket` | Get a ticket by ID |
+| `support_list_tickets` | List tickets with filters |
+| `support_get_stats` | Aggregate ticket stats |
+| `support_create_ticket` | Create a ticket |
+| `support_update_ticket` | Update a ticket |
+
+### Surveys (`surveys`)
+| Tool | Description |
+|------|-------------|
+| `surveys_get` | Get a survey by ID |
+| `surveys_list` | List surveys |
+| `surveys_list_responses` | List responses for a survey |
+| `surveys_get_stats` | Survey analytics |
+| `surveys_create` | Create a survey |
+| `surveys_submit_response` | Submit a response |
+
+### Workflows (`workflows`)
+| Tool | Description |
+|------|-------------|
+| `workflows_list` | List workflow executions |
+| `workflows_get` | Get a workflow execution with steps |
+
+### Stores (`stores`)
+| Tool | Description |
+|------|-------------|
+| `stores_get_store` / `stores_list_stores` | Read stores |
+| `stores_create_store` / `stores_update_store` / `stores_remove_store` | Manage stores |
+| `stores_get_facility` / `stores_list_facilities` | Read facilities |
+| `stores_create_facility` / `stores_update_facility` / `stores_remove_facility` | Manage facilities |
+
+### Resources (`resources`)
+| Tool | Description |
+|------|-------------|
+| `resources_list` / `resources_get` | Read resource definitions |
+| `resources_add` / `resources_update` / `resources_remove` | Manage resource definitions |
+
+---
+
+## Domain Knowledge
+
+### Promotions Engine
+
+Every promotion has an `itemsDiscountComputation` script that computes per-item discounts. There are no predefined discount types — the script IS the discount logic.
+
+**Script environment:**
+- `$('cart')` — full cart object. `$('cart').items` is the items array. Each item: `{ id, price, quantity, category, tags, ...custom }`
+- `$('cart').total` — cart total
+- `$('user')` — current user (if userId provided)
+- `$('couponCodes')` — applied coupon codes
+
+**Return format:** Array of `{ id: string, amount: number }` where `id` = item ID and `amount` = discount to subtract.
+
+**Condition system:**
+- Structure: `{ conditions: [{ leftValue, operator, rightValue, rightType }], combinator: "AND" | "OR" }`
+- Fields: `cart.total`, `cart.itemCount`, `cart.uniqueItemCount`, `cart.items[0].price`, etc.
+- Operators: `equals`, `notEquals`, `gt`, `gte`, `lt`, `lte`, `contains`, `notContains`, `startsWith`, `endsWith`, `exists`, `notExists`, `regex`, `before`, `after`, `isEmpty`, `isNotEmpty`, `hasKey`
+
+**Stacking modes:**
+- `stackable` — combines with other promotions (default)
+- `exclusive` — highest priority wins, all others excluded
+- `exclusive_group` — highest priority within its group wins
+
+**Cart formats:**
+- **Standard:** Items have `quantity` field. Engine expands internally.
+  ```json
+  { "items": [{ "id": "muffin-001", "price": 3.50, "quantity": 2 }] }
+  ```
+- **Sub-items (pre-expanded):** Each unit is a separate entry with a unique ID and a shared logical ID in another field. Pass `itemIdField` to specify which field to use.
+  ```json
+  { "items": [{ "id": "sub-1", "sku": "muffin-001", "price": 3.50 }, { "id": "sub-2", "sku": "muffin-001", "price": 3.50 }] }
+  ```
+
+**Coupon system:** Promotions can require a coupon code (`requiresCoupon: true`). Create coupons with `promotions_create_coupon`, validate them during cart evaluation by passing `couponCodes`.
+
+#### Promotion Examples
+
+**10% off all items:**
+```json
+{
+  "name": "10% Off Everything",
+  "status": "active",
+  "conditions": { "conditions": [], "combinator": "AND" },
+  "itemsDiscountComputation": {
+    "script": "const items = $('cart').items;\nreturn items.map(item => ({ id: item.id, amount: item.price * 0.10 }));",
+    "language": "javascript"
+  }
+}
+```
+
+**$5 off orders over $50:**
+```json
+{
+  "name": "$5 Off Over $50",
+  "status": "active",
+  "conditions": {
+    "conditions": [{ "leftValue": "cart.total", "operator": "gte", "rightValue": 50, "rightType": "number" }],
+    "combinator": "AND"
+  },
+  "itemsDiscountComputation": {
+    "script": "const items = $('cart').items;\nconst total = items.reduce((s, i) => s + i.price, 0);\nreturn items.map(item => ({ id: item.id, amount: (item.price / total) * 5 }));",
+    "language": "javascript"
+  }
+}
+```
+
+**BOGO: buy 2+ shoes, cheapest free:**
+```json
+{
+  "itemsDiscountComputation": {
+    "script": "const shoes = $('cart').items.filter(i => i.category === 'shoes');\nif (shoes.length < 2) return [];\nconst sorted = [...shoes].sort((a, b) => a.price - b.price);\nreturn [{ id: sorted[0].id, amount: sorted[0].price }];",
+    "language": "javascript"
+  }
+}
+```
+
+#### Cart Evaluation
+
+Use `promotions_evaluate_cart` with:
+```json
+{
+  "cart": {
+    "items": [
+      { "id": "item-1", "price": 25.00, "quantity": 2, "category": "shoes" },
+      { "id": "item-2", "price": 15.00, "quantity": 1, "category": "accessories" }
+    ]
+  },
+  "userId": "user_123",
+  "couponCodes": ["SAVE10"]
+}
+```
+
+Response includes: `summary` (originalTotal, totalDiscount, finalTotal), `items` (per-item discounts), `appliedPromotions`, `evaluatedPromotions` (with condition/computation match details), and `warnings`.
+
+---
+
+### Loyalty Rules
+
+Rules trigger when events are ingested. Each rule has conditions (evaluated against runtime context) and actions (executed when conditions match).
+
+**Condition expressions** use Handlebars syntax: `{{ event.type }}`, `{{ event.payload.amount }}`, `{{ user.email }}`, `{{ history.amount }}`
+
+**Action types:**
+- `reward` — `{ assetType: "points", amount: 10, description: "Purchase reward" }`. Dynamic: `amount: "{{ event.amount }}"`
+- `integration` — `{ integrationId: "intg_xxx" }` — triggers webhook/Telegram/Slack
+- `apply_referral` / `complete_referral` / `mark_code_used` — referral lifecycle actions
+
+**Rule example — 1 point per dollar spent:**
+```json
+{
+  "name": "Dollar-to-Points",
+  "eventType": "purchase",
+  "conditions": {
+    "conditions": [{ "leftValue": "{{ event.type }}", "operator": "equals", "rightValue": "purchase", "rightType": "string" }],
+    "combinator": "AND"
+  },
+  "actions": [{ "type": "reward", "config": { "assetType": "points", "amount": "{{ event.payload.amount }}", "description": "1 point per dollar" } }]
+}
+```
+
+---
+
+### Events & Ingestion
+
+Events are sent externally via `POST /api/ingest/events` with an API key. The MCP server can read events but not ingest them directly.
+
+**Processing flow:** Event stored → queued → rules matched by `eventType` → resources resolved → conditions evaluated → actions executed → event marked processed.
+
+**Event payload example:**
+```json
+{ "type": "purchase", "userId": "user123", "payload": { "orderId": "order_abc", "amount": 99.99, "items": [...] } }
+```
+
+---
+
+### Resources
+
+Resources provide runtime context for rule evaluation. Types:
+- **event** — incoming event data
+- **http** — external REST API call
+- **database** — PostgreSQL query via integration
+- **internal** — Engine-X entity data (users, wallets, transactions via registry tools)
+- **payload** — request body data
+
+Resources are resolved before rule evaluation. Their data is accessible in condition expressions.
+
+---
+
+## Best Practices
+
+1. **Start by exploring** — use `promotions_get_aggregate_stats`, `project_get_config`, or list tools to understand the current state before making changes.
+2. **Test before activating** — create promotions in `draft` status, use `promotions_evaluate_cart` to test with sample carts, then set to `active`.
+3. **Use `project_test_conditions`** to validate rule conditions against sample data before saving.
+4. **For destructive actions** (delete, debit), always confirm with the user first.
+5. **Cart evaluation** returns detailed match info — check `evaluatedPromotions` for per-promotion condition/computation results and `warnings` for coupon validation issues.

package/dist/index.js

@@ -6516,6 +6516,11 @@ var require_dist = __commonJS((exports, module) => {
   exports.default = formatsPlugin;
 });
 
+// src/index.ts
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/core/core.js
 var NEVER = Object.freeze({
   status: "aborted"
@@ -13656,6 +13661,13 @@ class StdioServerTransport {
 }
 
 // src/index.ts
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var SKILL_CONTENT;
+try {
+  SKILL_CONTENT = readFileSync(resolve(__dirname2, "../SKILL.md"), "utf-8");
+} catch {
+  SKILL_CONTENT = "Store Layer MCP Server — manage loyalty programs, promotions, wallets, users, events, and referrals. Use the available tools to interact with your project.";
+}
 var API_URL = (process.env.STORE_LAYER_API_URL || "https://api.storelayer.io").replace(/\/$/, "");
 var API_KEY = process.env.STORE_LAYER_API_KEY;
 var PROJECT_ID = process.env.STORE_LAYER_PROJECT_ID;
@@ -13736,7 +13748,7 @@ async function main() {
     mcpToRegistry.set(mcpName, tool.name);
     mcpToManifest.set(mcpName, tool);
   }
-  const server = new Server({ name: "store-layer", version: "0.1.0" }, { capabilities: { tools: {} } });
+  const server = new Server({ name: "store-layer", version: "0.1.0" }, { capabilities: { tools: {}, prompts: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: manifest.map((tool) => ({
       name: toMcpName(tool.name),
@@ -13783,6 +13795,31 @@ async function main() {
       };
     }
   });
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: [
+      {
+        name: "store-layer-guide",
+        description: "Comprehensive guide for using Store Layer tools — covers all domains (promotions, wallets, users, events, referrals, rules), with examples and best practices."
+      }
+    ]
+  }));
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name !== "store-layer-guide") {
+      throw new Error(`Unknown prompt: ${request.params.name}`);
+    }
+    return {
+      description: "Store Layer MCP skill guide",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: SKILL_CONTENT
+          }
+        }
+      ]
+    };
+  });
   const transport = new StdioServerTransport;
   await server.connect(transport);
   console.error("Store Layer MCP server running on stdio");

package/package.json

@@ -1,13 +1,14 @@
 {
 	"name": "@storelayer/mcp-server",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "MCP server for Store Layer — manage loyalty programs, promotions, wallets, and more from Claude Desktop, Claude Code, or Cursor.",
 	"type": "module",
 	"bin": {
 		"store-layer-mcp-server": "dist/index.js"
 	},
 	"files": [
-		"dist"
+		"dist",
+		"SKILL.md"
 	],
 	"scripts": {
 		"build": "bun build src/index.ts --target=node --outdir=dist --format=esm",