shopify-store-mcp 1.0.0

package/dist/logger.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Operation logger for tracking all GraphQL calls
+ * Logs to SQLite database for debugging and history
+ */
+/**
+ * Get the current session ID
+ */
+export declare function getSessionId(): string;
+/**
+ * Log a GraphQL operation
+ */
+export declare function logOperation(params: {
+    storeDomain: string;
+    toolName: string;
+    query: string;
+    variables?: Record<string, unknown>;
+    response?: unknown;
+    success: boolean;
+    errorMessage?: string;
+    durationMs: number;
+}): Promise<void>;
+/**
+ * Query operation history
+ */
+export declare function getOperationHistory(params: {
+    storeDomain: string;
+    toolName?: string;
+    operationType?: "query" | "mutation";
+    success?: boolean;
+    since?: Date;
+    limit?: number;
+}): Promise<Array<{
+    id: string;
+    toolName: string;
+    operationType: string;
+    query: string;
+    success: boolean;
+    errorMessage: string | null;
+    durationMs: number;
+    createdAt: Date;
+}>>;
+/**
+ * Get aggregated statistics
+ */
+export declare function getOperationStats(params: {
+    storeDomain: string;
+    since: Date;
+}): Promise<{
+    totalCalls: number;
+    successCount: number;
+    errorCount: number;
+    avgDurationMs: number;
+    byTool: Record<string, {
+        calls: number;
+        successRate: number;
+        avgDuration: number;
+    }>;
+}>;

package/dist/logger.js

@@ -0,0 +1,165 @@
+/**
+ * Operation logger for tracking all GraphQL calls
+ * Logs to SQLite database for debugging and history
+ */
+import prisma from "./db.js";
+import { randomUUID } from "crypto";
+// Session ID for this MCP process instance
+const sessionId = randomUUID();
+// Check if logging is enabled (default: true)
+const isLoggingEnabled = process.env.MCP_LOG_OPERATIONS !== "false";
+// Max length for query/response strings in DB
+const MAX_QUERY_LENGTH = 10000;
+const MAX_RESPONSE_LENGTH = 50000;
+/**
+ * Get the current session ID
+ */
+export function getSessionId() {
+    return sessionId;
+}
+/**
+ * Truncate a string to a maximum length
+ */
+function truncate(str, maxLength) {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return str.slice(0, maxLength) + "... [truncated]";
+}
+/**
+ * Detect if a GraphQL operation is a query or mutation
+ */
+function detectOperationType(query) {
+    const trimmed = query.trim().toLowerCase();
+    if (trimmed.startsWith("mutation")) {
+        return "mutation";
+    }
+    return "query";
+}
+/**
+ * Log a GraphQL operation
+ */
+export async function logOperation(params) {
+    if (!isLoggingEnabled) {
+        return;
+    }
+    try {
+        await prisma.operationLog.create({
+            data: {
+                storeDomain: params.storeDomain,
+                sessionId,
+                toolName: params.toolName,
+                operationType: detectOperationType(params.query),
+                query: truncate(params.query, MAX_QUERY_LENGTH),
+                variables: params.variables
+                    ? truncate(JSON.stringify(params.variables), MAX_QUERY_LENGTH)
+                    : null,
+                response: params.response
+                    ? truncate(JSON.stringify(params.response), MAX_RESPONSE_LENGTH)
+                    : null,
+                success: params.success,
+                errorMessage: params.errorMessage || null,
+                durationMs: params.durationMs,
+            },
+        });
+    }
+    catch (error) {
+        // Don't fail the operation if logging fails
+        console.error("[shopify-store-mcp] Failed to log operation:", error);
+    }
+}
+/**
+ * Query operation history
+ */
+export async function getOperationHistory(params) {
+    const where = {
+        storeDomain: params.storeDomain,
+    };
+    if (params.toolName) {
+        where.toolName = params.toolName;
+    }
+    if (params.operationType) {
+        where.operationType = params.operationType;
+    }
+    if (params.success !== undefined) {
+        where.success = params.success;
+    }
+    if (params.since) {
+        where.createdAt = { gte: params.since };
+    }
+    return prisma.operationLog.findMany({
+        where,
+        orderBy: { createdAt: "desc" },
+        take: params.limit || 50,
+        select: {
+            id: true,
+            toolName: true,
+            operationType: true,
+            query: true,
+            success: true,
+            errorMessage: true,
+            durationMs: true,
+            createdAt: true,
+        },
+    });
+}
+/**
+ * Get aggregated statistics
+ */
+export async function getOperationStats(params) {
+    // Get all operations in the period
+    const operations = await prisma.operationLog.findMany({
+        where: {
+            storeDomain: params.storeDomain,
+            createdAt: { gte: params.since },
+        },
+        select: {
+            toolName: true,
+            success: true,
+            durationMs: true,
+        },
+    });
+    if (operations.length === 0) {
+        return {
+            totalCalls: 0,
+            successCount: 0,
+            errorCount: 0,
+            avgDurationMs: 0,
+            byTool: {},
+        };
+    }
+    const totalCalls = operations.length;
+    const successCount = operations.filter((op) => op.success).length;
+    const errorCount = totalCalls - successCount;
+    const avgDurationMs = operations.reduce((sum, op) => sum + op.durationMs, 0) / totalCalls;
+    // Group by tool
+    const byTool = {};
+    const toolGroups = new Map();
+    for (const op of operations) {
+        const group = toolGroups.get(op.toolName) || {
+            total: 0,
+            success: 0,
+            duration: 0,
+        };
+        group.total++;
+        if (op.success)
+            group.success++;
+        group.duration += op.durationMs;
+        toolGroups.set(op.toolName, group);
+    }
+    for (const [toolName, group] of toolGroups) {
+        byTool[toolName] = {
+            calls: group.total,
+            successRate: group.success / group.total,
+            avgDuration: group.duration / group.total,
+        };
+    }
+    return {
+        totalCalls,
+        successCount,
+        errorCount,
+        avgDurationMs,
+        byTool,
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/prompts/index.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAllPrompts(server: McpServer): void;

package/dist/prompts/index.js

@@ -0,0 +1,169 @@
+import { z } from "zod";
+export function registerAllPrompts(server) {
+    // Product Analysis Prompt
+    server.registerPrompt("analyze-product", {
+        title: "Analyze Product",
+        description: "Generate a detailed analysis of a product including its variants, pricing, inventory status, and recommendations for optimization.",
+        argsSchema: {
+            productId: z
+                .string()
+                .describe("The product ID (GID or numeric) to analyze"),
+        },
+    }, async ({ productId }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Please analyze the product with ID "${productId}". Use the get_product tool to fetch its details, then provide:
+
+1. **Product Overview**: Title, vendor, type, and current status
+2. **Pricing Analysis**: Current prices across variants, compare-at prices if set
+3. **Inventory Status**: Stock levels, which variants are low or out of stock
+4. **SEO Review**: Handle, title length, description quality
+5. **Recommendations**: Actionable suggestions to improve the product listing
+
+Start by fetching the product data.`,
+                },
+            },
+        ],
+    }));
+    // Order Summary Prompt
+    server.registerPrompt("summarize-orders", {
+        title: "Summarize Recent Orders",
+        description: "Generate a summary of recent orders including revenue, fulfillment status, and trends.",
+        argsSchema: {
+            timeframe: z
+                .enum(["today", "week", "month"])
+                .default("week")
+                .describe("The timeframe to analyze"),
+            limit: z
+                .number()
+                .default(50)
+                .describe("Number of orders to fetch"),
+        },
+    }, async ({ timeframe, limit }) => {
+        const dateFilter = timeframe === "today"
+            ? "created_at:>=today"
+            : timeframe === "week"
+                ? "created_at:>=7_days_ago"
+                : "created_at:>=30_days_ago";
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Please provide a summary of orders from the ${timeframe}. Use the get_orders tool with query "${dateFilter}" and first=${limit}.
+
+Include in your analysis:
+1. **Total Orders**: Count and total revenue
+2. **Fulfillment Status**: Breakdown by unfulfilled, partially fulfilled, fulfilled
+3. **Payment Status**: Breakdown by paid, pending, refunded
+4. **Top Products**: Most ordered items
+5. **Average Order Value**: Calculate and compare to typical benchmarks
+
+Start by fetching the order data.`,
+                    },
+                },
+            ],
+        };
+    });
+    // Inventory Health Check Prompt
+    server.registerPrompt("inventory-health", {
+        title: "Inventory Health Check",
+        description: "Analyze inventory levels across products and identify items that need attention (low stock, overstock, etc.).",
+        argsSchema: {
+            threshold: z
+                .number()
+                .default(10)
+                .describe("Low stock threshold to flag items"),
+        },
+    }, async ({ threshold }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Please perform an inventory health check. Use the get_inventory tool to fetch inventory levels.
+
+Analyze and report:
+1. **Low Stock Items**: Products with inventory below ${threshold} units
+2. **Out of Stock**: Items with zero inventory
+3. **Overstock Candidates**: Items with unusually high inventory (if detectable)
+4. **Inventory Distribution**: Summary by location if multiple locations exist
+5. **Action Items**: Prioritized list of items needing restocking
+
+Start by fetching inventory data.`,
+                },
+            },
+        ],
+    }));
+    // Customer Insights Prompt
+    server.registerPrompt("customer-insights", {
+        title: "Customer Insights",
+        description: "Analyze customer data to identify patterns, VIP customers, and engagement opportunities.",
+        argsSchema: {
+            segment: z
+                .enum(["all", "repeat", "high-value", "recent"])
+                .default("all")
+                .describe("Customer segment to analyze"),
+        },
+    }, async ({ segment }) => {
+        const queryMap = {
+            all: "",
+            repeat: "orders_count:>1",
+            "high-value": "total_spent:>500",
+            recent: "updated_at:>=30_days_ago",
+        };
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Please analyze the "${segment}" customer segment. Use the get_customers tool${queryMap[segment] ? ` with query "${queryMap[segment]}"` : ""}.
+
+Provide insights on:
+1. **Customer Count**: Total customers in this segment
+2. **Engagement Metrics**: Average orders, total spent
+3. **Geographic Distribution**: Where customers are located
+4. **VIP Identification**: Top customers by order count or spend
+5. **Opportunities**: Suggestions for engagement or retention
+
+Start by fetching customer data.`,
+                    },
+                },
+            ],
+        };
+    });
+    // Custom GraphQL Query Prompt
+    server.registerPrompt("custom-query", {
+        title: "Custom GraphQL Query",
+        description: "Help construct and execute a custom GraphQL query against the Shopify Admin API.",
+        argsSchema: {
+            intent: z
+                .string()
+                .describe("What data do you want to fetch or what action do you want to perform?"),
+        },
+    }, async ({ intent }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `I need help with a custom Shopify Admin API query. My goal is: "${intent}"
+
+Please:
+1. Determine if this requires a query (read) or mutation (write)
+2. Construct the appropriate GraphQL operation
+3. Use the run_graphql_query tool to execute it
+4. Explain the results
+
+If you're unsure about the exact schema, start with a simpler query and iterate based on what fields are available.`,
+                },
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=index.js.map

package/dist/queue.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Rate-limited queue for Shopify API calls
+ * Respects Shopify's rate limits based on shop plan tier
+ */
+export declare const SHOPIFY_TIER_CONFIGS: {
+    readonly STANDARD: {
+        readonly name: "Standard Shopify";
+        readonly concurrency: 1;
+        readonly interval: 1000;
+        readonly intervalCap: 1;
+    };
+    readonly ADVANCED: {
+        readonly name: "Advanced Shopify";
+        readonly concurrency: 1;
+        readonly interval: 1000;
+        readonly intervalCap: 2;
+    };
+    readonly PLUS: {
+        readonly name: "Shopify Plus";
+        readonly concurrency: 2;
+        readonly interval: 1000;
+        readonly intervalCap: 5;
+    };
+    readonly ENTERPRISE: {
+        readonly name: "Shopify for Enterprise (Commerce Components)";
+        readonly concurrency: 3;
+        readonly interval: 1000;
+        readonly intervalCap: 10;
+    };
+};
+export type ShopifyTier = keyof typeof SHOPIFY_TIER_CONFIGS;
+/**
+ * Get the current queue configuration
+ */
+export declare function getCurrentTierInfo(): {
+    tier: ShopifyTier;
+    config: (typeof SHOPIFY_TIER_CONFIGS)[ShopifyTier];
+};
+/**
+ * Update the queue to use a different tier's rate limits
+ */
+export declare function updateQueue(tier: ShopifyTier): void;
+/**
+ * Detect Shopify tier from shop plan information
+ */
+export declare function detectTierFromPlan(plan: {
+    shopifyPlus?: boolean;
+    displayName?: string;
+}): ShopifyTier;
+/**
+ * Enqueue a function to be executed with rate limiting
+ */
+export declare function enqueue<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Get queue statistics
+ */
+export declare function getQueueStats(): {
+    pending: number;
+    size: number;
+    isPaused: boolean;
+};
+/**
+ * Pause the queue (useful for graceful shutdown)
+ */
+export declare function pauseQueue(): void;
+/**
+ * Resume the queue
+ */
+export declare function resumeQueue(): void;
+/**
+ * Clear all pending items from the queue
+ */
+export declare function clearQueue(): void;

package/dist/queue.js

@@ -0,0 +1,120 @@
+/**
+ * Rate-limited queue for Shopify API calls
+ * Respects Shopify's rate limits based on shop plan tier
+ */
+import PQueue from "p-queue";
+// Shopify Admin API rate limit configurations
+// https://shopify.dev/docs/api/usage/limits#rate-limits
+export const SHOPIFY_TIER_CONFIGS = {
+    STANDARD: {
+        name: "Standard Shopify",
+        // GraphQL Admin API: 100 points/second, bucket size 1000 points
+        // Conservative settings: ~1 request/second
+        concurrency: 1,
+        interval: 1000,
+        intervalCap: 1,
+    },
+    ADVANCED: {
+        name: "Advanced Shopify",
+        // GraphQL Admin API: 200 points/second
+        concurrency: 1,
+        interval: 1000,
+        intervalCap: 2,
+    },
+    PLUS: {
+        name: "Shopify Plus",
+        // GraphQL Admin API: 1000 points/second
+        concurrency: 2,
+        interval: 1000,
+        intervalCap: 5,
+    },
+    ENTERPRISE: {
+        name: "Shopify for Enterprise (Commerce Components)",
+        // GraphQL Admin API: 2000 points/second
+        concurrency: 3,
+        interval: 1000,
+        intervalCap: 10,
+    },
+};
+// Global queue instance
+let queue = new PQueue(SHOPIFY_TIER_CONFIGS.STANDARD);
+let currentTier = "STANDARD";
+/**
+ * Get the current queue configuration
+ */
+export function getCurrentTierInfo() {
+    return {
+        tier: currentTier,
+        config: SHOPIFY_TIER_CONFIGS[currentTier],
+    };
+}
+/**
+ * Update the queue to use a different tier's rate limits
+ */
+export function updateQueue(tier) {
+    const config = SHOPIFY_TIER_CONFIGS[tier];
+    // Clear existing queue and create new one
+    queue.clear();
+    queue = new PQueue({
+        concurrency: config.concurrency,
+        interval: config.interval,
+        intervalCap: config.intervalCap,
+    });
+    currentTier = tier;
+    console.error(`[shopify-store-mcp] Queue updated to ${config.name} tier (${tier})`);
+}
+/**
+ * Detect Shopify tier from shop plan information
+ */
+export function detectTierFromPlan(plan) {
+    // Check for Shopify Plus first (most specific)
+    if (plan.shopifyPlus) {
+        return "PLUS";
+    }
+    // Check display name for other tiers
+    const displayName = (plan.displayName || "").toLowerCase();
+    if (displayName.includes("advanced")) {
+        return "ADVANCED";
+    }
+    if (displayName.includes("enterprise") ||
+        displayName.includes("commerce components")) {
+        return "ENTERPRISE";
+    }
+    // Default to STANDARD for Basic, Development, Grow, Lite, etc.
+    return "STANDARD";
+}
+/**
+ * Enqueue a function to be executed with rate limiting
+ */
+export async function enqueue(fn) {
+    return queue.add(fn);
+}
+/**
+ * Get queue statistics
+ */
+export function getQueueStats() {
+    return {
+        pending: queue.pending,
+        size: queue.size,
+        isPaused: queue.isPaused,
+    };
+}
+/**
+ * Pause the queue (useful for graceful shutdown)
+ */
+export function pauseQueue() {
+    queue.pause();
+}
+/**
+ * Resume the queue
+ */
+export function resumeQueue() {
+    queue.start();
+}
+/**
+ * Clear all pending items from the queue
+ */
+export function clearQueue() {
+    queue.clear();
+}
+//# sourceMappingURL=queue.js.map

package/dist/resources/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ShopifyConfig } from "../config.js";
+export declare function registerAllResources(server: McpServer, config: ShopifyConfig): void;