brewpage-mcp

BrewPage API——开源公共层

此仓库是 BrewPage 的开源公共层—— BrewPage 是一个专有的 HTML/KV/JSON/文件托管平台。 后端、前端和基础设施仍为闭源。

文档： https://kochetkov-ma.github.io/brewpage-openapi/ | API 参考： https://kochetkov-ma.github.io/brewpage-openapi/api-reference/

什么是 BrewPage

BrewPage 是一项免费即时托管服务，可用于托管 HTML 页面、Markdown 文档、多文件网站、AI 产物、JSON 文档、键值存储和二进制文件。 创建内容无需注册或 API 密钥。请使用返回的确切主 HTTPS link；发布内容可以使用 BrewPage 路径，也可以使用自己的内容主机。

主要特点：

• HTML 和 Markdown 页面——发布原始 HTML，或发布渲染为样式化 HTML 的 Markdown，大小上限为 5 MB，并即时获得短 URL。
• 多文件网站——上传 ZIP 压缩包或单个文件（最多 20 MB / 100 个文件），即可获得完整托管的静态网站。
• 键值存储——通过命名空间／存储 ID 访问 KV 键值对，每个存储最多 1,000 个键；可通过所有者令牌原地修改。
• JSON 文档——存储和检索任意 JSON，每个文档最多 1 MiB，每个命名空间最多 10,000 个文档。
• 文件托管——上传任意安全文件类型（图像、PDF、视频、音频、压缩包、代码），大小上限为 5 MB（视频为 20 MB），并支持内联预览。
• 可见性——REST 请求中省略 ?ns= 时会选择 public；MCP 请求中省略命名空间时会生成一个未公开列出的命名空间。未设置密码的公共内容可能符合展示在图库中的条件；能否被搜索到还取决于交付方式。自定义命名空间不会公开列出，除非受密码保护，否则任何拥有链接的人都可以读取。未公开列出、受保护或其他不符合条件的原生响应会带有 noindex；符合条件的公共 HTML、网站和文件可能允许被索引。
• 所有者令牌——每个发布响应都包含一个 ownerToken。使用它可原地更新内容（URL 保持不变）、删除内容或列出自己的资源。无需账户，也无需会话。
• TTL——默认 15 天，通常最长 30 天，通过 REST ttl 查询参数配置。特定所有者的上限和符合条件的自动延长可能会影响过期时间；请使用返回的 expiresAt。
• 访问——读取未受保护的内容和创建内容无需账户。读取受保护的内容需使用 X-Password；更新所有者内容、删除内容和获取限定范围的列表需使用 X-Owner-Token。速率限制取决于操作／可见性；请处理 429 和 Retry-After。

API 基础 URL 为 https://brewpage.app。brewdata.app 是一个重定向域名：每个路径都会返回 301 并跳转至 brewpage.app。

为什么这对大模型和 Agent 很重要

AI Agent 经常需要通过稳定的 URL，向用户或下游系统分享结构化输出——报告、产物、生成的 HTML、中间 JSON 状态。BrewPage 通过零配置的 REST API 提供此功能：调用一次 POST，返回一个 URL。无需 OAuth、S3 存储桶配置或基础设施。MCP 服务（brewpage-mcp）将 API 封装为 16 个类型化工具，任何兼容 MCP 的 Agent（Claude、Codex、Gemini、Cursor）都可以直接调用。

快速开始

发布 HTML 页面并获取可分享的链接：

curl -X POST 'https://brewpage.app/api/html?ns=public&format=html&ttl=15' \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyAgent/1.0" \
  -d '{"content": "<h1>Hello, world!</h1>"}'

响应：

{
  "id": "aBcDeFgHiJ",
  "namespace": "public",
  "link": "https://brewpage.app/public/aBcDeFgHiJ",
  "ownerLink": "https://brewpage.app/api/html/public/aBcDeFgHiJ",
  "ownerToken": "your-secret-token",
  "expiresAt": "2026-06-04T02:00:00Z",
  "sizeBytes": 22
}

在任意浏览器中打开 link 即可，无需其他步骤。

LLM 和 Agent 的用例

场景	API 调用
AI Agent 生成可分享的 HTML 报告，并需要一个稳定的 URL 返回给用户	POST /api/html -- 立即返回链接
GPT 工作流需要在不同对话轮次之间持久保存 JSON 状态，且不使用外部存储	POST /api/json?ns=myproject then GET /api/json/myproject/{id}
代码生成工具生成了可下载文件（PDF、压缩包、脚本），需要托管该文件	POST /api/files -- 文件以正确的 MIME 类型提供，并支持内嵌预览
Agent 发布了一个资源，之后还要对其进行完善，同时不使共享 URL 失效	PUT /api/html/{ns}/{id} with X-Owner-Token -- 替换内容，URL 保持不变
多步骤工作流需要从 ZIP 部署完整的静态网站（HTML + CSS + JS）	POST /api/sites with [email protected] -- 所有文件均可通过原样保留的相对链接访问

API 功能

资源	描述	限制
HTML 页面	原始 HTML 或 Markdown，可立即生成短 URL	5 MB，TTL 1--30d
键值存储	按命名空间 / 存储 ID 访问的命名键值对	每个存储 1,000 个键
JSON 文档	存储和检索任意 JSON，并支持按所有者范围列出	1 MiB，每个命名空间 10,000 个文档
文件	上传文件，自动检测 MIME 类型并支持内嵌预览	5 MB（视频 20 MB），每个命名空间 1,000 个文件
网站	通过 ZIP 或单个文件上传多文件 HTML 网站	总计 20 MB，100 个文件，每个文件 5 MB，TTL 1--30d

创建后会返回主链接和所有者令牌。请保留令牌以便管理，并按原样分享链接。密码保护不包含在内容发现中；仅公开命名空间并不能保证内容会被编入索引。TTL 和支持的输入因操作而异。

API 示例

发布 Markdown：

curl -X POST "https://brewpage.app/api/html?format=markdown" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyAgent/1.0" \
  -d '{"content": "# My Document\n\nHello **world**"}'

存储 JSON 文档：

curl -X POST https://brewpage.app/api/json \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyAgent/1.0" \
  -d '{"name": "config", "version": 1}'

上传网站（ZIP 压缩包）：

curl -X POST "https://brewpage.app/api/sites" \
  -H "User-Agent: MyAgent/1.0" \
  -F "[email protected];type=application/zip"

原位更新内容（稳定 URL）：

curl -X PUT "https://brewpage.app/api/html/public/aBcDeFgHiJ" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyAgent/1.0" \
  -H "X-Owner-Token: your-secret-token" \
  -d '{"content": "<h1>Updated content</h1>"}'

获取平台统计数据：

curl https://brewpage.app/api/stats

API 参考

• 交互式文档 -- kochetkov-ma.github.io/brewpage-openapi
• API 参考（Scalar） -- kochetkov-ma.github.io/brewpage-openapi/api-reference
• OpenAPI 规范（YAML） -- openapi/openapi.yaml
• OpenAPI 规范（JSON） -- openapi/openapi.json

后端生成的公开 JSON 契约具有模式权威性。YAML 由此确定性生成；Scalar 提供完全相同的 JSON 副本。有关导出来源的信息，请参阅 openapi/openapi.provenance.json。导入新快照前，请先修正后端生成流程；不要在 YAML 中编写模式。

端点

标签	描述
HTML	发布、获取、更新和删除 HTML/Markdown 页面
KV	键值存储 CRUD（获取、设置、列出和删除键）
JSON	JSON 文档 CRUD，并支持按所有者范围列出
文件	上传、下载、列出和删除文件
网站	上传多文件网站（ZIP 或文件）、查看信息、提供内容和删除
图库	浏览公开内容，支持搜索和分页
统计数据	全平台使用统计数据
短链接	为已发布内容生成 URL 短链接
SEO	Sitemap 和 robots.txt 端点
报告	针对已发布内容的滥用举报
命名空间	提供无冲突的命名空间建议

MCP 服务

brewpage-mcp 软件包提供了一个模型上下文协议服务器，包含 16 个工具，用于 AI 辅助内容发布和管理。下方列出了部分工具；完整列表和文档请参阅 mcp-server/README.md。

软件包发布使用 .github/workflows/release.yml，通过针对软件包配置的 npm Trusted Publisher/OIDC 发布到 kochetkov-ma/brewpage-openapi，工作流为 release.yml，且不使用环境。CI 无需 NPM_TOKEN、手动登录 npm 或轮换静态令牌。本地运行 npm whoami 无法验证 GitHub Actions 的 OIDC 身份验证。同一工作流会通过 GitHub OIDC 自动发布到官方 MCP registry（io.github.kochetkov-ma/brewpage-mcp）；无需本地 mcp-publisher 令牌。

若要从本地终端重试发布，请触发当前的 main 工作流：

gh workflow run release.yml --repo kochetkov-ma/brewpage-openapi --ref main

不支持重新运行使用令牌身份验证的历史标签工作流；请改用当前的 main。重试会检查匹配的版本标签和未更改的 MCP 源代码；若该版本已存在，则跳过发布。

工具	描述
publish_html	发布 HTML 或 Markdown 内容，可选设置密码、TTL、文件名和顶部工具栏
publish_file	从 URL 上传文件
publish_site	发布单页或多文件 HTML 网站
delete_resource	根据所有者令牌删除任意资源（HTML、KV、JSON、文件）
get_page	获取已发布的 HTML 页面及其内容
get_stats	获取平台范围的使用统计信息

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "brewpage": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Claude Code

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "brewpage": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

资源

资源	URL
在线平台	https://brewpage.app
大模型上下文文件	https://brewpage.app/llms.txt
完整大模型参考资料	https://brewpage.app/llms-full.txt
OpenAPI 规范（YAML）	openapi/openapi.yaml
MCP 服务	mcp-server/
npm 软件包	https://www.npmjs.com/package/brewpage-mcp
交互式 API 文档	https://kochetkov-ma.github.io/brewpage-openapi/
Claude 技能	https://github.com/kochetkov-ma/claude-brewcode/tree/main/skills/brewpage-publish
Brewcode 插件套件	https://github.com/kochetkov-ma/claude-brewcode
Brewcode 网站	https://brewcode.app
GitHub Action（将 CI 构件发布到 BrewPage）	https://github.com/kochetkov-ma/brewpage-action
BrewPage Cookbook（交互式示例）	https://github.com/kochetkov-ma/brewpage-cookbook
brewdoc CLI（面向 Agent 系统的文档转 Markdown 工具）	https://pypi.org/project/brewdoc/
brewdoc CLI 源代码	https://github.com/kochetkov-ma/brewdoc
Wiki	https://github.com/kochetkov-ma/brewpage-openapi/wiki
发布版本	https://github.com/kochetkov-ma/brewpage-openapi/releases

BrewPage 平台主页使用 schema.org/SoftwareApplication 结构化数据进行描述。

此处开源的内容

组件	描述
OpenAPI 3.1 规范	所有公开端点的完整 API 合约（YAML + JSON）
交互式文档	Astro + Scalar 文档网站（GitHub Pages）
MCP 服务	brewpage-mcp —— Claude Desktop/Code 集成（16 个工具）
Wiki	代码片段、速查表、技巧与窍门
发布说明	API 和公开工具的变更日志

专有内容

组件	描述
后端	Spring Boot + Kotlin REST API
前端	HTML/CSS/JS + Caddy 反向代理
基础设施	VPS 部署、CI/CD 流水线
端到端测试套件	Playwright + Testcontainers

项目结构

brewpage-openapi/
  openapi/
    openapi.json          # OpenAPI 3.1 spec (JSON)
    openapi.yaml          # OpenAPI 3.1 spec (YAML)
  docs/                   # Astro documentation site
    src/
      pages/              # Documentation pages
      components/         # Scalar API reference
  mcp-server/             # MCP server (brewpage-mcp)
    src/
      index.ts            # Server entry point
  .github/
    workflows/            # CI/CD (docs deploy, releases)
  README.md
  RELEASE-NOTES.md
  LICENSE

许可证

Apache 2.0 适用于本仓库的合约／文档层。独立打包的 MCP 服务 使用 MIT 许可证。托管后端、前端和基础设施仍为专有。SDK／CLI 模块规范属于提案；它们并不代表已有发布的软件包。