mcpField
P
pp-shopify

pp-shopify

github.com/mvanhorn其他2.1k233 次安装今天更新
代码仓库

关于 pp-shopify

pp-shopify 是驱动 shopify-pp-cli 的技能，为需要以只读方式检查、导出和分析 Shopify 商店数据的团队与 Agent 提供命令行入口。它涵盖订单、客户、产品、库存和履约，并提供本地数据分析及面向 Agent 的结构化输出。

主要功能

  1. 01查询订单、客户、产品与库存
  2. 02检查弃购和履约订单
  3. 03本地同步数据与来源标记
  4. 04自然语言查询匹配命令
  5. 05JSON 输出、字段筛选与交付

适用场景

  1. 01分析弃购以规划挽回活动
  2. 02检查库存数量和商品目录
  3. 03发现延迟履约与运输异常
  4. 04生成每日经营简报和客户分群

MCP 相关

README 提供 shopify-pp-mcp 的安装与 Claude Code 注册步骤。MCP 客户端可通过该服务器使用 Shopify CLI 功能。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mvanhorn/printing-press-library --skill pp-shopify

安装后在 Claude Code 中输入/pp-shopify确认已加载。

详细介绍

Shopify — Printing Press CLI

前提条件：安装 CLI

此技能由 shopify-pp-cli 二进制文件驱动。**调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

  1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin： 
    npx -y @mvanhorn/printing-press-library install shopify --cli-only
  2. 验证：shopify-pp-cli --version
  3. 确保所报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/commerce/shopify/cmd/shopify-pp-cli@latest

如果安装后 --version 报告“command not found”，则运行时无法在 $PATH 中找到二进制文件目录。验证成功之前，请勿执行技能命令。

何时不使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求，请勿启用此 CLI。此 CLI 仅提供用于检查、导出、同步和分析的只读命令。

命令参考

abandoned-checkouts — Shopify 弃购结账数据，可用于恢复营销活动和流失购物车分析。

  • shopify-pp-cli abandoned-checkouts get — 根据 GraphQL ID 获取一条 Shopify 弃购结账记录。
  • shopify-pp-cli abandoned-checkouts list — 从 Shopify Admin GraphQL API 列出弃购结账记录。

customers — Shopify 客户数据，包含终身订单数、终身消费金额和联系信息字段。

  • shopify-pp-cli customers get — 根据 GraphQL ID 获取一位 Shopify 客户。
  • shopify-pp-cli customers list — 从 Shopify Admin GraphQL API 列出客户。

fulfillment-orders — Shopify 履行订单，可用于分析延迟、路由和履行状态。

  • shopify-pp-cli fulfillment-orders get — 根据 GraphQL ID 获取一条 Shopify 履行订单。
  • shopify-pp-cli fulfillment-orders list — 从 Shopify Admin GraphQL API 列出履行订单。

inventory-items — Shopify 库存项目，包含跟踪状态以及各地点的可用数量。

  • shopify-pp-cli inventory-items get — 根据 GraphQL ID 获取一项 Shopify 库存项目。
  • shopify-pp-cli inventory-items list — 从 Shopify Admin GraphQL API 列出库存项目。

orders — Shopify 订单，包含金额总计、财务状态和履行状态。

  • shopify-pp-cli orders get — 根据 GraphQL ID 获取一笔 Shopify 订单。
  • shopify-pp-cli orders list — 从 Shopify Admin GraphQL API 列出订单。

products — Shopify 商品，包含商品状态、目录元数据和精简的变体库存概览。

  • shopify-pp-cli products get — 根据 GraphQL ID 获取一件 Shopify 商品。
  • shopify-pp-cli products list — 从 Shopify Admin GraphQL API 列出商品。

新鲜度约定

此打印版 CLI 仅为已注册的、由存储支持的读取命令路径提供有界新鲜度。在 --data-source auto 模式下，这些路径会检查 sync_state，并可能在读取本地数据前执行有界刷新。--data-source local 永不刷新。--data-source live 从 API 读取，且不会修改本地存储。设置 SHOPIFY_NO_AUTO_REFRESH=1 可跳过新鲜度钩子，而不更改数据源选择。

覆盖的路径：

  • shopify-pp-cli abandoned-checkouts
  • shopify-pp-cli abandoned-checkouts get
  • shopify-pp-cli abandoned-checkouts list
  • shopify-pp-cli abandoned-checkouts search
  • shopify-pp-cli customers
  • shopify-pp-cli customers get
  • shopify-pp-cli customers list
  • shopify-pp-cli customers search
  • shopify-pp-cli fulfillment-orders
  • shopify-pp-cli fulfillment-orders get
  • shopify-pp-cli fulfillment-orders list
  • shopify-pp-cli fulfillment-orders search
  • shopify-pp-cli inventory-items
  • shopify-pp-cli inventory-items get
  • shopify-pp-cli inventory-items list
  • shopify-pp-cli inventory-items search
  • shopify-pp-cli orders
  • shopify-pp-cli orders get
  • shopify-pp-cli orders list
  • shopify-pp-cli orders search
  • shopify-pp-cli products
  • shopify-pp-cli products get
  • shopify-pp-cli products list
  • shopify-pp-cli products search

当 JSON 输出使用生成的来源信息信封时，新鲜度元数据位于 meta.freshness。请将其视为此覆盖命令路径的当前缓存新鲜度，而不是完整历史回填或特定于 API 的数据增强保证。

查找合适的命令

当你知道想做什么，但不知道该用哪个命令时，可以直接询问 CLI：

shopify-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中解析出最匹配的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help，或缩小查询范围。

手写扩展

这些命令由规范作者声明，需要单独手写接线；生成器不会为它们生成 Cobra 注册代码。此处列出这些命令以便查找，并刻意将它们放在 ## Command Reference 之外，这样 verify-skill 的未知命令检查就不会将其视为生成器负责的路径。

  • shopify-pp-cli bulk-operations — 执行、轮询并检查 Shopify Admin GraphQL 批量操作。
  • shopify-pp-cli store daily-brief — 基于本地存储中的营收、热门产品、风险检查和建议操作生成每日高管简报。
  • shopify-pp-cli store audit — 根据退款、履约风险、配送异常和滞销库存计算健康评分。
  • shopify-pp-cli growth campaign-brief — 根据热门产品、VIP 和召回机会生成数据支持的营销活动简报。
  • shopify-pp-cli growth winback-candidates — 按客户终身价值及建议的召回方式，对沉寂客户进行排序。
  • shopify-pp-cli growth vip-segments — 根据消费额、频率和最近消费时间对高价值客户分群。
  • shopify-pp-cli ops fulfillment-risk — 查找超过指定时限的未完成履约订单。
  • shopify-pp-cli ops shipping-anomalies — 根据已同步的配送明细，查找免费、缺失或费用过高的配送费。
  • shopify-pp-cli merchandising bundle-opportunities — 根据共同购买提升幅度和置信度推荐捆绑销售组合。
  • shopify-pp-cli merchandising dead-stock-actions — 将近期无销售的库存转化为降价或捆绑销售操作。
  • shopify-pp-cli merchandising launch-brief — 根据本地证据为产品制定上市或重新上市简报。

身份验证设置

运行 shopify-pp-cli auth setup，打印获取密钥的 URL 和步骤（添加 --launch 可打开该 URL）。然后设置：

export SHOPIFY_ACCESS_TOKEN="<your-key>"

或者将其持久化到 ~/.config/shopify-pp-cli/config.toml。

运行 shopify-pp-cli doctor 验证设置。

Agent 模式

在任何命令后添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

  • 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

  • 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐项遍历。对于冗长 API，这对控制上下文大小至关重要：

    shopify-pp-cli abandoned-checkouts list --agent --select id,name,status

  • 可预览 — --dry-run 显示请求，但不会发送

  • 适合离线使用 — 在本地 SQLite 存储可用时，同步／搜索命令可以使用它

  • 非交互式 — 绝不提示输入，所有输入都通过标志提供

  • 只读 — 请勿使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会更改数据的请求

响应封装

从本地存储或 API 读取数据的命令会将输出封装在来源信息中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时 API 还是本地存储。只有当 stdout 是终端，且未设置任何机器可读格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将易读的 N results (live) 摘要输出到 stderr。管道／Agent 消费者和显式指定格式的运行会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有任何不妥之处时，请记录下来：

shopify-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
shopify-pp-cli feedback --stdin < notes.txt
shopify-pp-cli feedback list --json --limit 10

条目会保存在本地 ~/.local/share/shopify-pp-cli/feedback.jsonl。除非设置了 SHOPIFY_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 SHOPIFY_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认仅保存在本地。

记录让你感到意外的事，而不是提交错误报告。简短、具体，用一行写清楚：这才是能不断累积价值的部分。

输出传递

每个命令都接受 --deliver <sink>。除了输出到 stdout（或替代 stdout），命令还会将结果发送到指定的接收端，让 Agent 无需手动通过管道即可路由命令结果。支持三种接收端：

接收端效果
stdout默认；仅写入 stdout
file:<path>以原子方式将输出写入 <path>（临时文件 + 重命名）
webhook:<url>将输出正文 POST 到该 URL（使用 application/json；传入 --compact 时使用 application/x-ndjson）

遇到未知方案时会拒绝请求，并返回列出受支持方案的结构化错误。Webhook 失败时会返回非零退出码，并在 stderr 记录 URL 和 HTTP 状态码。

命名配置

配置是已保存的一组标志值，可在多次调用中重复使用。如果计划任务中的 Agent 每次运行都以相同配置调用同一命令，可使用配置——这就是 HeyGen 的“Beacon”模式。

shopify-pp-cli profile save briefing --json
shopify-pp-cli --profile briefing abandoned-checkouts list
shopify-pp-cli profile list --json
shopify-pp-cli profile show briefing
shopify-pp-cli profile delete briefing --yes

显式标志的优先级始终高于配置值；配置值优先级高于默认值。agent-context 会在 available_profiles 下列出所有可用配置，方便 Agent 在运行时发现它们。

退出代码

代码含义
0成功
2用法错误（参数错误）
3未找到资源
4需要身份验证
5API 错误（上游问题）
7触发速率限制（等待后重试）
10配置错误

参数解析

解析 $ARGUMENTS：

  1. 为空、help 或 --help → 显示 shopify-pp-cli --help 的输出
  2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上方的先决条件
  3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并添加 --agent）

安装 MCP 服务

  1. 安装 MCP 服务： 
    go install github.com/mvanhorn/printing-press-library/library/commerce/shopify/cmd/shopify-pp-mcp@latest
  2. 在 Claude Code 中注册： 
    claude mcp add shopify-pp-mcp -- shopify-pp-mcp
  3. 验证：claude mcp list

直接使用

  1. 检查是否已安装：which shopify-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的先决条件）。
  2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
  3. 使用 --agent 标志执行： 
    shopify-pp-cli <command> [subcommand] [args] --agent
  4. 如果有歧义，请查看子命令帮助：shopify-pp-cli <command> --help。

评论

支持 Markdown