@anton.andrusenko/shopify-mcp-admin 2.1.2 → 2.3.0

package/README.md

@@ -77,9 +77,70 @@ The AI will use the `list-products` tool to fetch your catalog.
 
 ## 🔐 Authentication Methods
 
-shopify-mcp-admin supports two authentication methods:
+shopify-mcp-admin supports multiple authentication methods depending on your use case:
 
-### Option 1: Legacy Custom App Token (Recommended for existing apps)
+### Authentication Methods Overview
+
+| Method | Use Case | Client Types |
+|--------|----------|--------------|
+| **OAuth 2.0 Authorization Code + PKCE** | Web-based AI clients with browser | ChatGPT MCP Apps, Claude Web Custom Connectors |
+| **API Key Bearer Token** | Desktop/CLI apps, programmatic access | Claude Desktop, Cursor, LibreChat, VS Code |
+| **Legacy Custom App Token** | Local development, single-tenant | STDIO transport, local testing |
+| **Dev Dashboard Client Credentials** | Shopify Dev Dashboard apps | Local development with OAuth |
+
+### Which Method Should I Use?
+
+| Your Client | Recommended Method |
+|-------------|-------------------|
+| **ChatGPT (MCP Apps)** | OAuth 2.0 (automatic via DCR) — See [ChatGPT Integration](#-chatgpt-mcp-apps-integration) |
+| **Claude Web (Custom Connectors)** | OAuth 2.0 (automatic via DCR) — See [Claude Web Integration](#-claude-web-custom-connectors-integration) |
+| **Claude Desktop** | API Key Bearer Token — See [Claude Desktop](#️-claude-desktop-integration) |
+| **Cursor, VS Code** | API Key Bearer Token — See [LibreChat](#-librechat-integration) |
+| **LibreChat** | API Key Bearer Token — See [LibreChat](#-librechat-integration) |
+| **Local Development** | Legacy Token or Dev Dashboard |
+
+---
+
+### Option 1: OAuth 2.0 Authorization Code + PKCE (ChatGPT, Claude Web)
+
+For web-based AI clients that support OAuth 2.0:
+
+- **Automatic client registration** via Dynamic Client Registration (RFC 7591)
+- **PKCE required** with S256 method (RFC 7636)
+- **No manual credentials needed** — clients handle registration automatically
+- **Browser-based authorization** with consent page
+
+The server exposes discovery endpoints at:
+- `/.well-known/oauth-authorization-server` (RFC 8414)
+- `/.well-known/oauth-protected-resource` (RFC 9728)
+
+> See [OAuth 2.0 Endpoints Reference](#-oauth-20-endpoints-reference) for details.
+
+---
+
+### Option 2: API Key Bearer Token (Claude Desktop, Cursor, LibreChat)
+
+For desktop apps and programmatic access:
+
+1. **Get API Key**: Visit your MCP Dashboard (`/app`) → Settings → API Keys
+2. **Generate Key**: Click "Create New Key" and copy the `sk_live_...` key
+3. **Configure Client**: Add `Authorization: Bearer sk_live_...` header
+4. **Ensure a Default Shop is set**: In the dashboard, go to **Settings → Default Shop** (recommended, especially if you have multiple shops connected)
+
+```bash
+# Example: Test with curl
+curl -X POST https://shopify-mcp.com/mcp \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
+  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
+```
+
+> **Cursor note:** Cursor does not run an OAuth “Connect” flow inside MCP. Use an API key + `streamable-http` transport, and connect your Shopify store via the dashboard (`/app`) first.
+
+---
+
+### Option 3: Legacy Custom App Token (Local Development)
 
 If you have a Custom App with a static access token:
 
@@ -88,7 +149,9 @@ SHOPIFY_STORE_URL=mystore.myshopify.com
 SHOPIFY_ACCESS_TOKEN=shpat_xxxxx
 ```
 
-### Option 2: Dev Dashboard (OAuth 2.0)
+---
+
+### Option 4: Dev Dashboard Client Credentials (Local Development)
 
 If you're using Shopify's new Dev Dashboard with client credentials:
 
@@ -102,15 +165,6 @@ Tokens are automatically refreshed every 24 hours.
 
 > **Remote mode note (multi-tenant):** Shops connected via OAuth now support **expiring offline tokens with automatic refresh** (Shopify Dec 2025 refresh tokens). See `docs/TOKEN-REFRESH-IMPLEMENTATION.md`.
 
-### 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
@@ -478,11 +532,248 @@ mcpServers:
 
 ---
 
-## 🌐 OpenAI/ChatGPT Integration
+## 🤖 ChatGPT MCP Apps Integration
+
+ChatGPT supports connecting to MCP servers via **OAuth 2.0 Authorization Code Flow with PKCE**. This is the recommended method for ChatGPT Plus/Pro/Team/Enterprise users.
+
+### How It Works
+
+When you add the Shopify MCP server in ChatGPT:
+
+1. **ChatGPT discovers** the OAuth endpoints via `/.well-known/oauth-authorization-server` (RFC 8414)
+2. **ChatGPT registers** itself as an OAuth client via `/oauth/register` (RFC 7591 Dynamic Client Registration)
+3. **You authorize** the connection via a consent page at `/oauth/authorize`
+4. **ChatGPT exchanges** the authorization code for tokens via `/oauth/token`
+5. **ChatGPT uses** the access token to call MCP tools
+
+> **No manual `client_id` or `client_secret` needed** — ChatGPT handles registration automatically!
+
+### Prerequisites
+
+1. **Deployed MCP Server** — Your server running in remote mode at `https://shopify-mcp.com` (or your own domain)
+2. **Shopify Store Connected** — At least one shop connected in your MCP Dashboard
+3. **ChatGPT Plus/Pro/Team/Enterprise** — MCP Apps require a paid ChatGPT subscription
+
+### Step-by-Step Setup
+
+#### Step 1: Ensure Your Shop is Connected
+
+1. Visit your MCP Dashboard: `https://shopify-mcp.com/app`
+2. Log in or register a tenant account
+3. Go to **Shops** and connect your Shopify store (OAuth or manual token)
+4. Verify the shop shows as "Connected"
+
+#### Step 2: Add MCP Server in ChatGPT
+
+1. Open ChatGPT → **Settings** → **Connectors** (or **Apps**)
+2. Enable **Developer Mode** in Advanced Settings (if required)
+3. Click **Create** or **Add New MCP Server**
+4. Fill in the configuration:
+
+| Field | Value |
+|-------|-------|
+| **Name** | `Shopify MCP` |
+| **Description** | `Manage Shopify store: products, inventory, collections, content, SEO` |
+| **MCP Server URL** | `https://shopify-mcp.com/mcp` |
+| **Authentication** | `OAuth 2.0` (auto-detected via discovery) |
+
+5. Click **Save** or **Connect**
+
+#### Step 3: Authorize the Connection
+
+1. ChatGPT will open an authorization page at `https://shopify-mcp.com/oauth/authorize`
+2. Log in with your MCP Dashboard credentials (same email/password)
+3. Review the requested scopes and click **Authorize**
+4. You'll be redirected back to ChatGPT with the connection established
+
+#### Step 4: Test the Connection
+
+In ChatGPT, try:
+> "List all products in my Shopify store"
+
+ChatGPT will use the `list-products` tool to fetch your catalog.
+
+### ChatGPT Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "OAuth discovery failed" | Verify server is running: `curl https://shopify-mcp.com/.well-known/oauth-authorization-server` |
+| "Client registration failed" | Check server logs for registration errors |
+| "Authorization failed" | Ensure you're logged in to the MCP Dashboard with the correct account |
+| "No shop configured" | Connect a shop in your MCP Dashboard first |
+| "Token expired" | Re-authorize the connection in ChatGPT settings |
+| Connection timeout | Check server health: `curl https://shopify-mcp.com/health` |
+
+### Re-Authorization
+
+If your connection stops working:
+
+1. Go to ChatGPT → **Settings** → **Connectors**
+2. Find the Shopify MCP connection and click **Disconnect**
+3. Click **Connect** again to start a fresh OAuth flow
+4. Complete the authorization as described above
+
+---
+
+## 🔮 Claude Web Custom Connectors Integration
+
+Claude Web (claude.ai) supports MCP connections via **Custom Connectors** using the same OAuth 2.0 Authorization Code Flow with PKCE.
+
+> **Plan Requirements:** Claude Web Custom Connectors require **Claude Pro, Max, Team, or Enterprise** subscription.
+
+### How It Works
+
+Claude Web's Custom Connectors work similarly to ChatGPT's MCP Apps:
+
+1. **Claude discovers** OAuth endpoints via `/.well-known/oauth-authorization-server`
+2. **Claude registers** as an OAuth client via Dynamic Client Registration (RFC 7591)
+3. **You authorize** the connection via the consent page
+4. **Claude exchanges** the authorization code for tokens
+5. **Claude uses** the access token for MCP tool calls
+
+### Prerequisites
+
+1. **Deployed MCP Server** — Your server at `https://shopify-mcp.com` (or your own domain)
+2. **Shopify Store Connected** — At least one shop connected in your MCP Dashboard
+3. **Claude Pro/Max/Team/Enterprise** — Custom Connectors require a paid subscription
+
+### Step-by-Step Setup
+
+#### Step 1: Ensure Your Shop is Connected
+
+1. Visit your MCP Dashboard: `https://shopify-mcp.com/app`
+2. Log in or register a tenant account
+3. Connect your Shopify store under **Shops**
+
+#### Step 2: Add Custom Connector in Claude Web
+
+1. Go to **claude.ai** → **Settings** (gear icon)
+2. Navigate to **Integrations** or **Custom Connectors**
+3. Click **Add Connector** or **New**
+4. Fill in the configuration:
+
+| Field | Value |
+|-------|-------|
+| **Name** | `Shopify MCP` |
+| **Description** | `Manage Shopify store via MCP` |
+| **Server URL** | `https://shopify-mcp.com/mcp` |
 
-For OpenAI function calling or ChatGPT plugins, use HTTP transport mode.
+5. Click **Save** or **Connect**
 
-### Step 1: Start the Server
+#### Step 3: Authorize the Connection
+
+1. Claude will redirect you to `https://shopify-mcp.com/oauth/authorize`
+2. Log in with your MCP Dashboard credentials
+3. Review and approve the authorization request
+4. You'll be redirected back to Claude with the connection active
+
+#### Step 4: Test the Connection
+
+In Claude, try:
+> "What products are in my Shopify store?"
+
+Claude will use the MCP tools to query your store.
+
+### Claude Web Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Custom Connectors not available" | Upgrade to Claude Pro, Max, Team, or Enterprise |
+| "OAuth flow failed" | Verify server discovery: `curl https://shopify-mcp.com/.well-known/oauth-authorization-server` |
+| "Authorization error" | Ensure you're using the correct MCP Dashboard credentials |
+| "Connector not responding" | Check server health: `curl https://shopify-mcp.com/health` |
+| "Token expired" | Disconnect and reconnect the Custom Connector |
+
+### Re-Authorization
+
+If the connection expires or breaks:
+
+1. Go to Claude Web → **Settings** → **Integrations**
+2. Find the Shopify connector and click **Remove** or **Disconnect**
+3. Add the connector again and complete the authorization flow
+
+---
+
+## 🔌 OAuth 2.0 Endpoints Reference
+
+The MCP server exposes the following OAuth 2.0 endpoints for client authentication:
+
+| Endpoint | Method | Description | RFC |
+|----------|--------|-------------|-----|
+| `/.well-known/oauth-authorization-server` | GET | Authorization server metadata (issuer, endpoints, capabilities) | [RFC 8414](https://tools.ietf.org/html/rfc8414) |
+| `/.well-known/oauth-protected-resource` | GET | Protected resource metadata (resource server, scopes) | [RFC 9728](https://tools.ietf.org/html/rfc9728) |
+| `/oauth/register` | POST | Dynamic Client Registration (automatic client registration) | [RFC 7591](https://tools.ietf.org/html/rfc7591) |
+| `/oauth/authorize` | GET | Authorization endpoint with consent UI | [RFC 6749](https://tools.ietf.org/html/rfc6749) |
+| `/oauth/token` | POST | Token endpoint (authorization_code, refresh_token grants) | [RFC 6749](https://tools.ietf.org/html/rfc6749), [RFC 7636](https://tools.ietf.org/html/rfc7636) |
+
+### OAuth Flow Diagram
+
+```
+┌─────────────┐                                    ┌─────────────────────────┐
+│   ChatGPT   │                                    │    MCP Server           │
+│  or Claude  │                                    │  (shopify-mcp.com)      │
+└──────┬──────┘                                    └───────────┬─────────────┘
+       │                                                       │
+       │  1. GET /.well-known/oauth-authorization-server       │
+       │ ───────────────────────────────────────────────────>  │
+       │  <─── Authorization server metadata (RFC 8414)        │
+       │                                                       │
+       │  2. POST /oauth/register (Dynamic Client Registration)│
+       │ ───────────────────────────────────────────────────>  │
+       │  <─── client_id, client_secret (RFC 7591)             │
+       │                                                       │
+       │  3. Redirect user to /oauth/authorize?client_id=...   │
+       │     &redirect_uri=...&code_challenge=...&state=...    │
+       │ ───────────────────────────────────────────────────>  │
+       │                                                       │
+       │        ┌─────────────────────────────────────────┐    │
+       │        │ User sees consent page, logs in,        │    │
+       │        │ approves authorization                   │    │
+       │        └─────────────────────────────────────────┘    │
+       │                                                       │
+       │  <─── Redirect to callback with authorization code    │
+       │                                                       │
+       │  4. POST /oauth/token (exchange code for tokens)      │
+       │     code=...&code_verifier=...&grant_type=...         │
+       │ ───────────────────────────────────────────────────>  │
+       │  <─── access_token, refresh_token (RFC 6749/7636)     │
+       │                                                       │
+       │  5. POST /mcp (with Bearer access_token)              │
+       │ ───────────────────────────────────────────────────>  │
+       │  <─── MCP tool results                                │
+       └───────────────────────────────────────────────────────┘
+```
+
+### Discovery Endpoint Example
+
+```bash
+curl https://shopify-mcp.com/.well-known/oauth-authorization-server
+```
+
+```json
+{
+  "issuer": "https://shopify-mcp.com",
+  "authorization_endpoint": "https://shopify-mcp.com/oauth/authorize",
+  "token_endpoint": "https://shopify-mcp.com/oauth/token",
+  "registration_endpoint": "https://shopify-mcp.com/oauth/register",
+  "response_types_supported": ["code"],
+  "grant_types_supported": ["authorization_code", "refresh_token"],
+  "code_challenge_methods_supported": ["S256"],
+  "token_endpoint_auth_methods_supported": ["client_secret_post"]
+}
+```
+
+---
+
+## 🌐 OpenAI/ChatGPT Integration (Alternative Methods)
+
+In addition to the OAuth-based ChatGPT MCP Apps integration above, you can also use API key authentication for programmatic access.
+
+### Option 1: Local Server (Development)
+
+Run the server locally for development and testing with OpenAI function calling.
+
+#### Step 1: Start the Server
 
 ```bash
 TRANSPORT=http \
@@ -492,7 +783,7 @@ SHOPIFY_ACCESS_TOKEN=shpat_xxxxx \
 npx @anton.andrusenko/shopify-mcp-admin
 ```
 
-### Step 2: Test the Connection
+#### Step 2: Test the Connection
 
 ```bash
 # List available tools
@@ -501,7 +792,7 @@ curl -X POST http://localhost:3000/mcp \
   -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
 ```
 
-### Step 3: Call a Tool
+#### Step 3: Call a Tool
 
 ```bash
 # Example: List products
@@ -518,9 +809,25 @@ curl -X POST http://localhost:3000/mcp \
   }'
 ```
 
+---
+
+### Option 3: Remote Server with Bearer Token
+
+Connect to your production MCP server from any OpenAI-compatible client.
+
+```bash
+# Authenticated request to remote server
+curl -X POST https://your-server.com/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
+  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
+```
+
+---
+
 ### OpenAI Function Calling Format
 
-Each tool can be converted to OpenAI function format:
+Each tool can be converted to OpenAI function format for custom integrations:
 
 ```json
 {
@@ -1144,6 +1451,81 @@ export SHOPIFY_MCP_LAZY_LOADING=true
 | `ECONNREFUSED` | Server not running | Start server with `npx @anton.andrusenko/shopify-mcp-admin` |
 | `Invalid store URL` | Wrong URL format | Use `store.myshopify.com` format |
 
+### OAuth Connection Troubleshooting
+
+If you're having issues connecting ChatGPT or Claude Web via OAuth:
+
+#### "OAuth discovery failed" or "Server not found"
+
+1. Verify the server is running:
+   ```bash
+   curl https://shopify-mcp.com/.well-known/oauth-authorization-server
+   ```
+   Expected: JSON response with `issuer`, `authorization_endpoint`, etc.
+
+2. Check server health:
+   ```bash
+   curl https://shopify-mcp.com/health
+   ```
+   Expected: `200 OK` with `{"status": "healthy", ...}`
+
+#### "Client registration failed"
+
+- **Cause**: Dynamic Client Registration (DCR) endpoint issue
+- **Solution**: Check server logs for `/oauth/register` errors
+- **Verify**: `curl -X POST https://shopify-mcp.com/oauth/register -H "Content-Type: application/json" -d '{"client_name":"test","redirect_uris":["https://example.com/callback"]}'`
+
+#### "Authorization failed" or "Invalid credentials"
+
+- **Cause**: Wrong MCP Dashboard credentials
+- **Solution**: Log in to `https://shopify-mcp.com/app` directly to verify your email/password
+- **Note**: OAuth login uses your MCP Dashboard account, not Shopify credentials
+
+#### "No shop configured" or "No shops connected"
+
+- **Cause**: No Shopify store connected to your tenant account
+- **Solution**: 
+  1. Log in to `https://shopify-mcp.com/app`
+  2. Go to **Shops** → **Connect Shop**
+  3. Complete the OAuth flow or enter a manual access token
+
+#### "Token expired" or "Access denied"
+
+- **Cause**: OAuth access token expired (tokens last 1 hour by default)
+- **Solution**: 
+  1. Disconnect the MCP connection in ChatGPT/Claude settings
+  2. Reconnect and complete the OAuth flow again
+  3. The server will issue fresh tokens
+
+#### "PKCE verification failed"
+
+- **Cause**: PKCE code_verifier doesn't match code_challenge
+- **Solution**: This is a client-side issue; report to ChatGPT/Claude support
+- **Note**: The server requires S256 PKCE method (plain is not supported)
+
+#### "Invalid redirect_uri"
+
+- **Cause**: The OAuth callback URL doesn't match a registered pattern
+- **Solution**: 
+  - ChatGPT: Redirect URIs must match `https://chatgpt.com/*` or `https://chat.openai.com/*`
+  - Claude Web: Redirect URIs must match `https://claude.ai/*`
+
+### Re-Authorizing OAuth Connections
+
+If your OAuth connection stops working:
+
+**For ChatGPT:**
+1. Go to ChatGPT → **Settings** → **Connectors** (or **Apps**)
+2. Find the Shopify MCP connection
+3. Click **Disconnect** or **Remove**
+4. Click **Connect** again and complete the OAuth flow
+
+**For Claude Web:**
+1. Go to claude.ai → **Settings** → **Integrations**
+2. Find the Shopify MCP connector
+3. Click **Disconnect** or **Remove**
+4. Re-add the connector and authorize again
+
 ### Debug Mode
 
 Enable verbose logging to diagnose issues:

package/dist/{chunk-QXLLD2A7.js → chunk-5QMYOO4B.js}

@@ -97,17 +97,33 @@ var log = {
    * Info level logging
    *
    * @param msg - Info message
+   * @param data - Optional data object to include (JSON-stringified)
    */
-  info: (msg) => {
-    console.error(`[INFO] ${sanitizeLogMessage(msg)}`);
+  info: (msg, data) => {
+    const sanitizedMsg = sanitizeLogMessage(msg);
+    if (data) {
+      const sanitizedData = sanitizeObject(data);
+      const dataStr = safeStringify(sanitizedData);
+      console.error(`[INFO] ${sanitizedMsg} ${dataStr}`);
+    } else {
+      console.error(`[INFO] ${sanitizedMsg}`);
+    }
   },
   /**
    * Warning level logging
    *
    * @param msg - Warning message
+   * @param data - Optional data object to include (JSON-stringified)
    */
-  warn: (msg) => {
-    console.error(`[WARN] ${sanitizeLogMessage(msg)}`);
+  warn: (msg, data) => {
+    const sanitizedMsg = sanitizeLogMessage(msg);
+    if (data) {
+      const sanitizedData = sanitizeObject(data);
+      const dataStr = safeStringify(sanitizedData);
+      console.error(`[WARN] ${sanitizedMsg} ${dataStr}`);
+    } else {
+      console.error(`[WARN] ${sanitizedMsg}`);
+    }
   },
   /**
    * Error level logging