@theethosteam/shopify-mcp 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# @theethosteam/shopify-mcp
+
+Multi-store read + write MCP server (and CLI) for the **Shopify Admin GraphQL
+API**. Built for agency use: one server, every client store, and every response
+names the store it ran against so data can never be misattributed.
+
+- **19 typed tools** — shop identity, products (CRUD), orders, customers,
+  collections, locations, themes, webhooks — plus a **raw GraphQL passthrough**
+  for everything else.
+- **Tiered writes** — routine writes (create/update product, create webhook)
+  execute; **deletes are dry-run unless `confirm:true`**; raw-passthrough
+  **mutations are refused unless `confirm:true`**.
+- **Multi-store** — one env entry per store; `shopify_use_store` switches the
+  session default (request-scoped on the remote host, so users never clobber
+  each other).
+- Runs three ways, like every Ethos connector: **remote connector**
+  (`https://mcp.theethosteam.com/api/shopify/mcp`), **stdio via npx**, and
+  **CLI** (`shop`).
+
+## Auth: per-store custom-app Admin tokens
+
+No OAuth dance. Each store gets a [custom app](https://help.shopify.com/en/manual/apps/app-types/custom-apps):
+store admin → **Settings → Apps and sales channels → Develop apps → Create app**
+→ enable the Admin API scopes you need (start with `read_products,
+write_products, read_orders, read_customers, read_themes, read_locations,
+write_webhooks`) → **Install app** → copy the Admin API access token
+(`shpat_…`). The token is shown **once**.
+
+## Env
+
+```bash
+# One entry per store — alias is the suffix, lowercased ("bia" here):
+SHOPIFY_STORE_BIA="born-in-apparel.myshopify.com|shpat_xxx"
+SHOPIFY_STORE_A2="a2-phone-repair.myshopify.com|shpat_yyy"
+
+# Single-store shorthand (registers as alias "default"):
+SHOPIFY_STORE_DOMAIN=born-in-apparel.myshopify.com
+SHOPIFY_ADMIN_TOKEN=shpat_xxx
+
+# Optional:
+SHOPIFY_ACTIVE_STORE=bia        # default store when several are configured
+SHOPIFY_API_VERSION=2026-07     # defaults to the pinned stable
+```
+
+With multiple stores and no active store set, tools **refuse rather than
+guess** — pass `store:"bia"` or call `shopify_use_store` first.
+
+## Run
+
+```bash
+# MCP over stdio
+npx -y @theethosteam/shopify-mcp
+
+# CLI
+npx -y -p @theethosteam/shopify-mcp shop whoami
+npx -y -p @theethosteam/shopify-mcp shop products -q "status:active" -s bia
+npx -y -p @theethosteam/shopify-mcp shop orders -q "financial_status:paid"
+npx -y -p @theethosteam/shopify-mcp shop graphql '{ shop { name } }'
+```
+
+Claude Code:
+
+```bash
+claude mcp add shopify -e SHOPIFY_STORE_DOMAIN=<shop>.myshopify.com -e SHOPIFY_ADMIN_TOKEN=shpat_... -- npx -y @theethosteam/shopify-mcp
+```
+
+## Tools
+
+| Tool | Tier |
+|---|---|
+| `shopify_whoami` · `shopify_list_stores` · `shopify_use_store` | awareness |
+| `shopify_list_products` · `shopify_get_product` | read |
+| `shopify_create_product` · `shopify_update_product` | routine write |
+| `shopify_delete_product` | **confirm-gated** |
+| `shopify_list_orders` · `shopify_get_order` | read |
+| `shopify_list_customers` · `shopify_get_customer` | read |
+| `shopify_list_collections` · `shopify_list_locations` · `shopify_list_themes` | read |
+| `shopify_list_webhooks` · `shopify_create_webhook` | read / routine |
+| `shopify_delete_webhook` | **confirm-gated** |
+| `shopify_graphql` | read free / **mutations confirm-gated** |
+
+List queries accept [Shopify search syntax](https://shopify.dev/docs/api/usage/search-syntax)
+(`status:active`, `financial_status:paid`, `created_at:>2026-08-01`, …) and
+cursor pagination (`first` ≤ 50, `after` from the previous page's
+`pageInfo.endCursor`).
+
+## Notes
+
+- **API version** is pinned per release (`LATEST_STABLE` in `core/client.ts`);
+  Shopify versions the Admin API quarterly and supports each for 12 months —
+  bump the pin with a normal version bump.
+- Throttled calls (`THROTTLED`) retry once automatically.
+- Mutation soft failures (`userErrors`) surface as tool errors with field paths.
+- The remote host's **user-mode (OAuth) logins carry no Shopify creds yet** —
+  Shopify tools on `mcp.theethosteam.com` work in bearer/admin mode (deployment
+  env). Per-user store grants would follow the `ghl_pits` pattern in
+  `connector_users` when needed.

package/bin/shop.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { tsImport } from "tsx/esm/api";
+await tsImport("../cli.ts", import.meta.url);

package/bin/shopify-mcp.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { tsImport } from "tsx/esm/api";
+await tsImport("../mcp.ts", import.meta.url);

package/cli.ts

@@ -0,0 +1,106 @@
+import { Command } from "commander";
+import { loadEnv } from "./core/env.js";
+import * as shopify from "./core/shopify.js";
+
+loadEnv();
+
+const out = (data: unknown) => console.log(JSON.stringify(data, null, 2));
+const run = (fn: () => Promise<unknown> | unknown) =>
+  Promise.resolve()
+    .then(fn)
+    .then(out)
+    .catch((e: any) => {
+      console.error("ERROR:", e?.message ?? String(e));
+      process.exit(1);
+    });
+
+const program = new Command();
+program
+  .name("shop")
+  .description("Shopify Admin CLI — multi-store reads + guarded writes over per-store custom-app tokens.")
+  .version("0.1.0");
+
+const st = (cmd: Command) => cmd.option("-s, --store <aliasOrDomain>", "store alias or *.myshopify.com domain");
+
+// ---- Awareness -------------------------------------------------------------
+st(program.command("whoami")).description("Active store + shop identity + API version").action((o: any) => run(() => shopify.whoami(o.store)));
+program.command("stores").description("All configured stores").action(() => run(() => shopify.stores()));
+
+// ---- Reads -----------------------------------------------------------------
+st(program.command("products"))
+  .description("List/search products")
+  .option("-q, --query <s>", "Shopify search syntax, e.g. 'status:active'")
+  .option("--first <n>")
+  .option("--after <cursor>")
+  .action((o: any) => run(() => shopify.listProducts({ query: o.query, first: o.first ? Number(o.first) : undefined, after: o.after, store: o.store })));
+st(program.command("product <idOrHandle>"))
+  .description("One product in full (numeric id, gid, or handle)")
+  .action((idOrHandle: string, o: any) =>
+    run(() =>
+      /^\d+$|^gid:/.test(idOrHandle)
+        ? shopify.getProduct({ id: idOrHandle, store: o.store })
+        : shopify.getProduct({ handle: idOrHandle, store: o.store }),
+    ),
+  );
+st(program.command("orders"))
+  .description("List orders, newest first")
+  .option("-q, --query <s>", "e.g. 'financial_status:paid'")
+  .option("--first <n>")
+  .option("--after <cursor>")
+  .action((o: any) => run(() => shopify.listOrders({ query: o.query, first: o.first ? Number(o.first) : undefined, after: o.after, store: o.store })));
+st(program.command("order <id>")).description("One order in full").action((id: string, o: any) => run(() => shopify.getOrder(id, o.store)));
+st(program.command("customers"))
+  .description("List/search customers")
+  .option("-q, --query <s>")
+  .option("--first <n>")
+  .option("--after <cursor>")
+  .action((o: any) => run(() => shopify.listCustomers({ query: o.query, first: o.first ? Number(o.first) : undefined, after: o.after, store: o.store })));
+st(program.command("customer <id>")).description("One customer in full").action((id: string, o: any) => run(() => shopify.getCustomer(id, o.store)));
+st(program.command("collections")).description("List collections").action((o: any) => run(() => shopify.listCollections({ store: o.store })));
+st(program.command("locations")).description("Inventory locations").action((o: any) => run(() => shopify.listLocations(o.store)));
+st(program.command("themes")).description("Online-store themes").action((o: any) => run(() => shopify.listThemes(o.store)));
+st(program.command("webhooks")).description("Webhook subscriptions").action((o: any) => run(() => shopify.listWebhooks(o.store)));
+
+// ---- Writes (destructive ones need --confirm) ------------------------------
+st(program.command("create-product <title>"))
+  .description("Create a product (add --status DRAFT while iterating)")
+  .option("--status <s>", "ACTIVE|DRAFT|ARCHIVED")
+  .option("--vendor <s>")
+  .option("--type <s>", "productType")
+  .option("--tags <csv>")
+  .action((title: string, o: any) =>
+    run(() =>
+      shopify.createProduct(
+        {
+          title,
+          status: o.status,
+          vendor: o.vendor,
+          productType: o.type,
+          tags: o.tags ? String(o.tags).split(",").map((t: string) => t.trim()) : undefined,
+        },
+        o.store,
+      ),
+    ),
+  );
+st(program.command("delete-product <id>"))
+  .description("Delete a product (dry-run without --confirm)")
+  .option("--confirm")
+  .action((id: string, o: any) =>
+    run(() => (o.confirm ? shopify.deleteProduct(id, o.store) : shopify.getProduct({ id, store: o.store }).then((p) => ({ dryRun: true, wouldDelete: p })))),
+  );
+
+// ---- Raw -------------------------------------------------------------------
+st(program.command("graphql <query>"))
+  .description("Raw Admin GraphQL (mutations need --confirm)")
+  .option("-v, --variables <json>")
+  .option("--confirm")
+  .action((query: string, o: any) =>
+    run(() => {
+      if (shopify.isMutation(query) && !o.confirm) {
+        return { refused: true, note: "Mutation — re-run with --confirm." };
+      }
+      return shopify.raw(query, o.variables ? JSON.parse(o.variables) : undefined, o.store);
+    }),
+  );
+
+program.parseAsync(process.argv);

package/core/client.ts

@@ -0,0 +1,155 @@
+import { credKeys, getCred, setCred } from "./creds.js";
+
+/**
+ * Store resolution + Admin GraphQL transport.
+ *
+ * Credential model (mirrors ghl-mcp's per-location PITs):
+ *   SHOPIFY_STORE_<ALIAS> = "<shop>.myshopify.com|shpat_..."   one entry per store
+ *   SHOPIFY_STORE_DOMAIN + SHOPIFY_ADMIN_TOKEN                  single-store shorthand
+ *                                                               (registered under alias "default")
+ *   SHOPIFY_ACTIVE_STORE = alias or domain                      session default (use_store writes it)
+ *   SHOPIFY_API_VERSION                                         defaults to LATEST_STABLE
+ *
+ * Tokens are Admin API access tokens from a per-store custom app
+ * (store admin → Settings → Apps and sales channels → Develop apps).
+ */
+
+export const LATEST_STABLE = "2026-07";
+
+export class ShopifyError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly detail?: unknown,
+  ) {
+    super(message);
+  }
+}
+
+export interface Store {
+  alias: string;
+  domain: string;
+  token: string;
+}
+
+const normDomain = (d: string): string => {
+  let s = d.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+  if (s && !s.includes(".")) s = `${s}.myshopify.com`;
+  return s;
+};
+
+/** Every configured store, from the request context else env. */
+export function listStores(): Store[] {
+  const out: Store[] = [];
+  const domain = getCred("SHOPIFY_STORE_DOMAIN");
+  const token = getCred("SHOPIFY_ADMIN_TOKEN");
+  if (domain && token) out.push({ alias: "default", domain: normDomain(domain), token });
+  for (const key of credKeys("SHOPIFY_STORE_")) {
+    if (key === "SHOPIFY_STORE_DOMAIN") continue;
+    const raw = getCred(key);
+    if (!raw) continue;
+    const sep = raw.indexOf("|");
+    if (sep < 0) continue; // malformed entry — skip rather than guess
+    const alias = key.slice("SHOPIFY_STORE_".length).toLowerCase();
+    out.push({ alias, domain: normDomain(raw.slice(0, sep)), token: raw.slice(sep + 1).trim() });
+  }
+  return out;
+}
+
+/** Resolve a store by alias or domain; undefined falls back to the active/only store. */
+export function resolveStore(aliasOrDomain?: string): Store {
+  const stores = listStores();
+  if (stores.length === 0) {
+    throw new ShopifyError(
+      "No Shopify store configured. Set SHOPIFY_STORE_DOMAIN + SHOPIFY_ADMIN_TOKEN, or SHOPIFY_STORE_<ALIAS>=\"<shop>.myshopify.com|shpat_...\".",
+    );
+  }
+  const want = aliasOrDomain ?? getCred("SHOPIFY_ACTIVE_STORE");
+  if (!want) {
+    if (stores.length === 1) return stores[0];
+    throw new ShopifyError(
+      `Multiple stores configured (${stores.map((s) => s.alias).join(", ")}) and no active store. Pass store:<alias> or call use_store.`,
+    );
+  }
+  const needle = want.trim().toLowerCase();
+  const hit =
+    stores.find((s) => s.alias === needle) ??
+    stores.find((s) => s.domain === normDomain(needle));
+  if (!hit) {
+    throw new ShopifyError(
+      `Unknown store "${want}". Configured: ${stores.map((s) => `${s.alias} (${s.domain})`).join(", ")}.`,
+    );
+  }
+  return hit;
+}
+
+/** Set the session's active store (request-scoped on the remote host). */
+export function useStore(aliasOrDomain: string): Store {
+  const store = resolveStore(aliasOrDomain);
+  setCred("SHOPIFY_ACTIVE_STORE", store.alias);
+  return store;
+}
+
+export const apiVersion = (): string => getCred("SHOPIFY_API_VERSION") || LATEST_STABLE;
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * One Admin GraphQL call. Throws ShopifyError on HTTP or GraphQL errors;
+ * a THROTTLED response is retried once after a short pause.
+ */
+export async function gql<T = any>(
+  query: string,
+  variables: Record<string, unknown> = {},
+  store?: Store,
+  attempt = 0,
+): Promise<T> {
+  const s = store ?? resolveStore();
+  const res = await fetch(`https://${s.domain}/admin/api/${apiVersion()}/graphql.json`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Shopify-Access-Token": s.token,
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+  if (res.status === 401 || res.status === 403) {
+    throw new ShopifyError(
+      `Shopify rejected the token for ${s.domain} (HTTP ${res.status}). Re-check the custom app's Admin API token and scopes.`,
+      res.status,
+    );
+  }
+  if (!res.ok) {
+    throw new ShopifyError(`Shopify HTTP ${res.status} from ${s.domain}: ${await res.text()}`, res.status);
+  }
+  const body = (await res.json()) as { data?: T; errors?: any[] };
+  if (body.errors?.length) {
+    const throttled = body.errors.some((e) => e?.extensions?.code === "THROTTLED");
+    if (throttled && attempt < 1) {
+      await sleep(1500);
+      return gql(query, variables, s, attempt + 1);
+    }
+    throw new ShopifyError(
+      `Shopify GraphQL error from ${s.domain}: ${body.errors.map((e) => e.message).join("; ")}`,
+      undefined,
+      body.errors,
+    );
+  }
+  return body.data as T;
+}
+
+/** Accept a bare numeric id or a full gid for the given resource kind. */
+export const gid = (kind: string, id: string): string =>
+  /^\d+$/.test(id) ? `gid://shopify/${kind}/${id}` : id;
+
+/** Throw if the payload carries non-empty userErrors (mutation soft failures). */
+export function assertNoUserErrors(payload: any, op: string): void {
+  const errs = payload?.userErrors;
+  if (Array.isArray(errs) && errs.length) {
+    throw new ShopifyError(
+      `${op} failed: ${errs.map((e: any) => `${(e.field ?? []).join(".") || "?"}: ${e.message}`).join("; ")}`,
+      undefined,
+      errs,
+    );
+  }
+}

package/core/creds.ts

@@ -0,0 +1,54 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Per-request credential context for multi-user remote hosts.
+ *
+ * A remote MCP host (apps/connectors-mcp) serves many users from one process,
+ * so user credentials cannot live in process.env. The host runs each request
+ * inside credStore.run(<that user's creds>, …); credential reads in this
+ * package go through getCred()/credKeys(), which resolve from the request
+ * store when one is active and fall back to process.env otherwise (stdio CLI,
+ * single-user deployments — behavior unchanged).
+ *
+ * The store is deliberately AUTHORITATIVE while active: a key absent from the
+ * request store is absent, full stop — never silently satisfied by the host's
+ * own env credentials (that would let one user act as another).
+ *
+ * globalThis holds the single AsyncLocalStorage instance so every connector
+ * package in the process shares one context, even when bundlers duplicate
+ * this module. This file is intentionally identical across the packages.
+ */
+type CredMap = Record<string, string | undefined>;
+
+const g = globalThis as typeof globalThis & {
+  __ethosCredStore?: AsyncLocalStorage<CredMap>;
+};
+
+export const credStore: AsyncLocalStorage<CredMap> = (g.__ethosCredStore ??=
+  new AsyncLocalStorage<CredMap>());
+
+/** True while running inside a per-request credential context. */
+export const hasCredContext = (): boolean => credStore.getStore() !== undefined;
+
+/** The named credential from the active request context, else process.env. */
+export function getCred(name: string): string | undefined {
+  const store = credStore.getStore();
+  return store ? store[name] : process.env[name];
+}
+
+/** All credential names with the prefix, from the active context else env. */
+export function credKeys(prefix: string): string[] {
+  const store = credStore.getStore();
+  return Object.keys(store ?? process.env).filter((k) => k.startsWith(prefix));
+}
+
+/**
+ * Write a value into the active request context when one exists, else into
+ * process.env. Keeps per-session mutations (e.g. ghl `use_location`) scoped to
+ * the request instead of leaking process-wide in a multi-user host.
+ */
+export function setCred(name: string, value: string): void {
+  const store = credStore.getStore();
+  if (store) store[name] = value;
+  else process.env[name] = value;
+}

package/core/env.ts

@@ -0,0 +1,53 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+/** Absolute path to the package root (one level up from core/). */
+export function pkgRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+/** Path to the package's .env file (where a rotated refresh token is stored). */
+export function envPath(): string {
+  return join(pkgRoot(), ".env");
+}
+
+/**
+ * Best-effort .env loader. Reads the package .env and the cwd .env and sets
+ * any keys that aren't already in process.env (so env vars passed by the MCP
+ * client / `claude mcp add -e` always win). Silent if no file exists.
+ */
+export function loadEnv(): void {
+  for (const path of [envPath(), join(process.cwd(), ".env")]) {
+    let txt: string;
+    try {
+      txt = readFileSync(path, "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of txt.split("\n")) {
+      const m = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*(.*?)\s*$/);
+      if (!m) continue;
+      let val = m[2];
+      if (
+        (val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))
+      ) {
+        val = val.slice(1, -1);
+      }
+      if (process.env[m[1]] === undefined) process.env[m[1]] = val;
+    }
+  }
+}
+
+/** Upsert a single KEY=value into the package .env (used by `auth:exchange`). */
+export function upsertEnv(key: string, value: string): void {
+  const path = envPath();
+  let lines: string[] = [];
+  if (existsSync(path)) lines = readFileSync(path, "utf8").split("\n");
+  const idx = lines.findIndex((l) => l.match(new RegExp(`^\\s*${key}\\s*=`)));
+  const entry = `${key}=${value}`;
+  if (idx >= 0) lines[idx] = entry;
+  else lines.push(entry);
+  writeFileSync(path, lines.filter((l, i) => l !== "" || i < lines.length - 1).join("\n") + "\n");
+}

package/core/register.ts

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as shopify from "./shopify.js";
+
+const json = (data: unknown) => ({
+  content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+});
+
+/**
+ * Register every Shopify tool on a given McpServer.
+ *
+ * Shared by BOTH transports so they expose the identical toolset:
+ *   - the stdio entrypoint (mcp.ts), and
+ *   - the remote HTTP handler (apps/connectors-mcp, via mcp-handler).
+ *
+ * Pure: it only registers tools. Env loading + transport wiring live in the caller.
+ */
+/**
+ * Some MCP clients (claude.ai custom-connector harness among them) deliver
+ * every argument as a string when they lack property types to coerce against.
+ * Same leniency shim as ghl-mcp: retry a failing string value JSON.parsed or
+ * array-wrapped; correctly-typed clients see zero behavior change.
+ */
+function lenientField(schema: z.ZodTypeAny): z.ZodTypeAny {
+  return z.preprocess((v) => {
+    if (typeof v !== "string" || schema.safeParse(v).success) return v;
+    const candidates: unknown[] = [];
+    const t = v.trim();
+    if (/^[\[{"]|^-?\d|^(true|false|null)$/.test(t)) {
+      try {
+        candidates.push(JSON.parse(t));
+      } catch {
+        /* not JSON — fall through */
+      }
+    }
+    candidates.push([v]);
+    for (const c of candidates) if (schema.safeParse(c).success) return c;
+    return v;
+  }, schema);
+}
+
+function lenientShape(shape: Record<string, z.ZodTypeAny>): Record<string, z.ZodTypeAny> {
+  const out: Record<string, z.ZodTypeAny> = {};
+  for (const [k, s] of Object.entries(shape)) out[k] = lenientField(s);
+  return out;
+}
+
+const storeArg = {
+  store: z.string().optional().describe("Store alias or *.myshopify.com domain (defaults to the active store)"),
+};
+const paging = {
+  first: z.number().optional().describe("Page size, max 50 (default 20)"),
+  after: z.string().optional().describe("Cursor from the previous page's pageInfo.endCursor"),
+};
+
+export function registerTools(server: McpServer) {
+  /** Wrap a handler so thrown errors become an isError tool result. */
+  function tool(
+    name: string,
+    description: string,
+    shape: Record<string, z.ZodTypeAny>,
+    run: (a: any) => Promise<unknown> | unknown,
+  ) {
+    server.tool(name, description, lenientShape(shape), async (a: any) => {
+      try {
+        return json(await run(a));
+      } catch (e: any) {
+        return {
+          content: [{ type: "text" as const, text: `ERROR: ${e?.message ?? String(e)}` }],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  // ---- Awareness ----------------------------------------------------------
+
+  tool(
+    "shopify_whoami",
+    "Active store + shop identity (name, domain, plan, currency, timezone) + API version. Run this first — it also proves the token works.",
+    storeArg,
+    (a) => shopify.whoami(a.store),
+  );
+
+  tool("shopify_list_stores", "All configured stores (alias + domain) and the API version.", {}, () =>
+    shopify.stores(),
+  );
+
+  tool(
+    "shopify_use_store",
+    "Set the session's active store; subsequent tools default to it.",
+    { store: z.string().describe("Store alias or *.myshopify.com domain") },
+    (a) => shopify.switchStore(a.store),
+  );
+
+  // ---- Products -----------------------------------------------------------
+
+  tool(
+    "shopify_list_products",
+    "List/search products. `query` uses Shopify search syntax (e.g. 'status:active', 'title:*hoodie*', 'tag:sale').",
+    { query: z.string().optional(), ...paging, ...storeArg },
+    (a) => shopify.listProducts(a),
+  );
+
+  tool(
+    "shopify_get_product",
+    "One product in full — variants, options, images, description — by id (numeric or gid) or handle.",
+    { id: z.string().optional(), handle: z.string().optional(), ...storeArg },
+    (a) => shopify.getProduct(a),
+  );
+
+  const productFields = {
+    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(),
+  };
+
+  tool(
+    "shopify_create_product",
+    "Create a product. Shopify defaults new products to ACTIVE — pass status:'DRAFT' while iterating.",
+    { title: z.string(), ...productFields, ...storeArg },
+    (a) => {
+      const { store, ...input } = a;
+      return shopify.createProduct(input, store);
+    },
+  );
+
+  tool(
+    "shopify_update_product",
+    "Update product fields (only the fields you pass change).",
+    { id: z.string(), title: z.string().optional(), ...productFields, ...storeArg },
+    (a) => {
+      const { id, store, ...input } = a;
+      return shopify.updateProduct(id, input, store);
+    },
+  );
+
+  tool(
+    "shopify_delete_product",
+    "DELETE a product permanently. Dry-run unless confirm:true.",
+    { id: z.string(), confirm: z.boolean().optional(), ...storeArg },
+    async (a) => {
+      if (!a.confirm) {
+        const current = await shopify.getProduct({ id: a.id, store: a.store });
+        return { dryRun: true, wouldDelete: current, note: "Pass confirm:true to delete." };
+      }
+      return shopify.deleteProduct(a.id, a.store);
+    },
+  );
+
+  // ---- Orders -------------------------------------------------------------
+
+  tool(
+    "shopify_list_orders",
+    "List orders, newest first. `query` uses Shopify search syntax (e.g. 'financial_status:paid', 'created_at:>2026-08-01', 'fulfillment_status:unfulfilled').",
+    { query: z.string().optional(), ...paging, ...storeArg },
+    (a) => shopify.listOrders(a),
+  );
+
+  tool(
+    "shopify_get_order",
+    "One order in full — line items, customer, addresses, fulfillments, totals.",
+    { id: z.string(), ...storeArg },
+    (a) => shopify.getOrder(a.id, a.store),
+  );
+
+  // ---- Customers ----------------------------------------------------------
+
+  tool(
+    "shopify_list_customers",
+    "List/search customers (query e.g. 'email:jane@…', 'orders_count:>5').",
+    { query: z.string().optional(), ...paging, ...storeArg },
+    (a) => shopify.listCustomers(a),
+  );
+
+  tool(
+    "shopify_get_customer",
+    "One customer in full, incl. their 10 latest orders.",
+    { id: z.string(), ...storeArg },
+    (a) => shopify.getCustomer(a.id, a.store),
+  );
+
+  // ---- Catalog / storefront ----------------------------------------------
+
+  tool("shopify_list_collections", "List collections with product counts.", { ...paging, ...storeArg }, (a) =>
+    shopify.listCollections(a),
+  );
+
+  tool("shopify_list_locations", "Inventory locations.", storeArg, (a) => shopify.listLocations(a.store));
+
+  tool(
+    "shopify_list_themes",
+    "Online-store themes (the MAIN role is the live theme).",
+    storeArg,
+    (a) => shopify.listThemes(a.store),
+  );
+
+  // ---- Webhooks -----------------------------------------------------------
+
+  tool("shopify_list_webhooks", "Webhook subscriptions with endpoints.", storeArg, (a) =>
+    shopify.listWebhooks(a.store),
+  );
+
+  tool(
+    "shopify_create_webhook",
+    "Subscribe an HTTPS callback to a topic (e.g. ORDERS_CREATE, PRODUCTS_UPDATE).",
+    { topic: z.string(), callbackUrl: z.string(), ...storeArg },
+    (a) => shopify.createWebhook(a.topic, a.callbackUrl, a.store),
+  );
+
+  tool(
+    "shopify_delete_webhook",
+    "Delete a webhook subscription. Dry-run unless confirm:true.",
+    { id: z.string(), confirm: z.boolean().optional(), ...storeArg },
+    async (a) => {
+      if (!a.confirm) return { dryRun: true, wouldDeleteWebhook: a.id, note: "Pass confirm:true to delete." };
+      return shopify.deleteWebhook(a.id, a.store);
+    },
+  );
+
+  // ---- Raw passthrough ----------------------------------------------------
+
+  tool(
+    "shopify_graphql",
+    "Raw Admin GraphQL passthrough — the escape hatch for anything without a typed tool. Queries run as-is; MUTATIONS are refused unless confirm:true.",
+    {
+      query: z.string(),
+      variables: z.record(z.unknown()).optional(),
+      confirm: z.boolean().optional(),
+      ...storeArg,
+    },
+    (a) => {
+      if (shopify.isMutation(a.query) && !a.confirm) {
+        return {
+          refused: true,
+          note: "This is a mutation. Re-run with confirm:true to execute it.",
+        };
+      }
+      return shopify.raw(a.query, a.variables as Record<string, unknown> | undefined, a.store);
+    },
+  );
+}

package/core/shopify.ts

@@ -0,0 +1,312 @@
+import {
+  apiVersion,
+  assertNoUserErrors,
+  gid,
+  gql,
+  listStores,
+  resolveStore,
+  useStore,
+} from "./client.js";
+
+/**
+ * Typed operations over the Admin GraphQL API, shared by the MCP tools
+ * (core/register.ts) and the CLI (cli.ts). Every response names the store it
+ * ran against, so multi-store sessions can never misattribute data.
+ */
+
+const branded = <T>(store: { alias: string; domain: string }, data: T) => ({
+  store: `${store.alias} (${store.domain})`,
+  ...(data as object),
+});
+
+const pageArgs = (first?: number, after?: string) => ({
+  first: Math.min(Math.max(first ?? 20, 1), 50),
+  after: after || null,
+});
+
+// ---- Awareness -------------------------------------------------------------
+
+export function stores() {
+  return {
+    apiVersion: apiVersion(),
+    stores: listStores().map((s) => ({ alias: s.alias, domain: s.domain })),
+  };
+}
+
+export function switchStore(aliasOrDomain: string) {
+  const s = useStore(aliasOrDomain);
+  return { active: s.alias, domain: s.domain };
+}
+
+export async function whoami(store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `{ shop { id name myshopifyDomain primaryDomain { host } plan { publicDisplayName shopifyPlus } currencyCode ianaTimezone email } }`,
+    {},
+    s,
+  );
+  return branded(s, { apiVersion: apiVersion(), shop: data.shop });
+}
+
+// ---- Products --------------------------------------------------------------
+
+const PRODUCT_CARD = `id title handle status vendor productType tags totalInventory updatedAt
+  priceRangeV2 { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } }`;
+
+export async function listProducts(o: { query?: string; first?: number; after?: string; store?: string }) {
+  const s = resolveStore(o.store);
+  const data = await gql(
+    `query ($first: Int!, $after: String, $query: String) {
+       products(first: $first, after: $after, query: $query) {
+         nodes { ${PRODUCT_CARD} }
+         pageInfo { hasNextPage endCursor }
+       }
+     }`,
+    { ...pageArgs(o.first, o.after), query: o.query || null },
+    s,
+  );
+  return branded(s, data.products);
+}
+
+export async function getProduct(o: { id?: string; handle?: string; store?: string }) {
+  const s = resolveStore(o.store);
+  const selection = `${PRODUCT_CARD} descriptionHtml
+    options { name values }
+    variants(first: 50) { nodes { id title sku price compareAtPrice inventoryQuantity selectedOptions { name value } } }
+    media(first: 20) { nodes { ... on MediaImage { id image { url altText } } } }`;
+  if (o.handle && !o.id) {
+    const data = await gql(
+      `query ($handle: String!) { productByIdentifier(identifier: { handle: $handle }) { ${selection} } }`,
+      { handle: o.handle },
+      s,
+    );
+    return branded(s, { product: data.productByIdentifier });
+  }
+  if (!o.id) throw new Error("Pass id or handle.");
+  const data = await gql(
+    `query ($id: ID!) { product(id: $id) { ${selection} } }`,
+    { id: gid("Product", o.id) },
+    s,
+  );
+  return branded(s, { product: data.product });
+}
+
+export interface ProductInput {
+  title?: string;
+  descriptionHtml?: string;
+  vendor?: string;
+  productType?: string;
+  tags?: string[];
+  status?: "ACTIVE" | "DRAFT" | "ARCHIVED";
+}
+
+export async function createProduct(input: ProductInput & { title: string }, store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `mutation ($product: ProductCreateInput!) {
+       productCreate(product: $product) {
+         product { ${PRODUCT_CARD} }
+         userErrors { field message }
+       }
+     }`,
+    { product: input },
+    s,
+  );
+  assertNoUserErrors(data.productCreate, "productCreate");
+  return branded(s, { product: data.productCreate.product });
+}
+
+export async function updateProduct(id: string, input: ProductInput, store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `mutation ($product: ProductUpdateInput!) {
+       productUpdate(product: $product) {
+         product { ${PRODUCT_CARD} }
+         userErrors { field message }
+       }
+     }`,
+    { product: { id: gid("Product", id), ...input } },
+    s,
+  );
+  assertNoUserErrors(data.productUpdate, "productUpdate");
+  return branded(s, { product: data.productUpdate.product });
+}
+
+export async function deleteProduct(id: string, store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `mutation ($input: ProductDeleteInput!) {
+       productDelete(input: $input) { deletedProductId userErrors { field message } }
+     }`,
+    { input: { id: gid("Product", id) } },
+    s,
+  );
+  assertNoUserErrors(data.productDelete, "productDelete");
+  return branded(s, { deletedProductId: data.productDelete.deletedProductId });
+}
+
+// ---- Orders ----------------------------------------------------------------
+
+export async function listOrders(o: { query?: string; first?: number; after?: string; store?: string }) {
+  const s = resolveStore(o.store);
+  const data = await gql(
+    `query ($first: Int!, $after: String, $query: String) {
+       orders(first: $first, after: $after, query: $query, sortKey: CREATED_AT, reverse: true) {
+         nodes { id name createdAt displayFinancialStatus displayFulfillmentStatus
+           totalPriceSet { shopMoney { amount currencyCode } }
+           customer { id displayName defaultEmailAddress { emailAddress } } }
+         pageInfo { hasNextPage endCursor }
+       }
+     }`,
+    { ...pageArgs(o.first, o.after), query: o.query || null },
+    s,
+  );
+  return branded(s, data.orders);
+}
+
+export async function getOrder(id: string, store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `query ($id: ID!) {
+       order(id: $id) {
+         id name createdAt processedAt displayFinancialStatus displayFulfillmentStatus note tags
+         totalPriceSet { shopMoney { amount currencyCode } }
+         subtotalPriceSet { shopMoney { amount currencyCode } }
+         totalShippingPriceSet { shopMoney { amount currencyCode } }
+         customer { id displayName defaultEmailAddress { emailAddress } defaultPhoneNumber { phoneNumber } }
+         shippingAddress { name address1 address2 city provinceCode zip countryCodeV2 }
+         lineItems(first: 50) { nodes { title quantity sku variantTitle
+           originalUnitPriceSet { shopMoney { amount currencyCode } } } }
+         fulfillments { status trackingInfo { company number url } }
+       }
+     }`,
+    { id: gid("Order", id) },
+    s,
+  );
+  return branded(s, { order: data.order });
+}
+
+// ---- Customers -------------------------------------------------------------
+
+export async function listCustomers(o: { query?: string; first?: number; after?: string; store?: string }) {
+  const s = resolveStore(o.store);
+  const data = await gql(
+    `query ($first: Int!, $after: String, $query: String) {
+       customers(first: $first, after: $after, query: $query) {
+         nodes { id displayName defaultEmailAddress { emailAddress } defaultPhoneNumber { phoneNumber } createdAt numberOfOrders
+           amountSpent { amount currencyCode } }
+         pageInfo { hasNextPage endCursor }
+       }
+     }`,
+    { ...pageArgs(o.first, o.after), query: o.query || null },
+    s,
+  );
+  return branded(s, data.customers);
+}
+
+export async function getCustomer(id: string, store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `query ($id: ID!) {
+       customer(id: $id) {
+         id displayName defaultEmailAddress { emailAddress } defaultPhoneNumber { phoneNumber } note tags createdAt numberOfOrders
+         amountSpent { amount currencyCode }
+         defaultAddress { address1 address2 city provinceCode zip countryCodeV2 }
+         orders(first: 10, sortKey: CREATED_AT, reverse: true) { nodes { id name createdAt
+           totalPriceSet { shopMoney { amount currencyCode } } } }
+       }
+     }`,
+    { id: gid("Customer", id) },
+    s,
+  );
+  return branded(s, { customer: data.customer });
+}
+
+// ---- Catalog structure / storefront ---------------------------------------
+
+export async function listCollections(o: { first?: number; after?: string; store?: string }) {
+  const s = resolveStore(o.store);
+  const data = await gql(
+    `query ($first: Int!, $after: String) {
+       collections(first: $first, after: $after) {
+         nodes { id title handle updatedAt productsCount { count } }
+         pageInfo { hasNextPage endCursor }
+       }
+     }`,
+    pageArgs(o.first, o.after),
+    s,
+  );
+  return branded(s, data.collections);
+}
+
+export async function listLocations(store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `{ locations(first: 20) { nodes { id name isActive address { city provinceCode countryCode } } } }`,
+    {},
+    s,
+  );
+  return branded(s, data.locations);
+}
+
+export async function listThemes(store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `{ themes(first: 20) { nodes { id name role updatedAt } } }`,
+    {},
+    s,
+  );
+  return branded(s, data.themes);
+}
+
+// ---- Webhooks --------------------------------------------------------------
+
+export async function listWebhooks(store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `{ webhookSubscriptions(first: 50) { nodes { id topic createdAt uri } } }`,
+    {},
+    s,
+  );
+  return branded(s, data.webhookSubscriptions);
+}
+
+export async function createWebhook(topic: string, callbackUrl: string, store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `mutation ($topic: WebhookSubscriptionTopic!, $sub: WebhookSubscriptionInput!) {
+       webhookSubscriptionCreate(topic: $topic, webhookSubscription: $sub) {
+         webhookSubscription { id topic }
+         userErrors { field message }
+       }
+     }`,
+    { topic, sub: { callbackUrl, format: "JSON" } },
+    s,
+  );
+  assertNoUserErrors(data.webhookSubscriptionCreate, "webhookSubscriptionCreate");
+  return branded(s, { webhook: data.webhookSubscriptionCreate.webhookSubscription });
+}
+
+export async function deleteWebhook(id: string, store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(
+    `mutation ($id: ID!) {
+       webhookSubscriptionDelete(id: $id) { deletedWebhookSubscriptionId userErrors { field message } }
+     }`,
+    { id: gid("WebhookSubscription", id) },
+    s,
+  );
+  assertNoUserErrors(data.webhookSubscriptionDelete, "webhookSubscriptionDelete");
+  return branded(s, { deletedWebhookSubscriptionId: data.webhookSubscriptionDelete.deletedWebhookSubscriptionId });
+}
+
+// ---- Raw passthrough -------------------------------------------------------
+
+export const isMutation = (query: string): boolean =>
+  /^\s*mutation\b/i.test(query.trim().replace(/^#[^\n]*\n\s*/g, ""));
+
+export async function raw(query: string, variables?: Record<string, unknown>, store?: string) {
+  const s = resolveStore(store);
+  const data = await gql(query, variables ?? {}, s);
+  return branded(s, { data });
+}

package/mcp.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadEnv } from "./core/env.js";
+import { registerTools } from "./core/register.js";
+
+loadEnv();
+
+const server = new McpServer({ name: "shopify-mcp", version: "0.1.0" });
+registerTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(
+  "[shopify-mcp] ready v0.1.0 — multi-store Admin GraphQL, store-branded responses, confirm-gated deletes/mutations, raw passthrough.",
+);

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@theethosteam/shopify-mcp",
+  "version": "0.1.0",
+  "description": "Multi-store read + write MCP server (and CLI) for the Shopify Admin GraphQL API. Per-store custom-app tokens (SHOPIFY_STORE_<ALIAS>), store-aware responses, tiered writes (routine executes, destructive confirm-gated), raw GraphQL passthrough. Runs via npx, locally or in cloud.",
+  "type": "module",
+  "exports": {
+    "./register": "./core/register.ts"
+  },
+  "bin": {
+    "shopify-mcp": "bin/shopify-mcp.mjs",
+    "shop": "bin/shop.mjs"
+  },
+  "files": [
+    "bin",
+    "core",
+    "mcp.ts",
+    "cli.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "mcp": "node bin/shopify-mcp.mjs",
+    "shop": "node bin/shop.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "shopify",
+    "admin-api",
+    "graphql",
+    "ecommerce"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/The-Ethos-Team/connectors.git",
+    "directory": "packages/shopify-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.25.2",
+    "commander": "^15.0.0",
+    "tsx": "^4.22.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0"
+  }
+}