epicmerch-mcp 1.0.0

package/src/tools/_examples.js

@@ -0,0 +1,352 @@
+// src/tools/_examples.js
+//
+// Sample prompts seeded into each MCP tool's `description` at registration time.
+// This is how Claude/ChatGPT learn which prompts should auto-route to which tool.
+//
+// Add a new entry whenever a new merchant_* tool is added.
+
+export const TOOL_EXAMPLES = {
+  // --- Setup & diagnosis ---
+  merchant_quick_setup: [
+    'Set up an EpicMerch store for me',
+    'I want to start selling online',
+    'Create a store and import from Shopify',
+  ],
+  merchant_diagnose: [
+    'Is my store ready to launch?',
+    "What's still missing from my setup?",
+    'Check my store health',
+  ],
+
+  // --- Products ---
+  merchant_list_products: [
+    'Show me my products',
+    'List products in the Apparel category',
+    'How many products do I have?',
+  ],
+  merchant_get_product: [
+    'Show me product details for Blue Tee',
+    'Get product 123',
+  ],
+  merchant_create_product: [
+    'Add a new product called Blue Tee for $25',
+    'Create a product',
+  ],
+  merchant_update_product: [
+    'Change the price of Blue Tee to $30',
+    'Update product stock',
+  ],
+  merchant_delete_product: [
+    'Delete the product called Old Tee',
+    'Remove product 456',
+  ],
+  merchant_generate_product_description: [
+    'Generate a description for my new hoodie',
+    'Write product copy for the Red Hoodie',
+  ],
+  merchant_get_product_recommendations: [
+    'Recommend related products',
+    'What products should I show together?',
+  ],
+
+  // --- Categories ---
+  merchant_list_categories: [
+    'Show me my product categories',
+    'List all categories',
+  ],
+  merchant_create_category: [
+    'Create a category called Winter Collection',
+    'Add a new category',
+  ],
+  merchant_update_category: [
+    'Rename my Winter category',
+    'Update category visibility',
+  ],
+  merchant_delete_category: [
+    'Delete the Winter category',
+    'Remove category 789',
+  ],
+  merchant_toggle_category_visibility: [
+    'Hide the Sale category',
+    'Make the Featured category visible',
+  ],
+
+  // --- Orders ---
+  merchant_list_orders: [
+    'Show recent orders',
+    'Which orders are pending?',
+    'List shipped orders',
+  ],
+  merchant_get_order: [
+    'Show me order #123',
+    'Get details for order ord_abc',
+  ],
+  merchant_update_order_status: [
+    'Mark order #123 as shipped',
+    'Cancel order #456',
+  ],
+  merchant_update_payment_status: [
+    'Mark order #123 as paid',
+    'Set order payment to unpaid',
+  ],
+
+  // --- Customers ---
+  merchant_list_customers: [
+    'Show me my customers',
+    'List all users',
+  ],
+  merchant_get_customer: [
+    'Show me customer details for John',
+    'Get customer 456',
+  ],
+  merchant_delete_customer: [
+    'Delete customer 456',
+    'Remove a user account',
+  ],
+
+  // --- Analytics ---
+  merchant_get_analytics_stats: [
+    'How are my sales this week?',
+    "What's my revenue today?",
+    'Show me overall store stats',
+  ],
+  merchant_get_sales_trend: [
+    'How are sales trending over the last month?',
+    'Show the sales chart',
+  ],
+  merchant_get_top_products: [
+    'What are my best-selling products?',
+    'Top products this month',
+  ],
+  merchant_get_traffic: [
+    'How much storefront traffic did I get?',
+    'Show me visitor stats',
+  ],
+  merchant_get_revenue_by_category: [
+    'Which category makes me the most money?',
+    'Revenue breakdown by category',
+  ],
+  merchant_get_cart_abandonment: [
+    "What's my cart abandonment rate?",
+    'How many carts were abandoned?',
+  ],
+  merchant_get_order_status_distribution: [
+    'How are my orders distributed by status?',
+    'Order status breakdown',
+  ],
+  merchant_get_peak_hours: [
+    'When do I get the most orders?',
+    'Peak shopping hours',
+  ],
+  merchant_get_geographic_distribution: [
+    'Where are my customers from?',
+    'Show me orders by region',
+  ],
+  merchant_get_period_comparison: [
+    'How does this month compare to last month?',
+    'Compare current vs previous period',
+  ],
+  merchant_get_ai_insights: [
+    'Give me AI insights on my store',
+    "What's the AI noticing about my sales?",
+  ],
+
+  // --- Notifications ---
+  merchant_list_subscribers: [
+    'Show my newsletter subscribers',
+    'How many people subscribe?',
+  ],
+  merchant_send_notification: [
+    'Send a promo email to my customers',
+    'Send a notification',
+  ],
+  merchant_get_abandoned_carts: [
+    'Show me abandoned carts from the last 24 hours',
+    'Who has abandoned a cart?',
+  ],
+  merchant_send_to_user: [
+    'Send a notification to customer 456',
+    'Message a specific user',
+  ],
+  merchant_get_notification_history: [
+    'Show my notification history',
+    'What notifications did I send?',
+  ],
+  merchant_get_notification_stats: [
+    'How are my notifications performing?',
+    'Notification open rates',
+  ],
+
+  // --- Settings ---
+  merchant_get_settings: [
+    'Show me my store settings',
+    'What are my current settings?',
+  ],
+  merchant_update_currency: [
+    'Change my store currency to USD',
+    'Set currency to EUR',
+  ],
+  merchant_get_checkout_settings: [
+    'Show me my checkout configuration',
+    'Is my payment configured?',
+  ],
+  merchant_update_checkout_settings: [
+    'Update my Razorpay keys',
+    'Change my checkout type',
+  ],
+  merchant_get_email_settings: [
+    'Show me my email settings',
+    'How is email configured?',
+  ],
+  merchant_update_email_settings: [
+    'Update my SMTP settings',
+    'Change email sender address',
+  ],
+  merchant_get_logistics_settings: [
+    'Show my shipping configuration',
+    'Is Shiprocket connected?',
+  ],
+  merchant_update_logistics_settings: [
+    'Update my Shiprocket credentials',
+    'Change logistics settings',
+  ],
+  merchant_get_security_settings: [
+    'Show my security settings',
+    'What domains are allowed?',
+  ],
+  merchant_add_allowed_domain: [
+    'Allow mystore.com to access my API',
+    'Add a CORS domain',
+  ],
+  merchant_remove_allowed_domain: [
+    'Remove olddomain.com from allowed list',
+    'Block a domain',
+  ],
+
+  // --- API Keys ---
+  merchant_list_api_keys: [
+    'Show me my API keys',
+    'List my API keys',
+  ],
+  merchant_generate_api_key: [
+    'Generate a new API key called Mobile App',
+    'Create an API key',
+  ],
+  merchant_delete_api_key: [
+    'Revoke the Mobile App API key',
+    'Delete API key abc123',
+  ],
+
+  // --- Storefront generation ---
+  merchant_list_storefront_templates: [
+    'Show me storefront templates',
+    'What storefront designs are available?',
+  ],
+  merchant_generate_storefront_from_prompt: [
+    'Build me a storefront for a streetwear brand',
+    'Generate a storefront from this prompt',
+  ],
+  merchant_get_deploy_options: [
+    'How can I deploy my storefront?',
+    'Show deployment options',
+  ],
+
+  // --- GitHub ---
+  merchant_get_github_status: [
+    'Is GitHub connected?',
+    'Show my GitHub status',
+  ],
+  merchant_list_github_repos: [
+    'List my GitHub repositories',
+    'Show my connected repos',
+  ],
+  merchant_push_to_github: [
+    'Push my storefront to GitHub',
+    'Deploy code to my repo',
+  ],
+
+  // --- Logistics ---
+  merchant_get_shipping_rates: [
+    'What are shipping rates for an order?',
+    'Calculate shipping cost',
+  ],
+  merchant_create_shipment: [
+    'Create a shipment for order 123',
+    'Ship this order',
+  ],
+  merchant_track_shipment: [
+    'Track shipment ABC123',
+    "Where's my package?",
+  ],
+
+  // --- Finance ---
+  merchant_get_consolidation_report: [
+    'Show my financial consolidation',
+    'Get the reconciliation report',
+  ],
+
+  // --- Shiprocket ---
+  merchant_list_sr_orders: [
+    'Show Shiprocket orders',
+    'List SR Checkout orders',
+  ],
+  merchant_initiate_refund: [
+    'Refund order 123 for $50',
+    'Initiate a Shiprocket refund',
+  ],
+  merchant_sync_product_to_sr: [
+    'Sync product 789 to Shiprocket',
+    'Push a product to SR catalog',
+  ],
+
+  // --- Shopify migration ---
+  merchant_shopify_migrate: [
+    'Migrate my Shopify store',
+    'Import products from mystore.myshopify.com',
+    'Move my Shopify catalog to EpicMerch',
+  ],
+
+  // --- Stripe ---
+  merchant_configure_stripe: [
+    'Set up Stripe for my store',
+    'Configure my Stripe payment keys',
+    'Add Stripe to my EpicMerch store',
+  ],
+  merchant_test_stripe_connection: [
+    'Test my Stripe connection',
+    'Is Stripe configured correctly?',
+    'Verify my Stripe keys work',
+  ],
+  merchant_set_checkout_type: [
+    'Switch my checkout to Stripe',
+    'Change checkout to Razorpay',
+    'Use Shiprocket Checkout',
+  ],
+};
+
+/**
+ * Returns a new array of tool definitions with example prompts appended to each
+ * description (when the tool name has an entry in TOOL_EXAMPLES).
+ *
+ * Does not mutate the input. Tools without an entry pass through unchanged.
+ * A malformed entry (non-array) is silently skipped — the tool registers with
+ * its base description so a typo in TOOL_EXAMPLES can never break server startup.
+ *
+ * @param {Array<{name: string, description: string, schema: object}>} defs
+ * @returns {Array<{name: string, description: string, schema: object}>}
+ */
+export function withExamples(defs) {
+  return defs.map((def) => {
+    const examples = TOOL_EXAMPLES[def.name];
+    if (!Array.isArray(examples) || examples.length === 0) return { ...def };
+
+    const block = [
+      '',
+      '',
+      'Example prompts that should trigger this tool:',
+      ...examples.map((e) => `- "${e}"`),
+    ].join('\n');
+
+    return { ...def, description: (def.description ?? '') + block };
+  });
+}

package/src/tools/developer.js

@@ -0,0 +1,65 @@
+// src/tools/developer.js
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const readExample = (name) =>
+  readFileSync(join(__dir, '../resources/examples', `${name}.md`), 'utf-8');
+
+export function developerTools(client) {
+  return {
+    async store_get_config(_args) {
+      const data = await client.get('/customer/config');
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+
+    async store_list_products({ category, keyword, sort, page, limit } = {}) {
+      const p = new URLSearchParams();
+      if (category) p.set('type', category);
+      if (keyword) p.set('keyword', keyword);
+      if (sort) p.set('sort', sort);
+      if (page) p.set('page', page);
+      if (limit) p.set('limit', limit);
+      const qs = p.toString();
+      const data = await client.get(`/products/public${qs ? `?${qs}` : ''}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+
+    async store_get_product({ id }) {
+      const data = await client.get(`/products/public/${id}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+
+    async store_search_products({ query, category, page, limit } = {}) {
+      const p = new URLSearchParams({ keyword: query });
+      if (category) p.set('type', category);
+      if (page) p.set('page', page);
+      if (limit) p.set('limit', limit);
+      const data = await client.get(`/products/public?${p.toString()}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+
+    async store_list_categories(_args) {
+      const data = await client.get('/categories/visible');
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+
+    async store_get_integration_guide({ module }) {
+      const valid = ['auth', 'products', 'orders', 'payments'];
+      if (!valid.includes(module)) {
+        return { isError: true, content: [{ type: 'text', text: `module must be one of: ${valid.join(', ')}` }] };
+      }
+      return { content: [{ type: 'text', text: readExample(module) }] };
+    },
+  };
+}
+
+export const developerToolDefs = [
+  { name: 'store_get_config', description: 'Fetch the active store config (merchant name, currency, checkout type).', schema: {} },
+  { name: 'store_list_products', description: 'List products from the active store.', schema: { category: { type: 'string' }, keyword: { type: 'string' }, sort: { type: 'string' }, page: { type: 'number' }, limit: { type: 'number' } } },
+  { name: 'store_get_product', description: 'Get a single product by ID.', schema: { id: { type: 'string' } } },
+  { name: 'store_search_products', description: 'Search products by keyword.', schema: { query: { type: 'string' }, category: { type: 'string' }, page: { type: 'number' }, limit: { type: 'number' } } },
+  { name: 'store_list_categories', description: 'List all visible product categories.', schema: {} },
+  { name: 'store_get_integration_guide', description: 'Get code examples for integrating a specific EpicMerch module. module: auth | products | orders | payments', schema: { module: { type: 'string' } } },
+];