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 をそのまま公開するか、Markdown をスタイル付き HTML に変換して公開できます。最大 5 MB で、すぐに短縮 URL が生成されます。
• 複数ファイルのサイト -- ZIP アーカイブまたは個別ファイル（最大 20 MB／100 ファイル）をアップロードし、完全に配信される静的サイトを取得できます。
• キー・バリュー・ストア -- 名前空間／ストア ID でアドレス指定される KV ペアです。1 ストアあたり最大 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 はリダイレクト用ドメインで、すべてのパスが brewpage.app に 301 リダイレクトされます。

LLM とエージェントにとっての重要性

AI エージェントは、レポート、アーティファクト、生成した HTML、中間の JSON 状態などの構造化された出力を、安定した URL を介してユーザーや下流システムと共有する必要がよくあります。BrewPage は、セットアップ不要の REST API でこれを実現します。POST を 1 回呼び出すだけで、URL が返されます。OAuth、S3 バケットの設定、インフラストラクチャは不要です。MCP サーバー（brewpage-mcp）は、API を 16 個の型付きツールにラップしており、MCP 対応のエージェント（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 とエージェントのユースケース

シナリオ	API 呼び出し
AI エージェントが共有可能な HTML レポートを生成し、ユーザーに返すための安定した URL を必要とする	POST /api/html -- リンクを即座に返します
GPT パイプラインが、外部ストレージを使わずに会話ターン間で JSON 状態を保持する必要がある	POST /api/json?ns=myproject の後に GET /api/json/myproject/{id}
コード生成ツールがダウンロード可能なファイル（PDF、アーカイブ、スクリプト）を生成し、ホスティングする必要がある	POST /api/files -- 適切な MIME タイプでファイルを配信し、インラインプレビューを表示します
エージェントがアーティファクトを公開し、共有 URL を無効にせずに後から改良する	X-Owner-Token を指定して PUT /api/html/{ns}/{id} -- コンテンツを置き換え、URL は変更しません
マルチステップパイプラインが ZIP から完全な静的サイト（HTML + CSS + JS）をデプロイする	[email protected] を指定して POST /api/sites -- すべてのファイルを相対リンクを維持したまま配信します

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	サイトマップと robots.txt のエンドポイント
レポート	公開コンテンツに関する不正利用の報告
名前空間	競合しない名前空間の候補

MCP サーバー

brewpage-mcp パッケージは、AI を活用したコンテンツの公開と管理を行う 16 個のツールを備えた Model Context Protocol サーバーを提供します。以下に一部のツールを掲載します。完全な一覧とドキュメントについては、mcp-server/README.md をご覧ください。

パッケージのリリースでは、kochetkov-ma/brewpage-openapi を対象としたパッケージスコープの npm Trusted Publisher/OIDC を、環境を指定せずに release.yml ワークフローの .github/workflows/release.yml で使用します。CI では NPM_TOKEN、npm への手動ログイン、静的トークンのローテーションは不要です。ローカルでの npm whoami では、GitHub Actions の OIDC 認証を検証できません。公式 MCP レジストリ（io.github.kochetkov-ma/brewpage-mcp）への公開は、同じワークフロー内で GitHub OIDC により自動的に行われるため、ローカルの mcp-publisher トークンは不要です。

ローカルターミナルから公開を再試行するには、現在の main ワークフローをディスパッチします。

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

トークン認証を使用していた過去のタグのワークフローを再実行することはサポートされていません。代わりに現在の main を使用してください。再試行では、対応するバージョンタグと MCP ソースに変更がないことを確認し、そのバージョンがすでに存在する場合は公開をスキップします。

ツール	説明
publish_html	オプションのパスワード、TTL、ファイル名、上部ツールバーを指定して HTML または Markdown コンテンツを公開します
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
LLM コンテキストファイル	https://brewpage.app/llms.txt
LLM 完全リファレンス	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（エージェントシステム向けのドキュメントから 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 パイプライン
E2E テストスイート	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 モジュールの仕様は提案であり、リリース済みのパッケージを定めるものではありません。