shopify-store-mcp 1.0.0

package/dist/resources/index.js

@@ -0,0 +1,180 @@
+export function registerAllResources(server, config) {
+    // Store Configuration Resource
+    server.registerResource("store-config", "shopify://config", {
+        title: "Store Configuration",
+        description: "Current store connection configuration including domain and API version. " +
+            "Use this to verify which store you're connected to.",
+        mimeType: "application/json",
+    }, async () => ({
+        contents: [
+            {
+                uri: "shopify://config",
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    storeDomain: config.storeDomain,
+                    apiVersion: config.apiVersion,
+                    hasStorefrontAccess: !!config.storefrontAccessToken,
+                    hasCustomerAccess: !!config.customerAccessToken,
+                }, null, 2),
+            },
+        ],
+    }));
+    // Shopify Query Syntax Reference
+    server.registerResource("query-syntax", "shopify://docs/query-syntax", {
+        title: "Shopify Query Syntax Reference",
+        description: "Reference guide for Shopify's search query syntax used in filtering products, orders, customers, etc.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "shopify://docs/query-syntax",
+                mimeType: "text/markdown",
+                text: `# Shopify Query Syntax Reference
+
+## Basic Syntax
+
+Queries use field:value pairs separated by spaces (AND logic).
+
+## Common Fields by Resource
+
+### Products
+- \`title:boots\` - Title contains "boots"
+- \`status:active\` - Product status (active, draft, archived)
+- \`vendor:Nike\` - Filter by vendor
+- \`product_type:shoes\` - Filter by product type
+- \`tag:sale\` - Has specific tag
+- \`created_at:>2024-01-01\` - Created after date
+- \`inventory_total:>0\` - Has inventory
+
+### Orders
+- \`name:#1001\` - Order number
+- \`email:customer@example.com\` - Customer email
+- \`financial_status:paid\` - Payment status (paid, pending, refunded, voided)
+- \`fulfillment_status:unfulfilled\` - Fulfillment status (unfulfilled, partial, fulfilled)
+- \`created_at:>=7_days_ago\` - Relative date
+- \`tag:wholesale\` - Has specific tag
+
+### Customers
+- \`email:john@example.com\` - Email address
+- \`country:US\` - Country code
+- \`orders_count:>5\` - Number of orders
+- \`total_spent:>100\` - Total amount spent
+- \`tag:vip\` - Has specific tag
+- \`state:enabled\` - Account state
+
+### Collections
+- \`title:Summer\` - Collection title
+- \`collection_type:smart\` - Type (smart or custom)
+
+## Operators
+- \`:value\` - Equals or contains
+- \`:>value\` - Greater than
+- \`:>=value\` - Greater than or equal
+- \`:<value\` - Less than
+- \`:<=value\` - Less than or equal
+
+## Date Shortcuts
+- \`today\`
+- \`yesterday\`
+- \`7_days_ago\`
+- \`30_days_ago\`
+- \`90_days_ago\`
+
+## Examples
+\`\`\`
+# Active products from Nike with low inventory
+status:active vendor:Nike inventory_total:<10
+
+# Paid but unfulfilled orders from this week
+financial_status:paid fulfillment_status:unfulfilled created_at:>=7_days_ago
+
+# VIP customers with multiple orders
+tag:vip orders_count:>3
+\`\`\`
+`,
+            },
+        ],
+    }));
+    // GID Format Reference
+    server.registerResource("gid-format", "shopify://docs/gid-format", {
+        title: "Shopify GID Format Reference",
+        description: "Reference for Shopify's Global ID (GID) format used to identify resources.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "shopify://docs/gid-format",
+                mimeType: "text/markdown",
+                text: `# Shopify GID (Global ID) Format
+
+## Format
+\`gid://shopify/{ResourceType}/{NumericID}\`
+
+## Common Resource Types
+| Type | GID Example |
+|------|-------------|
+| Product | \`gid://shopify/Product/123456789\` |
+| ProductVariant | \`gid://shopify/ProductVariant/123456789\` |
+| Order | \`gid://shopify/Order/123456789\` |
+| Customer | \`gid://shopify/Customer/123456789\` |
+| Collection | \`gid://shopify/Collection/123456789\` |
+| InventoryItem | \`gid://shopify/InventoryItem/123456789\` |
+| InventoryLevel | \`gid://shopify/InventoryLevel/123456789?inventory_item_id=X&location_id=Y\` |
+| Location | \`gid://shopify/Location/123456789\` |
+| Metafield | \`gid://shopify/Metafield/123456789\` |
+| FulfillmentOrder | \`gid://shopify/FulfillmentOrder/123456789\` |
+
+## Notes
+- Most tools in this MCP accept both numeric IDs and full GIDs
+- When in doubt, use the full GID format
+- GIDs from query responses can be used directly in subsequent calls
+`,
+            },
+        ],
+    }));
+    // Available Scopes Reference
+    server.registerResource("api-scopes", "shopify://docs/scopes", {
+        title: "API Scopes Reference",
+        description: "Reference for Shopify Admin API access scopes required for different operations.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "shopify://docs/scopes",
+                mimeType: "text/markdown",
+                text: `# Shopify Admin API Scopes
+
+## Required Scopes by Operation
+
+### Products
+- \`read_products\` - List and view products
+- \`write_products\` - Create and update products
+
+### Orders
+- \`read_orders\` - List and view orders
+- \`write_orders\` - Update orders, create fulfillments
+
+### Customers
+- \`read_customers\` - List and view customers
+- \`write_customers\` - Create and update customers
+
+### Inventory
+- \`read_inventory\` - View inventory levels
+- \`write_inventory\` - Adjust inventory quantities
+
+### Other Common Scopes
+- \`read_locations\` - View store locations
+- \`read_shipping\` - View shipping settings
+- \`read_fulfillments\` - View fulfillments
+- \`write_fulfillments\` - Create fulfillments
+
+## Checking Your Scopes
+If a tool returns a 403 error, it likely means your custom app is missing the required scope. Update your app's API access scopes in:
+
+**Shopify Admin → Settings → Apps and sales channels → Develop apps → [Your App] → Configuration**
+`,
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=index.js.map

package/dist/shopify-client.d.ts

@@ -0,0 +1,16 @@
+import { type AdminApiClient } from "@shopify/admin-api-client";
+import { type StorefrontApiClient } from "@shopify/storefront-api-client";
+import type { ShopifyConfig } from "./config.js";
+/**
+ * Get the Admin API client (singleton).
+ * Used for store management operations: products, orders, customers, inventory, etc.
+ */
+export declare function getAdminClient(config: ShopifyConfig): AdminApiClient;
+/**
+ * Get the Storefront API client (singleton).
+ * Used for customer-facing operations: product browsing, cart, checkout, etc.
+ * Requires SHOPIFY_STOREFRONT_ACCESS_TOKEN to be set.
+ */
+export declare function getStorefrontClient(config: ShopifyConfig): StorefrontApiClient | null;
+export declare const getShopifyClient: typeof getAdminClient;
+export type { AdminApiClient, StorefrontApiClient };

package/dist/shopify-client.js

@@ -0,0 +1,39 @@
+import { createAdminApiClient } from "@shopify/admin-api-client";
+import { createStorefrontApiClient } from "@shopify/storefront-api-client";
+let adminClientInstance = null;
+let storefrontClientInstance = null;
+/**
+ * Get the Admin API client (singleton).
+ * Used for store management operations: products, orders, customers, inventory, etc.
+ */
+export function getAdminClient(config) {
+    if (!adminClientInstance) {
+        adminClientInstance = createAdminApiClient({
+            storeDomain: config.storeDomain,
+            apiVersion: config.apiVersion,
+            accessToken: config.adminAccessToken,
+        });
+    }
+    return adminClientInstance;
+}
+/**
+ * Get the Storefront API client (singleton).
+ * Used for customer-facing operations: product browsing, cart, checkout, etc.
+ * Requires SHOPIFY_STOREFRONT_ACCESS_TOKEN to be set.
+ */
+export function getStorefrontClient(config) {
+    if (!config.storefrontAccessToken) {
+        return null;
+    }
+    if (!storefrontClientInstance) {
+        storefrontClientInstance = createStorefrontApiClient({
+            storeDomain: config.storeDomain,
+            apiVersion: config.apiVersion,
+            publicAccessToken: config.storefrontAccessToken,
+        });
+    }
+    return storefrontClientInstance;
+}
+// Legacy alias for backwards compatibility
+export const getShopifyClient = getAdminClient;
+//# sourceMappingURL=shopify-client.js.map

package/dist/tools/graphql.d.ts

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

package/dist/tools/graphql.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { formatSuccessResponse, formatGraphQLErrors, formatErrorResponse, } from "../errors.js";
+export function registerGraphQLTools(server, client) {
+    server.registerTool("run_graphql_query", {
+        title: "Run GraphQL Query",
+        description: "Execute any GraphQL query or mutation against the Shopify Admin API. " +
+            "This is the most powerful and flexible tool - use it when other specialized tools " +
+            "don't cover your use case, or when you need precise control over the query shape. " +
+            "Returns the raw API response including data and any errors. " +
+            "Refer to Shopify's Admin API GraphQL reference for available queries and mutations.",
+        inputSchema: {
+            query: z
+                .string()
+                .describe("The GraphQL query or mutation string. Must be valid GraphQL syntax. " +
+                "Example: 'query { shop { name } }'"),
+            variables: z
+                .record(z.unknown())
+                .optional()
+                .describe("Variables to pass to the GraphQL operation as a JSON object. " +
+                "Keys should match the variable names in your query (without the $ prefix)."),
+        },
+        annotations: {
+            // Cannot determine if read-only since it could be a mutation
+            openWorldHint: true,
+        },
+    }, async ({ query, variables }) => {
+        try {
+            const response = await client.request(query, {
+                variables: variables,
+            });
+            if (response.errors) {
+                return formatGraphQLErrors(response);
+            }
+            return formatSuccessResponse(response.data);
+        }
+        catch (error) {
+            return formatErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=graphql.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AdminApiClient } from "../shopify-client.js";
+export declare function registerAllTools(server: McpServer, client: AdminApiClient, storeDomain: string): void;

package/dist/tools/index.js

@@ -0,0 +1,23 @@
+// Core tools
+import { registerShopTools } from "./shop.js";
+import { registerGraphQLTools } from "./graphql.js";
+// Smart tools (multi-step workflows)
+import { registerSmartFileTools } from "./smart-files.js";
+import { registerSmartBulkTools } from "./smart-bulk.js";
+import { registerSmartMetaobjectTools } from "./smart-metaobjects.js";
+import { registerSmartSchemaTools } from "./smart-schema.js";
+// Infrastructure tools
+import { registerInfrastructureTools } from "./infrastructure.js";
+export function registerAllTools(server, client, storeDomain) {
+    // Core tools (2)
+    registerShopTools(server, client); // get_shop_info
+    registerGraphQLTools(server, client); // run_graphql_query - the universal escape hatch
+    // Smart tools (5) - multi-step workflows that agents would struggle with
+    registerSmartFileTools(server, client, storeDomain); // upload_file
+    registerSmartBulkTools(server, client, storeDomain); // bulk_export, bulk_import
+    registerSmartMetaobjectTools(server, client, storeDomain); // upsert_metaobject
+    registerSmartSchemaTools(server, client, storeDomain); // schema_discover
+    // Infrastructure tools (3) - config, debugging, stats
+    registerInfrastructureTools(server, client, storeDomain); // configure, get_history, get_stats
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/infrastructure.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Infrastructure tools for configuration, history, and stats
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AdminApiClient } from "../shopify-client.js";
+export declare function registerInfrastructureTools(server: McpServer, client: AdminApiClient, storeDomain: string): void;

package/dist/tools/infrastructure.js

@@ -0,0 +1,215 @@
+/**
+ * Infrastructure tools for configuration, history, and stats
+ */
+import { z } from "zod";
+import { formatSuccessResponse, formatGraphQLErrors, formatErrorResponse, } from "../errors.js";
+import prisma from "../db.js";
+import { updateQueue, detectTierFromPlan, getCurrentTierInfo, SHOPIFY_TIER_CONFIGS, } from "../queue.js";
+import { getOperationHistory, getOperationStats, getSessionId, } from "../logger.js";
+import { GET_SHOP } from "../graphql/admin/index.js";
+import { enqueue } from "../queue.js";
+export function registerInfrastructureTools(server, client, storeDomain) {
+    // CONFIGURE
+    server.registerTool("configure", {
+        title: "Configure MCP",
+        description: "Configure the MCP server settings. " +
+            "Set the rate limit tier manually or auto-detect from shop plan. " +
+            "Returns current configuration including tier, queue settings, and session info.",
+        inputSchema: {
+            tier: z
+                .enum(["STANDARD", "ADVANCED", "PLUS", "ENTERPRISE"])
+                .optional()
+                .describe("Manually set the rate limit tier. " +
+                "STANDARD: 1 req/sec (Basic, Development plans). " +
+                "ADVANCED: 2 req/sec (Advanced plans). " +
+                "PLUS: 5 req/sec (Shopify Plus). " +
+                "ENTERPRISE: 10 req/sec (Commerce Components)."),
+            autoDetect: z
+                .boolean()
+                .optional()
+                .describe("Auto-detect tier from shop plan. " +
+                "Queries the shop and sets tier based on plan name."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ tier, autoDetect }) => {
+        try {
+            let detectedTier;
+            let shopPlan;
+            let shopName;
+            // Auto-detect from shop plan
+            if (autoDetect) {
+                const response = await enqueue(() => client.request(GET_SHOP, {}));
+                if (response.errors) {
+                    return formatGraphQLErrors(response);
+                }
+                const shopData = response.data;
+                shopName = shopData.shop.name;
+                shopPlan = shopData.shop.plan.displayName;
+                detectedTier = detectTierFromPlan({
+                    shopifyPlus: shopData.shop.plan.shopifyPlus,
+                    displayName: shopData.shop.plan.displayName,
+                });
+            }
+            // Use provided tier, or detected tier, or keep current
+            const newTier = tier || detectedTier;
+            if (newTier) {
+                updateQueue(newTier);
+                // Save to database
+                await prisma.storeConfig.upsert({
+                    where: { storeDomain },
+                    update: {
+                        tier: newTier,
+                        autoDetected: !!autoDetect,
+                        shopName,
+                        shopPlan,
+                    },
+                    create: {
+                        storeDomain,
+                        tier: newTier,
+                        autoDetected: !!autoDetect,
+                        shopName,
+                        shopPlan,
+                    },
+                });
+            }
+            // Get current config
+            const currentTier = getCurrentTierInfo();
+            const config = await prisma.storeConfig.findUnique({
+                where: { storeDomain },
+            });
+            return formatSuccessResponse({
+                success: true,
+                config: {
+                    storeDomain,
+                    tier: currentTier.tier,
+                    tierConfig: currentTier.config,
+                    autoDetected: config?.autoDetected || false,
+                    shopName: config?.shopName || shopName,
+                    shopPlan: config?.shopPlan || shopPlan,
+                    sessionId: getSessionId(),
+                },
+                availableTiers: Object.keys(SHOPIFY_TIER_CONFIGS),
+            });
+        }
+        catch (error) {
+            return formatErrorResponse(error);
+        }
+    });
+    // GET HISTORY
+    server.registerTool("get_history", {
+        title: "Get Operation History",
+        description: "Query past operations for debugging. " +
+            "Filter by tool name, operation type, success/failure, or date range. " +
+            "Returns recent operations with query, response, duration, and errors.",
+        inputSchema: {
+            toolName: z
+                .string()
+                .optional()
+                .describe("Filter by tool name (e.g., 'get_products', 'upload_file')"),
+            operationType: z
+                .enum(["query", "mutation"])
+                .optional()
+                .describe("Filter by operation type"),
+            success: z
+                .boolean()
+                .optional()
+                .describe("Filter by success (true) or failure (false)"),
+            since: z
+                .string()
+                .optional()
+                .describe("ISO date string. Only return operations after this date."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .default(50)
+                .describe("Maximum number of operations to return (1-500). Default: 50"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ toolName, operationType, success, since, limit }) => {
+        try {
+            const operations = await getOperationHistory({
+                storeDomain,
+                toolName,
+                operationType,
+                success,
+                since: since ? new Date(since) : undefined,
+                limit,
+            });
+            return formatSuccessResponse({
+                success: true,
+                count: operations.length,
+                operations,
+            });
+        }
+        catch (error) {
+            return formatErrorResponse(error);
+        }
+    });
+    // GET STATS
+    server.registerTool("get_stats", {
+        title: "Get Usage Statistics",
+        description: "Get aggregated statistics for operations. " +
+            "Includes total calls, success rate, average duration, and breakdown by tool.",
+        inputSchema: {
+            period: z
+                .enum(["day", "week", "month"])
+                .default("day")
+                .describe("Time period for statistics. Default: day"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ period }) => {
+        try {
+            // Calculate since date based on period
+            const since = new Date();
+            switch (period) {
+                case "day":
+                    since.setDate(since.getDate() - 1);
+                    break;
+                case "week":
+                    since.setDate(since.getDate() - 7);
+                    break;
+                case "month":
+                    since.setMonth(since.getMonth() - 1);
+                    break;
+            }
+            const stats = await getOperationStats({
+                storeDomain,
+                since,
+            });
+            return formatSuccessResponse({
+                success: true,
+                period,
+                since: since.toISOString(),
+                stats: {
+                    totalCalls: stats.totalCalls,
+                    successCount: stats.successCount,
+                    errorCount: stats.errorCount,
+                    successRate: stats.totalCalls > 0 ? stats.successCount / stats.totalCalls : 0,
+                    avgDurationMs: Math.round(stats.avgDurationMs),
+                    byTool: stats.byTool,
+                },
+            });
+        }
+        catch (error) {
+            return formatErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=infrastructure.js.map

package/dist/tools/shop.d.ts

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

package/dist/tools/shop.js

@@ -0,0 +1,28 @@
+import { formatSuccessResponse, formatGraphQLErrors, formatErrorResponse, } from "../errors.js";
+import { GET_SHOP } from "../graphql/admin/index.js";
+export function registerShopTools(server, client) {
+    server.registerTool("get_shop_info", {
+        title: "Get Shop Info",
+        description: "Retrieve the store's configuration and settings. Returns store name, email, domain, " +
+            "Shopify plan details, primary domain, currency, weight unit, timezone, and billing address. " +
+            "Use this to verify store connection or get store-wide settings.",
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        try {
+            const response = await client.request(GET_SHOP);
+            if (response.errors) {
+                return formatGraphQLErrors(response);
+            }
+            return formatSuccessResponse(response.data);
+        }
+        catch (error) {
+            return formatErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=shop.js.map

package/dist/tools/smart-bulk.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Smart bulk operation tools
+ * Handles bulk export and import with polling
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AdminApiClient } from "../shopify-client.js";
+export declare function registerSmartBulkTools(server: McpServer, client: AdminApiClient, storeDomain: string): void;