@alfe.ai/shopify-mcp 0.2.2 → 0.2.3

package/README.md

@@ -10,6 +10,26 @@ Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: buil
 npm install @alfe.ai/shopify-mcp
 ```
 
+## Safety model
+
+Every store operation requires the canonical `your-store.myshopify.com` domain
+shown by `shopify_list_shops`; custom hosts and URL paths are rejected before a
+Shopify access token is sent. GraphQL requests have bounded input, deadline,
+retry, and response limits, and redirects are disabled.
+
+Commerce-critical mutations require exact confirmation values in addition to
+their target arguments:
+
+- price updates confirm the variant ID and price;
+- fulfillment confirms the fulfillment-order ID;
+- refunds and cancellations confirm the order ID; and
+- inventory adjustments confirm the inventory item, location, and signed
+  quantity delta.
+
+These confirmations are designed to bind an approval to the action's actual
+consequence. Large reads must be narrowed or paginated rather than returned as
+one unbounded MCP result.
+
 ## Links
 
 - 🌐 Website: <https://alfe.ai>

package/dist/server.js

@@ -1,11 +1,84 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 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/validation.ts
+const MAX_GRAPHQL_QUERY_CHARS = 1e5;
+const MAX_GRAPHQL_REQUEST_BYTES = 1024 * 1024;
+const MAX_TOOL_TEXT_CHARS = 1e5;
+const SHOP_DOMAIN_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.myshopify\.com$/u;
+const SHOPIFY_GID_PATTERN = /^gid:\/\/shopify\/([A-Za-z][A-Za-z0-9]*)\/([A-Za-z0-9]+)$/u;
+const MONEY_PATTERN = /^(?:0|[1-9]\d{0,12})(?:\.\d{1,2})?$/u;
+const MAX_JSON_DEPTH = 8;
+const MAX_JSON_NODES = 1e4;
+const MAX_JSON_ARRAY_ITEMS = 1e3;
+const MAX_JSON_STRING_CHARS = 1e5;
+const UNSAFE_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function validateShopDomain(value) {
+	if (typeof value !== "string") throw new Error("shop must be a string");
+	const normalized = value.trim().toLowerCase();
+	if (!SHOP_DOMAIN_PATTERN.test(normalized)) throw new Error("shop must be a canonical your-store.myshopify.com domain");
+	return normalized;
+}
+function validateShopifyApiVersion(value) {
+	if (typeof value !== "string" || !/^\d{4}-(?:01|04|07|10)$/u.test(value)) throw new Error("Shopify API version must use a quarterly YYYY-MM value");
+	return value;
+}
+function validateVariables(value) {
+	if (value === void 0) return Object.create(null);
+	if (!isRecord(value)) throw new Error("GraphQL variables must be an object");
+	const result = cloneRecord(value, 0, { nodes: 0 });
+	const encoded = JSON.stringify(result);
+	if (Buffer.byteLength(encoded, "utf-8") > 1048576) throw new Error(`GraphQL variables exceed the ${String(MAX_GRAPHQL_REQUEST_BYTES)} byte limit`);
+	return result;
+}
+function cloneJson(value, depth, budget) {
+	budget.nodes += 1;
+	if (budget.nodes > MAX_JSON_NODES) throw new Error("GraphQL variables contain too many values");
+	if (depth > MAX_JSON_DEPTH) throw new Error("GraphQL variables exceed the JSON depth limit");
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error("GraphQL variables contain a non-finite number");
+		return value;
+	}
+	if (typeof value === "string") {
+		if (value.length > MAX_JSON_STRING_CHARS) throw new Error("GraphQL variables contain an oversized string");
+		return value;
+	}
+	if (Array.isArray(value)) {
+		if (value.length > MAX_JSON_ARRAY_ITEMS) throw new Error("GraphQL variables contain an oversized array");
+		return value.map((item) => cloneJson(item, depth + 1, budget));
+	}
+	if (!isRecord(value)) throw new Error("GraphQL variables must contain JSON-only values");
+	return cloneRecord(value, depth, budget);
+}
+function cloneRecord(value, depth, budget) {
+	const result = Object.create(null);
+	for (const [key, nested] of Object.entries(value)) {
+		if (key.length < 1 || key.length > 256 || UNSAFE_KEYS.has(key)) throw new Error("GraphQL variables contain an unsafe key");
+		result[key] = cloneJson(nested, depth + 1, budget);
+	}
+	return result;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/shopify-client.ts
-/** Error carrying the raw GraphQL error entries so the tool layer can surface them. */
+/** Bounded Shopify Admin GraphQL client for one canonical myshopify domain. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+const MAX_ERROR_RESPONSE_BYTES = 64 * 1024;
+const MAX_ACCESS_TOKEN_LENGTH = 16384;
+const MAX_RETRIES = 5;
+const MAX_RETRY_DELAY_MS = 3e4;
 var ShopifyGraphQLError = class extends Error {
 	errors;
 	constructor(message, errors) {
@@ -14,7 +87,9 @@ var ShopifyGraphQLError = class extends Error {
 		this.errors = errors;
 	}
 };
-const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const defaultSleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms).unref();
+});
 var ShopifyClient = class {
 	shopDomain;
 	accessToken;
@@ -23,90 +98,185 @@ var ShopifyClient = class {
 	retryBaseMs;
 	sleep;
 	fetchImpl;
+	requestTimeoutMs;
 	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.shopDomain = validateShopDomain(config.shopDomain);
+		this.accessToken = validateAccessToken(config.accessToken);
+		this.apiVersion = validateShopifyApiVersion(config.apiVersion);
+		this.maxRetries = boundedInteger("maxRetries", config.maxRetries ?? 2, 0, MAX_RETRIES);
+		this.retryBaseMs = boundedInteger("retryBaseMs", config.retryBaseMs ?? 500, 1, MAX_RETRY_DELAY_MS);
 		this.sleep = config.sleep ?? defaultSleep;
 		this.fetchImpl = config.fetchImpl ?? fetch;
+		this.requestTimeoutMs = boundedInteger("requestTimeoutMs", config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, 1e3, 12e4);
 	}
 	get endpoint() {
 		return `https://${this.shopDomain}/admin/api/${this.apiVersion}/graphql.json`;
 	}
 	async graphql(query, variables) {
+		if (typeof query !== "string" || query.trim().length < 1 || query.length > 1e5) throw new Error(`GraphQL query must contain 1 to ${String(MAX_GRAPHQL_QUERY_CHARS)} characters`);
+		const requestBody = encodeRequestBody(query, validateVariables(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;
+			const response = await this.request(requestBody);
+			if (response.status === 429 && attempt < this.maxRetries) {
+				await cancelBody(response);
+				const waitMs = retryDelay(response.headers.get("Retry-After"), this.retryBaseMs, 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}`);
+			if (!response.ok) {
+				await readResponseText(response, MAX_ERROR_RESPONSE_BYTES);
+				throw new Error(`Shopify Admin API HTTP ${String(response.status)} request failed`);
 			}
-			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;
+			const parsed = parseGraphQLResponse(await readResponseText(response, MAX_RESPONSE_BYTES));
+			if (parsed.errors.length > 0) {
+				if (parsed.errors.some((error) => error.extensions?.code === "THROTTLED") && attempt < this.maxRetries) {
+					const waitMs = retryDelay(null, this.retryBaseMs, 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);
+				throw new ShopifyGraphQLError(`Shopify GraphQL request failed: ${parsed.errors.map((error) => error.message).join("; ")}`, parsed.errors);
 			}
-			if (body.data === void 0) throw new Error(`Shopify GraphQL response for ${this.shopDomain} had no data`);
-			return body.data;
+			if (parsed.data === void 0) throw new Error("Shopify GraphQL response had no data");
+			return parsed.data;
+		}
+	}
+	async request(body) {
+		try {
+			return await this.fetchImpl(this.endpoint, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Accept: "application/json",
+					"X-Shopify-Access-Token": this.accessToken
+				},
+				body,
+				redirect: "error",
+				signal: AbortSignal.timeout(this.requestTimeoutMs)
+			});
+		} catch (error) {
+			throw new Error("Shopify Admin API request failed", { cause: error });
 		}
 	}
 };
-/**
-* 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}`);
+function assertNoUserErrors(data, payloadKey, errorKey = "userErrors") {
+	if (!isRecord(data) || !isRecord(data[payloadKey])) throw new Error(`Shopify ${payloadKey} response was malformed`);
+	const rawErrors = data[payloadKey][errorKey];
+	if (!Array.isArray(rawErrors) || rawErrors.length > 100) throw new Error(`Shopify ${payloadKey} response had malformed ${errorKey}`);
+	const details = rawErrors.map((rawError) => {
+		if (!isRecord(rawError) || typeof rawError.message !== "string") throw new Error(`Shopify ${payloadKey} response had malformed ${errorKey}`);
+		const message = rawError.message.slice(0, 1024);
+		if (rawError.field === null || rawError.field === void 0) return message;
+		if (!Array.isArray(rawError.field) || rawError.field.length > 32 || !rawError.field.every((field) => typeof field === "string" && field.length <= 128)) throw new Error(`Shopify ${payloadKey} response had malformed ${errorKey}`);
+		return rawError.field.length > 0 ? `${rawError.field.join(".")}: ${message}` : message;
+	});
+	if (details.length > 0) throw new Error(`Shopify ${payloadKey} failed: ${details.join("; ")}`);
+}
+function validateAccessToken(value) {
+	if (typeof value !== "string" || value.length < 1 || value.length > MAX_ACCESS_TOKEN_LENGTH || value !== value.trim() || /[\r\n]/u.test(value)) throw new Error("Shopify access token is invalid");
+	return value;
+}
+function boundedInteger(label, value, min, max) {
+	if (!Number.isInteger(value) || value < min || value > max) throw new Error(`${label} must be an integer from ${String(min)} to ${String(max)}`);
+	return value;
+}
+function encodeRequestBody(query, variables) {
+	const body = JSON.stringify({
+		query,
+		variables
+	});
+	if (Buffer.byteLength(body, "utf-8") > 1048576) throw new Error(`GraphQL request exceeds the ${String(MAX_GRAPHQL_REQUEST_BYTES)} byte limit`);
+	return body;
+}
+function retryDelay(retryAfter, baseMs, attempt) {
+	const seconds = retryAfter === null ? NaN : Number(retryAfter);
+	const requested = Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : baseMs * 2 ** attempt;
+	return Math.min(Math.max(1, Math.round(requested)), MAX_RETRY_DELAY_MS);
+}
+async function cancelBody(response) {
+	try {
+		await response.body?.cancel("retrying throttled request");
+	} catch {}
+}
+async function readResponseText(response, maxBytes) {
+	const declaredLength = response.headers.get("content-length");
+	if (declaredLength !== null) {
+		const length = Number(declaredLength);
+		if (!Number.isSafeInteger(length) || length < 0 || length > maxBytes) throw new Error(`Shopify response exceeds ${String(maxBytes)} bytes`);
 	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) break;
+			if (chunk.value === void 0) throw new Error("Shopify response stream returned an invalid chunk");
+			total += chunk.value.byteLength;
+			if (total > maxBytes) {
+				await reader.cancel("response exceeds limit");
+				throw new Error(`Shopify response exceeds ${String(maxBytes)} bytes`);
+			}
+			chunks.push(chunk.value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total).toString("utf-8");
+}
+function parseGraphQLResponse(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new Error("Shopify GraphQL response was not valid JSON", { cause: error });
+	}
+	if (!isRecord(parsed)) throw new Error("Shopify GraphQL response was malformed");
+	const errors = normalizeGraphQLErrors(parsed.errors);
+	return {
+		data: parsed.data,
+		errors
+	};
+}
+function normalizeGraphQLErrors(value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || value.length > 100) throw new Error("Shopify GraphQL errors were malformed");
+	return value.map((entry) => {
+		if (!isRecord(entry) || typeof entry.message !== "string") throw new Error("Shopify GraphQL errors were malformed");
+		let extensions;
+		if (entry.extensions !== void 0) {
+			if (!isRecord(entry.extensions)) throw new Error("Shopify GraphQL errors were malformed");
+			if (entry.extensions.code !== void 0 && typeof entry.extensions.code !== "string") throw new Error("Shopify GraphQL errors were malformed");
+			extensions = entry.extensions.code === void 0 ? {} : { code: entry.extensions.code.slice(0, 128) };
+		}
+		return {
+			message: entry.message.slice(0, 1024),
+			...extensions ? { extensions } : {}
+		};
+	});
 }
 //#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 shopField = z.coerce.string().trim().toLowerCase().regex(SHOP_DOMAIN_PATTERN, "Expected a canonical your-store.myshopify.com domain").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.");
+const pageSizeField = z.coerce.number().int().min(1).max(250).optional();
+const cursorField = z.coerce.string().trim().min(1).max(4096).optional();
+const searchField = z.coerce.string().trim().min(1).max(1e4).optional();
+const boundedText = (maxChars = MAX_TOOL_TEXT_CHARS) => z.coerce.string().min(1).max(maxChars);
+const optionalText = (maxChars = MAX_TOOL_TEXT_CHARS) => boundedText(maxChars).optional();
+const tagsField = z.array(boundedText(255)).max(250).optional();
+const shopifyGidField = (resource) => z.coerce.string().trim().max(256).regex(SHOPIFY_GID_PATTERN).refine((value) => SHOPIFY_GID_PATTERN.exec(value)?.[1] === resource, { message: `Expected a gid://shopify/${resource}/... identifier` });
+const moneyField = z.coerce.string().trim().regex(MONEY_PATTERN, "Expected a non-negative decimal with at most two fractional digits");
+const safeHttpsUrlField = z.coerce.string().trim().max(2048).refine((value) => {
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" && !url.username && !url.password;
+	} catch {
+		return false;
+	}
+}, "Expected an HTTPS URL without embedded credentials");
 const LIST_SHOPS_TOOL_NAME = "shopify_list_shops";
 //#endregion
 //#region src/tools.ts
@@ -127,14 +297,19 @@ const LIST_SHOPS_TOOL_NAME = "shopify_list_shops";
 * 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 MAX_TOOL_RESULT_BYTES = 5 * 1024 * 1024;
+const ok = (data) => {
+	const text = JSON.stringify(data, null, 2);
+	if (Buffer.byteLength(text, "utf-8") > MAX_TOOL_RESULT_BYTES) throw new Error(`Shopify tool result exceeds ${String(MAX_TOOL_RESULT_BYTES)} bytes`);
+	return { content: [{
+		type: "text",
+		text
+	}] };
+};
 const fail = (err) => ({
 	content: [{
 		type: "text",
-		text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
+		text: JSON.stringify({ error: (err instanceof Error ? err.message : String(err)).slice(0, 4096) })
 	}],
 	isError: true
 });
@@ -153,14 +328,24 @@ function registerTools(server, resolveClient, listShops) {
 			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(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.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, () => 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.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			shop: shopField,
-			first: z.coerce.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.")
+			first: pageSizeField.describe("Page size (default 50, max 250)."),
+			after: cursorField.describe("Pagination cursor from a previous page's pageInfo.endCursor."),
+			query: searchField.describe("Optional Shopify product search query.")
 		}
 	}, guarded(async (client, args) => {
 		return ok(await client.graphql(`query ListProducts($first: Int!, $after: String, $query: String) {
@@ -179,9 +364,13 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	register("shopify_get_product", {
 		description: "Fetch one product (with its variants) by GID from a connected Shopify store.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			shop: shopField,
-			id: z.string().describe("The product GID, e.g. gid://shopify/Product/1234567890.")
+			id: shopifyGidField("Product").describe("The product GID, e.g. gid://shopify/Product/1234567890.")
 		}
 	}, guarded(async (client, args) => {
 		return ok(await client.graphql(`query GetProduct($id: ID!) {
@@ -195,13 +384,17 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	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).",
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: false
+		},
 		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(),
+			title: boundedText(255).describe("Product title (required)."),
+			descriptionHtml: optionalText(5e5),
+			vendor: optionalText(255),
+			productType: optionalText(255),
+			tags: tagsField,
 			status: z.enum([
 				"ACTIVE",
 				"DRAFT",
@@ -226,14 +419,18 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	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.",
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: true
+		},
 		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(),
+			id: shopifyGidField("Product").describe("The product GID to update."),
+			title: optionalText(255),
+			descriptionHtml: optionalText(5e5),
+			vendor: optionalText(255),
+			productType: optionalText(255),
+			tags: tagsField,
 			status: z.enum([
 				"ACTIVE",
 				"DRAFT",
@@ -258,14 +455,21 @@ function registerTools(server, resolveClient, listShops) {
 		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.",
+		description: "Set the price of a single product variant. Copy the exact variant and price into confirmVariantId and confirmPrice to confirm the commerce change.",
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: true
+		},
 		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\".")
+			productId: shopifyGidField("Product").describe("The parent product GID."),
+			variantId: shopifyGidField("ProductVariant").describe("The variant GID to reprice."),
+			price: moneyField.describe("The new price as a decimal string, e.g. \"19.99\"."),
+			confirmVariantId: shopifyGidField("ProductVariant").describe("Exact variant GID confirming the price target."),
+			confirmPrice: moneyField.describe("Exact decimal price confirming the new value.")
 		}
 	}, guarded(async (client, args) => {
+		if (args.confirmVariantId !== args.variantId || args.confirmPrice !== args.price) throw new Error("Variant price confirmation must exactly match variantId and price");
 		const data = await client.graphql(`mutation SetVariantPrice($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
           productVariantsBulkUpdate(productId: $productId, variants: $variants) {
             productVariants { id price }
@@ -283,11 +487,15 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	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.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			shop: shopField,
-			first: z.coerce.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).")
+			first: pageSizeField.describe("Page size (default 50, max 250)."),
+			after: cursorField.describe("Pagination cursor."),
+			query: searchField.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) {
@@ -310,9 +518,13 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	register("shopify_get_order", {
 		description: "Fetch one order (with line items and fulfillment orders) by GID from a connected Shopify store.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			shop: shopField,
-			id: z.string().describe("The order GID, e.g. gid://shopify/Order/1234567890.")
+			id: shopifyGidField("Order").describe("The order GID, e.g. gid://shopify/Order/1234567890.")
 		}
 	}, guarded(async (client, args) => {
 		return ok(await client.graphql(`query GetOrder($id: ID!) {
@@ -328,16 +540,23 @@ function registerTools(server, resolveClient, listShops) {
         }`, { 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.",
+		description: "Fulfill a fulfillment order. Copy the exact fulfillmentOrderId into confirmFulfillmentOrderId to confirm this irreversible shipment action.",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false
+		},
 		inputSchema: {
 			shop: shopField,
-			fulfillmentOrderId: z.string().describe("The fulfillment order GID (from order.fulfillmentOrders)."),
+			fulfillmentOrderId: shopifyGidField("FulfillmentOrder").describe("The fulfillment order GID (from order.fulfillmentOrders)."),
+			confirmFulfillmentOrderId: shopifyGidField("FulfillmentOrder").describe("Exact fulfillment-order GID confirming the shipment target."),
 			notifyCustomer: z.boolean().optional().describe("Send the shipping notification (default false)."),
-			trackingNumber: z.string().optional(),
-			trackingUrl: z.string().optional(),
-			trackingCompany: z.string().optional()
+			trackingNumber: optionalText(255),
+			trackingUrl: safeHttpsUrlField.optional(),
+			trackingCompany: optionalText(255)
 		}
 	}, guarded(async (client, args) => {
+		if (args.confirmFulfillmentOrderId !== args.fulfillmentOrderId) throw new Error("confirmFulfillmentOrderId must exactly match fulfillmentOrderId");
 		const fulfillment = {
 			lineItemsByFulfillmentOrder: [{ fulfillmentOrderId: args.fulfillmentOrderId }],
 			notifyCustomer: args.notifyCustomer ?? false
@@ -359,24 +578,31 @@ function registerTools(server, resolveClient, listShops) {
 		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.",
+		description: "Create a refund record against an order. Copy the exact orderId into confirmOrderId to confirm the financial/inventory target.",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false
+		},
 		inputSchema: {
 			shop: shopField,
-			orderId: z.string().describe("The order GID to refund."),
-			note: z.string().optional(),
+			orderId: shopifyGidField("Order").describe("The order GID to refund."),
+			confirmOrderId: shopifyGidField("Order").describe("Exact order GID confirming the refund target."),
+			note: optionalText(1e4),
 			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.coerce.number().int().min(1),
+				lineItemId: shopifyGidField("LineItem").describe("The order line item GID to refund."),
+				quantity: z.coerce.number().int().min(1).max(1e6),
 				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.")
+			})).min(1).max(250).optional().describe("Line items to refund. Omit for a shipping-only or note-only refund.")
 		}
 	}, guarded(async (client, args) => {
+		if (args.confirmOrderId !== args.orderId) throw new Error("confirmOrderId must exactly match the order being refunded");
 		const input = {
 			orderId: args.orderId,
 			notify: args.notify ?? false
@@ -400,10 +626,16 @@ function registerTools(server, resolveClient, listShops) {
 		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.",
+		description: "Cancel an order (async job). Copy the exact orderId into confirmOrderId to confirm the irreversible target; reason and restock are required.",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false
+		},
 		inputSchema: {
 			shop: shopField,
-			orderId: z.string().describe("The order GID to cancel."),
+			orderId: shopifyGidField("Order").describe("The order GID to cancel."),
+			confirmOrderId: shopifyGidField("Order").describe("Exact order GID confirming cancellation."),
 			reason: z.enum([
 				"CUSTOMER",
 				"DECLINED",
@@ -415,9 +647,10 @@ function registerTools(server, resolveClient, listShops) {
 			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).")
+			staffNote: optionalText(255).describe("Internal note (max 255 chars).")
 		}
 	}, guarded(async (client, args) => {
+		if (args.confirmOrderId !== args.orderId) throw new Error("confirmOrderId must exactly match the order being cancelled");
 		const variables = {
 			orderId: args.orderId,
 			reason: args.reason,
@@ -438,17 +671,20 @@ function registerTools(server, resolveClient, listShops) {
             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("; ")}`);
+		assertNoUserErrors(data, "orderCancel", "orderCancelUserErrors");
 		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.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			shop: shopField,
-			first: z.coerce.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.")
+			first: pageSizeField.describe("Page size (default 50, max 250)."),
+			after: cursorField,
+			query: searchField.describe("Optional Shopify customer search query.")
 		}
 	}, guarded(async (client, args) => {
 		return ok(await client.graphql(`query ListCustomers($first: Int!, $after: String, $query: String) {
@@ -464,9 +700,13 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	register("shopify_get_customer", {
 		description: "Fetch one customer by GID from a connected Shopify store.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			shop: shopField,
-			id: z.string().describe("The customer GID, e.g. gid://shopify/Customer/1234567890.")
+			id: shopifyGidField("Customer").describe("The customer GID, e.g. gid://shopify/Customer/1234567890.")
 		}
 	}, guarded(async (client, args) => {
 		return ok(await client.graphql(`query GetCustomer($id: ID!) {
@@ -478,14 +718,18 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	register("shopify_create_customer", {
 		description: "Create a customer in a connected Shopify store using the customerCreate mutation.",
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: false
+		},
 		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()
+			firstName: optionalText(255),
+			lastName: optionalText(255),
+			email: z.email().max(320).optional(),
+			phone: optionalText(64),
+			note: optionalText(1e5),
+			tags: tagsField
 		}
 	}, guarded(async (client, args) => {
 		const input = {};
@@ -506,15 +750,19 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	register("shopify_update_customer", {
 		description: "Update fields on an existing customer in a connected Shopify store using customerUpdate. Only supplied fields change.",
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: true
+		},
 		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()
+			id: shopifyGidField("Customer").describe("The customer GID to update."),
+			firstName: optionalText(255),
+			lastName: optionalText(255),
+			email: z.email().max(320).optional(),
+			phone: optionalText(64),
+			note: optionalText(1e5),
+			tags: tagsField
 		}
 	}, guarded(async (client, args) => {
 		const input = { id: args.id };
@@ -535,9 +783,13 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	register("shopify_list_locations", {
 		description: "List the inventory locations of a connected Shopify store (needed to adjust inventory levels).",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			shop: shopField,
-			first: z.coerce.number().int().min(1).max(250).optional().describe("Page size (default 50).")
+			first: pageSizeField.describe("Page size (default 50).")
 		}
 	}, guarded(async (client, args) => {
 		return ok(await client.graphql(`query ListLocations($first: Int!) {
@@ -548,10 +800,14 @@ function registerTools(server, resolveClient, listShops) {
 	}));
 	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).",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			shop: shopField,
-			inventoryItemId: z.string().describe("The inventory item GID (variant.inventoryItem.id)."),
-			first: z.coerce.number().int().min(1).max(250).optional().describe("Page size (default 50).")
+			inventoryItemId: shopifyGidField("InventoryItem").describe("The inventory item GID (variant.inventoryItem.id)."),
+			first: pageSizeField.describe("Page size (default 50).")
 		}
 	}, guarded(async (client, args) => {
 		return ok(await client.graphql(`query InventoryLevels($id: ID!, $first: Int!) {
@@ -572,15 +828,23 @@ function registerTools(server, resolveClient, listShops) {
 		}));
 	}));
 	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.",
+		description: "Adjust available inventory. Copy inventoryItemId, locationId, and delta into the matching confirmation fields to confirm the stock change.",
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: false
+		},
 		inputSchema: {
 			shop: shopField,
-			inventoryItemId: z.string().describe("The inventory item GID."),
-			locationId: z.string().describe("The location GID (from shopify_list_locations)."),
-			delta: z.coerce.number().int().describe("Signed quantity change, e.g. 10 or -3."),
-			reason: z.string().optional().describe("Adjustment reason code (default \"correction\").")
+			inventoryItemId: shopifyGidField("InventoryItem").describe("The inventory item GID."),
+			locationId: shopifyGidField("Location").describe("The location GID (from shopify_list_locations)."),
+			delta: z.coerce.number().int().min(-1e6).max(1e6).refine((value) => value !== 0).describe("Non-zero signed quantity change, e.g. 10 or -3."),
+			confirmInventoryItemId: shopifyGidField("InventoryItem"),
+			confirmLocationId: shopifyGidField("Location"),
+			confirmDelta: z.coerce.number().int().min(-1e6).max(1e6),
+			reason: optionalText(255).describe("Adjustment reason code (default \"correction\").")
 		}
 	}, guarded(async (client, args) => {
+		if (args.confirmInventoryItemId !== args.inventoryItemId || args.confirmLocationId !== args.locationId || args.confirmDelta !== args.delta) throw new Error("Inventory confirmation must exactly match inventoryItemId, locationId, and delta");
 		const data = await client.graphql(`mutation AdjustInventory($input: InventoryAdjustQuantitiesInput!, $key: String!) {
             inventoryAdjustQuantities(input: $input) @idempotent(key: $key) {
               inventoryAdjustmentGroup { createdAt reason changes { name delta } }
@@ -621,6 +885,7 @@ function registerTools(server, resolveClient, listShops) {
 * Architecture:
 *   OpenClaw ←(stdio)→ this server ←(https)→ Shopify Admin GraphQL API
 */
+const packageMetadata = createRequire(import.meta.url)("../package.json");
 /**
 * Fallback Admin API version. The connect provider stamps the pinned version
 * (`2026-07`) onto every account via `buildCredentialsResponse`, so this is only
@@ -639,11 +904,12 @@ function log(msg) {
 * to ask the user to reconnect rather than retrying blindly.
 */
 function resolveClient(shop) {
-	const c = clients.get(shop);
+	const normalizedShop = validateShopDomain(shop);
+	const c = clients.get(normalizedShop);
 	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).`);
+	const known = shopSnapshot.find((s) => s.shopDomain === normalizedShop);
+	if (known && !known.connected) throw new Error(`Shop ${normalizedShop} 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: ${normalizedShop}. 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();
@@ -652,12 +918,17 @@ async function main() {
 		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)`);
+	const seenShops = /* @__PURE__ */ new Set();
 	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`);
+		const candidateDomain = acct.shopDomain || (acct.accountIdentifier.endsWith(".myshopify.com") ? acct.accountIdentifier : "");
+		if (!acct.accessToken || !candidateDomain) {
+			log("Skipping Shopify account — missing access token or shop domain");
+			let deadShopDomain = "unavailable.invalid";
+			if (candidateDomain) try {
+				deadShopDomain = validateShopDomain(candidateDomain);
+			} catch {}
 			shopSnapshot.push({
-				shopDomain: shopDomain || acct.accountIdentifier,
+				shopDomain: deadShopDomain,
 				shopName: acct.shopName || acct.displayName,
 				shopGid: acct.shopGid || null,
 				connectedAt: acct.connectedAt,
@@ -666,15 +937,33 @@ async function main() {
 			});
 			continue;
 		}
-		if (clients.has(shopDomain)) {
+		let shopDomain;
+		let client;
+		try {
+			shopDomain = validateShopDomain(candidateDomain);
+			client = new ShopifyClient({
+				accessToken: acct.accessToken,
+				shopDomain,
+				apiVersion: acct.apiVersion || FALLBACK_API_VERSION
+			});
+		} catch {
+			log("Skipping Shopify account — invalid credential metadata");
+			shopSnapshot.push({
+				shopDomain: "unavailable.invalid",
+				shopName: acct.shopName || acct.displayName,
+				shopGid: acct.shopGid || null,
+				connectedAt: acct.connectedAt,
+				connected: false,
+				reason: "invalid_credential_metadata"
+			});
+			continue;
+		}
+		if (seenShops.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
-		}));
+		seenShops.add(shopDomain);
+		clients.set(shopDomain, client);
 		shopSnapshot.push({
 			shopDomain,
 			shopName: acct.shopName || acct.displayName,
@@ -682,11 +971,11 @@ async function main() {
 			connectedAt: acct.connectedAt,
 			connected: true
 		});
-		log(`Cached client for store ${shopDomain} (${acct.shopName || acct.displayName || "no name"})`);
+		log(`Cached client for store ${shopDomain}`);
 	}
 	const server = new McpServer({
 		name: "shopify-mcp-server",
-		version: "0.1.0"
+		version: packageMetadata.version
 	});
 	registerTools(server, resolveClient, () => shopSnapshot);
 	const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/shopify-mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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",
@@ -19,8 +19,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.5",
-    "@alfe.ai/config": "0.4.0",
-    "@alfe.ai/agent-api-client": "0.14.0"
+    "@alfe.ai/config": "0.4.1",
+    "@alfe.ai/agent-api-client": "0.15.0"
   },
   "license": "UNLICENSED",
   "homepage": "https://alfe.ai",