Beecargo

Beecargo MCP

Beecargo のファイルホスティング API 用 Model Context Protocol サーバーです。

ポータブルなマーケットプレイス向けパッケージ（Agent Plugins 1.0 + Cursor マニフェスト）は ../agent-plugin にあります。

最短手順（エージェント）

人間がダッシュボードにログインすることなく、永続的な共有リンクを公開します。

1. ヘッダーなしでホスト型 MCP を追加します：https://mcp.beecargo.net/mcp（すべてのツールを利用可能。詳細は examples/cursor-http.mcp.json を参照）。/mcp で認証が必要な場合は、初期登録専用ツールを利用できる https://mcp.beecargo.net/mcp/guest を使います。
2. beecargo_register_agent を呼び出します → 短い PoW を解き、初期登録用の bc_* を返します（10GB／100rpm。セッションでこのキーが引き継がれます）。
3. 公開 HTTPS url を指定して beecargo_upload を呼び出します → https://beecargo.net/d/{shortId} を引き渡します（常に完全な共有 URL を使用します）。複数ファイルを引き渡す場合：最初のファイルでは openShare: true を指定し、後続のアップロードでは shareShortId を指定します（同じリンクを使用し、ロック解除は 1 回だけです）。
4. 任意：fileId または Shipment の shortId を指定し、protect: true（と handoffMessage）を設定して beecargo_update_share_settings を呼び出すと、非公開チャネルで unlockCode と handoffUrl（/h/…）を返します。

本番環境のエージェント向け（同時ストレージ 100GB 込み／1000rpm／高いリモート数／時）：ダッシュボードの POST /api-keys/agent（Pro が必要）またはオペレーターの POST /agent/api-keys で Pro ティアのキーを発行します。

一時的なアップロードでは登録を省略できます。beecargo_upload は匿名でも動作します（制限がより厳しくなります。deletionToken を保存してください）。

ツール

ツール	認証	説明
beecargo_register_agent	なし	ブートストラップ用の bc_* を自己発行します（PoW ＋レート制限あり）
beecargo_upload	任意	URL、小容量の base64、またはローカルパス（stdio）でアップロードします。拡張可能な複数ファイル共有には openShare ／ shareShortId を使用します
beecargo_upload_status	任意	非同期 URL アップロードジョブの状態をポーリングします
beecargo_create_checkout	なし	Premium の Stripe チェックアウトを発行します（推奨：2 日間のトライアル後、週払い）
beecargo_purchase_checkout	任意	価格設定された共有（shortId ／ fileId ／ bundleId）用の購入リンクを発行します
beecargo_purchase_claim	なし	支払い後、sessionId から beecargo_get_download_url 用の purchaseToken を取得します
beecargo_claim_file	API キー	claimToken を使って匿名アップロードを取得します
beecargo_search_tools	なし	ツールをキーワード検索します
beecargo_update_share_settings	API キー	公開範囲、priceCents ／ currency、直接共有、保持期間、protect ／ handoffMessage（fileId または shortId）を設定します
beecargo_connect	ダッシュボードキー ／ OAuth	販売者の Stripe Connect（action: status | onboard | login）
beecargo_folders	API キー	フォルダーを作成または一覧表示します（action: create | list）
beecargo_get_download_url	なし	署名付きダウンロード URL（必要に応じて unlockCode ／ unlockToken ／ handoffToken ／ purchaseToken）
beecargo_file_info	任意	ショートコードでメタデータを取得します（unlockRequired）
beecargo_list_files	必須	所有ファイルを一覧表示します（includeFolders。パイプラインマニフェストには任意で runId を指定）
beecargo_delete_file	キーまたは削除トークン	ファイルを削除します

高度な機能

ツール	認証	説明
beecargo_create_upload_delegation	API key	bc_*を保持してはならないワーカー向けに、有効期間の短いuploadUrlとdelegationTokenを発行します。通常のエージェントによるアップロードにはbeecargo_uploadを推奨します。

詳しいガイド：アップロード、アップロード状況、実行アーティファクト、アップロード委任、フォルダー、共有設定、販売者への支払い、価格付き共有の購入。

Stdio（ローカル）

cd apps/mcp && pnpm build && pnpm start

任意：環境変数にBEECARGO_API_KEY=bc_…を設定します。beecargo_register_agentの実行後、stdioセッションは新しいキーを自動的に引き継ぎます。

examples/cursor-stdio.mcp.jsonを参照してください。

HTTP（ホスト型）

https://mcp.beecargo.net/mcp（認証済みの場合、すべてのツールを利用可能）。ゲスト向けの初期接続先：https://mcp.beecargo.net/mcp/guest。詳細はexamples/cursor-http.mcp.jsonを参照してください。

既存のキーを使用する場合：examples/cursor-http-with-key.mcp.json。

環境変数については.env.exampleを参照してください。主な項目：

• BEECARGO_API_URL：デフォルトはhttps://api.beecargo.net
• BEECARGO_API_FETCH_TIMEOUT_MS：大きな同期リモートの場合は値を大きくしてください（デフォルトの目安：300000）
• BEECARGO_MCP_REQUIRE_AUTH：trueに設定すると、/mcpでトランスポートのベアラートークンまたはbc_*が必須になります（デフォルト：初期接続は認証不要、レート制限あり）
• BEECARGO_MCP_BEARER_TOKEN：REQUIRE_AUTH=trueの場合に使用する、任意の共有トランスポートシークレット
• BEECARGO_MERCHANT_OAUTH_ENABLED：OAuthリソースメタデータを公開し、Connect with Beecargoを有効にします（APIとMCPの両方で一致するINTERNAL_API_KEYが必要です）

公式MCPレジストリ

server.jsonは、io.github.Beecargo/mcpの公式MCPレジストリマニフェストです（スキーマ2025-12-11）。ホスト型リモートのURLはhttps://mcp.beecargo.net/mcpです。検出用ファイルのコピーは、このホストとhttps://beecargo.netの`/.well-known/mcp/server.json`にもあります。

このファイルがあるからといって、サーバーがすでにレジストリに掲載されているわけではありません。

CLI（ローカルスクリプト）

専用パッケージ@beecargo/cliを使用します。

npx --yes github:Beecargo/cli upload ./artifact.zip --json
npx --yes github:Beecargo/cli remote https://example.com/file.bin --async --json
npx --yes github:Beecargo/cli share FILE_ID --price-cents 500 --key YOUR_BC_KEY
npx --yes github:Beecargo/cli download FILE_ID ./out.bin --purchase-token TOKEN

モノレポから実行する場合：pnpm cli upload ./artifact.zip。公開フラグ（--ttl、--protect、…）はMCPのbeecargo_uploadと同じです。share --price-centsとdownload --purchase-tokenは、MCPのshare-settingsとretrieveに対応します。

pnpm smoke:http   # MCP transport (no API)
BEECARGO_API_URL=http://localhost:3001 pnpm smoke:api   # live upload against API

lomi MCPとの対応関係

lomi	Beecargo
OpenAPIで生成されたツール	手書きのファイルツール（対象範囲を縮小）
lomi_search_tools	beecargo_search_tools
ヘッダーなしのHTTP接続	同じ（デフォルト）。BEECARGO_MCP_REQUIRE_AUTHは任意
x-lomi-api-key + OAuth	x-beecargo-api-key / Bearer bc_* + 匿名
GET/POST/DELETE /mcp	同じ
/health、/ready	同じ
RESTでの再試行 + タイムアウト	BEECARGO_API_FETCH_*環境変数
ツールの結果	{ ok, status, body } + 共有リンクのヒント

公開

スコープは @beecargo です。初回の公開は --otp を使って手動で行います。その後、npm パッケージで Trusted Publisher を GitHub の Beecargo/mcp ワークフロー publish.yml に設定します。次に、package.json のパッチバージョンを上げて main にプッシュします。

pnpm typecheck && pnpm publish --access public --otp=XXXXXX