mcp-cos-upload 1.0.3 → 1.0.4

package/README.md

@@ -1,23 +1,61 @@
 # mcp-cos-upload
 
-MCP server for uploading files to Tencent Cloud COS. Supports uploading from URL (e.g., Figma export) or text content.
+MCP server for uploading files to Tencent Cloud COS. Supports uploading from URL (e.g., Figma export), local file path, or text content.
 
-## Installation
+## Features
+
+- 🚀 **Multiple upload sources** - URL, local file, or text content
+- 🗜️ **Smart image compression** - PNG, JPEG, WebP, GIF, SVG auto-optimization
+- 📁 **Auto-organized storage** - Files stored by date folders with random suffix
+- 🔗 **CDN support** - Returns CDN URL for fast access
+
+---
+
+## For Team Members (Users)
+
+### Quick Start
+
+#### Method 1: Project `.env` File (Recommended)
+
+Create a `.env` file in your project root:
 
 ```bash
-npm install mcp-cos-upload
+cp node_modules/mcp-cos-upload/.env.example .env
+# Or create manually:
 ```
 
-## Usage
+```env
+COS_SECRET_ID=your_secret_id
+COS_SECRET_KEY=your_secret_key
+COS_DEFAULT_BUCKET=your_bucket_name
+COS_DEFAULT_REGION=ap-guangzhou
+COS_KEY_PREFIX=figma-assets
+COS_CDN_DOMAIN=cdn.example.com
+```
 
-### MCP Configuration (Cursor / Claude Desktop)
+Then add MCP configuration (Cursor Settings → MCP) without `env`:
 
-Add to your MCP configuration:
+```json
+{
+  "mcpServers": {
+    "mcp-cos-upload": {
+      "command": "npx",
+      "args": ["-y", "mcp-cos-upload"]
+    }
+  }
+}
+```
+
+> **Note:** The `.env` file contains secrets and is already excluded from Git via `.gitignore`. Never commit it. Use `.env.example` as a reference template.
+
+#### Method 2: MCP `env` Configuration
+
+Alternatively, pass credentials directly in MCP config:
 
 ```json
 {
   "mcpServers": {
-    "cos-upload": {
+    "mcp-cos-upload": {
       "command": "npx",
       "args": ["-y", "mcp-cos-upload"],
       "env": {
@@ -25,14 +63,18 @@ Add to your MCP configuration:
         "COS_SECRET_KEY": "your_secret_key",
         "COS_DEFAULT_BUCKET": "your_bucket_name",
         "COS_DEFAULT_REGION": "ap-guangzhou",
-        "COS_KEY_PREFIX": "uploads/",
-        "COS_CDN_DOMAIN": "your-cdn-domain.com"
+        "COS_KEY_PREFIX": "figma-assets",
+        "COS_CDN_DOMAIN": "cdn.example.com"
       }
     }
   }
 }
 ```
 
+#### Priority
+
+If both are configured, project `.env` file takes **higher priority** over MCP `env` configuration.
+
 ### Environment Variables
 
 | Variable | Required | Description |
@@ -40,11 +82,126 @@ Add to your MCP configuration:
 | `COS_SECRET_ID` | ✅ | Tencent Cloud SecretId |
 | `COS_SECRET_KEY` | ✅ | Tencent Cloud SecretKey |
 | `COS_DEFAULT_BUCKET` | ✅ | Default COS bucket name |
-| `COS_DEFAULT_REGION` | ✅ | Default COS region (e.g., `ap-guangzhou`) |
-| `COS_KEY_PREFIX` | ❌ | Key prefix for uploaded files (e.g., `uploads/`) |
+| `COS_DEFAULT_REGION` | ✅ | Default COS region (e.g., `ap-guangzhou`, `ap-beijing`) |
+| `COS_KEY_PREFIX` | ❌ | Key prefix for uploaded files (default: `figma-assets`) |
 | `COS_CDN_DOMAIN` | ❌ | Custom CDN domain (e.g., `cdn.example.com`) |
 
-## Tools
+### Usage Examples
+
+Just tell AI what you want to upload:
+
+```
+上传这张图片：/Users/me/Downloads/screenshot.png
+```
+
+```
+Upload this image to COS: https://example.com/image.png
+```
+
+The AI will automatically:
+1. Call the `cos_upload` tool
+2. Compress the image (if applicable)
+3. Upload to COS with date-organized path
+4. Return the CDN URL
+
+### Upload Path Structure
+
+Files are automatically organized:
+
+```
+{COS_KEY_PREFIX}/{YYYY-MM-DD}/{filename}_{random}.{ext}
+
+Example:
+figma-assets/2025-12-22/screenshot_a3b8k2.png
+```
+
+---
+
+## For Developers
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/user/mcp-cos-upload.git
+cd mcp-cos-upload
+
+# Install dependencies
+npm install
+```
+
+### Local Development
+
+#### Method 1: Direct Node Execution
+
+```bash
+# Set environment variables
+export COS_SECRET_ID="your_secret_id"
+export COS_SECRET_KEY="your_secret_key"
+export COS_DEFAULT_BUCKET="your_bucket"
+export COS_DEFAULT_REGION="ap-guangzhou"
+
+# Run the MCP server
+node src/index.js
+```
+
+#### Method 2: Configure in Cursor for Testing
+
+Point to your local development path:
+
+```json
+{
+  "mcpServers": {
+    "mcp-cos-upload": {
+      "command": "node",
+      "args": ["/path/to/mcp-cos-upload/src/index.js"],
+      "env": {
+        "COS_SECRET_ID": "your_secret_id",
+        "COS_SECRET_KEY": "your_secret_key",
+        "COS_DEFAULT_BUCKET": "your_bucket",
+        "COS_DEFAULT_REGION": "ap-guangzhou"
+      }
+    }
+  }
+}
+```
+
+After modifying code, restart Cursor or disable/enable the MCP to reload.
+
+### Project Structure
+
+```
+mcp-cos-upload/
+├── src/
+│   ├── index.js    # MCP server entry, tool definitions
+│   └── cos.js      # COS client configuration
+├── .env.example    # Environment variables template
+├── package.json
+├── CHANGELOG.md
+└── README.md
+```
+
+### Publishing to npm
+
+```bash
+# 1. Update version in package.json
+npm version patch  # or minor/major
+
+# 2. Login to npm (first time only)
+npm login
+
+# 3. Publish
+npm publish
+
+# 4. Verify
+npm info mcp-cos-upload
+```
+
+After publishing, team members can use it immediately with `npx -y mcp-cos-upload`.
+
+---
+
+## Tool Reference
 
 ### cos_upload
 
@@ -57,37 +214,62 @@ Upload a file to Tencent Cloud COS.
 | `url` | string | ❌ | URL to download and upload |
 | `filepath` | string | ❌ | Local file path to upload |
 | `content` | string | ❌ | Text content to upload |
-| `bucket` | string | ❌ | COS bucket name (uses env default if not provided) |
-| `region` | string | ❌ | COS region (uses env default if not provided) |
+| `bucket` | string | ❌ | COS bucket name (uses env default) |
+| `region` | string | ❌ | COS region (uses env default) |
 | `key` | string | ❌ | Object key (auto-generated if not provided) |
-| `folder` | string | ❌ | Folder prefix (overrides `COS_KEY_PREFIX`) |
+| `folder` | string | ❌ | Folder prefix (default: `figma-assets`, use server config) |
 | `filename` | string | ❌ | Custom filename |
 | `ext` | string | ❌ | File extension (e.g., `png`, `jpg`, `svg`) |
 | `compress` | boolean | ❌ | Enable image compression (default: `true`) |
-| `quality` | number | ❌ | Compression quality 1-100 (default: `80`, for JPEG/WebP/PNG) |
+| `quality` | number | ❌ | Compression quality 1-100 (default: `80`) |
 
-> Note: `url`, `filepath`, and `content` are mutually exclusive - provide only one.
+> **Note:** `url`, `filepath`, and `content` are mutually exclusive - provide only one.
 
-**Example:**
+**Response:**
 
+```json
+{
+  "bucket": "your-bucket",
+  "region": "ap-guangzhou",
+  "key": "figma-assets/2025-12-22/image_a3b8k2.png",
+  "cdnUrl": "https://cdn.example.com/figma-assets/2025-12-22/image_a3b8k2.png"
+}
 ```
-Upload this image to COS: https://example.com/image.png
-```
+
+---
 
 ## Image Compression
 
 Supports automatic compression for uploaded images:
 
-| Format | Compression |
-|--------|-------------|
-| PNG | Lossless/lossy compression |
-| JPEG | Quality adjustment with mozjpeg |
-| WebP | Quality adjustment |
+| Format | Compression Method |
+|--------|-------------------|
+| PNG | Palette mode + color quantization (TinyPNG-like) |
+| JPEG | mozjpeg encoder with trellis quantization |
+| WebP | Smart subsampling |
 | GIF | Optimization |
-| SVG | SVGO optimization (removes redundant code) |
+| SVG | SVGO (removes redundant code) |
 
 Compression is enabled by default. Use `compress: false` to upload original files.
 
+---
+
+## Troubleshooting
+
+### MCP not working after code changes
+
+Restart Cursor or toggle the MCP off/on in settings to reload the server.
+
+### Permission denied
+
+Ensure your `COS_SECRET_ID` and `COS_SECRET_KEY` have write access to the bucket.
+
+### Upload failed with network error
+
+Check if your network can access Tencent Cloud COS endpoints.
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-cos-upload",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "MCP server for uploading files to Tencent Cloud COS",
   "type": "module",
   "main": "src/index.js",
@@ -21,6 +21,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "cos-nodejs-sdk-v5": "^2.15.4",
+    "dotenv": "^17.3.1",
     "sharp": "^0.34.5",
     "svgo": "^4.0.0",
     "zod": "^3.24.0"

package/src/cos.js

@@ -1,5 +1,8 @@
 // mcp-cos-upload - COS client configuration
 import COS from "cos-nodejs-sdk-v5";
+import dotenv from "dotenv";
+
+dotenv.config({ override: true });
 
 export function createCosClient() {
   const secretId = process.env.COS_SECRET_ID;