npm package: @mcpcn/mcp-file-manager
Description: 文件管理MCP服务器（支持图片上传和文件下载）
Latest version: 1.1.7

# MCP 文件上传/下载服务器

一个基于 Model Context Protocol (MCP) 的通用文件上传/下载服务器，支持：
- 将本地文件上传到云端并返回可访问的 URL；
- 从 URL 下载文件保存到本地。

## 功能特性

- 📁 **通用文件支持**：支持图片、文档、音视频等常见文件格式
- 🛡️ **安全限制**：禁止上传压缩包（zip、rar、7z）、可执行文件（exe、bat、sh）、脚本文件（js、py、php）等危险文件
- 🚀 **快速上传下载**：云端存储上传，本地保存下载
- 🔗 **直接访问链接**：上传返回可直接访问的文件 URL
- ⚡ **MCP 协议集成**：基于 MCP 协议，易于集成
- 📦 **大小控制**：上传最大50MB，下载无大小限制
- 📝 **详细日志**：完善的错误处理和日志输出

## 安装

### 前置要求

- Node.js >= 18
- pnpm >= 8

### 安装依赖

```bash
cd typescript/文件上传下载
pnpm install
```

### 构建项目

```bash
pnpm build
```

## 使用方法

### 1. 直接运行

```bash
pnpm start
```

### 2. 作为 MCP 服务器

在您的 MCP 客户端配置中添加：

```json
{
  "mcpServers": {
    "文件上传下载": {
      "command": "node",
      "args": ["/path/to/文件上传下载/dist/index.js"],
      "env": {}
    }
  }
}
```

### 3. 使用 npx

```json
{
  "mcpServers": {
    "文件上传下载": {
      "command": "npx",
      "args": ["-y", "@mcpcn/mcp-file-upload"],
      "env": {}
    }
  }
}
```

## 工具说明

### upload_file

上传本地文件到云端，返回可访问的文件 URL（最大 50MB）。

**支持的文件格式：**
- **图片格式**: jpg, jpeg, png, gif, webp, bmp, svg, tiff, tif, ico, avif, heic, heif, jfif, pjpeg, pjp, apng
- **文档格式**: txt, doc, docx, pdf, xls, xlsx, ppt, pptx, csv, rtf
- **音视频格式**: mp4, avi, mov, wmv, flv, mp3, wav, aac, flac
- **其他格式**: json, xml, html, css 等

**禁止的文件格式：**
- **压缩包**: zip, rar, 7z, tar, gz, bz2, xz, cab, iso, dmg 等
- **可执行文件**: exe, bat, cmd, com, scr, pif, msc, vbs, jar, run, bin, deb, rpm, pkg, msi, ipa, apk 等
- **脚本文件**: sh, ps1, py, rb, pl, php, asp, aspx, jsp, cgi, js 等
- **系统文件**: dll, so, dylib, sys, drv, ocx, reg, inf 等

**参数：**
- `path` (string, 必需): 要上传的本地文件路径

**示例：**

```json
{
  "name": "upload_file",
  "arguments": { "path": "/Users/username/Documents/document.pdf" }
}
```



**返回：**包含文件 URL 的文本消息。

### download_file

从指定 URL 下载文件保存到本地（无大小限制）。

**参数：**
- `url` (string, 必需): 要下载的文件 URL（例如上传返回的 URL）
- `savePath` (string, 可选): 保存路径。可传目录（以 `/` 结尾）或完整文件路径，默认保存到桌面
- `filename` (string, 可选): 保存文件名（当 `savePath` 为目录时可用）
- `overwrite` (boolean, 可选): 如目标已存在是否覆盖，默认 false

**示例：**

```json
{
  "name": "download_file",
  "arguments": {
    "url": "https://example.com/path/to/file.pdf",
    "savePath": "./downloads/",
    "filename": "document.pdf",
    "overwrite": true
  }
}
```

**返回：**包含保存路径与文件大小的文本消息。

## API 接口（上传）

本服务器使用以下 API 进行文件上传：

- **接口地址**: `https://www.mcpcn.cc/api/fileUploadAndDownload/uploadMcpFile`
- **请求方法**: POST
- **请求格式**: multipart/form-data
- **文件字段名**: `file`

## 错误处理

服务器提供完善的错误处理，包括：

- 文件不存在错误
- **禁止的文件格式错误**（安全限制）
- 文件大小超限错误（上传50MB以上）
- 网络连接错误
- 服务器响应错误
- 上传/下载超时错误

## 开发

### 开发模式

```bash
pnpm dev
```

### 清理构建文件

```bash
pnpm clean
```

### 完整重新构建

```bash
pnpm prepare
```

## 项目结构

```
文件上传下载/
├── src/
│   └── index.ts          # 主要服务器实现
├── dist/
│   └── index.js          # 构建输出文件
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript 配置
└── README.md            # 使用说明
```

## 技术栈

- **TypeScript** - 类型安全的 JavaScript
- **Node.js** - 运行时环境
- **@modelcontextprotocol/sdk** - MCP 协议实现
- **form-data** - multipart/form-data 支持
- **node-fetch** - HTTP 请求库

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.1.0
- 改为通用文件上传功能
- 支持图片、文档、音视频等多种文件格式
- 添加安全限制，禁止压缩包、可执行文件、脚本文件等
- 上传文件大小限制提升至50MB
- 下载文件取消大小限制
- 增强错误处理和格式验证

### v1.0.0
- 初始版本
- 专门支持图片上传功能（仅图片格式）
- 支持 16 种常见图片格式
- 完整的错误处理和文件格式验证
- MCP 协议集成