@shoppexio/mcp-commerce-server 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/mcp-commerce-server",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shoppex MCP server for commerce operations over the Dev API",
   "type": "module",
   "repository": {
@@ -34,6 +34,8 @@
   "files": [
     "bin",
     "src/server.mjs",
+    "src/prompts.mjs",
+    "src/resources.mjs",
     "src/index.d.ts",
     "README.md"
   ],

package/src/prompts.mjs

@@ -0,0 +1,168 @@
+/**
+ * MCP Prompts for Shoppex — curated multi-tool workflows that merchants
+ * invoke by name in their MCP client. Each prompt returns a user-message
+ * with a full instruction block that primes the LLM to run a pre-planned
+ * sequence of tool calls.
+ *
+ * Registration via `server.registerPrompt(name, {title, description, argsSchema}, cb)`.
+ */
+
+import * as z from 'zod/v4';
+
+function text(body) {
+  return { messages: [{ role: 'user', content: { type: 'text', text: body } }] };
+}
+
+export function registerShoppexPrompts(server) {
+  server.registerPrompt(
+    'shoppex_daily_brief',
+    {
+      title: 'Daily brief',
+      description:
+        'Summarise today\'s shop health: revenue, orders, failed payments, open tickets, new disputes. Produces an actionable morning brief.',
+    },
+    () => text(`Give me a concise morning brief for my Shoppex shop. Follow this order:
+
+1. Call analytics_revenue for the current month.
+2. Call orders_list with limit=10 to see the most recent orders.
+3. Call invoices_list with status="pending", limit=5.
+4. Call disputes_list with limit=5 (only flag if status=open).
+5. Call tickets_list with status="open", limit=5.
+
+Return a short markdown briefing with these sections:
+- **Revenue today / MTD** (use currency from the analytics response)
+- **Latest orders** (3 most recent, one line each)
+- **Attention items** — pending invoices over 24h, open disputes, open tickets
+- **Suggested next action** — one sentence, concrete
+
+Keep it under 150 words. Do not invent numbers — if a tool returned 0 items, say so.`),
+  );
+
+  server.registerPrompt(
+    'shoppex_launch_product',
+    {
+      title: 'Launch a product',
+      description:
+        'End-to-end product launch: create the product, generate a launch coupon, and return a ready-to-send Discord/Telegram announcement.',
+      argsSchema: {
+        product_name: z.string().min(1),
+        price: z.string().min(1),
+        coupon_percent: z.string().min(1).optional(),
+      },
+    },
+    ({ product_name, price, coupon_percent }) => text(`Launch a new product called "${product_name}" priced at $${price}. Work in this order:
+
+1. Call products_create with { title: "${product_name}", price: ${price}, type: "SERVICE" }. Capture the returned uniqid.
+2. ${coupon_percent ? `Call coupons_create with { code: "LAUNCH${Math.round(Math.random() * 999)}", discount_value: ${coupon_percent}, discount_type: "PERCENTAGE" }.` : 'Skip coupon unless the user explicitly asks for one.'}
+3. Call payment_links_create for the new product so we have a single shareable checkout URL. Use name="${product_name} launch", type="PRODUCT", gateways=["STRIPE","CRYPTO"].
+
+After the tools run, produce:
+- A short confirmation in markdown ("Created …").
+- A ready-to-post Discord launch blurb (2-3 sentences, casual tone, include the payment link and the coupon code if created).
+
+Do NOT invent the uniqid or URL — use what the tools returned.`),
+  );
+
+  server.registerPrompt(
+    'shoppex_fraud_check',
+    {
+      title: 'Fraud check',
+      description:
+        'Investigate suspicious orders: look at recent high-value orders, match them against the blacklist, and propose block/refund actions.',
+    },
+    () => text(`Run a fraud-risk scan on the shop. Work in this order:
+
+1. Call orders_list with limit=30.
+2. Call disputes_list with limit=20.
+3. Call blacklist_list with limit=50.
+
+Analyse the data and answer:
+- Any order whose customer email or IP is already on the blacklist? (exact match)
+- Any order with an unusually high value vs. the shop's typical order size?
+- Any order with a recent dispute against the same customer email?
+- Any order from a country/IP cluster that has disputes (>=2 in the last 30 days)?
+
+Return a markdown report:
+- **Risk score**: low / medium / high (overall)
+- **Flagged orders** (table: order id, customer, reason, suggested action)
+- **Recommended blacklist adds** (email/ip/country with reason)
+
+Do not execute block/refund automatically. End with: "Want me to add these to the blacklist? Confirm one-by-one."`),
+  );
+
+  server.registerPrompt(
+    'shoppex_weekly_recap',
+    {
+      title: 'Weekly recap',
+      description:
+        'Seven-day performance recap: revenue, top products, customer additions, operational health. Designed for founder/team standups.',
+    },
+    () => text(`Give me a 7-day recap for the shop. Work in this order:
+
+1. Call analytics_revenue for the last 7 days.
+2. Call orders_list with limit=50 (to estimate order volume).
+3. Call products_list with limit=20 to know the catalog.
+4. Call customers_list with limit=20 (most recent signups).
+5. Call invoices_list with status="paid", limit=20.
+
+Return a markdown recap with:
+- **Revenue (7d)** + YoY trend if data allows
+- **Top 3 products by order count**
+- **New customers this week** (count + 2-3 notable emails if VIP-like)
+- **Operational signals** (pending invoices, failed payments if visible)
+- **Focus for next week** — one concrete initiative
+
+Tone: factual, founder-facing, under 250 words.`),
+  );
+
+  server.registerPrompt(
+    'shoppex_customer_care',
+    {
+      title: 'Customer care',
+      description:
+        'Look up a customer end-to-end: orders, invoices, subscriptions, licenses, tickets. Returns a full timeline plus a draft reply.',
+      argsSchema: {
+        email: z.string().email(),
+      },
+    },
+    ({ email }) => text(`Look up the full history for customer "${email}". Work in this order:
+
+1. Call customers_get with email="${email}".
+2. Call orders_list with customer_email="${email}", limit=20.
+3. Call invoices_list with customer_email="${email}", limit=10.
+4. Call licenses_list (then filter locally by the customer's id).
+5. Call subscriptions_list (then filter locally by the customer's id).
+
+Return a markdown report:
+- **Summary** (customer name/email, total spend, first-seen / last-seen)
+- **Timeline** (orders + tickets chronologically)
+- **Open issues** (active disputes, unresolved tickets, failed payments)
+- **Draft reply** — a ready-to-send support message that addresses likely concerns, signed as the shop
+
+Keep the draft reply polite, short, and actionable. Do not invent details the tools didn't return.`),
+  );
+
+  server.registerPrompt(
+    'shoppex_theme_refresh',
+    {
+      title: 'Theme refresh',
+      description:
+        'Guided mini-review of the shop\'s active theme: structure, sections, recent changes, publish readiness.',
+    },
+    () => text(`Do a theme-refresh review. Work in this order:
+
+1. Call theme_list to find the active theme for this shop (is_active=true).
+2. Call theme_inspect on the active theme to get sections, settings, tokens.
+3. Call theme_diff on the active theme to see draft vs. published state.
+4. Call theme_latest_run on the active theme to see the last build health.
+
+Return a markdown report:
+- **Active theme** (name, scheme, version)
+- **Section inventory** (list of sections + page count)
+- **Draft status** (any pending changes? any build errors?)
+- **Publish readiness** — safe to publish? what risks?
+- **Suggested improvements** — 2-3 concrete section-level tweaks (e.g. "Add a testimonials section above footer"). Keep them specific.
+
+Format: founder-facing, under 200 words.`),
+  );
+}

package/src/resources.mjs

@@ -0,0 +1,112 @@
+/**
+ * MCP Resources for Shoppex — cacheable read-only context documents the
+ * client can attach to a conversation (e.g. Claude Desktop "Attach" menu).
+ * Each resource fetches fresh data on read and returns JSON text.
+ *
+ * Registration via `server.registerResource(name, uri, { title, description, mimeType }, async () => ({ contents: [...] }))`.
+ */
+
+import { ShoppexCommerceDevApiClient } from './server.mjs';
+
+function resolveShopApiKey() {
+  const fromEnv = process.env.SHOPPEX_SHOP_API_KEY?.trim()
+    || process.env.SHOPPEX_API_KEY?.trim()
+    || process.env.SHOP_API_KEY?.trim();
+  if (!fromEnv) {
+    throw new Error('Shoppex resources require SHOPPEX_SHOP_API_KEY to be set.');
+  }
+  return fromEnv;
+}
+
+function buildClient() {
+  return new ShoppexCommerceDevApiClient({
+    shopApiKey: resolveShopApiKey(),
+    apiBaseUrl: process.env.SHOPPEX_API_BASE_URL?.trim()
+      || process.env.API_URL?.trim()
+      || 'https://api.shoppex.io',
+  });
+}
+
+function jsonResource(uri, value) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: 'application/json',
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}
+
+export function registerShoppexResources(server) {
+  server.registerResource(
+    'shoppex_products_catalog',
+    'shoppex://products',
+    {
+      title: 'Product catalog',
+      description: 'Current product catalog for the authenticated shop (up to 50 products, includes variants).',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().productsList({ limit: 50 });
+      return jsonResource(uri.href, data ?? []);
+    },
+  );
+
+  server.registerResource(
+    'shoppex_recent_orders',
+    'shoppex://orders/recent',
+    {
+      title: 'Recent orders',
+      description: '50 most recent orders across all statuses.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().ordersList({ limit: 50 });
+      return jsonResource(uri.href, data ?? []);
+    },
+  );
+
+  server.registerResource(
+    'shoppex_analytics_summary',
+    'shoppex://analytics/summary',
+    {
+      title: 'Analytics summary',
+      description: 'Month-to-date revenue totals and recent trends.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().analyticsRevenue({ currency: 'USD' });
+      return jsonResource(uri.href, data ?? {});
+    },
+  );
+
+  server.registerResource(
+    'shoppex_categories',
+    'shoppex://categories',
+    {
+      title: 'Category tree',
+      description: 'Full product category list for the shop.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().categoriesList();
+      return jsonResource(uri.href, data ?? []);
+    },
+  );
+
+  server.registerResource(
+    'shoppex_open_tickets',
+    'shoppex://tickets/open',
+    {
+      title: 'Open support tickets',
+      description: 'Tickets currently in status=open for the shop.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().ticketsList({ limit: 50, status: 'open' });
+      return jsonResource(uri.href, data ?? []);
+    },
+  );
+}

package/src/server.mjs

@@ -1,6 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod/v4';
+import { registerShoppexPrompts } from './prompts.mjs';
+import { registerShoppexResources } from './resources.mjs';
 
 const DEV_API_TIMEOUT_MS = Number.parseInt(process.env.SHOPPEX_DEV_API_TIMEOUT_MS ?? '10000', 10);
 
@@ -1162,7 +1164,7 @@ export async function executeCommerceTool(toolName, args) {
 export function createCommerceMcpServer() {
   const server = new McpServer({
     name: 'shoppex-commerce',
-    version: '0.1.0',
+    version: '0.7.0',
   });
 
   for (const tool of createCommerceToolCatalog()) {
@@ -1175,6 +1177,9 @@ export function createCommerceMcpServer() {
     });
   }
 
+  registerShoppexResources(server);
+  registerShoppexPrompts(server);
+
   return server;
 }