shopify-store-mcp 1.0.2 → 1.0.10

package/README.md

@@ -6,44 +6,99 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
 
-A Model Context Protocol (MCP) server that connects to **live Shopify stores** via the Admin and Storefront APIs. Unlike documentation-only MCPs, this server enables AI agents to perform real operations on your store.
+A Model Context Protocol (MCP) server that connects to **live Shopify stores** via the Admin and Storefront APIs. Unlike documentation-only MCPs, this server enables AI agents to perform **real operations** on your store.
+
+## Why This MCP?
+
+| Feature | Shopify Store MCP | [Shopify Dev MCP](https://shopify.dev/docs/apps/build/devmcp) |
+|---------|-------------------|---------------------------------------------------------------|
+| Execute GraphQL queries | ✅ Real API calls | ❌ Documentation only |
+| Modify store data | ✅ Full CRUD | ❌ No |
+| Upload files | ✅ Yes | ❌ No |
+| Bulk operations | ✅ Yes | ❌ No |
+| API documentation | ❌ No | ✅ Yes |
+| Schema introspection | ❌ No | ✅ Yes |
+
+> **Important:** For the best experience, use **both** this MCP and the official [Shopify Dev MCP](https://shopify.dev/docs/apps/build/devmcp) together. The Dev MCP helps your AI agent understand Shopify's API schemas and documentation, while this MCP executes the actual operations on your store.
 
 ## Features
 
-- **Universal GraphQL Access** - Execute any Admin API query or mutation via `run_graphql_query`
-- **Smart Multi-Step Tools** - File uploads, bulk operations, metaobject upserts with automatic polling
-- **Rate Limiting** - Respects Shopify's plan-based rate limits (Standard/Advanced/Plus/Enterprise)
-- **Operation Logging** - SQLite database tracks all operations for debugging and history
-- **Schema Discovery** - Explore your store's metafield definitions and metaobject types
+- **Universal GraphQL Access** — Execute any Admin API query or mutation via `run_graphql_query`
+- **Smart Multi-Step Tools** — File uploads, bulk operations, metaobject upserts with automatic polling
+- **Rate Limiting** — Respects Shopify's plan-based rate limits (Standard/Advanced/Plus/Enterprise)
+- **Operation Logging** — SQLite database tracks all operations for debugging and history
+- **Schema Discovery** — Explore your store's metafield definitions and metaobject types
 
-## Setup
+## Prerequisites
 
-### Prerequisites
+1. **Node.js 18+**
+2. **Shopify store** with a [custom app](https://help.shopify.com/en/manual/apps/app-types/custom-apps)
+3. **Admin API access token** — Create a custom app in Shopify Admin → Settings → Apps and development channels → Develop apps
 
-1. A Shopify store with a [custom app](https://help.shopify.com/en/manual/apps/app-types/custom-apps)
-2. Admin API access token with required scopes
-3. Node.js 18+
+## Installation
 
-### Installation
+<details>
+<summary><strong>Cursor</strong></summary>
 
-```bash
-npm install -g shopify-store-mcp
+### Quick Install
+
+[![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-blue?style=for-the-badge&logo=cursor)](https://cursor.com/install-mcp?name=shopify-store-mcp&config=eyJtY3BTZXJ2ZXJzIjp7InNob3BpZnktc3RvcmUtbWNwIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15Iiwic2hvcGlmeS1zdG9yZS1tY3AiXSwiZW52Ijp7IlNIT1BJRllfU1RPUkVfVVJMIjoieW91ci1zdG9yZS5teXNob3BpZnkuY29tIiwiU0hPUElGWV9BQ0NFU1NfVE9LRU4iOiJzaHBhdF94eHh4eHh4eHh4eHh4eHh4eHh4eHgifX19fQ==)
+
+After installing, edit the configuration to add your actual store credentials.
+
+### Manual Configuration
+
+Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "shopify-store-mcp": {
+      "command": "npx",
+      "args": ["-y", "shopify-store-mcp"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
 ```
 
-Or run directly with npx:
+<details>
+<summary>Windows Configuration</summary>
 
-```bash
-npx shopify-store-mcp
+```json
+{
+  "mcpServers": {
+    "shopify-store-mcp": {
+      "command": "cmd",
+      "args": ["/k", "npx", "-y", "shopify-store-mcp"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
 ```
 
-## Usage with Claude Desktop or Cursor
+</details>
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
 
-Add the following to your MCP configuration:
+Add to your Claude Desktop config:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
-    "shopify-store": {
+    "shopify-store-mcp": {
       "command": "npx",
       "args": ["-y", "shopify-store-mcp"],
       "env": {
@@ -55,12 +110,13 @@ Add the following to your MCP configuration:
 }
 ```
 
-On Windows, use this configuration:
+<details>
+<summary>Windows Configuration</summary>
 
 ```json
 {
   "mcpServers": {
-    "shopify-store": {
+    "shopify-store-mcp": {
       "command": "cmd",
       "args": ["/k", "npx", "-y", "shopify-store-mcp"],
       "env": {
@@ -72,15 +128,131 @@ On Windows, use this configuration:
 }
 ```
 
+</details>
+
+</details>
+
+<details>
+<summary><strong>Claude Code (CLI)</strong></summary>
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "shopify-store-mcp": {
+      "command": "npx",
+      "args": ["-y", "shopify-store-mcp"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code (Copilot)</strong></summary>
+
+Add to your VS Code settings (`settings.json`):
+
+```json
+{
+  "mcp.servers": {
+    "shopify-store-mcp": {
+      "command": "npx",
+      "args": ["-y", "shopify-store-mcp"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to your Windsurf MCP config (`~/.windsurf/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "shopify-store-mcp": {
+      "command": "npx",
+      "args": ["-y", "shopify-store-mcp"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Other MCP Clients</strong></summary>
+
+For any MCP-compatible client, use:
+
+```bash
+npx -y shopify-store-mcp
+```
+
+With environment variables:
+- `SHOPIFY_STORE_URL` — Your store's myshopify.com domain
+- `SHOPIFY_ACCESS_TOKEN` — Admin API access token
+
+</details>
+
+## Recommended: Add Shopify Dev MCP
+
+For the best AI agent experience, also add the official **[Shopify Dev MCP](https://shopify.dev/docs/apps/build/devmcp)**. It provides:
+
+- API documentation search
+- GraphQL schema introspection
+- Query validation
+- Up-to-date Shopify API knowledge
+
+This helps your AI agent know **what queries to write** before executing them with this MCP.
+
+```json
+{
+  "mcpServers": {
+    "shopify-store-mcp": {
+      "command": "npx",
+      "args": ["-y", "shopify-store-mcp"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxxx"
+      }
+    },
+    "shopify-dev-mcp": {
+      "command": "npx",
+      "args": ["-y", "@shopify/dev-mcp@latest"]
+    }
+  }
+}
+```
+
 ## Environment Variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `SHOPIFY_STORE_URL` | Yes | - | Store's myshopify.com domain |
-| `SHOPIFY_ACCESS_TOKEN` | Yes | - | Admin API access token |
-| `SHOPIFY_STOREFRONT_ACCESS_TOKEN` | No | - | Storefront API token |
-| `SHOPIFY_API_VERSION` | No | `2025-01` | API version |
+| `SHOPIFY_STORE_URL` | Yes | — | Store's myshopify.com domain |
+| `SHOPIFY_ACCESS_TOKEN` | Yes | — | Admin API access token |
+| `SHOPIFY_STOREFRONT_ACCESS_TOKEN` | No | — | Storefront API token |
+| `SHOPIFY_API_VERSION` | No | `2026-01` | API version (or `unstable` for bleeding edge) |
 | `SHOPIFY_TIER` | No | `STANDARD` | Rate limit tier |
+| `MCP_LOG_OPERATIONS` | No | `true` | Enable operation logging |
 
 ## Available Tools
 
@@ -88,17 +260,20 @@ On Windows, use this configuration:
 
 | Tool | Description |
 |------|-------------|
-| `get_shop_info` | Retrieve store configuration and settings |
-| `run_graphql_query` | Execute any GraphQL query or mutation |
+| `get_shop_info` | Retrieve store configuration, plan info, and settings |
+| `run_graphql_query` | **Universal tool** — Execute any GraphQL query or mutation |
 
 ### Smart Tools
 
+Multi-step workflows that handle complexity automatically:
+
 | Tool | Description |
 |------|-------------|
-| `upload_file` | Upload file from URL, poll until ready, return CDN URL |
-| `bulk_export` | Start bulk query, poll completion, return JSONL download URL |
-| `bulk_import` | Staged upload + bulk mutation with automatic polling |
+| `upload_file` | Upload file (URL, local path, or base64) → poll until ready → return CDN URL |
+| `bulk_export` | Start bulk query → poll completion → return JSONL download URL |
+| `bulk_import` | Staged upload → bulk mutation → poll completion |
 | `upsert_metaobject` | Create or update metaobject by handle (idempotent) |
+| `delete_metaobject` | Delete metaobject by ID or type+handle |
 | `schema_discover` | Discover metafield definitions and metaobject types |
 
 ### Infrastructure Tools
@@ -107,20 +282,20 @@ On Windows, use this configuration:
 |------|-------------|
 | `configure` | Set rate limit tier (manual or auto-detect from shop plan) |
 | `get_history` | Query past operations for debugging |
-| `get_stats` | Aggregated usage statistics |
+| `get_stats` | Aggregated usage statistics (calls, errors, response times) |
 
 ## Rate Limiting
 
-The server respects Shopify's rate limits based on your shop plan:
+The server automatically respects Shopify's rate limits based on your shop plan:
 
 | Tier | Requests/sec | Plans |
 |------|--------------|-------|
-| STANDARD | 1 | Basic, Development, Lite |
-| ADVANCED | 2 | Advanced |
-| PLUS | 5 | Shopify Plus |
-| ENTERPRISE | 10 | Commerce Components |
+| `STANDARD` | 1 | Basic, Development, Lite |
+| `ADVANCED` | 2 | Advanced |
+| `PLUS` | 5 | Shopify Plus |
+| `ENTERPRISE` | 10 | Commerce Components |
 
-Use the `configure` tool to set your tier manually or auto-detect from your shop plan.
+Use the `configure` tool to set your tier or auto-detect from your shop plan.
 
 ## Available Prompts
 
@@ -144,35 +319,43 @@ Use the `configure` tool to set your tier manually or auto-detect from your shop
 ## Development
 
 ```bash
+# Clone the repo
+git clone https://github.com/Brahim-Benzarti/Shopify_store-MCP.git
+cd Shopify_store-MCP
+
 # Install dependencies
 npm install
 
 # Build
 npm run build
 
-# Run with inspector
+# Run with MCP Inspector
 npm run inspect
 
 # Watch mode
 npm run dev
-```
-
-### Database
 
-The server uses SQLite for operation logging and configuration. The database is automatically created at `~/.shopify-mcp/mcp.db`.
-
-```bash
 # View database
 npm run db:studio
 ```
 
+### Database
+
+The server uses SQLite for operation logging and configuration. Database is automatically created at `~/.shopify-mcp/mcp.db`.
+
 ## Security
 
-- Never commit your `.env` file or access tokens
-- Use environment variables or MCP config for credentials
-- Access tokens should have minimal required scopes
-- The server logs operations locally for debugging (disable with `MCP_LOG_OPERATIONS=false`)
+- **Never commit** your `.env` file or access tokens
+- Use **environment variables** or MCP config for credentials
+- Access tokens should have **minimal required scopes**
+- Operations are logged locally for debugging (disable with `MCP_LOG_OPERATIONS=false`)
 
 ## License
 
-ISC
+[ISC](LICENSE)
+
+## Related
+
+- [Shopify Dev MCP](https://shopify.dev/docs/apps/build/devmcp) — Official Shopify MCP for API documentation
+- [Shopify Admin API](https://shopify.dev/docs/api/admin-graphql) — GraphQL API reference
+- [Model Context Protocol](https://modelcontextprotocol.io/) — MCP specification

package/dist/config.js

@@ -16,7 +16,7 @@ export function loadConfig() {
     const adminAccessToken = process.env.SHOPIFY_ACCESS_TOKEN;
     const storefrontAccessToken = process.env.SHOPIFY_STOREFRONT_ACCESS_TOKEN;
     const customerAccessToken = process.env.SHOPIFY_CUSTOMER_ACCESS_TOKEN;
-    const apiVersion = process.env.SHOPIFY_API_VERSION || "2025-01";
+    const apiVersion = process.env.SHOPIFY_API_VERSION || "2026-01";
     const bugReportEnabled = process.env.SHOPIFY_MCP_BUG_REPORTS === "true";
     const bugReportBaseDir = process.env.SHOPIFY_MCP_BUG_REPORT_DIR;
     if (!storeDomain) {

package/dist/errors.js

@@ -59,7 +59,7 @@ export function formatGraphQLErrors(response) {
     };
 }
 export function formatUserErrors(userErrors) {
-    const lines = userErrors.map((e) => `- ${e.field.join(".")}: ${e.message}`);
+    const lines = userErrors.map((e) => `- ${e.field?.join(".") || "general"}: ${e.message}`);
     return {
         content: [
             {

package/dist/graphql/admin/specialized/bulk.d.ts

@@ -14,12 +14,22 @@ export declare const BULK_OPERATION_RUN_QUERY = "#graphql\n  mutation BulkOperat
  */
 export declare const BULK_OPERATION_RUN_MUTATION = "#graphql\n  mutation BulkOperationRunMutation($mutation: String!, $stagedUploadPath: String!) {\n    bulkOperationRunMutation(mutation: $mutation, stagedUploadPath: $stagedUploadPath) {\n      bulkOperation {\n        id\n        status\n        url\n        objectCount\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\n";
 /**
- * Get current bulk operation status
- * Only one bulk operation can run at a time per app
+ * Get current bulk operation status (for queries)
+ * Deprecated in 2026-01, use GET_BULK_OPERATION_BY_ID instead
  */
 export declare const GET_CURRENT_BULK_OPERATION = "#graphql\n  query GetCurrentBulkOperation {\n    currentBulkOperation {\n      id\n      type\n      status\n      query\n      url\n      rootObjectCount\n      objectCount\n      fileSize\n      partialDataUrl\n      errorCode\n      createdAt\n      completedAt\n    }\n  }\n";
 /**
- * Get a specific bulk operation by ID
+ * Get current bulk MUTATION operation status
+ * Required for polling mutation status in versions < 2026-01
+ */
+export declare const GET_CURRENT_BULK_MUTATION = "#graphql\n  query GetCurrentBulkMutation {\n    currentBulkOperation(type: MUTATION) {\n      id\n      type\n      status\n      url\n      objectCount\n      fileSize\n      partialDataUrl\n      errorCode\n      createdAt\n      completedAt\n    }\n  }\n";
+/**
+ * Get a specific bulk operation by ID (API version 2026-01+)
+ * Use this for polling both queries and mutations
+ */
+export declare const GET_BULK_OPERATION_BY_ID = "#graphql\n  query GetBulkOperationById($id: ID!) {\n    bulkOperation(id: $id) {\n      id\n      type\n      status\n      url\n      objectCount\n      fileSize\n      partialDataUrl\n      errorCode\n      createdAt\n      completedAt\n    }\n  }\n";
+/**
+ * Get a specific bulk operation by ID (legacy node query)
  */
 export declare const GET_BULK_OPERATION = "#graphql\n  query GetBulkOperation($id: ID!) {\n    node(id: $id) {\n      ... on BulkOperation {\n        id\n        type\n        status\n        query\n        url\n        rootObjectCount\n        objectCount\n        fileSize\n        partialDataUrl\n        errorCode\n        createdAt\n        completedAt\n      }\n    }\n  }\n";
 /**

package/dist/graphql/admin/specialized/bulk.js

@@ -46,8 +46,8 @@ export const BULK_OPERATION_RUN_MUTATION = `#graphql
   }
 `;
 /**
- * Get current bulk operation status
- * Only one bulk operation can run at a time per app
+ * Get current bulk operation status (for queries)
+ * Deprecated in 2026-01, use GET_BULK_OPERATION_BY_ID instead
  */
 export const GET_CURRENT_BULK_OPERATION = `#graphql
   query GetCurrentBulkOperation {
@@ -68,7 +68,47 @@ export const GET_CURRENT_BULK_OPERATION = `#graphql
   }
 `;
 /**
- * Get a specific bulk operation by ID
+ * Get current bulk MUTATION operation status
+ * Required for polling mutation status in versions < 2026-01
+ */
+export const GET_CURRENT_BULK_MUTATION = `#graphql
+  query GetCurrentBulkMutation {
+    currentBulkOperation(type: MUTATION) {
+      id
+      type
+      status
+      url
+      objectCount
+      fileSize
+      partialDataUrl
+      errorCode
+      createdAt
+      completedAt
+    }
+  }
+`;
+/**
+ * Get a specific bulk operation by ID (API version 2026-01+)
+ * Use this for polling both queries and mutations
+ */
+export const GET_BULK_OPERATION_BY_ID = `#graphql
+  query GetBulkOperationById($id: ID!) {
+    bulkOperation(id: $id) {
+      id
+      type
+      status
+      url
+      objectCount
+      fileSize
+      partialDataUrl
+      errorCode
+      createdAt
+      completedAt
+    }
+  }
+`;
+/**
+ * Get a specific bulk operation by ID (legacy node query)
  */
 export const GET_BULK_OPERATION = `#graphql
   query GetBulkOperation($id: ID!) {

package/dist/resources/index.js

@@ -172,6 +172,134 @@ tag:vip orders_count:>3
 If a tool returns a 403 error, it likely means your custom app is missing the required scope. Update your app's API access scopes in:
 
 **Shopify Admin → Settings → Apps and sales channels → Develop apps → [Your App] → Configuration**
+`,
+            },
+        ],
+    }));
+    // Smart Tools Reference
+    server.registerResource("smart-tools", "shopify://docs/smart-tools", {
+        title: "Smart Tools Reference",
+        description: "Reference guide for smart multi-step tools that handle complex workflows automatically.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "shopify://docs/smart-tools",
+                mimeType: "text/markdown",
+                text: `# Smart Tools Reference
+
+Smart tools handle complex multi-step workflows automatically, including polling and staged uploads.
+
+## upload_file
+
+Upload files to Shopify with automatic status polling. Returns the final CDN URL when ready.
+
+### Mode 1: External URL
+Shopify fetches the file from a publicly accessible URL.
+
+\`\`\`json
+{
+  "url": "https://example.com/image.jpg",
+  "alt": "Product image"
+}
+\`\`\`
+
+### Mode 2: Local File Path (Recommended for large files)
+Read file directly from disk. MIME type is auto-detected.
+
+\`\`\`json
+{
+  "filePath": "/path/to/document.pdf",
+  "alt": "Product manual"
+}
+\`\`\`
+
+### Mode 3: Base64 Content (Small files only, < 5MB)
+For small files when you already have the content encoded.
+
+\`\`\`json
+{
+  "content": "iVBORw0KGgoAAAANSUhEUgAA...",
+  "filename": "photo.jpg",
+  "mimeType": "image/jpeg"
+}
+\`\`\`
+
+**Required for Mode 3:** \`content\`, \`filename\`, \`mimeType\`
+
+### Content Types
+- \`IMAGE\` - jpg, png, gif, webp, svg
+- \`VIDEO\` - mp4, mov, webm
+- \`FILE\` - pdf, documents, other files
+
+## bulk_export
+
+Export large datasets to JSONL format.
+
+\`\`\`json
+{
+  "query": "{ products { edges { node { id title } } } }"
+}
+\`\`\`
+
+Returns a download URL for the JSONL file when complete.
+
+## bulk_import
+
+Import data via bulk mutations.
+
+\`\`\`json
+{
+  "mutation": "mutation($input: ProductInput!) { productUpdate(input: $input) { product { id } } }",
+  "jsonlUrl": "https://example.com/data.jsonl"
+}
+\`\`\`
+
+## upsert_metaobject
+
+Create or update a metaobject by handle (idempotent).
+
+\`\`\`json
+{
+  "type": "color_swatch",
+  "handle": "navy-blue",
+  "fields": [
+    { "key": "name", "value": "Navy Blue" },
+    { "key": "hex", "value": "#000080" }
+  ]
+}
+\`\`\`
+
+## delete_metaobject
+
+Delete a metaobject by ID or by type+handle.
+
+\`\`\`json
+{
+  "id": "gid://shopify/Metaobject/123456789"
+}
+\`\`\`
+
+Or by type and handle:
+
+\`\`\`json
+{
+  "type": "color_swatch",
+  "handle": "navy-blue"
+}
+\`\`\`
+
+## schema_discover
+
+Discover custom schema definitions in the store.
+
+\`\`\`json
+{
+  "includeMetafields": true,
+  "includeMetaobjects": true,
+  "metafieldOwnerTypes": ["PRODUCT", "VARIANT"]
+}
+\`\`\`
 `,
             },
         ],

package/dist/tools/graphql.d.ts

@@ -1,3 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { AdminApiClient } from "../shopify-client.js";
-export declare function registerGraphQLTools(server: McpServer, client: AdminApiClient): void;
+export declare function registerGraphQLTools(server: McpServer, client: AdminApiClient, storeDomain: string): void;

package/dist/tools/graphql.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { formatSuccessResponse, formatGraphQLErrors, formatErrorResponse, } from "../errors.js";
-export function registerGraphQLTools(server, client) {
+import { enqueue } from "../queue.js";
+import { logOperation } from "../logger.js";
+export function registerGraphQLTools(server, client, storeDomain) {
     server.registerTool("run_graphql_query", {
         title: "Run GraphQL Query",
         description: "Execute any GraphQL query or mutation against the Shopify Admin API. " +
@@ -24,16 +26,45 @@ export function registerGraphQLTools(server, client) {
             openWorldHint: true,
         },
     }, async ({ query, variables }) => {
+        const startTime = Date.now();
         try {
-            const response = await client.request(query, {
+            const response = await enqueue(() => client.request(query, {
                 variables: variables,
-            });
+            }));
             if (response.errors) {
+                await logOperation({
+                    storeDomain,
+                    toolName: "run_graphql_query",
+                    query,
+                    variables,
+                    response,
+                    success: false,
+                    errorMessage: "GraphQL errors",
+                    durationMs: Date.now() - startTime,
+                });
                 return formatGraphQLErrors(response);
             }
+            await logOperation({
+                storeDomain,
+                toolName: "run_graphql_query",
+                query,
+                variables,
+                response: response.data,
+                success: true,
+                durationMs: Date.now() - startTime,
+            });
             return formatSuccessResponse(response.data);
         }
         catch (error) {
+            await logOperation({
+                storeDomain,
+                toolName: "run_graphql_query",
+                query,
+                variables,
+                success: false,
+                errorMessage: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startTime,
+            });
             return formatErrorResponse(error);
         }
     });