MCP 服务器

Shopify MCP Proxy & Mock Server (ShopifyMCPMockShop)

一个用于与 Mock.shop 交互的 Shopify MCP 服务器

ramakay

开发者工具

访问服务器

README

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 版本以及操作的潜在影响（通过 ToolAnnotations，如 readonly、destructive 等）。
解决特定需求： 通过提供专为 Shopify 开发工作流程量身定制的安全执行引擎，填补了纯信息工具或闭源商业产品留下的空白。

目标是使开发人员能够自信地利用 AI 辅助进行 Shopify 任务，因为他们知道自己拥有一个构建了有意防护措施和清晰操作上下文的工具。

设置 & 本地运行

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

克隆存储库：

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

安装依赖项：
```
npm install
```
构建服务器：
```
npm run build
```
这会将 TypeScript 代码编译为 dist 目录中的 JavaScript (dist/server.js)。
配置环境（可选 - 适用于真实商店）：
- 如果要连接到真实的 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）目前未使用。
运行： 该服务器旨在由 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": {
    // ... 其他服务器 ...
    "shopify-mcp": {
      "command": "node",
      "args": [
        "/full/path/to/ShopifyMCPMockShop/dist/server.js"
      ],
      "env": {
        // 仅在连接到真实商店时需要：
        // "SHOPIFY_STORE": "your-store.myshopify.com",
        // "SHOPIFY_ACCESS_TOKEN": "your-storefront-token",
        // "SHOPIFY_VERSION": "2025-04"
      },
      "disabled": false,
      "alwaysAllow": []
    }
    // ... 其他服务器 ...
  }
}

重要提示：

将 /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

(注意：计划在未来的更新中添加 Admin API 工具，如 getCustomerById 和 createProduct，目前已禁用。)

检查服务器功能

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

# 确保您已首先运行 'npm install' 和 'npm run build'
# 从项目根目录运行此命令
npm run inspect

此命令执行已编译的服务器 (node dist/server.js) 并通过其标准输入发送标准的 mcp/capabilities 请求。服务器处理此请求并将其功能（包括可用工具、资源模板和服务器信息）作为 JSON 响应打印到其标准输出，您将在终端中看到该响应。这对于调试和确认服务器宣传的功能非常有用。

已知问题

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