@joy-loyalty/mcp 0.3.7

package/README.md

@@ -0,0 +1,88 @@
+# Joy Loyalty MCP Server
+
+Connect Claude, Cursor, or any [MCP](https://modelcontextprotocol.io)-compatible AI client to your Joy Loyalty program. Ask questions and manage loyalty data in natural language — no code required.
+
+## Quick start
+
+**1. Get your API key**
+
+In your Joy admin, go to **Settings → Manage keys**:
+- **Recommended:** click **"Generate read-only key"** (a `ro_...` key). This is the safest option — it can read your loyalty data but can never award, deduct, or change points, even if the key is ever exposed.
+- Only use your full **Secret key** if you need write access (awarding points, adjusting balances, etc.).
+
+**2. Add the server to your AI client**
+
+For **Claude Desktop**, edit your config file:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "joy-loyalty": {
+      "command": "npx",
+      "args": ["-y", "@joy-loyalty/mcp"],
+      "env": {
+        "JOY_APP_KEY": "<your-shop-id>",
+        "JOY_SECRET_KEY": "<your-key-from-step-1>"
+      }
+    }
+  }
+}
+```
+
+No install required — `npx` downloads and runs the latest version automatically. [Node.js](https://nodejs.org) 20 or later must be installed on your machine.
+
+**3. Restart your AI client** and try asking: *"How is my loyalty program set up?"*
+
+## Enabling write access (optional)
+
+By default, the server is **read-only** — even if you provide your full secret key. To allow the assistant to award points, adjust balances, or make other changes, you must explicitly opt in:
+
+```json
+"env": {
+  "JOY_APP_KEY": "<your-shop-id>",
+  "JOY_SECRET_KEY": "<your-full-secret-key>",
+  "JOY_MCP_ENABLE_WRITES": "true"
+}
+```
+
+⚠️ **`"true"` must be quoted** — it's a text value, not a JSON boolean. Writing `true` without quotes will cause your AI client to reject the whole configuration with an error like *"not a valid MCP server configuration"*.
+
+Your Joy plan must be **Advanced or higher** to use the API.
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `JOY_APP_KEY` | Yes | Your shop ID |
+| `JOY_SECRET_KEY` | Yes (one of these two) | Your API key — a read-only (`ro_...`) or full secret key from Settings → Manage keys |
+| `JOY_MCP_ENABLE_WRITES` | No | Set to `"true"` (quoted) to allow point/data changes. Requires a full secret key — read-only keys can never write regardless of this setting |
+| `JOY_API_BASE_URL` | No | Defaults to production. Only change this if instructed by Joy support |
+
+## What it can do
+
+**Always available (read-only):**
+- Look up a member's points, tier, and profile
+- List members and browse their point/reward/referral history
+- View your shop's tiers, earning rules, and redemption rules
+- View referral program performance
+
+**With write access enabled:**
+- Award or deduct points, with a mandatory reason recorded for every change
+- Adjust a member's balance (always previews the change before applying it)
+- Redeem points for a reward, refund a redeemed coupon, or change a member's tier
+- Generate a referral invite link
+
+Every point-changing action requires a stated reason and is recorded in your Joy activity log for audit purposes.
+
+## Security
+
+- The server only talks to Joy's official API — it never sends your data anywhere else.
+- Your API key is only sent to Joy's servers, over HTTPS.
+- Read-only keys cannot perform any write operation, even if explicitly requested.
+- Destructive actions (deducting points, refunds, tier changes) require your AI client's own confirmation step before running.
+
+## Support
+
+Questions or issues: contact Joy support through your admin dashboard, or visit [joy.so](https://joy.so).

package/build/config.js

@@ -0,0 +1,55 @@
+export class ConfigError extends Error {
+}
+const DEFAULT_API_BASE_URL = 'https://api.joy.so';
+// Every request carries the shop's secret key in headers — a config pointing at
+// an attacker's host would exfiltrate it on the first call. Only Joy API hosts
+// (prod, staging, Firebase staging projects) and local emulators are accepted.
+const JOY_API_HOSTS = new Set(['api.joy.so', 'dev-api.joy.so']);
+const FIREBASE_STAGING_HOST = /^avada-joy(-staging(-\d+)?)?\.(firebaseapp\.com|web\.app)$/;
+function assertAllowedBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new ConfigError(`JOY_API_BASE_URL is not a valid URL: "${baseUrl}".`);
+    }
+    const host = parsed.hostname;
+    const isLocal = host === 'localhost' || host === '127.0.0.1';
+    // Non-local traffic must be TLS — the key travels in headers, and http://
+    // to a real host hands it to any on-path attacker.
+    if (!isLocal && parsed.protocol !== 'https:') {
+        throw new ConfigError(`JOY_API_BASE_URL must use https (got "${parsed.protocol}//") — the shop's secret key travels in request headers.`);
+    }
+    if (isLocal || JOY_API_HOSTS.has(host) || FIREBASE_STAGING_HOST.test(host))
+        return;
+    throw new ConfigError(`JOY_API_BASE_URL host "${host}" is not a Joy API host — refusing to send the shop's secret key there. Allowed: api.joy.so, dev-api.joy.so, avada-joy-staging-N.firebaseapp.com, localhost.`);
+}
+/**
+ * Load and validate configuration from environment variables. Fails fast with an
+ * actionable message — a misconfigured server must never reach the transport.
+ */
+export function loadConfig(env = process.env) {
+    const appKey = env.JOY_APP_KEY?.trim();
+    const secretKey = env.JOY_SECRET_KEY?.trim() || undefined;
+    const privateBotKey = env.JOY_PRIVATE_BOT_KEY?.trim() || undefined;
+    const apiBaseUrl = (env.JOY_API_BASE_URL?.trim() || DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+    assertAllowedBaseUrl(apiBaseUrl);
+    if (!appKey) {
+        throw new ConfigError('Missing JOY_APP_KEY (your shop ID). Set it in the "env" block of your MCP client config.');
+    }
+    if (!secretKey && !privateBotKey) {
+        throw new ConfigError('Missing credential: set JOY_SECRET_KEY (merchant API secret key) or JOY_PRIVATE_BOT_KEY (Joy-internal, read-only).');
+    }
+    if (secretKey && privateBotKey) {
+        throw new ConfigError('Set only ONE of JOY_SECRET_KEY or JOY_PRIVATE_BOT_KEY — they are mutually exclusive auth modes.');
+    }
+    const mode = privateBotKey ? 'internal-bot' : 'merchant';
+    // Writes require the merchant secret key AND an explicit opt-in flag. Having the
+    // secret key alone is not consent: it is the only key a merchant has.
+    const writesEnabled = mode === 'merchant' && env.JOY_MCP_ENABLE_WRITES === 'true';
+    // 0 is meaningful: "always dry-run every deduction" (most conservative)
+    const rawThreshold = Number(env.JOY_MCP_DEDUCT_DRYRUN_THRESHOLD ?? '1000');
+    const deductDryRunThreshold = Number.isFinite(rawThreshold) && rawThreshold >= 0 ? rawThreshold : 1000;
+    return { apiBaseUrl, appKey, secretKey, privateBotKey, mode, writesEnabled, deductDryRunThreshold };
+}