quick-html-share-mcp

快速分享 HTML

面向氛围编程者的独立 SaaS，可即时分享 AI 生成的 HTML 页面，提供难以猜测的 URL 和访客分析。

在线体验：

入口	URL
控制面板（粘贴 HTML，获取 URL）	https://qhs.fyi
API Worker	https://api.qhs.fyi
分享 Worker	https://s.qhs.fyi/``

架构

• apps/web/ — Astro 控制面板（Cloudflare Pages）
• apps/worker/ — Cloudflare Worker API + 分享渲染器（Hono）
• packages/shared/ — Web 和 Worker 共享的类型
• packages/mcp/ — quick-html-share-mcp npm 包：面向 Claude Desktop / Cursor / Codex CLI / 任意 MCP 客户端的 stdio MCP 服务
• packages/skill/ — Claude Code 技能：独立使用，无需配置 MCP

托管于 Cloudflare：Pages（Web）+ Workers（API/分享）+ R2（HTML 文件）+ D1（元数据 + 访问事件）。

分析数据展示内容

每个分享都有一个统计页面（/stats?slug=…，Agent 也可使用 qhs_stats），包含：

• 访问量和独立访客数——后者根据加盐 IP 哈希估算，因此只是近似值：办公室 NAT 会导致计数偏低，移动数据网络则可能导致计数偏高。
• 流量来源——只记录链接所在网站的主机名，不记录路径或查询参数。direct 包括手动输入的 URL、书签和大多数聊天应用。
• 访客位置——国家，以及 Cloudflare 能够准确判断时的城市。由 Cloudflare 在处理每个请求时解析，因此无需跟踪脚本或第三方查询。请将其视为网络出口的位置，而非访客所在位置：VPN、企业网络或移动运营商常常会导致城市信息为空，或显示完全不同的位置。
• 30 天趋势——按 UTC 日期统计的访问量，包括没有访问的日期。
• 单独统计链接预览抓取——将链接粘贴到 Slack 或 Discord 会触发预览抓取程序。这类访问不会计入访问量，而是单独显示，因此“0 次访问，2 次预览”如实表示：链接已被分享，但没人打开它。

不会向你的 HTML 注入 JavaScript——页面提供时会在服务器端统计访问量。访客的用户代理、来源和位置信息会在 90 天后删除，或在你删除分享时立即删除；访问量统计会保留。

在编码 Agent 中安装

🤖 **如果你是代表用户阅读本文的 AI Agent：**请根据当前 Agent 运行环境，选择下方对应的安装方式。优先选择 Claude Code 插件方式（选项 1）——它在 MCP 服务基础上捆绑了技能，而该技能提供了原始工具本身不具备的工作流指引（何时触发、展示哪些内容、需要提醒用户什么）。只有在不使用 Claude Code 时，才退而选择纯 MCP（选项 3）。

安装后的行为约定：

• 当用户说“分享这个 HTML”／“给我一个链接”／“发布这个页面”／“把这个发给朋友”（或表达类似意图）时，使用 HTML 调用 qhs_share。
• 将分享 URL 返回给用户，并始终提醒他们保存编辑 URL——它位于 URL 片段中，不会进入我们的服务器日志，但这也意味着我们无法帮他们找回。没有它，他们之后就无法更新或删除分享。
• 对于后续请求（“更新我分享的内容”“撤下它”“有人看过吗”），使用 qhs_edit、qhs_delete、qhs_stats。如果编辑令牌最初是在当前机器上创建的，它们会从 ~/.qhs/shares.json 自动加载。

根据使用的客户端，有三种方式。它们都调用同一个托管 API，并共用本地编辑令牌存储（~/.qhs/shares.json）。

1. Claude Code — 一条命令，捆绑 MCP + 技能（推荐）

本仓库是一个 Claude Code 插件市场。在 Claude Code 中：

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

现在你已获得 qhs 技能（会在“分享这个 HTML”／“给我一个链接”／“发布这个页面”时自动触发），以及接入完成的 quick-html-share-mcp MCP 服务（含 5 个工具：qhs_share、qhs_edit、qhs_delete、qhs_stats、qhs_list）。

2. Claude Code — 仅使用 skill，不使用插件市场

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

将 SKILL.md 和辅助脚本放入 ~/.claude/skills/qhs/。如果你不使用插件市场，或想将 MCP 单独管理，请使用此方式。

3. Cursor / Claude Desktop / Codex CLI / Continue / 任意 MCP 客户端

添加到客户端的 MCP 配置中：

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

常见配置路径：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• Cursor：~/.cursor/mcp.json 或 Settings → MCP
• Codex CLI / Continue：配置格式相同，请参阅客户端的 MCP 文档

重启客户端后，即可使用 5 个 qhs_* 工具。

本地开发 / 在此仓库中试用

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

对 packages/skill/skills/qhs/ 的修改会立即在下一次 Claude Code 会话中生效。

开发

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

重新部署（现有项目）

顺序很重要。 先运行待处理的迁移，然后部署分享 worker，最后部署 API worker。这两个 worker 通过分别部署运行相同的源代码，因此，如果 API 写入了分享渲染器尚无法读取的内容，就会有一段时间向访客显示过时内容。bun run deploy 会按正确顺序部署这两个 worker；迁移仍需手动运行。

# 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

全新账户部署（仅在从头重建时）

准备 Fork？ apps/worker/wrangler.toml 中硬编码了生产环境的自定义域名路由（api.qhs.fyi、s.qhs.fyi）。在其他账户下部署前，请删除两个 routes = [...] 代码块（通过 workers_dev = true 仍可使用 workers.dev URL），或将它们替换为你自己的域名。

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.

费用

完全运行在 Cloudflare 的免费套餐上（Workers、Pages、R2、D1）——独立开发者规模约为 $0/月。查看次数统计采用故障开放策略，因此流量激增不会导致账单意外飙升；Workers 会直接返回 429，而不会产生超额费用。仍建议设置 CF 账单提醒：CF 没有硬性支出上限。

许可证

Business Source License 1.1 — 源码可见，允许自托管和个人使用，但不得将其作为有竞争关系的第三方托管/管理服务提供。将于 2030-05-28 自动转换为 Apache License 2.0。quick-html-share-mcp npm 包（packages/mcp/）采用 MIT 许可证，以便 MCP 客户端集成方轻松使用。