Shopify MCP Server Graphql

Shopify MCP服务器

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

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

Shopify核心工具

响应形状（突出显示）

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

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

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

资源

先决条件

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. 重建并重新启动。

故障排除

许可证

麻省理工学院

______________________________________________________________________

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