# zplflow

> Universal Thermal Label Infrastructure: 6-Dialect AST Transpiler (ZPL, EPL, TSPL, DPL, IPL, SBPL), Bi-directional ZPL ↔ PDF conversion, On-Premise Smart Routing, 100% physical hardware parity, and native Model Context Protocol (MCP) server for AI agents.

zplflow is the modern enterprise thermal label infrastructure for logistics, ERP (SAP, AS/400, Odoo), WMS, and 3PL fulfillment platforms. It replaces legacy single-direction converters and fragile desktop print agents with an industrial-grade, non-invasive programmable middleware.

## Key Capabilities

- **6-Dialect Universal Label Bridge:** Bidirectional AST-to-AST transpilation between ZPL II, Eltron EPL2, TSC TSPL2, Datamax DPL, Intermec IPL, and SATO SBPL in < 9 µs, eliminating printer hardware lock-in without touching host ERP code.
- **Bi-directional PDF ↔ ZPL Conversion:** Synchronous (< 50ms) and asynchronous conversion between raw ZPL and vector/raster PDF. Supports 203 DPI (8 dpmm), 300 DPI (12 dpmm), and 600 DPI (24 dpmm) with budget-aware degradation.
- **100% Physical Hardware Parity:** Dot-perfect rendering calibrated directly on physical industrial thermal printer hardware. Preserves exact barcode quiet zones and font metrics, with zero-panic resilience against corrupt legacy streams.
- **On-Premise Smart Routing & Edge Spooling:** Industrial 1 Hub : N Print Servers architecture. Intelligent format classification, automated failover, out-of-paper auto-resume, IPPS :631 TLS Zero-CUPS (NIS2-ready), and 72-hour offline token-lease resilience.
- **Programmable ZPL Pipelines (24 Transformers):** Parse, inspect, and mutate ZPL DOM on the fly (GS1-128 compliance, 2D DataMatrix injection, dynamic expiry dates, carrier re-routing).
- **Odoo WMS Direct Thermal Printing:** Native direct printing bridge eliminating the €30/month per-station Odoo IoT Box for 1-click sub-250ms thermal printing.
- **Enterprise Privacy & Sovereignty:** 100% hosted in the European Union (OVHcloud, Gravelines, France). Zero payload retention, GDPR and NIS2 compliant.
- **Native AI Agent Support (MCP):** Official Model Context Protocol server for Claude, Cursor, Windsurf, and LLM orchestration frameworks.
- **Deterministic Token Pricing:** Transparent pricing starting with 6,000 free tokens/month and pass-through direct printing at 0 tokens.

## Quick Start (ZPL to PDF)

### cURL

```bash
curl -X POST "https://api.zplflow.io/v1/convert/zpl-to-pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-zpl" \
  -H "Accept: application/pdf" \
  --data-binary '^XA^FO50,50^ADN,36,20^FDzplflow Universal Bridge^FS^XZ' \
  --output label.pdf
```

### Python

```python
import requests

zpl_payload = "^XA^FO50,50^ADN,36,20^FDzplflow Label^FS^XZ"

response = requests.post(
    "https://api.zplflow.io/v1/convert/zpl-to-pdf",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/x-zpl",
        "Accept": "application/pdf",
    },
    data=zpl_payload.encode("utf-8"),
    params={"dpu": "8dpmm"},  # 8dpmm = 203 DPI, 12dpmm = 300 DPI
)
response.raise_for_status()

with open("label.pdf", "wb") as f:
    f.write(response.content)
```

### Node.js / TypeScript

```typescript
const zpl = "^XA^FO50,50^ADN,36,20^FDzplflow Label^FS^XZ";

const response = await fetch("https://api.zplflow.io/v1/convert/zpl-to-pdf?dpu=8dpmm", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/x-zpl",
    "Accept": "application/pdf",
  },
  body: zpl,
});

if (!response.ok) {
  throw new Error(`Conversion failed: ${response.statusText}`);
}

const pdfBuffer = Buffer.from(await response.arrayBuffer());
```

## Model Context Protocol (MCP) for AI Agents

AI agents can directly inspect labels, run conversions, and manipulate pipelines via zplflow's remote MCP server.

- **MCP Endpoint:** `https://mcp.zplflow.io/v1/mcp/`
- **Transport:** Streamable HTTP

### Claude Desktop Configuration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zplflow": {
      "type": "remote",
      "url": "https://mcp.zplflow.io/v1/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

### Cursor & Windsurf Configuration

1. Add a new **Remote MCP Server**.
2. Set URL to `https://mcp.zplflow.io/v1/mcp/`.
3. Add header: `Authorization: Bearer YOUR_API_KEY`.

Available MCP tools include: `estimateCost`, `getAccountBalance`, `listPipelines`, `getPipeline`, `submitConversion`, `listJobs`, `getJob`, `cancelJob`.

## Comparison: zplflow vs Traditional Tools (Labelary, Generic Emulators)

| Feature | Legacy Converters (Labelary) | Generic Web Emulators | zplflow Enterprise Infrastructure |
|---|---|---|---|
| Latency | ~400ms – 1200ms | 150ms – 500ms (Python GIL) | **< 50ms (PDF) / 1.59–8.79 µs (AST)** |
| Multi-Dialect Bridge | No (ZPL only) | Input raster only (ZPL, EPL) | **6 Languages Bi-directional (ZPL, EPL2, TSPL2, DPL, IPL, SBPL)** |
| Hardware Parity | Approximate | Generic fonts (*Liberation Sans*) | **100% Physical Hardware Parity** |
| Bi-directional (PDF ↔ ZPL) | No (ZPL → PNG/PDF only) | Raster ^GF only | **Full Bi-directional (Vector & Dot-snapped)** |
| On-Premise Printing Hub | None | Single-PC isolated agent | **1 Hub : N Print Servers (Failover, Auto-Resume, IPPS :631 TLS)** |
| Odoo WMS Direct Bridge | None | SEO keyword only (no code) | **Native bridge: 1-click sub-250ms (No IoT Box needed)** |
| DOM Pipelines / GS1-128 | No | String replace only | **24 Programmable DOM Transformers (AST manipulation)** |
| Data Residency & Privacy | US-hosted | Variable / Third-party | **100% EU-hosted (OVHcloud France, GDPR & NIS2)** |
| Native MCP Server | No | Node.js wrapper | **Native High-Performance Go MCP (`https://mcp.zplflow.io/v1/mcp/`)** |
| SLA & Multi-Tenant Reseller | Best effort, rate limited | Single-user Stripe only | **99.95% SLA + Wholesale Token Pool for ISVs/3PLs** |

## Documentation Links

- [Full LLM Specification & API Reference](https://www.zplflow.io/llms-full.txt): Complete consolidated documentation for deep LLM context ingestion.
- [Documentation Index](https://www.zplflow.io/docs): Developer guides, authentication, and examples.
- [API Authentication & Scopes](https://www.zplflow.io/docs/authentication): API key generation, bearer tokens, and granular scopes.
- [Conversion Endpoints](https://www.zplflow.io/docs/conversions): Sync/async conversion specifications and DPI options.
- [Pipeline Engine](https://www.zplflow.io/docs/pipelines): Real-time label manipulation and GS1 transformation.
- [MCP Server Guide](https://www.zplflow.io/docs/mcp): Complete setup and tool specifications for autonomous AI agents.
- [Labelary Comparison](https://www.zplflow.io/vs/labelary): Detailed feature-by-feature benchmark and migration instructions.
- [Pricing & Limits](https://www.zplflow.io/pricing): Free tier details and token packages.