barcode-mcp

Stateless barcode tools for LLM agents, exposed via the Model Context Protocol (protocol 2025-11-25 via SDK 1.30.0, negotiable down to 2024-10-07).

Extracted from the engines proven in the QR Saver PWA: one WASM engine (zxing-cpp via zxing-wasm) does both render and decode — no DOM, no browser, fully headless.

Tools

render_barcode decodes its own output before returning; failures come back with warning, never silently.

Related MCP server: QR Reader MCP Server

Connect (hosted, no install)

Live endpoint, no API key — registered in the official MCP Registry as io.github.appvantagelabs2-a11y/barcode.

list_formats and validate_gtin are free. decode_barcode and render_barcode cost fractions of a cent per call, two ways:

1. x402 (permissionless) — unpaid calls return HTTP 402 with USDC payment instructions; an x402-capable client pays and retries automatically. GET /health shows the current price.

2. Trial key — send X-API-Key: <key> for a free quota of 50 decode/render calls per key. Responses carry X-Trial-Remaining: N; when exhausted the call falls back to x402. Ask for a trial key via a GitHub issue.

Claude Code

claude mcp add barcode --transport http https://mcp.casuyi.com/mcp

Cursor / VS Code (Copilot) / Windsurf / any mcpServers JSON client

{
  "mcpServers": {
    "barcode": { "type": "http", "url": "https://mcp.casuyi.com/mcp" }
  }
}

Claude Desktop — Settings → Connectors → Add custom connector → URL above.

Programmatic (JSON-RPC) — MCP 2025-11-25, Streamable HTTP:

curl -X POST https://mcp.casuyi.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Examples and clients

• examples/curl.md — raw JSON-RPC: tools/list, free validation call, render (x402)

• examples/claude-code.md — connect from Claude Code / Desktop / Cursor / any MCP client

• clients/python.py — minimal Python client (stdlib only)

Run (self-host)

npm install
node test/run.mjs   # 24 tests: round-trips, GTIN, small-image, MCP smoke
node index.js       # stdio MCP server

Register the stdio variant in an MCP client:

{
  "mcpServers": {
    "barcode": { "command": "node", "args": ["/path/to/barcode-mcp/index.js"] }
  }
}

Known behaviors

• UPC-A verifies as zero-padded EAN-13 (042100005264 → 0042100005264) — inherent to the GTIN family, reported in warning.

• Heavy resampling of a large render (non-integer downscale with lanczos) can alias modules below zxing's detection floor — same in native zxing-cpp. Real camera captures (native small sizes) decode fine, including a nearest-upscale retry inside decode().

• WASM loading in Node requires the wasmBinary override (see lib/decoder.js); the browser-style locateFile path fails in Node.

Roadmap (agent-commerce)

• HTTP transport + x402 pay-per-call for agent marketplaces (Agentic.Market, MCP registries)

• Migration to spec 2026-07-28 (stateless core, Mcp-Method/Mcp-Name headers) once the SDK line ships it — the HTTP/gateway mode is exactly what a public paid endpoint wants.