file-share-mcp 1.0.16 → 1.0.17

package/README.md

@@ -12,8 +12,8 @@ The agent can list, read, and notify about files. The user can upload, download,
   - `share_file` — Notify the user that a file is ready to download
   - `preview_file` — Read the content of a `.txt` or `.md` file (max 1 MB)
   - `write_file` — Write text content to a new file in the shared folder
-  - `copy_file` — Copy a file from the agent workspace into the shared folder
-  - `download_file` — Copy a file from the shared folder to the agent machine (any file type, binary included)
+  - `copy_file` — Copy a file from the agent machine into the shared folder (see [Moving files across machines](#moving-files-across-machines))
+  - `download_file` — Copy a file from the shared folder onto the agent machine (any file type, binary included — see [Downloading to the agent machine](#downloading-to-the-agent-machine))
   - `create_directory` / `delete_directory` — Manage subdirectories
   - `move_file` — Move or rename a file inside the shared folder
 - **Web GUI** — Upload, download, preview, and delete files from a browser
@@ -109,6 +109,53 @@ All configuration is done via environment variables, passed in the MCP `env` blo
 
 ---
 
+## Moving files across machines
+
+Two tools move a file between the agent and the shared folder, in opposite directions:
+
+| Tool | Direction | Names the file with |
+|---|---|---|
+| `copy_file` | agent machine → shared folder | `source_path` (absolute file path) |
+| `download_file` | shared folder → agent machine | `destination_path` (absolute directory) |
+
+Both are straightforward **over stdio**, the usual case where the MCP server is a child
+process of the agent: one filesystem, and the paths mean the same thing on both sides.
+Nothing to configure.
+
+**Through [`@imenam/mcp-http-gateway`](https://www.npmjs.com/package/@imenam/mcp-http-gateway)**
+the server runs on the gateway machine, and neither path means anything there. MCP has no
+file-transfer primitive — only the bytes a message carries actually travel — so the relay,
+which runs next to the agent in `--mcp` mode, fills the gap in both directions. Configure it
+with `GATEWAY_INLINE_ROOTS` (reading, for `copy_file`), `GATEWAY_INLINE_WRITE_ROOTS`
+(writing, for `download_file`) and `GATEWAY_INLINE_EXTENSIONS: "*"` — its default only covers
+spreadsheets, which a general file share has no reason to be limited to.
+
+Neither direction has a fallback. With the relay in the chain but the matching root
+unconfigured, the call fails and names the variable to set; nothing is read, written, or
+dumped into the conversation.
+
+### Uploading: `copy_file`
+
+`source_path` is the absolute path of the file on the agent machine. Through the relay, the
+hidden `source_content` / `source_name` parameters carry the file itself; the agent only ever
+names a path.
+
+### Downloading: `download_file`
+
+`destination_path` is the **absolute directory** where the file should land on the agent
+machine. The file keeps its own name; `destination_overwrite` (default `false`) governs
+replacing an existing file.
+**absolute directory** where it should land on the agent machine. The file keeps its own
+name; `destination_overwrite` (default `false`) governs replacing an existing file.
+
+Through the relay, the hidden `destination_relay` flag tells the server the destination is
+on another machine: it then returns the file's bytes in its response, and the relay writes
+them and strips them from the result. The bytes never reach the agent's context — an 8 MiB
+file base64-encoded into a conversation would be costly, and an agent re-typing it by hand
+would corrupt it.
+
+---
+
 ## Data & Logs
 
 By default, all user data is stored in `~/.file-share-mcp/`:

package/dist/mcp-server.js

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'url';
 import fs from 'fs';
 import { GuiLauncher, setupLogging, createLogger, reconnectGuiToolDefinition } from '@imenam/mcp-gui-interface';
 import { getConfig } from './utils/config-manager.js';
-import { getSharedFiles, validateSafePath, writeSharedFile, copyToSharedFolder, copyFromSharedFolder, createDirectory, deleteDirectory, moveFile, } from './utils/file-manager.js';
+import { getSharedFiles, validateSafePath, writeSharedFile, copyToSharedFolder, writeSharedFileFromBase64, copyFromSharedFolder, readForRelay, createDirectory, deleteDirectory, moveFile, } from './utils/file-manager.js';
 import { VERSION } from './version.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -121,7 +121,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         source_path: {
                             type: 'string',
-                            description: 'Absolute path to the source file in the agent workspace.',
+                            description: 'Absolute path to the source file on the agent machine.',
+                        },
+                        source_content: {
+                            type: 'string',
+                            description: 'Filled in by the mcp-http-gateway relay, never by the agent: the base64 content of the file read on the agent machine.',
+                        },
+                        source_name: {
+                            type: 'string',
+                            description: 'Filled in by the mcp-http-gateway relay, never by the agent: the original name of the file read on the agent machine.',
                         },
                         filename: {
                             type: 'string',
@@ -137,7 +145,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'download_file',
-                description: 'Download a file from the shared folder to the agent workspace (the reverse of copy_file). Works for any file type, including binary ones.',
+                description: 'Download a file from the shared folder onto the agent machine. Works for any file type, including binary ones. The file never passes through the conversation.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -147,12 +155,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         destination_path: {
                             type: 'string',
-                            description: 'ABSOLUTE destination path on the agent machine: either an existing directory (the file keeps its name) or the full target file path. Missing parent directories are created.',
+                            description: 'ABSOLUTE path of the destination DIRECTORY on the agent machine. It is created if missing, and the file keeps its own name.',
                         },
-                        overwrite: {
+                        destination_overwrite: {
                             type: 'boolean',
                             description: 'Replace the destination file if it already exists. Defaults to false.',
                         },
+                        destination_relay: {
+                            type: 'boolean',
+                            description: 'Filled in by the mcp-http-gateway relay, never by the agent. Signals that the destination lives on another machine and that the file content must travel in the response.',
+                        },
                     },
                     required: ['path', 'destination_path'],
                 },
@@ -280,23 +292,57 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'copy_file': {
-                const { source_path, filename, path: relativePath } = z.object({
-                    source_path: z.string(),
+                const { source_path, source_content, source_name, filename, path: relativePath } = z.object({
+                    source_path: z.string().optional(),
+                    source_content: z.string().optional(),
+                    source_name: z.string().optional(),
                     filename: z.string().optional(),
                     path: z.string().optional(),
                 }).parse(args);
+                // Le relais a lu le fichier sur la machine de l'agent : son chemin ne désigne
+                // rien ici, seuls les octets sont exploitables.
+                if (source_content !== undefined) {
+                    const target = filename ?? source_name;
+                    if (!target) {
+                        throw new Error('source_name or filename is required when the content is provided.');
+                    }
+                    const copiedName = writeSharedFileFromBase64(source_content, target, relativePath ?? '');
+                    return {
+                        content: [{ type: 'text', text: `File "${copiedName}" copied to shared folder.` }],
+                    };
+                }
+                // Pas de relais : le MCP tourne à côté de l'agent, son disque est le bon.
+                if (!source_path) {
+                    throw new Error('source_path is required.');
+                }
                 const copiedName = copyToSharedFolder(source_path, filename, relativePath ?? '');
                 return {
                     content: [{ type: 'text', text: `File "${copiedName}" copied to shared folder.` }],
                 };
             }
             case 'download_file': {
-                const { path: relativePath, destination_path, overwrite } = z.object({
+                const { path: relativePath, destination_path, destination_overwrite, destination_relay } = z.object({
                     path: z.string(),
-                    destination_path: z.string(),
-                    overwrite: z.boolean().optional(),
+                    destination_path: z.string().optional(),
+                    destination_overwrite: z.boolean().optional(),
+                    destination_relay: z.boolean().optional(),
                 }).parse(args);
-                const written = copyFromSharedFolder(relativePath, destination_path, overwrite ?? false);
+                // Le relais tourne sur la machine de l'agent et a retenu la destination : il
+                // attend les octets, qu'il écrira lui-même. Écrire ici viserait le mauvais disque.
+                if (destination_relay) {
+                    const { blob, mimeType, name } = readForRelay(relativePath);
+                    return {
+                        content: [{
+                                type: 'resource',
+                                resource: { uri: `file:///${name}`, name, mimeType, blob },
+                            }],
+                    };
+                }
+                // Pas de relais : le MCP tourne à côté de l'agent, son disque est le bon.
+                if (!destination_path) {
+                    throw new Error('destination_path is required.');
+                }
+                const written = copyFromSharedFolder(relativePath, destination_path, destination_overwrite ?? false);
                 return {
                     content: [{ type: 'text', text: `File "${relativePath}" downloaded to "${written}".` }],
                 };

package/dist/utils/file-manager.js

@@ -90,6 +90,28 @@ export function writeSharedFile(filename, content, relativePath = '') {
     fs.writeFileSync(dest, content, 'utf-8');
     return dest;
 }
+/**
+ * Write into the shared folder a file whose content travelled base64-encoded.
+ *
+ * Used when the gateway relay has read the file on the agent machine and inlined it:
+ * the server never sees the agent's disk, so the bytes are all it gets.
+ */
+export function writeSharedFileFromBase64(base64, filename, relativePath = '') {
+    // Le relais peut préfixer le contenu façon data-URI ; on l'accepte des deux formes.
+    const payload = base64.replace(/^data:[^;,]*;base64,/, '');
+    const data = Buffer.from(payload, 'base64');
+    if (data.length > RELAY_MAX_BYTES) {
+        throw new Error(`File too large to receive: ${data.length} bytes, the limit is ${RELAY_MAX_BYTES}.`);
+    }
+    const targetFilename = path.basename(filename);
+    if (!targetFilename || targetFilename === '.' || targetFilename === '..') {
+        throw new Error(`Invalid target filename: ${filename}`);
+    }
+    const dir = validateSafePath(relativePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, targetFilename), data);
+    return relativePath ? `${relativePath}/${targetFilename}` : targetFilename;
+}
 export function copyToSharedFolder(sourcePath, filename, relativePath = '') {
     const targetFilename = filename ? path.basename(filename) : path.basename(sourcePath);
     const stats = fs.statSync(sourcePath);
@@ -101,13 +123,61 @@ export function copyToSharedFolder(sourcePath, filename, relativePath = '') {
     fs.copyFileSync(sourcePath, path.join(dir, targetFilename));
     return relativePath ? `${relativePath}/${targetFilename}` : targetFilename;
 }
+/** Hard ceiling on what may be encoded into a tool response. The relay applies its own,
+ *  configurable limit; this one only exists so a huge file fails cleanly here instead of
+ *  exhausting memory while being base64-encoded. */
+const RELAY_MAX_BYTES = 32 * 1024 * 1024;
+const MIME_BY_EXTENSION = {
+    '.csv': 'text/csv',
+    '.htm': 'text/html',
+    '.html': 'text/html',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.json': 'application/json',
+    '.md': 'text/markdown',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.zip': 'application/zip',
+};
 /**
- * Copy a file out of the shared folder onto the agent machine.
+ * Read a shared file for delivery through the gateway relay.
  *
- * `destination` is either a directory (existing, or written with a trailing
- * separator) — the file then keeps its name — or the full target file path.
+ * The bytes travel base64-encoded inside the tool response, and the relay — which runs
+ * on the agent machine — writes them there and strips them from the result. They are
+ * never meant to reach the agent's context.
  */
-export function copyFromSharedFolder(relativePath, destination, overwrite = false) {
+export function readForRelay(relativePath) {
+    const sourcePath = validateSafePath(relativePath);
+    if (!fs.existsSync(sourcePath)) {
+        throw new Error(`File not found in shared folder: ${relativePath}`);
+    }
+    const stats = fs.statSync(sourcePath);
+    if (!stats.isFile()) {
+        throw new Error(`Path is not a file: ${relativePath}`);
+    }
+    if (stats.size > RELAY_MAX_BYTES) {
+        throw new Error(`File too large to transfer: ${relativePath} weighs ${stats.size} bytes, the limit is ${RELAY_MAX_BYTES}.`);
+    }
+    const name = path.basename(sourcePath);
+    return {
+        blob: fs.readFileSync(sourcePath).toString('base64'),
+        mimeType: MIME_BY_EXTENSION[path.extname(name).toLowerCase()] ?? 'application/octet-stream',
+        name,
+    };
+}
+/**
+ * Copy a file out of the shared folder into a directory on the agent machine.
+ *
+ * `destinationDir` is always a directory, created if missing, and the file keeps its
+ * name. Letting it mean either a directory or a file path would be ambiguous for a
+ * path that does not exist yet — and the relay, which writes the remote half of this
+ * same tool, has no way to guess either.
+ */
+export function copyFromSharedFolder(relativePath, destinationDir, overwrite = false) {
     const sourcePath = validateSafePath(relativePath);
     if (!fs.existsSync(sourcePath)) {
         throw new Error(`File not found in shared folder: ${relativePath}`);
@@ -115,19 +185,17 @@ export function copyFromSharedFolder(relativePath, destination, overwrite = fals
     if (!fs.statSync(sourcePath).isFile()) {
         throw new Error(`Path is not a file: ${relativePath}`);
     }
-    if (!path.isAbsolute(destination)) {
-        throw new Error(`Destination must be an absolute path: ${destination}`);
+    if (!path.isAbsolute(destinationDir)) {
+        throw new Error(`destination_path must be an absolute directory path: ${destinationDir}`);
+    }
+    if (fs.existsSync(destinationDir) && !fs.statSync(destinationDir).isDirectory()) {
+        throw new Error(`destination_path must be a directory, but a file already exists there: ${destinationDir}`);
     }
-    const looksLikeDir = destination.endsWith('/') ||
-        destination.endsWith(path.sep) ||
-        (fs.existsSync(destination) && fs.statSync(destination).isDirectory());
-    const destPath = looksLikeDir
-        ? path.join(destination, path.basename(sourcePath))
-        : destination;
+    const destPath = path.join(destinationDir, path.basename(sourcePath));
     if (!overwrite && fs.existsSync(destPath)) {
-        throw new Error(`Destination already exists: ${destPath}. Pass overwrite=true to replace it.`);
+        throw new Error(`Destination already exists: ${destPath}. Pass destination_overwrite=true to replace it.`);
     }
-    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.mkdirSync(destinationDir, { recursive: true });
     fs.copyFileSync(sourcePath, destPath);
     return destPath;
 }

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '1.0.16';
+export const VERSION = '1.0.17';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "file-share-mcp",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "MCP server for bidirectional file sharing between AI agents and users, with a built-in web GUI",
   "author": "",
   "license": "ISC",