Blank Files MCP

Blank Files 网站

为 blankfiles.com 提供支持的 Laravel 应用。按类型和类别浏览并下载有效的最简空白文件。文件数据和资源通过可配置的 CDN 从 filearchitect/blank-files 仓库提供。

要求

• PHP 8.2+
• Composer
• Node.js 18+（用于 Vite 前端构建）

安装

git clone https://github.com/filearchitect/blankfiles-website.git
cd blankfiles-website
composer install
cp .env.example .env
php artisan key:generate

在 .env 中设置 CDN_URL（参见配置）。然后构建前端并运行应用：

npm install && npm run build
php artisan serve

或者使用 Laravel Herd 和 .test 域名。

配置

变量	描述
CDN_URL	必填。 用于将可下载文件 URL 构造为 {CDN_URL}/files/{filename} 的基础 URL。默认值：https://raw.githubusercontent.com/filearchitect/blank-files/main（在 config/app.php 中设置）。
CATALOG_URL	可选。目录 JSON（files/files.json）的直接 URL。为确保数据最新，默认值为 https://raw.githubusercontent.com/filearchitect/blank-files/main/files/files.json。
CACHE_ENABLED	可选。设为 true 时，会缓存来自 CDN 的文件列表。TTL 由 CATALOG_TTL_MINUTES 控制（默认值为 10）。参见 config/cache.php 和 app/Services/FileService.php。
CATALOG_TTL_MINUTES	可选。CACHE_ENABLED=true 时，远程目录缓存的 TTL（分钟）。较低的值可更快反映新增格式；较高的值可减少 CDN 请求。
API_KEYS	可选。供更高请求频率的 API 客户端使用的逗号分隔 API 密钥（通过 X-API-Key 或 Authorization: Bearer ... 使用）。
API_PUBLIC_RATE_LIMIT	可选。公共 API 每分钟请求数限制（默认值为 30）。
API_KEY_RATE_LIMIT	可选。使用 API 密钥的请求每分钟数量限制（默认值为 300）。
API_USAGE_LOG_CHANNEL	可选。用于 API 使用情况分析的日志通道（默认值为 api_usage）。
OPENPANEL_CLIENT_ID	可选。设置后启用 OpenPanel 网站分析脚本。
OPENPANEL_CLIENT_SECRET	可选。保留用于服务器端 OpenPanel 事件（不会暴露给浏览器脚本）。

项目结构

路径	用途
app/Http/Controllers/FileController.php	Web：主页、文件详情页、下载代理。
app/Http/Controllers/Api/FileController.php	API：列出所有文件、按类型列出文件。
app/Services/FileService.php	获取目录 JSON（CATALOG_URL），并使用 CDN_URL 格式化文件 URL。
routes/web.php	Web 路由（主页、文件展示、下载）。
routes/api.php	API v1 路由。
resources/views/files/	用于文件列表和文件详情的 Blade 视图。

部署

推送到 main 时，GitHub Actions 会：

1. 使用 npm ci 和 npm run build 构建前端（Vite）。
2. 将 public/build/ 通过 SCP 传输到 Forge 服务器。
3. 触发 Laravel Forge 部署。
4. 在服务器上运行 php artisan optimize:clear。

必需的仓库机密：

• FORGE_SSH_HOST — 服务器的 SSH 主机。
• FORGE_SSH_USER — SSH 用户（例如 forge）。
• SSH_PRIVATE_KEY — 用于 SCP/SSH 的私钥。
• FORGE_SERVER_ID — Forge 服务器 ID。
• FORGE_SITE_ID — Forge 站点 ID。
• FORGE_API_KEY — Forge 部署令牌。

请参阅 .github/workflows/deploy.yml。

---

面向开发者和机器人

基础 URL

生产环境：https://blankfiles.com。提供 HTML 和 JSON；适用时使用 Accept: application/json。

Web 路由

方法	路径	描述
GET	/	主页：按类别列出文件。Accept: application/json 时返回 JSON。限流：30 次/分钟。
GET	/upload-testing	面向上传测试场景的二进制文件专题落地页，链接至热门文件格式和类别。
GET	/files/{category}/{type}	SEO 友好的文件详情页（例如 /files/document-spreadsheet/xlsx）。约束：category、type = [A-Za-z0-9\-]+。
GET	/files/download/{category}/{type}	下载代理：以流的形式传输文件，并设置 Content-Disposition: attachment（文件名为 blank.{type} 或 blank.{type}.zip）。限流：60 次/分钟。

API 路由（前缀为 api/v1）

方法	路径	响应
GET	/api/v1/files	{ "files": [ ... ], "meta": { "version", "generated_at", "count" } }。
GET	/api/v1/files/{type}	相同的架构，按扩展名筛选。
GET	/api/v1/files/{category}/{type}	找到匹配项时，返回恰好包含一个条目的相同架构；未找到时返回 404。
GET	/api/v1/status	API 健康状态 + 汇总目录指标（file_count、type_count、category_count）及上游来源信息。

机器友好说明

• 规范的文件目录架构定义于 blank-files 仓库：files/files.json（包含 files 键，值为 { type, url, category, package? } 数组）。
• 下载 URL：使用 API 的 url 字段直接通过 CDN 访问，或使用 GET /files/download/{category}/{type} 进行同源下载，并获得可预测的文件名。
• API 响应和站点地图支持条件请求（ETag、Last-Modified）。
• 速率限制：基于公网 IP 的限制和可选的 API 密钥限制（X-API-Key）。
• API 使用分析记录在 storage/logs/api-usage-*.log 中（可配置通道）。
• 兼容性政策：API policy。
• 增长页面的 Web 着陆页分析记录在 storage/logs/web-traffic-*.log 中。

客户端代码片段

curl -sS "https://blankfiles.com/api/v1/files/document-spreadsheet/xlsx" \
  -H "Accept: application/json" \
  -H "X-API-Key: $BLANKFILES_API_KEY"

const res = await fetch("https://blankfiles.com/api/v1/files", {
  headers: { "Accept": "application/json", "If-None-Match": etag }
});
if (res.status === 304) {
  // unchanged
}

import requests
r = requests.get("https://blankfiles.com/api/v1/status", timeout=20)
r.raise_for_status()
print(r.json())

兼容性政策

• /api/v1/* 下的 URL 版本保持稳定。
• 破坏性变更需要使用新的主版本 API 路径。
• 弃用的端点至少保留 90 天后才会移除。
• 可以添加新字段；客户端应忽略未知字段。

---

相关内容

• filearchitect/blank-files — 文件列表和空白文件资源的权威来源。

MCP 服务（适用于 Agent 市场／注册表）

此仓库现已包含一个精简的 MCP 服务，可将 Blank Files 作为工具调用提供。

• 脚本：scripts/mcp/blankfiles-mcp.mjs
• 运行：npm run mcp:server
• 可选环境变量：BLANKFILES_BASE_URL（默认值：https://blankfiles.com）

可用的 MCP 工具：

• list_blank_files — 列出文件，可选筛选条件（category、type、limit）
• files_by_type — 按扩展名列出条目
• file_by_category_type — 按类别和扩展名确定性地查找单个条目

本地 MCP 客户端配置示例：

{
  "mcpServers": {
    "blankfiles": {
      "command": "node",
      "args": ["/absolute/path/to/blankfiles-website/scripts/mcp/blankfiles-mcp.mjs"],
      "env": {
        "BLANKFILES_BASE_URL": "https://blankfiles.com"
      }
    }
  }
}

注册表提交辅助文件：

• 模板元数据：scripts/mcp/registry/server.json.template
• 发布检查清单：scripts/mcp/registry/PUBLISHING.md

已发布的软件包工作区：

• packages/blankfiles-mcp（以 @filearchitect/blankfiles-mcp 发布）

OpenClaw 技能（便于在 ClawHub 中发现）

此仓库包含适用于 OpenClaw 的技能包：

• 技能路径：skills/blankfiles
• 技能入口：skills/blankfiles/SKILL.md
• 发布指南：skills/blankfiles/references/publish.md

典型的发布流程：

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

许可证

本项目采用 MIT 许可证。