epicmerch-mcp 1.0.0

package/skills/epicmerch-products.md

@@ -0,0 +1,95 @@
+---
+name: epicmerch-products
+description: Add an EpicMerch product catalog with search and category filtering to the current project.
+---
+
+# EpicMerch Products Integration
+
+**Idempotency rule:** Before writing any file, check if it already exists. If it does, SKIP that file and tell the user "X already exists — keeping it". Never overwrite existing files.
+
+## Step 1: Install SDK
+
+Check `package.json`. If `"epicmerch"` is in `dependencies`, skip. Otherwise: `npm install epicmerch`.
+
+## Step 2: SDK initializer
+
+If `src/lib/epicmerch.js` already exists, skip. Otherwise write:
+
+```js
+import EpicMerch from 'epicmerch';
+
+export const store = new EpicMerch({
+  apiKey: import.meta.env.VITE_API_KEY,
+  ...(import.meta.env.VITE_API_URL && { baseUrl: import.meta.env.VITE_API_URL }),
+});
+```
+
+## Step 3: ProductCard
+
+If `src/components/ProductCard.jsx` already exists, skip. Otherwise write:
+
+```jsx
+export default function ProductCard({ product, onAddToCart }) {
+  return (
+    <div className="product-card">
+      <img src={product.images?.[0]} alt={product.name} />
+      <h3>{product.name}</h3>
+      <p>₹{product.price}</p>
+      <button onClick={() => onAddToCart(product._id)}>Add to Cart</button>
+    </div>
+  );
+}
+```
+
+## Step 4: ProductList
+
+If `src/components/ProductList.jsx` already exists, skip. Otherwise write:
+
+```jsx
+import { useEffect, useState } from 'react';
+import { store } from '../lib/epicmerch';
+import ProductCard from './ProductCard';
+
+export default function ProductList() {
+  const [products, setProducts] = useState([]);
+  const [categories, setCategories] = useState([]);
+  const [category, setCategory] = useState(undefined);
+  const [query, setQuery] = useState('');
+
+  useEffect(() => { store.categories.list().then(setCategories); }, []);
+
+  useEffect(() => {
+    if (query.trim()) {
+      store.products.search(query).then(d => setProducts(d.products ?? d));
+    } else {
+      store.products.list({ type: category, limit: 12 }).then(d => setProducts(d.products ?? d));
+    }
+  }, [query, category]);
+
+  const addToCart = (productId) => store.cart.add(productId, 1);
+
+  return (
+    <div>
+      <input
+        placeholder="Search products..."
+        value={query}
+        onChange={e => setQuery(e.target.value)}
+      />
+      <div>
+        {categories.map(c => (
+          <button key={c} onClick={() => { setQuery(''); setCategory(c === 'All' ? undefined : c); }}>{c}</button>
+        ))}
+      </div>
+      <div className="product-grid">
+        {products.map(p => <ProductCard key={p._id} product={p} onAddToCart={addToCart} />)}
+      </div>
+    </div>
+  );
+}
+```
+
+## Step 5: Tell the user what's next
+
+List CREATED files. Then:
+
+> "Product catalog integrated. Set `VITE_API_KEY` in `.env` (ask me to generate one via the MCP if you don't have it). Import `<ProductList />` into your app."

package/skills/epicmerch-stripe.md

@@ -0,0 +1,64 @@
+---
+name: epicmerch-stripe
+description: Set up Stripe payments for an EpicMerch store conversationally — get keys, configure webhook, test, and activate.
+---
+
+# EpicMerch Stripe Setup
+
+You're helping a merchant configure Stripe as their payment processor. Walk them through these steps.
+
+## Step 1: Confirm they have a Stripe account
+
+Ask: "Do you already have a Stripe account at dashboard.stripe.com? If not, sign up first — it's free and takes 5 minutes."
+
+## Step 2: Collect their API keys
+
+Ask them to go to https://dashboard.stripe.com/apikeys and copy:
+- Their **publishable key** (starts with `pk_`)
+- Their **secret key** (starts with `sk_`) — remind them this is secret
+
+## Step 3: Set up the webhook
+
+Tell them:
+> "In your Stripe Dashboard, go to Developers → Webhooks → Add endpoint.
+>
+> For the endpoint URL, use:
+> `https://api.epicmerch.in/api/webhook/stripe?merchantId=<their-merchant-id>`
+>
+> Subscribe to these events:
+> - `payment_intent.succeeded`
+> - `payment_intent.payment_failed`
+>
+> After creating the webhook, reveal the **Signing secret** (starts with `whsec_`)."
+
+You can find their merchant ID by calling `merchant_get_settings()` and reading the `_id` or `id` field.
+
+## Step 4: Save their credentials
+
+Call `merchant_configure_stripe` with the three values:
+```
+merchant_configure_stripe({
+  publishableKey: "pk_live_...",
+  secretKey:      "sk_live_...",
+  webhookSecret:  "whsec_..."
+})
+```
+
+## Step 5: Test the connection
+
+Call `merchant_test_stripe_connection()`. You should see `{ ok: true, accountId, country, chargesEnabled }`.
+
+If `chargesEnabled` is `false`, tell the merchant their Stripe account isn't fully activated yet — they need to complete onboarding in the Stripe Dashboard.
+
+## Step 6: Activate Stripe as their checkout
+
+Call `merchant_set_checkout_type({ type: "stripe" })`.
+
+Their storefront will now use Stripe Payment Element (cards, Link, Apple Pay, Google Pay) on the next checkout.
+
+## Style
+
+- Ask one question at a time. Don't dump all six steps at once.
+- After each step, confirm before moving on ("Got it — paste your publishable key when you have it").
+- Read back the result of each MCP call so the merchant sees progress.
+- If `merchant_test_stripe_connection` fails, diagnose: the most common cause is a wrong secret key (regenerate in Stripe Dashboard) or test/live key mismatch.

package/skills/epicmerch.md

@@ -0,0 +1,389 @@
+---
+name: epicmerch
+description: One-shot EpicMerch integration — installs the SDK and scaffolds auth, product catalog, and order management into the current project.
+---
+
+# EpicMerch Full Integration
+
+You are integrating EpicMerch into this project. EpicMerch is a complete e-commerce backend that handles auth, inventory, orders, and payments. Follow every step below in order without asking for confirmation unless a step explicitly says to ask.
+
+**Idempotency rule (apply throughout):** Before writing any file in the scaffold steps below, check if it already exists. If it does, SKIP that file and tell the user "X already exists — keeping it". Never overwrite existing files. The merchant may already have a polished version of any of these components; preserving their work is more important than completing the scaffold.
+
+## Checklist
+
+- [ ] **Step 0: Survey the project**
+
+List which of the scaffold target files already exist in this project:
+- `src/lib/epicmerch.js`
+- `src/components/Login.jsx`
+- `src/components/ProductCard.jsx`
+- `src/components/ProductList.jsx`
+- `src/components/Cart.jsx`
+- `src/components/Checkout.jsx`
+- `src/components/OrderHistory.jsx`
+- `.env.example`
+- `.env`
+
+Briefly tell the user which already exist (those will be skipped) and which will be created. Then proceed.
+
+- [ ] **Step 1: Detect framework**
+
+Read `package.json`. Determine the framework:
+- If `"react"` or `"vite"` in dependencies → framework = `react`, envPrefix = `VITE_`
+- If `"next"` in dependencies → framework = `react`, envPrefix = `NEXT_PUBLIC_`
+- If `"vue"` in dependencies → framework = `react`, envPrefix = `VITE_`; tell the user: "Vue is not yet natively supported — installing React templates instead."
+- Otherwise → framework = `react`, envPrefix = `VITE_`
+
+Tell the user: "Detected [framework]. Installing EpicMerch SDK..."
+
+- [ ] **Step 2: Install the SDK**
+
+Check `package.json` first. If `"epicmerch"` is already in `dependencies`, skip the install and tell the user "epicmerch SDK already installed". Otherwise:
+
+Run: `npm install epicmerch`
+
+- [ ] **Step 3: Create SDK initializer**
+
+**If `src/lib/epicmerch.js` already exists, skip this step entirely** and tell the user "src/lib/epicmerch.js already exists — keeping it". Otherwise, write `src/lib/epicmerch.js` using the `envPrefix` detected in Step 1 to substitute the env var names:
+
+- For `VITE_` prefix (Vite / React):
+```js
+import EpicMerch from 'epicmerch';
+
+export const store = new EpicMerch({
+  apiKey: import.meta.env.VITE_API_KEY,
+  ...(import.meta.env.VITE_API_URL && { baseUrl: import.meta.env.VITE_API_URL }),
+});
+```
+
+- For `NEXT_PUBLIC_` prefix (Next.js):
+```js
+import EpicMerch from 'epicmerch';
+
+export const store = new EpicMerch({
+  apiKey: process.env.NEXT_PUBLIC_API_KEY,
+  ...(process.env.NEXT_PUBLIC_API_URL && { baseUrl: process.env.NEXT_PUBLIC_API_URL }),
+});
+```
+
+- [ ] **Step 4: Scaffold auth**
+
+**If `src/components/Login.jsx` already exists, skip this step** and tell the user "Login.jsx already exists — keeping it". Otherwise write `src/components/Login.jsx`:
+
+```jsx
+import { useState } from 'react';
+import { store } from '../lib/epicmerch';
+
+export default function Login({ onLogin }) {
+  const [phone, setPhone] = useState('');
+  const [otp, setOtp] = useState('');
+  const [step, setStep] = useState('phone');
+
+  const sendOtp = async () => {
+    await store.auth.sendOtp(phone, 'phone');
+    setStep('otp');
+  };
+
+  const verify = async () => {
+    const result = await store.auth.verifyOtp(phone, otp, {});
+    if (result.token) {
+      store.setCustomerToken(result.token);
+      localStorage.setItem('customerInfo', JSON.stringify(result));
+      onLogin(result);
+    }
+  };
+
+  return (
+    <div>
+      {step === 'phone' ? (
+        <>
+          <input value={phone} onChange={e => setPhone(e.target.value)} placeholder="+919876543210" />
+          <button onClick={sendOtp}>Send OTP</button>
+        </>
+      ) : (
+        <>
+          <input value={otp} onChange={e => setOtp(e.target.value)} placeholder="Enter OTP" />
+          <button onClick={verify}>Verify</button>
+        </>
+      )}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 5: Scaffold product catalog**
+
+For each of the two files in this step, check existence individually. If a file already exists, skip writing it and tell the user "X already exists — keeping it". Otherwise write it.
+
+Write `src/components/ProductCard.jsx`:
+
+```jsx
+export default function ProductCard({ product, onAddToCart }) {
+  return (
+    <div className="product-card">
+      <img src={product.images?.[0]} alt={product.name} />
+      <h3>{product.name}</h3>
+      <p>₹{product.price}</p>
+      <button onClick={() => onAddToCart(product._id)}>Add to Cart</button>
+    </div>
+  );
+}
+```
+
+Write `src/components/ProductList.jsx`:
+
+```jsx
+import { useEffect, useState } from 'react';
+import { store } from '../lib/epicmerch';
+import ProductCard from './ProductCard';
+
+export default function ProductList() {
+  const [products, setProducts] = useState([]);
+  const [categories, setCategories] = useState([]);
+  const [category, setCategory] = useState(undefined);
+  const [query, setQuery] = useState('');
+
+  useEffect(() => { store.categories.list().then(setCategories); }, []);
+
+  useEffect(() => {
+    if (query.trim()) {
+      store.products.search(query).then(d => setProducts(d.products ?? d));
+    } else {
+      store.products.list({ type: category, limit: 12 }).then(d => setProducts(d.products ?? d));
+    }
+  }, [query, category]);
+
+  const addToCart = (productId) => store.cart.add(productId, 1);
+
+  return (
+    <div>
+      <input
+        placeholder="Search products..."
+        value={query}
+        onChange={e => setQuery(e.target.value)}
+      />
+      <div>
+        {categories.map(c => (
+          <button key={c} onClick={() => { setQuery(''); setCategory(c === 'All' ? undefined : c); }}>{c}</button>
+        ))}
+      </div>
+      <div className="product-grid">
+        {products.map(p => <ProductCard key={p._id} product={p} onAddToCart={addToCart} />)}
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 5b: Wire up an existing search bar (only if `ProductList.jsx` was skipped)**
+
+If you wrote a fresh `ProductList.jsx` in Step 5, skip this step — the canonical scaffold already has search wired.
+
+If `ProductList.jsx` was SKIPPED because it already existed, the merchant has their own UI. They may have a search bar somewhere — in a `Navbar`, a `Header`, a dedicated `SearchBar.jsx`, a search page, etc. — that isn't currently calling EpicMerch's search API. Detect and offer to wire it up.
+
+**Detection.** Look through `src/` for files containing any of these signals (case-insensitive):
+- `<input` whose `placeholder` mentions `search`
+- A state variable named `query`, `search`, `searchTerm`, `searchQuery`, or `keyword`
+- A handler named `onSearch`, `handleSearch`, `onQueryChange`, or similar
+
+For each match, check whether the file already calls `store.products.search(`. If yes, it's wired — skip silently.
+
+**For each unwired match:** show the merchant the file path and the snippet you found, then say:
+
+> "I noticed a search input in `<path>` that doesn't call EpicMerch's search yet. The one-line wire-up is:
+>
+> ```js
+> import { store } from '../lib/epicmerch';  // add at top if missing
+>
+> // inside the search handler / useEffect:
+> store.products.search(query).then(d => setProducts(d.products ?? d));
+> ```
+>
+> Want me to apply this to your component? (yes / no — I'll leave it alone if no.)"
+
+**WAIT for an explicit yes before editing.** If the merchant declines, move on without changing the file.
+
+If you find no search bar anywhere in `src/`, skip this step silently — don't tell the merchant "no search bar found", just continue to Step 6.
+
+- [ ] **Step 6: Scaffold cart + orders**
+
+For each of the three files in this step (Cart.jsx, Checkout.jsx, OrderHistory.jsx), check existence individually. If a file already exists, skip writing it and tell the user "X already exists — keeping it". Otherwise write it.
+
+Write `src/components/Cart.jsx`:
+
+```jsx
+import { useEffect, useState } from 'react';
+import { store } from '../lib/epicmerch';
+
+export default function Cart({ onCheckout }) {
+  const [cart, setCart] = useState({ items: [] });
+
+  useEffect(() => { store.cart.get().then(setCart); }, []);
+
+  const remove = async (productId) => {
+    await store.cart.remove(productId);
+    store.cart.get().then(setCart);
+  };
+
+  const total = cart.items?.reduce((s, i) => s + i.price * i.qty, 0) ?? 0;
+
+  return (
+    <div>
+      {cart.items?.map(item => (
+        <div key={item.productId}>
+          <span>{item.name} x{item.qty}</span>
+          <span>₹{item.price * item.qty}</span>
+          <button onClick={() => remove(item.productId)}>Remove</button>
+        </div>
+      ))}
+      <p>Total: ₹{total}</p>
+      <button onClick={onCheckout}>Checkout</button>
+    </div>
+  );
+}
+```
+
+Write `src/components/Checkout.jsx`:
+
+```jsx
+import { useState } from 'react';
+import { store } from '../lib/epicmerch';
+
+const loadRazorpay = () =>
+  new Promise((resolve) => {
+    if (window.Razorpay) return resolve(true);
+    const script = document.createElement('script');
+    script.src = 'https://checkout.razorpay.com/v1/checkout.js';
+    script.onload = () => resolve(true);
+    script.onerror = () => resolve(false);
+    document.body.appendChild(script);
+  });
+
+export default function Checkout({ cart, onSuccess }) {
+  const [address, setAddress] = useState({ street: '', city: '', postalCode: '', country: 'India' });
+
+  const placeOrder = async () => {
+    await loadRazorpay();
+    const total = cart.items.reduce((s, i) => s + i.price * i.qty, 0);
+    const { orderId } = await store.orders.create({
+      orderItems: cart.items.map(i => ({ productId: i.productId, qty: i.qty, price: i.price })),
+      shippingAddress: address,
+      paymentMethod: 'Razorpay',
+      totalPrice: total,
+    });
+    const config = await store.payment.getConfig();
+    const { razorpayOrderId } = await store.payment.createOrder(total * 100, orderId);
+    const rzp = new window.Razorpay({
+      key: config.razorpayKeyId,
+      order_id: razorpayOrderId,
+      amount: total * 100,
+      handler: async (response) => {
+        await store.payment.verify({ ...response, orderId });
+        await store.cart.clear();
+        onSuccess(orderId);
+      },
+    });
+    rzp.open();
+  };
+
+  return (
+    <div>
+      <input placeholder="Street" onChange={e => setAddress(a => ({ ...a, street: e.target.value }))} />
+      <input placeholder="City" onChange={e => setAddress(a => ({ ...a, city: e.target.value }))} />
+      <input placeholder="Postal Code" onChange={e => setAddress(a => ({ ...a, postalCode: e.target.value }))} />
+      <button onClick={placeOrder}>Place Order</button>
+    </div>
+  );
+}
+```
+
+Do NOT add any Razorpay script tag to `index.html` — the script loads dynamically only when the user clicks Place Order.
+
+Write `src/components/OrderHistory.jsx`:
+
+```jsx
+import { useEffect, useState } from 'react';
+import { store } from '../lib/epicmerch';
+
+export default function OrderHistory() {
+  const [orders, setOrders] = useState([]);
+
+  useEffect(() => { store.orders.list().then(setOrders); }, []);
+
+  return (
+    <div>
+      <h2>Your Orders</h2>
+      {orders.map(order => (
+        <div key={order._id}>
+          <span>Order #{order._id.slice(-6)}</span>
+          <span> — ₹{order.totalPrice}</span>
+          <span> — {order.status}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 7: Generate API key via MCP + write `.env`**
+
+This step has two parts: write `.env.example` (the template), then generate a real API key and write a working `.env`.
+
+**Part A — `.env.example`:** If `.env.example` already exists, skip writing it and tell the user ".env.example already exists — keeping it". Otherwise write `.env.example`:
+
+```
+VITE_API_KEY=your_epicmerch_api_key_here
+# VITE_API_URL is OPTIONAL — only set it for local development.
+# Production: leave it unset; the SDK defaults to https://api.epicmerch.in/api
+# Local dev: VITE_API_URL=http://localhost:5002/api
+```
+
+Check `.gitignore` — if `.env` is not listed, append `.env` to `.gitignore` before any `.env` file is written.
+
+**Part B — generate a real API key + write `.env`:**
+
+First, read `.env` if it exists. If it already contains a `VITE_API_KEY=` line whose value is NOT the placeholder string `your_epicmerch_api_key_here` (i.e. there's already a real key), skip Part B entirely and tell the user "Existing API key in .env — keeping it".
+
+Otherwise, the merchant is authenticated via the EpicMerch MCP (this skill assumes the MCP is connected — that's how it was invoked). Generate a key by calling the MCP tool:
+
+```
+merchant_generate_api_key({ name: "Storefront" })
+```
+
+The response will include the new key. Extract it (the field is typically `key` or `apiKey` — check the response shape). Then write/update `.env`.
+
+**Production (default).** Write only the key — the SDK already knows the prod URL:
+
+```
+VITE_API_KEY=<the generated key from the MCP response>
+```
+
+**Local development.** Only if the merchant is clearly running against a local EpicMerch server (e.g. they explicitly said so, or their existing `.env` already had a `localhost` URL, or the MCP was wired with `EPICMERCH_API_URL=http://localhost:...`), ALSO write the override:
+
+```
+VITE_API_KEY=<the generated key from the MCP response>
+VITE_API_URL=http://localhost:5002/api
+```
+
+When in doubt, default to the production form (no `VITE_API_URL` line). Don't ask the merchant — guess from context.
+
+**Fallback if MCP isn't available:** If the `merchant_generate_api_key` tool fails or isn't connected, tell the user: "MCP tool unavailable. Generate a key manually at https://epicmerch.in/dashboard → API Keys and add it to .env." Do NOT fail the whole flow — continue to Step 8.
+
+- [ ] **Step 8: Tell the user what to do next**
+
+Print a summary using the actual state of the project:
+
+- List the files you CREATED in this run (skip the ones that were already present).
+- If you skipped any, briefly mention them as "kept as-is".
+- If Step 5b wired up a search bar in an existing component, mention which file you edited and that it now calls `store.products.search()`.
+- If the API key was generated automatically, mention that ".env now has a working VITE_API_KEY — your storefront should load real product data on next refresh."
+- Then output the next-steps block exactly:
+
+```
+Next steps:
+1. (API key auto-generated and saved to .env — if not, get one at https://epicmerch.in/dashboard → API Keys)
+2. Restart your dev server (npm run dev) to pick up the .env changes
+3. Import the new components into your App.jsx where you need them
+
+Need help with payments, analytics, or notifications? Ask me!
+```

package/smithery.yaml

@@ -0,0 +1,6 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties: {}
+  exampleConfig: {}

package/src/adapters/mcp.js

@@ -0,0 +1,76 @@
+// src/adapters/mcp.js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+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 { prompts } from '../prompts/index.js';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const readResource = (rel) => readFileSync(join(__dir, '../resources', rel), 'utf-8');
+
+function buildZodSchema(schemaDef) {
+  const shape = {};
+  for (const [key, def] of Object.entries(schemaDef)) {
+    if (def.type === 'string') shape[key] = z.string().optional();
+    else if (def.type === 'number') shape[key] = z.number().optional();
+    else if (def.type === 'boolean') shape[key] = z.boolean().optional();
+    else shape[key] = z.any().optional();
+  }
+  return shape;
+}
+
+export async function startMcpAdapter(session, client) {
+  const server = new McpServer({ name: 'epicmerch', version: '1.0.0' });
+
+  const allToolDefs = [...sessionToolDefs, ...developerToolDefs, ...scaffoldToolDefs, ...merchantToolDefs];
+  const allHandlers = {
+    ...sessionTools(session),
+    ...developerTools(client),
+    ...scaffoldTools(),
+    ...merchantTools(client, session),
+  };
+
+  // Register all tools
+  for (const def of allToolDefs) {
+    const zodShape = buildZodSchema(def.schema || {});
+    server.tool(def.name, def.description, zodShape, async (args) => {
+      return allHandlers[def.name](args);
+    });
+  }
+
+  // Register resources
+  const resources = [
+    { name: 'EpicMerch Overview', uri: 'epicmerch://overview', file: 'overview.md' },
+    { name: 'EpicMerch SDK Guide', uri: 'epicmerch://sdk-guide', file: 'sdk-guide.md' },
+    { name: 'Auth Examples', uri: 'epicmerch://examples/auth', file: 'examples/auth.md' },
+    { name: 'Products Examples', uri: 'epicmerch://examples/products', file: 'examples/products.md' },
+    { name: 'Orders Examples', uri: 'epicmerch://examples/orders', file: 'examples/orders.md' },
+    { name: 'Payments Examples', uri: 'epicmerch://examples/payments', file: 'examples/payments.md' },
+  ];
+
+  for (const r of resources) {
+    server.resource(r.name, r.uri, async () => ({
+      contents: [{ uri: r.uri, text: readResource(r.file), mimeType: 'text/markdown' }],
+    }));
+  }
+
+  // Register prompts
+  for (const p of prompts) {
+    const argShape = {};
+    for (const arg of (p.arguments || [])) {
+      argShape[arg.name] = z.string().optional().describe(arg.description);
+    }
+    server.prompt(p.name, p.description, argShape, p.handler);
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[EpicMerch MCP] Server started (stdio)');
+}