内容
# Shopify MCP 服务器
一个面向生产的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，暴露 Shopify Admin GraphQL API 给 AI 助手。连接 Claude Desktop、Claude Code 或任何 MCP 兼容的客户端，通过类型化的工具接口管理产品、客户、订单、库存和元字段。
---
## 目录
- [概述](#概述)
- [架构](#架构)
- [功能](#功能)
- [需求](#需求)
- [安装](#安装)
- [配置](#配置)
- [开发](#开发)
- [测试](#测试)
- [项目结构](#项目结构)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [常见问题](#常见问题)
- [许可证](#许可证)
---
## 概述
该服务器将 MCP 工具调用转换为 Shopify Admin GraphQL 操作。它支持静态访问令牌和 OAuth 客户端凭证（开发仪表盘应用），可选的 Redis 缓存令牌持久性，结构化 JSON 日志记录和优雅的关闭。
```mermaid
flowchart LR
客户端[MCP 客户端] -->|stdio JSON-RPC| 服务器[MCP 服务器]
服务器 --> 工具[工具注册表]
工具 --> GraphQL[Shopify Admin GraphQL]
服务器 --> 认证[OAuth 令牌管理器]
认证 --> Redis[(Redis 缓存)]
认证 --> GraphQL
```
---
## 架构
### 运行时层
| 层 | 责任 |
|-------|----------------|
| `src/index.ts` | 进程入口，错误边界 |
| `src/server/` | 启动，MCP 连接，关闭钩子 |
| `src/config/` | 环境和 CLI 配置 |
| `src/lib/` | 认证，日志记录，Redis，共享实用程序 |
| `src/tools/` | 40 个 MCP 工具（产品，订单，客户，…） |
### 请求工作流
```mermaid
sequenceDiagram
参与者 C as MCP 客户端
参与者 M as McpServer
参与者 T as 工具
参与者 S as Shopify API
C->>M: 工具/调用
M->>T: 执行（参数）
T->>T: Zod 模式验证
T->>S: GraphQL 请求
S-->>T: 响应
T-->>M: 格式化 JSON
M-->>C: MCP 内容块
```
### 认证流程
```mermaid
sequenceDiagram
参与者 S as 服务器
参与者 R as Redis
参与者 SH as Shopify OAuth
S->>R: 检查缓存令牌
alt 有效缓存命中
R-->>S: access_token
else 缓存未命中
S->>SH: 客户端凭证授权
SH-->>S: access_token + expires_in
S->>R: 存储令牌并设置 TTL
end
Note over S: 在过期前 5 分钟自动刷新
```
---
## 功能
| 类别 | 功能 |
|----------|-------------|
| **产品** | CRUD，变体，选项，集合 |
| **客户** | CRUD，合并，地址管理 |
| **订单** | 查询，取消，完成，退款，草稿订单 |
| **元字段** | 读取，写入，删除任意资源 |
| **库存** | 设置数量，读取级别和项目 |
| **发现** | 商店信息，位置，市场，价格列表 |
| **平台** | Redis 令牌缓存，结构化日志记录，优雅关闭，严格 TypeScript |
所有列表工具支持光标分页，排序和 Shopify 搜索语法筛选。
---
## 需求
- **Node.js** 18 或更高版本
- **Shopify 商店**，带有自定义应用和 Admin API 范围
- **Redis**（可选）用于 OAuth 令牌在重启期间的持久性
### 要求的 Admin API 范围
`read_products`，`write_products`，`read_customers`，`write_customers`，`read_orders`，`write_orders`（以及库存/元字段所需的范围）。
---
## 安装
### 使用 npx 运行（推荐）
```bash
npx shopify-mcp \
--clientId 您的_CLIENT_ID \
--clientSecret 您的_CLIENT_SECRET \
--domain 您的商店.myshopify.com
```
### 从源代码安装
```bash
git clone https://github.com/GeLi2001/shopify-mcp.git
cd shopify-mcp
npm install
npm run build
npm start
```
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"shopify": {
"command": "npx",
"args": [
"shopify-mcp",
"--clientId", "<CLIENT_ID>",
"--clientSecret", "<CLIENT_SECRET>",
"--domain", "<store>.myshopify.com"
]
}
}
}
```
配置位置：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
---
## 配置
复制 `.env.example` 到 `.env` 并填写值：
```bash
cp .env.example .env
```
### 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `MYSHOPIFY_DOMAIN` | 是 | 商店域名，例如 `store.myshopify.com` |
| `SHOPIFY_ACCESS_TOKEN` | 选项 A | 静态 `shpat_` 令牌（旧应用） |
| `SHOPIFY_CLIENT_ID` | 选项 B | 开发仪表盘客户端 ID |
| `SHOPIFY_CLIENT_SECRET` | 选项 B | 开发仪表盘客户端密钥 |
| `SHOPIFY_API_VERSION` | 否 | API 版本（默认：`2026-01`） |
| `LOG_LEVEL` | 否 | `debug`，`info`，`warn`，`error` |
| `REDIS_ENABLED` | 否 | 启用 Redis 持久性（`true`/`false`） |
| `REDIS_URL` | 如果使用 Redis | 连接 URL，例如 `redis://127.0.0.1:6379` |
| `REDIS_KEY_PREFIX` | 否 | 键命名空间前缀（默认：`shopify-mcp:`） |
| `REDIS_MAX_RETRIES` | 否 | 最大命令重试次数（默认：`10`） |
| `REDIS_CONNECT_TIMEOUT_MS` | 否 | 连接超时，毫秒（默认：`10000`） |
CLI 标志（`--accessToken`，`--clientId`，`--clientSecret`，`--domain`，`--apiVersion`）覆盖环境变量。
---
## 开发
```bash
# 安装依赖
npm install
# 在开发环境中运行（直接使用 TypeScript）
npm run dev
# 完整的验证管道
npm run validate
# GraphQL 模式验证
npm run validate:graphql
```
### 脚本
| 脚本 | 目的 |
|--------|---------|
| `npm run build` | 编译 TypeScript 到 `dist/` |
| `npm run typecheck` | 类型检查源代码和测试 |
| `npm run lint` | ESLint |
| `npm test` | Jest 单元测试 |
| `npm run validate` | 类型检查 + 校验 + 测试 + 构建 |
---
## 测试
测试位于 `tests/` 目录下，涵盖配置解析、日志记录、错误实用程序和 Redis 令牌缓存。
```bash
npm test
```
测试使用模拟的 Redis 客户端 - 测试套件不需要运行 Redis 实例。
---
## 项目结构
```
shopify-mcp/
├── docs/
│ └── AUDIT.md # 内部架构审计
├── src/
│ ├── config/ # 环境加载（Zod 验证）
│ ├── lib/ # 认证，日志记录，Redis，工具工厂
│ │ └── redis/ # 连接管理器 + 令牌缓存
│ ├── server/ # 启动，MCP 服务器，关闭
│ ├── tools/ # MCP 工具实现
│ └── index.ts # 入口点
├── tests/ # 单元测试
├── .env.example # 配置模板
├── .github/workflows/ # CI（构建，校验，测试，类型检查）
└── package.json
```
**设计决策：**
- 工具使用 `createTool()` 工厂函数消除重复的 GraphQL 客户端连接。
- 配置集中在 `src/config/env.ts`，使用 Zod 验证。
- OAuth 令牌可选地持久存储在 Redis 中，以便重启时不强制重新认证。
- 日志是结构化的 JSON 输出到 stderr（安全用于 stdio MCP 传输）。
---
## 故障排除
### 认证错误
```
Authentication credentials are required
```
提供 `SHOPIFY_ACCESS_TOKEN` 或 `SHOPIFY_CLIENT_ID` 和 `SHOPIFY_CLIENT_SECRET`。
### 错误的软件包安装
如果您看到引用不同软件包名称的错误，请验证您正在运行 `shopify-mcp`（此软件包），而不是类似名称的替代软件包。
### MCP 连接问题
检查 Claude Desktop MCP 日志：
```bash
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log
```
确保服务器启动时没有错误：
```bash
SHOPIFY_ACCESS_TOKEN=shpat_xxx MYSHOPIFY_DOMAIN=store.myshopify.com npm start
```
### Redis 连接失败
如果 `REDIS_ENABLED=true` 但 Redis 无法访问，服务器将在启动时退出。启动 Redis 或设置 `REDIS_ENABLED=false`。
```bash
docker run -d -p 6379:6379 redis:7-alpine
```
### GraphQL 用户错误
Shopify 在变异响应中返回字段级错误。服务器将这些错误作为 `Failed to <operation>: field: message` 显示。
---
## 贡献
1. 分叉仓库并创建功能分支。
2. 在打开拉取请求之前运行 `npm run validate`。
3. 保持提交聚焦并编写清晰的提交消息。
4. 为新的库或配置行为添加测试。
5. 不要提交机密信息、`.env` 或 `package-lock.json`。
---
## 常见问题
**这是否取代 Shopify Admin UI？**
否。它为 AI 助手提供编程接口，通过 MCP。
**我可以使用静态访问令牌吗？**
是的。设置 `SHOPIFY_ACCESS_TOKEN` 以适用于具有 `shpat_` 令牌的旧自定义应用。
**Redis 是否必需？**
否。Redis 是可选的，仅缓存 OAuth 令牌以进行客户端凭证认证。
**有多少工具可用？**
40 个工具涵盖产品、客户、订单、元字段、库存和商店发现。
**使用哪个 API 版本？**
默认 `2026-01`。使用 `SHOPIFY_API_VERSION` 或 `--apiVersion` 覆盖。
**为什么 stderr 上使用 JSON 日志？**
MCP 使用 stdout 进行协议。日志必须输出到 stderr 以避免破坏传输。
---
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
