# Shopify Commerce MCP Server

一个独立的 Shopify Admin GraphQL MCP Server，可供 Codex、DeepSeek Harness 和其他 MCP Client 使用。它提供商品搜索、草稿创建、更新、发布与下架工具，以及本机凭证配置页面。

## 能力

- 安全配置 `shop domain + client ID + client secret`，或已有 Admin API access token
- Client Credentials token 自动交换、内存缓存和到期刷新
- 商品搜索、详情、草稿创建、基础信息更新、状态切换
- Publication（销售渠道）列表、发布与撤下
- 密钥不进入 MCP tool 输出，不写日志；配置文件权限为 `0600`

## 安装与运行

要求 Node.js 20 或更高版本。

```bash
pnpm install
pnpm config
```

打开 `http://127.0.0.1:3210`，填写凭证、保存并测试连接。然后使用 `pnpm start` 启动 stdio MCP Server。

环境变量优先于本机配置文件：`SHOPIFY_SHOP`、`SHOPIFY_CLIENT_ID`、`SHOPIFY_CLIENT_SECRET`、`SHOPIFY_API_VERSION`。也可以使用 `SHOPIFY_ACCESS_TOKEN` 直接提供访问令牌。默认配置文件位于 `~/.config/shopify-commerce-mcp/config.json`；可通过 `SHOPIFY_MCP_CONFIG_PATH` 改写。

## Shopify 设置

在 Shopify Dev Dashboard 中创建 App、选择 API scopes、发布 App Version，并将 App 安装到商店。建议最小权限为 `write_products` 和 `write_publications`。

Client Credentials 只适用于 App 和商店同属一个 Shopify Organization 的服务端集成。对接其他商家的店铺应改用 Shopify OAuth 安装流程；MCP Tools 无需因此改变，只需替换认证层和多租户凭证存储。

## 安全与动作语义

- `shopify_create_product_draft` 永远创建 `DRAFT`，不自动发布。
- `shopify_set_product_status` 将状态切到 `ACTIVE` 后，商品仍不等于已发布。
- `shopify_publish_product` 和 `shopify_unpublish_product` 单独建模，Harness 应在调用前要求人工确认。
- 配置 Web Server 只监听 `127.0.0.1`，不应通过反向代理暴露到公网。

运行 `pnpm test` 可执行不需要真实店铺凭证的自动化测试。

## 在 Codex 中注册

```bash
codex mcp add shopify-commerce -- node /absolute/path/to/src/index.js stdio
```

业务编排、发布确认和批处理规则不放在本仓库中，请搭配独立的 `shopify-product-operator-skill` 使用。