[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92307":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":28,"readmeContent":29,"aiSummary":30,"trendingCount":15,"starSnapshotCount":15,"syncStatus":31,"lastSyncTime":32,"discoverSource":33},92307,"shopify-mcp","Cesarjoquin\u002Fshopify-mcp","Cesarjoquin","shopify mcp server for Claude Desktop, Claude Code, or any MCP-compatible client to manage products, customers, orders, inventory, and metafields through a typed tool interface of shopify mcp","",null,"Rust",154,1138,52,0,61,55.27,"MIT License",false,"main",true,[23,24,25,26,5,27],"claude-desktop","mcp","mcp-tool","shopify","shopify-tool","2026-07-22 04:02:05","# Shopify MCP Server\n\nA production-oriented [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002F) server that exposes the Shopify Admin GraphQL API to AI assistants. Connect Claude Desktop, Claude Code, or any MCP-compatible client to manage products, customers, orders, inventory, and metafields through a typed tool interface.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Development](#development)\n- [Testing](#testing)\n- [Project Structure](#project-structure)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [FAQ](#faq)\n- [License](#license)\n\n---\n\n## Overview\n\nThis server translates MCP tool calls into Shopify Admin GraphQL operations. It supports static access tokens and OAuth client-credentials (Dev Dashboard apps), optional Redis-backed token persistence, structured JSON logging, and graceful shutdown.\n\n```mermaid\nflowchart LR\n  Client[MCP Client] -->|stdio JSON-RPC| Server[MCP Server]\n  Server --> Tools[Tool Registry]\n  Tools --> GraphQL[Shopify Admin GraphQL]\n  Server --> Auth[OAuth Token Manager]\n  Auth --> Redis[(Redis Cache)]\n  Auth --> GraphQL\n```\n\n---\n\n## Architecture\n\n### Runtime layers\n\n| Layer | Responsibility |\n|-------|----------------|\n| `src\u002Findex.ts` | Process entry, error boundary |\n| `src\u002Fserver\u002F` | Bootstrap, MCP wiring, shutdown hooks |\n| `src\u002Fconfig\u002F` | Environment and CLI configuration |\n| `src\u002Flib\u002F` | Auth, logging, Redis, shared utilities |\n| `src\u002Ftools\u002F` | 40 MCP tools (products, orders, customers, …) |\n\n### Request workflow\n\n```mermaid\nsequenceDiagram\n  participant C as MCP Client\n  participant M as McpServer\n  participant T as Tool\n  participant S as Shopify API\n\n  C->>M: tools\u002Fcall\n  M->>T: execute(args)\n  T->>T: Zod schema validation\n  T->>S: GraphQL request\n  S-->>T: Response\n  T-->>M: Formatted JSON\n  M-->>C: MCP content block\n```\n\n### Authentication flow\n\n```mermaid\nsequenceDiagram\n  participant S as Server\n  participant R as Redis\n  participant SH as Shopify OAuth\n\n  S->>R: Check cached token\n  alt Valid cache hit\n    R-->>S: access_token\n  else Cache miss\n    S->>SH: client_credentials grant\n    SH-->>S: access_token + expires_in\n    S->>R: Store token with TTL\n  end\n  Note over S: Auto-refresh 5 min before expiry\n```\n\n---\n\n## Features\n\n| Category | Capabilities |\n|----------|-------------|\n| **Products** | CRUD, variants, options, collections |\n| **Customers** | CRUD, merge, address management |\n| **Orders** | Query, cancel, fulfill, refund, draft orders |\n| **Metafields** | Read, write, delete on any resource |\n| **Inventory** | Set quantities, read levels and items |\n| **Discovery** | Shop info, locations, markets, price lists |\n| **Platform** | Redis token cache, structured logging, graceful shutdown, strict TypeScript |\n\nAll list tools support cursor pagination, sorting, and Shopify search syntax filtering.\n\n---\n\n## Requirements\n\n- **Node.js** 18 or later\n- **Shopify store** with a custom app and Admin API scopes\n- **Redis** (optional) for OAuth token persistence across restarts\n\n### Required Admin API scopes\n\n`read_products`, `write_products`, `read_customers`, `write_customers`, `read_orders`, `write_orders` (plus scopes for inventory\u002Fmetafields as needed).\n\n---\n\n## Installation\n\n### Run with npx (recommended)\n\n```bash\nnpx shopify-mcp \\\n  --clientId YOUR_CLIENT_ID \\\n  --clientSecret YOUR_CLIENT_SECRET \\\n  --domain your-store.myshopify.com\n```\n\n### Install from source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FGeLi2001\u002Fshopify-mcp.git\ncd shopify-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"shopify\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"shopify-mcp\",\n        \"--clientId\", \"\u003CCLIENT_ID>\",\n        \"--clientSecret\", \"\u003CCLIENT_SECRET>\",\n        \"--domain\", \"\u003Cstore>.myshopify.com\"\n      ]\n    }\n  }\n}\n```\n\nConfig locations:\n- **macOS:** `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n- **Windows:** `%APPDATA%\u002FClaude\u002Fclaude_desktop_config.json`\n\n---\n\n## Configuration\n\nCopy `.env.example` to `.env` and fill in values:\n\n```bash\ncp .env.example .env\n```\n\n### Environment variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `MYSHOPIFY_DOMAIN` | Yes | Store domain, e.g. `store.myshopify.com` |\n| `SHOPIFY_ACCESS_TOKEN` | Option A | Static `shpat_` token (legacy apps) |\n| `SHOPIFY_CLIENT_ID` | Option B | Dev Dashboard client ID |\n| `SHOPIFY_CLIENT_SECRET` | Option B | Dev Dashboard client secret |\n| `SHOPIFY_API_VERSION` | No | API version (default: `2026-01`) |\n| `LOG_LEVEL` | No | `debug`, `info`, `warn`, `error` |\n| `REDIS_ENABLED` | No | Enable Redis persistence (`true`\u002F`false`) |\n| `REDIS_URL` | If Redis | Connection URL, e.g. `redis:\u002F\u002F127.0.0.1:6379` |\n| `REDIS_KEY_PREFIX` | No | Key namespace prefix (default: `shopify-mcp:`) |\n| `REDIS_MAX_RETRIES` | No | Max command retries (default: `10`) |\n| `REDIS_CONNECT_TIMEOUT_MS` | No | Connect timeout in ms (default: `10000`) |\n\nCLI flags (`--accessToken`, `--clientId`, `--clientSecret`, `--domain`, `--apiVersion`) override environment variables.\n\n---\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run in development (TypeScript directly)\nnpm run dev\n\n# Full validation pipeline\nnpm run validate\n\n# GraphQL schema validation\nnpm run validate:graphql\n```\n\n### Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `npm run build` | Compile TypeScript to `dist\u002F` |\n| `npm run typecheck` | Type-check source and tests |\n| `npm run lint` | ESLint |\n| `npm test` | Jest unit tests |\n| `npm run validate` | typecheck + lint + test + build |\n\n---\n\n## Testing\n\nTests live in `tests\u002F` and cover configuration parsing, logging, error utilities, and Redis token caching.\n\n```bash\nnpm test\n```\n\nTests use mocked Redis clients — no running Redis instance required for the test suite.\n\n---\n\n## Project Structure\n\n```\nshopify-mcp\u002F\n├── docs\u002F\n│   └── AUDIT.md           # Internal architecture audit\n├── src\u002F\n│   ├── config\u002F            # Environment loading (Zod-validated)\n│   ├── lib\u002F               # Auth, logging, Redis, tool factory\n│   │   └── redis\u002F         # Connection manager + token cache\n│   ├── server\u002F            # Bootstrap, MCP server, shutdown\n│   ├── tools\u002F             # MCP tool implementations\n│   └── index.ts           # Entry point\n├── tests\u002F                 # Unit tests\n├── .env.example           # Configuration template\n├── .github\u002Fworkflows\u002F     # CI (build, lint, test, typecheck)\n└── package.json\n```\n\n**Design decisions:**\n- Tools use a `createTool()` factory to eliminate duplicated GraphQL client wiring.\n- Configuration is centralized in `src\u002Fconfig\u002Fenv.ts` with Zod validation.\n- OAuth tokens optionally persist in Redis so restarts do not force re-authentication.\n- Logs are structured JSON on stderr (safe for stdio MCP transport).\n\n---\n\n## Troubleshooting\n\n### Authentication errors\n\n```\nAuthentication credentials are required\n```\n\nProvide either `SHOPIFY_ACCESS_TOKEN` or both `SHOPIFY_CLIENT_ID` and `SHOPIFY_CLIENT_SECRET`.\n\n### Wrong package installed\n\nIf you see errors referencing a different package name, verify you are running `shopify-mcp` (this package), not a similarly named alternative.\n\n### MCP connection issues\n\nCheck Claude Desktop MCP logs:\n\n```bash\n# macOS\ntail -f ~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp*.log\n```\n\nEnsure the server starts without errors:\n\n```bash\nSHOPIFY_ACCESS_TOKEN=shpat_xxx MYSHOPIFY_DOMAIN=store.myshopify.com npm start\n```\n\n### Redis connection failures\n\nIf `REDIS_ENABLED=true` but Redis is unreachable, the server exits at startup. Either start Redis locally or set `REDIS_ENABLED=false`.\n\n```bash\ndocker run -d -p 6379:6379 redis:7-alpine\n```\n\n### GraphQL userErrors\n\nShopify returns field-level errors in mutation responses. The server surfaces these as `Failed to \u003Coperation>: field: message`.\n\n---\n\n## Contributing\n\n1. Fork the repository and create a feature branch.\n2. Run `npm run validate` before opening a pull request.\n3. Keep commits focused and write clear commit messages.\n4. Add tests for new library or configuration behavior.\n5. Do not commit secrets, `.env`, or `package-lock.json`.\n\n---\n\n## FAQ\n\n**Does this replace the Shopify Admin UI?**  \nNo. It provides programmatic access for AI assistants via MCP.\n\n**Can I use a static access token?**  \nYes. Set `SHOPIFY_ACCESS_TOKEN` for legacy custom apps with `shpat_` tokens.\n\n**Is Redis required?**  \nNo. Redis is optional and only caches OAuth tokens for client-credentials auth.\n\n**How many tools are available?**  \n40 tools covering products, customers, orders, metafields, inventory, and store discovery.\n\n**Which API version is used?**  \nDefault `2026-01`. Override with `SHOPIFY_API_VERSION` or `--apiVersion`.\n\n**Why JSON logs on stderr?**  \nMCP uses stdout for the protocol. Logs must go to stderr to avoid corrupting the transport.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","这是一个为 Shopify 商店提供 AI 助手集成能力的 Model Context Protocol（MCP）服务端实现。它将 MCP 工具调用安全、结构化地映射至 Shopify Admin GraphQL API，支持产品、客户、订单、库存、元字段等核心资源的增删改查操作，并内置 OAuth 认证管理、Redis 令牌缓存、Zod 参数校验与结构化日志。适用于需通过 Claude Desktop\u002FCode 或其他 MCP 兼容客户端自动化管理 Shopify 店铺的开发者与运营团队。",2,"2026-07-08 04:30:02","CREATED_QUERY"]