金大哥 - shopify-liquid-mcp MCP 详情

article

README

🚀 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 | 此（Liquid MCP） | |---------|---------------------|-------------------| | 专注点 | 所有Shopify API（管理、店面、功能等） | 仅针对Liquid模板 | | 存储方式 | 远程（查询shopify.dev） | 本地（无需网络） | | 速度 | 依赖网络 | 即时响应（<1ms） | | 离线使用 | ❌ 需要网络 | ✅ 完全离线 | | 可定制性 | 固定文档 | 可添加自定义文档 | | 覆盖范围 | 通用API文档 | 198份特定于Liquid的文档 | | 运行环境 | Node.js | Python |

使用场景

适合使用官方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

📚 详细文档

🤝 贡献

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

快速开始

# 分叉并克隆仓库
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主题开发社区精心打造

shopify-liquid-mcp

README

🚀 Shopify Liquid MCP Server

🚀 快速开始

🎯 为何选择此MCP服务器？

与官方Shopify MCP对比

使用场景

✨ 主要特性

📦 安装指南

选项1：使用pip（推荐）

选项2：使用Docker

选项3：使用docker-compose

选项4：从源代码安装

💻 使用示例

与VS Code集成

使用Docker

使用本地安装

与Claude Desktop集成

使用Docker

使用本地安装

与Cursor集成

与Zed编辑器集成

与Continue.dev集成

🛠️ 可用工具

1. search_liquid_docs(queries: List[str])

2. get_liquid_tag(tag_name: str)

3. get_liquid_filter(filter_name: str)

4. get_liquid_object(object_name: str)

5. list_liquid_tags()

6. list_liquid_filters()

7. list_liquid_objects()

💬 示例查询

📊 文档覆盖范围

完整参考

🐳 Docker使用说明

快速开始

使用docker-compose

自定义文档

🔧 技术细节

运行测试

手动测试

重新索引文档

📚 详细文档

🤝 贡献

快速开始

📄 许可证

🙏 致谢

🔗 相关项目

📞 支持

⭐ 星标历史

运行方式说明

托管运行

本地运行 / 其它方式

1. `search_liquid_docs(queries: List[str])`

2. `get_liquid_tag(tag_name: str)`

3. `get_liquid_filter(filter_name: str)`

4. `get_liquid_object(object_name: str)`

5. `list_liquid_tags()`

6. `list_liquid_filters()`

7. `list_liquid_objects()`