内容
<p align="center">
<a href="https://htmldrop.link"><img src=".github/logo.svg" width="140" alt="htmldrop logo"></a>
</p>
<h1 align="center">htmldrop</h1>
<p align="center"><b>为代理发布 HTML - 只需一次 API 调用，附带 MCP 服务器。</b></p>
<p align="center">
<a href="https://htmldrop.link"><img src="https://img.shields.io/badge/htmldrop.link-live-e8503a" alt="htmldrop.link"></a>
<a href="https://github.com/vin-spiegel/htmldrop/actions/workflows/ci.yml"><img src="https://github.com/vin-spiegel/htmldrop/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://www.npmjs.com/package/htmldrop-mcp"><img src="https://img.shields.io/npm/v/htmldrop-mcp" alt="npm"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
</p>
---
htmldrop 将任何 HTML 或 Markdown 工件转换为可分享的链接，瞬间完成。报告、仪表板、图表、演示文稿——任何代理（或人类）创建的内容。Markdown 被渲染成一个干净的阅读页面。不需要 git，不需要构建，不需要仪表板。
**立即试用：[htmldrop.link](https://htmldrop.link)** - 拖放 HTML 文件，粘贴 HTML 源代码，或向 API 发送 POST 请求。
## 工作原理
```bash
curl -X POST https://htmldrop.link/publish \
-H "Content-Type: application/json" \
-d '{"html":"<h1>Hello agents</h1>","title":"Demo"}'
```
```json
{
"url": "https://happy-otter-42.htmldrop.link",
"id": "...",
"subdomain": "happy-otter-42",
"expires_at": "2026-07-17T00:00:00.000Z"
}
```
每个链接都有自己的子域名、自动生成的 Open Graph 预览卡和 TTL - 共享的工件不会永远存在。
## 连接您的代理（MCP）
托管的 MCP 服务器位于 `https://htmldrop.link/mcp`（SSE）并公开一个工具：`publish_html`。
### Claude 代码
```bash
claude mcp add --transport sse htmldrop https://htmldrop.link/mcp
```
### Claude 桌面版
Claude 桌面版使用 stdio 进行通信，因此使用 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) 桥接到托管服务器。在 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"htmldrop": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://htmldrop.link/mcp"]
}
}
}
```
### 光标
光标直接连接到 SSE URL。在 `.cursor/mcp.json` 中：
```json
{
"mcpServers": {
"htmldrop": { "url": "https://htmldrop.link/mcp" }
}
}
```
### Codex CLI
在 `~/.codex/config.toml` 中：
```toml
[mcp_servers.htmldrop]
command = "npx"
args = ["-y", "mcp-remote", "https://htmldrop.link/mcp"]
```
### 自托管实例（npm，stdio）
运行您自己的 htmldrop？[`htmldrop-mcp`](https://www.npmjs.com/package/htmldrop-mcp) 包是一个本地 stdio MCP 服务器，它发布到**您的**存储和域名：
```json
{
"mcpServers": {
"htmldrop": {
"command": "npx",
"args": ["-y", "htmldrop-mcp"],
"env": {
"BASE_DOMAIN": "your-domain.example",
"CLOUDFLARE_R2_ENDPOINT": "...",
"CLOUDFLARE_R2_ACCESS_KEY_ID": "...",
"CLOUDFLARE_R2_SECRET_ACCESS_KEY": "...",
"CLOUDFLARE_R2_BUCKET_NAME": "..."
}
}
}
}
```
### `publish_html` 工具
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `html` | 字符串 | 要发布的 HTML 内容（或使用 `markdown` / `url`） |
| `markdown` | 字符串 | Markdown 内容 - 渲染成样式化的阅读页面 |
| `url` | 字符串 | 要获取和发布的远程 HTML 页面 |
| `title` | 字符串 | 元数据和社交卡的标题 |
| `ttl_days` | 数字 | 工件过期前的天数 |
| `password` | 字符串 | 可选的密码保护 |
| `owner_key` | 字符串 | 可选的密钥，用于更高的限制和更长的 TTL |
完整的代理文档位于 [AGENTS.md](AGENTS.md) 中，也在 [htmldrop.link/agents.md](https://htmldrop.link/agents.md) 上提供。
## REST API
| 端点 | 正文 | 备注 |
| --- | --- | --- |
| `POST /publish` | JSON `{ html \| markdown, title, ttl_days, password, url }` | 主要端点 |
| `POST /publish/raw` | 原始 `text/html` 或 `text/markdown` 正文 | 标题通过 `x-htmldrop-title` 头或 `?title=` |
| `POST /publish/from-url` | JSON `{ url, title, ttl_days, password }` | 获取并重新发布页面 |
在 `x-htmldrop-key` 头中传递所有者密钥，以获得更高的速率限制和更长的默认 TTL。（`x-pin-key` 仍然被接受以保持向后兼容。）
## 自托管
```bash
git clone https://github.com/vin-spiegel/htmldrop.git
cd htmldrop
pnpm install
cp .env.example .env # 默认设置可以直接使用
pnpm dev # http://localhost:3000
```
当未配置 Cloudflare R2 时，存储会回退到本地文件系统 - 无需数据库，可水平扩展。
### 环境变量
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `PORT` | `3000` | HTTP 端口 |
| `BASE_DOMAIN` | `localhost` | 工件子域名的基准域名 |
| `CLOUDFLARE_R2_*` | - | 可选的 R2 存储（端点，密钥，存储桶） |
| `ANON_TTL_DAYS` | `7` | 匿名发布的 TTL |
| `KEY_TTL_DAYS` | `30` | 密钥发布的 TTL |
| `MAX_HTML_SIZE_BYTES` | `26214400` | 上传上限（25 MB） |
| `RATE_LIMIT_ANON_PER_MINUTE` | `10` | 每分钟的 IP 速率限制 |
| `RATE_LIMIT_KEY_PER_MINUTE` | `60` | 每分钟的密钥速率限制 |
生产环境需要一个通配符 DNS 记录（`*.your-domain`）指向服务器，以便工件子域名可以解析。
### 部署到 Railway
```bash
railway login
railway init --name htmldrop
railway up
```
然后在 Railway 仪表板中设置 `BASE_DOMAIN` 和（可选）R2 变量，并附加您的域名及其通配符。
## 安全默认值
- 工件以 `X-Robots-Tag: noindex, nofollow, noarchive` 提供服务
- 每 IP 和每密钥速率限制
- 所有内容都通过 TTL 过期
- 可选的工件密码保护
有关漏洞和滥用报告，请参见 [SECURITY.md](SECURITY.md)。
## 开发
```bash
pnpm dev # 使用 tsx 运行
pnpm test # vitest
pnpm run build # tsc -> dist/
```
## 许可证
[MIT](LICENSE)
