epicmerch-mcp 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epicmerch-mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "MCP server for EpicMerch — integrates e-commerce into Claude and ChatGPT",
   "type": "module",
   "main": "src/index.js",

package/skills/epicmerch-payments.md

@@ -0,0 +1,86 @@
+---
+name: epicmerch-payments
+description: Set up payments on an EpicMerch store — help the merchant pick between Razorpay (India, default) and Stripe (international), then route to the right setup skill.
+---
+
+# EpicMerch Payments — the umbrella
+
+This is the entry point for any "set up payments" / "configure checkout" / "add card payments" intent. Your job is to figure out **which processor the merchant should use**, then hand off to the matching detailed skill.
+
+## Step 1: Check what's already configured
+
+Before asking anything, call `merchant_get_checkout_settings()`. The response tells you:
+
+- `checkoutType` — current active flow (`"epicmerch"`, `"stripe"`, or `"shiprocket"`)
+- `razorpayKeyId` (string or null) + `razorpayKeySecretIsSet` (bool)
+- `stripePublishableKey` (string or null) + `stripeSecretKeyIsSet` (bool) + `stripeWebhookSecretIsSet` (bool)
+
+Decide based on what's there:
+
+| Current state | Suggested action |
+|---|---|
+| Nothing configured | Help the merchant pick + set up (continue to Step 2) |
+| Razorpay configured, `checkoutType: epicmerch` | Tell them: "Razorpay is already live on your store. Want to add Stripe as a backup / switch to Stripe?" |
+| Stripe configured, `checkoutType: stripe` | Tell them: "Stripe is already live. Want to switch back to Razorpay?" |
+| Both configured, only one active | Tell them which is active + ask if they want to switch |
+
+If something's clearly already set up and they didn't ask to change it, stop here. Don't redo configured work.
+
+## Step 2: Help them pick
+
+If nothing is configured (or they want to add a new one), help them choose:
+
+| Question | Razorpay | Stripe |
+|---|---|---|
+| Where are most of your customers? | India 🇮🇳 | International 🌍 |
+| Currency you charge in? | INR primarily | USD, EUR, GBP, AUD, etc. |
+| Payment methods you want? | UPI, netbanking, Indian cards, wallets | Cards, Apple Pay, Google Pay, Stripe Link |
+| Compliance | RBI-compliant by default | Stripe handles PCI; you handle GDPR |
+| Setup time | ~5 min if account exists | ~10 min (needs webhook config) |
+| Account onboarding | KYC ~24h (already done usually) | Stripe activation can take a day |
+
+Ask the merchant ONE question that disambiguates. Don't make them read the table. The best single question is usually:
+
+> "Where are most of your customers — India, or international?"
+
+- **India only** → Razorpay
+- **International / mostly outside India** → Stripe
+- **Both / not sure** → ask: "What currency do you want to charge in?" then route accordingly.
+
+## Step 3: Hand off to the specific skill
+
+Once you know which one:
+
+- **Razorpay** → hand off to `/epicmerch-razorpay`. Don't try to configure it inline; the specific skill has the right Razorpay-dashboard URLs, key format hints, and the activation step.
+- **Stripe** → hand off to `/epicmerch-stripe`. Same reasoning — that skill has the webhook URL, the test recipe, and the activation step.
+
+If you're running inside a client that doesn't support slash command handoff (e.g. **Codex**), invoke the same MCP tools yourself:
+
+**For Razorpay inline:**
+```
+merchant_configure_razorpay({ keyId: "rzp_live_...", keySecret: "..." })
+merchant_set_checkout_type({ type: "epicmerch" })
+merchant_get_checkout_settings()    // verify
+merchant_diagnose()                  // confirm readiness
+```
+
+**For Stripe inline:**
+```
+merchant_configure_stripe({ publishableKey: "pk_live_...", secretKey: "sk_live_...", webhookSecret: "whsec_..." })
+merchant_test_stripe_connection()
+merchant_set_checkout_type({ type: "stripe" })
+```
+
+## Step 4: After setup
+
+Once whichever processor is live, suggest:
+
+- "Want to test? Place a small test order on your storefront. With test keys, no real money moves; with live keys, you can refund it after."
+- "Need to set up Shiprocket for shipping? Use `merchant_get_logistics_settings` first to see what's there."
+- "Ready to launch? Run `merchant_diagnose()` — I'll check everything."
+
+## Style
+
+- Don't ask "Razorpay or Stripe?" out of context. ALWAYS check current state first (Step 1) — if it's set up, just confirm.
+- Don't pile up questions. One at a time.
+- Never paste the merchant's secret back at them — refer to it as `"the secret you provided"`. Treat secrets as write-only.

package/skills/epicmerch-razorpay.md

@@ -0,0 +1,98 @@
+---
+name: epicmerch-razorpay
+description: Set up Razorpay payments for an EpicMerch store conversationally — get the Key ID + Secret from Razorpay's dashboard, save them, and activate the EpicMerch Checkout flow.
+---
+
+# EpicMerch Razorpay Setup
+
+You're helping a merchant configure Razorpay as their payment processor. This pairs Razorpay with EpicMerch's default checkout flow (Razorpay for payments + Shiprocket for shipping). Walk them through these steps.
+
+## Step 1: Confirm they have a Razorpay account
+
+Ask: "Do you already have a Razorpay account at dashboard.razorpay.com? If not, sign up first — it's free and KYC takes ~24 hours."
+
+If they're in India and just starting out, Razorpay is the most common choice. For international merchants, hand off to `/epicmerch-stripe` instead.
+
+## Step 2: Decide test vs live mode
+
+Ask: "Are you setting up for testing (`rzp_test_...` keys), or going live with real customers (`rzp_live_...`)?"
+
+Make sure they understand:
+- **Test keys** — no real money. Use Razorpay's test card numbers from their docs. Switch to live before launching.
+- **Live keys** — real money. Account must be activated (KYC complete + bank account linked).
+
+## Step 3: Collect their API keys
+
+Tell them:
+
+> "In a new browser tab, open https://dashboard.razorpay.com → Settings → API Keys → Generate Key (or Show, if you've generated one before).
+>
+> Copy these two values:
+> - **Key ID** — looks like `rzp_live_XXXXX` or `rzp_test_XXXXX`
+> - **Key Secret** — long random string. Razorpay only shows it ONCE when you generate. If you've already saved it somewhere safe, paste it now."
+
+If the merchant lost their secret, tell them: "You'll need to regenerate the key pair in Razorpay's dashboard. The old Key ID stops working when you do this, so update both fields below."
+
+## Step 4: Save them
+
+Call:
+
+```
+merchant_configure_razorpay({
+  keyId:     "rzp_live_XXXXX",
+  keySecret: "your_secret_here"
+})
+```
+
+The server encrypts the secret before storing. The response confirms the save with `razorpayKeyId` echoed back and `razorpayKeySecretIsSet: true`.
+
+## Step 5: Activate the checkout
+
+Razorpay only powers payments under EpicMerch's default checkout flow. Activate it:
+
+```
+merchant_set_checkout_type({ type: "epicmerch" })
+```
+
+This sets the storefront to use EpicMerch Checkout (Razorpay payments + Shiprocket shipping). If the merchant was previously on Stripe or Shiprocket-managed checkout, this switches them over.
+
+## Step 6: Verify it took effect
+
+Call `merchant_get_checkout_settings()` and confirm the response includes:
+- `checkoutType: "epicmerch"`
+- `razorpayKeyId` matching what you just set
+- `razorpayKeySecretIsSet: true`
+
+If those line up, you're done.
+
+## Step 7: Smoke test (optional but recommended)
+
+Tell the merchant: "Want me to do a quick health check? I'll look at your full store readiness, including payment config."
+
+Then call `merchant_diagnose()`. Read off the `payment.razorpayConfigured` value — should be `true` — and the `readinessScore`.
+
+## Step 8: Done
+
+Say:
+
+> "Razorpay is now live on your storefront. Customers will see Razorpay's payment widget at checkout — cards, UPI, netbanking, wallets. **Make sure you're using live keys before launch** — test keys won't charge real money."
+
+If they're on test keys, remind them again: "When you're ready to launch, repeat Steps 3–4 with live keys."
+
+## Style
+
+- Ask one question at a time. Don't dump all the steps at once.
+- After each `merchant_*` call, read back the relevant field so the merchant sees progress.
+- If a save fails (e.g. validation error from the server), surface the error message verbatim — don't paraphrase.
+
+## Troubleshooting
+
+If `merchant_get_checkout_settings` shows `razorpayKeySecretIsSet: false` after Step 4, the secret didn't persist. Causes:
+- Empty string passed (Razorpay secrets are 30+ chars; if the merchant pasted nothing, the field stays empty)
+- Encryption key mismatch on the server side (rare; tell the merchant to check with support)
+
+If Step 5 errors with "must be one of: ...", you typed the wrong checkout type. Use exactly `"epicmerch"` (lowercase).
+
+## Handoff
+
+If the merchant says "actually I want Stripe instead" — switch to `/epicmerch-stripe`. If "what's the difference between Razorpay and Stripe?" — use `/epicmerch-payments` to compare.

package/src/tools/_examples.js

@@ -317,6 +317,13 @@ export const TOOL_EXAMPLES = {
     'Is Stripe configured correctly?',
     'Verify my Stripe keys work',
   ],
+
+  // --- Razorpay ---
+  merchant_configure_razorpay: [
+    'Set up Razorpay for my store',
+    'Add my Razorpay keys',
+    'Configure Razorpay payments',
+  ],
   merchant_set_checkout_type: [
     'Switch my checkout to Stripe',
     'Change checkout to Razorpay',

package/src/tools/merchant.js

@@ -362,6 +362,18 @@ export function merchantTools(client, session) {
       return ok(await client.authGet('/users/stripe/test'));
     },
 
+    // --- RAZORPAY CONFIGURATION ---
+    async merchant_configure_razorpay({ keyId, keySecret }) {
+      requireAuth();
+      if (!keyId && !keySecret) {
+        throw new Error('At least one of `keyId` or `keySecret` must be provided.');
+      }
+      const body = {};
+      if (keyId !== undefined)     body.razorpayKeyId     = keyId;
+      if (keySecret !== undefined) body.razorpayKeySecret = keySecret;
+      return ok(await client.authPut('/users/checkout-settings', body));
+    },
+
     async merchant_set_checkout_type({ type }) {
       requireAuth();
       const valid = ['epicmerch', 'stripe', 'shiprocket'];
@@ -603,6 +615,14 @@ const _baseMerchantToolDefs = [
     description: 'Verify the merchant\'s Stripe keys work by fetching their Stripe account. Returns accountId, country, and charges-enabled status.',
     schema: {},
   },
+  {
+    name: 'merchant_configure_razorpay',
+    description: 'Configure Razorpay payment processing for the merchant: stores Key ID + Key Secret. Pair with merchant_set_checkout_type({type:"epicmerch"}) to activate the EpicMerch Checkout flow that uses Razorpay. Both fields are optional individually so you can update one at a time (e.g. rotating the secret without re-entering the key id).',
+    schema: {
+      keyId:     { type: 'string', description: 'Razorpay Key ID, e.g. rzp_live_... or rzp_test_...' },
+      keySecret: { type: 'string', description: 'Razorpay Key Secret. Stored encrypted server-side.' },
+    },
+  },
   {
     name: 'merchant_set_checkout_type',
     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).',