Shopify MCP Proxy & Mock Server (ShopifyMCPMockShop)

Shopify MCP 代理与模拟服务（ShopifyMCPMockShop）

本项目实现了一个模型上下文协议（MCP）服务，作为 Shopify Storefront API 的智能桥接和代理。它独特地支持 mock.shop，无需真实商店凭据即可安全地进行开发和测试。

该服务通过**标准输入/输出（stdio）**进行通信，因此适合与 Claude Desktop 和 Cursor 等客户端进行本地集成。

动机

通用 AI 开发工具和现成的 MCP 服务往往承诺很多，却可能缺乏透明度、安全机制（如显式的 ToolAnnotations）、稳定性或受控开发和测试所需的特定功能，尤其是在针对 Shopify 这类快速演进的 API 时。

本项目源于对可靠的开源 Shopify MCP 服务的需求，它能够：

• 优先考虑安全性： 深度集成 mock.shop，提供关键的沙盒环境，实现无风险开发和准确测试，而不影响线上商店。
• 强调透明度与控制： 让开发者（及其 AI 合作伙伴）确切了解与 Shopify API 的交互方式，包括使用的 API 版本以及操作可能产生的影响（通过 readonly、destructive 等 ToolAnnotations）。
• 满足特定需求： 为 Shopify 开发工作流提供专为其打造的安全执行引擎，弥补纯信息类工具或闭源商业产品留下的空白。

我们的目标是让开发者能够放心地借助 AI 完成 Shopify 相关任务，因为他们使用的是一款具备明确防护措施和清晰操作上下文的工具。

架构

系统概览

ShopifyMCPMockShop 服务采用分层架构，将 MCP 协议处理与 Shopify API 集成清晰分离：

数据流

此时序图展示了典型请求在系统中的流转过程，从用户交互到 API 响应：

工具层级

MCP 服务提供了一套全面的工具，并按 Shopify 资源类型组织：

本地设置与运行

此服务是一个独立的 Node.js 脚本。

1. 克隆代码仓库：

   git clone https://github.com/ramakay/ShopifyMockMCP.git
   cd ShopifyMCPMockShop
   

2. 安装依赖项：

   npm install
   

3. 构建服务：

   npm run build
   

   此命令会将 TypeScript 代码编译为 JavaScript，并输出到 dist 目录（dist/server.js）。

4. 配置环境（可选——用于真实商店）：

   • 如果你希望连接到真实的 Shopify 商店，而不是 mock.shop，请在运行服务前设置以下环境变量（例如，通过 export 设置，或使用客户端加载的 .env 文件）：
     • SHOPIFY_STORE：你的商店域名（例如，your-store.myshopify.com）。用于连接真实商店时必需。
     • SHOPIFY_ACCESS_TOKEN：你的 Storefront API 访问令牌。用于连接真实商店时必需。
     • SHOPIFY_VERSION：可选的特定 Storefront API 版本（例如，2025-04）。默认使用最新稳定版本。
   • 注意： 使用 mock.shop（未设置 SHOPIFY_STORE 时的默认选项）无需任何环境变量。
   • 注意： Admin API 功能目前已禁用，但计划在未来更新中推出。配置变量（USE_ADMIN_API、ADMIN_ACCESS_TOKEN、ADMIN_VERSION）目前尚未使用。

5. 运行： MCP 客户端（如 Claude Desktop 或 Cursor）会根据 stdio 配置自动启动此服务。你无需手动运行 npm run start。请参阅下方的“用法”部分。

在 Cursor 或 Claude Desktop 中使用

将 MCP 客户端（Cursor、Claude Desktop）配置为通过 stdio 启动此服务。在相应的配置文件中添加如下条目：

• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor： ~/.cursor/mcp.json（或类似路径）

{
  "mcpServers": {
    // ... other servers ...
    "shopify-mcp": {
      "command": "node",
      "args": [
        "/full/path/to/ShopifyMCPMockShop/dist/server.js"
      ],
      "env": {
        // Only needed if connecting to a REAL store:
        // "SHOPIFY_STORE": "your-store.myshopify.com",
        // "SHOPIFY_ACCESS_TOKEN": "your-storefront-token",
        // "SHOPIFY_VERSION": "2025-04"
      },
      "disabled": false,
      "alwaysAllow": []
    }
    // ... other servers ...
  }
}

重要提示：

• 将 /full/path/to/ShopifyMCPMockShop 替换为克隆仓库所在位置的绝对路径。
• 仅当连接到真实商店时才添加 env 变量。
• 修改配置后，重启客户端（Cursor/Claude Desktop）。

可用工具

此 MCP 服务目前提供用于与 Shopify Storefront API 交互的工具。

工具名称	说明	API
getShopInfo	获取商店的基本信息（名称、描述、货币）。	Storefront
getProductById	获取指定 ID 的商品。如果 includeImages 为 true，则返回 JSON 详情和第一张图片（75px），格式为 base64 ImageContentBlock。	Storefront
findProducts	搜索／筛选商品，并支持分页／排序。	Storefront
getCollectionById	获取指定 ID 的商品系列，可选择是否包含商品。	Storefront
findCollections	搜索／筛选商品系列，并支持分页／排序。	Storefront
cartCreate	创建新的购物车。	Storefront
cartLinesAdd	向现有购物车添加商品项。	Storefront
cartLinesUpdate	更新现有购物车中的商品项（例如数量）。	Storefront
cartLinesRemove	从现有购物车中移除商品项。	Storefront
getCart	根据 ID 获取现有购物车的详细信息。	Storefront

（注意：getCustomerById 和 createProduct 等 Admin API 工具计划在未来更新中加入，目前已禁用。）

检查服务功能

若要验证服务是否已正确构建，并查看它向 MCP 客户端公布的确切功能，可以使用 package.json 中定义的 inspect 脚本：

# Ensure you have run 'npm install' and 'npm run build' first
# Run this from the project root directory
npm run inspect

此命令会运行编译后的服务（node dist/server.js），并通过标准输入发送标准的 mcp/capabilities 请求。服务会处理该请求，并将其功能（包括可用工具、资源模板和服务信息）作为 JSON 响应打印到标准输出，你可以在终端中查看。此功能有助于调试并确认服务公布的功能。

已知问题

• 行内图片渲染： Claude Desktop 和 Cursor 等客户端目前会将 ImageContentBlock（当 includeImages 为 true 时由 getProductById 使用）渲染在主文本响应下方的独立 UI 区块中，而不是行内显示。尝试在文本区块中使用 Markdown 或 HTML 图片标签也无法在这些客户端中实现行内渲染。

未来计划

• 重新集成并测试 Admin API 工具（getCustomerById、createProduct 等）。
• 添加 Admin API 凭据的配置选项（USE_ADMIN_API、ADMIN_ACCESS_TOKEN、ADMIN_VERSION）。
• 实现测试框架。
• 如果客户端支持有所改善，探索资源处理方式。

许可证

MIT 许可证