qiniu-mcp/README.md

A Model Context Protocol server for Qiniu Cloud Storage services with optimized local file upload support

# Qiniu MCP (Model Context Protocol)

A Model Context Protocol server for Qiniu Cloud Storage services, enabling AI assistants like Claude, Cursor, and Raycast to interact with Qiniu Cloud Storage.

## 🌟 Features

- **🔒 Secure Remote Architecture**: API keys stay on your server, not in the npm package
- **📦 Easy Installation**: Install via npm and configure with your credentials
- **🚀 Multiple AI Platforms**: Works with Cursor, Claude Desktop, and Raycast
- **☁️ Full Qiniu Integration**: Upload, download, list, delete, copy, and move files
- **🔧 Flexible Configuration**: Environment variables or config files
- **⚡ High Performance**: Built with TypeScript and modern Node.js

## 🏗️ Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Client     │    │   npm package   │    │  Remote Server  │
│ (Cursor/Claude) │◄──►│  (qiniu-mcp)    │◄──►│ (mcp.qiaomu.ai) │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  User Config    │    │  Qiniu Cloud    │
                       │  (API Keys)     │    │     APIs        │
                       └─────────────────┘    └─────────────────┘
```

## 📦 Installation

### Global Installation (Recommended)

```bash
npm install -g qiniu-mcp
```

### Local Installation

```bash
npm install qiniu-mcp
```

## ⚙️ Configuration

### Method 1: Environment Variables

```bash
export QINIU_ACCESS_KEY="your_access_key"
export QINIU_SECRET_KEY="your_secret_key"
export QINIU_BUCKET="your_default_bucket"      # Optional
export QINIU_REGION="z0"                       # Optional (z0=华东, z1=华北, z2=华南)
export QINIU_DOMAIN="your_custom_domain.com"   # Optional
```

### Method 2: Configuration File

Create `~/.qiniu-mcp.json`:

```json
{
  "accessKey": "your_access_key",
  "secretKey": "your_secret_key",
  "bucket": "your_default_bucket",
  "region": "z0",
  "domain": "your_custom_domain.com"
}
```

## 🔧 Usage with AI Clients

### Cursor

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP" or go to Extensions > MCP
3. Add the following configuration:

```json
{
  "mcp.servers": {
    "qiniu": {
      "command": "qiniu-mcp",
      "args": []
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "qiniu": {
      "command": "qiniu-mcp",
      "args": []
    }
  }
}
```

### Raycast

1. Install the MCP extension in Raycast
2. Configure it to use the `qiniu-mcp` command

## 🛠️ Available Tools

### `qiniu_upload_file`
Upload a file to Qiniu Cloud Storage (server-side file path).

**Parameters:**
- `filePath` (required): Server-side file path to upload
- `bucket` (optional): Target bucket name (uses default if not provided)
- `key` (optional): Object key (filename) in the bucket
- `expires` (optional): Upload token expiration time in seconds

### `qiniu_upload_local_file` ⭐ **NEW**
Upload a local file to Qiniu Cloud Storage (optimized for client-side files).

**Parameters:**
- `filePath` (required): Local file path or `file://` URL to upload
- `bucket` (optional): Target bucket name (uses default if not provided)
- `key` (optional): Object key (filename) in the bucket
- `expires` (optional): Upload token expiration time in seconds

**Features:**
- ✅ Supports local file paths and `file://` URLs
- ✅ Automatic content type detection
- ✅ Optimized for client-side file uploads
- ✅ No manual base64 conversion required

### `qiniu_upload_content`
Upload text content directly to Qiniu Cloud Storage.

**Parameters:**
- `content` (required): Text content to upload
- `bucket` (optional): Target bucket name (uses default if not provided)
- `key` (required): Object key (filename) in the bucket
- `contentType` (optional): MIME type (default: 'text/plain')
- `expires` (optional): Upload token expiration time in seconds

### `qiniu_upload_base64`
Upload base64 encoded binary content to Qiniu Cloud Storage.

**Parameters:**
- `base64Content` (required): Base64 encoded content (without data URI prefix)
- `bucket` (optional): Target bucket name (uses default if not provided)
- `key` (required): Object key (filename) in the bucket
- `contentType` (optional): MIME type (default: 'application/octet-stream')
- `expires` (optional): Upload token expiration time in seconds

### `qiniu_upload_from_url` ⭐ **NEW**
Upload a file from URL directly to Qiniu Cloud Storage (faster than base64).

**Parameters:**
- `url` (required): URL of the file to upload
- `bucket` (optional): Target bucket name (uses default if not provided)
- `key` (optional): Object key (filename) in the bucket (auto-generated if not provided)
- `expires` (optional): Upload token expiration time in seconds

**Features:**
- ✅ Direct upload from remote URLs
- ✅ No base64 conversion overhead
- ✅ Automatic content type detection
- ✅ Faster than traditional base64 upload

### `qiniu_list_files`
List files in a Qiniu Cloud Storage bucket.

**Parameters:**
- `bucket` (required): Bucket name to list files from
- `prefix` (optional): File prefix to filter results
- `limit` (optional): Maximum number of files to return (default: 100, max: 1000)
- `marker` (optional): Marker for pagination

### `qiniu_delete_file`
Delete a file from Qiniu Cloud Storage.

**Parameters:**
- `bucket` (required): Bucket name
- `key` (required): Object key (filename) to delete

### `qiniu_get_file_info`
Get detailed information about a file.

**Parameters:**
- `bucket` (required): Bucket name
- `key` (required): Object key (filename)

### `qiniu_generate_download_url`
Generate a download URL for a file.

**Parameters:**
- `bucket` (required): Bucket name
- `key` (required): Object key (filename)
- `domain` (optional): Custom domain for the download URL
- `expires` (optional): URL expiration time in seconds (default: 3600)
- `private` (optional): Whether the file is in a private bucket (default: false)

### `qiniu_copy_file`
Copy a file within Qiniu Cloud Storage.

**Parameters:**
- `sourceBucket` (required): Source bucket name
- `sourceKey` (required): Source object key
- `targetBucket` (required): Target bucket name
- `targetKey` (required): Target object key

### `qiniu_move_file`
Move/rename a file within Qiniu Cloud Storage.

**Parameters:**
- `sourceBucket` (required): Source bucket name
- `sourceKey` (required): Source object key
- `targetBucket` (required): Target bucket name
- `targetKey` (required): Target object key

## 💡 Example Usage

Once configured, you can ask your AI assistant:

### Local File Upload (Recommended)
```
Upload the local file ~/Documents/report.pdf to my qiniu bucket
```

### Upload from URL
```
Upload the image from https://example.com/image.jpg to my qiniu bucket
```

### File Management
```
List all files in my "images" bucket that start with "2024/"
```

```
Delete the file "old-document.pdf" from my documents bucket
```

### Performance Comparison
- **Local File Upload**: `qiniu_upload_local_file` - Optimized for client files
- **URL Upload**: `qiniu_upload_from_url` - Direct upload, no base64 conversion
- **Base64 Upload**: `qiniu_upload_base64` - For when you already have base64 data
- **Server File Upload**: `qiniu_upload_file` - For files on the server

```
Generate a download URL for the file "report.pdf" in bucket "documents"
```

```
Copy the file "old-logo.png" from bucket "assets" to "backup" bucket as "logo-backup.png"
```

## 🔍 Troubleshooting

### Connection Issues

1. **Server unreachable**: Check your internet connection and firewall settings
2. **Authentication failed**: Verify your Qiniu access key and secret key are correct
3. **SSL/TLS errors**: The client handles self-signed certificates automatically

### Configuration Issues

1. **Command not found**: Ensure the package is installed globally or use the full path
2. **Permission denied**: Check file permissions on your config file
3. **Invalid JSON**: Validate your configuration file syntax

### Debug Mode

Run with debug output:

```bash
DEBUG=* qiniu-mcp
```

## 🏗️ Development

### Building from Source

```bash
git clone https://github.com/yourusername/qiniu-mcp.git
cd qiniu-mcp
npm install
npm run build
```

### Running Tests

```bash
npm test
```

### Server Development

The remote server code is in the `server/` directory:

```bash
cd server
npm install
npm run dev
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📞 Support

- GitHub Issues: [Report bugs or request features](https://github.com/yourusername/qiniu-mcp/issues)
- Documentation: [Full documentation](https://github.com/yourusername/qiniu-mcp#readme)