QR for Agent

Servidor MCP de códigos QR dinámicos para agentes de IA: crea, actualiza y rastrea códigos QR.

Documentación

QR for Agent

API QR-como-servicio construida para agentes de IA. Crea, actualiza y rastrea códigos QR dinámicos programáticamente mediante API REST o MCP (37 herramientas).

Los códigos QR apuntan a URLs cortas (/r/:shortId) que puedes redirigir en cualquier momento: la imagen del QR nunca cambia, pero al escanearlo se va al nuevo destino. Multi-tenant por diseño, con análisis completos de escaneos.

API en vivo: api.qrforagent.com | Sitio: qrforagent.com | MCP: qr-for-agent

Características

Códigos QR dinámicos — cambia la URL de destino sin regenerar la imagen
11 tipos de QR — URL, vCard, WiFi, Email, SMS, Phone, Event, Text, Location, Social, App Store
Estilo personalizado — formas de puntos (square, rounded, dots, classy-rounded), estilos de esquinas, colores, degradados, inserción de logotipos, marcos con texto CTA
SVG y PNG — salida vectorial y de mapa de bits
Análisis enriquecidos — tipo de dispositivo, navegador, SO, país, ciudad, referente, escaneos por día
Webhooks en tiempo real — cargas firmadas con HMAC-SHA256 y registro de entrega
Seguimiento UTM — añade automáticamente parámetros UTM a las URLs de redirección
Soporte GTM — página intermedia con fragmentos de Google Tag Manager
Redirecciones condicionales — enruta por dispositivo, SO, país, idioma, rango de tiempo o división A/B
Dominios personalizados — los usuarios Pro personalizan las URLs cortas con su propio dominio (qr.yourbrand.com/r/abc123)
Expiración y programación — expira códigos QR automáticamente o programa cambios de URL
Seguimiento de conversiones — píxel de seguimiento + API para eventos posteriores al escaneo (compras, registros) con análisis de ROI
Marcos y plantillas — marcos decorativos alrededor de los códigos QR (banner_top, banner_bottom, rounded) con texto CTA
Operaciones por lotes — crea, actualiza o elimina hasta 50 códigos QR por solicitud, o hasta 500 mediante carga CSV (Pro)
Multi-tenant — cada clave API solo ve sus propios datos
Servidor MCP — qr-for-agent con 37 herramientas para Claude Desktop, Cursor, etc.
Cuotas basadas en plan — Gratis (10 QR, 1K escaneos/mes) y Pro ($19/mes, ilimitado)
Registro de autoservicio — POST /api/register con correo electrónico, sin tarjeta de crédito
Integración con Stripe — checkout, portal de facturación, gestión de planes impulsada por webhooks
Documentación OpenAPI — Swagger UI en /documentation
Descubrible por IA — /.well-known/ai-plugin.json y /.well-known/mcp.json
Código abierto — licencia MIT, autoalojable mediante Docker

Inicio rápido

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

En el primer inicio, se genera automáticamente una clave API y se imprime en la consola.

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"}'

Endpoints de la API

Gestión de códigos QR (requiere `X-API-Key`)

Método	Ruta	Descripción
`POST`	`/api/qr`	Crear un código QR (11 tipos, estilo personalizado)
`GET`	`/api/qr`	Listar todos los códigos QR (paginado)
`GET`	`/api/qr/:shortId`	Obtener detalles de un código QR
`PATCH`	`/api/qr/:shortId`	Actualizar URL de destino, etiqueta, UTM, GTM, reglas de redirección
`DELETE`	`/api/qr/:shortId`	Eliminar código QR y sus análisis
`GET`	`/api/qr/:shortId/image`	Descargar imagen QR (regenerada con el estilo almacenado)
`POST`	`/api/qr/bulk`	Crear hasta 50 códigos QR (todo o nada)
`PATCH`	`/api/qr/bulk`	Actualizar hasta 50 códigos QR (éxito parcial)
`DELETE`	`/api/qr/bulk`	Eliminar hasta 50 códigos QR (éxito parcial)
`POST`	`/api/qr/bulk/csv`	Crear hasta 500 códigos QR desde CSV (solo Pro)

Análisis (requiere `X-API-Key`)

Método	Ruta	Descripción
`GET`	`/api/analytics/:shortId`	Estadísticas de escaneo con desgloses por dispositivo, navegador, SO, país, ciudad + conversiones

Conversiones (requiere `X-API-Key`)

Método	Ruta	Descripción
`POST`	`/api/conversions`	Registrar un evento de conversión para un código QR que posees
`GET`	`/api/conversions/:shortId`	Obtener estadísticas de conversión (totales, por_evento, por_día, recientes)

Webhooks (requiere `X-API-Key`)

Método	Ruta	Descripción
`POST`	`/api/webhooks`	Registrar endpoint de webhook (devuelve secreto HMAC)
`GET`	`/api/webhooks`	Listar todos los webhooks
`DELETE`	`/api/webhooks/:id`	Eliminar un webhook

Dominio personalizado (requiere `X-API-Key`, solo Pro)

Método	Ruta	Descripción
`GET`	`/api/domain`	Obtener dominio personalizado actual y estado de DNS
`PUT`	`/api/domain`	Establecer dominio personalizado
`DELETE`	`/api/domain`	Eliminar dominio personalizado

Cuenta (requiere `X-API-Key`)

Método	Ruta	Descripción
`GET`	`/api/usage`	Uso y cuota actuales
`POST`	`/api/stripe/checkout`	Crear sesión de Stripe Checkout (actualizar a Pro)
`POST`	`/api/stripe/portal`	Abrir portal de facturación de Stripe

Público (sin autenticación)

Método	Ruta	Descripción
`POST`	`/api/register`	Registro de clave API de autoservicio (con límite de velocidad)
`GET`	`/r/:shortId`	Redirigir a la URL de destino (registra escaneo)
`GET`	`/t/:shortId`	Píxel de seguimiento de conversiones (devuelve GIF 1×1)
`GET`	`/i/:shortId`	Servir imagen QR (almacenable en caché)
`GET`	`/health`	Verificación de salud
`GET`	`/documentation`	Swagger UI
`GET`	`/.well-known/ai-plugin.json`	Manifiesto de plugin de IA
`GET`	`/.well-known/mcp.json`	Manifiesto de descubrimiento MCP

Administración (requiere cabecera `X-Admin-Secret`)

Método	Ruta	Descripción
`GET`	`/api/admin/keys`	Listar todas las claves API registradas
`GET`	`/api/admin/stats`	Métricas del panel

Autenticación

Todos los endpoints /api/* requieren una cabecera X-API-Key.

Formato: qr_ + cadena aleatoria de 32 caracteres
Generación automática: en el primer inicio si no existen claves
Multi-tenant: cada clave solo ve sus propios códigos QR
Crear una clave: npm run key:create "my-label"
Listar claves: npm run key:list

Los endpoints públicos (/r/*, /i/*, /health, /documentation, /.well-known/*) no requieren autenticación.

Servidor MCP

Publicado como qr-for-agent en npm. 37 herramientas para que los agentes de IA gestionen códigos QR de forma nativa.

npx qr-for-agent

Claude Desktop / Cursor

Añade a tu configuración de MCP (claude_desktop_config.json o .cursor/mcp.json):

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

Herramientas disponibles (37)

Herramienta	Descripción
`create_qr_code`	Crear un código QR de URL con estilo personalizado opcional
`get_qr_code`	Obtener detalles de un código QR por ID corto
`update_qr_destination`	Cambiar a dónde redirige un código QR
`list_qr_codes`	Listar todos los códigos QR con paginación
`delete_qr_code`	Eliminar un código QR y sus análisis
`get_qr_analytics`	Obtener estadísticas de escaneo y desgloses
`bulk_create_qr_codes`	Crear hasta 50 códigos QR a la vez
`bulk_update_qr_codes`	Actualizar hasta 50 códigos QR a la vez
`bulk_delete_qr_codes`	Eliminar hasta 50 códigos QR a la vez
`create_vcard_qr`	Crear un código QR de contacto vCard
`create_wifi_qr`	Crear un código QR de credenciales WiFi
`create_email_qr`	Crear un código QR de correo electrónico (mailto:)
`create_sms_qr`	Crear un código QR de SMS
`create_phone_qr`	Crear un código QR de llamada telefónica
`create_event_qr`	Crear un código QR de evento de calendario
`create_text_qr`	Crear un código QR de texto plano
`create_location_qr`	Crear un código QR de geolocalización
`create_social_qr`	Crear un código QR de enlaces a redes sociales
`create_app_store_qr`	Crear un código QR de redirección inteligente a tienda de aplicaciones
`update_vcard_qr`	Actualizar un código QR de vCard
`update_wifi_qr`	Actualizar un código QR de WiFi
`update_social_qr`	Actualizar un código QR de redes sociales
`update_app_store_qr`	Actualizar un código QR de tienda de aplicaciones
`create_webhook`	Registrar un endpoint de webhook
`list_webhooks`	Listar todos los webhooks registrados
`delete_webhook`	Eliminar un webhook
`register`	Registrarse para obtener una clave API
`get_usage`	Obtener uso y cuota actuales
`upgrade_to_pro`	Crear una sesión de Stripe Checkout
`manage_billing`	Abrir portal de facturación de Stripe
`set_utm_params`	Establecer parámetros de seguimiento UTM en un código QR
`set_redirect_rules`	Establecer reglas de redirección condicional en un código QR
`set_custom_domain`	Establecer o eliminar dominio personalizado (Pro)
`get_custom_domain`	Obtener dominio personalizado actual y estado de DNS
`bulk_create_from_csv`	Crear hasta 500 códigos QR desde datos CSV (Pro)
`record_conversion`	Registrar un evento de conversión posterior al escaneo
`get_conversions`	Obtener estadísticas de conversión para un código QR

Configuración

Copia .env.example a .env y edita:

Variable	Predeterminado	Descripción
`PORT`	`3100`	Puerto HTTP
`HOST`	`0.0.0.0`	Dirección de enlace
`BASE_URL`	`http://localhost:3100`	URL pública (usada en URLs cortas)
`DATABASE_URL`	`./data/qr-agent.db`	Ruta del archivo SQLite
`SHORT_ID_LENGTH`	`8`	Longitud de los IDs cortos generados
`ADMIN_SECRET`	(ninguno)	Secreto para endpoints de administración (cabecera `X-Admin-Secret`)
`STRIPE_SECRET_KEY`	(ninguno)	Clave secreta de la API de Stripe
`STRIPE_WEBHOOK_SECRET`	(ninguno)	Secreto de firma de webhooks de Stripe
`STRIPE_PRICE_ID`	(ninguno)	ID de precio de Stripe para el plan Pro

Base de datos

SQLite con Drizzle ORM. Seis tablas:

api_keys — almacenamiento de claves con etiqueta, correo electrónico, plan (gratis/pro), IDs de Stripe, dominio personalizado
qr_codes — metadatos del QR, URLs de destino, tipo/type_data, opciones de estilo, UTM, GTM, reglas de redirección, expiración/programación
scan_events — seguimiento de escaneos: marca de tiempo, user-agent, referer, IP, dispositivo, navegador, SO, país, ciudad
webhooks — endpoints de webhook por clave API, secreto HMAC, eventos suscritos
webhook_deliveries — registro de entrega: estado, código de respuesta, mensajes de error
conversion_events — seguimiento de conversiones: nombre del evento, valor, metadatos, referer, IP, marca de tiempo

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)

Las migraciones se ejecutan automáticamente al iniciar el servidor.

Despliegue

Docker

docker compose up -d

La base de datos se persiste en un volumen de Docker.

Railway

El proyecto incluye railway.toml y un Dockerfile de múltiples etapas. Conecta tu repositorio de GitHub a Railway: se compila y despliega automáticamente con verificaciones de salud en /health.

Pruebas

195 pruebas de integración que cubren todos los endpoints, autenticación, aislamiento multi-tenant, tipos de QR, webhooks, operaciones por lotes, dominios personalizados, marcos, conversiones, carga CSV y análisis.

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

Scripts

Script	Descripción
`npm run dev`	Iniciar servidor de desarrollo con recarga automática
`npm run build`	Compilar TypeScript
`npm start`	Ejecutar servidor de producción
`npm test`	Ejecutar suite de pruebas
`npm run test:watch`	Pruebas en modo observador
`npm run key:create`	Crear clave API
`npm run key:list`	Listar claves API
`npm run db:generate`	Generar migración
`npm run db:migrate`	Ejecutar migraciones
`npm run db:studio`	Abrir Drizzle Studio

Licencia

MIT

QR for Agent

Documentación

QR for Agent

Características

Inicio rápido

Endpoints de la API

Gestión de códigos QR (requiere X-API-Key)

Análisis (requiere X-API-Key)

Conversiones (requiere X-API-Key)

Webhooks (requiere X-API-Key)

Dominio personalizado (requiere X-API-Key, solo Pro)

Cuenta (requiere X-API-Key)

Público (sin autenticación)

Administración (requiere cabecera X-Admin-Secret)

Autenticación

Servidor MCP

Claude Desktop / Cursor

Herramientas disponibles (37)

Configuración

Base de datos

Despliegue

Docker

Railway

Pruebas

Scripts

Licencia

Gestión de códigos QR (requiere `X-API-Key`)

Análisis (requiere `X-API-Key`)

Conversiones (requiere `X-API-Key`)

Webhooks (requiere `X-API-Key`)

Dominio personalizado (requiere `X-API-Key`, solo Pro)

Cuenta (requiere `X-API-Key`)

Administración (requiere cabecera `X-Admin-Secret`)