@storage4everyone/mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,75 +1,9 @@
-# Storage4Everyone MCP server
+# @storage4everyone/mcp
 
-`@storage4everyone/mcp` lets AI agents (Claude Code, Claude Desktop, Cursor and other [Model Context Protocol](https://modelcontextprotocol.io) clients) list, download, upload and delete files in your Storage4Everyone buckets.
+A [Model Context Protocol](https://modelcontextprotocol.io) server for **Storage4Everyone (S4E)** cloud object storage.
 
-It runs on your own machine, started by the agent app, and calls the same API as the [JavaScript SDK](https://www.npmjs.com/package/@storage4everyone/sdk) with your API key. The key's scopes, bucket list, expiry, rate limits and quotas apply to everything the agent does.
+Lets AI agents such as Claude Code, Claude Desktop and Cursor list, download, upload and delete files in your S4E buckets, using your own API key.
 
-## 1. Create a key for the agent
+📘 Full documentation: [docs.storage4everyone.com](https://docs.storage4everyone.com)
 
-In **Dashboard → API Keys**, create a separate key for each agent:
-
-- **Scopes:** `storage:read` only, unless the agent must upload or delete.
-- **Buckets:** choose only the buckets the agent needs.
-- **Expiry:** set one (for example 30 days).
-
-Revoke the key in the dashboard to cut off the agent. Revocation takes effect within about a minute.
-
-## 2. Add it to your agent
-
-Claude Code:
-
-```sh
-claude mcp add s4e --env S4E_API_KEY=s4e_live_... --env S4E_BUCKET=bkt_... -- npx -y @storage4everyone/mcp
-```
-
-Claude Desktop, Cursor and other clients use a JSON config like this:
-
-```json
-{
-  "mcpServers": {
-    "s4e": {
-      "command": "npx",
-      "args": ["-y", "@storage4everyone/mcp"],
-      "env": {
-        "S4E_API_KEY": "s4e_live_...",
-        "S4E_BUCKET": "bkt_...",
-        "S4E_MCP_ROOT": "/path/to/agent-files"
-      }
-    }
-  }
-}
-```
-
-On Windows, some clients need `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@storage4everyone/mcp"]`.
-
-## 3. Settings
-
-| Variable | Required | Meaning |
-| --- | --- | --- |
-| `S4E_API_KEY` | Yes | The agent's API key. Read from the environment only; never passed as a tool argument. |
-| `S4E_BUCKET` | No | Default bucket (`bkt_…`, name, or `s4e://workspace/bucket`) when the agent does not name one. |
-| `S4E_MCP_ROOT` | No | The only local folder the server reads uploads from and writes downloads to. Defaults to the folder the agent app starts it in. Use a dedicated folder. |
-| `S4E_MCP_ALLOW_WRITE` | No | Set to `true` to enable `upload_file` and `delete_object`. Off by default. |
-
-## 4. Tools
-
-| Tool | What it does | Needs |
-| --- | --- | --- |
-| `list_buckets` | Lists buckets the key can access | `storage:read` |
-| `list_objects` | Lists files in a bucket (name, size, type, upload time); optional prefix; up to 500 per call | `storage:read` |
-| `download_file` | Saves a file into `S4E_MCP_ROOT` and returns the saved path. Will not overwrite unless `overwrite: true` | `storage:read` |
-| `upload_file` | Uploads a file from `S4E_MCP_ROOT` (up to 5 GiB; large files are sent in parts) | `storage:write` + `S4E_MCP_ALLOW_WRITE=true` |
-| `delete_object` | Deletes a file (paid plans move it to the Trash Bin) | `storage:write` + `S4E_MCP_ALLOW_WRITE=true` |
-
-The service may assign stored file names on upload; use the returned `fileName` afterwards.
-
-Not included: share links, usage figures, creating buckets, client apps and browser sessions. These need the dashboard.
-
-## 5. Security
-
-- **The server decides what is allowed.** The MCP package adds no permissions. A read-only key cannot upload, even with `S4E_MCP_ALLOW_WRITE=true`.
-- **Local folder sandbox.** Paths outside `S4E_MCP_ROOT` are refused, including `..`, other absolute paths, and symlinks or junctions that point outside it. This stops a misled agent from uploading files such as SSH keys or writing outside the folder.
-- **No secrets in the agent's context.** Tool results never contain the API key or signed download URLs, and error messages are scrubbed of both. Downloads go to disk; file contents are not returned to the model.
-- **File names are data.** Treat names in listings as untrusted text. Agents should not follow instructions found in file names or downloaded files.
-- **Rate limits and quotas** are the same as for any API client. When a limit is hit, the agent gets the error code and the retry time; the server does not retry automatically.
-- **Your agent provider sees tool results.** File names, sizes and bucket names returned to the agent are sent to whichever AI service runs it, under that service's terms.
+License: Apache-2.0

package/dist/env.d.ts

@@ -0,0 +1,8 @@
+export declare const ENV_FILES: string[];
+/** Minimal dotenv parser: KEY=value, optional `export`, quotes, and trailing # comments. */
+export declare function parseEnv(text: string): Record<string, string>;
+/**
+ * Fills S4E_API_KEY and S4E_BUCKET from the project's .env files when the MCP config does
+ * not set them. Values already in `env` always win. Returns the files that supplied a value.
+ */
+export declare function loadEnvFiles(dir: string, env?: NodeJS.ProcessEnv): Promise<string[]>;

package/dist/env.js

@@ -0,0 +1,51 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+// Same order as Next.js and Vite in development: the first file that sets a value wins.
+export const ENV_FILES = ['.env.development.local', '.env.local', '.env.development', '.env'];
+// S4E_API_BASE and S4E_MCP_* are never read from files: a cloned project must not be able
+// to send your key to another server or turn on write tools.
+const FILE_KEYS = ['S4E_API_KEY', 'S4E_BUCKET'];
+/** Minimal dotenv parser: KEY=value, optional `export`, quotes, and trailing # comments. */
+export function parseEnv(text) {
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        let value = match[2].trim();
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.lastIndexOf(quote) > 0)
+            value = value.slice(1, value.lastIndexOf(quote));
+        else
+            value = value.replace(/\s+#.*$/, '');
+        out[match[1]] = value;
+    }
+    return out;
+}
+/**
+ * Fills S4E_API_KEY and S4E_BUCKET from the project's .env files when the MCP config does
+ * not set them. Values already in `env` always win. Returns the files that supplied a value.
+ */
+export async function loadEnvFiles(dir, env = process.env) {
+    const used = [];
+    for (const file of ENV_FILES) {
+        let text;
+        try {
+            text = await readFile(path.join(dir, file), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const values = parseEnv(text);
+        let supplied = false;
+        for (const key of FILE_KEYS) {
+            if (!env[key] && values[key]) {
+                env[key] = values[key];
+                supplied = true;
+            }
+        }
+        if (supplied)
+            used.push(file);
+    }
+    return used;
+}

package/dist/index.js

@@ -3,14 +3,27 @@ import { realpath } from 'node:fs/promises';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { Storage4Everyone } from '@storage4everyone/sdk';
 import { createServer } from './server.js';
+import { loadEnvFiles } from './env.js';
 // stdout carries the MCP protocol; all diagnostics go to stderr.
+const rootSetting = process.env.S4E_MCP_ROOT || process.cwd();
+let root;
+try {
+    root = await realpath(rootSetting);
+}
+catch {
+    console.error(`S4E_MCP_ROOT folder not found: ${rootSetting}. Create it or set S4E_MCP_ROOT to an existing folder.`);
+    process.exit(1);
+}
+// The agent app starts the server in the project folder, so its .env files can supply the key.
+const project = process.cwd();
+const envFiles = await loadEnvFiles(project);
 if (!process.env.S4E_API_KEY) {
-    console.error('S4E_API_KEY is not set. Create an API key in the Storage4Everyone dashboard and pass it in the MCP server env.');
+    console.error(`S4E_API_KEY is not set. Add S4E_API_KEY=s4e_live_... to .env.local in ${project}, or pass it in the MCP server env. ` +
+        'Create a key in the Storage4Everyone dashboard under API Keys.');
     process.exit(1);
 }
 // No automatic retries: rate-limit errors go back to the agent with their retry time.
 const client = new Storage4Everyone({ maxRetries: 0 });
-const root = await realpath(process.env.S4E_MCP_ROOT || process.cwd());
 const allowWrite = process.env.S4E_MCP_ALLOW_WRITE === 'true';
 await createServer({ client, root, allowWrite }).connect(new StdioServerTransport());
-console.error(`Storage4Everyone MCP server ready (folder: ${root}, write tools: ${allowWrite ? 'on' : 'off'}).`);
+console.error(`Storage4Everyone MCP server ready (folder: ${root}, settings from: ${envFiles.length ? envFiles.join(', ') : 'MCP env'}, write tools: ${allowWrite ? 'on' : 'off'}).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storage4everyone/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Model Context Protocol server that lets AI agents use Storage4Everyone buckets with your API key",
   "type": "module",
   "main": "./dist/server.js",