@anton.andrusenko/shopify-mcp-admin 0.1.0 → 0.3.0

package/README.md

@@ -1,10 +1,11 @@
-# shopify-mcp-admin
+# @anton.andrusenko/shopify-mcp-admin
 
 > 🛍️ **MCP Server for Shopify Admin API** — Enable AI agents to manage Shopify stores with 40 powerful tools
 
-[![npm version](https://badge.fury.io/js/shopify-mcp-admin.svg)](https://badge.fury.io/js/shopify-mcp-admin)
+[![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)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
+[![codecov](https://codecov.io/gh/AntonAndrusenko/shopify-mcp-admin/graph/badge.svg)](https://codecov.io/gh/AntonAndrusenko/shopify-mcp-admin)
 
 ---
 
@@ -32,10 +33,10 @@
 
 ```bash
 # Run directly with npx (recommended)
-npx shopify-mcp-admin
+npx @anton.andrusenko/shopify-mcp-admin
 
 # Or install globally
-npm install -g shopify-mcp-admin
+npm install -g @anton.andrusenko/shopify-mcp-admin
 ```
 
 ### Configuration
@@ -57,18 +58,58 @@ The AI will use the `list-products` tool to fetch your catalog.
 
 ---
 
+## 🔐 Authentication Methods
+
+shopify-mcp-admin supports two authentication methods:
+
+### Option 1: Legacy Custom App Token (Recommended for existing apps)
+
+If you have a Custom App with a static access token:
+
+```bash
+SHOPIFY_STORE_URL=mystore.myshopify.com
+SHOPIFY_ACCESS_TOKEN=shpat_xxxxx
+```
+
+### Option 2: Dev Dashboard (OAuth 2.0)
+
+If you're using Shopify's new Dev Dashboard with client credentials:
+
+```bash
+SHOPIFY_STORE_URL=mystore.myshopify.com
+SHOPIFY_CLIENT_ID=xxxxx
+SHOPIFY_CLIENT_SECRET=xxxxx
+```
+
+Tokens are automatically refreshed every 24 hours.
+
+### Which Should I Use?
+
+| Scenario | Method |
+|----------|--------|
+| Existing Custom App with static token | Legacy (Option 1) |
+| New Dev Dashboard app | Client Credentials (Option 2) |
+| Development/Partner store | Either works |
+| Production store (after Jan 2026) | Client Credentials required |
+
+---
+
 ## ⚙️ Configuration Reference
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `SHOPIFY_STORE_URL` | ✅ Yes | — | Your Shopify store domain (e.g., `your-store.myshopify.com`) |
-| `SHOPIFY_ACCESS_TOKEN` | ✅ Yes | — | Admin API access token from your Custom App |
+| `SHOPIFY_ACCESS_TOKEN` | ⚡ See below | — | Admin API access token from your Custom App |
+| `SHOPIFY_CLIENT_ID` | ⚡ See below | — | Client ID from Dev Dashboard app |
+| `SHOPIFY_CLIENT_SECRET` | ⚡ See below | — | Client Secret from Dev Dashboard app |
 | `SHOPIFY_API_VERSION` | No | `2025-10` | Shopify API version |
 | `TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
 | `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` |
 
+**⚡ Authentication:** Provide EITHER `SHOPIFY_ACCESS_TOKEN` (legacy) OR both `SHOPIFY_CLIENT_ID` and `SHOPIFY_CLIENT_SECRET` (Dev Dashboard).
+
 ### Required Shopify Scopes
 
 Configure these scopes when creating your Custom App:
@@ -95,12 +136,14 @@ Edit your Claude Desktop configuration file:
 
 ### Step 2: Add the MCP Server
 
+**Option 1: Legacy Token Authentication**
+
 ```json
 {
   "mcpServers": {
     "shopify": {
       "command": "npx",
-      "args": ["shopify-mcp-admin"],
+      "args": ["@anton.andrusenko/shopify-mcp-admin"],
       "env": {
         "SHOPIFY_STORE_URL": "your-store.myshopify.com",
         "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx"
@@ -110,6 +153,24 @@ Edit your Claude Desktop configuration file:
 }
 ```
 
+**Option 2: Dev Dashboard (OAuth 2.0)**
+
+```json
+{
+  "mcpServers": {
+    "shopify": {
+      "command": "npx",
+      "args": ["@anton.andrusenko/shopify-mcp-admin"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_CLIENT_ID": "xxxxx",
+        "SHOPIFY_CLIENT_SECRET": "xxxxx"
+      }
+    }
+  }
+}
+```
+
 ### Step 3: Restart Claude Desktop
 
 Quit and reopen Claude Desktop. You should see "shopify" in the MCP servers list.
@@ -135,7 +196,7 @@ TRANSPORT=http \
 PORT=3000 \
 SHOPIFY_STORE_URL=your-store.myshopify.com \
 SHOPIFY_ACCESS_TOKEN=shpat_xxxxx \
-npx shopify-mcp-admin
+npx @anton.andrusenko/shopify-mcp-admin
 ```
 
 ### Step 2: Test the Connection
@@ -186,7 +247,7 @@ Each tool can be converted to OpenAI function format:
 
 ## 🛠️ Available Tools
 
-shopify-mcp-admin provides **40 tools** organized into 7 categories:
+@anton.andrusenko/shopify-mcp-admin provides **40 tools** organized into 7 categories:
 
 <details>
 <summary><strong>📦 Product Management (7 tools)</strong></summary>
@@ -303,7 +364,7 @@ shopify-mcp-admin provides **40 tools** organized into 7 categories:
 | `401 Unauthorized` | Invalid access token | Regenerate token in Shopify Admin |
 | `403 Forbidden` | Missing API scopes | Add required scopes to Custom App |
 | `429 Too Many Requests` | Rate limited | Wait; shopify-mcp-admin auto-retries |
-| `ECONNREFUSED` | Server not running | Start server with `npx shopify-mcp-admin` |
+| `ECONNREFUSED` | Server not running | Start server with `npx @anton.andrusenko/shopify-mcp-admin` |
 | `Invalid store URL` | Wrong URL format | Use `store.myshopify.com` format |
 
 ### Debug Mode
@@ -312,12 +373,39 @@ Enable verbose logging to diagnose issues:
 
 ```bash
 # Option 1: DEBUG flag
-DEBUG=1 npx shopify-mcp-admin
+DEBUG=1 npx @anton.andrusenko/shopify-mcp-admin
 
 # Option 2: LOG_LEVEL
-LOG_LEVEL=debug npx shopify-mcp-admin
+LOG_LEVEL=debug npx @anton.andrusenko/shopify-mcp-admin
 ```
 
+### MCP Inspector
+
+Use [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to visually test and debug the server:
+
+```bash
+# Test production build
+npm run build
+npm run inspect
+
+# Development mode (no build needed)
+npm run inspect:dev
+
+# With saved configuration
+cp mcp-inspector.example.json mcp-inspector.json
+# Edit mcp-inspector.json with your credentials
+npm run inspect:config
+```
+
+MCP Inspector opens a web UI at `http://localhost:6274` where you can:
+
+- 📋 Browse all 40 registered tools with schemas
+- ▶️ 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.
+
 ### FAQ
 
 **Q: Can I connect to multiple stores?**  
@@ -416,8 +504,11 @@ npm run dev
 | `npm run dev` | Start development server with hot reload |
 | `npm run build` | Build for production |
 | `npm run test` | Run unit tests |
+| `npm run test:coverage` | Run tests with coverage report |
 | `npm run lint` | Run Biome linter |
 | `npm run lint:fix` | Auto-fix linting issues |
+| `npm run inspect` | Open MCP Inspector with production build |
+| `npm run inspect:dev` | Open MCP Inspector in development mode |
 
 ### Pull Request Guidelines