qrpaint
A QR code that is also a picture: a lighthouse at sunset, a
café awning, your own photograph — with a scannable code
painted into it. qrpaint is a thin forwarding client for
the hosted QRX service. It serves nine tools locally and
passes every call, unchanged, to the service, which paints
the picture, checks that it still scans, and hands back a
code with its own short link.
Because the painting happens on the hosted service, this
package holds no rendering logic of its own. What it does
hold is the contract: the exact tool list and schemas from
the service's public server card, the session handshake
each call travels over, and the rule that nothing is ever
sent until an API key is present.
Configuration
QRX_API_KEY (required for tool calls) — your QRX API
key, sent to the hosted endpoint on every request as
Authorization: Bearer <key>. Without it, the server
still starts and lists its tools, but every call fails
with QRX_API_KEY is not set and no request is made.QRX_MCP_URL (optional) — the hosted MCP endpoint.
Defaults to https://qrx.codes/mcp.
Tools
generate_qr_code — start a new art code from a
prompt (what the picture should show) and a
destination link, with an optional style from
list_styles. Answers at once with the code's id while
the picture is painted.generate_qr_code_from_image — weave a code into a
picture you already have, passed once as an attached
image file, a public imageUrl, or imageBase64,
plus the destination.vary_qr_code — a new code based on an existing code's
id, with a change to its picture ("make it night
time"). The original is untouched and the new code opens
the same destination.get_qr_code — a code's status, finished image and
short link by id; wait (0–25 seconds, default 25)
lets it hold for a code that is still being painted.list_qr_codes — your codes, newest first, paged with
limit (1–100, default 20) and cursor.change_qr_code_destination — retarget an existing
link code to a new destination; printed copies follow
at once.get_account — the connected account's plan and how
much of today's code allowance remains.get_profile — which QRX account is connected.list_styles — the looks you can pass as style to
generate_qr_code.
A typical flow is generate_qr_code (or
generate_qr_code_from_image), then get_qr_code with
the returned id until its status is succeeded — usually
under a minute. Codes count against your QRX allowance;
get_account shows what is left.
How forwarding works
Each tool call opens a fresh session with the hosted
endpoint: an initialize request (protocol version
2025-03-26), the returned session id carried into a
notifications/initialized note, then the tools/call
request with your arguments exactly as given. Responses
arrive as plain JSON or as server-sent events; both are
read. The remote result comes back as JSON text. A remote
error surfaces with the remote message, a non-2xx reply
fails with qrx error: HTTP <status>, and an unreachable
endpoint fails with qrx unreachable. Calls are never
retried — a retry could paint (and charge) a second code.
The handshake is a reconstruction of the standard
Streamable HTTP session flow; the endpoint, the Bearer
auth and the missing-key behaviour are the original
package's documented design.
There is no local argument validation beyond the
missing-key rule: the schemas above are served verbatim
for your MCP client to validate against, and the service
itself is the authority on every call.
CLI
Each tool is a subcommand taking one JSON argument string:
Output is the remote result as JSON text. Exit codes: 0
on success, 1 on an error result (including a
missing-key, remote or upstream failure), 2 on a usage
error.
MCP server
MCP client config (provide the key through the client's
environment):
Docker
Development
License
MIT — Copyright (c) 2026 Rene Turcios
