shopify-store-mcp 1.0.0

package/dist/tools/smart-bulk.js

@@ -0,0 +1,286 @@
+/**
+ * Smart bulk operation tools
+ * Handles bulk export and import with polling
+ */
+import { z } from "zod";
+import { formatSuccessResponse, formatGraphQLErrors, formatErrorResponse, formatUserErrors, } from "../errors.js";
+import { BULK_OPERATION_RUN_QUERY, GET_CURRENT_BULK_OPERATION, STAGED_UPLOADS_CREATE, BULK_OPERATION_RUN_MUTATION, } from "../graphql/admin/index.js";
+import { pollUntil } from "../utils/polling.js";
+import { enqueue } from "../queue.js";
+import { logOperation } from "../logger.js";
+// Bulk operation status constants
+const BULK_STATUS = {
+    CREATED: "CREATED",
+    RUNNING: "RUNNING",
+    COMPLETED: "COMPLETED",
+    FAILED: "FAILED",
+    CANCELED: "CANCELED",
+    CANCELING: "CANCELING",
+};
+export function registerSmartBulkTools(server, client, storeDomain) {
+    // BULK EXPORT
+    server.registerTool("bulk_export", {
+        title: "Bulk Export Data",
+        description: "Export large amounts of data from Shopify using bulk operations. " +
+            "This is a SMART tool that: starts the bulk query, polls until complete, returns download URL. " +
+            "Use this for exporting products, orders, customers, etc. in JSONL format. " +
+            "The query should be the inner query WITHOUT the top-level 'query' keyword. " +
+            "Example: { products { edges { node { id title } } } }",
+        inputSchema: {
+            query: z
+                .string()
+                .describe("The GraphQL query to execute. Provide the inner query without 'query' keyword. " +
+                "Example: { products { edges { node { id title handle status } } } }"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ query }) => {
+        const startTime = Date.now();
+        try {
+            // Step 1: Start the bulk query
+            const startResponse = await enqueue(() => client.request(BULK_OPERATION_RUN_QUERY, {
+                variables: { query },
+            }));
+            if (startResponse.errors) {
+                await logOperation({
+                    storeDomain,
+                    toolName: "bulk_export",
+                    query: BULK_OPERATION_RUN_QUERY,
+                    variables: { query },
+                    response: startResponse,
+                    success: false,
+                    errorMessage: "GraphQL errors",
+                    durationMs: Date.now() - startTime,
+                });
+                return formatGraphQLErrors(startResponse);
+            }
+            const startData = startResponse.data;
+            if (startData.bulkOperationRunQuery.userErrors.length > 0) {
+                await logOperation({
+                    storeDomain,
+                    toolName: "bulk_export",
+                    query: BULK_OPERATION_RUN_QUERY,
+                    variables: { query },
+                    response: startResponse,
+                    success: false,
+                    errorMessage: startData.bulkOperationRunQuery.userErrors.map(e => e.message).join(", "),
+                    durationMs: Date.now() - startTime,
+                });
+                return formatUserErrors(startData.bulkOperationRunQuery.userErrors);
+            }
+            const bulkOp = startData.bulkOperationRunQuery.bulkOperation;
+            if (!bulkOp) {
+                return formatErrorResponse("No bulk operation returned");
+            }
+            // Step 2: Poll until complete
+            const result = await pollUntil(async () => {
+                const statusResponse = await enqueue(() => client.request(GET_CURRENT_BULK_OPERATION, {}));
+                if (statusResponse.errors) {
+                    return { done: true, error: "Failed to check bulk operation status" };
+                }
+                const current = statusResponse.data.currentBulkOperation;
+                if (!current || current.id !== bulkOp.id) {
+                    return { done: true, error: "Bulk operation not found or changed" };
+                }
+                if (current.status === BULK_STATUS.COMPLETED) {
+                    return {
+                        done: true,
+                        result: {
+                            id: current.id,
+                            status: "COMPLETED",
+                            url: current.url,
+                            objectCount: current.objectCount,
+                        },
+                    };
+                }
+                if (current.status === BULK_STATUS.FAILED) {
+                    return {
+                        done: true,
+                        error: `Bulk operation failed: ${current.errorCode || "Unknown error"}`,
+                    };
+                }
+                if (current.status === BULK_STATUS.CANCELED) {
+                    return { done: true, error: "Bulk operation was canceled" };
+                }
+                // Still running
+                return { done: false };
+            }, {
+                intervalMs: 5000, // Check every 5 seconds
+                timeoutMs: 300000, // 5 minutes max
+            });
+            await logOperation({
+                storeDomain,
+                toolName: "bulk_export",
+                query: BULK_OPERATION_RUN_QUERY,
+                variables: { query },
+                response: result,
+                success: true,
+                durationMs: Date.now() - startTime,
+            });
+            return formatSuccessResponse({
+                success: true,
+                bulkOperation: result,
+                message: `Bulk export completed. Download URL: ${result.url}`,
+                downloadUrl: result.url,
+            });
+        }
+        catch (error) {
+            await logOperation({
+                storeDomain,
+                toolName: "bulk_export",
+                query: BULK_OPERATION_RUN_QUERY,
+                variables: { query },
+                success: false,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            });
+            return formatErrorResponse(error);
+        }
+    });
+    // BULK IMPORT
+    server.registerTool("bulk_import", {
+        title: "Bulk Import Data",
+        description: "Import large amounts of data to Shopify using bulk mutations. " +
+            "This is a SMART tool that: creates staged upload, uploads JSONL, runs bulk mutation, polls until complete. " +
+            "The mutation should be a single mutation that will run for each line in the JSONL. " +
+            "The JSONL file should have one JSON object per line with the mutation variables.",
+        inputSchema: {
+            mutation: z
+                .string()
+                .describe("The GraphQL mutation to execute per JSONL line. " +
+                "Example: mutation productUpdate($input: ProductInput!) { productUpdate(input: $input) { product { id } userErrors { message } } }"),
+            jsonlContent: z
+                .string()
+                .describe("The JSONL content to import. One JSON object per line with mutation variables. " +
+                "Example: {\"input\": {\"id\": \"gid://shopify/Product/123\", \"title\": \"New Title\"}}"),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ mutation, jsonlContent }) => {
+        const startTime = Date.now();
+        try {
+            // Step 1: Create staged upload
+            const filename = `bulk-import-${Date.now()}.jsonl`;
+            const stagedResponse = await enqueue(() => client.request(STAGED_UPLOADS_CREATE, {
+                variables: {
+                    input: [
+                        {
+                            filename,
+                            mimeType: "text/jsonl",
+                            httpMethod: "POST",
+                            resource: "BULK_MUTATION_VARIABLES",
+                        },
+                    ],
+                },
+            }));
+            if (stagedResponse.errors) {
+                return formatGraphQLErrors(stagedResponse);
+            }
+            const stagedData = stagedResponse.data;
+            if (stagedData.stagedUploadsCreate.userErrors.length > 0) {
+                return formatUserErrors(stagedData.stagedUploadsCreate.userErrors);
+            }
+            const target = stagedData.stagedUploadsCreate.stagedTargets[0];
+            if (!target) {
+                return formatErrorResponse("No staged upload target returned");
+            }
+            // Step 2: Upload JSONL to staged URL
+            const formData = new FormData();
+            for (const param of target.parameters) {
+                formData.append(param.name, param.value);
+            }
+            formData.append("file", new Blob([jsonlContent], { type: "text/jsonl" }), filename);
+            const uploadResponse = await fetch(target.url, {
+                method: "POST",
+                body: formData,
+            });
+            if (!uploadResponse.ok) {
+                return formatErrorResponse(`Failed to upload JSONL: ${uploadResponse.statusText}`);
+            }
+            // Step 3: Run bulk mutation
+            const bulkResponse = await enqueue(() => client.request(BULK_OPERATION_RUN_MUTATION, {
+                variables: {
+                    mutation,
+                    stagedUploadPath: target.resourceUrl,
+                },
+            }));
+            if (bulkResponse.errors) {
+                return formatGraphQLErrors(bulkResponse);
+            }
+            const bulkData = bulkResponse.data;
+            if (bulkData.bulkOperationRunMutation.userErrors.length > 0) {
+                return formatUserErrors(bulkData.bulkOperationRunMutation.userErrors);
+            }
+            const bulkOp = bulkData.bulkOperationRunMutation.bulkOperation;
+            if (!bulkOp) {
+                return formatErrorResponse("No bulk operation returned");
+            }
+            // Step 4: Poll until complete
+            const result = await pollUntil(async () => {
+                const statusResponse = await enqueue(() => client.request(GET_CURRENT_BULK_OPERATION, {}));
+                if (statusResponse.errors) {
+                    return { done: true, error: "Failed to check bulk operation status" };
+                }
+                const current = statusResponse.data.currentBulkOperation;
+                if (!current || current.id !== bulkOp.id) {
+                    return { done: true, error: "Bulk operation not found or changed" };
+                }
+                if (current.status === BULK_STATUS.COMPLETED) {
+                    return {
+                        done: true,
+                        result: {
+                            id: current.id,
+                            status: "COMPLETED",
+                            objectCount: current.objectCount,
+                        },
+                    };
+                }
+                if (current.status === BULK_STATUS.FAILED) {
+                    return {
+                        done: true,
+                        error: `Bulk operation failed: ${current.errorCode || "Unknown error"}`,
+                    };
+                }
+                return { done: false };
+            }, {
+                intervalMs: 5000,
+                timeoutMs: 300000,
+            });
+            await logOperation({
+                storeDomain,
+                toolName: "bulk_import",
+                query: BULK_OPERATION_RUN_MUTATION,
+                variables: { mutation, jsonlLines: jsonlContent.split("\n").length },
+                response: result,
+                success: true,
+                durationMs: Date.now() - startTime,
+            });
+            return formatSuccessResponse({
+                success: true,
+                bulkOperation: result,
+                message: `Bulk import completed. ${result.objectCount} objects processed.`,
+            });
+        }
+        catch (error) {
+            await logOperation({
+                storeDomain,
+                toolName: "bulk_import",
+                query: BULK_OPERATION_RUN_MUTATION,
+                variables: { mutation },
+                success: false,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            });
+            return formatErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=smart-bulk.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Smart file upload tool
+ * Handles the full workflow: create file → poll status → return ready URL
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AdminApiClient } from "../shopify-client.js";
+export declare function registerSmartFileTools(server: McpServer, client: AdminApiClient, storeDomain: string): void;

package/dist/tools/smart-files.js

@@ -0,0 +1,169 @@
+/**
+ * Smart file upload tool
+ * Handles the full workflow: create file → poll status → return ready URL
+ */
+import { z } from "zod";
+import { formatSuccessResponse, formatGraphQLErrors, formatErrorResponse, formatUserErrors, } from "../errors.js";
+import { FILE_CREATE, GET_FILE } from "../graphql/admin/index.js";
+import { pollUntil } from "../utils/polling.js";
+import { enqueue } from "../queue.js";
+import { logOperation } from "../logger.js";
+// File status constants
+const FILE_STATUS = {
+    PROCESSING: "PROCESSING",
+    READY: "READY",
+    FAILED: "FAILED",
+    UPLOADED: "UPLOADED",
+};
+export function registerSmartFileTools(server, client, storeDomain) {
+    server.registerTool("upload_file", {
+        title: "Upload File",
+        description: "Upload a file to Shopify from an external URL. " +
+            "This is a SMART tool that handles the full workflow: " +
+            "creates the file, polls until it's ready, and returns the final CDN URL. " +
+            "Supports images, videos, and generic files. " +
+            "Use this instead of raw fileCreate when you need the final URL immediately.",
+        inputSchema: {
+            url: z
+                .string()
+                .url()
+                .describe("The external URL of the file to upload. Shopify will fetch this."),
+            filename: z
+                .string()
+                .optional()
+                .describe("Optional filename. If not provided, extracted from URL."),
+            alt: z
+                .string()
+                .optional()
+                .describe("Alt text for images. Recommended for accessibility."),
+            contentType: z
+                .enum(["IMAGE", "VIDEO", "FILE"])
+                .optional()
+                .describe("Content type hint. IMAGE for images, VIDEO for videos, FILE for documents/other. " +
+                "If not provided, Shopify will auto-detect."),
+            duplicateResolution: z
+                .enum(["APPEND_UUID", "REPLACE", "RAISE_ERROR"])
+                .default("APPEND_UUID")
+                .describe("How to handle duplicate filenames: " +
+                "APPEND_UUID (default) adds unique suffix, " +
+                "REPLACE overwrites existing, " +
+                "RAISE_ERROR fails if exists."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ url, filename, alt, contentType, duplicateResolution }) => {
+        const startTime = Date.now();
+        try {
+            // Step 1: Create the file
+            const createResponse = await enqueue(() => client.request(FILE_CREATE, {
+                variables: {
+                    files: [
+                        {
+                            originalSource: url,
+                            filename: filename || undefined,
+                            alt: alt || undefined,
+                            contentType: contentType || undefined,
+                            duplicateResolutionMode: duplicateResolution,
+                        },
+                    ],
+                },
+            }));
+            if (createResponse.errors) {
+                await logOperation({
+                    storeDomain,
+                    toolName: "upload_file",
+                    query: FILE_CREATE,
+                    variables: { url, filename, alt, contentType, duplicateResolution },
+                    response: createResponse,
+                    success: false,
+                    errorMessage: "GraphQL errors",
+                    durationMs: Date.now() - startTime,
+                });
+                return formatGraphQLErrors(createResponse);
+            }
+            const createData = createResponse.data;
+            if (createData.fileCreate.userErrors.length > 0) {
+                await logOperation({
+                    storeDomain,
+                    toolName: "upload_file",
+                    query: FILE_CREATE,
+                    variables: { url, filename, alt, contentType, duplicateResolution },
+                    response: createResponse,
+                    success: false,
+                    errorMessage: createData.fileCreate.userErrors.map(e => e.message).join(", "),
+                    durationMs: Date.now() - startTime,
+                });
+                return formatUserErrors(createData.fileCreate.userErrors);
+            }
+            const createdFile = createData.fileCreate.files[0];
+            if (!createdFile) {
+                return formatErrorResponse("No file returned from fileCreate");
+            }
+            // Step 2: Poll until file is ready (or failed)
+            const fileId = createdFile.id;
+            const readyFile = await pollUntil(async () => {
+                const statusResponse = await enqueue(() => client.request(GET_FILE, { variables: { id: fileId } }));
+                if (statusResponse.errors) {
+                    return { done: true, error: "Failed to check file status" };
+                }
+                const node = statusResponse.data.node;
+                if (!node) {
+                    return { done: true, error: "File not found" };
+                }
+                if (node.fileStatus === FILE_STATUS.READY) {
+                    // Extract the final URL based on file type
+                    const finalUrl = node.url || node.image?.url || node.originalSource?.url;
+                    return {
+                        done: true,
+                        result: {
+                            id: fileId,
+                            status: "READY",
+                            url: finalUrl,
+                            ...node,
+                        },
+                    };
+                }
+                if (node.fileStatus === FILE_STATUS.FAILED) {
+                    const errorMsg = node.fileErrors?.map(e => e.message).join(", ") || "File processing failed";
+                    return { done: true, error: errorMsg };
+                }
+                // Still processing
+                return { done: false };
+            }, {
+                intervalMs: 2000,
+                timeoutMs: 60000, // 60 seconds max
+            });
+            await logOperation({
+                storeDomain,
+                toolName: "upload_file",
+                query: FILE_CREATE,
+                variables: { url, filename, alt, contentType, duplicateResolution },
+                response: readyFile,
+                success: true,
+                durationMs: Date.now() - startTime,
+            });
+            return formatSuccessResponse({
+                success: true,
+                file: readyFile,
+                message: `File uploaded successfully. CDN URL: ${readyFile.url}`,
+            });
+        }
+        catch (error) {
+            await logOperation({
+                storeDomain,
+                toolName: "upload_file",
+                query: FILE_CREATE,
+                variables: { url, filename, alt, contentType, duplicateResolution },
+                success: false,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            });
+            return formatErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=smart-files.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Smart metaobject tools
+ * Handles upsert (get or create/update) in one operation
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AdminApiClient } from "../shopify-client.js";
+export declare function registerSmartMetaobjectTools(server: McpServer, client: AdminApiClient, storeDomain: string): void;

package/dist/tools/smart-metaobjects.js

@@ -0,0 +1,186 @@
+/**
+ * Smart metaobject tools
+ * Handles upsert (get or create/update) in one operation
+ */
+import { z } from "zod";
+import { formatSuccessResponse, formatGraphQLErrors, formatErrorResponse, formatUserErrors, } from "../errors.js";
+import { GET_METAOBJECT_BY_HANDLE, METAOBJECT_CREATE, METAOBJECT_UPDATE, } from "../graphql/admin/index.js";
+import { enqueue } from "../queue.js";
+import { logOperation } from "../logger.js";
+export function registerSmartMetaobjectTools(server, client, storeDomain) {
+    server.registerTool("upsert_metaobject", {
+        title: "Upsert Metaobject",
+        description: "Create or update a metaobject by handle (idempotent). " +
+            "This is a SMART tool that: checks if metaobject exists → creates if not → updates if exists. " +
+            "Use this when you want to ensure a metaobject exists with certain data, " +
+            "regardless of whether it already exists. " +
+            "The handle must be unique within the metaobject type.",
+        inputSchema: {
+            type: z
+                .string()
+                .describe("The metaobject type (e.g., 'color_swatch', 'brand', 'faq'). " +
+                "Must match an existing metaobject definition in the store."),
+            handle: z
+                .string()
+                .describe("Unique handle for this metaobject within its type. " +
+                "Used to identify the metaobject for upsert."),
+            fields: z
+                .array(z.object({
+                key: z.string().describe("Field key as defined in the metaobject definition"),
+                value: z.string().describe("Field value (JSON string for complex types)"),
+            }))
+                .describe("Array of field key-value pairs to set on the metaobject"),
+            publishStatus: z
+                .enum(["ACTIVE", "DRAFT"])
+                .default("ACTIVE")
+                .describe("Publish status. ACTIVE makes it visible on storefront if publishable."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true, // Same input = same result
+            openWorldHint: false,
+        },
+    }, async ({ type, handle, fields, publishStatus }) => {
+        const startTime = Date.now();
+        try {
+            // Step 1: Check if metaobject already exists
+            const existingResponse = await enqueue(() => client.request(GET_METAOBJECT_BY_HANDLE, {
+                variables: {
+                    handle: { type, handle },
+                },
+            }));
+            if (existingResponse.errors) {
+                await logOperation({
+                    storeDomain,
+                    toolName: "upsert_metaobject",
+                    query: GET_METAOBJECT_BY_HANDLE,
+                    variables: { type, handle },
+                    response: existingResponse,
+                    success: false,
+                    errorMessage: "GraphQL errors checking existing",
+                    durationMs: Date.now() - startTime,
+                });
+                return formatGraphQLErrors(existingResponse);
+            }
+            const existing = existingResponse.data.metaobjectByHandle;
+            let result;
+            let action;
+            if (existing) {
+                // Step 2a: Update existing metaobject
+                action = "updated";
+                const updateResponse = await enqueue(() => client.request(METAOBJECT_UPDATE, {
+                    variables: {
+                        id: existing.id,
+                        metaobject: {
+                            fields,
+                            capabilities: publishStatus
+                                ? { publishable: { status: publishStatus } }
+                                : undefined,
+                        },
+                    },
+                }));
+                if (updateResponse.errors) {
+                    await logOperation({
+                        storeDomain,
+                        toolName: "upsert_metaobject",
+                        query: METAOBJECT_UPDATE,
+                        variables: { id: existing.id, fields },
+                        response: updateResponse,
+                        success: false,
+                        errorMessage: "GraphQL errors during update",
+                        durationMs: Date.now() - startTime,
+                    });
+                    return formatGraphQLErrors(updateResponse);
+                }
+                const updateData = updateResponse.data;
+                if (updateData.metaobjectUpdate.userErrors.length > 0) {
+                    await logOperation({
+                        storeDomain,
+                        toolName: "upsert_metaobject",
+                        query: METAOBJECT_UPDATE,
+                        variables: { id: existing.id, fields },
+                        response: updateResponse,
+                        success: false,
+                        errorMessage: updateData.metaobjectUpdate.userErrors.map(e => e.message).join(", "),
+                        durationMs: Date.now() - startTime,
+                    });
+                    return formatUserErrors(updateData.metaobjectUpdate.userErrors);
+                }
+                result = updateData.metaobjectUpdate.metaobject;
+            }
+            else {
+                // Step 2b: Create new metaobject
+                action = "created";
+                const createResponse = await enqueue(() => client.request(METAOBJECT_CREATE, {
+                    variables: {
+                        metaobject: {
+                            type,
+                            handle,
+                            fields,
+                            capabilities: publishStatus
+                                ? { publishable: { status: publishStatus } }
+                                : undefined,
+                        },
+                    },
+                }));
+                if (createResponse.errors) {
+                    await logOperation({
+                        storeDomain,
+                        toolName: "upsert_metaobject",
+                        query: METAOBJECT_CREATE,
+                        variables: { type, handle, fields },
+                        response: createResponse,
+                        success: false,
+                        errorMessage: "GraphQL errors during create",
+                        durationMs: Date.now() - startTime,
+                    });
+                    return formatGraphQLErrors(createResponse);
+                }
+                const createData = createResponse.data;
+                if (createData.metaobjectCreate.userErrors.length > 0) {
+                    await logOperation({
+                        storeDomain,
+                        toolName: "upsert_metaobject",
+                        query: METAOBJECT_CREATE,
+                        variables: { type, handle, fields },
+                        response: createResponse,
+                        success: false,
+                        errorMessage: createData.metaobjectCreate.userErrors.map(e => e.message).join(", "),
+                        durationMs: Date.now() - startTime,
+                    });
+                    return formatUserErrors(createData.metaobjectCreate.userErrors);
+                }
+                result = createData.metaobjectCreate.metaobject;
+            }
+            await logOperation({
+                storeDomain,
+                toolName: "upsert_metaobject",
+                query: action === "created" ? METAOBJECT_CREATE : METAOBJECT_UPDATE,
+                variables: { type, handle, fields },
+                response: result,
+                success: true,
+                durationMs: Date.now() - startTime,
+            });
+            return formatSuccessResponse({
+                success: true,
+                action,
+                metaobject: result,
+                message: `Metaobject ${action} successfully.`,
+            });
+        }
+        catch (error) {
+            await logOperation({
+                storeDomain,
+                toolName: "upsert_metaobject",
+                query: "upsert_metaobject",
+                variables: { type, handle, fields },
+                success: false,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            });
+            return formatErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=smart-metaobjects.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * Smart schema discovery tool
+ * Combines metafield definitions and metaobject definitions in one call
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AdminApiClient } from "../shopify-client.js";
+export declare function registerSmartSchemaTools(server: McpServer, client: AdminApiClient, storeDomain: string): void;