shopify-store-mcp 1.0.0

package/dist/tools/smart-schema.js

@@ -0,0 +1,138 @@
+/**
+ * Smart schema discovery tool
+ * Combines metafield definitions and metaobject definitions in one call
+ */
+import { z } from "zod";
+import { formatSuccessResponse, formatGraphQLErrors, formatErrorResponse, } from "../errors.js";
+import { GET_METAFIELD_DEFINITIONS, GET_METAOBJECT_DEFINITIONS, } from "../graphql/admin/index.js";
+import { enqueue } from "../queue.js";
+import { logOperation } from "../logger.js";
+// Valid metafield owner types
+const METAFIELD_OWNER_TYPES = [
+    "PRODUCT",
+    "PRODUCTVARIANT",
+    "COLLECTION",
+    "CUSTOMER",
+    "ORDER",
+    "DRAFTORDER",
+    "SHOP",
+    "COMPANY",
+    "LOCATION",
+    "MARKET",
+    "PAGE",
+    "BLOG",
+    "ARTICLE",
+    "DISCOUNT",
+];
+export function registerSmartSchemaTools(server, client, storeDomain) {
+    server.registerTool("schema_discover", {
+        title: "Discover Store Schema",
+        description: "Discover custom schema in the store: metafield definitions and metaobject types. " +
+            "This is a SMART tool that combines multiple discovery queries in one call. " +
+            "Use this to understand what custom fields and data types are available in the store " +
+            "before working with metafields or metaobjects.",
+        inputSchema: {
+            includeMetafields: z
+                .boolean()
+                .default(true)
+                .describe("Include metafield definitions in the response"),
+            includeMetaobjects: z
+                .boolean()
+                .default(true)
+                .describe("Include metaobject definitions in the response"),
+            metafieldOwnerTypes: z
+                .array(z.enum(METAFIELD_OWNER_TYPES))
+                .optional()
+                .describe("Filter metafield definitions by owner type(s). " +
+                "If not provided, fetches definitions for PRODUCT, CUSTOMER, ORDER, and SHOP."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ includeMetafields, includeMetaobjects, metafieldOwnerTypes }) => {
+        const startTime = Date.now();
+        try {
+            const result = {};
+            // Fetch metafield definitions
+            if (includeMetafields) {
+                const ownerTypes = metafieldOwnerTypes || ["PRODUCT", "CUSTOMER", "ORDER", "SHOP"];
+                const metafieldDefs = {};
+                for (const ownerType of ownerTypes) {
+                    const response = await enqueue(() => client.request(GET_METAFIELD_DEFINITIONS, {
+                        variables: {
+                            ownerType,
+                            first: 100,
+                        },
+                    }));
+                    if (response.errors) {
+                        console.error(`[schema_discover] Error fetching metafield definitions for ${ownerType}:`, response.errors);
+                        continue;
+                    }
+                    const data = response.data;
+                    metafieldDefs[ownerType] = data.metafieldDefinitions.edges.map((edge) => edge.node);
+                }
+                result.metafieldDefinitions = metafieldDefs;
+            }
+            // Fetch metaobject definitions
+            if (includeMetaobjects) {
+                const response = await enqueue(() => client.request(GET_METAOBJECT_DEFINITIONS, {
+                    variables: { first: 100 },
+                }));
+                if (response.errors) {
+                    await logOperation({
+                        storeDomain,
+                        toolName: "schema_discover",
+                        query: GET_METAOBJECT_DEFINITIONS,
+                        variables: {},
+                        response,
+                        success: false,
+                        errorMessage: "GraphQL errors fetching metaobject definitions",
+                        durationMs: Date.now() - startTime,
+                    });
+                    return formatGraphQLErrors(response);
+                }
+                const data = response.data;
+                result.metaobjectDefinitions = data.metaobjectDefinitions.edges.map((edge) => edge.node);
+            }
+            // Build summary
+            const summary = [];
+            if (result.metafieldDefinitions) {
+                const totalDefs = Object.values(result.metafieldDefinitions).reduce((sum, defs) => sum + defs.length, 0);
+                summary.push(`${totalDefs} metafield definitions across ${Object.keys(result.metafieldDefinitions).length} owner types`);
+            }
+            if (result.metaobjectDefinitions) {
+                summary.push(`${result.metaobjectDefinitions.length} metaobject types`);
+            }
+            await logOperation({
+                storeDomain,
+                toolName: "schema_discover",
+                query: "schema_discover",
+                variables: { includeMetafields, includeMetaobjects, metafieldOwnerTypes },
+                response: { summary },
+                success: true,
+                durationMs: Date.now() - startTime,
+            });
+            return formatSuccessResponse({
+                success: true,
+                summary: summary.join(", "),
+                ...result,
+            });
+        }
+        catch (error) {
+            await logOperation({
+                storeDomain,
+                toolName: "schema_discover",
+                query: "schema_discover",
+                variables: { includeMetafields, includeMetaobjects, metafieldOwnerTypes },
+                success: false,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            });
+            return formatErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=smart-schema.js.map

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+export interface ToolResponse {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export interface PageInfo {
+    hasNextPage: boolean;
+    endCursor: string | null;
+}
+export interface MoneyV2 {
+    amount: string;
+    currencyCode: string;
+}
+export interface UserError {
+    field: string[];
+    message: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/polling.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Polling utility for async Shopify operations
+ * Used by smart tools to wait for bulk operations, file uploads, etc.
+ */
+export interface PollResult<T> {
+    done: boolean;
+    result?: T;
+    error?: string;
+}
+export interface PollOptions {
+    /** Time between checks in milliseconds */
+    intervalMs: number;
+    /** Maximum time to wait in milliseconds */
+    timeoutMs: number;
+    /** Optional callback on each poll iteration */
+    onPoll?: (elapsed: number) => void;
+}
+/**
+ * Poll until a condition is met or timeout
+ *
+ * @param checkFn Function that checks the condition and returns result
+ * @param options Polling configuration
+ * @returns The result when done
+ * @throws Error if timeout or error returned from checkFn
+ *
+ * @example
+ * const result = await pollUntil(
+ *   async () => {
+ *     const file = await getFile(id);
+ *     if (file.status === 'READY') return { done: true, result: file };
+ *     if (file.status === 'FAILED') return { done: true, error: 'Upload failed' };
+ *     return { done: false };
+ *   },
+ *   { intervalMs: 2000, timeoutMs: 30000 }
+ * );
+ */
+export declare function pollUntil<T>(checkFn: () => Promise<PollResult<T>>, options: PollOptions): Promise<T>;
+/**
+ * Sleep for a specified duration
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn Function to retry
+ * @param options Retry configuration
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, options: {
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    shouldRetry?: (error: unknown) => boolean;
+}): Promise<T>;

package/dist/utils/polling.js

@@ -0,0 +1,77 @@
+/**
+ * Polling utility for async Shopify operations
+ * Used by smart tools to wait for bulk operations, file uploads, etc.
+ */
+/**
+ * Poll until a condition is met or timeout
+ *
+ * @param checkFn Function that checks the condition and returns result
+ * @param options Polling configuration
+ * @returns The result when done
+ * @throws Error if timeout or error returned from checkFn
+ *
+ * @example
+ * const result = await pollUntil(
+ *   async () => {
+ *     const file = await getFile(id);
+ *     if (file.status === 'READY') return { done: true, result: file };
+ *     if (file.status === 'FAILED') return { done: true, error: 'Upload failed' };
+ *     return { done: false };
+ *   },
+ *   { intervalMs: 2000, timeoutMs: 30000 }
+ * );
+ */
+export async function pollUntil(checkFn, options) {
+    const start = Date.now();
+    while (Date.now() - start < options.timeoutMs) {
+        const { done, result, error } = await checkFn();
+        if (error) {
+            throw new Error(error);
+        }
+        if (done) {
+            return result;
+        }
+        // Call optional progress callback
+        if (options.onPoll) {
+            options.onPoll(Date.now() - start);
+        }
+        // Wait before next check
+        await sleep(options.intervalMs);
+    }
+    throw new Error(`Polling timeout after ${options.timeoutMs}ms`);
+}
+/**
+ * Sleep for a specified duration
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn Function to retry
+ * @param options Retry configuration
+ */
+export async function retryWithBackoff(fn, options) {
+    let lastError;
+    let delay = options.initialDelayMs;
+    for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Check if we should retry this error
+            if (options.shouldRetry && !options.shouldRetry(error)) {
+                throw error;
+            }
+            // Don't sleep after the last attempt
+            if (attempt < options.maxRetries) {
+                await sleep(delay);
+                delay = Math.min(delay * 2, options.maxDelayMs);
+            }
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=polling.js.map

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "shopify-store-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Shopify store operations via Admin and Storefront APIs",
+  "author": "Brahim Benzarti",
+  "license": "ISC",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "shopify-store-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "prisma/schema.prisma",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "shopify",
+    "admin-api",
+    "graphql",
+    "ai",
+    "claude",
+    "cursor"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ibrahimbenzarti/shopify-store-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ibrahimbenzarti/shopify-store-mcp/issues"
+  },
+  "homepage": "https://github.com/ibrahimbenzarti/shopify-store-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "prisma generate && tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "inspect": "npm run build && npx @modelcontextprotocol/inspector dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "graphql-codegen": "graphql-codegen -p=adminApi && graphql-codegen -p=storefrontApi",
+    "graphql-codegen:admin": "graphql-codegen -p=adminApi",
+    "graphql-codegen:storefront": "graphql-codegen -p=storefrontApi",
+    "graphql-codegen:watch": "graphql-codegen --watch",
+    "db:generate": "prisma generate",
+    "db:push": "prisma db push",
+    "db:studio": "prisma studio",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "@prisma/client": "^6.3.0",
+    "@shopify/admin-api-client": "^1.1.0",
+    "@shopify/storefront-api-client": "^1.0.0",
+    "dotenv": "^16.4.5",
+    "p-queue": "^8.0.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@graphql-codegen/cli": "^5.0.0",
+    "@shopify/api-codegen-preset": "^1.1.1",
+    "@types/node": "^22.0.0",
+    "graphql": "^16.9.0",
+    "graphql-config": "^5.1.0",
+    "prisma": "^6.3.0",
+    "typescript": "^5.6.0"
+  },
+  "resolutions": {
+    "@graphql-tools/url-loader": "8.0.16",
+    "@graphql-codegen/client-preset": "4.7.0",
+    "@graphql-codegen/typescript-operations": "4.5.0"
+  },
+  "overrides": {
+    "@graphql-tools/url-loader": "8.0.16",
+    "@graphql-codegen/client-preset": "4.7.0",
+    "@graphql-codegen/typescript-operations": "4.5.0"
+  }
+}

package/prisma/schema.prisma

@@ -0,0 +1,82 @@
+// Shopify Store MCP - Prisma Schema
+// SQLite database for operation logging, configuration, and background jobs
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+
+// ============================================================================
+// STORE CONFIGURATION
+// ============================================================================
+
+// Store configuration per shop (rate limit tier, settings)
+model StoreConfig {
+  id           String   @id @default(uuid())
+  storeDomain  String   @unique
+  tier         String   @default("STANDARD") // STANDARD, ADVANCED, PLUS, ENTERPRISE
+  autoDetected Boolean  @default(false)
+  shopName     String?
+  shopPlan     String?
+  createdAt    DateTime @default(now())
+  updatedAt    DateTime @updatedAt
+}
+
+// ============================================================================
+// OPERATION LOGGING
+// ============================================================================
+
+// Logs every GraphQL operation for debugging and history
+model OperationLog {
+  id            String   @id @default(uuid())
+  storeDomain   String
+  sessionId     String   // MCP session identifier
+  toolName      String   // Tool that was called
+  operationType String   // "query" | "mutation"
+  query         String   // GraphQL query (may be truncated)
+  variables     String?  // JSON string of variables
+  response      String?  // JSON string of response (may be truncated)
+  success       Boolean
+  errorMessage  String?
+  durationMs    Int
+  createdAt     DateTime @default(now())
+
+  @@index([storeDomain])
+  @@index([storeDomain, createdAt])
+  @@index([toolName])
+  @@index([sessionId])
+  @@index([createdAt])
+}
+
+// ============================================================================
+// BACKGROUND JOBS
+// ============================================================================
+
+// Tracks long-running async operations (bulk export/import, file uploads)
+model BackgroundJob {
+  id               String   @id @default(uuid())
+  storeDomain      String
+  sessionId        String   // MCP session that started the job
+  bulkOperationId  String?  // Shopify bulk operation GID if applicable
+  type             String   // BULK_EXPORT, BULK_IMPORT, FILE_UPLOAD
+  name             String   // Human-readable job name
+  status           String   @default("PENDING") // PENDING, RUNNING, COMPLETED, FAILED, CANCELLED
+  progress         Float    @default(0) // Progress percentage (0-100)
+  total            Int      @default(0) // Total items to process
+  processed        Int      @default(0) // Items processed so far
+  data             String?  // JSON - additional job metadata
+  result           String?  // JSON - job results
+  error            String?  // Error message if failed
+  createdAt        DateTime @default(now())
+  updatedAt        DateTime @updatedAt
+
+  @@index([storeDomain])
+  @@index([storeDomain, status])
+  @@index([bulkOperationId])
+  @@index([status])
+  @@index([sessionId])
+}