QR Agent Core

QR Agent Core

QR-as-a-Service infrastructure for AI agents — generate, manage, and track dynamic QR codes programmatically.

QR codes point to short URLs that you can retarget at any time. The QR image never changes, but scanning it goes to the new destination. Built for AI agents with MCP support, REST API, and multi-tenant isolation.

Features

• Dynamic QR codes — change the destination URL without regenerating the image
• SVG & PNG — vector and bitmap output
• Scan analytics — track scans with timestamps, user agents, and referrers
• Multi-tenant — each API key sees only its own QR codes
• MCP server — qr-for-agent npm package for Claude Desktop, Cursor, etc.
• OpenAPI docs — Swagger UI at /documentation
• AI-discoverable — /.well-known/ai-plugin.json and /.well-known/mcp.json
• SQLite — zero-config database, single file

Quick Start

git clone https://github.com/benswel/qr-agent-core.git
cd qr-agent-core
npm install
npm run dev

On first startup, an API key is auto-generated and printed to the console. Use it to create your first QR code:

curl -X POST http://localhost:3100/api/qr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY_HERE" \
  -d '{"target_url": "https://example.com", "label": "My first QR"}'

API Endpoints

QR Code Management (requires X-API-Key)

Analytics (requires X-API-Key)

Public Endpoints (no auth)

Example: Create a QR code

curl -X POST http://localhost:3100/api/qr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY" \
  -d '{"target_url": "https://example.com", "format": "svg"}'

Response:

{
  "id": 1,
  "short_id": "wkQ5W-fm",
  "short_url": "http://localhost:3100/r/wkQ5W-fm",
  "target_url": "https://example.com",
  "format": "svg",
  "image_data": "<svg>...</svg>",
  "created_at": "2025-02-24T10:00:00.000Z"
}

Example: Update destination (dynamic link)

curl -X PATCH http://localhost:3100/api/qr/wkQ5W-fm \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY" \
  -d '{"target_url": "https://new-destination.com"}'

Authentication

All /api/* endpoints require an X-API-Key header.

• Format: qr_ + 32-character random string
• Auto-generated: on first startup if no keys exist
• Multi-tenant: each key only sees its own QR codes
• Create a key: npm run key:create "my-label"
• List keys: npm run key:list

Public endpoints (/r/*, /i/*, /health, /documentation, /.well-known/*) don't require auth.

MCP Server

The MCP server is published as qr-for-agent on npm. It lets AI agents manage QR codes as native tools.

npx qr-for-agent

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "your-api-key",
        "BASE_URL": "https://your-instance.example.com"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "your-api-key",
        "BASE_URL": "https://your-instance.example.com"
      }
    }
  }
}

Available Tools

Configuration

Copy .env.example to .env and edit:

Database

SQLite with Drizzle ORM. Three tables:

• api_keys — API key storage with labels and expiration
• qr_codes — QR code metadata, target URLs, tenant isolation via api_key_id
• scan_events — scan tracking with timestamps, user agents, IPs

npm run db:generate   # Generate migration from schema changes
npm run db:migrate    # Apply pending migrations
npm run db:studio     # Open Drizzle Studio (web UI)

Migrations run automatically on server startup.

Deployment

Docker

docker compose up -d

The database is persisted in a Docker volume.

Railway

The project includes railway.toml and a multi-stage Dockerfile. Deploy by connecting your GitHub repo to Railway — it will build and deploy automatically with health checks on /health.

Tests

37+ integration tests covering CRUD, auth, multi-tenant isolation, redirects, and analytics.

npm test           # Run all tests
npm run test:watch # Watch mode

Scripts

License

MIT