epicmerch-mcp 1.3.21 → 1.3.23

package/skills/epicmerch.md

@@ -120,13 +120,10 @@ There is no hard "skip" here: `complete` requires a non-empty catalog. If the me
 
 Remember the answer as `visualStyle`.
 
-**4b — Scaffold + style.** Run `/epicmerch-storefront`, passing along the chosen
-`visualStyle`. It runs the tiered flow: it lays the standard skeleton from the
-`store_scaffold_full` tool (instant — no hand-writing), applies the matching Tailwind
-theme pass (or leaves it unstyled on "skip"), confirms the session-restore block, and
-ends on the `/epicmerch-verify` gate. You don't style files here — the leaf skill owns
-the theme pass. Recap what it reports (`✓ Storefront scaffolded + styled (<visualStyle>)`
-or `unstyled`).
+**4b — Scaffold + style.** Run `/epicmerch-storefront`. After it finishes:
+- If `visualStyle` ≠ skip, do a quick styling pass: 5-10 well-chosen Tailwind utility classes per component (typography, spacing, colour) matching `visualStyle`. Don't overdo it.
+- Confirm `src/lib/epicmerch.js` contains the **session-restore block** (the `localStorage.getItem('customerInfo') → setCustomerToken` snippet). Without it, OTP login appears to work but doesn't survive a page reload — the #1 silent storefront bug. The 1.3.4+ scaffold includes it by default; add it manually if missing.
+- Recap `✓ Storefront scaffolded + styled (<visualStyle>)` (or `unstyled`).
 
 **Optional add-on (not gated):** once the storefront exists, you may offer a 1-click Buy Now button — *"Want a 1-click 'Buy Now' button? Razorpay's Magic Checkout lets customers buy without a cart screen."* → `/epicmerch-magic-checkout` (it verifies Razorpay first). This is optional and does NOT affect `complete`; the merchant can add it anytime by saying *"add a Buy Now button"*. Then re-loop.
 

package/src/adapters/mcp.js

@@ -11,6 +11,7 @@ import { developerTools, developerToolDefs } from '../tools/developer.js';
 import { scaffoldTools, scaffoldToolDefs } from '../tools/scaffold.js';
 import { merchantTools, merchantToolDefs } from '../tools/merchant.js';
 import { prompts } from '../prompts/index.js';
+import { VERSION } from '../version.js';
 
 const __dir = dirname(fileURLToPath(import.meta.url));
 const readResource = (rel) => readFileSync(join(__dir, '../resources', rel), 'utf-8');
@@ -27,7 +28,7 @@ function buildZodSchema(schemaDef) {
 }
 
 export async function startMcpAdapter(session, client) {
-  const server = new McpServer({ name: 'epicmerch', version: '1.0.0' });
+  const server = new McpServer({ name: 'epicmerch', version: VERSION });
 
   const allToolDefs = [...sessionToolDefs, ...developerToolDefs, ...scaffoldToolDefs, ...merchantToolDefs];
   const allHandlers = {

package/src/adapters/openapi.js

@@ -6,6 +6,7 @@ import { sessionTools, sessionToolDefs } from '../tools/session.js';
 import { developerTools, developerToolDefs } from '../tools/developer.js';
 import { scaffoldTools, scaffoldToolDefs } from '../tools/scaffold.js';
 import { merchantTools, merchantToolDefs } from '../tools/merchant.js';
+import { VERSION } from '../version.js';
 
 const ALL_TOOL_DEFS = [...sessionToolDefs, ...developerToolDefs, ...scaffoldToolDefs, ...merchantToolDefs];
 
@@ -46,7 +47,7 @@ function buildOpenApiSpec(serverUrl) {
 
   return {
     openapi: '3.1.0',
-    info: { title: 'EpicMerch MCP Tools', version: '1.0.0', description: 'EpicMerch tools for Claude and ChatGPT' },
+    info: { title: 'EpicMerch MCP Tools', version: VERSION, description: 'EpicMerch tools for Claude and ChatGPT' },
     servers: [{ url: serverUrl || 'https://mcp.epicmerch.in' }],
     paths,
     components: {

package/src/auth.js

@@ -7,6 +7,13 @@ export class Session {
   #jwts = new Map();
   #authMode;
   #tokenStore;
+  // Active PLATFORM store (EpicMerch Store entity, multi-store merchants).
+  // Distinct from #stores/#active above, which are named CREDENTIAL PROFILES
+  // (login entries in ~/.epicmerch/token.json / EPICMERCH_STORES) — do not
+  // conflate the two. When set, the Client sends it as X-Store-Id on every
+  // request and the server's tenantMiddleware scopes data to that store.
+  // null = server default (API key's pinned store, else Store #1).
+  #activePlatformStoreId = null;
 
   constructor({ stores, defaultStore, apiUrl, authMode = 'apikey', tokenStore = null }) {
     if (!stores || Object.keys(stores).length === 0) {
@@ -27,6 +34,10 @@ export class Session {
   getApiKey() { return this.#stores[this.#active]; }
   getApiUrl() { return this.#apiUrl; }
 
+  // --- Platform store context (multi-store; see field comment above) ---
+  activePlatformStoreId() { return this.#activePlatformStoreId; }
+  setActivePlatformStoreId(id) { this.#activePlatformStoreId = id || null; }
+
   getAuthMode() {
     return this.#authMode;
   }

package/src/client.js

@@ -40,6 +40,12 @@ export class Client {
     } else {
       headers['x-api-key'] = this.#session.getApiKey();
     }
+    // Active platform store (multi-store merchants, set via merchant_switch_store).
+    // Re-read from the session on every call — headers are built per-request via
+    // the `headers: () => ...` callbacks, so a switch takes effect immediately.
+    // #authHeaders() spreads this, so BOTH header paths carry it.
+    const platformStoreId = this.#session.activePlatformStoreId?.();
+    if (platformStoreId) headers['X-Store-Id'] = platformStoreId;
     return headers;
   }
 

package/src/lib/onboardingState.js

@@ -1,159 +1,163 @@
-// src/lib/onboardingState.js
-//
-// The CONTROL PLANE of the /epicmerch onboarding harness.
-//
-// This module is the single source of truth for "what's done / what's next /
-// are we complete". It re-derives that from live server state on every call —
-// nothing is cached, nothing is asserted by the LLM. The thin skill loop in
-// epicmerch.md drives off `deriveOnboardingState`, and `merchant_diagnose`
-// reuses the same helpers (safeGet/unwrap/unwrapList/productStock) so the two
-// can never drift apart — the `countInStock` regression class is structurally
-// impossible once both read stock through the same `productStock`.
-//
-// THE GATE: `complete` is true only when EVERY step — including `verified` — is
-// done, and `verified.done` requires a fresh server-recorded `lastVerifiedAt`.
-// That timestamp is stamped ONLY by /epicmerch-verify (Deep mode) → merchant_mark_verified →
-// POST /api/users/verification-passed. The LLM cannot fake it; "done but never
-// verified" is unreachable.
-
-// Freshness window for the `verified` gate (hours). A store counts as verified
-// only if its last successful /epicmerch-verify (Deep mode) run was within this window. Kept
-// simple (time-based only) for now — re-verify-on-change is out of scope.
-export const VERIFIED_FRESHNESS_HOURS = 24;
-
-// Canonical step order. `nextStep` is the first not-done step in this order, and
-// `complete` is "no not-done step remains". `verified` is intentionally last so
-// the gate can't be satisfied before a live e2e run.
-export const STEP_ORDER = ['account', 'apiKey', 'payment', 'products', 'storefront', 'verified'];
-
-// Fetch a path, never throw. Returns { ok:true, data } or { ok:false, error }.
-// One failed read does not abort the others (callers Promise.all these).
-export const safeGet = async (client, path) => {
-  try { return { ok: true, data: await client.authGet(path) }; }
-  catch (e) { return { ok: false, error: e?.message || String(e) }; }
-};
-
-// Unwrap a single-object response, tolerating shape drift (e.g. profile may be
-// { user: {...} } or {...}). Returns `fallback` when the read failed.
-export const unwrap = (r, fallback = null) => (r?.ok ? (r.data ?? fallback) : fallback);
-
-// Unwrap a list response into a plain array, tolerating these shapes:
-//   [...]                    (bare array)
-//   { products:   [...] }    (products list endpoint)
-//   { categories: [...] }    (categories list endpoint)
-//   { keys:       [...] }    (api-keys list endpoint)
-// Returns null when the read failed (so callers can distinguish "fetch error"
-// from "fetched, empty").
-export const unwrapList = (r) => {
-  if (!r?.ok) return null;
-  const d = r.data;
-  if (Array.isArray(d)) return d;
-  if (Array.isArray(d?.products)) return d.products;
-  if (Array.isArray(d?.categories)) return d.categories;
-  if (Array.isArray(d?.keys)) return d.keys;
-  return [];
-};
-
-// Total available stock for a product. The Prisma API returns `stock` (NOT the
-// legacy Mongo field `countInStock` — reading that made EVERY product look
-// out-of-stock). For products with variants, true availability is the sum of
-// per-variant stock. Falls back to countInStock only for very old API shapes.
-export const productStock = (p) => {
-  if (Array.isArray(p?.variants) && p.variants.length > 0) {
-    return p.variants.reduce((sum, v) => sum + (Number(v?.stock) || 0), 0);
-  }
-  return Number(p?.stock ?? p?.countInStock ?? 0) || 0;
-};
-
-// True when `lastVerifiedAt` (ISO string or Date) is within the freshness window.
-export const isVerifiedFresh = (lastVerifiedAt, hours = VERIFIED_FRESHNESS_HOURS) => {
-  if (!lastVerifiedAt) return false;
-  const ts = new Date(lastVerifiedAt).getTime();
-  if (Number.isNaN(ts)) return false;
-  return (Date.now() - ts) < hours * 60 * 60 * 1000;
-};
-
-/**
- * Derive the deterministic onboarding state from live server reads + one client
- * flag. This is the ONLY place the harness decides done/next/complete.
- *
- * Server reads (4, in parallel):
- *   /users/settings          → account done (200) + lastVerifiedAt (verified)
- *   /keys                    → apiKey done (length > 0)
- *   /users/checkout-settings → payment done (processor + checkoutType)
- *   /products                → products done (total > 0)
- * Client flag:
- *   storefrontPresent        → storefront done (does src/lib/epicmerch.js exist?)
- *
- * @param {object} client - Client with authGet(path) → parsed JSON (throws on error).
- * @param {{ storefrontPresent?: boolean }} opts
- * @returns {Promise<{ steps: object, nextStep: string|null, complete: boolean }>}
- */
-export async function deriveOnboardingState(client, { storefrontPresent = false } = {}) {
-  const [settingsR, keysR, checkoutR, productsR] = await Promise.all([
-    safeGet(client, '/users/settings'),
-    safeGet(client, '/keys'),
-    safeGet(client, '/users/checkout-settings'),
-    safeGet(client, '/products'),
-  ]);
-
-  const settings = unwrap(settingsR);
-  const keys     = unwrapList(keysR) || [];
-  const checkout = unwrap(checkoutR);
-  const products = unwrapList(productsR) || [];
-
-  // --- account: the settings read succeeded (merchant is authenticated + provisioned).
-  const accountDone = settingsR.ok;
-
-  // --- apiKey: at least one storefront key issued.
-  const apiKeyDone = keys.length > 0;
-
-  // --- payment: a processor is configured AND a checkout type is selected.
-  const razorpayConfigured = Boolean(checkout?.razorpayKeyId && checkout?.razorpayKeySecretIsSet);
-  const stripeConfigured   = Boolean(checkout?.stripeSecretKeyIsSet);
-  const checkoutType       = checkout?.checkoutType ?? null;
-  const paymentDone = Boolean((razorpayConfigured || stripeConfigured) && checkoutType);
-
-  // --- products: at least one product in the catalog (prefer total, fall back to page length).
-  const productCount = Number(unwrap(productsR)?.total) || products.length;
-  const inStockCount = products.filter((p) => productStock(p) > 0).length;
-  const productsDone = productCount > 0;
-
-  // --- storefront: client says the scaffold exists locally.
-  const storefrontDone = Boolean(storefrontPresent);
-
-  // --- verified: server stamped lastVerifiedAt within the freshness window.
-  const lastVerifiedAt = settings?.lastVerifiedAt ?? null;
-  const verifiedDone = isVerifiedFresh(lastVerifiedAt);
-
-  const steps = {
-    account: accountDone
-      ? { done: true, detail: settings?.name ? `Store "${settings.name}" is provisioned.` : 'Merchant account is provisioned.' }
-      : { done: false, action: `Authenticate first — run \`npx epicmerch-mcp login\` in a terminal. (settings read failed: ${settingsR.error || 'unknown'})` },
-
-    apiKey: apiKeyDone
-      ? { done: true, detail: `${keys.length} storefront API key(s) issued.` }
-      : { done: false, action: 'Generate a storefront API key with merchant_generate_api_key.' },
-
-    payment: paymentDone
-      ? { done: true, detail: `Payment ready (checkoutType="${checkoutType}"${razorpayConfigured ? ', Razorpay configured' : ''}${stripeConfigured ? ', Stripe configured' : ''}).` }
-      : { done: false, action: 'Configure a payment processor — run /epicmerch-payments, then set the checkout type.' },
-
-    products: productsDone
-      ? { done: true, detail: `${productCount} product(s) in catalog (${inStockCount} in stock).` }
-      : { done: false, action: 'Add products — run /epicmerch-migrate (Shopify import) or merchant_create_product with the full shape (variants as { variant, stock }).' },
-
-    storefront: storefrontDone
-      ? { done: true, detail: 'Storefront scaffold present (src/lib/epicmerch.js found).' }
-      : { done: false, action: 'Scaffold the storefront — ask the merchant the vibe question (4a), then run /epicmerch-storefront (4b) and do a style pass.' },
-
-    verified: verifiedDone
-      ? { done: true, detail: `Verified live ${lastVerifiedAt} (within ${VERIFIED_FRESHNESS_HOURS}h).` }
-      : { done: false, action: 'Run /epicmerch-verify (Deep mode) — a full product→cart→order→cleanup pass against the live API. On success it stamps verification server-side (this is the un-fakeable gate; Smoke mode is the no-token fallback).' },
-  };
-
-  const nextStep = STEP_ORDER.find((k) => !steps[k].done) ?? null;
-  const complete = nextStep === null; // true ONLY when ALL steps incl. verified are done
-
-  return { steps, nextStep, complete };
-}
+// src/lib/onboardingState.js
+//
+// The CONTROL PLANE of the /epicmerch onboarding harness.
+//
+// This module is the single source of truth for "what's done / what's next /
+// are we complete". It re-derives that from live server state on every call —
+// nothing is cached, nothing is asserted by the LLM. The thin skill loop in
+// epicmerch.md drives off `deriveOnboardingState`, and `merchant_diagnose`
+// reuses the same helpers (safeGet/unwrap/unwrapList/productStock) so the two
+// can never drift apart — the `countInStock` regression class is structurally
+// impossible once both read stock through the same `productStock`.
+//
+// THE GATE: `complete` is true only when EVERY step — including `verified` — is
+// done, and `verified.done` requires a fresh server-recorded `lastVerifiedAt`.
+// That timestamp is stamped ONLY by /epicmerch-verify (Deep mode) → merchant_mark_verified →
+// POST /api/users/verification-passed. The LLM cannot fake it; "done but never
+// verified" is unreachable.
+
+// Freshness window for the `verified` gate (hours). A store counts as verified
+// only if its last successful /epicmerch-verify (Deep mode) run was within this window. Kept
+// simple (time-based only) for now — re-verify-on-change is out of scope.
+export const VERIFIED_FRESHNESS_HOURS = 24;
+
+// Canonical step order. `nextStep` is the first not-done step in this order, and
+// `complete` is "no not-done step remains". `verified` is intentionally last so
+// the gate can't be satisfied before a live e2e run.
+export const STEP_ORDER = ['account', 'apiKey', 'payment', 'products', 'storefront', 'verified'];
+
+// Fetch a path, never throw. Returns { ok:true, data } or { ok:false, error }.
+// One failed read does not abort the others (callers Promise.all these).
+export const safeGet = async (client, path) => {
+  try { return { ok: true, data: await client.authGet(path) }; }
+  catch (e) { return { ok: false, error: e?.message || String(e) }; }
+};
+
+// Unwrap a single-object response, tolerating shape drift (e.g. profile may be
+// { user: {...} } or {...}). Returns `fallback` when the read failed.
+export const unwrap = (r, fallback = null) => (r?.ok ? (r.data ?? fallback) : fallback);
+
+// Unwrap a list response into a plain array, tolerating these shapes:
+//   [...]                    (bare array)
+//   { products:   [...] }    (products list endpoint)
+//   { categories: [...] }    (categories list endpoint)
+//   { keys:       [...] }    (api-keys list endpoint)
+// Returns null when the read failed (so callers can distinguish "fetch error"
+// from "fetched, empty").
+export const unwrapList = (r) => {
+  if (!r?.ok) return null;
+  const d = r.data;
+  if (Array.isArray(d)) return d;
+  if (Array.isArray(d?.products)) return d.products;
+  if (Array.isArray(d?.categories)) return d.categories;
+  if (Array.isArray(d?.keys)) return d.keys;
+  return [];
+};
+
+// Total available stock for a product. The Prisma API returns `stock` (NOT the
+// legacy Mongo field `countInStock` — reading that made EVERY product look
+// out-of-stock). For products with variants, true availability is the sum of
+// per-variant stock. Falls back to countInStock only for very old API shapes.
+export const productStock = (p) => {
+  if (Array.isArray(p?.variants) && p.variants.length > 0) {
+    return p.variants.reduce((sum, v) => sum + (Number(v?.stock) || 0), 0);
+  }
+  return Number(p?.stock ?? p?.countInStock ?? 0) || 0;
+};
+
+// True when `lastVerifiedAt` (ISO string or Date) is within the freshness window.
+export const isVerifiedFresh = (lastVerifiedAt, hours = VERIFIED_FRESHNESS_HOURS) => {
+  if (!lastVerifiedAt) return false;
+  const ts = new Date(lastVerifiedAt).getTime();
+  if (Number.isNaN(ts)) return false;
+  return (Date.now() - ts) < hours * 60 * 60 * 1000;
+};
+
+/**
+ * Derive the deterministic onboarding state from live server reads + one client
+ * flag. This is the ONLY place the harness decides done/next/complete.
+ *
+ * Server reads (4, in parallel):
+ *   /users/settings          → account done (200) + lastVerifiedAt (verified)
+ *   /keys                    → apiKey done (length > 0)
+ *   /users/checkout-settings → payment done (processor + checkoutType)
+ *   /products                → products done (total > 0)
+ * Client flag:
+ *   storefrontPresent        → storefront done (does src/lib/epicmerch.js exist?)
+ *
+ * @param {object} client - Client with authGet(path) → parsed JSON (throws on error).
+ * @param {{ storefrontPresent?: boolean }} opts
+ * @returns {Promise<{ steps: object, nextStep: string|null, complete: boolean }>}
+ */
+export async function deriveOnboardingState(client, { storefrontPresent = false } = {}) {
+  const [settingsR, keysR, checkoutR, productsR] = await Promise.all([
+    safeGet(client, '/users/settings'),
+    safeGet(client, '/keys'),
+    safeGet(client, '/users/checkout-settings'),
+    safeGet(client, '/products'),
+  ]);
+
+  const settings = unwrap(settingsR);
+  const keys     = unwrapList(keysR) || [];
+  const checkout = unwrap(checkoutR);
+  const products = unwrapList(productsR) || [];
+
+  // --- account: the settings read succeeded (merchant is authenticated + provisioned).
+  const accountDone = settingsR.ok;
+
+  // --- apiKey: at least one storefront key issued.
+  const apiKeyDone = keys.length > 0;
+
+  // --- payment: a processor is configured AND a checkout type is selected.
+  const razorpayConfigured = Boolean(checkout?.razorpayKeyId && checkout?.razorpayKeySecretIsSet);
+  const stripeConfigured   = Boolean(checkout?.stripeSecretKeyIsSet);
+  const checkoutType       = checkout?.checkoutType ?? null;
+  const paymentDone = Boolean((razorpayConfigured || stripeConfigured) && checkoutType);
+
+  // --- products: at least one product in the catalog (prefer total, fall back to page length).
+  const productCount = Number(unwrap(productsR)?.total) || products.length;
+  const inStockCount = products.filter((p) => productStock(p) > 0).length;
+  const productsDone = productCount > 0;
+
+  // --- storefront: client says the scaffold exists locally.
+  const storefrontDone = Boolean(storefrontPresent);
+
+  // --- verified: server stamped lastVerifiedAt within the freshness window.
+  const lastVerifiedAt = settings?.lastVerifiedAt ?? null;
+  const verifiedDone = isVerifiedFresh(lastVerifiedAt);
+
+  const steps = {
+    account: accountDone
+      ? { done: true, detail: settings?.name ? `Store "${settings.name}" is provisioned.` : 'Merchant account is provisioned.' }
+      : { done: false, action: `Authenticate first — run \`npx epicmerch-mcp login\` in a terminal. (settings read failed: ${settingsR.error || 'unknown'})` },
+
+    apiKey: apiKeyDone
+      ? { done: true, detail: `${keys.length} storefront API key(s) issued.` }
+      : { done: false, action: 'Generate a storefront API key with merchant_generate_api_key.' },
+
+    // Per-shop: /users/checkout-settings is store-scoped (the client sends
+    // X-Store-Id from session.activePlatformStoreId), so this gate reflects the
+    // ACTIVE shop. settings.name (from the same store-scoped /users/settings read)
+    // names which shop, so the gate is unambiguous when a merchant has many shops.
+    payment: paymentDone
+      ? { done: true, detail: `Payment ready for "${settings?.name ?? 'this shop'}" (checkoutType="${checkoutType}"${razorpayConfigured ? ', Razorpay configured' : ''}${stripeConfigured ? ', Stripe configured' : ''}).` }
+      : { done: false, action: `Configure a payment processor for "${settings?.name ?? 'this shop'}" — run /epicmerch-payments, then set the checkout type.` },
+
+    products: productsDone
+      ? { done: true, detail: `${productCount} product(s) in catalog (${inStockCount} in stock).` }
+      : { done: false, action: 'Add products — run /epicmerch-migrate (Shopify import) or merchant_create_product with the full shape (variants as { variant, stock }).' },
+
+    storefront: storefrontDone
+      ? { done: true, detail: 'Storefront scaffold present (src/lib/epicmerch.js found).' }
+      : { done: false, action: 'Scaffold the storefront — ask the merchant the vibe question (4a), then run /epicmerch-storefront (4b) and do a style pass.' },
+
+    verified: verifiedDone
+      ? { done: true, detail: `Verified live ${lastVerifiedAt} (within ${VERIFIED_FRESHNESS_HOURS}h).` }
+      : { done: false, action: 'Run /epicmerch-verify (Deep mode) — a full product→cart→order→cleanup pass against the live API. On success it stamps verification server-side (this is the un-fakeable gate; Smoke mode is the no-token fallback).' },
+  };
+
+  const nextStep = STEP_ORDER.find((k) => !steps[k].done) ?? null;
+  const complete = nextStep === null; // true ONLY when ALL steps incl. verified are done
+
+  return { steps, nextStep, complete };
+}

package/src/tools/_examples.js

@@ -311,6 +311,14 @@ export const TOOL_EXAMPLES = {
     'Push a product to SR catalog',
   ],
 
+  // --- Multi-store ---
+  merchant_switch_store: [
+    'Switch to my other store',
+    'Work on my Streetwear store',
+    'Which stores do I have?',
+    'List my stores',
+  ],
+
   // --- Shopify migration ---
   merchant_shopify_migrate: [
     'Migrate my Shopify store',

package/src/tools/merchant.js

@@ -195,7 +195,13 @@ export function merchantTools(client, session) {
 
     // --- SHIPROCKET ---
     async merchant_list_sr_orders(body) { requireAuth(); return ok(await client.authPost('/sr-checkout/order-list', body)); },
-    async merchant_initiate_refund({ orderId, amount }) { requireAuth(); return ok(await client.authPost('/sr-checkout/refund', { order_id: orderId, amount })); },
+    async merchant_initiate_refund({ orderId, amount, reason, restock } = {}) {
+      requireAuth();
+      const body = { amount };
+      if (reason !== undefined) body.reason = reason;
+      if (restock !== undefined) body.restock = restock;
+      return ok(await client.authPost(`/orders/${orderId}/refund`, body));
+    },
     async merchant_sync_product_to_sr({ productId }) { requireAuth(); return ok(await client.authPost('/sr-checkout/catalog/sync-product', { productId })); },
 
     // --- SHOPIFY MIGRATION ---
@@ -399,12 +405,13 @@ export function merchantTools(client, session) {
       // src/lib/onboardingState.js and SHARED with the onboarding state machine,
       // so the health report and the harness gate can never drift — same reads,
       // same stock math, one source of truth (kills the countInStock drift class).
-      const [profileR, productsR, categoriesR, checkoutR, keysR] = await Promise.all([
+      const [profileR, productsR, categoriesR, checkoutR, keysR, storesR] = await Promise.all([
         safeGet(client, '/users/profile'),
         safeGet(client, '/products'),
         safeGet(client, '/categories'),
         safeGet(client, '/users/checkout-settings'),
         safeGet(client, '/keys'),
+        safeGet(client, '/stores'),
       ]);
 
       const profile  = unwrap(profileR, null);
@@ -413,8 +420,18 @@ export function merchantTools(client, session) {
       const checkout = unwrap(checkoutR, null);
       const keys     = unwrapList(keysR);
 
+      // MULTI-STORE: every section above is scoped server-side by X-Store-Id (the
+      // active PLATFORM store from session.activePlatformStoreId). Resolve that
+      // store's id/name so the diagnosis is unambiguous about WHICH shop it
+      // describes — the checkout/payment reads are per-shop now.
+      const storesData    = unwrap(storesR, null);
+      const activeStoreId = session.activePlatformStoreId?.() || storesData?.activeStoreId || null;
+      const activeStore   = (storesData?.stores || []).find((s) => s.id === activeStoreId) || null;
+
       // Build each section, returning { error } if its fetch failed.
       const store = profileR.ok ? {
+        activeStoreId,
+        activeStoreName: activeStore?.name ?? null,
         name:      profile?.name ?? profile?.user?.name ?? null,
         currency:  profile?.currency ?? profile?.user?.currency ?? null,
         hasDomain: Boolean(profile?.domain ?? profile?.user?.domain),
@@ -506,6 +523,35 @@ export function merchantTools(client, session) {
       requireAuth();
       return ok(await client.authPost('/users/verification-passed', {}));
     },
+
+    // --- MULTI-STORE: active-store context ---
+    // Sets the session's active PLATFORM store (EpicMerch Store entity — NOT a
+    // credential profile; see Session#activePlatformStoreId). Once set, the
+    // Client sends X-Store-Id on every request and the server's tenantMiddleware
+    // scopes all merchant tools to that store. No per-tool storeId params.
+    // GET /api/stores returns { stores: [{id,name,slug,status,createdAt}], activeStoreId, maxStores }.
+    async merchant_switch_store({ store } = {}) {
+      requireAuth();
+      const data = await client.authGet('/stores');
+      const list = Array.isArray(data) ? data : (data.stores || []);
+      if (!store) {
+        return ok({
+          activeStoreId: session.activePlatformStoreId() || data.activeStoreId || null,
+          stores: list,
+        });
+      }
+      const match = list.find(s => s.id === store
+        || (s.slug && s.slug.toLowerCase() === String(store).toLowerCase())
+        || (s.name && s.name.toLowerCase() === String(store).toLowerCase()));
+      if (!match) {
+        return ok({
+          error: `No store matching "${store}".`,
+          stores: list.map(s => ({ id: s.id, name: s.name, slug: s.slug })),
+        });
+      }
+      session.setActivePlatformStoreId(match.id);
+      return ok({ switched: true, activeStore: { id: match.id, name: match.name, slug: match.slug } });
+    },
   };
 }
 
@@ -593,8 +639,18 @@ const _baseMerchantToolDefs = [
   { name: 'merchant_update_email_settings', description: 'Update email settings.', schema: {} },
   { name: 'merchant_get_logistics_settings', description: 'Get logistics/shipping settings.', schema: {} },
   { name: 'merchant_update_logistics_settings', description: 'Update logistics settings.', schema: {} },
-  { name: 'merchant_get_checkout_settings', description: 'Get checkout settings.', schema: {} },
-  { name: 'merchant_update_checkout_settings', description: 'Update checkout settings.', schema: {} },
+  { name: 'merchant_get_checkout_settings', description: 'Get checkout settings: checkoutType plus the merchant-defined per-store pricing (taxRate as a fraction, shippingFee, freeShippingThreshold, codEnabled). A null pricing field means the store falls back to the platform env/default. These values are the single source of truth the storefront display is seeded from, so they always match what the server charges.', schema: {} },
+  {
+    name: 'merchant_update_checkout_settings',
+    description: 'Update checkout settings. Set the merchant-defined per-store pricing here — it is the single source of truth used for BOTH the storefront display and the server-side charge. IMPORTANT: taxRate is a FRACTION (0.18 = 18% GST), NOT a percentage. Pass null (or "") for any pricing field to clear it and fall back to the platform env/default. Use merchant_set_checkout_type / merchant_configure_razorpay / merchant_configure_stripe for those specific fields; this tool can also set them but the dedicated tools validate inputs.',
+    schema: {
+      checkoutType: { type: 'string', description: "Checkout processor: 'epicmerch' | 'stripe' | 'shiprocket'" },
+      taxRate: { type: 'number', description: 'Tax applied to the cart subtotal, as a FRACTION (0.18 = 18%). null clears → env/default.' },
+      shippingFee: { type: 'number', description: 'Flat shipping fee in the store currency. null clears → env/default.' },
+      freeShippingThreshold: { type: 'number', description: 'Subtotal at or above which shipping is free. null clears → env/default.' },
+      codEnabled: { type: 'boolean', description: 'Whether Cash on Delivery is offered at checkout.' },
+    },
+  },
   { name: 'merchant_get_security_settings', description: 'Get security settings and allowed domains.', schema: {} },
   { name: 'merchant_add_allowed_domain', description: 'Add an allowed CORS domain.', schema: { domain: { type: 'string' } } },
   { name: 'merchant_remove_allowed_domain', description: 'Remove an allowed CORS domain.', schema: { domain: { type: 'string' } } },
@@ -612,7 +668,7 @@ const _baseMerchantToolDefs = [
   { name: 'merchant_track_shipment', description: 'Track a shipment by tracking ID.', schema: { trackingId: { type: 'string' } } },
   { name: 'merchant_get_consolidation_report', description: 'Get financial consolidation report.', schema: {} },
   { name: 'merchant_list_sr_orders', description: 'List Shiprocket orders.', schema: {} },
-  { name: 'merchant_initiate_refund', description: 'Initiate a Shiprocket refund.', schema: { orderId: { type: 'string' }, amount: { type: 'number' } } },
+  { name: 'merchant_initiate_refund', description: 'Issue a real provider-backed refund (Stripe/Razorpay/Shiprocket) for an order. Full or partial; set restock:true on a FULL refund to return inventory.', schema: { orderId: { type: 'string' }, amount: { type: 'number' }, reason: { type: 'string' }, restock: { type: 'boolean' } } },
   { name: 'merchant_sync_product_to_sr', description: 'Sync a product to Shiprocket catalog.', schema: { productId: { type: 'string' } } },
   {
     name: 'merchant_quick_setup',
@@ -666,6 +722,11 @@ const _baseMerchantToolDefs = [
     description: 'Set which checkout flow the merchant\'s storefront uses. Must be one of: "epicmerch" (Razorpay + Shiprocket), "stripe" (Stripe + Shiprocket), or "shiprocket" (full SR Checkout).',
     schema: { type: { type: 'string' } },
   },
+  {
+    name: 'merchant_switch_store',
+    description: 'Switch the active store (multi-store merchants). All subsequent merchant tools operate on this store. Call with no args to list available stores.',
+    schema: { store: { type: 'string', description: 'Store id, slug, or name. Omit to list stores.' } },
+  },
   {
     name: 'merchant_shopify_migrate',
     description: 'Migrate a Shopify store to EpicMerch. stage="extract" fetches Shopify data and returns a preview diff + sessionId. stage="import" runs the actual import for an approved sessionId.',

package/src/version.js

@@ -0,0 +1,13 @@
+// src/version.js
+// Single source of the package version, read from package.json at runtime — so
+// the MCP serverInfo handshake, the OpenAPI spec, etc. always match the published
+// version instead of drifting from a hardcoded literal. Works in local dev, the
+// npm tarball, and the staged .dxt (package.json sits at ../ from src/ in all three).
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+export const VERSION = JSON.parse(
+  readFileSync(join(__dir, '..', 'package.json'), 'utf-8')
+).version;