shopify-graphql-extension-mcp 2.0.0

package/README.md

@@ -0,0 +1,107 @@
+# shopify-graphql-extension-mcp
+
+MCP server that runs Shopify Admin GraphQL through the Shopify GraphQL API Client
+Chrome extension's browser session. Any MCP client (Claude Code, Cursor, Claude
+Desktop, etc.) can query or mutate any Shopify store you have open in the browser
+— no API tokens, no app install. Pairs with the Chrome extension (hence the name).
+
+## How it works
+
+```
+MCP client  ──stdio MCP──►  this server  ──ws://127.0.0.1:6789──►  extension service worker
+                                                                       │  chrome.tabs.sendMessage
+                                                                       ▼
+                                                             content script → store Admin API
+```
+
+A Chrome MV3 service worker can't listen on a port, only dial out — so the server
+is the WebSocket host and the extension connects to it. Runs on plain Node (no
+Bun) so it ships to npm and launches with `npx`.
+
+## Install
+
+Install the extension first (from the Chrome Web Store), then add the MCP server.
+
+Claude Code:
+
+```bash
+claude mcp add shopify-admin -- npx -y shopify-graphql-extension-mcp
+```
+
+Other MCP clients (Cursor, Claude Desktop, …):
+
+```json
+{
+  "mcpServers": {
+    "shopify-admin": {
+      "command": "npx",
+      "args": ["-y", "shopify-graphql-extension-mcp"]
+    }
+  }
+}
+```
+
+Keep an `admin.shopify.com` tab open; the extension reconnects to the server
+automatically and the extension's MCP tab shows the live status.
+
+## Local development
+
+```bash
+cd mcp-bridge
+bun install
+bun run build          # bundle to dist/index.js for publishing
+node dist/index.js     # or: bun run src/index.ts
+```
+
+The wire contract is shared from `../chrome-extension/src/lib/bridge-protocol.ts`
+(single source of truth, inlined into the bundle at build time, reusable by the
+cloud relay later).
+
+Requires `jq` (used by the mutation approval hook below).
+
+## Tools
+
+- `list_stores` — the stores currently open in the browser (handle + domain).
+- `run_graphql` — run a read-only QUERY. Mutations are rejected with a pointer to
+  the mutation tool. Args: `query`, `variables?`, `store?` (handle or domain;
+  required only when more than one store is open), `apiVersion?`.
+- `run_graphql_mutation` — run a MUTATION (write). Same args. Reads are rejected.
+  This split lets the approval gate target writes only.
+
+## Mutation approval
+
+Writes are gated in the MCP client, not the bridge, so they survive
+`--dangerously-skip-permissions`:
+
+1. An `ask` rule in `~/.claude/settings.json`:
+   `"permissions": { "ask": ["mcp__shopify-admin__run_graphql_mutation"] }`.
+2. A `PreToolUse` hook (`hooks/mutation-ask.sh`) that summarizes the mutation
+   into a readable prompt and forces the `ask`. Wire it in settings.json with a
+   matcher of `mcp__shopify-admin__run_graphql_mutation`.
+
+Hook changes load at Claude Code startup, so restart after editing them.
+
+## Subscription gate
+
+Every tool call checks the user's subscription (trial or active) via the
+extension. Non-subscribers get a message with a checkout link.
+
+## Auth (bridge ↔ extension)
+
+The WS server accepts a connection only if it presents `?token=<SHOPIFY_BRIDGE_TOKEN>`
+(when that env var is set), otherwise it requires a `chrome-extension://` origin.
+To use a token: start the bridge with `SHOPIFY_BRIDGE_TOKEN=<secret>` and set the
+same value as `bridgeToken` in the extension's `chrome.storage.local`.
+
+## Config
+
+- `SHOPIFY_BRIDGE_PORT` — bridge WS port (default `6789`). If you change it, also
+  set `bridgePort` in the extension's `chrome.storage.local`.
+- `SHOPIFY_BRIDGE_TOKEN` — optional shared secret (see Auth above).
+
+## Notes / current limits
+
+- One bridge owns the port. On startup the bridge evicts any stale process
+  holding the port, so the newest bridge (the one your MCP client talks to)
+  always wins.
+- Works only while Chrome is open with a logged-in Shopify session in a tab.

package/dist/broker.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+// src/broker.ts
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
+import { randomUUID } from "node:crypto";
+
+// ../chrome-extension/src/lib/bridge-protocol.ts
+var BRIDGE_DEFAULT_PORT = 6789;
+var BRIDGE_PROTOCOL_VERSION = 1;
+
+// src/broker.ts
+var PORT = Number(process.env.SHOPIFY_BRIDGE_PORT ?? BRIDGE_DEFAULT_PORT);
+var TOKEN = process.env.SHOPIFY_BRIDGE_TOKEN ?? "";
+var REQUEST_TIMEOUT_MS = 6e4;
+var log = (...args) => console.error("[broker]", ...args);
+var extensionSocket = null;
+var inflight = /* @__PURE__ */ new Map();
+function extensionAuthorized(req) {
+  if (TOKEN) {
+    return new URL(req.url ?? "", "http://127.0.0.1").searchParams.get("token") === TOKEN;
+  }
+  return (req.headers.origin ?? "").startsWith("chrome-extension://");
+}
+var wss = new WebSocketServer({ noServer: true });
+var httpServer = createServer((_req, res) => {
+  res.writeHead(200, { "content-type": "text/plain" });
+  res.end("Shopify MCP broker");
+});
+httpServer.on("upgrade", (req, socket, head) => {
+  const role = new URL(req.url ?? "", "http://127.0.0.1").searchParams.get("role");
+  if (role === "mcp") {
+    wss.handleUpgrade(req, socket, head, (ws) => onMcpConnect(ws));
+    return;
+  }
+  if (!extensionAuthorized(req)) {
+    log("rejected extension connection (origin:", req.headers.origin ?? "(none)", ")");
+    socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+    socket.destroy();
+    return;
+  }
+  wss.handleUpgrade(req, socket, head, (ws) => onExtensionConnect(ws));
+});
+function onExtensionConnect(ws) {
+  if (extensionSocket && extensionSocket !== ws) {
+    try {
+      extensionSocket.close();
+    } catch {
+    }
+  }
+  extensionSocket = ws;
+  ws.send(JSON.stringify({ kind: "hello", role: "broker", protocolVersion: BRIDGE_PROTOCOL_VERSION }));
+  log("extension connected");
+  ws.on("message", (data) => {
+    let frame;
+    try {
+      frame = JSON.parse(String(data));
+    } catch {
+      return;
+    }
+    if (frame.kind !== "response") return;
+    const entry = inflight.get(frame.id);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    inflight.delete(frame.id);
+    try {
+      entry.mcp.send(JSON.stringify({ ...frame, id: entry.originalId }));
+    } catch {
+    }
+  });
+  ws.on("close", () => {
+    if (extensionSocket === ws) {
+      extensionSocket = null;
+      failInflight((e) => true, "Extension disconnected while a request was in flight.");
+    }
+    log("extension disconnected");
+  });
+}
+function onMcpConnect(ws) {
+  log("mcp client connected");
+  ws.on("message", (data) => {
+    let frame;
+    try {
+      frame = JSON.parse(String(data));
+    } catch {
+      return;
+    }
+    if (frame.kind === "ping" || frame.kind === "hello") return;
+    if (frame.kind !== "request") return;
+    if (!extensionSocket) {
+      ws.send(JSON.stringify({
+        kind: "response",
+        id: frame.id,
+        ok: false,
+        error: "The Shopify extension is not connected. Open Chrome with the extension installed and at least one admin.shopify.com tab open."
+      }));
+      return;
+    }
+    const brokerId = randomUUID();
+    const timer = setTimeout(() => {
+      inflight.delete(brokerId);
+      try {
+        ws.send(JSON.stringify({ kind: "response", id: frame.id, ok: false, error: `Timed out after ${REQUEST_TIMEOUT_MS}ms waiting for the extension.` }));
+      } catch {
+      }
+    }, REQUEST_TIMEOUT_MS);
+    inflight.set(brokerId, { mcp: ws, originalId: frame.id, timer });
+    extensionSocket.send(JSON.stringify({ kind: "request", id: brokerId, method: frame.method, params: frame.params }));
+  });
+  ws.on("close", () => {
+    failInflight((e) => e.mcp === ws, "MCP client disconnected.");
+    log("mcp client disconnected");
+  });
+}
+function failInflight(match, reason) {
+  for (const [id, e] of inflight) {
+    if (!match(e)) continue;
+    clearTimeout(e.timer);
+    inflight.delete(id);
+    try {
+      e.mcp.send(JSON.stringify({ kind: "response", id: e.originalId, ok: false, error: reason }));
+    } catch {
+    }
+  }
+}
+httpServer.on("error", (err) => {
+  if (err.code === "EADDRINUSE") {
+    log("another broker already owns the port; exiting");
+    process.exit(0);
+  }
+  log("fatal server error:", err.message);
+  process.exit(1);
+});
+httpServer.listen(PORT, "127.0.0.1", () => log(`broker listening on ws://127.0.0.1:${PORT}`));

package/dist/index.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import WebSocket from "ws";
+
+// ../chrome-extension/src/lib/bridge-protocol.ts
+var BRIDGE_DEFAULT_PORT = 6789;
+function isMutation(query) {
+  const stripped = query.replace(/"""[\s\S]*?"""/g, '""').replace(/"(?:[^"\\]|\\.)*"/g, '""').replace(/\/\*[\s\S]*?\*\//g, " ").replace(/#[^\n]*/g, " ").trim();
+  return /^mutation\b/i.test(stripped);
+}
+
+// src/index.ts
+var PORT = Number(process.env.SHOPIFY_BRIDGE_PORT ?? BRIDGE_DEFAULT_PORT);
+var TOKEN = process.env.SHOPIFY_BRIDGE_TOKEN ?? "";
+var REQUEST_TIMEOUT_MS = 6e4;
+var log = (...args) => console.error("[mcp]", ...args);
+var BROKER_URL = `ws://127.0.0.1:${PORT}/?role=mcp${TOKEN ? `&token=${encodeURIComponent(TOKEN)}` : ""}`;
+var BROKER_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "broker.js");
+var socket = null;
+var connecting = false;
+var spawnedThisCycle = false;
+var pending = /* @__PURE__ */ new Map();
+function spawnBroker() {
+  if (spawnedThisCycle) return;
+  spawnedThisCycle = true;
+  try {
+    const child = spawn(process.execPath, [BROKER_SCRIPT], { detached: true, stdio: "ignore" });
+    child.unref();
+    log("spawned broker");
+  } catch (err) {
+    log("failed to spawn broker:", err instanceof Error ? err.message : String(err));
+  }
+}
+function connect() {
+  if (connecting || socket?.readyState === WebSocket.OPEN || socket?.readyState === WebSocket.CONNECTING) return;
+  connecting = true;
+  const ws = new WebSocket(BROKER_URL);
+  socket = ws;
+  ws.on("open", () => {
+    connecting = false;
+    spawnedThisCycle = false;
+    log("connected to broker");
+  });
+  ws.on("message", (data) => {
+    let frame;
+    try {
+      frame = JSON.parse(String(data));
+    } catch {
+      return;
+    }
+    if (frame.kind !== "response") return;
+    const p = pending.get(frame.id);
+    if (!p) return;
+    clearTimeout(p.timer);
+    pending.delete(frame.id);
+    if (frame.ok) p.resolve(frame.result);
+    else p.reject(new Error(frame.error ?? "Unknown bridge error"));
+  });
+  ws.on("error", () => {
+    spawnBroker();
+  });
+  ws.on("close", () => {
+    connecting = false;
+    if (socket === ws) socket = null;
+    spawnedThisCycle = false;
+    setTimeout(connect, 300 + Math.floor(Math.random() * 400));
+  });
+}
+connect();
+function callBroker(method, params) {
+  return new Promise((resolve, reject) => {
+    if (socket?.readyState !== WebSocket.OPEN) {
+      connect();
+      reject(new Error("Connecting to the bridge. Make sure Chrome is open with the extension installed and an admin.shopify.com tab open, then try again."));
+      return;
+    }
+    const id = randomUUID();
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`Timed out after ${REQUEST_TIMEOUT_MS}ms waiting for the extension.`));
+    }, REQUEST_TIMEOUT_MS);
+    pending.set(id, { resolve, reject, timer });
+    socket.send(JSON.stringify({ kind: "request", id, method, params }));
+  });
+}
+var server = new McpServer({ name: "shopify-admin", version: "2.0.0" });
+server.tool(
+  "list_stores",
+  "List the Shopify stores currently open in the browser (admin.shopify.com tabs). Returns each store's handle and myshopify domain. Pass a handle or domain as the `store` argument to run_graphql when more than one store is open.",
+  {},
+  async () => {
+    const stores = await callBroker("list_stores", {});
+    if (!stores || stores.length === 0) {
+      return {
+        content: [{ type: "text", text: "No Shopify admin tabs are open. Open admin.shopify.com in Chrome for the store you want to use." }],
+        isError: true
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(stores, null, 2) }] };
+  }
+);
+var graphqlArgs = {
+  query: z.string().describe("The GraphQL operation."),
+  variables: z.record(z.any()).optional().describe("GraphQL variables, as an object."),
+  store: z.string().optional().describe("Store handle or myshopify domain. Required only when more than one store is open."),
+  apiVersion: z.string().optional().describe('Admin API version, e.g. "2026-04". Defaults to the extension default.')
+};
+async function forwardGraphql(args) {
+  try {
+    const data = await callBroker("run_graphql", args);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  } catch (err) {
+    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+  }
+}
+server.tool(
+  "run_graphql",
+  "Run a read-only GraphQL QUERY against a Shopify store's Admin API using the merchant's browser session \u2014 no API token required. Use this for queries only. For mutations (create/update/delete), use run_graphql_mutation, which asks the user for approval first. The store must be open in a browser tab. Returns the raw GraphQL JSON ({ data, errors }). The first 50 calls (queries + mutations combined) are free; after that the tool returns a 'Free tier limit reached' error with a link to subscribe \u2014 relay that upgrade step to the user.",
+  graphqlArgs,
+  async ({ query, variables, store, apiVersion }) => {
+    if (isMutation(query)) {
+      return { content: [{ type: "text", text: "This is a mutation (write). Use the run_graphql_mutation tool instead \u2014 it requires the user to approve the write." }], isError: true };
+    }
+    return forwardGraphql({ query, variables, store, apiVersion });
+  }
+);
+server.tool(
+  "run_graphql_mutation",
+  "Run a GraphQL MUTATION (create/update/delete) against a Shopify store's Admin API using the merchant's browser session \u2014 no API token required. This writes to live store data, so the user is asked to approve each call. Use run_graphql for read-only queries. The store must be open in a browser tab. Returns the raw GraphQL JSON ({ data, errors }). The first 50 calls (queries + mutations combined) are free; after that the tool returns a 'Free tier limit reached' error with a link to subscribe \u2014 relay that upgrade step to the user.",
+  graphqlArgs,
+  async ({ query, variables, store, apiVersion }) => {
+    if (!isMutation(query)) {
+      return { content: [{ type: "text", text: "This is not a mutation. Use the run_graphql tool for read-only queries." }], isError: true };
+    }
+    return forwardGraphql({ query, variables, store, apiVersion });
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+log("MCP server ready on stdio");

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "shopify-graphql-extension-mcp",
+  "version": "2.0.0",
+  "description": "MCP server that runs Shopify Admin GraphQL through the Shopify GraphQL API Client Chrome extension's browser session — no API tokens.",
+  "type": "module",
+  "bin": {
+    "shopify-graphql-extension-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts src/broker.ts --bundle --packages=external --platform=node --format=esm --outdir=dist --banner:js='#!/usr/bin/env node'",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "shopify",
+    "graphql",
+    "shopify-admin-api",
+    "chrome-extension"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/ws": "^8.5.12",
+    "esbuild": "^0.24.0"
+  }
+}