mcp-fs-shell-windows 0.2.4 → 0.2.6

package/README.md

@@ -1,8 +1,10 @@
 # mcp-fs-shell-windows — filesystem + standalone Windows shell MCP server
 
-A Node.js MCP server exposing **filesystem operations** and a **standalone shell** as tools. Heavily extended fork of [fabienvauchelles/mcp-filesystem-extended](https://github.com/fabienvauchelles/mcp-filesystem-extended), which itself extends the official [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem).
+A Windows-first MCP server that gives AI clients **comprehensive filesystem access** (batched read/write/search/patch across your chosen drives and UNC shares) plus **reliable local shell execution** (synchronous, background, and interactive) — in a single Node.js process with no client-side permission toggles.
 
-Developed and tested primarily on **Windows**: drive-letter roots (`C:\`, `D:\`) and UNC network-share roots (`\\server\\share`) are first-class, and the shell tools run commands through `cmd.exe` byte-for-byte — including background job management and detached interactive console windows.
+Heavily extended fork of [fabienvauchelles/mcp-filesystem-extended](https://github.com/fabienvauchelles/mcp-filesystem-extended), which itself extends the official [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem). Developed and tested primarily on **Windows**: drive-letter roots (`C:\`, `D:\`) and UNC network-share roots (`\\server\\share`) are first-class, and the shell tools run commands through `cmd.exe` byte-for-byte.
+
+**npm:** [mcp-fs-shell-windows](https://www.npmjs.com/package/mcp-fs-shell-windows) · **Source:** [gerarddeluca/mcp-fs-shell-windows](https://github.com/gerarddeluca/mcp-fs-shell-windows)
 
 ## Provenance
 
@@ -25,34 +27,22 @@ Developed and tested primarily on **Windows**: drive-letter roots (`C:\`, `D:\`)
 - Windows for the shell tools (they spawn `cmd.exe`, `taskkill`, and `powershell`). The filesystem tools work on any platform Node runs on.
 - `shell_python` requires Python on the system PATH.
 
-## Build
+## Quick start (npm)
 
-```bat
-npm ci
-npm run build
-```
-
-Run the server:
+Published on npm — `npx` downloads the server (and all dependencies) and runs it:
 
 ```bat
-node dist\index.js <allowed-dir> [more-dirs...]
+npx -y mcp-fs-shell-windows C:\ D:\
 ```
 
-## Usage
-
-Example MCP client config (Claude Desktop / LM Studio `mcp.json` style):
+MCP client config (Claude Desktop / LM Studio `mcp.json` style):
 
 ```json
 {
   "mcpServers": {
     "filesystem": {
-      "command": "node",
-      "args": [
-        "C:/path/to/repo/dist/index.js",
-        "C:\\",
-        "D:\\",
-        "\\\\server\\share"
-      ]
+      "command": "npx",
+      "args": ["-y", "mcp-fs-shell-windows", "C:\\", "D:\\", "\\\\server\\share"]
     }
   }
 }
@@ -60,6 +50,20 @@ Example MCP client config (Claude Desktop / LM Studio `mcp.json` style):
 
 The filesystem tools can only touch the passed directories (and anything under them). A root that cannot be accessed at startup logs a warning and is skipped; the server keeps running. Note that the shell tools are **not** root-restricted — see [Security](#security).
 
+## Build from source
+
+For developers, or to run uncommitted changes:
+
+```bat
+git clone https://github.com/gerarddeluca/mcp-fs-shell-windows
+cd mcp-fs-shell-windows
+npm ci
+npm run build
+node dist\index.js <allowed-dir> [more-dirs...]
+```
+
+Then point your MCP config at `node <path-to-repo>\dist\index.js` with the allowed directories as the remaining args (same shape as the npx example above).
+
 ### Filesystem tools (23)
 
 | Tool | Purpose |
@@ -105,15 +109,15 @@ User commands are spawned as `cmd.exe /d /c <command>` with **verbatim argv**
 
 Practical notes:
 
-- Background jobs live in an **in-memory registry** inside the server process: the table is lost on server restart, but job log files persist (under `%TEMP%\mcp-filesystem-extended\shell-jobs`).
+- Background jobs live in an **in-memory registry** inside the server process: the table is lost on server restart, but job log files persist (under `%TEMP%\mcp-fs-shell-windows\shell-jobs`).
 - `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`.
 
 ## Docker
 
 ```bat
-docker build -t mcp/filesystem-extended .
-docker run -i --rm -v /path/to/dir:/data mcp/filesystem-extended /data
+docker build -t mcp-fs-shell-windows .
+docker run -i --rm -v /path/to/dir:/data mcp-fs-shell-windows /data
 ```
 
 The filesystem tools work in the image; the shell tools require a Windows host with `cmd.exe`.

package/dist/shell/handler.js

@@ -13,7 +13,7 @@ import { SHELL_MAX_TIMEOUT_SEC } from "./schema.js";
 // ---------------------------------------------------------------------------
 // Shared state & helpers
 // ---------------------------------------------------------------------------
-export const SHELL_JOBS_DIR = nodePath.join(os.tmpdir(), "mcp-filesystem-extended", "shell-jobs");
+export const SHELL_JOBS_DIR = nodePath.join(os.tmpdir(), "mcp-fs-shell-windows", "shell-jobs");
 const jobs = new Map();
 let defaultShellCwd = process.cwd();
 // Best-effort startup cleanup: drop job log files older than 24 h.

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "mcp-fs-shell-windows",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "MCP filesystem server: batched file tools + standalone Windows shell tools (extended fork)",
   "license": "MIT",
-  "author": "Gerard",
+  "author": "Gerard DeLuca",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gerarddeluca/mcp-fs-shell-windows.git"
+  },
+  "homepage": "https://github.com/gerarddeluca/mcp-fs-shell-windows#readme",
+  "bugs": {
+    "url": "https://github.com/gerarddeluca/mcp-fs-shell-windows/issues"
+  },
   "engines": {
     "node": ">=20"
   },