Add README for @shopify/mcp package

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tizmagik

package.json

@@ -229,6 +229,20 @@
           ]
         }
       },
+      "packages/mcp": {
+        "entry": [
+          "**/src/index.ts!"
+        ],
+        "project": "**/*.ts!",
+        "ignoreDependencies": [
+          "zod-to-json-schema"
+        ],
+        "vite": {
+          "config": [
+            "vite.config.ts"
+          ]
+        }
+      },
       "packages/plugin-did-you-mean": {
         "entry": [
           "**/{commands,hooks}/**/*.ts!",

packages/cli-kit/src/public/node/mcp.ts

@@ -28,7 +28,7 @@ export async function requestDeviceCode(): Promise<DeviceCodeResponse> {
   const fqdn = await identityFqdn()
   const identityClientId = clientId()
   const scopes = allDefaultScopes()
-  const params = `client_id=${identityClientId}&scope=${scopes.join(' ')}`
+  const params = new URLSearchParams({client_id: identityClientId, scope: scopes.join(' ')}).toString()
   const url = `https://${fqdn}/oauth/device_authorization`
 
   const response = await shopifyFetch(url, {

packages/mcp/README.md

@@ -0,0 +1,50 @@
+# @shopify/mcp
+
+MCP server for the Shopify Admin API. Connects AI coding agents (Claude, Cursor, etc.) to your Shopify store via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Setup
+
+```bash
+claude mcp add shopify -- npx -y -p @shopify/mcp
+```
+
+Optionally set a default store so you don't have to pass it with every request:
+
+```bash
+export SHOPIFY_FLAG_STORE=my-store.myshopify.com
+```
+
+## Tools
+
+### `shopify_auth_login`
+
+Authenticate with a Shopify store. Returns a URL the user must visit to complete login via device auth. After approval, subsequent `shopify_graphql` calls will use the session automatically.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `store` | string | No | Store domain. Defaults to `SHOPIFY_FLAG_STORE` env var. |
+
+### `shopify_graphql`
+
+Execute a GraphQL query or mutation against the Shopify Admin API. Uses the latest supported API version.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | GraphQL query or mutation string |
+| `variables` | object | No | GraphQL variables |
+| `store` | string | No | Store domain override. Defaults to `SHOPIFY_FLAG_STORE` env var. |
+| `allowMutations` | boolean | No | Must be `true` to execute mutations. Safety measure to prevent unintended changes. |
+
+## Example
+
+```
+Agent: "List my products"
+
+→ shopify_auth_login(store: "my-store.myshopify.com")
+← "Open this URL to authenticate: https://accounts.shopify.com/activate?user_code=ABCD-EFGH"
+
+[user approves in browser]
+
+→ shopify_graphql(query: "{ products(first: 5) { edges { node { title } } } }")
+← { "products": { "edges": [{ "node": { "title": "T-Shirt" } }, ...] } }
+```

packages/mcp/package.json

@@ -48,9 +48,10 @@
     ]
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.27.1",
+    "@modelcontextprotocol/sdk": "1.22.0",
     "@shopify/cli-kit": "3.91.0",
-    "zod": "3.25.76"
+    "zod": "3.24.1",
+    "zod-to-json-schema": "3.24.5"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.1.4"

packages/mcp/src/tools/graphql.test.ts

@@ -140,13 +140,25 @@ describe('handleGraphql', () => {
     expect(result.content[0]!.text).toContain('allowMutations')
   })
 
+  test('detects mutations after a query in multi-operation document', async () => {
+    process.env.SHOPIFY_FLAG_STORE = 'test.myshopify.com'
+    const sm = createMockSessionManager()
+    const result = await handleGraphql(sm, {
+      query: 'query { shop { name } }\nmutation { productDelete(input: {id: "1"}) { deletedProductId } }',
+      allowMutations: false,
+    })
+    expect(result.isError).toBe(true)
+    expect(result.content[0]!.text).toContain('allowMutations')
+  })
+
   test('mutation pattern detection', () => {
-    const pattern = /^\s*mutation[\s({]/i
+    const pattern = /(?:^|\n)\s*mutation[\s({]/i
     expect(pattern.test('mutation { shop { name } }')).toBe(true)
     expect(pattern.test('  mutation CreateProduct($input: ProductInput!) { }')).toBe(true)
     expect(pattern.test('mutation(')).toBe(true)
     expect(pattern.test('MUTATION { }')).toBe(true)
     expect(pattern.test('Mutation { }')).toBe(true)
+    expect(pattern.test('query { shop { name } }\nmutation { }')).toBe(true)
     expect(pattern.test('query { shop { name } }')).toBe(false)
     expect(pattern.test('{ shop { name } }')).toBe(false)
     expect(pattern.test('query GetMutationResults { }')).toBe(false)

packages/mcp/src/tools/graphql.ts

@@ -5,7 +5,7 @@ import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js'
 import {z} from 'zod'
 import {adminRequest} from '@shopify/cli-kit/node/api/admin'
 
-const MUTATION_PATTERN = /^\s*mutation[\s({]/i
+const MUTATION_PATTERN = /(?:^|\n)\s*mutation[\s({]/i
 
 export async function handleGraphql(
   sessionManager: SessionManager,
@@ -19,7 +19,7 @@ export async function handleGraphql(
     }
   }
 
-  const stripped = params.query.replace(/^\s*(#[^\n]*\n)*/g, '')
+  const stripped = params.query.replace(/#[^\n]*/g, '')
   if (MUTATION_PATTERN.test(stripped) && !params.allowMutations) {
     return {
       content: [{type: 'text', text: 'Error: Mutations require allowMutations: true. This is a safety measure to prevent unintended changes.'}],