Shopify Liquid MCP

🚀 Shopify Liquid MCP Server

这是一个专为Shopify Liquid文档打造的服务器，速度快、支持本地使用且无需网络。它拥有198份全面的文档，涵盖了所有标签、过滤器和对象，能为Claude、Cursor等AI助手及其他支持MCP的工具，提供即时访问完整Shopify Liquid文档的能力。

🚀 快速开始

这是一个专门的模型上下文协议（MCP）服务器，为Claude、Cursor等AI助手以及其他支持MCP的工具，提供即时访问完整Shopify Liquid文档的能力。

🎯 为何选择此MCP服务器？

与官方Shopify MCP对比

虽然Shopify提供了一个官方MCP服务器，涵盖了所有Shopify API，但此服务器是专门为Liquid模板开发进行优化的：

使用场景

适合使用官方Shopify MCP的场景：

• 管理API/GraphQL开发
• 使用Shopify API进行应用开发
• 功能和POS扩展
• 实时模式验证

适合使用此Liquid MCP的场景：

• 使用Liquid进行主题开发
• Liquid模板调试
• 离线开发
• 更快地查找Liquid参考信息
• 特定项目的Liquid代码片段

两者结合使用！ 它们可以完美互补 - 官方MCP用于API，此服务器用于Liquid。

✨ 主要特性

• 🚀 极速响应 - 本地SQLite FTS5搜索（响应时间<1ms）
• 📚 全面覆盖 - 包含30个标签、101个过滤器和67个对象（共198份文档）
• 🔌 离线优先 - 无需网络请求，随时随地使用
• 🐳 支持Docker - 一键部署
• 🎨 支持IDE集成 - 可与VS Code、Cursor、Claude Desktop、Zed等集成
• 🔧 可定制 - 可添加特定项目的Liquid文档
• 📖 丰富文档 - 包含完整的语法、参数和示例
• 🔍 智能搜索 - 全文搜索并高亮显示代码片段

📦 安装指南

选项1：使用pip（推荐）

pip install git+https://github.com/florinel-chis/shopify-liquid-mcp.git

选项2：使用Docker

# 拉取镜像
docker pull florinel-chis/shopify-liquid-mcp:latest

# 或本地构建
docker build -t shopify-liquid-mcp .
docker run -it shopify-liquid-mcp

选项3：使用docker-compose

docker-compose up -d

选项4：从源代码安装

git clone https://github.com/florinel-chis/shopify-liquid-mcp.git
cd shopify-liquid-mcp
pip install -e .

💻 使用示例

与VS Code集成

使用Docker

创建或编辑 .vscode/settings.json：

{
  "mcp.servers": {
    "shopify-liquid": {
      "type": "docker",
      "image": "shopify-liquid-mcp:latest",
      "transport": "stdio"
    }
  }
}

使用本地安装

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "shopify-liquid": {
      "type": "stdio",
      "command": "shopify-liquid-mcp"
    }
  }
}

或者添加到VS Code设置中：

{
  "mcp.servers": {
    "shopify-liquid": {
      "command": "shopify-liquid-mcp",
      "args": [],
      "transport": "stdio"
    }
  }
}

与Claude Desktop集成

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

使用Docker

{
  "mcpServers": {
    "shopify-liquid": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "shopify-liquid-mcp:latest"]
    }
  }
}

使用本地安装

{
  "mcpServers": {
    "shopify-liquid": {
      "command": "shopify-liquid-mcp"
    }
  }
}

与Cursor集成

添加到Cursor的MCP配置中（设置 > 功能 > MCP服务器）：

{
  "mcpServers": {
    "shopify-liquid": {
      "command": "shopify-liquid-mcp"
    }
  }
}

或者使用Docker：

{
  "mcpServers": {
    "shopify-liquid": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "shopify-liquid-mcp:latest"]
    }
  }
}

与Zed编辑器集成

创建 .zed/settings.json：

{
  "context_servers": {
    "shopify-liquid": {
      "command": "shopify-liquid-mcp"
    }
  }
}

与Continue.dev集成

编辑 ~/.continue/config.json：

{
  "mcpServers": [
    {
      "name": "shopify-liquid",
      "command": "shopify-liquid-mcp"
    }
  ]
}

🛠️ 可用工具

配置完成后，您的AI助手可以使用7个专用工具：

1. search_liquid_docs(queries: List[str])

对所有Shopify Liquid文档进行全文搜索。

示例：

AI: 我将在文档中搜索“for循环”...

2. get_liquid_tag(tag_name: str)

获取特定标签的完整文档。

示例：

AI: 让我获取“for”标签的文档...

3. get_liquid_filter(filter_name: str)

获取特定过滤器的完整文档。

示例：

AI: 我将查找“upcase”过滤器的文档...

4. get_liquid_object(object_name: str)

获取特定对象的完整文档。

示例：

AI: 让我查看“product”对象的属性...

5. list_liquid_tags()

按类别列出所有30个可用标签。

6. list_liquid_filters()

按类别列出所有101个可用过滤器。

7. list_liquid_objects()

按类别列出所有67个可用对象。

💬 示例查询

您可以尝试向AI助手提出以下问题：

获取文档：

• "显示for循环标签的文档"
• "Liquid中的money过滤器如何工作？"
• "product对象有哪些可用属性？"

搜索：

• "搜索有关购物车功能的文档"
• "查找所有与日期相关的过滤器"
• "我可以用于集合的对象有哪些？"

列表：

• "列出所有Shopify Liquid标签"
• "显示所有可用的字符串过滤器"
• "有哪些迭代标签可用？"

构建：

• "帮助我以网格形式显示产品"
• "如何在Liquid中格式化日期？"
• "展示如何使用购物车"

📊 文档覆盖范围

完整参考

• 30个Liquid标签

  • 控制流：if、unless、case、else
  • 迭代：for、break、continue、cycle、tablerow、paginate
  • 变量：assign、capture、increment、decrement、echo
  • 主题：layout、section、sections、render、include、content_for
  • HTML/资产：form、style、stylesheet、javascript
  • 语法：comment、raw、liquid、doc

• 101个Liquid过滤器

  • 字符串（24个）：upcase、downcase、capitalize、append、prepend等
  • 数组（13个）：join、sort、reverse、map、where、size等
  • 数学（11个）：plus、minus、times、divided_by、modulo等
  • 货币（4个）：money、money_with_currency等
  • 图像（5个）：image_url、image_tag等
  • 颜色（9个）：color_darken、color_lighten等
  • 还有更多...

• 67个Liquid对象

  • 商店：shop、settings、theme、brand
  • 产品：product、variant、collection、collections
  • 购物车：cart、line_item、checkout
  • 客户：customer、address、company
  • 内容：page、blog、article、comment
  • 媒体：image、video、media、model
  • 还有更多...

🐳 Docker使用说明

快速开始

# 构建镜像
docker build -t shopify-liquid-mcp .

# 运行服务器
docker run -it --rm shopify-liquid-mcp

# 运行并保留持久数据
docker run -it --rm -v mcp-data:/data shopify-liquid-mcp

使用docker-compose

# 启动服务器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务器
docker-compose down

# 进入容器shell
docker-compose exec shopify-liquid-mcp bash

自定义文档

添加特定项目的Liquid文档：

# 创建自定义文档目录
mkdir custom-docs

# 添加.md文件
cp my-snippets.md custom-docs/

# 在docker-compose.yml中挂载
volumes:
  - ./custom-docs:/docs/custom:ro

🔧 技术细节

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_ingest.py

# 运行并查看覆盖率
pytest --cov=shopify_liquid_mcp

手动测试

# 测试服务器
python test_server.py

# 测试索引
python -m shopify_liquid_mcp.ingest

# 检查数据库
sqlite3 ~/.mcp/shopify-liquid-docs/database.db "SELECT COUNT(*) FROM liquid_docs;"

重新索引文档

# 强制重新索引
python -m shopify_liquid_mcp.ingest --force

# 自定义数据库位置
SHOPIFY_LIQUID_DB_PATH=/custom/path/db.sqlite python -m shopify_liquid_mcp.ingest

📚 详细文档

• 安装指南
• VS Code设置
• Docker指南
• 贡献指南
• 示例
• API参考

🤝 贡献

欢迎贡献代码！请阅读我们的贡献指南。

快速开始

# 分叉并克隆仓库
git clone https://github.com/florinel-chis/shopify-liquid-mcp.git
cd shopify-liquid-mcp

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 或在Windows上使用 `venv\Scripts\activate`

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 进行修改并提交PR

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• 灵感来源于 Gemini API Docs MCP
• 基于 FastMCP 构建
• 文档来源于 Shopify Liquid API
• MCP协议由 Anthropic 提供

🔗 相关项目

• 官方Shopify Dev MCP - 用于Shopify API开发
• FastMCP - MCP服务器框架
• 模型上下文协议 - MCP规范

📞 支持

• 🐛 问题反馈
• 💬 讨论区
• 📧 邮箱

⭐ 星标历史

❤️ 为Shopify主题开发社区精心打造