Blank Files MCP

Blank Files Website

Laravel application that powers blankfiles.com. Browse and download minimal valid blank files by type and category. File data and assets are served from the filearchitect/blank-files repository via a configurable CDN.

Requirements

• PHP 8.2+
• Composer
• Node.js 18+ (for Vite frontend build)

Installation

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

Set CDN_URL in .env (see Configuration). Then build the frontend and run the app:

npm install && npm run build
php artisan serve

Or use Laravel Herd with a .test domain.

Configuration

Variable	Description
CDN_URL	Required. Base URL used to construct downloadable file URLs as {CDN_URL}/files/{filename}. Default: https://raw.githubusercontent.com/filearchitect/blank-files/main (set in config/app.php).
CATALOG_URL	Optional. Direct URL for the catalog JSON (files/files.json). Default is https://raw.githubusercontent.com/filearchitect/blank-files/main/files/files.json for freshness.
CACHE_ENABLED	Optional. When true, the file list from the CDN is cached. TTL is controlled by CATALOG_TTL_MINUTES (default 10). See config/cache.php and app/Services/FileService.php.
CATALOG_TTL_MINUTES	Optional. Cache TTL in minutes for the remote catalog when CACHE_ENABLED=true. Lower values reflect new formats sooner; higher values reduce CDN fetches.
API_KEYS	Optional. Comma-separated API keys for higher-rate API clients (used by X-API-Key or Authorization: Bearer ...).
API_PUBLIC_RATE_LIMIT	Optional. Public API requests/minute limit (default 30).
API_KEY_RATE_LIMIT	Optional. API-key requests/minute limit (default 300).
API_USAGE_LOG_CHANNEL	Optional. Logging channel for API usage analytics (default api_usage).
OPENPANEL_CLIENT_ID	Optional. Enables OpenPanel web analytics script when set.
OPENPANEL_CLIENT_SECRET	Optional. Reserved for server-side OpenPanel events (not exposed to browser script).

Project structure

Path	Purpose
app/Http/Controllers/FileController.php	Web: homepage, file detail page, download proxy.
app/Http/Controllers/Api/FileController.php	API: list all files, list files by type.
app/Services/FileService.php	Fetches catalog JSON (CATALOG_URL) and formats file URLs from CDN_URL.
routes/web.php	Web routes (home, files show, download).
routes/api.php	API v1 routes.
resources/views/files/	Blade views for file listing and file detail.

Deployment

On push to main, GitHub Actions:

1. Builds the frontend (Vite) with npm ci and npm run build.
2. SCPs public/build/ to the Forge server.
3. Triggers a Laravel Forge deployment.
4. Runs php artisan optimize:clear on the server.

Required repository secrets:

• FORGE_SSH_HOST — SSH host for the server.
• FORGE_SSH_USER — SSH user (e.g. forge).
• SSH_PRIVATE_KEY — Private key for SCP/SSH.
• FORGE_SERVER_ID — Forge server ID.
• FORGE_SITE_ID — Forge site ID.
• FORGE_API_KEY — Forge deploy token.

See .github/workflows/deploy.yml.

---

For developers and bots

Base URL

Production: https://blankfiles.com. HTML and JSON are available; use Accept: application/json where applicable.

Web routes

Method	Path	Description
GET	/	Homepage: file list by category. Responds with JSON when Accept: application/json. Throttle: 30/min.
GET	/upload-testing	Binary-focused landing page for upload testing intent, linking to high-demand file formats and categories.
GET	/files/{category}/{type}	SEO-friendly file detail page (e.g. /files/document-spreadsheet/xlsx). Constraints: category, type = [A-Za-z0-9\-]+.
GET	/files/download/{category}/{type}	Download proxy: streams the file with Content-Disposition: attachment (filename blank.{type} or blank.{type}.zip). Throttle: 60/min.

API routes (prefix api/v1)

Method	Path	Response
GET	/api/v1/files	{ "files": [ ... ], "meta": { "version", "generated_at", "count" } }.
GET	/api/v1/files/{type}	Same schema, filtered by extension.
GET	/api/v1/files/{category}/{type}	Same schema with exactly one matching entry when found; 404 when missing.
GET	/api/v1/status	API health + aggregate catalog metrics (file_count, type_count, category_count) and upstream source info.

Machine-friendly notes

• The canonical file catalog schema is defined in the blank-files repo: files/files.json (key files, array of { type, url, category, package? }).
• Download URLs: use the API url field for direct CDN access, or GET /files/download/{category}/{type} for a same-origin download with a predictable filename.
• Conditional requests are supported on API responses and sitemap (ETag, Last-Modified).
• Rate limits: public IP-based limits and optional API-key limits (X-API-Key).
• API usage analytics are logged to storage/logs/api-usage-*.log (configurable channel).
• Compatibility policy: API policy.
• Web landing analytics for growth pages are logged to storage/logs/web-traffic-*.log.

Client snippets

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())

Compatibility policy

• URL versioning is stable under /api/v1/*.
• Breaking changes require a new major API path version.
• Deprecated endpoints are kept for at least 90 days before removal.
• New fields may be added; clients should ignore unknown fields.

---

Related

• filearchitect/blank-files — Source of truth for the file list and blank file assets.

MCP server (for agent marketplaces/registries)

This repository now includes a minimal MCP server that exposes Blank Files as tool calls.

• Script: scripts/mcp/blankfiles-mcp.mjs
• Run: npm run mcp:server
• Optional env: BLANKFILES_BASE_URL (default: https://blankfiles.com)

Available MCP tools:

• list_blank_files — list files, optional filters (category, type, limit)
• files_by_type — list entries by extension
• file_by_category_type — deterministic single lookup by category + extension

Example local MCP client config entry:

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

Registry submission helpers:

• Template metadata: scripts/mcp/registry/server.json.template
• Publish checklist: scripts/mcp/registry/PUBLISHING.md

Published package workspace:

• packages/blankfiles-mcp (publish as @filearchitect/blankfiles-mcp)

OpenClaw skill (ClawHub discoverability)

This repository includes an OpenClaw-ready skill bundle:

• Skill path: skills/blankfiles
• Skill entry: skills/blankfiles/SKILL.md
• Publish guide: skills/blankfiles/references/publish.md

Typical publish flow:

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

License

This project is licensed under the MIT License.