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主題開發社區精心打造