@mcpcn/mcp-file-upload/README.md

文件管理MCP服务器（支持图片上传和文件下载）

# MCP 图片上传/下载服务器

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

## 功能特性

- 🖼️ **专业图片支持**：支持 jpg, jpeg, png, gif, webp, bmp, svg, tiff, ico, avif, heic 等 16 种图片格式
- 🚀 **快速上传下载**：云端存储上传，本地保存下载
- 🔗 **直接访问链接**：上传返回可直接访问的图片 URL
- ⚡ **MCP 协议集成**：基于 MCP 协议，易于集成
- 🛡️ **安全验证**：严格的文件格式验证，仅允许图片文件
- 📁 **大小控制**：支持最大10MB图片文件
- 📝 **详细日志**：完善的错误处理和日志输出

## 安装

### 前置要求

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

### 安装依赖

```bash
cd typescript/mcp-image-upload
pnpm install
```

### 构建项目

```bash
pnpm build
```

## 使用方法

### 1. 直接运行

```bash
pnpm start
```

### 2. 作为 MCP 服务器

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

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

### 3. 使用 npx

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

## 工具说明

### upload_file

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

**支持的图片格式：**
- **常见格式**: jpg, jpeg, png, gif, webp, bmp, svg, tiff, tif, ico
- **现代格式**: avif, heic, heif, apng
- **特殊格式**: jfif, pjpeg, pjp

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

**示例：**

```json
{
  "name": "upload_file",
  "arguments": { "path": "/Users/username/Pictures/image.jpg" }
}
```

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

### download_file

从指定 URL 下载文件保存到本地（最大 10MB）。

**注意**：虽然上传工具仅限制图片格式，但下载工具可以下载任意 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.png",
    "savePath": "./downloads/",
    "filename": "file.png",
    "overwrite": true
  }
}
```

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

## API 接口（上传）

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

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

## 错误处理

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

- 文件不存在错误
- **不支持的文件格式错误**（仅允许图片格式）
- 文件大小超限错误（10MB 以上）
- 网络连接错误
- 服务器响应错误
- 上传超时错误

## 开发

### 开发模式

```bash
pnpm dev
```

### 清理构建文件

```bash
pnpm clean
```

### 完整重新构建

```bash
pnpm prepare
```

## 项目结构

```
mcp-image-upload/
├── 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.0.0
- 初始版本
- **专门支持图片上传功能**（仅图片格式）
- 支持 16 种常见图片格式
- 完整的错误处理和文件格式验证
- MCP 协议集成