Blankfiles Website

🚀 空白ファイルウェブサイト

blankfiles.com を動作させるLaravelアプリケーションです。種類とカテゴリー別に最小限の有効な空白ファイルを閲覧し、ダウンロードできます。ファイルデータとアセットは、設定可能なCDNを介して filearchitect/blank-files リポジトリから提供されます。

🚀 クイックスタート

このアプリケーションは、Laravelを使用して構築されており、PHP 8.2以上、Composer、Node.js 18以上が必要です。以下の手順でインストールとセットアップを行います。

✨ 主な機能

• 種類とカテゴリー別に空白ファイルを閲覧し、ダウンロードできます。
• ファイルデータとアセットは、設定可能なCDNを介して提供されます。
• APIを介してファイルの一覧を取得できます。
• ダウンロードプロキシを介してファイルをダウンロードできます。

📦 インストール

git clone https://github.com/filearchitect/blankfiles-website.git
cd blankfiles-website
composer install
cp .env.example .env
php artisan key:generate

.env ファイルで CDN_URL を設定します（設定 を参照）。その後、フロントエンドをビルドしてアプリを起動します。

npm install && npm run build
php artisan serve

または、Laravel Herd を使用して .test ドメインで起動することもできます。

📚 ドキュメント

設定

プロジェクト構造

デプロイ

main ブランチにプッシュすると、GitHub Actionsが以下の処理を行います。

1. npm ci と npm run build でフロントエンド（Vite）をビルドします。
2. public/build/ をForgeサーバーにSCPで転送します。
3. Laravel Forgeのデプロイをトリガーします。
4. サーバーで php artisan optimize:clear を実行します。

必要なリポジトリシークレット:

• FORGE_SSH_HOST — サーバーのSSHホスト。
• FORGE_SSH_USER — SSHユーザー（例: forge）。
• SSH_PRIVATE_KEY — SCP/SSH用の秘密鍵。
• FORGE_SERVER_ID — ForgeサーバーID。
• FORGE_SITE_ID — ForgeサイトID。
• FORGE_API_KEY — Forgeのデプロイトークン。

詳細は .github/workflows/deploy.yml を参照してください。

開発者とボット向け情報

ベースURL

本番環境: https://blankfiles.com。HTMLとJSONが利用可能です。必要に応じて Accept: application/json を使用してください。

ウェブルート

APIルート（接頭辞 api/v1）

機械可読なメモ

• 正規のファイルカタログスキーマは blank-files リポジトリで定義されています: files/files.json（キー files、{ type, url, category, package? } の配列）。
• ダウンロードURL: APIの url フィールドを使用して直接CDNにアクセスするか、GET /files/download/{category}/{type} を使用して予測可能なファイル名で同一オリジンのダウンロードを行います。
• APIレスポンスとサイトマップでは条件付きリクエストがサポートされています（ETag, Last-Modified）。
• レート制限: パブリックIPベースの制限とオプションのAPIキー制限（X-API-Key）があります。
• APIの使用状況分析は storage/logs/api-usage-*.log（設定可能なチャネル）にログ記録されます。
• 互換性ポリシー: APIポリシー。
• 成長ページのウェブランディング分析は storage/logs/web-traffic-*.log にログ記録されます。

クライアントスニペット

curl -sS "https://blankfiles.com/api/v1/files/document-spreadsheet/xlsx" \
  -H "Accept: application/json" \
  -H "X-API-Key: $BLANKFILES_API_KEY"

const res = await fetch("https://blankfiles.com/api/v1/files", {
  headers: { "Accept": "application/json", "If-None-Match": etag }
});
if (res.status === 304) {
  // 変更なし
}

import requests
r = requests.get("https://blankfiles.com/api/v1/status", timeout=20)
r.raise_for_status()
print(r.json())

互換性ポリシー

• URLのバージョニングは /api/v1/* の下で安定しています。
• 破壊的な変更には新しいメジャーAPIパスバージョンが必要です。
• 非推奨のエンドポイントは削除前に少なくとも90日間保持されます。
• 新しいフィールドが追加されることがあります。クライアントは未知のフィールドを無視する必要があります。

関連リポジトリ

• filearchitect/blank-files — ファイルリストと空白ファイルアセットの信頼できるソース。

MCPサーバー（エージェントマーケットプレイス/レジストリ用）

このリポジトリには、Blank Filesをツール呼び出しとして公開する最小限のMCPサーバーが含まれています。

• スクリプト: scripts/mcp/blankfiles-mcp.mjs
• 実行: npm run mcp:server
• オプションの環境変数: BLANKFILES_BASE_URL（デフォルト: https://blankfiles.com）

利用可能なMCPツール:

• list_blank_files — ファイルを一覧表示し、オプションでフィルターを指定できます（category, type, limit）
• files_by_type — 拡張子でエントリを一覧表示します
• file_by_category_type — カテゴリと拡張子で一意に検索します

ローカルMCPクライアントの設定例:

{
  "mcpServers": {
    "blankfiles": {
      "command": "node",
      "args": ["/absolute/path/to/blankfiles-website/scripts/mcp/blankfiles-mcp.mjs"],
      "env": {
        "BLANKFILES_BASE_URL": "https://blankfiles.com"
      }
    }
  }
}

レジストリ提出ヘルパー:

• テンプレートメタデータ: scripts/mcp/registry/server.json.template
• 公開チェックリスト: scripts/mcp/registry/PUBLISHING.md

公開されたパッケージワークスペース:

• packages/blankfiles-mcp（@filearchitect/blankfiles-mcp として公開）

OpenClawスキル（ClawHubの検索可能性）

このリポジトリには、OpenClaw対応のスキルバンドルが含まれています。

• スキルパス: skills/blankfiles
• スキルエントリ: skills/blankfiles/SKILL.md
• 公開ガイド: skills/blankfiles/references/publish.md

典型的な公開フロー:

npm i -g clawhub
clawhub login
clawhub publish ./skills/blankfiles \
  --slug blankfiles \
  --name "Blank Files Gateway" \
  --version 1.0.0 \
  --changelog "Initial release" \
  --tags latest

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。