Blank Files MCP

io.github.filearchitectPublished by GitHub account filearchitectv1.0.1Updated Nov 10, 2026

MCP server for listing and retrieving minimal valid blank files from blankfiles.com.

VerifiedSTDIODesktop onlyWeb Search & ScrapingFiles & Storage

Overview

AI-generated overview

Lists and looks up minimal valid blank files from blankfiles.com by category and file type, so an assistant can find a downloadable blank file.

What you can do
  • List blank files with optional category, type and limit filters
  • List catalog entries by file extension
  • Look up a single file deterministically by category plus extension
When to use it
Useful when you need a minimal, valid blank file of a given format (for example a spreadsheet or document) to test uploads, validate file handling, or seed a workflow, and want the assistant to find the right download entry.
Requirements
Runs as a local Node.js process (npm package @filearchitect/blankfiles-mcp, stdio). Network access to blankfiles.com is needed; the optional BLANKFILES_BASE_URL environment variable overrides the base URL. No authentication is declared.
Before you install
The server queries a third-party public site, so lookups and any filters are sent to blankfiles.com. It only lists and retrieves catalog entries; downloads are done separately via the returned URLs. Public rate limits apply, and an API key is optional for higher limits.

Installation

In SourceWeft

  1. Open Blank Files MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
git clone https://github.com/filearchitect/blankfiles-website.gitcd blankfiles-websitecomposer installcp .env.example .envphp artisan key:generate

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

bash
npm install && npm run buildphp artisan serve

Or use Laravel Herd with a .test domain.

Configuration

VariableDescription
CDN_URLRequired. 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_URLOptional. 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_ENABLEDOptional. 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_MINUTESOptional. Cache TTL in minutes for the remote catalog when CACHE_ENABLED=true. Lower values reflect new formats sooner; higher values reduce CDN fetches.
API_KEYSOptional. Comma-separated API keys for higher-rate API clients (used by X-API-Key or Authorization: Bearer ...).
API_PUBLIC_RATE_LIMITOptional. Public API requests/minute limit (default 30).
API_KEY_RATE_LIMITOptional. API-key requests/minute limit (default 300).
API_USAGE_LOG_CHANNELOptional. Logging channel for API usage analytics (default api_usage).
OPENPANEL_CLIENT_IDOptional. Enables OpenPanel web analytics script when set.
OPENPANEL_CLIENT_SECRETOptional. Reserved for server-side OpenPanel events (not exposed to browser script).

Project structure

PathPurpose
app/Http/Controllers/FileController.phpWeb: homepage, file detail page, download proxy.
app/Http/Controllers/Api/FileController.phpAPI: list all files, list files by type.
app/Services/FileService.phpFetches catalog JSON (CATALOG_URL) and formats file URLs from CDN_URL.
routes/web.phpWeb routes (home, files show, download).
routes/api.phpAPI 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

MethodPathDescription
GET/Homepage: file list by category. Responds with JSON when Accept: application/json. Throttle: 30/min.
GET/upload-testingBinary-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)

MethodPathResponse
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/statusAPI 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

bash
curl -sS "https://blankfiles.com/api/v1/files/document-spreadsheet/xlsx" \  -H "Accept: application/json" \  -H "X-API-Key: $BLANKFILES_API_KEY"
js
const res = await fetch("https://blankfiles.com/api/v1/files", {  headers: { "Accept": "application/json", "If-None-Match": etag }});if (res.status === 304) {  // unchanged}
python
import requestsr = 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

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:

json
{  "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:

bash
npm i -g clawhubclawhub loginclawhub 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.

Source: README.md at commit 00d8852

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.