epicmerch-mcp 1.3.20 → 1.3.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/package.json +1 -1
- package/skills/epicmerch.md +239 -239
- package/src/adapters/mcp.js +2 -1
- package/src/adapters/openapi.js +2 -1
- package/src/version.js +13 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "epicmerch",
|
|
3
3
|
"description": "Run your EpicMerch store from chat — products, orders, analytics, Shopify migration, Stripe setup. Auto-installs the MCP + slash commands + browser OAuth.",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.3.22",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Aditya Patel",
|
|
7
7
|
"email": "aditya141312@gmail.com",
|
package/package.json
CHANGED
package/skills/epicmerch.md
CHANGED
|
@@ -1,239 +1,239 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: epicmerch
|
|
3
|
-
description: EpicMerch umbrella — guided 6-step onboarding wizard for new merchants, driven by a deterministic state machine (merchant_onboarding_state) that re-derives progress from live state and CANNOT report "complete" until a real end-to-end order test (/epicmerch-verify Deep mode) has stamped verification server-side. Also an intent router for merchants who already know what they want (scaffold a storefront, set up payments, add a Buy Now button, manage a store, migrate from Shopify, verify the store). Verification is the non-negotiable, structurally-enforced definition of done.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# EpicMerch — the umbrella
|
|
7
|
-
|
|
8
|
-
The **one entry point** for everything EpicMerch. Merchants don't need to memorise 10+ slash commands; they say what they want (or say nothing) and you figure out the right flow.
|
|
9
|
-
|
|
10
|
-
## Mode detection
|
|
11
|
-
|
|
12
|
-
Two modes. Pick one based on what the merchant said:
|
|
13
|
-
|
|
14
|
-
| What the merchant said when invoking `/epicmerch` | Mode |
|
|
15
|
-
|---|---|
|
|
16
|
-
| Nothing specific. Just `/epicmerch` with no extra words. | **Wizard mode** (Step A below) |
|
|
17
|
-
| "help me start", "I'm new", "set up everything", "what's next", "where do I begin" | **Wizard mode** |
|
|
18
|
-
| "set up Razorpay", "add a Buy Now button", "migrate Shopify", "scaffold a storefront", "show me my products" — anything with a clear specific intent | **Intent mode** (Step B below) |
|
|
19
|
-
|
|
20
|
-
If ambiguous, ask ONE disambiguating question: *"Want me to walk you through a full setup wizard, or is there one specific thing you want to do?"*
|
|
21
|
-
|
|
22
|
-
---
|
|
23
|
-
|
|
24
|
-
## DEFINITION OF DONE — read this before you finish (applies to BOTH modes)
|
|
25
|
-
|
|
26
|
-
**`/epicmerch` is not complete until a live end-to-end test has run and passed.**
|
|
27
|
-
|
|
28
|
-
This holds no matter how the build happened — the wizard's scaffold step, an intent-mode `/epicmerch-storefront`, OR a fully custom build you designed through brainstorming (e.g. a themed multi-page store). However you got here, the LAST thing you do before telling the merchant "your store is set up" is run **`/epicmerch-verify` (Deep mode)** — the full product→cart→order pipeline; it automatically falls back to Smoke mode if the server's test-login isn't configured.
|
|
29
|
-
|
|
30
|
-
Common trap: a design-heavy request ("build me a saree store") pulls you into scope/theme/spec brainstorming and a custom build, and the flow ends at "looks good!" without ever testing against the live API. **Don't let that happen.** After the storefront files are written and the `.env` has a real API key, run the e2e/verify gate. A store that was never tested against the live API is not done — that's exactly how the cart-shape / productId / out-of-stock bugs reached real merchants.
|
|
31
|
-
|
|
32
|
-
If you realize you're wrapping up `/epicmerch` and haven't run the test → run it now.
|
|
33
|
-
|
|
34
|
-
In **Wizard mode** this is enforced for you: `merchant_onboarding_state` will not return `complete` until `/epicmerch-verify` (Deep mode) has stamped verification server-side, so you structurally can't wrap up early. In **Intent mode** and custom/brainstormed builds there's no such gate — that's where this reminder matters most.
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## Step A — Wizard mode (the harness loop)
|
|
39
|
-
|
|
40
|
-
Wizard mode is a **deterministic loop driven by the `merchant_onboarding_state` tool** — not prose you interpret. The tool re-derives what's done, what's next, and whether you're complete from **live server state on every call**, and it enforces the gate: you **cannot** reach `complete` until a real `/epicmerch-verify` (Deep mode) run has stamped verification server-side. That is what makes `/epicmerch` un-breakable — the control flow lives in code + a hard gate, so "done but never verified" is structurally unreachable. You bring the creative work (the conversation, the product shape, the styling); the tool owns order, idempotency, and the gate.
|
|
41
|
-
|
|
42
|
-
Open with one sentence:
|
|
43
|
-
|
|
44
|
-
> "I'll set up your EpicMerch store. I'll check what's already done, do the next thing, and finish with a live end-to-end test — that test is the only thing that marks the setup complete."
|
|
45
|
-
|
|
46
|
-
### The loop
|
|
47
|
-
|
|
48
|
-
Repeat until the tool returns `complete: true`:
|
|
49
|
-
|
|
50
|
-
1. Check the local project: does `src/lib/epicmerch.js` exist? (`true`/`false` → `storefrontPresent`).
|
|
51
|
-
2. Call `merchant_onboarding_state({ storefrontPresent })`.
|
|
52
|
-
3. If `complete === true` → print the **wrap-up recap** (below) and STOP. You're done.
|
|
53
|
-
4. Else → read `nextStep` and perform **that one step's action** (see *Step actions* below). The `steps[nextStep].action` string is a short reminder; the full expansion is below. Do exactly ONE step, recap it in one line (`✓ <what happened>`), then go back to 1.
|
|
54
|
-
|
|
55
|
-
**Rules that keep the harness honest:**
|
|
56
|
-
- Never skip ahead, never decide completion yourself, never print "your store is set up" before the tool returns `complete: true`.
|
|
57
|
-
- The loop is inherently idempotent — every turn re-reads live state, so re-running after a partial setup just resumes where you left off.
|
|
58
|
-
- If you catch yourself about to wrap up without `complete`, call the tool again — it will name the real gap.
|
|
59
|
-
|
|
60
|
-
### Step actions (the expansion of each `nextStep`)
|
|
61
|
-
|
|
62
|
-
#### `account` — authenticate
|
|
63
|
-
The tool couldn't read your settings (not connected / 401). Tell the merchant:
|
|
64
|
-
|
|
65
|
-
> "Your CLI isn't connected. Run `npx epicmerch-mcp setup` (or `npx epicmerch-mcp login` if MCP is already installed), then ask me again."
|
|
66
|
-
|
|
67
|
-
STOP the loop. Resume (re-call the tool) once they confirm they're connected.
|
|
68
|
-
|
|
69
|
-
#### `apiKey` — generate a storefront key
|
|
70
|
-
|
|
71
|
-
> "You don't have an API key yet. I'll generate one called 'Storefront' — that's what the SDK uses to talk to your store."
|
|
72
|
-
|
|
73
|
-
Call `merchant_generate_api_key({ name: 'Storefront' })`. Recap `✓ API key generated.` and re-loop.
|
|
74
|
-
|
|
75
|
-
#### `payment` — configure a processor
|
|
76
|
-
Ask **one** question:
|
|
77
|
-
|
|
78
|
-
> "Where do most of your customers buy from?
|
|
79
|
-
> 1) India (Razorpay — recommended)
|
|
80
|
-
> 2) Outside India (Stripe)"
|
|
81
|
-
|
|
82
|
-
- "India" / "1" → run `/epicmerch-payments` (it takes the Razorpay path)
|
|
83
|
-
- "outside" / "global" / "2" → run `/epicmerch-payments` (it takes the Stripe path)
|
|
84
|
-
|
|
85
|
-
`/epicmerch-payments` configures the chosen processor **and** the checkout type — the tool's `payment` step needs both before it counts as done. Re-loop; the tool confirms `payment.done`.
|
|
86
|
-
|
|
87
|
-
#### `products` — fill the catalog
|
|
88
|
-
The catalog is empty (the tool counts an empty catalog as not-done, so this step keeps surfacing until at least one product exists). Ask:
|
|
89
|
-
|
|
90
|
-
> "Your catalog is empty. Want me to:
|
|
91
|
-
> 1) Migrate your existing Shopify store
|
|
92
|
-
> 2) Add your first product right now
|
|
93
|
-
> 3) Add a quick sample product so we can finish, and you replace it later"
|
|
94
|
-
|
|
95
|
-
- "Shopify" / "1" → run `/epicmerch-migrate`
|
|
96
|
-
- "first product" / "2" → walk through it with `merchant_create_product`. **Do NOT just ask for name + price** — products that ship without variants and images break the storefront UX (empty size picker, broken image). Collect the FULL shape in ONE round of questions:
|
|
97
|
-
- **Name + Category** (`name`, `type`)
|
|
98
|
-
- **Description** (`description`)
|
|
99
|
-
- **Pricing** — list price (`price`), plus on-sale fields if applicable (`salePrice`, `discountPercent`). *"If this product is on sale, tell me the sale price and discount %. Otherwise say 'no sale'."*
|
|
100
|
-
- **Variants** (`variants`) — array of `{ variant: 'S', stock: 5 }` entries. *"What sizes / colors / options does this come in, and how many of each in stock? If just one option, say 'no variants'."* When passed, the server derives total stock from `sum(variant.stock)` and ignores the top-level `stock`.
|
|
101
|
-
- **Images** (`images`) — array of gallery URLs. Optionally `image` for an explicit primary; if omitted the server uses `images[0]`.
|
|
102
|
-
Pass everything to `merchant_create_product` in ONE call — never create-then-update.
|
|
103
|
-
- "sample" / "3" → create one reasonable sample product (full shape, a couple of variants, a placeholder image) so the loop can progress. Tell the merchant it's a placeholder they can edit or delete later.
|
|
104
|
-
|
|
105
|
-
There is no hard "skip" here: `complete` requires a non-empty catalog. If the merchant truly wants to stop, be honest that onboarding stays incomplete until a product exists.
|
|
106
|
-
|
|
107
|
-
#### `storefront` — scaffold into the project
|
|
108
|
-
`storefrontPresent` is false. First check the project: does `package.json` exist with React / Vite / Next in dependencies?
|
|
109
|
-
|
|
110
|
-
- **Not a frontend project / no `package.json`**: tell the merchant *"No frontend project detected here. Run `/epicmerch` from inside a React/Vite/Next project to scaffold the storefront."* `storefrontPresent` stays false, so the loop keeps flagging `storefront` — be honest that `complete` needs the storefront scaffolded (they can finish from a project later; a chat-only setup won't reach `complete`).
|
|
111
|
-
- **Project detected, no SDK file**: do the two-part sub-flow:
|
|
112
|
-
|
|
113
|
-
**4a — Visual style (before scaffolding).** Ask ONE question so the components match their vibe:
|
|
114
|
-
|
|
115
|
-
> "Quick — what's the vibe of your store?
|
|
116
|
-
> 1) Editorial Funk (bold typography, big imagery, asymmetric layouts)
|
|
117
|
-
> 2) Minimal Mono (clean, monochrome, lots of whitespace)
|
|
118
|
-
> 3) Vibrant Pop (colourful, rounded corners, playful)
|
|
119
|
-
> 4) Skip — functional unstyled scaffolds, I'll polish later"
|
|
120
|
-
|
|
121
|
-
Remember the answer as `visualStyle`.
|
|
122
|
-
|
|
123
|
-
**4b — Scaffold + style.** Run `/epicmerch-storefront`. After it finishes:
|
|
124
|
-
- 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.
|
|
125
|
-
- 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.
|
|
126
|
-
- Recap `✓ Storefront scaffolded + styled (<visualStyle>)` (or `unstyled`).
|
|
127
|
-
|
|
128
|
-
**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.
|
|
129
|
-
|
|
130
|
-
#### `verified` — the gate (the ONLY step that flips `complete`)
|
|
131
|
-
This is the un-fakeable half of the harness. Run **`/epicmerch-verify` (Deep mode)** automatically:
|
|
132
|
-
|
|
133
|
-
> "Last step — a live end-to-end test to confirm everything actually works."
|
|
134
|
-
|
|
135
|
-
It gets a customer session, creates a throwaway test product, adds it to a cart, creates a real order (exercising stock reservation + Razorpay order creation, no charge), verifies every response shape, then cleans up (cancels the order, deletes the product). This proves the WHOLE pipeline, not just read paths. It gets its customer token via the server's env-gated test phone (`store_auth_send_otp` + `store_auth_verify_otp` against `E2E_TEST_PHONE`), so it needs no SMS and no manual login.
|
|
136
|
-
|
|
137
|
-
- **On pass:** `/epicmerch-verify` (Deep mode) calls **`merchant_mark_verified`**, which stamps `lastVerifiedAt` server-side. That is the ONLY thing that flips the tool's `verified` step to done. Re-loop — `merchant_onboarding_state` will now return `complete: true`.
|
|
138
|
-
- **On any failure:** do NOT stamp verified. Route to `/epicmerch-debug` automatically — its four-check playbook (OTP not persisting, products not loading, INSUFFICIENT_STOCK on checkout, cart 401) fixes it without further merchant intervention. Then re-run `/epicmerch-verify` (Deep mode).
|
|
139
|
-
- **If the e2e token step fails** because the server lacks `E2E_TEST_PHONE`/`E2E_TEST_OTP` (you'll see a normal SMS channel instead of `e2e-test`, or a 401 on verify), fall back to `/epicmerch-verify` (read-path + payload checks, no token). **Important:** the fallback does NOT stamp `lastVerifiedAt`, so the `verified` step stays not-done and the tool will NOT report `complete`. Be honest: *"Ran the read-path + payload checks. To mark the store verified end-to-end (and finish onboarding), your EpicMerch operator needs to set `E2E_TEST_PHONE`/`E2E_TEST_OTP` on the server so the automated order test can run."*
|
|
140
|
-
|
|
141
|
-
### Wizard wrap-up
|
|
142
|
-
|
|
143
|
-
Print this one-block recap **only when `merchant_onboarding_state` has returned `complete: true`** (i.e. the `verified` step is done — never before):
|
|
144
|
-
|
|
145
|
-
```
|
|
146
|
-
━━━ Your store is set up ━━━
|
|
147
|
-
✓ Account connected as <email>
|
|
148
|
-
✓ API key: <name>
|
|
149
|
-
✓ Payments: <Razorpay/Stripe>
|
|
150
|
-
✓ Catalog: <N> products
|
|
151
|
-
✓ Storefront: scaffolded into <project> (or "skipped — no project")
|
|
152
|
-
✗ Buy Now button: skipped (or ✓ if they added it)
|
|
153
|
-
✓ End-to-end test: product → cart → order → cleanup all passed
|
|
154
|
-
(verified live — lastVerifiedAt stamped server-side)
|
|
155
|
-
|
|
156
|
-
Next: restart your dev server (`npm run dev`) to pick up `.env`. Your
|
|
157
|
-
store works end-to-end. Ask me about analytics, notifications, or
|
|
158
|
-
abandoned-cart messages whenever you're ready.
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
---
|
|
162
|
-
|
|
163
|
-
## Step B — Intent mode (router)
|
|
164
|
-
|
|
165
|
-
The merchant said something specific. Match against the table below, pick the closest, hand off. If multiple match, ask ONE disambiguating question.
|
|
166
|
-
|
|
167
|
-
| The merchant says … | Route to |
|
|
168
|
-
|---|---|
|
|
169
|
-
| "set up EpicMerch", "scaffold a storefront", "build me a store", "integrate ecommerce" (and the project has no `src/lib/epicmerch.js`) | `/epicmerch-storefront` |
|
|
170
|
-
| "add login / OTP / sign in" | `/epicmerch-storefront` (auth slice) |
|
|
171
|
-
| "add a product catalog", "show products on my site", "product list with search" | `/epicmerch-storefront` (products slice) |
|
|
172
|
-
| "add a cart", "build checkout", "order history page", "multi-product checkout" | `/epicmerch-storefront` (orders slice) |
|
|
173
|
-
| "add Buy Now button", "1-click checkout", "impulse buy", "Razorpay Magic Checkout" | `/epicmerch-magic-checkout` |
|
|
174
|
-
| "set up payments", "accept cards", "configure checkout", "set up Razorpay", "set up Stripe", "India / international payments" | `/epicmerch-payments` |
|
|
175
|
-
| "connect my store to Claude / Cursor / Codex", "log in to EpicMerch", "install the MCP" | `/epicmerch-setup` |
|
|
176
|
-
| "show me my store / products / orders / sales", "manage my store from chat" | `/epicmerch-merchant` |
|
|
177
|
-
| "migrate from Shopify", "import my Shopify catalog" | `/epicmerch-migrate` |
|
|
178
|
-
| "my login isn't sticking", "products aren't loading", "checkout fails", "insufficient stock undefined", "something's broken" | `/epicmerch-debug` |
|
|
179
|
-
| "test everything", "does checkout actually work", "full end-to-end test", "run a real order test" | `/epicmerch-verify` (Deep mode) |
|
|
180
|
-
|
|
181
|
-
### Hand-off (or inline)
|
|
182
|
-
|
|
183
|
-
**In Claude Code / Claude Desktop / Cursor / VS Code Claude extension:**
|
|
184
|
-
|
|
185
|
-
Tell the merchant which slash command you're invoking, then proceed:
|
|
186
|
-
|
|
187
|
-
> "Sounds like you want X — running `/epicmerch-Y` now."
|
|
188
|
-
|
|
189
|
-
The slash-command file is loaded from `~/.claude/commands/epicmerch-Y.md`; follow its steps.
|
|
190
|
-
|
|
191
|
-
**In Codex CLI (or any client without slash commands):**
|
|
192
|
-
|
|
193
|
-
Fetch the matching skill from the API and follow it:
|
|
194
|
-
|
|
195
|
-
```
|
|
196
|
-
Fetch https://api.epicmerch.in/api/skills/epicmerch-<slug>.md and execute every step against the current project, using the MCP tools available in this session.
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
If the fetch fails, fall back to the high-level intent using the MCP tools you have (e.g. for Razorpay: `merchant_configure_razorpay({keyId, keySecret})` + `merchant_set_checkout_type({type:'epicmerch'})`).
|
|
200
|
-
|
|
201
|
-
### After the sub-flow
|
|
202
|
-
|
|
203
|
-
Briefly recap and ask if anything else is needed. One short sentence, not three follow-ups.
|
|
204
|
-
|
|
205
|
-
**If the sub-flow built or changed the storefront** (`/epicmerch-storefront`, `/epicmerch-magic-checkout`, or a custom build), run the **Definition of Done** gate above before recapping — `/epicmerch-verify` (Deep mode). Don't say "done" on anything that touched checkout without testing it live. (Pure config sub-flows like payment setup don't need the storefront verify, but a quick `merchant_diagnose` confirms they took.)
|
|
206
|
-
|
|
207
|
-
Examples:
|
|
208
|
-
|
|
209
|
-
> "Razorpay is now live on your store. Want a Buy Now button too?" *(routes to `/epicmerch-magic-checkout`)*
|
|
210
|
-
|
|
211
|
-
> "Storefront scaffolded and end-to-end tested (product → cart → order all pass). Restart your dev server (`npm run dev`) to load `.env`. Need anything else — payments, Shopify migration, analytics?"
|
|
212
|
-
|
|
213
|
-
---
|
|
214
|
-
|
|
215
|
-
## Step C — Tool fallback (no skill match)
|
|
216
|
-
|
|
217
|
-
If the intent doesn't match any row in the table AND it's not a "start me up" wizard cue, fall through to MCP tools directly:
|
|
218
|
-
|
|
219
|
-
- "How many products do I have?" → `merchant_list_products`
|
|
220
|
-
- "What's missing from my setup?" → `merchant_diagnose`
|
|
221
|
-
- "Generate a new API key called X" → `merchant_generate_api_key`
|
|
222
|
-
- "Send a notification to all customers" → `merchant_send_notification`
|
|
223
|
-
|
|
224
|
-
Only escalate to a sub-skill if a multi-step recipe is needed (scaffolding files, configuring payment processors, multi-stage migrations).
|
|
225
|
-
|
|
226
|
-
---
|
|
227
|
-
|
|
228
|
-
## Style
|
|
229
|
-
|
|
230
|
-
- **One question at a time.** Never stack three.
|
|
231
|
-
- **Read intent from context.** React + no `src/lib/epicmerch.js` → don't ask, just say "I'll scaffold the storefront" and start.
|
|
232
|
-
- **Confirm destructive operations.** Anything that deletes data or sends bulk notifications needs a yes-or-no first.
|
|
233
|
-
- **Skill files are guidance, not gospel.** If a step fails (server error, etc.), surface the actual error and ask the merchant rather than blindly retrying.
|
|
234
|
-
- **Lead with numbers.** "You have 42 products and ₹5,231 revenue this week" beats "let me tell you about your store."
|
|
235
|
-
|
|
236
|
-
## What this skill does NOT do
|
|
237
|
-
|
|
238
|
-
- Does not collect email/password in chat. Auth always goes through the browser OAuth flow via `/epicmerch-setup` (which runs `npx epicmerch-mcp login`).
|
|
239
|
-
- Does not bypass per-skill safety checks. E.g. `/epicmerch-magic-checkout` won't scaffold a Buy Now button before verifying Razorpay is configured — the umbrella respects that and the wizard's step 2 ensures payments are configured before step 5 even asks.
|
|
1
|
+
---
|
|
2
|
+
name: epicmerch
|
|
3
|
+
description: EpicMerch umbrella — guided 6-step onboarding wizard for new merchants, driven by a deterministic state machine (merchant_onboarding_state) that re-derives progress from live state and CANNOT report "complete" until a real end-to-end order test (/epicmerch-verify Deep mode) has stamped verification server-side. Also an intent router for merchants who already know what they want (scaffold a storefront, set up payments, add a Buy Now button, manage a store, migrate from Shopify, verify the store). Verification is the non-negotiable, structurally-enforced definition of done.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# EpicMerch — the umbrella
|
|
7
|
+
|
|
8
|
+
The **one entry point** for everything EpicMerch. Merchants don't need to memorise 10+ slash commands; they say what they want (or say nothing) and you figure out the right flow.
|
|
9
|
+
|
|
10
|
+
## Mode detection
|
|
11
|
+
|
|
12
|
+
Two modes. Pick one based on what the merchant said:
|
|
13
|
+
|
|
14
|
+
| What the merchant said when invoking `/epicmerch` | Mode |
|
|
15
|
+
|---|---|
|
|
16
|
+
| Nothing specific. Just `/epicmerch` with no extra words. | **Wizard mode** (Step A below) |
|
|
17
|
+
| "help me start", "I'm new", "set up everything", "what's next", "where do I begin" | **Wizard mode** |
|
|
18
|
+
| "set up Razorpay", "add a Buy Now button", "migrate Shopify", "scaffold a storefront", "show me my products" — anything with a clear specific intent | **Intent mode** (Step B below) |
|
|
19
|
+
|
|
20
|
+
If ambiguous, ask ONE disambiguating question: *"Want me to walk you through a full setup wizard, or is there one specific thing you want to do?"*
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## DEFINITION OF DONE — read this before you finish (applies to BOTH modes)
|
|
25
|
+
|
|
26
|
+
**`/epicmerch` is not complete until a live end-to-end test has run and passed.**
|
|
27
|
+
|
|
28
|
+
This holds no matter how the build happened — the wizard's scaffold step, an intent-mode `/epicmerch-storefront`, OR a fully custom build you designed through brainstorming (e.g. a themed multi-page store). However you got here, the LAST thing you do before telling the merchant "your store is set up" is run **`/epicmerch-verify` (Deep mode)** — the full product→cart→order pipeline; it automatically falls back to Smoke mode if the server's test-login isn't configured.
|
|
29
|
+
|
|
30
|
+
Common trap: a design-heavy request ("build me a saree store") pulls you into scope/theme/spec brainstorming and a custom build, and the flow ends at "looks good!" without ever testing against the live API. **Don't let that happen.** After the storefront files are written and the `.env` has a real API key, run the e2e/verify gate. A store that was never tested against the live API is not done — that's exactly how the cart-shape / productId / out-of-stock bugs reached real merchants.
|
|
31
|
+
|
|
32
|
+
If you realize you're wrapping up `/epicmerch` and haven't run the test → run it now.
|
|
33
|
+
|
|
34
|
+
In **Wizard mode** this is enforced for you: `merchant_onboarding_state` will not return `complete` until `/epicmerch-verify` (Deep mode) has stamped verification server-side, so you structurally can't wrap up early. In **Intent mode** and custom/brainstormed builds there's no such gate — that's where this reminder matters most.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Step A — Wizard mode (the harness loop)
|
|
39
|
+
|
|
40
|
+
Wizard mode is a **deterministic loop driven by the `merchant_onboarding_state` tool** — not prose you interpret. The tool re-derives what's done, what's next, and whether you're complete from **live server state on every call**, and it enforces the gate: you **cannot** reach `complete` until a real `/epicmerch-verify` (Deep mode) run has stamped verification server-side. That is what makes `/epicmerch` un-breakable — the control flow lives in code + a hard gate, so "done but never verified" is structurally unreachable. You bring the creative work (the conversation, the product shape, the styling); the tool owns order, idempotency, and the gate.
|
|
41
|
+
|
|
42
|
+
Open with one sentence:
|
|
43
|
+
|
|
44
|
+
> "I'll set up your EpicMerch store. I'll check what's already done, do the next thing, and finish with a live end-to-end test — that test is the only thing that marks the setup complete."
|
|
45
|
+
|
|
46
|
+
### The loop
|
|
47
|
+
|
|
48
|
+
Repeat until the tool returns `complete: true`:
|
|
49
|
+
|
|
50
|
+
1. Check the local project: does `src/lib/epicmerch.js` exist? (`true`/`false` → `storefrontPresent`).
|
|
51
|
+
2. Call `merchant_onboarding_state({ storefrontPresent })`.
|
|
52
|
+
3. If `complete === true` → print the **wrap-up recap** (below) and STOP. You're done.
|
|
53
|
+
4. Else → read `nextStep` and perform **that one step's action** (see *Step actions* below). The `steps[nextStep].action` string is a short reminder; the full expansion is below. Do exactly ONE step, recap it in one line (`✓ <what happened>`), then go back to 1.
|
|
54
|
+
|
|
55
|
+
**Rules that keep the harness honest:**
|
|
56
|
+
- Never skip ahead, never decide completion yourself, never print "your store is set up" before the tool returns `complete: true`.
|
|
57
|
+
- The loop is inherently idempotent — every turn re-reads live state, so re-running after a partial setup just resumes where you left off.
|
|
58
|
+
- If you catch yourself about to wrap up without `complete`, call the tool again — it will name the real gap.
|
|
59
|
+
|
|
60
|
+
### Step actions (the expansion of each `nextStep`)
|
|
61
|
+
|
|
62
|
+
#### `account` — authenticate
|
|
63
|
+
The tool couldn't read your settings (not connected / 401). Tell the merchant:
|
|
64
|
+
|
|
65
|
+
> "Your CLI isn't connected. Run `npx epicmerch-mcp setup` (or `npx epicmerch-mcp login` if MCP is already installed), then ask me again."
|
|
66
|
+
|
|
67
|
+
STOP the loop. Resume (re-call the tool) once they confirm they're connected.
|
|
68
|
+
|
|
69
|
+
#### `apiKey` — generate a storefront key
|
|
70
|
+
|
|
71
|
+
> "You don't have an API key yet. I'll generate one called 'Storefront' — that's what the SDK uses to talk to your store."
|
|
72
|
+
|
|
73
|
+
Call `merchant_generate_api_key({ name: 'Storefront' })`. Recap `✓ API key generated.` and re-loop.
|
|
74
|
+
|
|
75
|
+
#### `payment` — configure a processor
|
|
76
|
+
Ask **one** question:
|
|
77
|
+
|
|
78
|
+
> "Where do most of your customers buy from?
|
|
79
|
+
> 1) India (Razorpay — recommended)
|
|
80
|
+
> 2) Outside India (Stripe)"
|
|
81
|
+
|
|
82
|
+
- "India" / "1" → run `/epicmerch-payments` (it takes the Razorpay path)
|
|
83
|
+
- "outside" / "global" / "2" → run `/epicmerch-payments` (it takes the Stripe path)
|
|
84
|
+
|
|
85
|
+
`/epicmerch-payments` configures the chosen processor **and** the checkout type — the tool's `payment` step needs both before it counts as done. Re-loop; the tool confirms `payment.done`.
|
|
86
|
+
|
|
87
|
+
#### `products` — fill the catalog
|
|
88
|
+
The catalog is empty (the tool counts an empty catalog as not-done, so this step keeps surfacing until at least one product exists). Ask:
|
|
89
|
+
|
|
90
|
+
> "Your catalog is empty. Want me to:
|
|
91
|
+
> 1) Migrate your existing Shopify store
|
|
92
|
+
> 2) Add your first product right now
|
|
93
|
+
> 3) Add a quick sample product so we can finish, and you replace it later"
|
|
94
|
+
|
|
95
|
+
- "Shopify" / "1" → run `/epicmerch-migrate`
|
|
96
|
+
- "first product" / "2" → walk through it with `merchant_create_product`. **Do NOT just ask for name + price** — products that ship without variants and images break the storefront UX (empty size picker, broken image). Collect the FULL shape in ONE round of questions:
|
|
97
|
+
- **Name + Category** (`name`, `type`)
|
|
98
|
+
- **Description** (`description`)
|
|
99
|
+
- **Pricing** — list price (`price`), plus on-sale fields if applicable (`salePrice`, `discountPercent`). *"If this product is on sale, tell me the sale price and discount %. Otherwise say 'no sale'."*
|
|
100
|
+
- **Variants** (`variants`) — array of `{ variant: 'S', stock: 5 }` entries. *"What sizes / colors / options does this come in, and how many of each in stock? If just one option, say 'no variants'."* When passed, the server derives total stock from `sum(variant.stock)` and ignores the top-level `stock`.
|
|
101
|
+
- **Images** (`images`) — array of gallery URLs. Optionally `image` for an explicit primary; if omitted the server uses `images[0]`.
|
|
102
|
+
Pass everything to `merchant_create_product` in ONE call — never create-then-update.
|
|
103
|
+
- "sample" / "3" → create one reasonable sample product (full shape, a couple of variants, a placeholder image) so the loop can progress. Tell the merchant it's a placeholder they can edit or delete later.
|
|
104
|
+
|
|
105
|
+
There is no hard "skip" here: `complete` requires a non-empty catalog. If the merchant truly wants to stop, be honest that onboarding stays incomplete until a product exists.
|
|
106
|
+
|
|
107
|
+
#### `storefront` — scaffold into the project
|
|
108
|
+
`storefrontPresent` is false. First check the project: does `package.json` exist with React / Vite / Next in dependencies?
|
|
109
|
+
|
|
110
|
+
- **Not a frontend project / no `package.json`**: tell the merchant *"No frontend project detected here. Run `/epicmerch` from inside a React/Vite/Next project to scaffold the storefront."* `storefrontPresent` stays false, so the loop keeps flagging `storefront` — be honest that `complete` needs the storefront scaffolded (they can finish from a project later; a chat-only setup won't reach `complete`).
|
|
111
|
+
- **Project detected, no SDK file**: do the two-part sub-flow:
|
|
112
|
+
|
|
113
|
+
**4a — Visual style (before scaffolding).** Ask ONE question so the components match their vibe:
|
|
114
|
+
|
|
115
|
+
> "Quick — what's the vibe of your store?
|
|
116
|
+
> 1) Editorial Funk (bold typography, big imagery, asymmetric layouts)
|
|
117
|
+
> 2) Minimal Mono (clean, monochrome, lots of whitespace)
|
|
118
|
+
> 3) Vibrant Pop (colourful, rounded corners, playful)
|
|
119
|
+
> 4) Skip — functional unstyled scaffolds, I'll polish later"
|
|
120
|
+
|
|
121
|
+
Remember the answer as `visualStyle`.
|
|
122
|
+
|
|
123
|
+
**4b — Scaffold + style.** Run `/epicmerch-storefront`. After it finishes:
|
|
124
|
+
- 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.
|
|
125
|
+
- 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.
|
|
126
|
+
- Recap `✓ Storefront scaffolded + styled (<visualStyle>)` (or `unstyled`).
|
|
127
|
+
|
|
128
|
+
**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.
|
|
129
|
+
|
|
130
|
+
#### `verified` — the gate (the ONLY step that flips `complete`)
|
|
131
|
+
This is the un-fakeable half of the harness. Run **`/epicmerch-verify` (Deep mode)** automatically:
|
|
132
|
+
|
|
133
|
+
> "Last step — a live end-to-end test to confirm everything actually works."
|
|
134
|
+
|
|
135
|
+
It gets a customer session, creates a throwaway test product, adds it to a cart, creates a real order (exercising stock reservation + Razorpay order creation, no charge), verifies every response shape, then cleans up (cancels the order, deletes the product). This proves the WHOLE pipeline, not just read paths. It gets its customer token via the server's env-gated test phone (`store_auth_send_otp` + `store_auth_verify_otp` against `E2E_TEST_PHONE`), so it needs no SMS and no manual login.
|
|
136
|
+
|
|
137
|
+
- **On pass:** `/epicmerch-verify` (Deep mode) calls **`merchant_mark_verified`**, which stamps `lastVerifiedAt` server-side. That is the ONLY thing that flips the tool's `verified` step to done. Re-loop — `merchant_onboarding_state` will now return `complete: true`.
|
|
138
|
+
- **On any failure:** do NOT stamp verified. Route to `/epicmerch-debug` automatically — its four-check playbook (OTP not persisting, products not loading, INSUFFICIENT_STOCK on checkout, cart 401) fixes it without further merchant intervention. Then re-run `/epicmerch-verify` (Deep mode).
|
|
139
|
+
- **If the e2e token step fails** because the server lacks `E2E_TEST_PHONE`/`E2E_TEST_OTP` (you'll see a normal SMS channel instead of `e2e-test`, or a 401 on verify), fall back to `/epicmerch-verify` (read-path + payload checks, no token). **Important:** the fallback does NOT stamp `lastVerifiedAt`, so the `verified` step stays not-done and the tool will NOT report `complete`. Be honest: *"Ran the read-path + payload checks. To mark the store verified end-to-end (and finish onboarding), your EpicMerch operator needs to set `E2E_TEST_PHONE`/`E2E_TEST_OTP` on the server so the automated order test can run."*
|
|
140
|
+
|
|
141
|
+
### Wizard wrap-up
|
|
142
|
+
|
|
143
|
+
Print this one-block recap **only when `merchant_onboarding_state` has returned `complete: true`** (i.e. the `verified` step is done — never before):
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
━━━ Your store is set up ━━━
|
|
147
|
+
✓ Account connected as <email>
|
|
148
|
+
✓ API key: <name>
|
|
149
|
+
✓ Payments: <Razorpay/Stripe>
|
|
150
|
+
✓ Catalog: <N> products
|
|
151
|
+
✓ Storefront: scaffolded into <project> (or "skipped — no project")
|
|
152
|
+
✗ Buy Now button: skipped (or ✓ if they added it)
|
|
153
|
+
✓ End-to-end test: product → cart → order → cleanup all passed
|
|
154
|
+
(verified live — lastVerifiedAt stamped server-side)
|
|
155
|
+
|
|
156
|
+
Next: restart your dev server (`npm run dev`) to pick up `.env`. Your
|
|
157
|
+
store works end-to-end. Ask me about analytics, notifications, or
|
|
158
|
+
abandoned-cart messages whenever you're ready.
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Step B — Intent mode (router)
|
|
164
|
+
|
|
165
|
+
The merchant said something specific. Match against the table below, pick the closest, hand off. If multiple match, ask ONE disambiguating question.
|
|
166
|
+
|
|
167
|
+
| The merchant says … | Route to |
|
|
168
|
+
|---|---|
|
|
169
|
+
| "set up EpicMerch", "scaffold a storefront", "build me a store", "integrate ecommerce" (and the project has no `src/lib/epicmerch.js`) | `/epicmerch-storefront` |
|
|
170
|
+
| "add login / OTP / sign in" | `/epicmerch-storefront` (auth slice) |
|
|
171
|
+
| "add a product catalog", "show products on my site", "product list with search" | `/epicmerch-storefront` (products slice) |
|
|
172
|
+
| "add a cart", "build checkout", "order history page", "multi-product checkout" | `/epicmerch-storefront` (orders slice) |
|
|
173
|
+
| "add Buy Now button", "1-click checkout", "impulse buy", "Razorpay Magic Checkout" | `/epicmerch-magic-checkout` |
|
|
174
|
+
| "set up payments", "accept cards", "configure checkout", "set up Razorpay", "set up Stripe", "India / international payments" | `/epicmerch-payments` |
|
|
175
|
+
| "connect my store to Claude / Cursor / Codex", "log in to EpicMerch", "install the MCP" | `/epicmerch-setup` |
|
|
176
|
+
| "show me my store / products / orders / sales", "manage my store from chat" | `/epicmerch-merchant` |
|
|
177
|
+
| "migrate from Shopify", "import my Shopify catalog" | `/epicmerch-migrate` |
|
|
178
|
+
| "my login isn't sticking", "products aren't loading", "checkout fails", "insufficient stock undefined", "something's broken" | `/epicmerch-debug` |
|
|
179
|
+
| "test everything", "does checkout actually work", "full end-to-end test", "run a real order test" | `/epicmerch-verify` (Deep mode) |
|
|
180
|
+
|
|
181
|
+
### Hand-off (or inline)
|
|
182
|
+
|
|
183
|
+
**In Claude Code / Claude Desktop / Cursor / VS Code Claude extension:**
|
|
184
|
+
|
|
185
|
+
Tell the merchant which slash command you're invoking, then proceed:
|
|
186
|
+
|
|
187
|
+
> "Sounds like you want X — running `/epicmerch-Y` now."
|
|
188
|
+
|
|
189
|
+
The slash-command file is loaded from `~/.claude/commands/epicmerch-Y.md`; follow its steps.
|
|
190
|
+
|
|
191
|
+
**In Codex CLI (or any client without slash commands):**
|
|
192
|
+
|
|
193
|
+
Fetch the matching skill from the API and follow it:
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
Fetch https://api.epicmerch.in/api/skills/epicmerch-<slug>.md and execute every step against the current project, using the MCP tools available in this session.
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
If the fetch fails, fall back to the high-level intent using the MCP tools you have (e.g. for Razorpay: `merchant_configure_razorpay({keyId, keySecret})` + `merchant_set_checkout_type({type:'epicmerch'})`).
|
|
200
|
+
|
|
201
|
+
### After the sub-flow
|
|
202
|
+
|
|
203
|
+
Briefly recap and ask if anything else is needed. One short sentence, not three follow-ups.
|
|
204
|
+
|
|
205
|
+
**If the sub-flow built or changed the storefront** (`/epicmerch-storefront`, `/epicmerch-magic-checkout`, or a custom build), run the **Definition of Done** gate above before recapping — `/epicmerch-verify` (Deep mode). Don't say "done" on anything that touched checkout without testing it live. (Pure config sub-flows like payment setup don't need the storefront verify, but a quick `merchant_diagnose` confirms they took.)
|
|
206
|
+
|
|
207
|
+
Examples:
|
|
208
|
+
|
|
209
|
+
> "Razorpay is now live on your store. Want a Buy Now button too?" *(routes to `/epicmerch-magic-checkout`)*
|
|
210
|
+
|
|
211
|
+
> "Storefront scaffolded and end-to-end tested (product → cart → order all pass). Restart your dev server (`npm run dev`) to load `.env`. Need anything else — payments, Shopify migration, analytics?"
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## Step C — Tool fallback (no skill match)
|
|
216
|
+
|
|
217
|
+
If the intent doesn't match any row in the table AND it's not a "start me up" wizard cue, fall through to MCP tools directly:
|
|
218
|
+
|
|
219
|
+
- "How many products do I have?" → `merchant_list_products`
|
|
220
|
+
- "What's missing from my setup?" → `merchant_diagnose`
|
|
221
|
+
- "Generate a new API key called X" → `merchant_generate_api_key`
|
|
222
|
+
- "Send a notification to all customers" → `merchant_send_notification`
|
|
223
|
+
|
|
224
|
+
Only escalate to a sub-skill if a multi-step recipe is needed (scaffolding files, configuring payment processors, multi-stage migrations).
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## Style
|
|
229
|
+
|
|
230
|
+
- **One question at a time.** Never stack three.
|
|
231
|
+
- **Read intent from context.** React + no `src/lib/epicmerch.js` → don't ask, just say "I'll scaffold the storefront" and start.
|
|
232
|
+
- **Confirm destructive operations.** Anything that deletes data or sends bulk notifications needs a yes-or-no first.
|
|
233
|
+
- **Skill files are guidance, not gospel.** If a step fails (server error, etc.), surface the actual error and ask the merchant rather than blindly retrying.
|
|
234
|
+
- **Lead with numbers.** "You have 42 products and ₹5,231 revenue this week" beats "let me tell you about your store."
|
|
235
|
+
|
|
236
|
+
## What this skill does NOT do
|
|
237
|
+
|
|
238
|
+
- Does not collect email/password in chat. Auth always goes through the browser OAuth flow via `/epicmerch-setup` (which runs `npx epicmerch-mcp login`).
|
|
239
|
+
- Does not bypass per-skill safety checks. E.g. `/epicmerch-magic-checkout` won't scaffold a Buy Now button before verifying Razorpay is configured — the umbrella respects that and the wizard's step 2 ensures payments are configured before step 5 even asks.
|
package/src/adapters/mcp.js
CHANGED
|
@@ -11,6 +11,7 @@ import { developerTools, developerToolDefs } from '../tools/developer.js';
|
|
|
11
11
|
import { scaffoldTools, scaffoldToolDefs } from '../tools/scaffold.js';
|
|
12
12
|
import { merchantTools, merchantToolDefs } from '../tools/merchant.js';
|
|
13
13
|
import { prompts } from '../prompts/index.js';
|
|
14
|
+
import { VERSION } from '../version.js';
|
|
14
15
|
|
|
15
16
|
const __dir = dirname(fileURLToPath(import.meta.url));
|
|
16
17
|
const readResource = (rel) => readFileSync(join(__dir, '../resources', rel), 'utf-8');
|
|
@@ -27,7 +28,7 @@ function buildZodSchema(schemaDef) {
|
|
|
27
28
|
}
|
|
28
29
|
|
|
29
30
|
export async function startMcpAdapter(session, client) {
|
|
30
|
-
const server = new McpServer({ name: 'epicmerch', version:
|
|
31
|
+
const server = new McpServer({ name: 'epicmerch', version: VERSION });
|
|
31
32
|
|
|
32
33
|
const allToolDefs = [...sessionToolDefs, ...developerToolDefs, ...scaffoldToolDefs, ...merchantToolDefs];
|
|
33
34
|
const allHandlers = {
|
package/src/adapters/openapi.js
CHANGED
|
@@ -6,6 +6,7 @@ import { sessionTools, sessionToolDefs } from '../tools/session.js';
|
|
|
6
6
|
import { developerTools, developerToolDefs } from '../tools/developer.js';
|
|
7
7
|
import { scaffoldTools, scaffoldToolDefs } from '../tools/scaffold.js';
|
|
8
8
|
import { merchantTools, merchantToolDefs } from '../tools/merchant.js';
|
|
9
|
+
import { VERSION } from '../version.js';
|
|
9
10
|
|
|
10
11
|
const ALL_TOOL_DEFS = [...sessionToolDefs, ...developerToolDefs, ...scaffoldToolDefs, ...merchantToolDefs];
|
|
11
12
|
|
|
@@ -46,7 +47,7 @@ function buildOpenApiSpec(serverUrl) {
|
|
|
46
47
|
|
|
47
48
|
return {
|
|
48
49
|
openapi: '3.1.0',
|
|
49
|
-
info: { title: 'EpicMerch MCP Tools', version:
|
|
50
|
+
info: { title: 'EpicMerch MCP Tools', version: VERSION, description: 'EpicMerch tools for Claude and ChatGPT' },
|
|
50
51
|
servers: [{ url: serverUrl || 'https://mcp.epicmerch.in' }],
|
|
51
52
|
paths,
|
|
52
53
|
components: {
|
package/src/version.js
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// src/version.js
|
|
2
|
+
// Single source of the package version, read from package.json at runtime — so
|
|
3
|
+
// the MCP serverInfo handshake, the OpenAPI spec, etc. always match the published
|
|
4
|
+
// version instead of drifting from a hardcoded literal. Works in local dev, the
|
|
5
|
+
// npm tarball, and the staged .dxt (package.json sits at ../ from src/ in all three).
|
|
6
|
+
import { readFileSync } from 'fs';
|
|
7
|
+
import { fileURLToPath } from 'url';
|
|
8
|
+
import { dirname, join } from 'path';
|
|
9
|
+
|
|
10
|
+
const __dir = dirname(fileURLToPath(import.meta.url));
|
|
11
|
+
export const VERSION = JSON.parse(
|
|
12
|
+
readFileSync(join(__dir, '..', 'package.json'), 'utf-8')
|
|
13
|
+
).version;
|