qrcanvas

qrcanvas

qrcanvas 是一个轻量的本地桥接程序，可连接托管的 Hovercode MCP 服务，用于在 Hovercode 工作区内管理二维码、短链接、落地页和表单。你可以通过 Agent 生成二维码——静态二维码，或动态二维码（其目标地址可编辑，扫描情况也会被跟踪）——为其设置颜色、图案、定位眼形状、边框和 Logo，批量生成二维码，用二维码封装 PDF，并下载渲染后的图片。同一工作区还包含短链接、由不同类型区块组成的落地页，以及可读取其回复的表单；所有内容都可通过文件夹和标签整理，并通过扫描和链接分析数据进行衡量。

该桥接程序不保存任何工作区数据。它会在本地返回工具列表，内容与从实时端点捕获的结果完全一致，并将每次工具调用转发至上游，原样返回收到的内容。本次重建包含全部 36 个捕获到的工具。此工具集用于对你自己的工作区执行 CRUD 操作；其中不包含支付、账单或发送工具。

工具

工作区和二维码：

• list_workspaces — 列出此账号可访问的工作区；当前工作区会标记出来。无必填参数。
• set_workspace — 切换当前工作区。必填：workspace。
• create_qr_code — 创建二维码并获取其详情及渲染后的 PNG。必填：qr_data。
• create_qr_codes_bulk — 一次创建多个二维码。必填：items。
• create_pdf_qr — 为 PDF 创建二维码。无必填参数。
• list_qr_codes — 列出并搜索二维码。无必填参数。
• get_qr_code / update_qr_code / delete_qr_code — 读取、更改或移除一个二维码。必填：id。
• download_qr — 下载二维码的渲染图片。必填：id。
• get_qr_activity — 获取一个二维码的扫描活动。必填：id。
• get_analytics — 获取工作区分析数据。无必填参数。

页面和表单：

• build_page — 根据排序后的区块构建并发布落地页。必填：title、blocks。
• create_page — 创建页面。必填：title。
• get_page / update_page / delete_page — 读取、更改或移除一个页面。必填：id。
• list_pages — 列出页面。无必填参数。
• list_block_types — 列出用于构建页面的区块类型。无必填参数。
• create_form — 创建表单。必填：title、fields。
• update_form — 更改表单。必填：id。
• list_forms — 列出表单。无必填参数。
• get_form — 读取一个表单。必填：id。
• get_form_responses — 读取表单回复。必填：id。

短链接和组织管理：

• create_short_link — 创建短链接。必填：link。
• get_short_link / update_short_link / delete_short_link — 读取、更改或移除一个链接。必填：id。
• list_short_links — 列出并搜索链接。无必填参数。
• get_short_link_activity — 获取一个链接的点击活动。必填：id。
• list_templates — 列出设计模板。无必填参数。
• list_folders — 列出文件夹。无必填参数。
• create_folder — 创建文件夹。必填： name。
• update_folder / delete_folder — 重命名、移动或移除文件夹。必填：id。
• list_tags — 列出标签。无必填参数。

配置

• HOVERCODE_MCP_URL（可选）— 覆盖上游端点。默认值为 https://hovercode.com/mcp/。（此覆盖接口是本次重建自行添加并注明的还原内容。）
• HOVERCODE_API_TOKEN（可选）— 设置后，每个上游请求都会携带 Authorization: Bearer <token> 请求头，其中包含你的 Hovercode API 令牌，可跳过 OAuth 浏览器流程。未设置时，不会发送密钥请求头。 （环境变量名称由原始项目的注册表记录确定；该记录对应的远程服务不设置请求头，因此 Bearer 请求头形式属于注明的还原内容——捕获原始工具集时未使用密钥。）

转发机制

首次调用工具时，客户端会在上游打开一个可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo 名称为 qrcanvas），然后发送 notifications/initialized 通知，接着发送携带调用方原样参数的 tools/call 请求。上游以 Mcp-Session-Id 标头响应 initialize 后，该值会附加到此会话的 每个后续请求中，并在进程的整个生命周期内复用该会话。 响应可能以纯 JSON 或服务器发送事件的形式到达；两种形式都会读取。

成功的上游结果会原样传递，包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或 无法完成的请求——会作为 isError 结果返回，文本以 qrcanvas error: 开头（此呈现方式是本次重建自行添加的标记）。

命令行界面

每个工具也可作为子命令使用，并接受一个 JSON 参数字符串：

npx @reneturcios/qrcanvas list_workspaces '{}'
npx @reneturcios/qrcanvas create_qr_code '{"qr_data":"https://example.com","dynamic":true}'
npx @reneturcios/qrcanvas create_short_link '{"link":"https://example.com/a/very/long/path"}'
npx @reneturcios/qrcanvas get_qr_code '{"id":"qr_123"}'
npx @reneturcios/qrcanvas --version

退出代码：成功时为 0，结果为 isError 时为 1， 用法错误时为 2。

MCP 服务

npx -y @reneturcios/qrcanvas mcp

MCP 客户端配置：

{
  "mcpServers": {
    "qrcanvas": {
      "command": "npx",
      "args": ["-y", "@reneturcios/qrcanvas", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/qrcanvas
docker run --rm ghcr.io/cloudcorprecords/qrcanvas --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数会正常传递给命令行界面。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用桩接的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。