shopify-theme-inspector

Shopify Theme Inspector MCP

询问 AI 助手 Shopify 主题为什么运行缓慢，即可获得一份报告，指出值得修复的 Liquid 文件及代码行。

Shopify Theme Inspector MCP 将 Shopify 的服务端 Liquid 分析器连接到 Codex、Claude Desktop、Cursor、Windsurf 和 VS Code 等 AI 工具。它会测量线上店面性能，找出开销高的模板和重复工作，对比不同页面，并将火焰图数据转化为易读的建议。

运行报告不需要编程知识。 如果你的 AI 应用支持 MCP，设置过程基本只需复制、粘贴、登录，然后提问。

说明

这是一个非官方的社区项目，与 Shopify 无关，也不受 Shopify 支持。

Shopify 商店所有者？从这里开始

这个工具旨在帮助解答一个实际问题：

我的 Shopify 主题中，哪些部分在向顾客发送页面之前增加了 Shopify 的工作量？

你可以用日常语言提出这个问题。AI 助手会运行技术检查、读取 Shopify 的性能分析数据，并解释发现的问题，无需你理解火焰图。

例如，报告可以指出：

• 首页的某个分区执行了大量服务端工作。
• 相同的产品、菜单、价格或图片代码被渲染了很多次。
• 第三方应用区块频繁出现在性能分析中最慢的部分。
• 某个系列或产品模板比不太重要的代码更值得优先处理。
• 最近的主题更改改善、降低了 Liquid 渲染时间，或没有带来明显变化。

最终结果是一份按优先级排列的排查计划，你可以自行理解，也可以交给 Shopify 开发者。它能帮助你以证据取代“商店感觉很慢”这种说法，明确指出哪些 Liquid 文件、分区、代码片段和操作值得关注。

重要

MCP 会诊断并说明潜在的主题瓶颈。它不会自动编辑或发布你的线上主题。主题开发者应审查、测试并安全部署代码更改——最好先在重复主题上进行。

“MCP”是什么意思？

MCP 是 **Model Context Protocol（模型上下文协议）**的缩写。简单来说，它是一种让 AI 助手使用一组专业工具的方式。

如果没有这个 MCP，AI 助手通常无法直接请求你商店的 Shopify Liquid 性能分析数据。接入后，助手就能运行经授权的只读性能检查，并与你讨论结果。

可以把它看作一座本地桥梁：

You ask a question
        ↓
Your AI assistant chooses the right inspection tool
        ↓
Shopify returns Liquid profiling data for the requested page
        ↓
The AI explains the evidence and suggests what to investigate

它如何帮助你的 Shopify 业务

情况	MCP 如何提供帮助
首页感觉很慢	找出占用服务器渲染时间最多的 Liquid 分区、片段和操作。
商品目录增大后，系列页面变慢了	比较页面，并查找重复的商品、菜单、筛选器或循环处理。
你安装或移除了应用	显示与应用相关的主题区块是否出现在性能分析中开销较大的部分。
代理机构或开发者优化了主题	保存性能分析历史记录，以便比较优化前后的结果。
你不知道从哪里着手	对可能的瓶颈进行排序，帮助团队优先调查影响最大的部分。
你需要向开发者说明情况	生成易读的 Markdown 或 CSV 报告，其中包含技术证据，以及适用时的相关文件信息。
不同页面类型的表现各不相同	比较首页、系列、商品、购物车以及其他公开店面 URL。

发现并修复 Liquid 瓶颈可以减少 Shopify 服务器端的主题渲染工作。不过，此工具不保证获得特定的 Lighthouse 分数、Core Web Vitals 结果、搜索排名或销售额提升。这些结果还取决于图片、JavaScript、应用、网络状况、客户设备、主题设计等诸多因素。

检查时会发生什么？

1. 选择一个页面，例如首页、系列页面或商品页面。
2. 使用获准访问该店铺的账号登录 Shopify。
3. MCP 请求该页面的只读 Liquid 性能分析。
4. Shopify 返回计时数据，显示主题在服务器上是如何渲染的。
5. AI 助手解读性能分析结果，并按可能的重要程度整理发现。
6. 由你或开发者决定要更改什么。 MCP 不会更改主题。
7. **安全更新主题后重新运行性能分析，**查看结果是否有所改善。

为了获得更可靠的对比，请对同一页面进行多次性能分析。Shopify 基础设施和缓存状态可能会导致不同运行结果之间出现正常波动。

可以检查哪些内容？

• 对你获准检查的 Shopify 店铺中的任何页面进行性能分析。
• 说明耗时较长的 Liquid 分区、片段、区块、标签和应用嵌入项。
• 在 Shopify 提供相关信息时，指出相关主题文件和行号。
• 比较两个页面，或将最多 10 个页面按速度从慢到快排序。
• 检测重复渲染、开销较大的查询、繁重的模板以及其他常见模式。
• 保存性能分析历史记录，以便衡量主题更改是否有帮助。
• 将报告导出为 Markdown、CSV 或 Speedscope JSON。
• 通过 AI 助手读取并解读结果。

性能分析为只读操作：它会向 Shopify 请求性能数据，不会编辑或发布你的主题。

开始之前

你需要：

1. Node.js 18 或更高版本。 如果尚未安装，请从 nodejs.org 下载 LTS 版本。
2. 用于登录 Shopify 的 Google Chrome 或 Chromium。
3. 支持本地 MCP 服务的 AI 应用。
4. 获准访问你要进行性能分析的店铺的 Shopify 账号。

使用 npm 软件包时，无需下载此存储库。

npm 包详情

此 MCP 已作为公开包发布到 npm，受支持的 AI 应用可以为你下载并启动它。

详情	值
包	shopify-theme-inspector-mcp
当前版本	0.5.1
运行环境	Node.js 18 或更高版本
许可证	MIT
源代码	GitHub 仓库
MCP Registry 标识	io.github.dragnoir/shopify-theme-inspector
MCP 连接类型	本地 STDIO 进程

以下示例使用 npx -y shopify-theme-inspector-mcp@latest。npx 会在需要时下载公开包，并在本地启动 MCP。你无需全局安装、克隆仓库或拥有 npm 账号。

查看最新发布的版本：

npm view shopify-theme-inspector-mcp version

使用 @latest 会自动选择当前的 npm 版本。需要可重复环境的团队可以将其替换为固定版本，例如 [email protected]。

连接到 Codex

打开终端并运行：

codex mcp add shopify-theme-inspector -- npx -y shopify-theme-inspector-mcp@latest

重启 Codex。你可以运行以下命令，确认服务已注册：

codex mcp list

然后询问：

使用 shopify-theme-inspector health_check 工具，并展示结果。

Codex 将本地 MCP 配置保存在 ~/.codex/config.toml 中。同一 Codex 主机上的 Codex 应用、CLI 和 IDE 扩展共用此配置。你也可以在支持的 Codex 界面中通过 Settings → MCP servers 添加服务。有关当前配置选项，请参阅官方的 Codex MCP 文档。

连接到 Claude Code

打开终端并运行：

claude mcp add --transport stdio --scope user shopify-theme-inspector -- npx -y shopify-theme-inspector-mcp@latest

--scope user 选项可让所有 Claude Code 项目使用此 MCP。运行以下命令确认连接：

claude mcp list

在 Claude Code 中，你也可以运行 /mcp 查看服务及其工具。然后询问：

使用 shopify-theme-inspector health_check 工具，并解释结果。

有关作用域、服务管理和故障排查，请参阅官方的 Claude Code MCP 文档。

连接到 Claude Desktop

Claude Desktop 可以在 macOS 或 Windows 上将此包作为本地 MCP 服务运行：

1. 安装 Node.js 18 或更高版本。
2. 打开 Claude Desktop → Settings → Developer → Edit Config。
3. 在 mcpServers 对象中添加以下配置。
4. 保存文件，完全退出 Claude Desktop，然后重新打开。

{
  "mcpServers": {
    "shopify-theme-inspector": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "shopify-theme-inspector-mcp@latest"]
    }
  }
}

如果你已有其他 MCP 服务，请保留它们，只添加 shopify-theme-inspector 条目。不要创建第二个 mcpServers 对象。

重启后，点击聊天框中的 + 按钮，在 Connectors 菜单中确认工具已可用。然后询问 Claude：

使用 Shopify Theme Inspector health_check，并说明是否已准备就绪。

配置文件通常位于：

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

请参阅官方 MCP 指南，了解如何将本地服务连接到 Claude Desktop。

在其他 MCP 应用中设置

在 AI 应用的设置中找到 MCP Servers、Tools 或 Integrations，然后添加一个本地/STDIO 服务：

• 名称： shopify-theme-inspector
• 命令： npx
• 参数： -y、shopify-theme-inspector-mcp@latest

如果应用要求提供 JSON，请使用：

{
  "mcpServers": {
    "shopify-theme-inspector": {
      "command": "npx",
      "args": ["-y", "shopify-theme-inspector-mcp@latest"]
    }
  }
}

保存服务后，重启 AI 应用。

生成你的第一份首页报告

将以下提示词逐条复制到 AI 助手中。请将示例域名替换为你的商店域名。

1. 检查连接

使用 Shopify Theme Inspector health_check，并解释结果。

2. 登录 Shopify

使用登录工具访问 https://example-store.com/

Chrome/Chromium 窗口会打开。使用有权访问该商店的 Shopify 账户登录。

如果你特别想重用已经打开且已登录的 Chrome 配置文件，请提出：

使用我现有的 Chrome 配置文件登录 https://example-store.com/。

AI 可以先使用 login_in_chrome，再使用 complete_login_in_chrome。根据你使用的 AI 应用，它可能会要求你从 Chrome 地址栏复制最终回调 URL。请将该 URL 视为临时私密登录数据，并且只提供给启动此次登录的本地 MCP 工具。

3. 请求一份易读的审计报告

为首页生成一份深入的性能报告。用通俗易懂的语言解释发现的问题，按影响程度排列修复项，并注明相关的 Liquid 文件和行号。

这样就足够开始了。AI 会选择分析工具，并将结果整理成报告。

任何人都可以使用的实用提示词

找出首页最严重的问题

分析 https://example-store.com/ 的首页，并告诉我最应优先修复的三个问题。

比较页面

比较 https://example-store.com/ 上的 / 和 /collections/all，并解释为什么其中一个页面较慢。

检查多个页面

分析 https://example-store.com/ 上的 /、/collections/all、/products/example 和 /cart。按速度从慢到快排列。

衡量主题优化效果

显示 https://example-store.com/ 上 / 的性能分析历史，并告诉我性能是否有所改善。

创建可分享的报告

为 https://example-store.com/ 的首页导出一份 Markdown 性能报告。

为开发人员或代理机构创建报告

分析 https://example-store.com/ 的首页。为我的 Shopify 开发人员创建一份交接报告，其中包括便于站主理解的摘要、每项发现的证据、相关的 Liquid 文件和行号、建议的修复方法、更改前需要检查的风险，以及前后对比测试计划。不要编辑主题。

查看经过脱敏的首页报告示例，了解分析自己商店之前预期的输出内容。该示例使用虚构的商店数据，不包含商家信息或身份验证数据。

区分业务决策与代码更改

审查首页性能分析，并将建议分为以下几类：我作为商店所有者可以决定的事项、Shopify 开发人员应调查的事项，以及需要更多证据才能更改主题的事项。

我需要 Shopify 开发者吗？

你不需要懂编程，也能按照步骤完成设置、请求性能分析，或阅读面向店主的报告。AI 助手可以解释技术术语，并帮助你准备一份清晰的需求说明。如果你不习惯安装 Node.js 或使用终端，可以请开发者或技术团队成员为你完成一次性设置。

通常，你需要 Shopify 主题开发者来实施建议。Liquid 性能优化可能会影响商品卡片、菜单、定价、本地化、分析、应用功能以及店面的其他行为。开发者可以确认原因，在重复主题上进行修改，测试店面，并仅在确认修改安全后发布。

一份有用的报告应包含：

• **店主摘要：**检查了什么，以及结果为何重要。
• **按优先级排序的发现：**哪些问题现在需要处理，哪些可以稍后处理，哪些仅在出现更多证据时才需要处理。
• **证据：**计时数据、重复次数、模板名称，以及 Shopify 提供的文件或行号信息。
• **建议操作：**开发者应调查什么，而不只是笼统地要求“优化主题”。
• **风险与权衡：**必须继续正常运行的功能或业务行为。
• **验证计划：**修改后如何再次分析和测试页面。

请将建议视为需要调查的线索，而不是删除主题或应用代码的许可。频繁渲染的组件仍可能是购物体验中不可或缺的一部分。

AI 可以检查什么

工具	功能
health_check	确认 MCP 服务正常运行，并列出其功能。
get_auth_status	显示店铺登录是否有效。
login	在专用浏览器会话中打开 Shopify Identity 登录页面。
login_in_chrome	在现有 Chrome 配置文件中开始登录。
complete_login_in_chrome	安全地完成现有 Chrome 登录流程。
logout	删除店铺的本地已保存身份验证信息。
profile_page	返回完整的 Shopify Liquid 火焰图。
get_profile_summary	返回易读的总计、顶层节点和模板细分数据。
get_bottlenecks	查找性能模式并推荐修复方法。
find_slow_templates	列出耗时超过指定阈值的分区和片段。
compare_pages	分析两个页面并显示差异。
batch_profile	分析最多 10 个页面并按表现排序。
get_profile_history	显示已保存运行记录中的渲染时间变化。
export_profile	导出 Markdown、CSV 或 Speedscope JSON。
login_legacy	启动访问 Admin API 主题文件所需的可选旧版会话。
analyze_liquid_file	静态检查 Liquid 文件；需要旧版登录。

对大多数用户来说，login、get_profile_summary、get_bottlenecks 和 find_slow_templates 就足够了。

如何阅读结果

• Liquid 总渲染时间是 Shopify 的服务器端主题渲染时间，并非浏览器完整的页面加载时间。
• 自身耗时是单个操作本身所做的工作，不包括其子项。
• 总耗时包括嵌套操作所做的工作。
• 百分比表示该分析中归因于某个节点或模板的耗时占比。
• 渲染／事件计数用于突出循环和嵌套主题结构中的重复工作。

不要将所有模板的百分比相加，并视为必定能节省的时间；父级和子级的计时可能重叠。请运行多次分析，并优先处理持续位居前列的项目。

通俗术语表

术语	含义
主题	控制在线商店外观和行为的模板与代码。
Liquid	Shopify 的模板语言。它会在页面送达购物者之前，于 Shopify 服务器上构建页面内容。
模板	某类页面的主要布局，例如产品页或系列页。
分区	主题页面中可配置的部分，例如横幅、产品网格或精选系列。
代码片段	较小且可重复使用的 Liquid 代码片段，例如产品卡片、价格或图标。
应用区块或嵌入内容	Shopify 应用添加的主题代码，用于提供店面功能。
服务器端渲染时间	Shopify 在发送响应前处理 Liquid 主题所花费的时间。这只是购物者整体页面加载体验的一部分。
瓶颈	消耗足够多的时间或重复次数足够多、值得调查的工作。
火焰图	一种技术可视化图表，显示渲染时间花在了哪些地方。MCP 会将这些数据转化为摘要和建议。
性能分析记录	一次记录 Shopify 如何渲染某个特定店面页面的测量结果。

检测内容

建议引擎可以标记以下内容：

• all_products[handle] 以及重复的产品／资源查找。
• content_for_header 周围耗时较高的工作。
• 嵌套较深或重复执行的 Liquid 循环。
• 开销较大的分区、代码片段、区块和第三方应用嵌入内容。
• 产品、菜单、图片、价格、架构和购物车渲染模式。
• 占用 Liquid 时间比例过高的模板。

建议只是着手调查的起点，并不能自动证明某项功能应该移除。业务价值和店面行为仍然很重要。

隐私与本地数据

身份验证信息和性能分析记录历史会保存在运行 MCP 服务的计算机上：

数据	默认位置
OAuth 令牌	~/.shopify-theme-inspector/oauth-tokens.json
性能分析记录历史	~/.shopify-theme-inspector/history/

• 令牌用于请求 Shopify 性能分析数据。
• 此软件包不会将性能分析结果发送到独立的分析服务。
• 你的 AI 应用可能有自己的数据和隐私政策；请另行查看该政策。
• 切勿在问题帖或公开聊天中发布 OAuth 回调 URL、访问令牌或本地令牌文件。

如果要移除某个商店已保存的身份验证信息，请运行 logout。

不会测量的内容

此软件包专注于 Shopify 的服务器端 Liquid 渲染。它不能替代 Lighthouse、WebPageTest 或真实用户 Core Web Vitals。

它不会直接测量：

• 浏览器 JavaScript 执行情况。
• 图片传输大小或 CDN 下载时间。
• 字体和第三方浏览器脚本。
• CLS、INP 或真实用户 LCP。
• 移动网络和设备性能。

若要开展完整的性能优化项目，请使用此 MCP 处理 Liquid 工作，并使用浏览器性能工具处理前端工作。

故障排除

AI 找不到这些工具

添加 MCP 服务后，重启 AI 应用。在 Codex 中运行：

codex mcp list

确认已启用 shopify-theme-inspector。

系统无法识别 npx

从 nodejs.org 安装 Node.js LTS 版本，然后重新打开终端和 AI 应用。

Shopify 提示商店未通过身份验证

让 AI 运行 get_auth_status，然后针对同一个商店域名再次运行 login。

打开了错误的 Chrome 配置文件

保持你偏好的 Chrome 配置文件处于打开状态，并让 AI 使用 login_in_chrome。如果 Chrome 仍选择了其他配置文件，请将授权 URL 复制到正确的配置文件中，完成登录后，仅向 complete_login_in_chrome 提供最终回调 URL。

不同运行的报告结果有所变化

由于 Shopify 基础设施和缓存状态的影响，结果存在一些差异是正常的。运行三到五次性能分析，并比较中位数和最慢结果。

浏览器无法打开

请安装 Google Chrome 或 Chromium。在无头 Linux 机器上，Puppeteer 可能还需要下载浏览器：

npx puppeteer browsers install chrome

从源代码安装和运行

本节面向贡献者和开发者。

git clone https://github.com/dragnoir/Shopify-Theme-Inspector-MCP.git
cd Shopify-Theme-Inspector-MCP
npm install
npm run build
npm run test:run

运行构建好的 MCP 服务：

node dist/index.js

打开 MCP Inspector：

npm run inspector

工作原理

1. Shopify Identity OAuth 对已授权的 Shopify 账户进行身份验证。
2. 服务将该登录信息换成 Storefront Renderer DevTools 令牌。
3. 服务使用 Shopify 的 Speedscope 响应类型请求店面。
4. Shopify 返回服务端 Liquid 火焰图，而不是普通 HTML。
5. MCP 会解析、比较、存储并导出这些数据，供 AI 助手使用。

贡献

欢迎提交问题和拉取请求。请提供：

• 用通俗语言描述问题或改进内容。
• 复现步骤。
• 不包含令牌或商店私人数据的脱敏示例。
• 代码更改的测试结果。

代码库：github.com/dragnoir/Shopify-Theme-Inspector-MCP

许可证

MIT