qr-agent-core

Purpose: To provide QR-as-a-Service for AI agents, allowing programmatic creation, updating, and tracking of dynamic QR codes via REST API or MCP. QR codes point to short links (/r/:shortId); the destination URL can be changed at any time while the QR code image remains unchanged; designed for multi-tenancy and provides scan analytics.\n\nMain capabilities: Supports 11 QR code types (URL, vCard, WiFi, Email, SMS, Phone, Event, Text, Location, Social, App Store); custom styling (dot shape, corner style, colors, gradients, embedded logo, border with CTA text); outputs SVG and PNG; analytics include device, browser, operating system, country, city, source, and daily scan statistics; real-time webhooks (HMAC-SHA256 signed and delivery logging); automatic UTM appending, GTM support, conditional redirects (device, OS, country, language, time range, or A/B split); custom domains (Pro); expiration and scheduled link switching; conversion tracking (pixel plus API records events such as purchases and sign-ups); bulk operations (up to 50 per request, Pro can upload 500 via CSV). The MCP service is named qr-for-agent, provides 37 tools, and can be integrated with Claude Desktop, Cursor, etc.\n\nUsage: All /api/* endpoints require the X-API-Key request header, with keys in the format qr_ plus a 32-character random string. Keys are automatically generated and printed to the console on first startup, and can also be created with npm run key:create "my-label" and listed with npm run key:list; /r/, /i/, /health, /documentation, and /.well-known/* are public endpoints that require no authentication; it is published as the npm package qr-for-agent and can be added in the MCP configuration (claude_desktop_config.json or .cursor/mcp.json); registration is available via POST /api/register (email only required, no credit card needed); documentation is at /documentation (Swagger UI).\n\nData and deployment: Uses SQLite with Drizzle ORM, six tables (api_keys, qr_codes, scan_events, webhooks, webhook_deliveries, conversion_events), migrations run automatically when the service starts, and the database is persisted in a Docker volume; includes railway.toml and a multi-stage Dockerfile, allowing self-hosting. Tests include 195 integration tests.\n\nLimitations: Quotas are divided by plan; the free version has 10 QR codes and 1,000 scans per month, while the Pro version is $19/month and unlimited (subject to the documentation; prices and quotas may change); custom domains are available only in Pro; conversion tracking is pixel plus API, and the specific integration details are not covered in the documentation.