# Shopify Liquid MCP Server

> 🚀 **Fast, local, offline-first MCP server** for Shopify Liquid documentation with **198 comprehensive docs** including all tags, filters, and objects.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/docker-supported-blue.svg)](https://hub.docker.com/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)

A specialized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides instant access to complete Shopify Liquid documentation for AI assistants like Claude, Cursor, and other MCP-compatible tools.

## 🎯 Why This MCP Server?

### vs. Official Shopify MCP

While Shopify provides an [official MCP server](https://shopify.dev/docs/apps/build/devmcp) that covers all Shopify APIs, this server is specifically optimized for **Liquid template development**:

| Feature | Official Shopify MCP | This (Liquid MCP) |
|---------|---------------------|-------------------|
| **Focus** | All Shopify APIs (Admin, Storefront, Functions, etc.) | **Liquid templating only** |
| **Storage** | Remote (queries shopify.dev) | **Local (no network needed)** |
| **Speed** | Network-dependent | **Instant (<1ms)** |
| **Offline** | ❌ Requires internet | **✅ Fully offline** |
| **Customization** | Fixed documentation | **Add your own docs** |
| **Coverage** | General API docs | **198 Liquid-specific docs** |
| **Runtime** | Node.js | **Python** |

### Use Cases

**Use Official Shopify MCP for:**
- Admin API/GraphQL development
- App development with Shopify APIs
- Functions and POS extensions
- Real-time schema validation

**Use This Liquid MCP for:**
- Theme development with Liquid
- Liquid template debugging
- Offline development
- Faster Liquid reference lookups
- Project-specific Liquid snippets

**Use Both!** They complement each other perfectly - official MCP for APIs, this for Liquid.

## ✨ Features

- 🚀 **Lightning Fast** - Local SQLite FTS5 search (<1ms response time)
- 📚 **Complete Coverage** - 30 tags, 101 filters, 67 objects (198 total docs)
- 🔌 **Offline First** - No network requests, works anywhere
- 🐳 **Docker Ready** - One command deployment
- 🎨 **IDE Integration** - Works with VS Code, Cursor, Claude Desktop, Zed
- 🔧 **Customizable** - Add your own project-specific Liquid docs
- 📖 **Rich Documentation** - Full syntax, parameters, examples for everything
- 🔍 **Smart Search** - Full-text search with snippet highlighting

## 📦 Installation

### Option 1: Using pip (Recommended)

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

### Option 2: Using Docker

```bash
# Pull the image
docker pull florinel-chis/shopify-liquid-mcp:latest

# Or build locally
docker build -t shopify-liquid-mcp .
docker run -it shopify-liquid-mcp
```

### Option 3: Using docker-compose

```bash
docker-compose up -d
```

### Option 4: From Source

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

## 🎮 Usage

### With VS Code

#### Using Docker

Create or edit `.vscode/settings.json`:

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

#### Using Local Installation

Create `.mcp.json` in your project root:

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

Or add to VS Code settings:

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

### With Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

#### Using Docker

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

#### Using Local Installation

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

### With Cursor

Add to Cursor's MCP configuration (Settings > Features > MCP Servers):

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

Or with Docker:

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

### With Zed Editor

Create `.zed/settings.json`:

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

### With Continue.dev

Edit `~/.continue/config.json`:

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

## 🛠️ Available Tools

Once configured, your AI assistant has access to 7 specialized tools:

### 1. `search_liquid_docs(queries: List[str])`
Full-text search across all Shopify Liquid documentation.

**Example:**
```
AI: I'll search for "for loop" in the documentation...
```

### 2. `get_liquid_tag(tag_name: str)`
Get complete documentation for a specific tag.

**Example:**
```
AI: Let me get the documentation for the 'for' tag...
```

### 3. `get_liquid_filter(filter_name: str)`
Get complete documentation for a specific filter.

**Example:**
```
AI: I'll look up the 'upcase' filter documentation...
```

### 4. `get_liquid_object(object_name: str)`
Get complete documentation for a specific object.

**Example:**
```
AI: Let me check the 'product' object properties...
```

### 5. `list_liquid_tags()`
List all 30 available tags organized by category.

### 6. `list_liquid_filters()`
List all 101 available filters organized by category.

### 7. `list_liquid_objects()`
List all 67 available objects organized by category.

## 💬 Example Queries

Try asking your AI assistant:

**Getting Documentation:**
- "Show me documentation for the for loop tag"
- "How does the money filter work in Liquid?"
- "What properties are available on the product object?"

**Searching:**
- "Search for documentation about cart functionality"
- "Find all filters related to dates"
- "What objects can I use for collections?"

**Listing:**
- "List all Shopify Liquid tags"
- "Show me all available string filters"
- "What iteration tags are available?"

**Building:**
- "Help me display products in a grid"
- "How do I format dates in Liquid?"
- "Show me how to work with the cart"

## 📊 Documentation Coverage

### Complete Reference

- **30 Liquid Tags**
  - Control flow: `if`, `unless`, `case`, `else`
  - Iteration: `for`, `break`, `continue`, `cycle`, `tablerow`, `paginate`
  - Variables: `assign`, `capture`, `increment`, `decrement`, `echo`
  - Theme: `layout`, `section`, `sections`, `render`, `include`, `content_for`
  - HTML/Assets: `form`, `style`, `stylesheet`, `javascript`
  - Syntax: `comment`, `raw`, `liquid`, `doc`

- **101 Liquid Filters**
  - String (24): `upcase`, `downcase`, `capitalize`, `append`, `prepend`, etc.
  - Array (13): `join`, `sort`, `reverse`, `map`, `where`, `size`, etc.
  - Math (11): `plus`, `minus`, `times`, `divided_by`, `modulo`, etc.
  - Money (4): `money`, `money_with_currency`, etc.
  - Image (5): `image_url`, `image_tag`, etc.
  - Color (9): `color_darken`, `color_lighten`, etc.
  - And more...

- **67 Liquid Objects**
  - Store: `shop`, `settings`, `theme`, `brand`
  - Products: `product`, `variant`, `collection`, `collections`
  - Cart: `cart`, `line_item`, `checkout`
  - Customer: `customer`, `address`, `company`
  - Content: `page`, `blog`, `article`, `comment`
  - Media: `image`, `video`, `media`, `model`
  - And more...

## 🐳 Docker Usage

### Quick Start

```bash
# Build the image
docker build -t shopify-liquid-mcp .

# Run the server
docker run -it --rm shopify-liquid-mcp

# Run with persistent data
docker run -it --rm -v mcp-data:/data shopify-liquid-mcp
```

### Using docker-compose

```bash
# Start the server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

# Shell access
docker-compose exec shopify-liquid-mcp bash
```

### Custom Documentation

Add your project-specific Liquid docs:

```bash
# Create custom docs directory
mkdir custom-docs

# Add your .md files
cp my-snippets.md custom-docs/

# Mount in docker-compose.yml
volumes:
  - ./custom-docs:/docs/custom:ro
```

## 🔧 Development

### Running Tests

```bash
# Run all tests
pytest

# Run specific test
pytest tests/test_ingest.py

# Run with coverage
pytest --cov=shopify_liquid_mcp
```

### Manual Testing

```bash
# Test the server
python test_server.py

# Test indexing
python -m shopify_liquid_mcp.ingest

# Check database
sqlite3 ~/.mcp/shopify-liquid-docs/database.db "SELECT COUNT(*) FROM liquid_docs;"
```

### Reindexing Documentation

```bash
# Force reindex
python -m shopify_liquid_mcp.ingest --force

# Custom database location
SHOPIFY_LIQUID_DB_PATH=/custom/path/db.sqlite python -m shopify_liquid_mcp.ingest
```

## 📖 Documentation

- [Installation Guide](./docs/INSTALLATION.md)
- [VS Code Setup](./docs/VSCODE.md)
- [Docker Guide](./docs/DOCKER.md)
- [Contributing](./CONTRIBUTING.md)
- [Examples](./EXAMPLES.md)
- [API Reference](./docs/API.md)

## 🤝 Contributing

Contributions welcome! Please read our [Contributing Guide](./CONTRIBUTING.md).

### Quick Start

```bash
# Fork and clone
git clone https://github.com/florinel-chis/shopify-liquid-mcp.git
cd shopify-liquid-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Make changes and submit PR
```

## 📜 License

MIT License - see [LICENSE](./LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by [Gemini API Docs MCP](https://github.com/philschmid/gemini-api-docs-mcp)
- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Documentation from [Shopify Liquid API](https://shopify.dev/docs/api/liquid)
- MCP Protocol by [Anthropic](https://www.anthropic.com/)

## 🔗 Related Projects

- [Official Shopify Dev MCP](https://shopify.dev/docs/apps/build/devmcp) - For Shopify API development
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

## 📞 Support

- 🐛 [Issues](https://github.com/florinel-chis/shopify-liquid-mcp/issues)
- 💬 [Discussions](https://github.com/florinel-chis/shopify-liquid-mcp/discussions)
- 📧 [Email](mailto:your.email@example.com)

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=florinel-chis/shopify-liquid-mcp&type=Date)](https://star-history.com/#florinel-chis/shopify-liquid-mcp&Date)

---

**Made with ❤️ for the Shopify theme development community**