@alfe.ai/shopify-mcp 0.2.0

package/README.md

@@ -0,0 +1,16 @@
+# @alfe.ai/shopify-mcp
+
+Shopify MCP server — full store management (products, orders incl. fulfil/refund, customers, inventory) over the Admin GraphQL API with Alfe OAuth credentials.
+
+Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: build, deploy, and run agents with persistent memory, identity, integrations, and channels. See the [documentation](https://docs.alfe.ai) to get started.
+
+## Install
+
+```bash
+npm install @alfe.ai/shopify-mcp
+```
+
+## Links
+
+- 🌐 Website: <https://alfe.ai>
+- 📚 Docs: <https://docs.alfe.ai>

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.js

@@ -0,0 +1,704 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveConfig } from "@alfe.ai/config";
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { z } from "zod";
+//#region src/shopify-client.ts
+/** Error carrying the raw GraphQL error entries so the tool layer can surface them. */
+var ShopifyGraphQLError = class extends Error {
+	errors;
+	constructor(message, errors) {
+		super(message);
+		this.name = "ShopifyGraphQLError";
+		this.errors = errors;
+	}
+};
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var ShopifyClient = class {
+	shopDomain;
+	accessToken;
+	apiVersion;
+	maxRetries;
+	retryBaseMs;
+	sleep;
+	fetchImpl;
+	constructor(config) {
+		this.shopDomain = config.shopDomain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+		this.accessToken = config.accessToken;
+		this.apiVersion = config.apiVersion;
+		this.maxRetries = config.maxRetries ?? 2;
+		this.retryBaseMs = config.retryBaseMs ?? 500;
+		this.sleep = config.sleep ?? defaultSleep;
+		this.fetchImpl = config.fetchImpl ?? fetch;
+	}
+	get endpoint() {
+		return `https://${this.shopDomain}/admin/api/${this.apiVersion}/graphql.json`;
+	}
+	async graphql(query, variables) {
+		let attempt = 0;
+		for (;;) {
+			const res = await this.fetchImpl(this.endpoint, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Accept: "application/json",
+					"X-Shopify-Access-Token": this.accessToken
+				},
+				body: JSON.stringify({
+					query,
+					variables: variables ?? {}
+				})
+			});
+			if (res.status === 429 && attempt < this.maxRetries) {
+				const retryAfter = Number(res.headers.get("Retry-After"));
+				const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : this.retryBaseMs * 2 ** attempt;
+				attempt += 1;
+				await this.sleep(waitMs);
+				continue;
+			}
+			if (!res.ok) {
+				const text = await res.text();
+				throw new Error(`Shopify Admin API HTTP ${String(res.status)} for ${this.shopDomain}: ${text}`);
+			}
+			const body = await res.json();
+			if (body.errors && body.errors.length > 0) {
+				if (body.errors.some((e) => e.extensions?.code === "THROTTLED") && attempt < this.maxRetries) {
+					const waitMs = this.retryBaseMs * 2 ** attempt;
+					attempt += 1;
+					await this.sleep(waitMs);
+					continue;
+				}
+				const messages = body.errors.map((e) => e.message).join("; ");
+				throw new ShopifyGraphQLError(`Shopify GraphQL error for ${this.shopDomain}: ${messages}`, body.errors);
+			}
+			if (body.data === void 0) throw new Error(`Shopify GraphQL response for ${this.shopDomain} had no data`);
+			return body.data;
+		}
+	}
+};
+/**
+* Read a mutation's `userErrors` array out of a typed payload and throw a single
+* descriptive Error if non-empty. Every write tool funnels through this so a
+* failed validation (`userErrors`) fails closed as an `isError` tool result
+* rather than silently returning a null record. `payloadKey` is the mutation's
+* top-level field name (e.g. `productCreate`).
+*/
+function assertNoUserErrors(data, payloadKey) {
+	const userErrors = data[payloadKey]?.userErrors ?? [];
+	if (userErrors.length > 0) {
+		const detail = userErrors.map((e) => e.field?.length ? `${e.field.join(".")}: ${e.message}` : e.message).join("; ");
+		throw new Error(`Shopify ${payloadKey} failed: ${detail}`);
+	}
+}
+//#endregion
+//#region src/shared.ts
+/**
+* Shared `shop` selector field. Every credential-touching tool requires it
+* (Pattern A per-call dispatch) — one Shopify OAuth grant maps to one store,
+* and the store's myshopify domain (`your-store.myshopify.com`) is the stable,
+* human-legible account selector. `McpServer.registerTool` expects a raw Zod
+* shape (`{ field: z.string() }`), NOT a JSON-Schema object.
+*
+* NOTE: the selector is `shop` (the myshopify domain), NOT the connect
+* provider's `accountIdentifier` (which keys on the immutable shop GID). The
+* GraphQL/token requests route on the domain, and it's what the LLM sees from
+* `shopify_list_shops`.
+*/
+const shopField = z.string().describe("The store's myshopify domain (e.g. your-store.myshopify.com) — use a value from shopify_list_shops to pick which connected store this call targets.");
+/** The discovery tool name, referenced in unknown-shop errors and Pattern A exemptions. */
+const LIST_SHOPS_TOOL_NAME = "shopify_list_shops";
+//#endregion
+//#region src/tools.ts
+/**
+* MCP tool registration for the Shopify MCP server (Pattern A multi-store).
+*
+* Every credential-touching tool takes a REQUIRED `shop` selector (the
+* myshopify domain) so the LLM deliberately chooses which connected store a
+* call targets — the server keeps one `ShopifyClient` per store and dispatches
+* per-call. `shopify_list_shops` is the only exempt (discovery) tool.
+*
+* Errors fail closed: a tool that throws (unknown shop, GraphQL `errors`,
+* mutation `userErrors`) returns `{ isError: true }` with the message, never a
+* partial/empty success. Unknown-shop errors name `shopify_list_shops` so the
+* LLM can recover.
+*
+* All operations use the Admin GraphQL API (pinned 2026-07). GraphQL
+* mutation/query names were verified against shopify.dev on 2026-07-20;
+* uncertain ones are flagged inline.
+*/
+const ok = (data) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(data, null, 2)
+}] });
+const fail = (err) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
+	}],
+	isError: true
+});
+/**
+* Register every tool. `resolveClient(shop)` throws an actionable Error for an
+* unknown/dead store; `listShops()` returns the discovery snapshot. Both are
+* injected so the whole surface is testable with a fake client map.
+*/
+function registerTools(server, resolveClient, listShops) {
+	const register = server.registerTool.bind(server);
+	/** Wrap a credential-touching handler so any throw becomes an isError result. */
+	const guarded = (fn) => async (args) => {
+		try {
+			return await fn(resolveClient(args.shop), args);
+		} catch (err) {
+			return fail(err);
+		}
+	};
+	register(LIST_SHOPS_TOOL_NAME, { description: "List the Shopify stores this agent has connected. Returns one entry per store — use the returned shopDomain (e.g. your-store.myshopify.com) as the `shop` selector on every other shopify_* tool." }, () => ok({ shops: listShops() }));
+	register("shopify_list_products", {
+		description: "List products in a connected Shopify store. Supports a search `query` (Shopify search syntax, e.g. \"title:Shirt status:active\") and cursor pagination.",
+		inputSchema: {
+			shop: shopField,
+			first: z.number().int().min(1).max(250).optional().describe("Page size (default 50, max 250)."),
+			after: z.string().optional().describe("Pagination cursor from a previous page's pageInfo.endCursor."),
+			query: z.string().optional().describe("Optional Shopify product search query.")
+		}
+	}, guarded(async (client, args) => {
+		return ok(await client.graphql(`query ListProducts($first: Int!, $after: String, $query: String) {
+          products(first: $first, after: $after, query: $query) {
+            edges {
+              cursor
+              node { id title handle status totalInventory vendor productType createdAt updatedAt }
+            }
+            pageInfo { hasNextPage endCursor }
+          }
+        }`, {
+			first: args.first ?? 50,
+			after: args.after,
+			query: args.query
+		}));
+	}));
+	register("shopify_get_product", {
+		description: "Fetch one product (with its variants) by GID from a connected Shopify store.",
+		inputSchema: {
+			shop: shopField,
+			id: z.string().describe("The product GID, e.g. gid://shopify/Product/1234567890.")
+		}
+	}, guarded(async (client, args) => {
+		return ok(await client.graphql(`query GetProduct($id: ID!) {
+          product(id: $id) {
+            id title handle descriptionHtml status vendor productType tags totalInventory
+            variants(first: 100) {
+              edges { node { id title sku price inventoryQuantity inventoryItem { id } selectedOptions { name value } } }
+            }
+          }
+        }`, { id: args.id }));
+	}));
+	register("shopify_create_product", {
+		description: "Create a product in a connected Shopify store. Uses the productCreate mutation. Pass a `title` (required) plus optional descriptionHtml, vendor, productType, tags, and status (ACTIVE/DRAFT/ARCHIVED).",
+		inputSchema: {
+			shop: shopField,
+			title: z.string().describe("Product title (required)."),
+			descriptionHtml: z.string().optional(),
+			vendor: z.string().optional(),
+			productType: z.string().optional(),
+			tags: z.array(z.string()).optional(),
+			status: z.enum([
+				"ACTIVE",
+				"DRAFT",
+				"ARCHIVED"
+			]).optional().describe("Defaults to ACTIVE in Shopify.")
+		}
+	}, guarded(async (client, args) => {
+		const input = { title: args.title };
+		if (args.descriptionHtml !== void 0) input.descriptionHtml = args.descriptionHtml;
+		if (args.vendor !== void 0) input.vendor = args.vendor;
+		if (args.productType !== void 0) input.productType = args.productType;
+		if (args.tags !== void 0) input.tags = args.tags;
+		if (args.status !== void 0) input.status = args.status;
+		const data = await client.graphql(`mutation CreateProduct($input: ProductInput!) {
+          productCreate(input: $input) {
+            product { id title handle status }
+            userErrors { field message }
+          }
+        }`, { input });
+		assertNoUserErrors(data, "productCreate");
+		return ok(data);
+	}));
+	register("shopify_update_product", {
+		description: "Update fields on an existing product in a connected Shopify store. Uses the productUpdate mutation. Only the supplied fields change.",
+		inputSchema: {
+			shop: shopField,
+			id: z.string().describe("The product GID to update."),
+			title: z.string().optional(),
+			descriptionHtml: z.string().optional(),
+			vendor: z.string().optional(),
+			productType: z.string().optional(),
+			tags: z.array(z.string()).optional(),
+			status: z.enum([
+				"ACTIVE",
+				"DRAFT",
+				"ARCHIVED"
+			]).optional()
+		}
+	}, guarded(async (client, args) => {
+		const input = { id: args.id };
+		if (args.title !== void 0) input.title = args.title;
+		if (args.descriptionHtml !== void 0) input.descriptionHtml = args.descriptionHtml;
+		if (args.vendor !== void 0) input.vendor = args.vendor;
+		if (args.productType !== void 0) input.productType = args.productType;
+		if (args.tags !== void 0) input.tags = args.tags;
+		if (args.status !== void 0) input.status = args.status;
+		const data = await client.graphql(`mutation UpdateProduct($input: ProductInput!) {
+          productUpdate(input: $input) {
+            product { id title handle status }
+            userErrors { field message }
+          }
+        }`, { input });
+		assertNoUserErrors(data, "productUpdate");
+		return ok(data);
+	}));
+	register("shopify_set_variant_price", {
+		description: "Set the price of a single product variant in a connected Shopify store. Uses productVariantsBulkUpdate (the productVariantUpdate mutation was removed; bulk-update is the current single/multi-variant path). Requires the parent product GID.",
+		inputSchema: {
+			shop: shopField,
+			productId: z.string().describe("The parent product GID."),
+			variantId: z.string().describe("The variant GID to reprice."),
+			price: z.string().describe("The new price as a decimal string, e.g. \"19.99\".")
+		}
+	}, guarded(async (client, args) => {
+		const data = await client.graphql(`mutation SetVariantPrice($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
+          productVariantsBulkUpdate(productId: $productId, variants: $variants) {
+            productVariants { id price }
+            userErrors { field message }
+          }
+        }`, {
+			productId: args.productId,
+			variants: [{
+				id: args.variantId,
+				price: args.price
+			}]
+		});
+		assertNoUserErrors(data, "productVariantsBulkUpdate");
+		return ok(data);
+	}));
+	register("shopify_list_orders", {
+		description: "List orders in a connected Shopify store. Supports a Shopify search `query` for status/date filters (e.g. \"financial_status:paid created_at:>2026-01-01 fulfillment_status:unfulfilled\") and cursor pagination.",
+		inputSchema: {
+			shop: shopField,
+			first: z.number().int().min(1).max(250).optional().describe("Page size (default 50, max 250)."),
+			after: z.string().optional().describe("Pagination cursor."),
+			query: z.string().optional().describe("Optional Shopify order search query (status/date filters).")
+		}
+	}, guarded(async (client, args) => {
+		return ok(await client.graphql(`query ListOrders($first: Int!, $after: String, $query: String) {
+          orders(first: $first, after: $after, query: $query, sortKey: CREATED_AT, reverse: true) {
+            edges {
+              cursor
+              node {
+                id name createdAt displayFinancialStatus displayFulfillmentStatus
+                totalPriceSet { shopMoney { amount currencyCode } }
+                customer { id displayName email }
+              }
+            }
+            pageInfo { hasNextPage endCursor }
+          }
+        }`, {
+			first: args.first ?? 50,
+			after: args.after,
+			query: args.query
+		}));
+	}));
+	register("shopify_get_order", {
+		description: "Fetch one order (with line items and fulfillment orders) by GID from a connected Shopify store.",
+		inputSchema: {
+			shop: shopField,
+			id: z.string().describe("The order GID, e.g. gid://shopify/Order/1234567890.")
+		}
+	}, guarded(async (client, args) => {
+		return ok(await client.graphql(`query GetOrder($id: ID!) {
+          order(id: $id) {
+            id name createdAt displayFinancialStatus displayFulfillmentStatus note
+            totalPriceSet { shopMoney { amount currencyCode } }
+            customer { id displayName email }
+            lineItems(first: 100) { edges { node { id title quantity sku variant { id } } } }
+            fulfillmentOrders(first: 20) {
+              edges { node { id status lineItems(first: 100) { edges { node { id remainingQuantity } } } } }
+            }
+          }
+        }`, { id: args.id }));
+	}));
+	register("shopify_fulfill_order", {
+		description: "Fulfill a fulfillment order in a connected Shopify store using the fulfillmentCreate mutation (fulfillmentOrder-based — the legacy order-based fulfillment API is removed). Pass the FULFILLMENT ORDER GID (from shopify_get_order → fulfillmentOrders), not the order GID. Omit line items to fulfill everything.",
+		inputSchema: {
+			shop: shopField,
+			fulfillmentOrderId: z.string().describe("The fulfillment order GID (from order.fulfillmentOrders)."),
+			notifyCustomer: z.boolean().optional().describe("Send the shipping notification (default false)."),
+			trackingNumber: z.string().optional(),
+			trackingUrl: z.string().optional(),
+			trackingCompany: z.string().optional()
+		}
+	}, guarded(async (client, args) => {
+		const fulfillment = {
+			lineItemsByFulfillmentOrder: [{ fulfillmentOrderId: args.fulfillmentOrderId }],
+			notifyCustomer: args.notifyCustomer ?? false
+		};
+		if (args.trackingNumber || args.trackingUrl || args.trackingCompany) {
+			const trackingInfo = {};
+			if (args.trackingNumber !== void 0) trackingInfo.number = args.trackingNumber;
+			if (args.trackingUrl !== void 0) trackingInfo.url = args.trackingUrl;
+			if (args.trackingCompany !== void 0) trackingInfo.company = args.trackingCompany;
+			fulfillment.trackingInfo = trackingInfo;
+		}
+		const data = await client.graphql(`mutation FulfillOrder($fulfillment: FulfillmentInput!) {
+          fulfillmentCreate(fulfillment: $fulfillment) {
+            fulfillment { id status trackingInfo { number url company } }
+            userErrors { field message }
+          }
+        }`, { fulfillment });
+		assertNoUserErrors(data, "fulfillmentCreate");
+		return ok(data);
+	}));
+	register("shopify_refund_order", {
+		description: "Create a refund against an order in a connected Shopify store using the refundCreate mutation. Provide refundLineItems and/or a shipping amount. Without transactions Shopify records the refund without moving money — supply refund line items for a real restock/refund.",
+		inputSchema: {
+			shop: shopField,
+			orderId: z.string().describe("The order GID to refund."),
+			note: z.string().optional(),
+			notify: z.boolean().optional().describe("Notify the customer (default false)."),
+			refundLineItems: z.array(z.object({
+				lineItemId: z.string().describe("The order line item GID to refund."),
+				quantity: z.number().int().min(1),
+				restockType: z.enum([
+					"NO_RESTOCK",
+					"CANCEL",
+					"RETURN",
+					"LEGACY_RESTOCK"
+				]).optional()
+			})).optional().describe("Line items to refund. Omit for a shipping-only or note-only refund.")
+		}
+	}, guarded(async (client, args) => {
+		const input = {
+			orderId: args.orderId,
+			notify: args.notify ?? false
+		};
+		if (args.note !== void 0) input.note = args.note;
+		if (args.refundLineItems?.length) input.refundLineItems = args.refundLineItems.map((li) => {
+			const entry = {
+				lineItemId: li.lineItemId,
+				quantity: li.quantity
+			};
+			if (li.restockType !== void 0) entry.restockType = li.restockType;
+			return entry;
+		});
+		const data = await client.graphql(`mutation RefundOrder($input: RefundInput!) {
+          refundCreate(input: $input) {
+            refund { id totalRefundedSet { shopMoney { amount currencyCode } } }
+            userErrors { field message }
+          }
+        }`, { input });
+		assertNoUserErrors(data, "refundCreate");
+		return ok(data);
+	}));
+	register("shopify_cancel_order", {
+		description: "Cancel an order in a connected Shopify store using the orderCancel mutation (async — returns a job). `reason` and `restock` are required by Shopify.",
+		inputSchema: {
+			shop: shopField,
+			orderId: z.string().describe("The order GID to cancel."),
+			reason: z.enum([
+				"CUSTOMER",
+				"DECLINED",
+				"FRAUD",
+				"INVENTORY",
+				"OTHER",
+				"STAFF"
+			]).describe("OrderCancelReason (required)."),
+			restock: z.boolean().describe("Whether to restock the order's inventory (required)."),
+			refund: z.boolean().optional().describe("Whether to refund the order's payment."),
+			notifyCustomer: z.boolean().optional().describe("Notify the customer (default false)."),
+			staffNote: z.string().optional().describe("Internal note (max 255 chars).")
+		}
+	}, guarded(async (client, args) => {
+		const variables = {
+			orderId: args.orderId,
+			reason: args.reason,
+			restock: args.restock,
+			notifyCustomer: args.notifyCustomer ?? false
+		};
+		if (args.staffNote !== void 0) variables.staffNote = args.staffNote;
+		if (args.refund) variables.refundMethod = { originalPaymentMethodsRefund: { fullRefund: true } };
+		const data = await client.graphql(`mutation CancelOrder(
+          $orderId: ID!, $reason: OrderCancelReason!, $restock: Boolean!,
+          $notifyCustomer: Boolean, $staffNote: String, $refundMethod: OrderCancelRefundMethodInput
+        ) {
+          orderCancel(
+            orderId: $orderId, reason: $reason, restock: $restock,
+            notifyCustomer: $notifyCustomer, staffNote: $staffNote, refundMethod: $refundMethod
+          ) {
+            job { id done }
+            orderCancelUserErrors { field message code }
+          }
+        }`, variables);
+		const errs = data.orderCancel?.orderCancelUserErrors ?? [];
+		if (errs.length > 0) throw new Error(`Shopify orderCancel failed: ${errs.map((e) => e.field?.length ? `${e.field.join(".")}: ${e.message}` : e.message).join("; ")}`);
+		return ok(data);
+	}));
+	register("shopify_list_customers", {
+		description: "List customers in a connected Shopify store. Supports a Shopify search `query` (e.g. \"email:*@example.com\") and cursor pagination.",
+		inputSchema: {
+			shop: shopField,
+			first: z.number().int().min(1).max(250).optional().describe("Page size (default 50, max 250)."),
+			after: z.string().optional(),
+			query: z.string().optional().describe("Optional Shopify customer search query.")
+		}
+	}, guarded(async (client, args) => {
+		return ok(await client.graphql(`query ListCustomers($first: Int!, $after: String, $query: String) {
+          customers(first: $first, after: $after, query: $query) {
+            edges { cursor node { id displayName email phone numberOfOrders createdAt } }
+            pageInfo { hasNextPage endCursor }
+          }
+        }`, {
+			first: args.first ?? 50,
+			after: args.after,
+			query: args.query
+		}));
+	}));
+	register("shopify_get_customer", {
+		description: "Fetch one customer by GID from a connected Shopify store.",
+		inputSchema: {
+			shop: shopField,
+			id: z.string().describe("The customer GID, e.g. gid://shopify/Customer/1234567890.")
+		}
+	}, guarded(async (client, args) => {
+		return ok(await client.graphql(`query GetCustomer($id: ID!) {
+          customer(id: $id) {
+            id displayName firstName lastName email phone note numberOfOrders
+            defaultAddress { address1 address2 city province country zip }
+          }
+        }`, { id: args.id }));
+	}));
+	register("shopify_create_customer", {
+		description: "Create a customer in a connected Shopify store using the customerCreate mutation.",
+		inputSchema: {
+			shop: shopField,
+			firstName: z.string().optional(),
+			lastName: z.string().optional(),
+			email: z.string().optional(),
+			phone: z.string().optional(),
+			note: z.string().optional(),
+			tags: z.array(z.string()).optional()
+		}
+	}, guarded(async (client, args) => {
+		const input = {};
+		if (args.firstName !== void 0) input.firstName = args.firstName;
+		if (args.lastName !== void 0) input.lastName = args.lastName;
+		if (args.email !== void 0) input.email = args.email;
+		if (args.phone !== void 0) input.phone = args.phone;
+		if (args.note !== void 0) input.note = args.note;
+		if (args.tags !== void 0) input.tags = args.tags;
+		const data = await client.graphql(`mutation CreateCustomer($input: CustomerInput!) {
+          customerCreate(input: $input) {
+            customer { id displayName email }
+            userErrors { field message }
+          }
+        }`, { input });
+		assertNoUserErrors(data, "customerCreate");
+		return ok(data);
+	}));
+	register("shopify_update_customer", {
+		description: "Update fields on an existing customer in a connected Shopify store using customerUpdate. Only supplied fields change.",
+		inputSchema: {
+			shop: shopField,
+			id: z.string().describe("The customer GID to update."),
+			firstName: z.string().optional(),
+			lastName: z.string().optional(),
+			email: z.string().optional(),
+			phone: z.string().optional(),
+			note: z.string().optional(),
+			tags: z.array(z.string()).optional()
+		}
+	}, guarded(async (client, args) => {
+		const input = { id: args.id };
+		if (args.firstName !== void 0) input.firstName = args.firstName;
+		if (args.lastName !== void 0) input.lastName = args.lastName;
+		if (args.email !== void 0) input.email = args.email;
+		if (args.phone !== void 0) input.phone = args.phone;
+		if (args.note !== void 0) input.note = args.note;
+		if (args.tags !== void 0) input.tags = args.tags;
+		const data = await client.graphql(`mutation UpdateCustomer($input: CustomerInput!) {
+          customerUpdate(input: $input) {
+            customer { id displayName email }
+            userErrors { field message }
+          }
+        }`, { input });
+		assertNoUserErrors(data, "customerUpdate");
+		return ok(data);
+	}));
+	register("shopify_list_locations", {
+		description: "List the inventory locations of a connected Shopify store (needed to adjust inventory levels).",
+		inputSchema: {
+			shop: shopField,
+			first: z.number().int().min(1).max(250).optional().describe("Page size (default 50).")
+		}
+	}, guarded(async (client, args) => {
+		return ok(await client.graphql(`query ListLocations($first: Int!) {
+          locations(first: $first) {
+            edges { node { id name isActive address { city province country } } }
+          }
+        }`, { first: args.first ?? 50 }));
+	}));
+	register("shopify_get_inventory_levels", {
+		description: "Get the inventory levels (available quantities per location) for an inventory item in a connected Shopify store. Pass the inventoryItem GID (from a product variant's inventoryItem.id).",
+		inputSchema: {
+			shop: shopField,
+			inventoryItemId: z.string().describe("The inventory item GID (variant.inventoryItem.id)."),
+			first: z.number().int().min(1).max(250).optional().describe("Page size (default 50).")
+		}
+	}, guarded(async (client, args) => {
+		return ok(await client.graphql(`query InventoryLevels($id: ID!, $first: Int!) {
+          inventoryItem(id: $id) {
+            id sku tracked
+            inventoryLevels(first: $first) {
+              edges {
+                node {
+                  id location { id name }
+                  quantities(names: ["available"]) { name quantity }
+                }
+              }
+            }
+          }
+        }`, {
+			id: args.inventoryItemId,
+			first: args.first ?? 50
+		}));
+	}));
+	register("shopify_adjust_inventory", {
+		description: "Adjust the available inventory quantity for an inventory item at a location in a connected Shopify store, using inventoryAdjustQuantities. `delta` is the signed change (e.g. -3 to decrement). Requires the inventoryItem GID and the location GID.",
+		inputSchema: {
+			shop: shopField,
+			inventoryItemId: z.string().describe("The inventory item GID."),
+			locationId: z.string().describe("The location GID (from shopify_list_locations)."),
+			delta: z.number().int().describe("Signed quantity change, e.g. 10 or -3."),
+			reason: z.string().optional().describe("Adjustment reason code (default \"correction\").")
+		}
+	}, guarded(async (client, args) => {
+		const data = await client.graphql(`mutation AdjustInventory($input: InventoryAdjustQuantitiesInput!, $key: String!) {
+            inventoryAdjustQuantities(input: $input) @idempotent(key: $key) {
+              inventoryAdjustmentGroup { createdAt reason changes { name delta } }
+              userErrors { field message }
+            }
+          }`, {
+			input: {
+				name: "available",
+				reason: args.reason ?? "correction",
+				changes: [{
+					delta: args.delta,
+					inventoryItemId: args.inventoryItemId,
+					locationId: args.locationId
+				}]
+			},
+			key: globalThis.crypto.randomUUID()
+		});
+		assertNoUserErrors(data, "inventoryAdjustQuantities");
+		return ok(data);
+	}));
+}
+//#endregion
+//#region src/server.ts
+/**
+* Shopify MCP Server (Pattern A multi-store)
+*
+* Custom MCP server implementing Shopify store management directly over the
+* Admin GraphQL API (like the Salesforce server; unlike the Xero proxy that
+* wraps a child MCP). Every tool that touches credentials requires the LLM to
+* pass `shop` (the myshopify domain) explicitly — the server keeps one
+* `ShopifyClient` per connected store and dispatches per-call.
+*
+* Shopify offline access tokens NEVER expire and carry no refresh token, so
+* there is no refresh machinery at all (unlike Salesforce's per-org refresh).
+* An app-uninstall silently invalidates the token; v1 fails closed and the
+* user reconnects from the dashboard.
+*
+* Architecture:
+*   OpenClaw ←(stdio)→ this server ←(https)→ Shopify Admin GraphQL API
+*/
+/**
+* Fallback Admin API version. The connect provider stamps the pinned version
+* (`2026-07`) onto every account via `buildCredentialsResponse`, so this is only
+* used if a legacy Connection row predates that field.
+*/
+const FALLBACK_API_VERSION = "2026-07";
+const clients = /* @__PURE__ */ new Map();
+const shopSnapshot = [];
+function log(msg) {
+	process.stderr.write(`[shopify-mcp-server] ${msg}\n`);
+}
+/**
+* Resolve a `shop` selector to its `ShopifyClient`. Throws if unknown — the LLM
+* should call `shopify_list_shops` to discover the valid set. If the store is
+* connected on the agent but couldn't be initialised, the error tells the LLM
+* to ask the user to reconnect rather than retrying blindly.
+*/
+function resolveClient(shop) {
+	const c = clients.get(shop);
+	if (c) return c;
+	const known = shopSnapshot.find((s) => s.shopDomain === shop);
+	if (known && !known.connected) throw new Error(`Shop ${shop} is connected on this agent but the server could not initialise a client for it (reason: ${known.reason ?? "unknown"}). Ask the user to reconnect this Shopify store from the dashboard.`);
+	throw new Error(`Unknown shop: ${shop}. Call ${LIST_SHOPS_TOOL_NAME} to see the connected Shopify stores on this agent (pass the shopDomain, e.g. your-store.myshopify.com).`);
+}
+async function main() {
+	const config = resolveConfig();
+	const { accounts } = await new AgentApiClient({
+		apiKey: config.apiKey,
+		apiUrl: config.apiUrl
+	}).getShopifyAccounts();
+	if (accounts.length === 0) log(`No Shopify stores connected — server will start with ${LIST_SHOPS_TOOL_NAME} only (returns a "no store connected" hint)`);
+	for (const acct of accounts) {
+		const shopDomain = acct.shopDomain || (acct.accountIdentifier.endsWith(".myshopify.com") ? acct.accountIdentifier : "");
+		if (!acct.accessToken || !shopDomain) {
+			log(`Skipping store ${acct.accountIdentifier} — missing access token or shop domain`);
+			shopSnapshot.push({
+				shopDomain: shopDomain || acct.accountIdentifier,
+				shopName: acct.shopName || acct.displayName,
+				shopGid: acct.shopGid || null,
+				connectedAt: acct.connectedAt,
+				connected: false,
+				reason: "missing_access_token_or_shop_domain"
+			});
+			continue;
+		}
+		if (clients.has(shopDomain)) {
+			log(`Duplicate shop ${shopDomain} returned by getShopifyAccounts() — keeping the first cached client`);
+			continue;
+		}
+		clients.set(shopDomain, new ShopifyClient({
+			accessToken: acct.accessToken,
+			shopDomain,
+			apiVersion: acct.apiVersion || FALLBACK_API_VERSION
+		}));
+		shopSnapshot.push({
+			shopDomain,
+			shopName: acct.shopName || acct.displayName,
+			shopGid: acct.shopGid || null,
+			connectedAt: acct.connectedAt,
+			connected: true
+		});
+		log(`Cached client for store ${shopDomain} (${acct.shopName || acct.displayName || "no name"})`);
+	}
+	const server = new McpServer({
+		name: "shopify-mcp-server",
+		version: "0.1.0"
+	});
+	registerTools(server, resolveClient, () => shopSnapshot);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	log(`Shopify MCP server running with ${String(clients.size)} connected store(s) and Pattern A selector enforcement`);
+}
+for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => {
+	process.exit(0);
+});
+main().catch((err) => {
+	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@alfe.ai/shopify-mcp",
+  "version": "0.2.0",
+  "description": "Shopify MCP server — full store management (products, orders incl. fulfil/refund, customers, inventory) over the Admin GraphQL API with Alfe OAuth credentials",
+  "type": "module",
+  "main": "./dist/server.js",
+  "bin": {
+    "shopify-mcp-server": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.5",
+    "@alfe.ai/config": "0.3.0",
+    "@alfe.ai/agent-api-client": "0.12.0"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://alfe.ai",
+  "author": "Alfe (https://alfe.ai)",
+  "keywords": [
+    "alfe",
+    "ai-agents",
+    "agent",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "shopify",
+    "ecommerce"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}