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 分

    请在仓库或注册中心条目中声明许可证。