QRTap

qrtap-mcp — 面向 AI Agent 的 QRTap

一个通过 stdio 通信的 MCP 服务，让 Claude 或任何兼容 MCP 的助手都能管理 QRTap 工作区：可编辑的二维码和短链接、公开页面、访客评价、预约请求和条件重定向。

Русская версия: README.ru.md.

为什么需要它

QRTap 二维码包含一个永久短链接，而该链接背后的目标地址可以永久编辑。在菜单、价目表、店面橱窗或名片上印一次二维码，之后便可按需随时更改其跳转目标，无需重新印制。

因此，这款产品很适合 Agent 使用：“给夏季菜单加个二维码”“把贴纸指向新版价目表”“给各个分店分别生成 120 个二维码”“有新的预约吗？”——这些操作都只需调用一两个工具。

安装

npx -y qrtap-mcp        # run the stdio server
npm i -g qrtap-mcp      # or install the qrtap-mcp binary

只需要 Node 20 或更高版本，无需其他依赖：软件包是编译后的 JavaScript，运行时零依赖，因此 npx 只需获取约 22 kB，服务便可启动——首次运行时无需下载工具链。它通过 stdin/stdout 使用 MCP 通信，且只向 stderr 写入日志。

配置

变量	含义
QRTAP_API_KEY	必填。 工作区 API 密钥。
QRTAP_API_URL	API 基础地址。默认值为 https://app.qrtap.kg。

如何获取密钥。 工作区所有者可在 QRTap 控制台的 app.qrtap.kg/workspace/api 中创建密钥。密钥只会显示一次，拥有整个工作区的权限，并且可随时在该页面撤销。**任何套餐（包括免费套餐）**都可以创建密钥——你可以先试用集成，再决定是否付费。套餐会影响额度和批量接口，而不会影响使用权限；请参阅下文的限制和套餐以及 app.qrtap.kg/pricing。

请像对待密码一样保护密钥：将其放在 MCP 客户端的 env 配置块中，不要写入提示词、代码仓库或共享文档。

Claude Desktop

依次点击“Settings” → “Developer” → “Edit Config”，然后在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "qrtap": {
      "command": "npx",
      "args": ["-y", "qrtap-mcp"],
      "env": { "QRTAP_API_KEY": "qrtap_key_XXXX" }
    }
  }
}

Claude Code

claude mcp add qrtap --env QRTAP_API_KEY=qrtap_key_XXXX -- npx -y qrtap-mcp

Cursor、Windsurf、VS Code 和其他 MCP 客户端

凡是接受标准 mcpServers 结构的地方，都可以使用相同的配置项——.cursor/mcp.json、项目根目录下的 .mcp.json，或客户端自己的设置文件：

{
  "mcpServers": {
    "qrtap": {
      "command": "npx",
      "args": ["-y", "qrtap-mcp"],
      "env": { "QRTAP_API_KEY": "qrtap_key_XXXX" }
    }
  }
}

工具

通过公共 REST API v1 提供 20 个工具。读取操作可以随意安全调用；标记为公开影响的四个工具会改变真实客户看到的内容，其说明会要求 Agent 先向用户确认。

二维码和短链接

工具	对应接口
qrtap_create_code(url, title?, external_ref?, group?, design_template_id?)	POST /api/v1/codes
qrtap_create_codes_bulk(items[])	POST /api/v1/codes/bulk — 最多 500 个，逐项返回结果
qrtap_list_codes(group?, external_ref?, include_stats?, limit?, offset?)	GET /api/v1/codes
qrtap_get_code(codeId)	GET /api/v1/codes/{id}
qrtap_change_destination(codeId, url) — 公开影响	PATCH /api/v1/codes/{id}
qrtap_code_history(codeId)	GET /api/v1/codes/{id}/history
qrtap_create_short_link(url)	POST /api/v1/codes
qrtap_list_design_templates()	GET /api/v1/design-templates

分析

工具	对应接口
qrtap_code_stats(codeId, from?, to?)	GET /api/v1/codes/{id}/stats
qrtap_group_stats(group, from?, to?)	GET /api/v1/groups/{group}/stats

扫码分析默认采用匿名汇总方式：提供总数、按日统计序列和设备类别划分。系统会排除机器人，不会存储访客 IP 或 user-agent，因此 Agent 无法查询个人访客记录。

公开页面（/a/{slug}）

工具	对应接口
qrtap_list_pages()	GET /api/v1/pages
qrtap_get_page(slug)	GET /api/v1/pages/{slug}
qrtap_create_page(content)	POST /api/v1/pages
qrtap_update_page(slug, content)	PATCH /api/v1/pages/{slug}

评价和预订

工具	对应接口
qrtap_list_reviews(status?)	GET /api/v1/reviews（默认值为 pending）
qrtap_moderate_review(reviewId, action) — 公开效果	POST /api/v1/reviews/{id}/moderate
qrtap_list_bookings(status?)	GET /api/v1/bookings
qrtap_set_booking_status(bookingId, status) — 公开效果	POST /api/v1/bookings/{id}/status

智能链接（条件重定向）

工具	对应接口
qrtap_get_smart_rules(codeId)	GET /api/v1/codes/{id}/smart-rules
qrtap_set_smart_rules(codeId, rules) — 公开效果	PUT /api/v1/codes/{id}/smart-rules

Agent 应了解的两条规则

覆盖前先读取。 qrtap_update_page 和 qrtap_set_smart_rules 会整体替换其 载荷，省略的内容都会被删除。使用 qrtap_get_page / qrtap_get_smart_rules 获取 当前状态，将更改合并进去，再发送完整对象。

批量操作时设置 external_ref。 创建操作根据 external_ref 实现幂等，因此重试 调用时会返回已有二维码，而不是创建重复项。这使部分失败的批次可以安全地重新运行。

可打印文件

每个二维码都会返回 png_url 和 svg_url。如果要交给印刷店，请直接请求 PDF — 文件接口需要使用相同的 Bearer 密钥：

curl -H "Authorization: Bearer $QRTAP_API_KEY" \
  "https://app.qrtap.kg/api/v1/codes/$CODE_ID/qr?format=pdf" -o code.pdf

format 为 png | svg | pdf；size 用于设置 PNG 宽度（256–3000，印刷用途建议约为 2000）。PNG 输出会在返回前进行解码验证。渲染功能没有作为工具开放，因为结果是二进制文件，而不是 Agent 能够推理的文本。

现成的 Agent 技能

常见任务的分步操作指南——无需重新印刷即可更改菜单、五分钟创建专家页面、为 2GIS/Google/Yandex 评价生成一个二维码、批量创建二维码、处理预订收件箱——都放在仓库的 skills/ 目录中。每份指南都是一个独立完整的 Markdown 文件，可直接交给助手使用。

限额和套餐

每个 /api/v1 调用都受两种限额约束：每分钟限额和每日配额，二者均由工作区套餐设定。

套餐	每分钟	每日	活跃密钥	批量和扫描 Webhook
Free	60	100	1	否
Standard	120	5,000	3	是
Full	300	50,000	10	是

免费套餐旨在让开发者或 Agent 在购买前试用集成：每天 100 次调用足以用于构建和演示，但不足以支撑业务运行。

超出限额时，API 会返回 429 并说明哪项限额已用尽——{"error":"rate_limited", "scope":"minute"} 表示需要等待几秒；{"error":"quota_exceeded","scope":"day"} 表示需要 等到 UTC 午夜。两种响应都包含 Retry-After 和 X-RateLimit-Limit / -Remaining / -Reset 标头；工具结果会原样呈现全部信息，让 Agent 可以退避，而不是不断重试。

无论使用哪种套餐，都建议优先使用两种调用：使用 qrtap_create_codes_bulk 替代循环调用，以及使用 qrtap_list_codes(include_stats=true) 替代逐个请求二维码统计信息。

qrtap_create_codes_bulk 需要付费套餐。在免费工作区中调用时，会返回 402 plan_required，并附上当前套餐和升级 URL；替代方案是在每日配额内循环调用 qrtap_create_code。当前套餐限额统一定义在平台的 API_PLAN_LIMITS 中，上表与其保持一致。

错误

API 请求失败时，会作为普通工具结果返回，并带有 isError: true，其中包含 HTTP 状态码和以文本形式呈现的响应正文，因此 Agent 可以读取并解释错误，而不会崩溃。只有未知的工具名称才会触发 JSON-RPC 错误（-32602）。

状态	含义
401	密钥缺失、无效或已撤销
402 plan_required	请求有效，但套餐不涵盖此操作（批量操作、扫描 webhook）
404	你的工作区中不存在此对象——其他租户的 ID 看起来和笔误一样，这是有意为之
422	内容遭拒：页面没有联系方式，或 QR 码说明中包含促销用语
429	预算已用尽；读取 scope 并遵循 Retry-After

许可证和条款——界限在哪里

此软件包中的客户端代码采用 MIT 许可证：你可以阅读、分支、打包使用，也可以将其集成到自己的产品中。LICENSE 文件列出了完整授权内容。

该许可证仅涵盖这个轻量客户端，不包含其他内容。访问 QRTap API 是另一回事，受你的 QRTap 套餐和 QRTap 使用条款约束：服务、托管平台以及工作区中的数据仍归 QRTap 所有。客户端采用 MIT 许可证并不代表你有权使用 API——你仍需要拥有包含 API 访问权限的有效密钥，并遵守常规限制和条款。

开发

在此软件包目录中运行所有命令，在 monorepo 和公开镜像中均如此：

npm install          # first time only
npm test             # vitest: tool→HTTP mapping and MCP dispatch
npm run typecheck

手动进行冒烟测试——每行一条 JSON-RPC 消息：

npm run build    # dist/ must exist first
QRTAP_API_KEY=qrtap_key_XXXX node bin/qrtap-mcp.mjs <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

发布的软件包是编译后的 JavaScript，位于 dist/ 中，且没有任何运行时依赖项——npx -y qrtap-mcp 下载约 22 kB，并在纯 Node 环境中启动，无需预先获取工具链。每次执行 npm pack 和 npm publish 时，prepack 都会重新构建 dist/，因此不会发布未构建或过时的软件包。

npm run build     # tsc -p tsconfig.build.json → dist/

仓库中的 TypeScript 源码位于 src/（采用 MIT 许可证，见下文），但不会包含在 tarball 中。MCP stdio 协议直接在 src/server.ts 中实现；导入路径带有显式的 .js 扩展名，因为 tsc 不会重写模块说明符，而生成的 ESM 必须能够在纯 Node 环境中解析。

关于此仓库

这是已发布的 qrtap-mcp npm 软件包的源代码：服务、测试和 Agent 技能。QRTap 平台的其余部分（Web 应用、API、数据库）是闭源的，存放在私有仓库中，因此这里的历史始于首次公开发布，而非首次提交。

有一项测试是有意省略的。plan-limits.test.ts 会从平台的数据库软件包中读取套餐表，并检查此 README 中的数字是否与实际销售内容一致；它只能在两部分代码都存在的环境中运行，因此保留在私有仓库中。

欢迎在此提交与服务、技能或文档相关的问题和拉取请求。

链接

• API 参考和密钥 — app.qrtap.kg/developers
• OpenAPI 规范 — app.qrtap.kg/openapi.json
• 套餐和限制 — app.qrtap.kg/pricing
• 问题 — github.com/IlyaShurf/qrtap-mcp/issues

MIT © 2026 QRTap（ИП Шуренков И.П.，吉尔吉斯共和国）