# shoplazza-mcp

把 [Shoplazza OpenAPI（REST）](https://www.shoplazza.dev/zh-CN/api/openapi) 封装成
[MCP (Model Context Protocol)](https://modelcontextprotocol.io) 服务的 Python 实现，
让 Claude、Cursor、DSH 等支持 MCP 的客户端可以直接读写 Shoplazza 店铺数据
（商品、订单、客户、库存、折扣、订阅 webhook 等）。

> 端点目录（`data/endpoints.json`）由 `tools/scrape_endpoints.py` 从官方文档自动抓取，
> 覆盖 **2026-01 版本共 311 个真实端点、46 个资源组**。

---

## 功能特性

| 能力 | 说明 |
| --- | --- |
| 61 个常用端点工具 | 商品 / 变体 / 订单 / 发货 / 客户 / 地址 / 收藏集 / 折扣 / 优惠券 / 库存 / 门店 / 页面 / 博客 / 文章 / metafield / webhook / 礼品卡 / 供应商 / 数据报表 / 授权 scope 等，输入参数由官方文档自动生成，**每个工具描述里标注所需 scope** |
| **多店铺支持** | 一个服务实例可配置多个店铺（`SHOPLAZZA_STORES`），每个 API 工具带可选 `shop_domain` 参数按店铺路由；`shoplazza_list_shops` 查看已配置店铺 |
| **官方 CLI 对齐** | 兼容 CLI 环境变量 `SHOPLAZZA_STORE` / `SHOPLAZZA_UAT`；每个 API 工具带 `dry_run` 参数（CLI `--dry-run` 同款，只预览请求不发）；`call_shoplazza_api` 等价 CLI 的 `api rest` 逃生舱；`shoplazza_search_endpoints` 等价 `schema` 自省 |
| 311 个端点全覆盖 | 开启 `SHOPLAZZA_REGISTER_ALL_ENDPOINTS=1` 后，目录中的每个端点都注册为独立工具 |
| 通用透传工具 | `call_shoplazza_api(method, path, path_params, query, body, dry_run)` 可调用任意端点 |
| 端点目录工具 | `shoplazza_search_endpoints` / `shoplazza_get_endpoint` 让模型随时发现正确的端点、参数与所需 scope |
| 双传输方式 | stdio（本地客户端默认） / Streamable HTTP（远程服务，`--transport http`） |
| 稳健性 | 自动处理「请求头鉴权、统一响应包 `{code,message,data}`、cursor 分页、429 限流重试（Retry-After，按店铺独立限速）、路径占位符校验、业务错误透出」 |

---

## 安装

要求：Python ≥ 3.10，[uv](https://docs.astral.sh/uv/)（推荐）或 pip。

```bash
cd shoplazza-mcp
uv sync          # 创建 .venv 并安装依赖（mcp、httpx）
```

不用 uv 时：

```bash
python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -e .
```

## 配置

通过环境变量提供凭证（**不要把密钥写进代码或提交到仓库**）：

```bash
# PowerShell / cmd
set SHOPLAZZA_SHOP_DOMAIN=your-store.myshoplazza.com
set SHOPLAZZA_ACCESS_TOKEN=your-access-token
```

| 变量 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- |
| `SHOPLAZZA_SHOP_DOMAIN` | ✅* | — | 默认/单店铺域名，如 `your-store.myshoplazza.com`（不带协议） |
| `SHOPLAZZA_ACCESS_TOKEN` | ✅* | — | 默认/单店铺访问令牌，对应 `Access-Token` 请求头 |
| `SHOPLAZZA_STORES` | 可选 | — | 多店铺 JSON：`{"a.myshoplazza.com":"token-a","b.myshoplazza.com":"token-b"}` |
| `SHOPLAZZA_API_VERSION` | | `2026-01` | API 版本，如 `2025-06`、`2022-01` |
| `SHOPLAZZA_REGISTER_ALL_ENDPOINTS` | | `0` | `1` 时注册全部 311 个端点工具 |
| `SHOPLAZZA_MAX_RPS` | | `2.0` | 客户端每秒最大请求数（漏桶，按店铺独立） |
| `SHOPLAZZA_MAX_RETRY_WAIT` | | `10.0` | 429 时最多等待秒数 |
| `SHOPLAZZA_REQUEST_TIMEOUT` | | `60.0` | 单请求超时（秒） |
| `SHOPLAZZA_DATA_DIR` | | 包内 `data/` | 自定义端点目录位置 |

\* 单店铺配置 `SHOPLAZZA_SHOP_DOMAIN` + `SHOPLAZZA_ACCESS_TOKEN` 与多店铺配置 `SHOPLAZZA_STORES` 二选一即可；
两者都设置时，`SHOPLAZZA_SHOP_DOMAIN` 为默认店铺。

**兼容官方 CLI 的环境变量名**（与上表等价，任一即可）：

```bash
export SHOPLAZZA_STORE=your-store.myshoplazza.com   # 等价 SHOPLAZZA_SHOP_DOMAIN
export SHOPLAZZA_UAT=your-access-token              # 等价 SHOPLAZZA_ACCESS_TOKEN
```

也就是说，你在官方 CLI 里用的 `SHOPLAZZA_STORE` / `SHOPLAZZA_UAT` 可以直接照搬给本服务，
token 同一套。

完整示例见 [.env.example](.env.example)。

### 多店铺用法

配置多个店铺后，服务里的每个 API 工具都会多出一个可选参数 `shop_domain`：

```bash
export SHOPLAZZA_STORES='{"us.myshoplazza.com":"token-us","de.myshoplazza.com":"token-de"}'
```

- 不带 `shop_domain` → 走默认店铺（`SHOPLAZZA_SHOP_DOMAIN`，或 STORES 的第一项）
- 带 `shop_domain` → 走指定店铺（未知店铺会报错并列出已配置店铺）
- `shoplazza_list_shops` → 查看服务已配置的所有店铺与默认店铺
- 每个店铺有独立的 Access-Token 与独立限速桶（符合官方按店铺限流的规则），
  多店铺之间互不阻塞

对话示例：

> “查一下 US 店铺今天的订单量，再看下 DE 店铺销量 top5 的商品”
> → 模型会分别以 `shop_domain=us.myshoplazza.com` 和 `shop_domain=de.myshoplazza.com`
> 调用 `shoplazza_orders` / `shoplazza_products`

Claude Desktop 配置示例（多店铺）：

```json
{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_STORES": "{\"us.myshoplazza.com\":\"token-us\",\"de.myshoplazza.com\":\"token-de\"}"
      }
    }
  }
}
```

### 需要的 API 权限（scope）

在[合作伙伴中心](https://partner.shoplazza.com)创建/安装应用、或给店铺授权时，
按"最小权限原则"只申请你要用到的 scope。查询数据给 `read_*`，需要修改才加同名 `write_*`：

| 你要访问的数据 | 申请 scope |
| --- | --- |
| 店铺信息 | `read_shop` |
| 商品 / 变体 / 库存 | `read_product` |
| 分类 / 收藏 | `read_collection` |
| 订单 / 支付信息 | `read_order` |
| 退款 / 售后 | `read_order`（含售后记录）+ `read_data` |
| 客户 | `read_customer` |
| 折扣码 / 优惠券 / 价格规则 | `read_price_rules` |
| 礼品卡 | `read_gift_cards` |
| 页面 / 博客 / 文章 / 重定向 | `read_shop_navigation` |
| 评论 | `read_comments` |
| webhook 管理 | 需 `write_*` 对应资源 scope（如 `write_product` / `write_order`） |
| Shoplazza Pay 资金数据 | `read_finance` |
| 数据分析报表 | `read_data` |

只读运营场景推荐组合：`read_shop, read_product, read_order, read_customer, read_price_rules, read_gift_cards, read_shop_navigation, read_data`。
授权后可调用 `shoplazza_oauth_access_scopes` 工具核对本次安装实际被授予的 scope。
官方完整映射见 [访问权限范围](https://www.shoplazza.dev/zh-CN/docs/app/building-blocks/authentication/access-scopes)。
每个工具的说明里都会标注该端点需要的 scope（如 `Required scope: read_order.`），403 报错时可以对着排查。

### 与官方 CLI 的对应关系

官方 [Shoplazza CLI](https://www.shoplazza.dev/zh-CN/docs/app/developer-tools/shoplazza-cli/) 的功能在本服务中都有对应：

| 官方 CLI | 本 MCP | 说明 |
| --- | --- | --- |
| `shoplazza products list --params '{"..."}'` | `shoplazza_products` 等 API 工具 | 同一套端点，输入参数按官方文档自动生成 |
| `shoplazza api rest GET /openapi/...` | `call_shoplazza_api` | 逃生舱，可调任意端点 |
| `--dry-run` | 每个工具可选 `dry_run=true` | 只预览请求（method/url/query/body/headers，token 打码），不发请求 |
| `--format json` / `--jq` | 默认返回 JSON 完整响应 | 结果就是结构化 JSON，可直接消费 |
| `shoplazza schema products.list` | `shoplazza_get_endpoint` / `shoplazza_search_endpoints` | 端点、参数、scope 自省 |
| `SHOPLAZZA_STORE` / `SHOPLAZZA_UAT` | 同名环境变量直接兼容 | CLI 的 token 体系与本服务同一套 |
| `auth login --scope ...` | `shoplazza_oauth_access_scopes` | 授权后核对实际 scope |
| `auth store use`（切换活跃店铺） | `shop_domain` 参数 | 本服务按调用路由店铺，无需切换全局状态 |

### 如何获取 Access Token

- **公开应用**：走 [OAuth 2.0 Authorization Code 流程](https://www.shoplazza.dev/zh-CN/docs/app/building-blocks/authentication/oauth-flow)，
  用 `code` 换取 `access_token`（有效期 1 年，可用 `refresh_token` 刷新）。
- **私有 / 内部集成**：在 Shoplazza 后台为应用与店铺生成对应的访问令牌。

## 运行

### stdio（本地 MCP 客户端，默认）

```bash
uv run shoplazza-mcp
```

### HTTP（远程服务）

```bash
uv run shoplazza-mcp --transport http --host 0.0.0.0 --port 8765
```

端点路径默认 `/mcp`，可用 `--http-path` 修改。

## 接入 MCP 客户端

**Claude Desktop**（`claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "shoplazza": {
      "command": "uv",
      "args": ["run", "--directory", "D:/projects/DSH-projects/shoplazza-mcp", "shoplazza-mcp"],
      "env": {
        "SHOPLAZZA_SHOP_DOMAIN": "your-store.myshoplazza.com",
        "SHOPLAZZA_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}
```

**Cursor**：在设置 → MCP 中添加服务器，配置见 [examples/mcp-cursor.json](examples/mcp-cursor.json)。

**远程 HTTP**（任何客户端）：把 `url` 指向 `http://host:8765/mcp`。

也可以直接运行（debug 查看工具列表与 JSON-RPC 交互）：

```bash
uv run mcp dev shoplazza-mcp
```

## 使用示例（Claude / Cursor 等对话）

- “列出店里最新 10 个订单”
- “查一下商品 `abcd-1234` 的库存”
- “把订单 `order-xxx` 取消，原因写 `customer requested`”
- “新建一个满 100 减 20 的折扣”
- “有什么 API 可以做退款？搜索一下端点” → 模型会调用 `shoplazza_search_endpoints("refund")` 后自动调用对应端点。

所有响应都返回 API 原始包：`{code, message, data, api_call_limit}`；
列表类响应在 `data` 中带 `cursor` / `pre_cursor`，配合 `page_size` / `per_page` 参数翻页。

## 开发与维护

- `tools/scrape_endpoints.py`：从 [官方端点文档页](https://www.shoplazza.dev/api/) 抓取并生成 `data/endpoints.json`
  （含每个端点的 method / path / 参数 / 请求体字段 / 响应结构）。
- 曲线维护：新增或移除「常用工具」只需修改 `shoplazza_mcp/tools.py` 里的 `CURATED_SLUGS` 清单。
- `scripts/smoke_test.py`：离线冒烟测试（stdio）；`scripts/http_smoke_test.py`：HTTP 冒烟测试。

## 安全说明

- Access Token 请只通过环境变量 / 客户端配置注入，不要写入代码仓库。
- 服务只走 HTTPS（官方要求所有端点仅 HTTPS 访问）。
- 作为 HTTP 服务暴露到外网时，请置于可信内网或自行加鉴权（如网关、防火墙）。

## License

MIT