Blank Files MCP

io.github.filearchitect由 GitHub 帳號 filearchitect 發布v1.0.1更新於 Nov 10, 2026

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

概覽

AI 產生的概覽

依類別與檔案類型列出並查詢 blankfiles.com 上的最小有效空白檔案,讓助理找到可下載的空白檔案。

可以做什麼
  • 依類別、類型與數量上限篩選列出空白檔案
  • 依副檔名列出目錄項目
  • 依類別加副檔名精確查詢單一檔案
適用情境
當你需要某種格式的最小有效空白檔案(例如試算表或文件)來測試上傳、驗證檔案處理流程,或作為工作流程的起點,並希望助理協助找到對應的下載項目時使用。
執行需求
以本機 Node.js 程序執行(npm 套件 @filearchitect/blankfiles-mcp,stdio 傳輸)。需要連線至 blankfiles.com 的網路;可選環境變數 BLANKFILES_BASE_URL 可覆寫基底網址。未宣告任何身分驗證。
安裝前請注意
此伺服器會查詢第三方公開網站,查詢條件與篩選參數會傳送至 blankfiles.com。它僅列出與取得目錄項目,實際下載需另行使用回傳的連結。受公開速率限制約束,可選 API 金鑰可取得較高額度。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Blank Files MCP,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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.

來源:README.md,提交 00d8852

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v1.0.1最新Sep 16, 2026

評分

已滿足適用檢查項的 40%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。