# Blank Files MCP [Health: Active] **Category:** 💻 Developer Tools **Repository:** https://github.com/filearchitect/blankfiles-website **GitHub Stars:** 2 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/blank-files-mcp ## Description MCP server for listing and retrieving minimal valid blank files from blankfiles.com. ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "blank-files-mcp": { "command": "npx", "args": ["-y","blank-files-mcp"] } } ``` ## Documentation & README # Blank Files Website Laravel application that powers [blankfiles.com](https://blankfiles.com). Browse and download minimal valid blank files by type and category. File data and assets are served from the [filearchitect/blank-files](https://github.com/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.git cd blankfiles-website composer install cp .env.example .env php artisan key:generate ``` Set `CDN_URL` in `.env` (see [Configuration](#configuration)). Then build the frontend and run the app: ```bash npm install && npm run build php artisan serve ``` Or use [Laravel Herd](https://herd.laravel.com) 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](https://github.com/filearchitect/blankfiles-website/blob/HEAD/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](https://github.com/filearchitect/blankfiles-website/blob/HEAD/config/cache.php) and [app/Services/FileService.php](https://github.com/filearchitect/blankfiles-website/blob/HEAD/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](https://github.com/filearchitect/blankfiles-website/blob/HEAD/.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](https://github.com/filearchitect/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](https://blankfiles.com/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 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](https://github.com/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: ```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 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.