npm package: @helloastral/pixi-mcp-server
Description: Model Context Protocol server for Pixi Order Printer - connect AI assistants to your Shopify templates
Author: Astral Commerce
Latest version: 1.0.0

# Pixi MCP Server

Model Context Protocol server for [Pixi Order Printer](https://pixiorderprinter.com) that enables AI assistants like Claude Desktop and ChatGPT to interact with your Shopify invoice templates.

## Features

- 📋 **List & Read Templates** - Browse and read all your Pixi templates
- ✏️ **Edit Templates** - Modify Liquid templates, GraphQL queries, and configurations
- ✅ **Validation** - Validate Liquid syntax and GraphQL queries before deploying
- 🤖 **AI-Powered** - Get intelligent suggestions and modifications from AI assistants
- 🔒 **Secure** - API key authentication with your Pixi account

## Installation

### Global Installation

```bash
npm install -g @helloastral/pixi-mcp-server
```

### Local Installation

```bash
npm install @helloastral/pixi-mcp-server
```

## Setup

### 1. Get Your API Key

1. Log into your [Pixi Order Printer](https://pixiorderprinter.com) account
2. Open any template editor
3. Click the "MCP" button in the AI tab
4. Generate an API key

### 2. Configure Your AI Assistant

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pixi": {
      "command": "npx",
      "args": ["-y", "@helloastral/pixi-mcp-server"],
      "env": {
        "PIXI_API_KEY": "your_api_key_here",
        "PIXI_APP_URL": "https://app.pixiorderprinter.com"
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "pixi": {
      "command": "pixi-mcp",
      "env": {
        "PIXI_API_KEY": "your_api_key_here",
        "PIXI_APP_URL": "https://app.pixiorderprinter.com"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PIXI_API_KEY` | ✅ Yes | - | Your Pixi MCP API key |
| `PIXI_APP_URL` | ❌ No | `http://localhost:4322` | Pixi API URL |
| `PIXI_DEBUG` | ❌ No | `false` | Enable debug logging |

## Available Tools

### `list_templates`
List all templates in your shop.

### `get_template`
Get complete details of a specific template including all files.

**Arguments:**
- `templateId` (string) - The template ID

### `read_file`
Read a specific file from a template.

**Arguments:**
- `templateId` (string) - The template ID
- `path` (string) - File path: `template.liquid`, `query.graphql`, `schema.json`, or `config.json`

### `write_file`
Write or update a file in a template.

**Arguments:**
- `templateId` (string) - The template ID
- `path` (string) - File path: `template.liquid`, `query.graphql`, `schema.json`, or `config.json`
- `content` (string) - The file content

### `validate_liquid`
Validate Liquid template syntax.

**Arguments:**
- `liquid` (string) - The Liquid template code

### `validate_query`
Validate GraphQL query against Shopify schema.

**Arguments:**
- `query` (string) - The GraphQL query
- `type` (string) - Query type: `order` or `draftOrder`

## Usage Examples

### With Claude Desktop

After setup, you can ask Claude:

> "List all my Pixi templates"

> "Show me the invoice template and add a payment terms section"

> "Validate the GraphQL query in my packing slip template"

### Context Prompt

Access comprehensive context about working with Pixi templates:

```
/pixi-context
```

This provides information about template structure, best practices, and workflows.

## Debugging

Enable debug logging to troubleshoot connection issues:

```json
{
  "mcpServers": {
    "pixi": {
      "command": "pixi-mcp",
      "env": {
        "PIXI_API_KEY": "your_api_key_here",
        "PIXI_APP_URL": "https://app.pixiorderprinter.com",
        "PIXI_DEBUG": "true"
      }
    }
  }
}
```

Debug logs will appear in your AI assistant's console showing:
- API calls and responses
- Tool invocations
- Error details

## Template Structure

Pixi templates consist of four files:

1. **template.liquid** - HTML/CSS document template using Liquid syntax
2. **query.graphql** - GraphQL queries to fetch Shopify order data
3. **schema.json** - JSON schema defining customizable fields
4. **config.json** - Template configuration and settings

## Support

- **Website**: [pixiorderprinter.com](https://pixiorderprinter.com)
- **Documentation**: Available in the Pixi app
- **Issues**: Contact support through the Pixi app

## License

MIT © Astral Commerce