QR for Agent

QR for Agent

专为 AI Agent 打造的二维码即服务 API。通过 REST API 或 MCP 以编程方式创建、更新和追踪动态二维码（37 个工具）。

二维码指向短 URL（/r/:shortId），你可以随时更改其目标地址——二维码图像不会改变，但扫描后会跳转到新的目标地址。采用多租户设计，并提供完整的扫描分析数据。

在线 API： api.qrforagent.com  |  网站： qrforagent.com  |  MCP： qr-for-agent

功能

• 动态二维码——无需重新生成图像即可更改目标 URL
• 11 种二维码类型——URL、vCard、WiFi、Email、SMS、Phone、Event、Text、Location、Social、App Store
• 自定义样式——点形状（方形、圆角、圆点、圆润典雅）、角落样式、颜色、渐变、嵌入徽标，以及带 CTA 文案的边框
• SVG 和 PNG——矢量和位图输出
• 增强型分析——设备类型、浏览器、操作系统、国家、城市、引荐来源、每日扫描量
• 实时 Webhook——采用 HMAC-SHA256 签名的载荷，并记录投递情况
• UTM 追踪——自动向重定向 URL 追加 UTM 参数
• GTM 支持——包含 Google Tag Manager 代码片段的中间页面
• 条件重定向——按设备、操作系统、国家、语言、时间范围或 A/B 拆分进行路由
• 自定义域名——Pro 用户可使用自己的域名为短 URL 添加品牌标识（qr.yourbrand.com/r/abc123）
• 过期与定时安排——自动使二维码过期，或安排 URL 切换
• 转化追踪——通过追踪像素和 API 记录扫描后的事件（购买、注册），并提供 ROI 分析
• 边框与模板——二维码装饰边框（banner_top、banner_bottom、rounded），并带有 CTA 文案
• 批量操作——每次请求最多创建、更新或删除 50 个二维码；通过 CSV 上传最多可处理 500 个（Pro）
• 多租户——每个 API 密钥只能访问自己的数据
• MCP 服务——qr-for-agent，提供 37 个工具，可用于 Claude Desktop、Cursor 等
• 按套餐设定配额——Free（10 个二维码，每月 1K 次扫描）和 Pro（$19/月，无限量）
• 自助注册——使用邮箱调用 POST /api/register，无需信用卡
• Stripe 集成——结账、账单门户，以及由 Webhook 驱动的套餐管理
• OpenAPI 文档——位于 /documentation 的 Swagger UI
• 可供 AI 发现——/.well-known/ai-plugin.json 和 /.well-known/mcp.json
• 开源——采用 MIT 许可证，可通过 Docker 自托管

快速开始

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

首次启动时，会自动生成 API 密钥并打印到控制台。

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 端点

二维码管理（需要 X-API-Key）

方法	路径	说明
POST	/api/qr	创建二维码（11 种类型，支持自定义样式）
GET	/api/qr	列出所有二维码（分页）
GET	/api/qr/:shortId	获取二维码详情
PATCH	/api/qr/:shortId	更新目标 URL、标签、UTM、GTM 和重定向规则
DELETE	/api/qr/:shortId	删除二维码及其分析数据
GET	/api/qr/:shortId/image	下载二维码图像（使用已保存的样式重新生成）
POST	/api/qr/bulk	创建最多 50 个二维码（全部成功或全部失败）
PATCH	/api/qr/bulk	更新最多 50 个二维码（允许部分成功）
DELETE	/api/qr/bulk	删除最多 50 个二维码（允许部分成功）
POST	/api/qr/bulk/csv	从 CSV 创建最多 500 个二维码（仅限 Pro）

分析数据（需要 X-API-Key）

方法	路径	说明
GET	/api/analytics/:shortId	扫描统计数据，按设备、浏览器、操作系统、国家、城市细分，并包含转化数据

转化（需要 X-API-Key）

方法	路径	描述
POST	/api/conversions	为你拥有的二维码记录一次转化事件
GET	/api/conversions/:shortId	获取转化统计（总计、按事件、按天、近期记录）

Webhook（需要 X-API-Key）

方法	路径	描述
POST	/api/webhooks	注册 Webhook 端点（返回 HMAC 密钥）
GET	/api/webhooks	列出所有 Webhook
DELETE	/api/webhooks/:id	删除 Webhook

自定义域名（需要 X-API-Key，仅限 Pro）

方法	路径	描述
GET	/api/domain	获取当前自定义域名和 DNS 状态
PUT	/api/domain	设置自定义域名
DELETE	/api/domain	移除自定义域名

账户（需要 X-API-Key）

方法	路径	描述
GET	/api/usage	当前用量和配额
POST	/api/stripe/checkout	创建 Stripe Checkout 会话（升级到 Pro）
POST	/api/stripe/portal	打开 Stripe 账单门户

公共接口（无需身份验证）

方法	路径	描述
POST	/api/register	自助注册 API 密钥（受速率限制）
GET	/r/:shortId	重定向到目标 URL（记录扫描）
GET	/t/:shortId	转化跟踪像素（返回 1×1 GIF）
GET	/i/:shortId	提供二维码图片（可缓存）
GET	/health	健康检查
GET	/documentation	Swagger UI
GET	/.well-known/ai-plugin.json	AI 插件清单
GET	/.well-known/mcp.json	MCP 发现清单

管理员（需要 X-Admin-Secret 请求头）

方法	路径	描述
GET	/api/admin/keys	列出所有已注册的 API 密钥
GET	/api/admin/stats	仪表盘指标

身份验证

所有 /api/* 端点都需要 X-API-Key 请求头。

• 格式：qr_ + 32 个字符的随机字符串
• 自动生成：首次启动时，如果不存在密钥则自动生成
• 多租户：每个密钥只能查看自己的二维码
• 创建密钥：npm run key:create "my-label"
• 列出密钥：npm run key:list

公共端点（/r/*、/i/*、/health、/documentation、/.well-known/*）无需身份验证。

MCP 服务

作为 qr-for-agent 发布在 npm 上。提供 37 个工具，供 AI Agent 原生管理二维码。

npx qr-for-agent

Claude Desktop / Cursor

添加到你的 MCP 配置中（claude_desktop_config.json 或 .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"
      }
    }
  }
}

可用工具（37 个）

工具	描述
create_qr_code	创建可选自定义样式的 URL 二维码
get_qr_code	按短 ID 获取二维码详情
update_qr_destination	更改二维码的重定向目标
list_qr_codes	分页列出所有二维码
delete_qr_code	删除二维码及其分析数据
get_qr_analytics	获取扫描统计数据和细分数据
bulk_create_qr_codes	一次创建最多 50 个二维码
bulk_update_qr_codes	一次更新最多 50 个二维码
bulk_delete_qr_codes	一次删除最多 50 个二维码
create_vcard_qr	创建 vCard 联系人二维码
create_wifi_qr	创建 WiFi 凭据二维码
create_email_qr	创建电子邮件（mailto:）二维码
create_sms_qr	创建短信二维码
create_phone_qr	创建电话呼叫二维码
create_event_qr	创建日历活动二维码
create_text_qr	创建纯文本二维码
create_location_qr	创建地理位置二维码
create_social_qr	创建社交媒体链接二维码
create_app_store_qr	创建智能应用商店重定向二维码
update_vcard_qr	更新 vCard 二维码
update_wifi_qr	更新 WiFi 二维码
update_social_qr	更新社交媒体二维码
update_app_store_qr	更新应用商店二维码
create_webhook	注册 webhook 端点
list_webhooks	列出所有已注册的 webhook
delete_webhook	删除 webhook
register	注册以获取 API 密钥
get_usage	获取当前用量和配额
upgrade_to_pro	创建 Stripe Checkout 会话
manage_billing	打开 Stripe 账单门户
set_utm_params	为二维码设置 UTM 跟踪参数
set_redirect_rules	为二维码设置条件重定向规则
set_custom_domain	设置或移除自定义域名（Pro）
get_custom_domain	获取当前自定义域名和 DNS 状态
bulk_create_from_csv	根据 CSV 数据创建最多 500 个二维码（Pro）
record_conversion	记录扫描后的转化事件
get_conversions	获取二维码的转化统计数据

配置

将 .env.example 复制为 .env 并进行编辑：

变量	默认值	描述
PORT	3100	HTTP 端口
HOST	0.0.0.0	绑定地址
BASE_URL	http://localhost:3100	公共 URL（用于短 URL）
DATABASE_URL	./data/qr-agent.db	SQLite 文件路径
SHORT_ID_LENGTH	8	生成的短 ID 长度
ADMIN_SECRET	（无）	管理端点的密钥（X-Admin-Secret 请求头）
STRIPE_SECRET_KEY	（无）	Stripe API 密钥
STRIPE_WEBHOOK_SECRET	（无）	Stripe webhook 签名密钥
STRIPE_PRICE_ID	（无）	Pro 套餐的 Stripe Price ID

数据库

使用 Drizzle ORM 和 SQLite。包含六张表：

• api_keys — 密钥存储，包含标签、电子邮件、套餐（free/pro）、Stripe ID 和自定义域名
• qr_codes — 二维码元数据、目标 URL、类型/type_data、样式选项、UTM、GTM、重定向规则、过期时间/计划
• scan_events — 扫描跟踪：时间戳、用户代理、来源页、IP、设备、浏览器、操作系统、国家/地区、城市
• webhooks — 每个 API 密钥对应的 webhook 端点、HMAC 密钥、订阅事件
• webhook_deliveries — 投递日志：状态、响应代码、错误消息
• conversion_events — 转化跟踪：事件名称、值、元数据、来源页、IP、时间戳

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)

服务器启动时会自动运行迁移。

部署

Docker

docker compose up -d

数据库保存在 Docker 卷中。

Railway

项目包含 railway.toml 和多阶段 Dockerfile。将 GitHub 仓库连接到 Railway，即可自动构建和部署，并在 /health 上执行运行状况检查。

测试

195 项集成测试，涵盖所有端点、身份验证、多租户隔离、二维码类型、Webhook、批量操作、自定义域名、帧、转换、CSV 上传和分析。

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

脚本

脚本	描述
npm run dev	启动支持自动重新加载的开发服务器
npm run build	编译 TypeScript
npm start	运行生产服务器
npm test	运行测试套件
npm run test:watch	以监视模式运行测试
npm run key:create	创建 API 密钥
npm run key:list	列出 API 密钥
npm run db:generate	生成迁移
npm run db:migrate	运行迁移
npm run db:studio	打开 Drizzle Studio

许可证

MIT