# quick-html-share-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/desper/quick-html-sharing  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/quick-html-share-mcp

## Description
Share AI-generated HTML from your coding agent. Unguessable URL + viewer analytics.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation & README

# Quick HTML Sharing

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

**Live:**

| Surface | URL |
|---------|-----|
| Dashboard (paste HTML, get URL) | https://qhs.fyi |
| API worker | https://api.qhs.fyi |
| Share worker | https://s.qhs.fyi/`<slug>` |

## 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

```bash
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:

```json
{
  "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

```bash
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

```bash
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.

```bash
# 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.

```bash
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](https://github.com/desper/quick-html-sharing/blob/HEAD/LICENSE) — 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.