shopify-storefront-mcp-server

🚀 Shopify店铺指南

本指南详细介绍了如何借助MCP（多渠道平台）服务器与Shopify店铺进行交互。涵盖功能概述、设置说明、环境变量配置、Storefront API令牌生成步骤、使用示例、客户资源管理以及数据隐私与存储策略等内容，助您高效管理Shopify店铺。

✨ 主要特性

• 商品信息查询：可获取所有产品及其详细信息。
• 购物车管理：支持添加、修改和删除购物车中的商品。
• 订单操作：能创建新订单或查看现有订单的状态。
• 库存同步：确保本地库存与Shopify店铺的库存保持一致。
• 价格规则应用：可应用促销活动和定价策略。

📦 安装指南

安装依赖项

使用以下命令安装所需包：

npm install shopify-api

配置环境变量

编辑.env文件，添加如下配置：

SHOPIFY_STORE_NAME=your-store.myshopify.com
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret

初始化数据库

运行以下命令创建本地数据库表：

npx knex migrate:latest

💻 使用示例

基础用法

查询商品信息

使用以下GraphQL查询获取所有产品：

query {
  products(first: 10) {
    edges {
      node {
        id
        title
        description
        price
      }
    }
  }
}

创建购物车

调用以下REST API创建新购物车：

POST /api/2025-04/graphql.json
{
  "query": "mutation createCart($lines: [CartLineInput!]!) {
    cartCreate(input: { lines: $lines }) {
      cart {
        id
        checkoutUrl
      }
      userErrors {
        field
        message
      }
    }
  }",
  "variables": {
    "lines": [
      {
        "merchandiseId": "gid://shopify/ProductVariant/12345678901234",
        "quantity": 1
      }
    ]
  }
}

高级用法

应用优惠券

使用以下突变应用指定的优惠券：

mutation applyCoupon($cartId: ID!, $couponCode: String!) {
  cartUpdate(id: $cartId, updates: { couponCode: $couponCode }) {
    cart {
      id
      totalAmount
    }
    userErrors {
      field
      message
    }
  }
}

📚 详细文档

客户资源管理

数据结构

客户数据存储在db/customers.json文件中，包含以下字段：

• id: 唯一标识符
• firstName: 名字
• lastName: 姓氏
• email: 邮箱地址
• address: 收货地址

数据操作

添加新客户

const newCustomer = {
  id: generateUUID(),
  firstName: "John",
  lastName: "Doe",
  email: "john.doe@example.com",
  address: "123 Main St, City"
};
db.customers.push(newCustomer);

更新现有客户

const customer = db.customers.find(c => c.id === customerId);
if (customer) {
  customer.firstName = "Jane";
  customer.lastName = "Smith";
}

数据隐私与存储

文件管理

• 数据文件：db/customers.json
• 示例文件：db/customers.json.example提供了一个模板，包含虚构的客户数据。

安全措施

1. 禁止将敏感文件如.env和db/customers.json提交到版本控制系统。
2. 使用加密技术保护客户的个人信息。
3. 定期备份数据库以防止数据丢失。

故障排除

问题：无法连接到Shopify店铺

解决方案：

1. 检查网络连接是否正常。
2. 确保API密钥和秘钥正确无误。
3. 查看Shopify的开发者文档以获取更多帮助。

问题：购物车创建失败

解决方案：

1. 验证传递的参数是否符合要求。
2. 确认商品是否存在且库存充足。
3. 检查日志文件以获取详细错误信息。

总结

本指南提供了与Shopify店铺交互的基本方法，涵盖了从数据查询到客户管理的各个方面。通过遵循这些步骤和最佳实践，您可以有效地集成和管理您的 Shopify 店铺。