mcp_file_manager

通过 mcp 服务实现用户/ai agent 上传/下载文件并生成对应链接，每次进行上传操作时都生成对应标识码供 ai 查找，文件 24 小时后自动删除。

一个开箱即用的文件中转 MCP 服务：AI 和人都可以把文件扔进来，拿到一个标识码和一个可直接分享的下载链接；之后只要报出标识码，AI 就能重新找到并读取这个文件。所有文件默认保留 24 小时，到期自动删除。

特点

• 双向可用：AI 用 MCP 工具上传/下载；人用浏览器页面上传/下载。两边共用同一套存储与标识码。
• 标识码友好：Crockford Base32（已剔除 I/L/O/U），展示为 7K2QF-9XM4T；查找时大小写、连字符、0/O 1/I/l 混淆全都宽容。
• 24 小时自动清理：后台守护任务每 10 分钟扫一次，启动时也扫一次（覆盖停机期间到期的文件），同时回收无主文件与失效上传链接。
• 全流式写盘：边写盘边算 SHA-256 并计数，超限立即中断，不把整个文件读进内存。
• 四种上传源：base64 内容、纯文本、服务器本地路径、远程 URL。
• 两种传输：stdio（供 Claude Desktop / Cursor 等客户端拉起）与无状态 Streamable HTTP（供远程部署）。
• 零依赖存储：本地文件系统 + 原子写入的 index.json，不需要数据库或对象存储。

关于保留期：仓库最初的描述是 14 天，本实现按最新要求改为 24 小时。保留期完全可配（FM_TTL_HOURS），如需恢复 14 天只需设为 336。

快速开始

需要 Node.js >= 20.11。

npm install
cp .env.example .env   # 可选，不改也能跑
npm run dev            # 开发模式：stdio + 本地文件服务
npm run build && npm start

启动后浏览器打开 http://localhost:8787 即为上传页面。

作为远程 HTTP 服务部署：

FM_HOST=0.0.0.0 FM_API_TOKEN=你的强密钥 npm run start:http
# MCP 端点：POST http://<host>:8787/mcp

接入 MCP 客户端（stdio）

参见 examples/claude_desktop_config.json：

{
  "mcpServers": {
    "file-manager": {
      "command": "node",
      "args": ["/结对路径/mcp_file_manager/dist/index.js"],
      "env": {
        "FM_DATA_DIR": "/结对路径/mcp_file_manager/data",
        "FM_PUBLIC_BASE_URL": "http://localhost:8787",
        "FM_TTL_HOURS": "24"
      }
    }
  }
}

stdio 模式下会同时启动本地文件 HTTP 服务，否则生成的下载链接没人响应。不需要时加 --no-http。 日志一律输出到 stderr，stdout 留给 MCP 的 JSON-RPC 通道。

前端页面

页面在 public/ 下，是三个普通静态文件（HTML + CSS + 原生 JS），无构建步骤、无前端依赖，由 Express 直接托管：

入口	用途
GET /	完整上传页：自己传文件、拿标识码、反查旧标识码
GET /u/:ticket	同一份页面的“一次性上传链接”形态，发给外部的人使用
GET /assets/*	public/ 里的样式与脚本

功能：

• 三种选文件方式：拖拽、点击选择、Ctrl / ⌘ + V 直接粘贴文件或截图；支持多文件排队逐个上传。
• 真实上传进度：用 XHR 上传，逐文件显示百分比进度条，失败的条目会留在列表里可直接重试。
• 标识码是主角：上传完成后用大号等宽字体展示 7K2QF-9XM4T，点一下即复制；另外提供“复制链接”与“复制给 AI”（一次拿到标识码 + 文件名 + 下载地址 + 到期时间）。
• 到期倒计时：每张卡片把 expiresAt 渲染为本地时间并满上“还剩 N 小时”，过期后变红并提示已被自动删除。
• 标识码反查：输入标识码即可重新拿回下载链接（走 GET /api/files/:code，大小写与连字符不敏感）。
• 本机历史：最近 20 次上传存在 localStorage（不上传服务器、到期自动消失），方便事后回查标识码。
• 高级选项：备注、标签、自定义保留小时数（上限受 FM_MAX_TTL_HOURS 约束）。
• 自适应：页面启动时拉 GET /api/config，自动展示当前保留策略与单文件上限（超限文件在上传前就被拦住）；仅当服务端设了 FM_API_TOKEN 时才显示 Token 输入框（保存在 sessionStorage）。
• 适配手机屏幕，跟随系统浅色/深色主题。

部署时请让 public/ 与 dist/ 一同发布（npm 包的 files 与 Dockerfile 都已包含）；缺少时页面会直接提示而不是返回空白。

MCP 工具

工具	作用	关键参数
upload_file	上传文件，返回标识码与链接	content(base64) / text / path / url 四选一，name、tags、ttlHours
download_file	按标识码取回内容	code、savePath、encoding(auto/utf-8/base64/none)
get_file_info	只看元数据与链接	code
list_files	列表/搜索（忘记标识码时用）	query、tag、limit、sort
delete_file	不等到期，立即删除	code
extend_expiry	重算为“从现在起再保留 N 小时”	code、hours
create_upload_link	生成给人用的临时上传页面	note、expiresInMinutes、maxUses、fileTtlHours
sweep_expired	手动触发一次到期清理	—
get_storage_stats	文件数、占用、保留策略、下一个到期时间	—

典型对话：

1. 用户：“把这份报价单存一下。” → AI 调 upload_file → 回复标识码 7K2QF-9XM4T + 下载链接 + “24 小时后自动删除”。
2. 用户（稍后）：“7K2QF-9XM4T 里的金额是多少？” → AI 调 download_file 直接读内容。
3. 需要用户提供文件时：AI 调 create_upload_link → 发出一个 /u/<ticket> 链接 → 用户上传后页面直接展示标识码。

HTTP 接口

方法	路径	说明	需 Token
GET	/	上传页面	否
GET	/assets/*	前端静态资源	否
GET	/healthz	健康检查	否
GET	/api/config	页面渲染用的公开配置（保留期、上限、是否需 Token）	否
POST	/api/upload	multipart 上传（字段名 file）	是
GET	/f/:code · /f/:code/:filename	下载（?inline 可在浏览器内预览）	否（标识码即凭证）
GET	/api/files/:code	单文件元数据 JSON	否
GET	/api/files	列表/搜索	是
DELETE	/api/files/:code	删除	是
POST	/api/files/:code/extend	延期，体 {"hours":48}	是
GET	/api/stats · POST /api/sweep	状态与手动清理	是
GET/POST	/u/:ticket	临时上传页面与提交	否（票据即凭证）
GET	/api/tickets/:ticket	票据详情（页面用于判定链接是否还有效）	否（票据即凭证）
POST	/mcp	无状态 Streamable HTTP MCP 端点	是

鉴权方式（三者均可，仅在设置了 FM_API_TOKEN 时生效）：Authorization: Bearer <token>、X-API-Token: <token>、?token=<token>。

# 上传
curl -X POST http://localhost:8787/api/upload \
  -H "Authorization: Bearer $FM_API_TOKEN" \
  -F "file=@./report.pdf" -F "tags=财务,Q3" -F "ttlHours=48"

# 下载
curl -OJ http://localhost:8787/f/7K2QF9XM4T

环境变量

变量	默认值	说明
FM_TTL_HOURS	24	默认保留时长（小时），到期自动删除
FM_MAX_TTL_HOURS	720	单次请求可申请的保留上限（30 天）
FM_SWEEP_INTERVAL_MINUTES	10	到期清理扫描间隔
FM_DATA_DIR	./data	数据目录（files/、tmp/、index.json）
FM_HOST / FM_PORT	127.0.0.1 / 8787	HTTP 监听地址
FM_PUBLIC_BASE_URL	http://<host>:<port>	拼接对外链接用，反代/域名下必须设置
FM_API_TOKEN	空	写接口鉴权；非本机部署强烈建议设置
FM_MAX_UPLOAD_MB	100	单文件上限
FM_MAX_INLINE_MB	4	MCP 内联返回内容的上限，超过则只给链接
FM_ALLOW_REMOTE_FETCH	1	是否允许 url 源上传
FM_ALLOW_LOCAL_PATH	1	是否允许 path 源上传
FM_LOG_LEVEL	info	debug / info / warn / error

保留与清理策略

• 每个文件写入时记录 expiresAt = 上传时间 + 24 小时。
• 三个时机会执行清理：服务启动时、每 10 分钟的守护任务、手动调用 sweep_expired。
• 另外，任何一次对已过期标识码的访问会返回 410 expired 并顺手删除该文件，不依赖守护任务的时序。
• 清理同时回收：到期文件实体 + 元数据、用尽/过期的上传票据、失去元数据的孤儿文件。
• 需要保留更久：上传时传 ttlHours，或事后调 extend_expiry；全局改默认值用 FM_TTL_HOURS。

项目结构

public/
  index.html        上传页（/ 与 /u/:ticket 共用这一份）
  styles.css        样式（含深色模式与移动端适配）
  app.js            原生 JS：拖拽/粘贴、进度条、标识码复制、反查、本机历史
src/
  index.ts          启动入口（参数解析、传输选择、优雅退出）
  service.ts        全部业务逻辑（上传/下载/列表/延期/清理/统计）
  store.ts          元数据索引（串行写队列 + 临时文件原子 rename）
  storage.ts        文件实体存储（标识码命名，彻底隔结路径穿越）
  codes.ts          标识码生成 / 归一化 / 展示格式
  retention.ts      24h 到期守护任务
  config.ts errors.ts logger.ts mime.ts utils.ts version.ts
  mcp/server.ts     9 个 MCP 工具定义
  http/app.ts       Express 路由 + 静态资源 + 无状态 MCP 端点
  http/pages.ts     前端目录定位与页面下发
tests/service.test.ts

分层原则：FileManagerService 是唯一真相，MCP 层、HTTP 层与前端都只是它的薄封装，保证各入口的标识码、链接与保留期行为完全一致。

开发

npm run typecheck   # tsc --noEmit
npm test            # node --test（含“默认 24 小时”与清理行为的回归用例）
npm run build       # 只编译 TypeScript；public/ 直接发布，无需构建

Docker

docker compose up -d --build
# 或
docker build -t mcp-file-manager . && docker run -p 8787:8787 -v "$PWD/data:/data" mcp-file-manager

安全提醒

• 标识码即凭证：拿到标识码即可下载（无需 Token），分享链接前请确认接收方。标识码空间为 32^10，无法枚举。
• 对外暴露时请务必设置 FM_API_TOKEN，并在反代层加上 HTTPS 与频率限制。
• 页面上的 Token 只存在当前浏览器会话（sessionStorage），不会写入磁盘持久保存。
• 如无需让 AI 读写服务器本地文件或抓取外网，请设 FM_ALLOW_LOCAL_PATH=0、FM_ALLOW_REMOTE_FETCH=0。
• 上传的原始文件名只保存在元数据里，磁盘上使用“标识码 + 白名单扩展名”命名。

后续可做

• 可插拔存储后端（S3 / R2）与预签名直传
• 多负载部署时把元数据换成 SQLite / Redis
• 可选的服务端加密与病毒扫描钩子
• 按上传者维度的配额与审计日志