Blank Files MCP

Blank Files Website

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

要件

• PHP 8.2+
• Composer
• Node.js 18+（Vite フロントエンドのビルド用）

インストール

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

または、.test ドメインで Laravel Herd を使用します。

設定

変数	説明
CDN_URL	必須。 ダウンロード可能なファイルの URL を {CDN_URL}/files/{filename} として構成するためのベース URL です。デフォルト：https://raw.githubusercontent.com/filearchitect/blank-files/main（config/app.php で設定）。
CATALOG_URL	任意。カタログ JSON（files/files.json）の直接 URL です。最新の内容を取得するため、デフォルトは https://raw.githubusercontent.com/filearchitect/blank-files/main/files/files.json です。
CACHE_ENABLED	任意。true の場合、CDN から取得したファイル一覧をキャッシュします。TTL は CATALOG_TTL_MINUTES（デフォルトは 10）で設定します。config/cache.php と app/Services/FileService.php を参照してください。
CATALOG_TTL_MINUTES	任意。CACHE_ENABLED=true の場合に、リモートカタログをキャッシュする TTL（分）です。値を小さくすると新しい形式がより早く反映され、値を大きくすると CDN へのリクエストが減ります。
API_KEYS	任意。リクエストレート上限の高い API クライアント用の API キーをカンマ区切りで指定します（X-API-Key または Authorization: Bearer ... で使用）。
API_PUBLIC_RATE_LIMIT	任意。公開 API の 1 分あたりのリクエスト上限です（デフォルトは 30）。
API_KEY_RATE_LIMIT	任意。API キーを使用したリクエストの 1 分あたりの上限です（デフォルトは 300）。
API_USAGE_LOG_CHANNEL	任意。API 利用状況の分析ログ用チャンネルです（デフォルトは api_usage）。
OPENPANEL_CLIENT_ID	任意。設定すると OpenPanel のウェブ分析スクリプトが有効になります。
OPENPANEL_CLIENT_SECRET	任意。サーバー側の OpenPanel イベント用に予約されています（ブラウザーのスクリプトには公開されません）。

プロジェクト構成

パス	用途
app/Http/Controllers/FileController.php	Web：ホームページ、ファイル詳細ページ、ダウンロードプロキシ。
app/Http/Controllers/Api/FileController.php	API：すべてのファイルの一覧、種類別のファイル一覧。
app/Services/FileService.php	カタログ JSON（CATALOG_URL）を取得し、CDN_URL からファイル URL を生成します。
routes/web.php	Web ルート（ホーム、ファイル詳細、ダウンロード）。
routes/api.php	API v1 ルート。
resources/views/files/	ファイル一覧とファイル詳細の Blade ビュー。

デプロイ

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 を使用してください。

Web ルート

メソッド	パス	説明
GET	/	ホームページ：カテゴリ別のファイル一覧。Accept: application/json の場合は JSON を返します。スロットル：30/分。
GET	/upload-testing	アップロードテストを目的とした、バイナリファイルに特化したランディングページです。需要の高いファイル形式やカテゴリへのリンクを掲載しています。
GET	/files/{category}/{type}	SEO に適したファイル詳細ページ（例：/files/document-spreadsheet/xlsx）。制約：category、type は [A-Za-z0-9\-]+。
GET	/files/download/{category}/{type}	ダウンロードプロキシ：Content-Disposition: attachment を指定してファイルをストリーミングします（ファイル名は blank.{type} または blank.{type}.zip）。スロットル：60/分。

API ルート（プレフィックス api/v1）

メソッド	パス	レスポンス
GET	/api/v1/files	{ "files": [ ... ], "meta": { "version", "generated_at", "count" } }。
GET	/api/v1/files/{type}	同じスキーマで、拡張子によるフィルタリングが適用されます。
GET	/api/v1/files/{category}/{type}	見つかった場合は一致するエントリーがちょうど 1 件含まれる同じスキーマ、見つからない場合は 404。
GET	/api/v1/status	API のヘルス状態と、カタログの集計メトリクス（file_count、type_count、category_count）、および上流ソースの情報。

機械処理向けの注意事項

• 正式なファイルカタログのスキーマは、blank-files リポジトリで定義されています：files/files.json（キー files、{ type, url, category, package? } の配列）。
• ダウンロード URL：CDN から直接アクセスするには API の url フィールドを使用するか、予測可能なファイル名で同一オリジンからダウンロードするには 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) {
  // unchanged
}

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 ライセンスのもとでライセンスされています。