mcp-cos-upload 1.0.4 → 1.1.1

package/README.md

@@ -11,17 +11,38 @@ MCP server for uploading files to Tencent Cloud COS. Supports uploading from URL
 
 ---
 
+### 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 (see Quick Start below).
+
+---
+
 ## For Team Members (Users)
 
 ### Quick Start
 
 #### Method 1: Project `.env` File (Recommended)
 
-Create a `.env` file in your project root:
+1. Create a `.env` file in your project root:
 
 ```bash
-cp node_modules/mcp-cos-upload/.env.example .env
-# Or create manually:
+# Copy the template
+cp .env.example .env
+# Then fill in your values
 ```
 
 ```env
@@ -33,31 +54,39 @@ COS_KEY_PREFIX=figma-assets
 COS_CDN_DOMAIN=cdn.example.com
 ```
 
-Then add MCP configuration (Cursor Settings → MCP) without `env`:
+2. Add MCP configuration (Cursor Settings → MCP):
 
 ```json
 {
   "mcpServers": {
     "mcp-cos-upload": {
-      "command": "npx",
-      "args": ["-y", "mcp-cos-upload"]
+      "command": "sh",
+      "args": ["-c", "command -v mcp-cos-upload >/dev/null 2>&1 || npm i -g mcp-cos-upload >/dev/null 2>&1; exec 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.
+> **Why not `npx`?** npm's `npx -y` outputs package installation info to stdout, which conflicts with MCP's stdio protocol. The shell wrapper auto-installs silently and keeps stdout clean.
+
+> **Note:** The `.env` file contains secrets — never commit it. Use `.env.example` as a reference template.
+
+The server searches for `.env` in the following order:
+1. `$COS_ENV_PATH` (custom path via env var)
+2. Project root (`process.cwd()/.env`, set by Cursor to workspace root)
+3. `~/.mcp-cos-upload.env`
+4. `~/.config/mcp-cos-upload/.env`
 
 #### Method 2: MCP `env` Configuration
 
-Alternatively, pass credentials directly in MCP config:
+Alternatively, pass credentials directly in MCP config (no `.env` file needed):
 
 ```json
 {
   "mcpServers": {
     "mcp-cos-upload": {
-      "command": "npx",
-      "args": ["-y", "mcp-cos-upload"],
+      "command": "sh",
+      "args": ["-c", "command -v mcp-cos-upload >/dev/null 2>&1 || npm i -g mcp-cos-upload >/dev/null 2>&1; exec mcp-cos-upload"],
       "env": {
         "COS_SECRET_ID": "your_secret_id",
         "COS_SECRET_KEY": "your_secret_key",
@@ -181,26 +210,6 @@ mcp-cos-upload/
 └── 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
@@ -256,6 +265,14 @@ Compression is enabled by default. Use `compress: false` to upload original file
 
 ## Troubleshooting
 
+### `Unexpected token` / JSON parse error on startup
+
+This happens when using `npx -y mcp-cos-upload` directly — npm outputs package installation info to stdout, breaking MCP's stdio protocol. **Use the recommended shell wrapper config** in Quick Start instead.
+
+### Missing COS_SECRET_ID or COS_SECRET_KEY
+
+The server cannot find your credentials. Make sure you have a `.env` file in your project root (or `~/.mcp-cos-upload.env`). Check the `.env.example` template for required variables.
+
 ### MCP not working after code changes
 
 Restart Cursor or toggle the MCP off/on in settings to reload the server.

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "mcp-cos-upload",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "MCP server for uploading files to Tencent Cloud COS",
   "type": "module",
   "main": "src/index.js",
-  "bin": "./src/index.js",
+  "bin": {
+    "mcp-cos-upload": "src/index.js"
+  },
   "files": [
     "src/**/*"
   ],

package/src/cos.js

@@ -1,8 +1,33 @@
 // mcp-cos-upload - COS client configuration
 import COS from "cos-nodejs-sdk-v5";
 import dotenv from "dotenv";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
 
-dotenv.config({ override: true });
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const envPaths = [
+  process.env.COS_ENV_PATH,
+  join(process.cwd(), ".env"),
+  join(homedir(), ".mcp-cos-upload.env"),
+  join(homedir(), ".config", "mcp-cos-upload", ".env"),
+  join(__dirname, "..", ".env"),
+].filter(Boolean);
+
+let envLoaded = false;
+for (const envPath of envPaths) {
+  if (existsSync(envPath)) {
+    dotenv.config({ path: envPath, override: true });
+    envLoaded = true;
+    process.stderr.write(`[mcp-cos-upload] loaded env from ${envPath}\n`);
+    break;
+  }
+}
+if (!envLoaded) {
+  dotenv.config({ override: true });
+}
 
 export function createCosClient() {
   const secretId = process.env.COS_SECRET_ID;