@storelayer/mcp-server 0.2.1 → 0.4.0

package/dist/index.js

@@ -6516,11 +6516,6 @@ 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"
@@ -13661,16 +13656,92 @@ 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;
+var SKILLS_REPO = "storelayer/skills";
+var SKILLS_BASE_PATH = "skills/storelayer";
+var SKILL_REFERENCES = [
+  {
+    name: "architecture",
+    description: "Platform architecture and patterns",
+    path: "references/architecture.md"
+  },
+  {
+    name: "wallet",
+    description: "Wallet/ledger system reference",
+    path: "references/wallet.md"
+  },
+  {
+    name: "promotions",
+    description: "Promotion engine reference",
+    path: "references/promotions.md"
+  },
+  {
+    name: "referral",
+    description: "Referral system reference",
+    path: "references/referral.md"
+  },
+  {
+    name: "events",
+    description: "Events and rules reference",
+    path: "references/events.md"
+  },
+  {
+    name: "external-users",
+    description: "Customer management reference",
+    path: "references/external-users.md"
+  },
+  {
+    name: "discount-scripts",
+    description: "Discount script reference",
+    path: "references/discount-scripts.md"
+  },
+  {
+    name: "conditions",
+    description: "Condition engine reference",
+    path: "references/conditions.md"
+  },
+  {
+    name: "mcp-tools",
+    description: "All MCP tools reference",
+    path: "references/mcp-tools.md"
+  }
+];
+var SKILL_AGENTS = [
+  {
+    name: "loyalty-builder",
+    description: "Design and build complete loyalty programs",
+    path: "agents/loyalty-builder.md"
+  },
+  {
+    name: "promo-engineer",
+    description: "Build promotions, discount scripts, and coupon campaigns",
+    path: "agents/promo-engineer.md"
+  },
+  {
+    name: "integration-dev",
+    description: "Set up event ingestion and external integrations",
+    path: "agents/integration-dev.md"
+  }
+];
+var SKILL_TOOLS = [
+  {
+    name: "setup-project",
+    description: "Step-by-step new project setup",
+    path: "tools/setup-project.md"
+  },
+  {
+    name: "test-promotion",
+    description: "Test promotions before activation",
+    path: "tools/test-promotion.md"
+  },
+  {
+    name: "debug-rules",
+    description: "Debug rules and promotions",
+    path: "tools/debug-rules.md"
+  }
+];
 function apiHeaders() {
   return {
     Authorization: `Bearer ${API_KEY}`,
@@ -13706,6 +13777,31 @@ async function executeTool(toolName, params, userId) {
     throw new Error(json.error || "Tool execution failed");
   return json.data;
 }
+var contentCache = new Map;
+var CACHE_TTL_MS = 15 * 60 * 1000;
+async function fetchSkillFile(relativePath) {
+  const cacheKey = relativePath;
+  const cached2 = contentCache.get(cacheKey);
+  if (cached2 && Date.now() - cached2.fetchedAt < CACHE_TTL_MS) {
+    return cached2.content;
+  }
+  const url = `https://raw.githubusercontent.com/${SKILLS_REPO}/main/${SKILLS_BASE_PATH}/${relativePath}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${relativePath} from GitHub (${res.status})`);
+  }
+  const content = await res.text();
+  contentCache.set(cacheKey, { content, fetchedAt: Date.now() });
+  return content;
+}
+async function fetchSkillGuide() {
+  try {
+    return await fetchSkillFile("SKILL.md");
+  } catch (error2) {
+    console.error("Failed to fetch SKILL.md from GitHub:", error2);
+    return "Storelayer MCP Server — manage loyalty programs, promotions, wallets, users, events, and referrals. Use the available tools to interact with your project. Skill guide unavailable (GitHub unreachable).";
+  }
+}
 function buildInputSchema(tool) {
   const schema = structuredClone(tool.parameters);
   if (!schema.type)
@@ -13739,8 +13835,12 @@ async function main() {
     process.exit(1);
   }
   console.error(`Connecting to Store Layer API at ${API_URL}...`);
-  const manifest = await fetchToolManifest();
+  const [manifest, skillGuide] = await Promise.all([
+    fetchToolManifest(),
+    fetchSkillGuide()
+  ]);
   console.error(`Loaded ${manifest.length} tools from Store Layer`);
+  console.error(`Skill guide loaded from GitHub (${SKILLS_REPO})`);
   const mcpToRegistry = new Map;
   const mcpToManifest = new Map;
   for (const tool of manifest) {
@@ -13748,7 +13848,12 @@ 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: {}, prompts: {} } });
+  const allSkillFiles = [
+    ...SKILL_REFERENCES.map((f) => ({ ...f, category: "reference" })),
+    ...SKILL_AGENTS.map((f) => ({ ...f, category: "agent" })),
+    ...SKILL_TOOLS.map((f) => ({ ...f, category: "tool" }))
+  ];
+  const server = new Server({ name: "store-layer", version: "0.4.0" }, { capabilities: { tools: {}, prompts: {}, resources: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: manifest.map((tool) => ({
       name: toMcpName(tool.name),
@@ -13799,26 +13904,74 @@ async function main() {
     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."
-      }
+        description: "Comprehensive guide for using Storelayer tools — covers all domains (promotions, wallets, users, events, referrals, rules), with recipes and best practices."
+      },
+      ...SKILL_AGENTS.map((agent) => ({
+        name: agent.name,
+        description: agent.description
+      }))
     ]
   }));
   server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-    if (request.params.name !== "store-layer-guide") {
-      throw new Error(`Unknown prompt: ${request.params.name}`);
+    const promptName = request.params.name;
+    if (promptName === "store-layer-guide") {
+      return {
+        description: "Storelayer MCP skill guide",
+        messages: [
+          {
+            role: "user",
+            content: { type: "text", text: skillGuide }
+          }
+        ]
+      };
     }
-    return {
-      description: "Store Layer MCP skill guide",
-      messages: [
-        {
-          role: "user",
-          content: {
-            type: "text",
-            text: SKILL_CONTENT
+    const agent = SKILL_AGENTS.find((a) => a.name === promptName);
+    if (agent) {
+      try {
+        const content = await fetchSkillFile(agent.path);
+        return {
+          description: agent.description,
+          messages: [
+            {
+              role: "user",
+              content: { type: "text", text: content }
+            }
+          ]
+        };
+      } catch (error2) {
+        throw new Error(`Failed to fetch agent ${agent.name}: ${error2 instanceof Error ? error2.message : String(error2)}`);
+      }
+    }
+    throw new Error(`Unknown prompt: ${promptName}`);
+  });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: allSkillFiles.map((file) => ({
+      uri: `storelayer://${file.category}/${file.name}`,
+      name: file.name,
+      description: file.description,
+      mimeType: "text/markdown"
+    }))
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const file = allSkillFiles.find((f) => `storelayer://${f.category}/${f.name}` === uri);
+    if (!file) {
+      throw new Error(`Unknown resource: ${uri}`);
+    }
+    try {
+      const content = await fetchSkillFile(file.path);
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "text/markdown",
+            text: content
           }
-        }
-      ]
-    };
+        ]
+      };
+    } catch (error2) {
+      throw new Error(`Failed to fetch ${file.path}: ${error2 instanceof Error ? error2.message : String(error2)}`);
+    }
   });
   const transport = new StdioServerTransport;
   await server.connect(transport);

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@storelayer/mcp-server",
-  "version": "0.2.1",
+  "version": "0.4.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",
-    "SKILL.md"
+    "dist"
   ],
   "scripts": {
     "build": "bun build src/index.ts --target=node --outdir=dist --format=esm",

package/SKILL.md

@@ -1,274 +0,0 @@
-# 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_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, appliedCount), `items` (per-item discounts), `applied` (matched promotions with discounts), `notApplied` (unmatched promotions with reasons, human-readable messages, and suggestions), `discounts` (flat discount list), `warnings`, and `usageRecords` (when not dry run).
-
----
-
-### 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",
-  "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 → 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** — Store Layer 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 `applied` for matched promotions with discounts, `notApplied` for unmatched promotions with reasons/suggestions, and `warnings` for coupon validation issues.