Blank Files MCP
MCP server for listing and retrieving minimal valid blank files from blankfiles.com.
Open source Open in the app JSON README (API)
About
MCP server for listing and retrieving minimal valid blank files from blankfiles.com.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- filearchitect
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Stars
- 2
- Last push
- 2026-06-03T03:23:16Z
- Repository state
- ativo
- Language
- Blade
- Added
- 2026-08-29 03:02:47
- Updated
- 2026-08-29 03:02:47
- Origin id
io.github.filearchitect/blankfiles-mcp
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](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](config/cache.php) and [app/Services/FileService.php](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](.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.