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有效负载示例 |
先决条件
- Node.js>=18
- 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）。
- 避免暴露访问令牌——将其存储在环境变量中，而不是提交的文件中。
延伸
添加新工具：
- 在中添加架构
ListToolsRequestSchema处理程序数组。 - 添加a
case分支在CallToolRequestSchema开关。 - 返回打印精美的JSON(
JSON.stringify(data, null, 2)). - 重建并重新启动。
故障排除
| 症状 | 检查 |
|---|---|
| 缺少数据/400个错误 | 验证访问令牌上所需的作用域 |
| “缺少Shopify配置” | 确保在同一shell会话中导出两个env变量 |
| 未找到模糊标题 | 相似度\<0.5；尝试使用id或句柄 |
| 空搜索结果 | 调整查询语法；类别筛选器添加 (product_type:... OR tag:...) |
许可证
麻省理工学院
______________________________________________________________________
对于发布到npm：请确保将此文件重命名为 README.md，添加适当的 repository 字段，包括 files 白名单（例如。 ["build","README.md","LICENSE"]).