feat(mcp): Add the @frontsail/qr-mcp stdio server

[korya]

Problem

An agent asked to make a QR code cannot produce the one our own site produces — it has to drive a browser or reach for a different library.

A different library means different defaults, different presets, and output that drifts from qr-code-gen.frontsail.app. PR #13 extracted the framework-free logic into @frontsail/qr-core so a second consumer could exist without forking it. This is that consumer.

Solution

Add packages/mcp — a stdio MCP server exposing two tools, generate_qr_code and create_share_link, sharing core's logic rather than reimplementing it.

{
  "mcpServers": {
    "qr-code-generator": {
      "command": "npx",
      "args": ["-y", "@frontsail/qr-mcp"]
    }
  }
}

generate_qr_code takes a content type and its fields plus the same customization options the web UI offers — colors including the transparent background sentinel, gradients, dot and corner styles, and a logo as a data URI or absolute path. It returns SVG text (280px), a base64 PNG (560px), or writes to an absolute output_path. create_share_link returns a link that reopens the design in the web editor, with logos excluded exactly as the web app excludes them.

The pipeline is a finding, not a preference

Rendering runs jsdom + @napi-rs/canvas + @resvg/resvg-js on a sanitized SVG. Two experiments on 2026-07-31 tried the alternatives, and what makes this worth spelling out is how they failed — almost never by throwing:

Approach	Failure
Library's own canvas/PNG path (node-canvas 2)	Emits a valid, scannable PNG with the logo silently missing
Library's own canvas/PNG path (napi canvas)	Emits a solid square
resvg on unsanitized SVG	Emits a solid square — resvg won't resolve url('#id')
No nodeCanvas at all, logo present	Hangs forever — the promise never settles, no error

Three of those four produce a plausible file rather than a failure. So nodeCanvas is always supplied, every render carries a hard timeout, and the tests assert on decoded pixels rather than on "a buffer came back".

The hang is the one that matters most for an MCP server: a tool call that never returns is strictly worse for an agent than one that errors, because there is nothing to report or retry. A test doctors the render to omit nodeCanvas and asserts it rejects — it takes 1.5 s of its 1.5 s timeout, which is the evidence the hang is real and the backstop works.

Parity is claimed precisely

• SVG without a logo is byte-identical to the web app's download. Guarded by tests/parity.test.ts against four SVGs captured from the live site through Playwright — the goldens are the browser's own files, not this package's output, so the test fails if the two ever diverge. The only tolerated difference is qr-code-styling's per-process instance counter in element ids, which has no rendered effect.
• PNGs and logo SVGs are the same design, not the same bytes. resvg is not Chromium, and the library re-encodes logo images through a canvas. Claiming byte-equality there would be a promise the package cannot keep.

This is also why sanitizing runs on the PNG path only: the url('#id') → url(#id) rewrite resvg needs changes bytes, and applying it to returned SVG would break the parity above.

Core is bundled, not depended on

@frontsail/qr-core sits in devDependencies on purpose. Core exports raw TypeScript with extensionless imports and pulls in UMD lz-string — neither loadable by plain Node — so vp pack inlines both into a single 31 kB ESM file. The published tarball is 2 files and 8.7 kB, with no reference to a private workspace package.

Verified by packing the tarball, installing it into a clean directory, and driving the linked qr-mcp binary over stdio with the SDK's own client: both tools answered, and the share link it produced decodes back to the original design.

Dependency weight and npx cold start

Package	Installed	Role
@napi-rs/canvas	25.9 MB	canvas for the library
jsdom	25.8 MB	DOM for the library
@modelcontextprotocol/sdk	23.9 MB	protocol + stdio transport
@resvg/resvg-js	3.4 MB	SVG → PNG
qr-code-styling	0.8 MB	the renderer
Combined	80 MB	first npx -y @frontsail/qr-mcp

80 MB is real, paid once per npx cache generation, and not meaningfully reducible here: jsdom is what makes the library run, the napi canvas is what stops the logo path hanging, and the SDK's own tree (express, hono, jose, ajv) is not ours to trim. Both native deps ship napi prebuilds for every major platform and run no install scripts — deliberately avoiding canvas/node-canvas, whose prebuild-install || node-gyp postinstall npm ≥ 11.16 is moving to block. The lockfile carries all platform variants, so CI on linux-x64 resolves without a rebuild.

No visual change — apps/web is untouched.

Other Changes

• The blueprint doc lands first, in its own commit, mirroring PR refactor(workspace): Split into apps/web and packages/core #13's shape.
• 62 new tests: the experiment matrix as pixel-level regressions (zero-alpha counts for transparency, logo-colored pixel counts to prove the logo rasterized), the SVG parity guard, schema and logo-path validation, and a stdio integration test driving the built artifact. Repo total is now 146 (37 core + 62 mcp + 47 e2e).
• AGENTS.md gains a packages/mcp section recording the invariants that are easy to unknowingly break — bundled core, the forbidden canvas path, sanitizer and timeout, and the real-PNG fixture requirement (resvg decodes node-canvas-2-encoded PNGs as black).
• Tool enums are derived from core's own option lists rather than retyped, so the MCP surface cannot drift from what the web app offers.
• Package name is tentative. @frontsail/qr-mcp is free on npm, but scope ownership is still unverifiable — npm whoami returns 401, the same blocker as PR refactor(workspace): Split into apps/web and packages/core #13's open question 2. Nothing publishes here, and the name is trivially changeable before a first release.

Related:

• refactor(workspace): Split into apps/web and packages/core #13

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
qr-code-generator	Ready	Preview	Jul 31, 2026 5:31pm