AI导哈

Shopify产品查询服务

一个专注于Shopify产品查询和订单状态检索的模型上下文协议（MCP）服务器，提供从AI助手调用的结构化工具。

  • by bhavik-dreamz
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 bhavik-dreamz/shopify-mcp-server-graphql

使用说明

Shopify MCP服务器

一个专注于Shopify产品查找和订单状态检索的固执己见的模型上下文协议（MCP）服务器。它公开了结构化的MCP工具，您可以从AI助手（Cursor、VS Code MCP扩展等）调用这些工具来搜索产品、获取完整的产品详细信息、检查订单状态、推荐、库存、退货等。

文件名注释：将其重命名为 README.md 在发布到npm之前，它会被自动拾取。

Shopify核心工具

工具 目的 关键输入
shopify_search_products 轻量级产品搜索+摘要 query （字符串），可选 category, limit
shopify_get_product_detail 按id/句柄/确切标题列出的完整产品详细信息（带模糊回退） 以下之一： id, handle, title
shopify_get_order_status 订单履行+商品+地址汇总 orderNumber 和 email
shopify_get_recommendations 模拟人工智能推荐（替换为真实逻辑） userId，可选 category, recentPurchases, limit
shopify_update_preferences 存储（模拟）用户偏好blob userId, preferences
shopify_check_inventory 变量库存快照 productIds （数字id数组）
shopify_process_return 模拟返回启动 orderId, items, reason, returnType

响应形状（突出显示）

shopify_search_products 返回简化的产品对象数组（id、标题、描述、价格、库存、变体、图像）。

shopify_get_product_detail 返回标准化的富产品对象：变体、图像、集合、元字段、库存总计、SEO等。当通过近似标题找到时，会附加模糊相似性评分。

shopify_get_order_status 返回：orderNumber、状态、orderDate、估计交货时间（简单+5天计算）、当前位置（导出）、项目[]、总计、送货和账单地址。

资源

URI 描述
test://info 服务器基本信息文本
test://sample-data JSON有效负载示例

先决条件

  1. Node.js>=18
  2. Shopify商店+私人应用程序/自定义应用程序访问令牌，具有相关范围（read_products、read_orders等）

环境变量

在运行之前设置这些（shell示例）：

export SHOPIFY_SHOP_DOMAIN="your-shop.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="shpat_***"
# Optional (defaults shown):
export SHOPIFY_API_VERSION="2024-01"

安装和构建

npm install
npm run build

运行（Shopify服务器入口点）

编译后，运行：

node build/shopify-mcp.js

或者在中添加脚本 package.json （推荐）：

"scripts": {
  "start:shopify": "node build/shopify-mcp.js"
}

编辑器集成示例

光标(~/.cursor/config.json)

{
  "mcp": {"servers": {"shopify": {"command": "node","args": ["/ABS/PATH/TO/build/shopify-mcp.js"],"env": {"SHOPIFY_SHOP_DOMAIN": "your-shop.myshopify.com","SHOPIFY_ACCESS_TOKEN": "shpat_***"}}}}
}

VS代码（settings.json）

{
  "mcp.servers": {
    "shopify": {
      "command": "node",
      "args": ["/ABS/PATH/TO/build/shopify-mcp.js"],
      "env": {
        "SHOPIFY_SHOP_DOMAIN": "your-shop.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_***"
      }
    }
  }
}

用法示例（自然语言提示）

询问您启用了MCP的AI：

  • “在Shopify上搜索150美元以下的跑鞋”（电话 shopify_search_products)
  • “获取产品手柄'ultra-boots-23'的完整详细信息”（电话 shopify_get_product_detail)
  • “12345订单的状态如何john@example.com（电话 shopify_get_order_status)
  • “为用户U123推荐4款与最近购买的耳机类似的产品”（电话 shopify_get_recommendations)

典型工具论证形式

// Product search
{ "query": "wireless headphones", "category": "Audio", "limit": 5 }

// Product detail by id
{ "id": "gid://shopify/Product/1234567890" }

// Product detail by handle
{ "handle": "wireless-headphones-pro" }

// Product detail by title (fuzzy fallback)
{ "title": "Wireless Headphones Pro" }

// Order status
{ "orderNumber": "#12345", "email": "buyer@example.com" }

// Inventory check
{ "productIds": [1234567890, 2345678901] }

开发工作流程

使用观察模式进行快速迭代：

npm run watch

在第二个终端中，每次成功编译后重新运行构建的文件。

错误处理

服务器使用以下命令抛出结构化MCP错误 McpError （例如InvalidParams、InvalidRequest）。工具故障以JSON块的形式返回： { "success": false, "error": "message" }.

模糊产品名称匹配

如果 title 查找失败，更广泛的搜索使用Levenshtein距离计算相似性得分；低于0.5相似性阈值的产品被拒绝，以避免不正确的匹配。

安全说明

  • 只有GraphQL和REST调用您的Shopify商店（除了其他演示服务器中的独立算法外，没有eval）。
  • 避免暴露访问令牌——将其存储在环境变量中，而不是提交的文件中。

延伸

添加新工具：

  1. 在中添加架构 ListToolsRequestSchema 处理程序数组。
  2. 添加a case 分支在 CallToolRequestSchema 开关。
  3. 返回打印精美的JSON(JSON.stringify(data, null, 2)).
  4. 重建并重新启动。

故障排除

症状 检查
缺少数据/400个错误 验证访问令牌上所需的作用域
“缺少Shopify配置” 确保在同一shell会话中导出两个env变量
未找到模糊标题 相似度<0.5；尝试使用id或句柄
空搜索结果 调整查询语法；类别筛选器添加 (product_type:... OR tag:...)

许可证

麻省理工学院

对于发布到npm：请确保将此文件重命名为 README.md，添加适当的 repository 字段，包括 files 白名单（例如。 ["build","README.md","LICENSE"]).

相关 MCP