@anton.andrusenko/shopify-mcp-admin 1.1.2 → 2.0.0

package/README.md

@@ -40,9 +40,25 @@ npx @anton.andrusenko/shopify-mcp-admin
 npm install -g @anton.andrusenko/shopify-mcp-admin
 ```
 
-### Configuration
+### Setup Wizard (Recommended)
 
-Set your environment variables:
+The easiest way to get started is with the interactive setup wizard:
+
+```bash
+npx @anton.andrusenko/shopify-mcp-admin init
+```
+
+The wizard will:
+1. **Prompt for your store URL** and validate the format
+2. **Choose authentication method** — Legacy token or OAuth 2.0
+3. **Test the connection** — Verifies credentials before saving
+4. **Select your AI client** — Claude Desktop, Cursor, Windsurf, VS Code, LibreChat, or OpenAI
+5. **Configure tool loading** — All tools, role preset, or lazy loading
+6. **Generate and save config** — Creates the appropriate config file for your client
+
+### Manual Configuration
+
+Alternatively, set environment variables directly:
 
 ```bash
 export SHOPIFY_STORE_URL=your-store.myshopify.com
@@ -99,10 +115,13 @@ Tokens are automatically refreshed every 24 hours.
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `SHOPIFY_STORE_URL` | ✅ Yes | — | Your Shopify store domain (e.g., `your-store.myshopify.com`) |
+| `SERVER_MODE` | No | `local` | Server mode: `local` (single-tenant) or `remote` (multi-tenant) |
+| `SHOPIFY_STORE_URL` | ✅ (local mode) | — | Your Shopify store domain (e.g., `your-store.myshopify.com`) |
 | `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 |
+| `DATABASE_URL` | ✅ (remote mode) | — | PostgreSQL connection URL for multi-tenant mode |
+| `ENCRYPTION_KEY` | ✅ (remote mode) | — | 64-char hex key for credential encryption |
 | `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`) |
@@ -111,7 +130,28 @@ Tokens are automatically refreshed every 24 hours.
 | `SHOPIFY_MCP_LAZY_LOADING` | No | `false` | Enable modular lazy loading (set to `true` for on-demand module loading) |
 | `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).
+### Server Modes
+
+shopify-mcp-admin supports two operating modes:
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| **local** (default) | Single-tenant with env credentials | Claude Desktop, local AI agents, development |
+| **remote** | Multi-tenant with database storage | SaaS platform, hosted service |
+
+**Local Mode** (default):
+- Credentials via `SHOPIFY_STORE_URL` + `SHOPIFY_ACCESS_TOKEN` (or OAuth)
+- All 79 tools operate on a single store
+- No database required
+- Works with STDIO and HTTP transports
+
+**Remote Mode**:
+- Multi-tenant with per-tenant credentials stored in PostgreSQL
+- Requires `DATABASE_URL` and `ENCRYPTION_KEY`
+- HTTP transport only (STDIO not supported for multi-tenant)
+- Web dashboard available at `/app`
+
+**⚡ Authentication (local mode):** Provide EITHER `SHOPIFY_ACCESS_TOKEN` (legacy) OR both `SHOPIFY_CLIENT_ID` and `SHOPIFY_CLIENT_SECRET` (Dev Dashboard).
 
 ### Required Shopify Scopes
 
@@ -1187,6 +1227,94 @@ Enable these settings for the `main` branch in **Settings → Branches**:
 
 ---
 
+## 🚀 Deployment
+
+shopify-mcp-admin supports multiple deployment options for different environments:
+
+### Railway (Recommended for Quick Start)
+
+Deploy to [Railway](https://railway.app) with the included `railway.json` configuration:
+
+1. Connect your GitHub repository to Railway
+2. Add environment variables (DATABASE_URL, ENCRYPTION_KEY, etc.)
+3. Deploy — Railway auto-detects the Dockerfile
+
+### Kubernetes
+
+For self-hosted or cloud Kubernetes clusters, see the [Kubernetes Deployment Guide](docs/kubernetes.md).
+
+Quick start:
+```bash
+# Build and push image
+docker build -t yourregistry/shopify-mcp-admin:v1.0.0 .
+docker push yourregistry/shopify-mcp-admin:v1.0.0
+
+# Configure and deploy
+cd k8s
+kustomize edit set image shopify-mcp-admin=yourregistry/shopify-mcp-admin:v1.0.0
+kubectl apply -k .
+```
+
+### Docker (Local/Development)
+
+```bash
+# Build image
+docker build -t shopify-mcp-admin .
+
+# Run container
+docker run -p 3000:3000 \
+  -e DATABASE_URL="postgresql://..." \
+  -e ENCRYPTION_KEY="..." \
+  shopify-mcp-admin
+```
+
+### Image Size
+
+The production Docker image is optimized for minimal size:
+- Multi-stage build with Alpine Linux
+- Production dependencies only (`npm prune --production`)
+- Target size: <150MB
+
+---
+
+## 🎨 Tenant Dashboard (Remote Mode)
+
+When running in remote mode (`SERVER_MODE=remote`), shopify-mcp-admin includes a web-based dashboard for tenant management. The dashboard provides a modern, responsive UI for:
+
+- **Shop Management** — View and connect Shopify stores
+- **API Key Management** — Generate, copy, and revoke API keys
+- **Usage Statistics** — Monitor API calls and activity
+- **Account Settings** — Update profile and change password
+
+### Accessing the Dashboard
+
+1. Start the server in remote mode:
+```bash
+SERVER_MODE=remote npm start
+```
+
+2. Navigate to `http://localhost:3000/app` in your browser
+
+3. Log in with your tenant credentials
+
+### Dashboard Features
+
+- ✨ **Modern UI** — Built with React, Vite, and Tailwind CSS
+- 📱 **Responsive Design** — Works on desktop, tablet, and mobile
+- ♿ **Accessible** — WCAG AA compliant with keyboard navigation
+- 🔐 **Secure** — Session-based authentication with HttpOnly cookies
+- 🎯 **Optimized** — <150KB gzipped bundle size
+
+### Tech Stack
+
+- **Frontend:** React 18 + Vite + TypeScript
+- **Styling:** Tailwind CSS + shadcn/ui components
+- **State:** React Query for server state management
+- **Forms:** React Hook Form + Zod validation
+- **Auth:** Session cookies with automatic expiry handling
+
+---
+
 ## 🤝 Contributing
 
 Contributions are welcome! Here's how to get started:
@@ -1251,3 +1379,55 @@ This project is licensed under the **MIT License** — see the [LICENSE](LICENSE
   <strong>Made with ❤️ for the AI-powered commerce era</strong>
 </p>
 
+---
+
+## 🚀 Deployment
+
+### Production Deployment
+
+For production deployment on Railway with Cloudflare, Sentry, and uptime monitoring, see the comprehensive deployment guide:
+
+📖 **[Production Deployment Guide](./docs/deployment.md)**
+
+The guide includes:
+- **Railway Setup**: Step-by-step instructions for deploying to Railway
+- **Cloudflare DNS**: DNS configuration and SSL/TLS setup
+- **Database Setup**: Prisma migrations and backup strategy
+- **Staging Environment**: Separate staging deployment configuration
+- **Monitoring**: Sentry error tracking and uptime monitoring setup
+
+### Environment Variables
+
+For production environment variables, see:
+
+📄 **[`.env.production.example`](./.env.production.example)**
+
+This template includes all required and optional environment variables with descriptions, example values, and generation instructions.
+
+### Quick Start: Local vs Production
+
+| Mode | Use Case | Transport | Database | Credentials |
+|------|----------|-----------|----------|-------------|
+| **Local** | Development, Claude Desktop | STDIO or HTTP | None | Environment variables |
+| **Remote** | Production, SaaS platform | HTTP only | PostgreSQL | Database (encrypted) |
+
+**Local Mode** (default):
+```bash
+export SHOPIFY_STORE_URL=your-store.myshopify.com
+export SHOPIFY_ACCESS_TOKEN=shpat_xxxxx
+npx @anton.andrusenko/shopify-mcp-admin
+```
+
+**Remote Mode** (production):
+```bash
+export SERVER_MODE=remote
+export DATABASE_URL=postgresql://...
+export ENCRYPTION_KEY=<64-char-hex>
+export TRANSPORT=http
+# See .env.production.example for all variables
+```
+
+---
+
+</p>
+

package/dist/chunk-3Y4P67GZ.js

@@ -0,0 +1,124 @@
+import {
+  log
+} from "./chunk-GKGHMPEC.js";
+
+// src/middleware/mcp-auth.ts
+var MCP_AUTH_ERROR_CODES = {
+  AUTH_REQUIRED: -32001,
+  // Missing authentication
+  AUTH_INVALID: -32002,
+  // Invalid API key format or key
+  AUTH_REVOKED: -32003,
+  // API key has been revoked
+  AUTH_FORBIDDEN: -32004
+  // Tenant suspended or no access
+};
+function createJsonRpcError(code, message, hint) {
+  const error = {
+    jsonrpc: "2.0",
+    error: {
+      code,
+      message
+    },
+    id: null
+  };
+  if (hint) {
+    error.error.data = { hint };
+  }
+  return error;
+}
+function parseBearerToken(authHeader) {
+  if (!authHeader) {
+    return null;
+  }
+  const parts = authHeader.split(" ");
+  if (parts.length !== 2 || parts[0].toLowerCase() !== "bearer") {
+    return null;
+  }
+  const token = parts[1];
+  if (!token || token.trim() === "") {
+    return null;
+  }
+  return token;
+}
+async function validateMcpApiKey(authHeader, apiKeyService, prisma) {
+  const token = parseBearerToken(authHeader);
+  if (!token) {
+    return {
+      valid: false,
+      error: "Authentication required",
+      httpStatus: 401
+    };
+  }
+  const validationResult = await apiKeyService.validate(token);
+  if (!validationResult.valid) {
+    const isRevoked = validationResult.error?.includes("revoked");
+    return {
+      valid: false,
+      error: validationResult.error || "Invalid API key",
+      httpStatus: isRevoked ? 403 : 401
+    };
+  }
+  const tenant = validationResult.tenant;
+  const tenantShops = await prisma.tenantShop.findMany({
+    where: {
+      tenantId: tenant.tenantId,
+      uninstalledAt: null
+      // Only active shops
+    },
+    select: {
+      shopDomain: true,
+      scopes: true
+    }
+  });
+  const allowedShops = tenantShops.map((shop) => shop.shopDomain);
+  const mcpTenantContext = {
+    tenantId: tenant.tenantId,
+    email: tenant.email,
+    defaultShop: validationResult.shop,
+    allowedShops
+  };
+  return {
+    valid: true,
+    tenant: mcpTenantContext
+  };
+}
+function createMcpAuthMiddleware(options) {
+  const { apiKeyService, prisma, isRemote } = options;
+  return async (req, res, next) => {
+    if (!isRemote) {
+      log.debug("[mcp-auth] Local mode: skipping API key validation");
+      next();
+      return;
+    }
+    const authResult = await validateMcpApiKey(req.headers.authorization, apiKeyService, prisma);
+    if (!authResult.valid) {
+      log.debug(`[mcp-auth] Auth failed: ${authResult.error}`);
+      let errorCode;
+      let hint;
+      if (authResult.httpStatus === 401) {
+        errorCode = authResult.error === "Authentication required" ? MCP_AUTH_ERROR_CODES.AUTH_REQUIRED : MCP_AUTH_ERROR_CODES.AUTH_INVALID;
+        hint = "Include Authorization: Bearer sk_live_xxx header";
+      } else {
+        errorCode = authResult.error?.includes("revoked") ? MCP_AUTH_ERROR_CODES.AUTH_REVOKED : MCP_AUTH_ERROR_CODES.AUTH_FORBIDDEN;
+        hint = "API key has been revoked or tenant is inactive";
+      }
+      res.status(authResult.httpStatus || 401).json(createJsonRpcError(errorCode, authResult.error || "Authentication failed", hint));
+      return;
+    }
+    req.mcpTenantContext = authResult.tenant;
+    log.debug(
+      `[mcp-auth] Auth successful for tenant: ${authResult.tenant?.tenantId?.substring(0, 8)}...`
+    );
+    next();
+  };
+}
+var MCP_AUTH_ERRORS = MCP_AUTH_ERROR_CODES;
+
+export {
+  createJsonRpcError,
+  parseBearerToken,
+  validateMcpApiKey,
+  createMcpAuthMiddleware,
+  MCP_AUTH_ERRORS
+};

package/dist/chunk-6YECVENJ.js

@@ -0,0 +1,208 @@
+import {
+  log
+} from "./chunk-GKGHMPEC.js";
+
+// src/db/client.ts
+import { PrismaClient } from "@prisma/client";
+import { PrismaClient as PrismaClient2 } from "@prisma/client";
+var prismaInstance = null;
+function getPrismaClient() {
+  if (!prismaInstance) {
+    log.debug("Creating new Prisma client instance");
+    prismaInstance = new PrismaClient({
+      log: process.env.DEBUG === "true" ? ["query", "info", "warn", "error"] : ["error"]
+    });
+  }
+  return prismaInstance;
+}
+async function disconnectPrisma() {
+  if (prismaInstance) {
+    log.debug("Disconnecting Prisma client");
+    await prismaInstance.$disconnect();
+    prismaInstance = null;
+  }
+}
+var prisma = getPrismaClient();
+
+// src/session/store.ts
+var SessionStore = class {
+  cleanupInterval = null;
+  prisma = getPrismaClient();
+  SESSION_TTL_MS = 24 * 60 * 60 * 1e3;
+  // 24 hours
+  /**
+   * Retrieve session data by session ID
+   * @param sessionId - Unique session identifier
+   * @returns SessionData if valid and not expired, null otherwise
+   */
+  async get(sessionId) {
+    try {
+      const session = await this.prisma.tenantSession.findUnique({
+        where: { id: sessionId },
+        select: {
+          tenantId: true,
+          expiresAt: true
+        }
+      });
+      if (!session) {
+        return null;
+      }
+      const expiresAt = session.expiresAt.getTime();
+      if (expiresAt < Date.now()) {
+        await this.prisma.tenantSession.delete({
+          where: { id: sessionId }
+        }).catch(() => {
+        });
+        return null;
+      }
+      return {
+        tenantId: session.tenantId,
+        expiresAt
+      };
+    } catch (error) {
+      log.error("Failed to retrieve session", error instanceof Error ? error : void 0);
+      return null;
+    }
+  }
+  /**
+   * Store session data with automatic 24-hour expiration
+   * @param sessionId - Unique session identifier
+   * @param data - Session data (tenantId)
+   */
+  async set(sessionId, data) {
+    const expiresAt = new Date(Date.now() + this.SESSION_TTL_MS);
+    try {
+      await this.prisma.tenantSession.upsert({
+        where: { id: sessionId },
+        update: {
+          expiresAt
+        },
+        create: {
+          id: sessionId,
+          tenantId: data.tenantId,
+          expiresAt
+        }
+      });
+    } catch (error) {
+      log.error("Failed to store session", error instanceof Error ? error : void 0);
+      throw error;
+    }
+  }
+  /**
+   * Delete a specific session
+   * @param sessionId - Session identifier to delete
+   */
+  async delete(sessionId) {
+    try {
+      await this.prisma.tenantSession.delete({
+        where: { id: sessionId }
+      });
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code !== "P2025") {
+        log.error("Failed to delete session", error instanceof Error ? error : void 0);
+      }
+    }
+  }
+  /**
+   * Delete all sessions for a specific tenant
+   * Used when a tenant changes their password for security
+   * @param tenantId - Tenant identifier
+   */
+  async deleteByTenantId(tenantId) {
+    try {
+      await this.prisma.tenantSession.deleteMany({
+        where: { tenantId }
+      });
+      log.debug(`Deleted all sessions for tenant ${tenantId}`);
+    } catch (error) {
+      log.error("Failed to delete tenant sessions", error instanceof Error ? error : void 0);
+      throw error;
+    }
+  }
+  /**
+   * Remove all expired sessions from the store
+   */
+  async cleanup() {
+    try {
+      const result = await this.prisma.tenantSession.deleteMany({
+        where: {
+          expiresAt: {
+            lt: /* @__PURE__ */ new Date()
+          }
+        }
+      });
+      if (result.count > 0) {
+        log.debug(`Cleaned up ${result.count} expired sessions`);
+      }
+    } catch (error) {
+      log.error("Session cleanup failed", error instanceof Error ? error : void 0);
+    }
+  }
+  /**
+   * Start automatic cleanup task (runs every 10 minutes)
+   * @returns Timer handle for cleanup task
+   */
+  startCleanup() {
+    if (this.cleanupInterval) {
+      return this.cleanupInterval;
+    }
+    this.cleanupInterval = setInterval(
+      () => {
+        this.cleanup().catch((error) => {
+          log.error("Background session cleanup error", error instanceof Error ? error : void 0);
+        });
+      },
+      10 * 60 * 1e3
+    );
+    this.cleanupInterval.unref();
+    log.info("Session cleanup background task started (runs every 10 minutes)");
+    return this.cleanupInterval;
+  }
+  /**
+   * Stop the automatic cleanup task
+   */
+  stopCleanup() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+      log.info("Session cleanup background task stopped");
+    }
+  }
+  /**
+   * Get the number of active sessions (for testing/monitoring)
+   */
+  async size() {
+    try {
+      return await this.prisma.tenantSession.count({
+        where: {
+          expiresAt: {
+            gte: /* @__PURE__ */ new Date()
+          }
+        }
+      });
+    } catch (error) {
+      log.error("Failed to count sessions", error instanceof Error ? error : void 0);
+      return 0;
+    }
+  }
+  /**
+   * Clear all sessions (for testing)
+   */
+  async clear() {
+    try {
+      await this.prisma.tenantSession.deleteMany();
+    } catch (error) {
+      log.error("Failed to clear sessions", error instanceof Error ? error : void 0);
+      throw error;
+    }
+  }
+};
+var sessionStore = new SessionStore();
+
+export {
+  getPrismaClient,
+  disconnectPrisma,
+  prisma,
+  SessionStore,
+  sessionStore
+};