@anton.andrusenko/shopify-mcp-admin 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 shopify-mcp-admin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,454 @@
+# 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)
+[![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/)
+
+---
+
+## ✨ Features
+
+- 🛠️ **40 MCP Tools** — Complete store management: products, inventory, collections, pages, blogs, redirects
+- 🤖 **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
+- 🔒 **Secure** — Tokens never exposed to AI agents; validated environment configuration
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+1. **Node.js 20+** — [Download](https://nodejs.org/)
+2. **Shopify Custom App** — Create one in your Shopify Admin:
+   - Go to **Settings → Apps and sales channels → Develop apps**
+   - Create a new app and configure Admin API scopes (see [Required Scopes](#required-shopify-scopes))
+   - Install the app and copy the Admin API access token
+
+### Installation
+
+```bash
+# Run directly with npx (recommended)
+npx shopify-mcp-admin
+
+# Or install globally
+npm install -g shopify-mcp-admin
+```
+
+### Configuration
+
+Set your environment variables:
+
+```bash
+export SHOPIFY_STORE_URL=your-store.myshopify.com
+export SHOPIFY_ACCESS_TOKEN=shpat_xxxxx
+```
+
+### First Tool Invocation
+
+Once connected to an AI agent, try:
+
+> "List all products in my Shopify store"
+
+The AI will use the `list-products` tool to fetch your catalog.
+
+---
+
+## ⚙️ 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_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` |
+
+### Required Shopify Scopes
+
+Configure these scopes when creating your Custom App:
+
+| Scope | Purpose |
+|-------|---------|
+| `read_products`, `write_products` | Product management |
+| `read_inventory`, `write_inventory` | Inventory management |
+| `read_content`, `write_content` | Pages, blogs, articles |
+| `read_online_store_navigation`, `write_online_store_navigation` | URL redirects |
+
+📖 **Setup Guide:** [Shopify Custom App Documentation](https://shopify.dev/docs/apps/tools/development-stores)
+
+---
+
+## 🖥️ Claude Desktop Integration
+
+### Step 1: Configure Claude Desktop
+
+Edit your Claude Desktop configuration file:
+
+- **macOS:** `~/.config/claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Step 2: Add the MCP Server
+
+```json
+{
+  "mcpServers": {
+    "shopify": {
+      "command": "npx",
+      "args": ["shopify-mcp-admin"],
+      "env": {
+        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
+        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx"
+      }
+    }
+  }
+}
+```
+
+### Step 3: Restart Claude Desktop
+
+Quit and reopen Claude Desktop. You should see "shopify" in the MCP servers list.
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Server not appearing | Check JSON syntax; ensure no trailing commas |
+| "Command not found" | Ensure Node.js 20+ is installed and in PATH |
+| Authentication errors | Verify `SHOPIFY_ACCESS_TOKEN` is correct |
+
+---
+
+## 🌐 OpenAI/ChatGPT Integration
+
+For OpenAI function calling or ChatGPT plugins, use HTTP transport mode.
+
+### Step 1: Start the Server
+
+```bash
+TRANSPORT=http \
+PORT=3000 \
+SHOPIFY_STORE_URL=your-store.myshopify.com \
+SHOPIFY_ACCESS_TOKEN=shpat_xxxxx \
+npx shopify-mcp-admin
+```
+
+### Step 2: Test the Connection
+
+```bash
+# List available tools
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
+```
+
+### Step 3: Call a Tool
+
+```bash
+# Example: List products
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "params": {
+      "name": "list-products",
+      "arguments": { "first": 10 }
+    },
+    "id": 2
+  }'
+```
+
+### OpenAI Function Calling Format
+
+Each tool can be converted to OpenAI function format:
+
+```json
+{
+  "name": "list-products",
+  "description": "List products from the Shopify store with optional filtering",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "first": { "type": "number", "description": "Number of products to return" },
+      "query": { "type": "string", "description": "Search query" }
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Available Tools
+
+shopify-mcp-admin provides **40 tools** organized into 7 categories:
+
+<details>
+<summary><strong>📦 Product Management (7 tools)</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `create-product` | Create a new product with title, description, variants, and images |
+| `get-product` | Retrieve a product by ID with full details |
+| `update-product` | Update product title, description, status, SEO fields |
+| `delete-product` | Delete a product by ID |
+| `list-products` | List products with pagination and search |
+| `update-product-variant` | Update variant price, SKU, inventory policy |
+| `add-product-image` | Add an image to a product from URL |
+
+</details>
+
+<details>
+<summary><strong>🏷️ Metafields (3 tools)</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `get-product-metafields` | Get all metafields for a product |
+| `set-product-metafields` | Set or update metafields on a product |
+| `delete-product-metafields` | Delete specific metafields from a product |
+
+</details>
+
+<details>
+<summary><strong>📁 Collection Management (7 tools)</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `create-collection` | Create a manual or smart collection |
+| `get-collection` | Retrieve collection details and products |
+| `update-collection` | Update collection title, description, SEO |
+| `delete-collection` | Delete a collection by ID |
+| `list-collections` | List all collections with pagination |
+| `add-products-to-collection` | Add products to a manual collection |
+| `remove-products-from-collection` | Remove products from a manual collection |
+
+</details>
+
+<details>
+<summary><strong>🖼️ Enhanced Image Management (3 tools)</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `update-product-image` | Update image alt text for SEO |
+| `delete-product-image` | Delete an image from a product |
+| `reorder-product-images` | Reorder product images by position |
+
+</details>
+
+<details>
+<summary><strong>🔀 URL Redirects (3 tools)</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `create-redirect` | Create a URL redirect (301/302) |
+| `delete-redirect` | Delete a URL redirect |
+| `list-redirects` | List all URL redirects |
+
+</details>
+
+<details>
+<summary><strong>📄 Page Management (5 tools)</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `create-page` | Create a new page (About, Contact, etc.) |
+| `get-page` | Retrieve a page by ID or handle |
+| `update-page` | Update page title, content, SEO |
+| `delete-page` | Delete a page by ID |
+| `list-pages` | List all pages with pagination |
+
+</details>
+
+<details>
+<summary><strong>📝 Blog & Article Management (8 tools)</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `create-blog` | Create a new blog |
+| `update-blog` | Update blog title and settings |
+| `delete-blog` | Delete a blog (and all articles) |
+| `list-blogs` | List all blogs |
+| `create-article` | Create a blog article |
+| `update-article` | Update article title, content, SEO |
+| `delete-article` | Delete an article |
+| `list-articles` | List articles in a blog |
+
+</details>
+
+<details>
+<summary><strong>📊 Inventory Management (4 tools)</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `get-inventory` | Get inventory levels for a product variant |
+| `update-inventory` | Set or adjust inventory quantity |
+| `list-low-inventory` | Find products with low stock |
+| `get-bulk-inventory` | Get inventory for multiple variants/locations |
+
+</details>
+
+---
+
+## 🔧 Troubleshooting
+
+### Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `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` |
+| `Invalid store URL` | Wrong URL format | Use `store.myshopify.com` format |
+
+### Debug Mode
+
+Enable verbose logging to diagnose issues:
+
+```bash
+# Option 1: DEBUG flag
+DEBUG=1 npx shopify-mcp-admin
+
+# Option 2: LOG_LEVEL
+LOG_LEVEL=debug npx shopify-mcp-admin
+```
+
+### FAQ
+
+**Q: Can I connect to multiple stores?**  
+A: Run separate server instances with different credentials.
+
+**Q: Does this work with development stores?**  
+A: Yes, development stores work with Custom Apps.
+
+**Q: How do I test without affecting production?**  
+A: Use a [development store](https://shopify.dev/docs/apps/tools/development-stores) for testing.
+
+**Q: Where can I report bugs?**  
+A: Open an issue on [GitHub Issues](https://github.com/AntonAndrusenko/shopify-mcp-admin/issues).
+
+---
+
+## 🔄 CI/CD Pipeline
+
+This project uses GitHub Actions for continuous integration and automated releases.
+
+### Continuous Integration
+
+Every push to `main` and every pull request triggers the CI workflow:
+
+```yaml
+# Runs on Node.js 20.x and 22.x
+npm ci        # Install dependencies
+npm run lint  # Biome linting
+npm run typecheck  # TypeScript type checking
+npm run test  # Vitest unit tests
+npm run build # Production build
+```
+
+All checks must pass before merging pull requests.
+
+### Automated Releases
+
+To publish a new version to npm:
+
+```bash
+# 1. Update version (creates git tag automatically)
+npm version patch  # or minor, or major
+
+# 2. Push commit and tag
+git push origin main --follow-tags
+```
+
+The release workflow automatically:
+1. Runs all CI checks
+2. Publishes to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements)
+3. Tags the npm package to match the git tag
+
+### Repository Setup (for Maintainers)
+
+#### Required Secrets
+
+Configure these in **Settings → Secrets and variables → Actions**:
+
+| Secret | Description |
+|--------|-------------|
+| `NPM_TOKEN` | npm automation token for publishing ([create one](https://docs.npmjs.com/creating-and-viewing-access-tokens)) |
+
+#### Branch Protection (Recommended)
+
+Enable these settings for the `main` branch in **Settings → Branches**:
+
+- ✅ Require a pull request before merging
+- ✅ Require status checks to pass before merging
+  - Select: `build (20.x)` and `build (22.x)`
+- ✅ Require branches to be up to date before merging
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Here's how to get started:
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/AntonAndrusenko/shopify-mcp-admin.git
+cd shopify-mcp-admin
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+```
+
+### Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with hot reload |
+| `npm run build` | Build for production |
+| `npm run test` | Run unit tests |
+| `npm run lint` | Run Biome linter |
+| `npm run lint:fix` | Auto-fix linting issues |
+
+### Pull Request Guidelines
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes with tests
+4. Run `npm run lint && npm run test`
+5. Commit with conventional commits (`feat:`, `fix:`, `docs:`, etc.)
+6. Open a Pull Request
+
+### Code Style
+
+This project uses [Biome](https://biomejs.dev/) for linting and formatting. Configuration is in `biome.json`.
+
+---
+
+## 📜 License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
+- [Shopify Admin API](https://shopify.dev/docs/api/admin)
+- Built with TypeScript, Express, and Zod
+
+---
+
+<p align="center">
+  <strong>Made with ❤️ for the AI-powered commerce era</strong>
+</p>
+

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node