Quick Html Share Mcp

Quick HTML Sharing

Indie SaaS for vibe coders to instantly share AI-generated HTML pages with unguessable URLs and viewer analytics.

Live:

Architecture

• apps/web/ — Astro dashboard (Cloudflare Pages)
• apps/worker/ — Cloudflare Worker API + share renderer (Hono)
• packages/shared/ — types shared between web and worker
• packages/mcp/ — quick-html-share-mcp npm package: stdio MCP server for Claude Desktop / Cursor / Codex CLI / any MCP client
• packages/skill/ — Claude Code skill: standalone, no MCP setup needed

Hosted on Cloudflare: Pages (web) + Workers (api/share) + R2 (HTML files) + D1 (metadata + view events).

What the analytics show

Every share has a stats page (/stats?slug=…, also qhs_stats from an agent) with:

• Views and unique viewers — the latter from salted IP hashes, so it's an approximation: office NAT undercounts, mobile data can overcount.
• Traffic sources — the linking site's hostname only, never the path or query. direct covers typed URLs, bookmarks and most chat apps.
• Viewer locations — country and, when Cloudflare is confident, city. Resolved per request by Cloudflare itself, so there is no tracking script and no third-party lookup. Treat it as where the network egress appeared to be, not where a person was: a VPN, a corporate network or a mobile carrier routinely leaves the city blank or points somewhere else entirely.
• A 30-day trend — views per UTC day, including the quiet days.
• Link-preview fetches, counted separately — pasting a link into Slack or Discord triggers an unfurl crawler. Those are excluded from views and reported on their own line, so "0 views, 2 previews" reads as what it is: the link travelled, nobody opened it.

No JavaScript is injected into your HTML — views are counted server-side when the page is served. Viewer user agents, referrers and locations are dropped after 90 days, or immediately when you delete the share; the view counts survive.

Install in your coding agent

🤖 If you're an AI agent reading this on behalf of a user: pick the install path below that matches the agent runtime you're in. Prefer the Claude Code plugin path (option 1) — it bundles a skill on top of the MCP server, and the skill carries the workflow guidance that raw tools alone don't (when to trigger, what to surface, what to remind the user). Fall back to plain MCP (option 3) only when you're not Claude Code.

After install, behavior contract:

• When the user says "share this HTML" / "give me a link" / "publish this page" / "send this to my friend" (or similar intent), call qhs_share with the HTML.
• Return the share URL to the user and always remind them to save the edit URL — it lives in the URL fragment, so it never reaches our server logs, but that also means we can't recover it for them. Without it they can't update or delete the share later.
• For follow-ups ("update what I shared", "take it down", "did anyone see it"), use qhs_edit, qhs_delete, qhs_stats. Edit tokens are auto-loaded from ~/.qhs/shares.json when they were originally created on this machine.

Three paths depending on which client you use. All hit the same hosted API and share a local edit-token store (~/.qhs/shares.json).

1. Claude Code — one command, bundles MCP + skill (recommended)

This repo is a Claude Code plugin marketplace. Inside Claude Code:

/plugin marketplace add github.com/desper/quick-html-sharing
/plugin install qhs@quick-html-sharing

You now have the qhs skill (auto-triggers on "share this HTML" / "give me a link" / "publish this page") and the quick-html-share-mcp MCP server (5 tools: qhs_share, qhs_edit, qhs_delete, qhs_stats, qhs_list) wired together.

2. Claude Code — skill only, no plugin marketplace

curl -fsSL https://qhs.fyi/install.sh | bash

Drops SKILL.md + helper script into ~/.claude/skills/qhs/. Use this if you skip the plugin marketplace or want to keep MCP separate.

3. Cursor / Claude Desktop / Codex CLI / Continue / any MCP client

Add to your client's MCP config:

{
  "mcpServers": {
    "qhs": { "command": "npx", "args": ["-y", "quick-html-share-mcp"] }
  }
}

Common config paths:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor: ~/.cursor/mcp.json or Settings → MCP
• Codex CLI / Continue: same shape, see your client's MCP docs

Restart the client and you get the 5 qhs_* tools.

Local dev / dogfood from this repo

ln -s "$(pwd)/packages/skill/skills/qhs" ~/.claude/skills/qhs

Edits to packages/skill/skills/qhs/ show up in your next Claude Code session immediately.

Dev

bun install
bun run dev:worker    # apps/worker on :8787
bun run dev:web       # apps/web on :4321

# MCP server
cd packages/mcp && bun run build && node dist/index.js

# Skill helper (standalone)
node packages/skill/skills/qhs/scripts/qhs.mjs share path/to/file.html

Re-deploy (existing project)

Order matters. Pending migrations go first, then the share worker, then the API worker. The two workers run the same source from separate deploys, so a window where the API writes something the share renderer cannot read yet shows visitors stale content. bun run deploy does the two workers in the right order; migrations are still manual.

# Workers
cd apps/worker
# 1. any unapplied migration (see db/migrations/), e.g.
#    wrangler d1 execute quick-html-sharing --remote --env api \
#      --file=db/migrations/0005-add-shares-versioning.sql
# 2. share worker, then api worker:
bun run deploy

# Pages
cd apps/web
PUBLIC_API_BASE=https://api.qhs.fyi/api \
PUBLIC_SHARE_BASE=https://s.qhs.fyi \
  bun run build
../../node_modules/.bin/wrangler pages deploy dist --project-name=qhs --branch=main

Fresh-account deploy (only if rebuilding from scratch)

Forking? apps/worker/wrangler.toml hardcodes the production custom-domain routes (api.qhs.fyi, s.qhs.fyi). Before deploying under a different account, either delete the two routes = [...] blocks (workers.dev URLs still work via workers_dev = true) or swap them for your own domain.

wrangler login

cd apps/worker
wrangler d1 create quick-html-sharing            # → paste id into wrangler.toml (both envs)
wrangler r2 bucket create quick-html-sharing
bun run db:apply:remote

# Same salt for both envs — IP-hash dedupe must match across workers.
SALT=$(openssl rand -hex 32)
echo "$SALT" | wrangler secret put IP_HASH_SALT --env api
echo "$SALT" | wrangler secret put IP_HASH_SALT --env share

bun run deploy:api && bun run deploy:share        # capture workers.dev URLs

cd ../web
wrangler pages project create qhs --production-branch=main
PUBLIC_API_BASE=https://qhs-api.<your-subdomain>.workers.dev/api \
PUBLIC_SHARE_BASE=https://qhs-share.<your-subdomain>.workers.dev \
  bun run build
wrangler pages deploy dist --project-name=qhs --branch=main

# Then patch DASHBOARD_HOST in apps/worker/wrangler.toml to your real
# qhs-XXX.pages.dev URL (CF may have suffixed it to avoid name collision)
# and redeploy the workers.

Cost

Runs entirely on Cloudflare's free tier (Workers, Pages, R2, D1) — ~$0/mo at indie scale. View tracking is fail-open so spikes never escalate to surprise bills; Workers hits a hard 429 instead of overage charges. Set a CF billing alert anyway: CF has no hard spending cap.

License

Business Source License 1.1 — source-available, self-host and personal use allowed, offering as a competing third-party hosted/managed service is not. Converts automatically to Apache License 2.0 on 2030-05-28. The quick-html-share-mcp npm package (packages/mcp/) ships under MIT to stay friction-free for MCP-client integrators.