UNPKG

qiniu-mcp

Version:

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

318 lines (236 loc) β€’ 9.37 kB
# 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)