@anton.andrusenko/shopify-mcp-admin 0.7.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @anton.andrusenko/shopify-mcp-admin
 
-> 🛍️ **MCP Server for Shopify Admin API** — Enable AI agents to manage Shopify stores with 71 powerful tools
+> 🛍️ **MCP Server for Shopify Admin API** — Enable AI agents to manage Shopify stores with 81 powerful tools
 
 [![npm version](https://badge.fury.io/js/@anton.andrusenko%2Fshopify-mcp-admin.svg)](https://www.npmjs.com/package/@anton.andrusenko/shopify-mcp-admin)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -11,7 +11,8 @@
 
 ## ✨ Features
 
-- 🛠️ **71 MCP Tools** — Complete store management: products, inventory, collections, pages, blogs, redirects, metafields, markets, locales & translations
+- 🛠️ **81 MCP Tools** — Complete store management: products, inventory, collections, pages, blogs, redirects, metafields, markets, locales & translations
+- 📦 **Modular Architecture** — 7 modules with lazy loading for optimal AI performance (see [Tool Modules](#-tool-modules))
 - 🤖 **AI-Optimized** — Tool descriptions and error messages designed for LLM comprehension
 - 🔌 **Dual Transport** — STDIO for Claude Desktop, HTTP for ChatGPT/OpenAI
 - ⚡ **Rate Limiting** — Automatic retry with exponential backoff for Shopify API limits
@@ -107,6 +108,8 @@ Tokens are automatically refreshed every 24 hours.
 | `PORT` | No | `3000` | HTTP server port (when `TRANSPORT=http`) |
 | `DEBUG` | No | — | Enable debug logging (`1` or `true`) |
 | `LOG_LEVEL` | No | `info` | Log level: `debug`, `info`, `warn`, `error` |
+| `SHOPIFY_MCP_LAZY_LOADING` | No | `true` | Enable modular lazy loading (set to `false` for all tools at startup) |
+| `SHOPIFY_MCP_ROLE` | No | — | Role preset for automatic module loading (see [Role Presets](#-role-presets)) |
 
 **⚡ Authentication:** Provide EITHER `SHOPIFY_ACCESS_TOKEN` (legacy) OR both `SHOPIFY_CLIENT_ID` and `SHOPIFY_CLIENT_SECRET` (Dev Dashboard).
 
@@ -248,16 +251,114 @@ Each tool can be converted to OpenAI function format:
 
 ---
 
+## 🎭 Role Presets
+
+Role presets automatically load appropriate tool modules at startup, optimizing the tool set for specific workflows and reducing AI context overhead.
+
+### Available Presets
+
+| Preset | Modules | Tools | Use Case |
+|--------|---------|-------|----------|
+| `inventory-manager` | core | 15 | Stock management and inventory operations |
+| `product-manager` | core, store-context, collections, product-extensions | 41 | Full product catalog management |
+| `content-manager` | core, content | 37 | Pages, blogs, and content marketing |
+| `seo-specialist` | core, collections, product-extensions, advanced-redirects | 38 | SEO optimization and URL management |
+| `international-manager` | core, store-context, international, collections | 46 | Multi-market and translation management |
+| `full-access` | All 7 modules | 81 | Full store administration |
+
+### Using Role Presets
+
+Set the `SHOPIFY_MCP_ROLE` environment variable:
+
+```bash
+export SHOPIFY_MCP_ROLE=product-manager
+npx @anton.andrusenko/shopify-mcp-admin
+```
+
+Or in Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "shopify": {
+      "command": "npx",
+      "args": ["-y", "@anton.andrusenko/shopify-mcp-admin"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
+        "SHOPIFY_MCP_ROLE": "product-manager"
+      }
+    }
+  }
+}
+```
+
+### Module Discovery
+
+If no role is set, the server starts with core tools only (15 tools). AI agents can discover and load additional modules dynamically:
+
+1. **Discover modules**: Use `list-modules` to see available modules
+2. **Load modules**: Use `load-module` with the module name to enable tools
+3. **Suggestions**: Tool responses include suggestions for relevant modules to load
+
+---
+
 ## 🛠️ Available Tools
 
-@anton.andrusenko/shopify-mcp-admin provides **71 tools** organized into 16 categories:
+@anton.andrusenko/shopify-mcp-admin provides **81 tools** (79 domain tools + 2 meta-tools) organized into 16 categories:
 
 <details>
-<summary><strong>🏪 Store Info (1 tool)</strong></summary>
+<summary><strong>🏪 Store Info (9 tools)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
 | `get-store-info` | Get basic store information (name, domain, plan, currency, timezone, email) |
+| `get-store-limits` | Get store resource limits (max variants, max options, location limit) |
+| `get-store-features` | Get feature flags (gift cards, reports, storefront, bundles, subscriptions) |
+| `get-store-currencies` | Get multi-currency configuration (base currency, presentment currencies, formats) |
+| `get-store-shipping` | Get shipping configuration (ships-to countries, countries in shipping zones) |
+| `get-store-domain` | Get primary domain configuration (hostname, URL, SSL status) |
+| `get-store-taxes` | Get tax configuration (taxes included in prices, tax shipping) |
+| `get-store-policies` | Get legal policies (privacy, terms of service, refund policy) |
+| `get-store-alerts` | Get admin alerts and setup requirements |
+
+#### Example: Get Store Limits
+
+```json
+{
+  "maxProductVariants": 2000,
+  "maxProductOptions": 3,
+  "locationLimit": 1000,
+  "redirectLimitReached": false
+}
+```
+
+#### Example: Get Store Features
+
+```json
+{
+  "giftCards": true,
+  "reports": true,
+  "storefront": true,
+  "bundles": {
+    "eligibleForBundles": true
+  },
+  "sellsSubscriptions": false
+}
+```
+
+#### Example: Get Store Currencies
+
+```json
+{
+  "currencyCode": "USD",
+  "enabledPresentmentCurrencies": ["USD", "EUR", "GBP", "CAD"],
+  "currencyFormats": {
+    "moneyFormat": "${{amount}}",
+    "moneyWithCurrencyFormat": "${{amount}} USD"
+  }
+}
+```
 
 </details>
 
@@ -453,6 +554,289 @@ Each tool can be converted to OpenAI function format:
 
 ---
 
+## 📦 Tool Modules
+
+shopify-mcp-admin uses a modular architecture to optimize AI agent performance. Instead of loading all 81 tools at startup (which can degrade AI performance by up to 85%), tools are organized into 7 modules that can be loaded on demand.
+
+### How Module Loading Works
+
+1. **At startup:** Only the **Core Module** (15 tools) is loaded by default
+2. **Discovery:** AI agents use `list-modules` to see available modules
+3. **Loading:** AI agents use `load-module` to enable additional tools
+4. **Suggestions:** Tool responses include hints about which modules to load next
+
+### Module Dependency Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         CORE MODULE                              │
+│            (Always Loaded - 15 tools)                           │
+│   Products (7) • Inventory (4) • Store Info (2) • Meta (2)      │
+└─────────────────────────────────────────────────────────────────┘
+        │
+        ├──────────────────────────────────────────────────────────┐
+        │                                                          │
+        ▼                                                          ▼
+┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
+│  STORE CONTEXT    │  │   COLLECTIONS     │  │     CONTENT       │
+│     (7 tools)     │  │    (10 tools)     │  │    (22 tools)     │
+│   No deps         │  │   No deps         │  │    No deps        │
+└───────────────────┘  └───────────────────┘  └───────────────────┘
+                               │
+        ├──────────────────────┼──────────────────────────────────┐
+        │                      │                                  │
+        ▼                      ▼                                  ▼
+┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
+│   INTERNATIONAL   │  │ PRODUCT EXTENSIONS│  │ ADVANCED REDIRECTS│
+│    (14 tools)     │  │     (9 tools)     │  │     (4 tools)     │
+│    No deps        │  │    No deps        │  │ Deps: product-ext │
+└───────────────────┘  └───────────────────┘  └───────────────────┘
+```
+
+### Module: Core (15 tools) — Always Loaded
+
+**Description:** Essential product and inventory management tools that form the foundation for most Shopify operations. Always loaded at startup.
+
+**Dependencies:** None
+
+**Tools:**
+
+| Category | Tools |
+|----------|-------|
+| Products (7) | `create-product`, `get-product`, `update-product`, `delete-product`, `list-products`, `update-product-variant`, `add-product-image` |
+| Inventory (4) | `get-inventory`, `update-inventory`, `list-low-inventory`, `get-bulk-inventory` |
+| Store Info (2) | `get-store-info`, `get-store-limits` |
+| Meta Tools (2) | `list-modules`, `load-module` |
+
+**Use Case:** Basic product catalog management, inventory tracking, and store information queries.
+
+---
+
+### Module: Store Context (7 tools)
+
+**Description:** Extended store configuration and context tools from Epic 11. Provides deep insights into store configuration including features, currencies, shipping, and more.
+
+**Dependencies:** None
+
+**Tools:**
+- `get-store-features` — Feature flags (gift cards, reports, storefront, bundles)
+- `get-store-currencies` — Multi-currency configuration
+- `get-store-shipping` — Shipping countries and zones
+- `get-store-domain` — Primary domain configuration
+- `get-store-taxes` — Tax configuration
+- `get-store-policies` — Legal policies (privacy, terms, refund)
+- `get-store-alerts` — Admin alerts and setup requirements
+
+**Use Case:** Understanding store capabilities before operations, multi-currency setup, tax configuration.
+
+**Load Command:** `load-module(module: "store-context")`
+
+---
+
+### Module: Collections (10 tools)
+
+**Description:** Product collection management for organizing products and navigation. Includes CRUD operations and metafields.
+
+**Dependencies:** None
+
+**Tools:**
+
+| Category | Tools |
+|----------|-------|
+| CRUD (7) | `list-collections`, `get-collection`, `create-collection`, `update-collection`, `delete-collection`, `add-products-to-collection`, `remove-products-from-collection` |
+| Metafields (3) | `get-collection-metafields`, `set-collection-metafields`, `delete-collection-metafields` |
+
+**Use Case:** Organizing products into collections, SEO optimization, storefront navigation.
+
+**Load Command:** `load-module(module: "collections")`
+
+---
+
+### Module: Product Extensions (9 tools)
+
+**Description:** Extended product management including metafields, advanced image operations, and URL redirects for SEO.
+
+**Dependencies:** None
+
+**Tools:**
+
+| Category | Tools |
+|----------|-------|
+| Metafields (3) | `get-product-metafields`, `set-product-metafields`, `delete-product-metafields` |
+| Images (3) | `update-product-image`, `delete-product-image`, `reorder-product-images` |
+| Redirects (3) | `create-redirect`, `list-redirects`, `delete-redirect` |
+
+**Use Case:** Adding custom metadata to products, SEO image alt text, URL redirects when changing product handles.
+
+**Load Command:** `load-module(module: "product-extensions")`
+
+---
+
+### Module: Content (22 tools)
+
+**Description:** Content management for pages, blogs, and articles. Complete CRUD operations plus metafields for content marketing and SEO.
+
+**Dependencies:** None
+
+**Tools:**
+
+| Category | Tools |
+|----------|-------|
+| Pages (8) | `list-pages`, `get-page`, `create-page`, `update-page`, `delete-page`, `get-page-metafields`, `set-page-metafields`, `delete-page-metafields` |
+| Blogs (7) | `list-blogs`, `create-blog`, `update-blog`, `delete-blog`, `get-blog-metafields`, `set-blog-metafields`, `delete-blog-metafields` |
+| Articles (7) | `list-articles`, `create-article`, `update-article`, `delete-article`, `get-article-metafields`, `set-article-metafields`, `delete-article-metafields` |
+
+**Use Case:** Content marketing, blog management, static pages (About, Contact, FAQ).
+
+**Load Command:** `load-module(module: "content")`
+
+---
+
+### Module: International (14 tools)
+
+**Description:** International commerce and localization tools. Markets, web presence, and shop locale translations for multi-region stores.
+
+**Dependencies:** None
+
+**Tools:**
+
+| Category | Tools |
+|----------|-------|
+| Markets (5) | `list-markets`, `get-market`, `create-market`, `update-market`, `delete-market` |
+| Web Presence (4) | `list-web-presences`, `create-web-presence`, `update-web-presence`, `delete-web-presence` |
+| Translations (5) | `list-shop-locales`, `enable-shop-locale`, `disable-shop-locale`, `register-translations`, `remove-translations` |
+
+**Use Case:** Multi-region selling, localized storefronts, translation management.
+
+**Load Command:** `load-module(module: "international")`
+
+---
+
+### Module: Advanced Redirects (4 tools)
+
+**Description:** Bulk URL redirect operations for large-scale SEO management. Import and mass-delete capabilities.
+
+**Dependencies:** `product-extensions` (auto-loaded when you load this module)
+
+**Tools:**
+- `bulk-delete-redirects` — Delete multiple redirects by ID
+- `bulk-delete-redirects-by-search` — Delete redirects matching a search query
+- `import-redirects` — Import redirects from CSV URL
+- `submit-redirect-import` — Submit a redirect import job for processing
+
+**Use Case:** Site migrations, bulk URL updates, SEO cleanup operations.
+
+**Load Command:** `load-module(module: "advanced-redirects")`
+
+> **Note:** Loading this module automatically loads `product-extensions` (9 tools) as a dependency.
+
+---
+
+### Choosing the Right Module
+
+| If you need to... | Load these modules |
+|-------------------|-------------------|
+| Manage basic products and inventory | Core only (default) |
+| Work with collections and organize products | `collections` |
+| Add product metafields or manage images | `product-extensions` |
+| Manage blog posts and pages | `content` |
+| Set up international markets | `international` |
+| Bulk manage URL redirects | `advanced-redirects` |
+| Full store administration | Use `full-access` role preset |
+
+---
+
+## 🔄 Upgrading from Previous Versions
+
+### What's New in v0.8.0+: Modular Tool Loading
+
+Starting with v0.8.0, shopify-mcp-admin uses **lazy loading** to optimize AI agent performance. Research shows that presenting more than 30 tools to an AI agent can degrade performance by up to 85%.
+
+**Default Behavior (Lazy Loading Enabled):**
+- Only 15 core tools are loaded at startup
+- Additional tools are loaded on-demand via `load-module`
+- AI agents discover available modules using `list-modules`
+- Token usage reduced by up to 81% compared to loading all tools
+
+### Breaking Changes
+
+| Previous Behavior | New Behavior (v0.8.0+) |
+|-------------------|------------------------|
+| All 79+ tools loaded at startup | 15 core tools loaded at startup |
+| No module concept | 7 modules with lazy loading |
+| N/A | `list-modules` and `load-module` meta-tools added |
+
+### Legacy Mode: Restore Previous Behavior
+
+If you prefer all tools loaded at startup (not recommended for optimal AI performance):
+
+```bash
+# Option 1: Environment variable
+export SHOPIFY_MCP_LAZY_LOADING=false
+
+# Option 2: In Claude Desktop config
+{
+  "mcpServers": {
+    "shopify": {
+      "command": "npx",
+      "args": ["-y", "@anton.andrusenko/shopify-mcp-admin"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
+        "SHOPIFY_MCP_LAZY_LOADING": "false"
+      }
+    }
+  }
+}
+```
+
+### Migration Steps
+
+1. **Review your use case** — Do you need all 81 tools? Most workflows only need a subset.
+
+2. **Choose a role preset** (recommended) — Set `SHOPIFY_MCP_ROLE` for pre-configured modules:
+   ```bash
+   export SHOPIFY_MCP_ROLE=product-manager
+   ```
+
+3. **Or use on-demand loading** — Let AI agents discover and load modules as needed:
+   - AI uses `list-modules` to see available modules
+   - AI uses `load-module` with module name to enable tools
+   - Tool responses suggest relevant modules automatically
+
+4. **Or disable lazy loading** — Set `SHOPIFY_MCP_LAZY_LOADING=false` for legacy behavior
+
+### When to Use Each Mode
+
+| Mode | Tools | Best For |
+|------|-------|----------|
+| **Lazy Loading (default)** | 15 at startup | New projects, optimal AI performance |
+| **Role Preset** | 15-81 based on role | Specific workflows (e.g., content manager) |
+| **Legacy Mode** | All 81 | Backward compatibility, full store admin |
+
+### Performance Comparison
+
+| Mode | Tools at Startup | Est. Token Usage | AI Performance |
+|------|------------------|------------------|----------------|
+| Lazy Loading (default) | 15 | ~4,500 | ⭐⭐⭐ Optimal |
+| inventory-manager | 15 | ~4,500 | ⭐⭐⭐ Optimal |
+| content-manager | 37 | ~11,100 | ⭐⭐ Good |
+| product-manager | 41 | ~12,300 | ⭐⭐ Good |
+| international-manager | 46 | ~13,800 | ⭐⭐ Good |
+| full-access | 81 | ~24,000 | ⭐ May degrade |
+| Legacy Mode | 81 | ~24,000 | ⭐ May degrade |
+
+### Troubleshooting Module Loading
+
+| Issue | Solution |
+|-------|----------|
+| Tool not found after upgrade | Load the appropriate module: `load-module(module: "collections")` |
+| "Module not found" error | Use `list-modules` to see valid module names |
+| Want all tools at startup | Set `SHOPIFY_MCP_LAZY_LOADING=false` |
+| AI agent loading too many modules | Use a role preset instead of on-demand loading |
+
+---
+
 ## 🔧 Troubleshooting
 
 ### Common Errors
@@ -497,12 +881,38 @@ npm run inspect:config
 
 MCP Inspector opens a web UI at `http://localhost:6274` where you can:
 
-- 📋 Browse all 71 registered tools with schemas
+- 📋 Browse registered tools with schemas (15 core tools by default, up to 81 with modules)
+- 📦 Test module loading via `list-modules` and `load-module`
+- 📊 Access 9 MCP resources for store context
 - ▶️ Execute tools interactively and view results
 - 🔍 Inspect JSON-RPC protocol messages
 - 📊 Monitor server events in real-time
 
-> **Tip:** Use `npm run inspect:dev` during development for instant feedback without rebuilding.
+> **Tip:** Copy `mcp-inspector.example.json` to `mcp-inspector.json` for pre-configured role presets like `product-manager` or `full-access`.
+
+---
+
+## 📊 MCP Resources
+
+The MCP server exposes comprehensive store context information via MCP resources. These are read-only data sources that AI agents can query for context.
+
+### Extended Store Resources
+
+| Resource URI | Description |
+|--------------|-------------|
+| `shopify://store/info` | Basic store info (name, domain, plan, currency, timezone) |
+| `shopify://store/limits` | Resource limits (max variants, max options, location limit) |
+| `shopify://store/features` | Feature flags (gift cards, reports, storefront, bundles) |
+| `shopify://store/currencies` | Multi-currency configuration (base currency, presentment currencies) |
+| `shopify://store/shipping` | Shipping configuration (ships-to countries, shipping zones) |
+| `shopify://store/domain` | Primary domain configuration (hostname, URL, SSL status) |
+| `shopify://store/taxes` | Tax configuration (taxes included, tax shipping) |
+| `shopify://store/policies` | Legal policies (privacy, terms of service, refund) |
+| `shopify://store/alerts` | Admin alerts and setup requirements |
+
+> **Note:** For MCP clients that don't support resources (e.g., Claude Desktop), equivalent tools are available. See **Store Info Tools** below.
+
+---
 
 ### FAQ