mcp-fs-shell-windows 0.2.6 → 0.2.7

package/README.md

@@ -12,12 +12,13 @@ Heavily extended fork of [fabienvauchelles/mcp-filesystem-extended](https://gith
 |---|---|
 | Official base | `@modelcontextprotocol/server-filesystem` (Anthropic, PBC; MIT) |
 | Base fork | [fabienvauchelles/mcp-filesystem-extended](https://github.com/fabienvauchelles/mcp-filesystem-extended) @ `b6c317a` (MIT) |
-| This fork | v0.2.1 tool parity + `transfer_files` rename, robustness patches, 8 shell tools (v0.2.2), verbatim argv (v0.2.4) — see [Differences](#differences-from-the-base-fork) |
+| This fork | v0.2.1 tool parity + `transfer_files` rename, robustness patches, 8 shell tools (v0.2.2), verbatim argv (v0.2.4), `launch_file` launcher (v0.2.7) — see [Differences](#differences-from-the-base-fork) |
 
 ## Features
 
 - **23 filesystem tools** — batched read/write/append/delete, move/copy, line-number patching, search (name / glob / regex / fuzzy), tree, counts, checksums, diffs, exact-match text editing. Confined to the allowed directories passed on the command line.
 - **8 shell tools** — synchronous, background, and interactive command execution implemented *inside the MCP server process*: no client-side permission toggles, survives client restarts, works with any MCP client.
+- **1 launcher tool** (`launch_file`, Windows-only) — opens files, folders, and http(s) links in their OS default app, fully detached: returns the moment the opener is spawned (never waits for the app), no console window, no stdio inheritance; filesystem targets are confined to the allowed directories.
 - **Windows-first** — drive roots, UNC roots, `cmd.exe /d /c` with verbatim argv, whole-process-tree kills (`taskkill /T /F`), detached interactive console windows.
 - **NAS-safe startup** — an allowed directory that is missing or offline (e.g., a powered-down network share) logs a warning and the server continues instead of exiting.
 
@@ -113,6 +114,12 @@ Practical notes:
 - `timeout /t` can fail when stdin is not an interactive console — use `ping -n N 127.0.0.1 >nul` for sleeps.
 - Synchronous calls are bounded (max 28 s) so they cannot wedge the MCP request channel; anything longer should go through `shell_start`.
 
+### Launcher tool (1, Windows-only)
+
+| Tool | Purpose |
+|---|---|
+| `launch_file` | Launch a file, folder, or http(s) link via the Windows shell opener (`explorer.exe` — the OS default association: VLC for .mkv, Explorer for folders, default browser for web links). The target is passed as a single argv element (spaces, Unicode, `&`, apostrophes, parentheses all safe) and the call returns as soon as the opener process is actually spawned — it never waits for the opened app, creates no console window, and inherits no stdio pipes. Filesystem paths are subject to the allowed-root policy and checked for existence; only `http://`/`https://` links are launched, every other URL scheme (`file:`, `javascript:`, `ms-*`, `steam:`, …) is rejected, so no `file:` URI can bypass the filesystem policy. A failed opener spawn errors instead of reporting success. The response reports `dispatched: true` (the opener process was created) — not that the app handled the target. A host-settable `LAUNCH_FILE_OPENER` env var overrides the opener executable (test seam). |
+
 ## Docker
 
 ```bat
@@ -140,10 +147,13 @@ The filesystem tools work in the image; the shell tools require a Windows host w
 
 **v0.2.4 — verbatim argv:** `windowsVerbatimArguments` + `/d` on all user-command spawns (run/test/start and the terminal launcher).
 
+**v0.2.7 — `launch_file`:** the detached OS launcher (see above). Renamed from a local `open_file` prototype so it cannot collide with other servers' `open_file` tools. Hardened: spawn-failure returns an error (the handler awaits the child's `spawn`/`error` events — it never reports success for a process Windows refused to create), URLs are restricted to http(s) so `file:` URIs cannot bypass the allowed-root policy, and non-Windows platforms fail with a clear error.
+
 ## Security
 
 - The filesystem tools are confined to the allowed directories passed at startup (and their subtrees).
 - The shell tools are **not** confined: anything the server process's user can execute will run, including against reachable network shares. Grant this server the same trust you would grant an unsandboxed shell.
+- `launch_file` targets are confined to the allowed directories (for paths), but the opened application runs with the full rights of the server user — like anything you double-click.
 - The server communicates over stdio and opens no network endpoints of its own.
 
 ## License

package/dist/launch_file/handler.js

@@ -0,0 +1,152 @@
+import fs from "fs/promises";
+import path from "path";
+import { spawn } from "child_process";
+import { validatePath } from "../helpers/path.js";
+/**
+ * Launch a file, directory, or web link in its Windows-associated
+ * application (the OS default: e.g. VLC for .mkv/.mp4, Explorer for
+ * folders, the default browser for http(s) links).
+ *
+ * Windows-only. Mechanism: spawn the shell opener with the target as a
+ * single argv element and stdio ignored:
+ *   %SystemRoot%\explorer.exe <target>
+ *
+ *   - Default association: explorer.exe performs a ShellExecute "open" -
+ *     exactly what a double-click does. Nothing is hardcoded.
+ *   - No pipe inheritance: stdio is "ignore", so the launched process never
+ *     receives the MCP server's stdin/stdout/stderr. The handler resolves
+ *     the moment Windows has spawned the opener - it does NOT stay pending
+ *     until the opened application exits (the exact bug the cmd+start route
+ *     hit: a long-lived GUI child held the pipes open).
+ *   - No intermediary console: the opener is a GUI process and the spawn
+ *     uses windowsHide, so no blank cmd.exe / PowerShell window appears.
+ *   - Verbatim arguments: the target is one argv element, so spaces,
+ *     Unicode, apostrophes, ampersands, parentheses, and every other
+ *     filename character are passed through exactly (no cmd/PowerShell
+ *     quoting to get wrong).
+ *   - Security policy: filesystem targets are routed through validatePath
+ *     (same allowed-roots + symlink resolution as every other tool). Only
+ *     http:// and https:// links are dispatched to the OS directly; every
+ *     other URL scheme (file:, javascript:, ms-*, steam:, vlc:, ...) is
+ *     rejected so the tool cannot reach arbitrary Windows protocol
+ *     handlers or bypass the allowed-roots policy.
+ */
+// Standard-form web links - the ONLY URLs dispatched to the OS opener.
+const WEB_URL = /^https?:\/\//i;
+// A Windows drive path: single letter, ':', then a separator or end of
+// string, e.g. "M:\\...", "C:/...", or a bare "M:".
+const WINDOWS_DRIVE = /^[A-Za-z]:([\\/]|$)/;
+// A URI scheme: 2+ scheme chars then ':'. (A bare drive letter is exactly
+// one char, so "M:foo" is NOT mistaken for a scheme and still resolves as
+// a drive-relative path through validatePath.)
+const URI_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]+:/;
+/**
+ * Windows-only guard; returns the full path to the shell opener.
+ *
+ * The opener defaults to %SystemRoot%\explorer.exe. The host-settable
+ * LAUNCH_FILE_OPENER environment variable overrides it - a test seam that
+ * makes the spawn-failure path testable end-to-end without touching the
+ * real environment (note: faking SystemRoot itself is impossible; Node's
+ * Windows CSPRNG init aborts unless SystemRoot is the real Windows dir).
+ * Only the opener executable changes; the target still passes the full
+ * URL/path policy below.
+ */
+function openerPath() {
+    if (process.platform !== "win32") {
+        throw new Error("launch_file is supported only on Windows");
+    }
+    const override = process.env.LAUNCH_FILE_OPENER;
+    if (override) {
+        return override;
+    }
+    const sysRoot = process.env.SystemRoot || "C:\\Windows";
+    return path.join(sysRoot, "explorer.exe");
+}
+/**
+ * Spawn the opener fully detached and settle the promise only when
+ * Windows has actually created the process ("spawn" event). A failed
+ * process creation ("error" event, e.g. opener executable missing)
+ * REJECTS - it never falsely reports success. Never waits for the opener
+ * to exit.
+ *
+ * Both listeners are removed on settlement, so there is no double
+ * settlement and no listener leak. Exported so tests can exercise both
+ * settlement paths directly.
+ */
+export function launchDetached(opener, target) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(opener, [target], {
+                stdio: "ignore",
+                detached: true,
+                windowsHide: true,
+            });
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        const onSpawn = () => {
+            child.removeListener("error", onError);
+            child.unref();
+            resolve();
+        };
+        const onError = (err) => {
+            child.removeListener("spawn", onSpawn);
+            child.unref();
+            reject(err);
+        };
+        child.once("spawn", onSpawn);
+        child.once("error", onError);
+    });
+}
+export async function handleLaunchFile(target, allowedDirectories) {
+    const trimmed = (target ?? "").trim();
+    if (!trimmed) {
+        throw new Error("path must not be empty");
+    }
+    const opener = openerPath();
+    // --- Web link: only http/https; ask the OS to open it (default browser) ---
+    if (WEB_URL.test(trimmed)) {
+        try {
+            await launchDetached(opener, trimmed);
+        }
+        catch (err) {
+            throw new Error(`Failed to launch URL: ${errorMessage(err)}`);
+        }
+        return JSON.stringify({ target: trimmed, kind: "url", dispatched: true });
+    }
+    // --- Other URL schemes: reject. This keeps file: URLs (and any other
+    //     registered protocol handler) from bypassing the filesystem policy. ---
+    if (URI_SCHEME.test(trimmed) && !WINDOWS_DRIVE.test(trimmed)) {
+        throw new Error("Unsupported URL: only http:// and https:// links can be launched. " +
+            'Filesystem targets must be plain paths (e.g. "M:\\..." or "\\\\server\\share"), ' +
+            "not file: URLs or other protocol schemes.");
+    }
+    // --- Filesystem target: enforce the existing path/security policy ---
+    const resolved = await validatePath(trimmed, allowedDirectories);
+    // Useful error for a target that does not exist.
+    let stats;
+    try {
+        stats = await fs.stat(resolved);
+    }
+    catch {
+        throw new Error(`Cannot launch: path does not exist: ${resolved}`);
+    }
+    try {
+        await launchDetached(opener, resolved);
+    }
+    catch (err) {
+        throw new Error(`Failed to launch target: ${errorMessage(err)}`);
+    }
+    return JSON.stringify({
+        target: trimmed,
+        kind: stats.isDirectory() ? "directory" : "file",
+        resolved,
+        dispatched: true,
+    });
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/launch_file/schema.js

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export const LaunchFileArgsSchema = z.object({
+    path: z.string(),
+});

package/dist/server.js

@@ -25,6 +25,7 @@ import { GetFileInfoArgsSchema } from "./file_info/schema.js";
 import { EditFilesArgsSchema } from "./edit_files/schema.js";
 import { FuzzyFindFilesArgsSchema } from "./fuzzy_find_files/schema.js";
 import { DeleteFilesByPatternArgsSchema } from "./delete_files_by_pattern/schema.js";
+import { LaunchFileArgsSchema } from "./launch_file/schema.js";
 import { ShellRunArgsSchema } from "./shell/schema.js";
 import { ShellTestArgsSchema } from "./shell/schema.js";
 import { ShellStartArgsSchema } from "./shell/schema.js";
@@ -56,6 +57,7 @@ import { handleGetFileInfo } from "./file_info/handler.js";
 import { handleEditFiles } from "./edit_files/handler.js";
 import { handleFuzzyFindFiles } from "./fuzzy_find_files/handler.js";
 import { handleDeleteFilesByPattern } from "./delete_files_by_pattern/handler.js";
+import { handleLaunchFile } from "./launch_file/handler.js";
 import { handleShellRun } from "./shell/handler.js";
 import { handleShellTest } from "./shell/handler.js";
 import { handleShellStart } from "./shell/handler.js";
@@ -72,7 +74,7 @@ export class FilesystemServer {
         this.allowedDirectories = allowedDirectories;
         this.server = new Server({
             name: "secure-filesystem-server",
-            version: "0.2.4",
+            version: "0.2.7",
         }, {
             capabilities: {
                 tools: {},
@@ -354,6 +356,14 @@ export class FilesystemServer {
                             "The default starts as the MCP server process's CWD and resets when the server restarts.",
                         inputSchema: zodToJsonSchema(ShellCwdArgsSchema),
                     },
+                    {
+                        name: "launch_file",
+                        description: "Launch a file, folder, or web link in its Windows-associated application (the OS default: e.g. VLC for .mkv/.mp4, Explorer for folders, the default browser for http(s) URLs). " +
+                            "File/folder paths must be within the allowed directories (C:/, D:/, M:, NAS UNC) and are checked for existence; only http:// and https:// links are launched - file: URLs and other protocol schemes (javascript:, ms-*, steam:, vlc:) are rejected. " +
+                            "The launch is fully detached: it returns once Windows has spawned the shell opener - it never waits for the opened application, does not inherit the server's stdio pipes, creates no intermediary console window, and passes file names verbatim (spaces, Unicode, apostrophes, ampersands, parentheses all safe). " +
+                            "Errors if the path does not exist, is outside the allowed directories, the URL scheme is not http/https, or the opener fails to spawn.",
+                        inputSchema: zodToJsonSchema(LaunchFileArgsSchema),
+                    },
                 ],
             };
         });
@@ -676,6 +686,16 @@ export class FilesystemServer {
                             content: [{ type: "text", text: result }],
                         };
                     }
+                    case "launch_file": {
+                        const parsed = LaunchFileArgsSchema.safeParse(args);
+                        if (!parsed.success) {
+                            throw new Error(`Invalid arguments for launch_file: ${parsed.error}`);
+                        }
+                        const result = await handleLaunchFile(parsed.data.path, this.allowedDirectories);
+                        return {
+                            content: [{ type: "text", text: result }],
+                        };
+                    }
                     default:
                         throw new Error(`Unknown tool: ${name}`);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-fs-shell-windows",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "MCP filesystem server: batched file tools + standalone Windows shell tools (extended fork)",
   "license": "MIT",
   "author": "Gerard DeLuca",